Embed Host Integration

This page is for the main-site host that embeds a generator page through iframe and needs to coordinate with @atomm-developer/generator-workbench in ?mode=embed.

If you are changing the generator shell itself, read Generator Workbench first. If you are changing the parent page that owns the iframe, read this page.

What Changes In mode=embed

When the embedded generator URL contains ?mode=embed, generator-workbench changes in two important ways:

1. It hides shell-owned platform UI inside the iframe, including .app-topbar and #sidebar-footer.
2. It starts an iframe bridge and exchanges postMessage events with the host page.

The runtime, export, template, and bridge capabilities still exist. Only the shell chrome is reduced.

Host Checklist

The host page should update all of the following:

1. Append mode=embed to the iframe URL.
2. Register the host-side message listener before relying on any bridge command.
3. Wait for generator_pageLoaded before flushing template or state payloads.
4. Prefer generator_loadTemplateData for template bootstrap.
5. Keep generator_setGeneratorData for runtime snapshot restore.
6. Handle success and error events from the iframe.

Do Not Use iframe.onload As Bridge Ready

iframe.onload only means the browser finished loading the page resource. It does not guarantee that generator-workbench has already mounted the runtime and attached the bridge listener.

For bridge commands, the only ready signal is:

• generator_pageLoaded

The iframe sends this event only after the bridge listener has been attached.

Recommended Handshake

Use this order:

1. Create the iframe URL with mode=embed.
2. Register the parent-page message listener.
3. Cache outgoing bridge payloads locally.
4. Wait for generator_pageLoaded.
5. Flush the cached payloads.
6. Wait for response events such as generator_toTemplateLoaded.

Minimal Host Example

const iframe = document.querySelector('#generator-frame')
const iframeOrigin = new URL(iframe.src, window.location.href).origin

const pendingMessages = []
let bridgeReady = false

function postToWorkbench(type, data) {
  const payload = { type, data }

  if (!bridgeReady) {
    pendingMessages.push(payload)
    return
  }

  iframe.contentWindow?.postMessage(payload, iframeOrigin)
}

function flushPendingMessages() {
  while (pendingMessages.length > 0) {
    const payload = pendingMessages.shift()
    iframe.contentWindow?.postMessage(payload, iframeOrigin)
  }
}

window.addEventListener('message', (event) => {
  if (event.origin !== iframeOrigin) {
    return
  }

  const message = event.data || {}

  switch (message.type) {
    case 'generator_pageLoaded':
      bridgeReady = true
      flushPendingMessages()
      return

    case 'generator_toTemplateLoaded':
      console.log('template applied', message.data)
      return

    case 'generator_toSelectTemplate':
      console.log('runtime selected template', message.data)
      return

    case 'generator_toTemplateError':
      console.error('bridge template error', message.data)
      return

    case 'generator_toFile':
      console.log('file payload', message.data)
      return
  }
})

postToWorkbench('generator_loadTemplateData', {
  title: 'Pendant 140x128',
  template: {
    type: 'generator-template',
    version: '1.0.0',
    generatorId: 'pendant-generator',
    defaults: {
      meta: {
        generatorId: 'pendant-generator',
        schemaVersion: '1.0.0',
      },
      params: {
        height: 150,
        width: 128,
      },
      version: '1.0.0',
    },
  },
})

Which Command To Use

Prefer generator_loadTemplateData

Use generator_loadTemplateData when the host wants to apply template data into the current generator runtime.

Why this is the preferred bootstrap path:

• it maps directly to sdk.template.applyToRuntime(...)
• it returns generator_toTemplateLoaded
• it is easier to retry safely
• it matches the workbench template import behavior

Use generator_setGeneratorData Carefully

Use generator_setGeneratorData when the host wants to restore runtime snapshot-like data through runtime.setState(...).

Important behavior:

• it does not emit a dedicated success ack event
• if it fails, the iframe reports generator_toTemplateError with action: 'setGeneratorData'
• because there is no success ack, it is less suitable as the primary template bootstrap command

Event Table

Direction	Event	Host action
iframe -> host	generator_pageLoaded	Mark bridge ready and flush queued payloads
host -> iframe	generator_loadTemplateData	Apply template data into workbench
iframe -> host	generator_toTemplateLoaded	Treat template bootstrap as completed
host -> iframe	generator_setGeneratorData	Restore runtime snapshot data
iframe -> host	generator_toTemplateError	Handle template or state bridge failure
iframe -> host	generator_toSelectTemplate	Receive runtime-reported template selection
host -> iframe	generator_getTemplateData	Pull current template from the iframe
iframe -> host	generator_toTemplateData	Read pulled template payload
host -> iframe	generator_getFile	Ask the iframe for export data
iframe -> host	generator_toFile	Consume returned file payload
iframe -> host	generator_toFileError	Handle export bridge failure

New Runtime-Side Contract

If the runtime inside the iframe needs to tell the main site that the user clicked a template card, it can now emit:

emit({
  type: 'select_template',
  data: {
    name: 'Spring Sale',
    category: 'marketing',
  },
})

When the route is ?mode=embed, generator-workbench automatically forwards it to the parent page bridge as:

• generator_toSelectTemplate

Error Handling Recommendations

• Log all generator_toTemplateError and generator_toFileError events in the host.
• Add a timeout around generator_loadTemplateData and treat missing generator_toTemplateLoaded as a failed bootstrap attempt.
• If the host sends commands before generator_pageLoaded, keep them in memory and retry only after ready arrives.
• Use ?bridgeDebug=1 temporarily on the iframe URL during integration debugging.

Suggested Host Migration

If your current host logic sends data immediately after creating the iframe, migrate it in this order:

1. Move the parent-page message listener registration earlier.
2. Add a local pending queue for outbound bridge payloads.
3. Gate payload flushing on generator_pageLoaded.
4. Convert template bootstrap from generator_setGeneratorData to generator_loadTemplateData where possible.
5. Keep generator_setGeneratorData only for real runtime snapshot restore cases.

Related Pages

• Generator Workbench
• Workbench Runtime Communication
• Generator Workbench Upgrade
• Runtime Contract