Tecof paneli tema editörünü bir iframe içinde açar ve onunla postMessage üzerinden konuşur. Aynı protokolü kendi panelinizde ya da aracınızda kullanabilirsiniz. Mesaj tipleri geriye dönük uyumluluk için puck: önekini korur; bu, motorun Puck olduğu anlamına gelmez.

sequenceDiagram
    participant Host as Panel (üst pencere)
    participant Studio as Tecof Studio (iframe)
    Host->>Studio: puck:save
    Studio-->>Host: puck:saved { data }
    Host->>Studio: puck:viewport { width: "375px" }
    Studio-->>Host: puck:itemSelected { item: { type, id } }
    Host->>Studio: puck:refetch { highlightType }

Diyagram

Üst pencere → editör#

Mesaj	Ek alanlar	Etki
`puck:save`	—	Taslağı kaydeder
`puck:publish`	—	Yalnız taslak kaydını tetikler; yayınlama panel/backend işidir
`puck:undo` / `puck:redo`	—	Geri al / yinele
`puck:refetch`	`highlightType?`	Taslağı sunucudan yeniden yükler (ör. bir AI ajanı taslağı sunucuda değiştirdiyse); verilirse o tipteki bileşen kanvasta vurgulanır
`puck:highlight`	`componentType`	Verilen tipteki bileşeni kanvasta vurgular
`puck:viewport`	`width`	`"375px"` / `375` → mobil, `"768px"` / `768` → tablet, diğer her değer → masaüstü

TypeScript

const iframe = document.querySelector<HTMLIFrameElement>("#studio")!;
const EDITOR_ORIGIN = "https://tema.ornek.com";

iframe.contentWindow?.postMessage({ type: "puck:save" }, EDITOR_ORIGIN);
iframe.contentWindow?.postMessage({ type: "puck:viewport", width: "375px" }, EDITOR_ORIGIN);

Editör → üst pencere#

Mesaj	Ek alanlar	Ne zaman
`puck:changed`	—	Doküman değişti (~300 ms debounce)
`puck:saved`	`data` (güncel taslak)	Kayıt başarılı
`puck:saveError`	`message`	Kayıt başarısız (revizyon önizlemesinde kaydetme denemesi dahil)
`puck:itemSelected`	`item: { type, id }`	Bir düğüm seçildi (Esc ile üst düğüme çıkıldığında da)
`puck:itemDeselected`	—	Seçim kaldırıldı

TypeScript

window.addEventListener("message", (event) => {
  if (event.origin !== EDITOR_ORIGIN) return;
  switch (event.data?.type) {
    case "puck:changed":
      markDirty();
      break;
    case "puck:saved":
      markSaved(event.data.data);
      break;
    case "puck:saveError":
      showError(event.data.message);
      break;
    case "puck:itemSelected":
      showContextFor(event.data.item.type, event.data.item.id);
      break;
  }
});

Editör yalnız bir iframe içinde çalışırken mesaj gönderir; doğrudan açıldığında köprü sessizdir.

Origin güvenliği#

Gömülü kullanımda hostOrigin prop’unu mutlaka verin. Editör gelen mesajların event.origin değerini bununla karşılaştırır ve giden mesajları yalnız bu origin’e yollar. Prop verilmezse geriye uyumluluk için '*' kullanılır: her origin mesaj gönderebilir ve taslak verisi (puck:saved) her üst pencereye gider.

TSX

<TecofEditor pageId={pageId} config={editorConfig} accessToken={token} hostOrigin="https://app.tecof.com" />

Kontrol listesi:

hostOrigin ile üst pencerenin origin’i birebir aynı olmalı (şema ve port dahil).
Mesajı iframe.contentWindow’a, hedef origin’i açıkça vererek gönderin.
Gelen mesajda event.origin’i ve puck: tipini doğrulayın.
Panel editöre JWT’yi adres parametresiyle verir (?token=); editör rotasını herkese açık bir sayfadan bağlamayın.