> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/postmessage-protocol.md).

# The postMessage protocol

The widget is a thin adapter over a `postMessage` conversation between your page and the editor's iframe. You do not need this page to use the widget - it translates the whole protocol into DOM events for you. It is here for a host that integrates without the widget, and for anyone debugging one that does.

{% hint style="info" %}
**Message names are wire format.** An existing message string is never changed; new messages are only added. So an older widget keeps working against a newer deployment, and the reverse. `PROTOCOL_VERSION` is currently `5`.
{% endhint %}

Every message is `{ type, data? }`. Import the names from `@scaleflex/template-builder` rather than typing the strings.

### What the editor sends

| Message                                    | `data`                                            | Sent when                                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `design-templates:builder:ready`           | -                                                 | The editor mounted and validated its credential                                                                                             |
| `design-templates:builder:open`            | -                                                 | The editor UI opened                                                                                                                        |
| `design-templates:builder:close`           | `{ reason }`                                      | The author left the editor                                                                                                                  |
| `design-templates:builder:save`            | `{ uuid, name? }`                                 | A DAM-backed save landed                                                                                                                    |
| `design-templates:builder:content`         | `{ templateId?, content, name?, templateQuery? }` | A stateless save - the edited template coming back                                                                                          |
| `design-templates:builder:content-request` | -                                                 | The editor is mounted in stateless mode and waiting for a template                                                                          |
| `design-templates:builder:dirty`           | `{ isDirty }`                                     | The unsaved-changes flag flipped                                                                                                            |
| `design-templates:builder:error`           | `{ code, message? }`                              | Something failed. Codes are in the [API reference](https://docs.scaleflex.com/developers-headless/studio/template-builder/api-reference.md) |

`close` carries a `reason` (added in protocol `4`). Read an absent one as `dismiss`: it keeps you behaving as you did before the reason existed, though it is not a faithful report - a pre-`4` deployment sends the same bare close when it navigates itself, so a whole-app host keeps discarding those navigations until the deployment is on `4` too.

* `dismiss` - the author pressed back or close. The editor deliberately stays where it is and leaves the decision to you: drop your modal, or, if you frame the whole app, send the frame back to its entry route.
* `navigation` - the app moved to one of its own non-editor screens, such as the variations list after a variation was saved. It is still running and already showing what the author asked for. **Do not reload the frame on this one** - that discards the navigation and drops the author back on your entry route.

The two save messages are deliberately separate. A DAM-backed save reports a uuid, because the deployment stored the file; a stateless save carries the whole document, because you are about to. The widget presents both as one `save` event, and which shape arrives in `detail` tells you which mode you are in.

### What a host sends

| Message                        | `data`                                               | Send it                                                            |
| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `design-templates:host:load`   | `{ content, templateId?, name?, templateQuery? }`    | In answer to `content-request`, and whenever you swap the template |
| `design-templates:host:config` | `{ customMetadata?, customMetadataLabel?, labels? }` | After `ready`, and whenever the configuration changes              |
| `design-templates:host:saved`  | `{ ok, message? }`                                   | After a stateless save, to report whether you stored it            |

`host:load` is stateless only. The template travels by message rather than in the URL because template XML routinely exceeds practical URL length limits.

`host:config` is separate from `host:load` because it is not per-template, and because it must also reach DAM-backed embeds - which never receive a `host:load` at all, since the deployment loads those templates itself. It is purely additive: a deployment that predates it ignores it. `labels` (protocol v5) is described in [Editor labels](https://docs.scaleflex.com/developers-headless/studio/template-builder/editor-labels.md); a deployment older than v5 ignores that field alone. Each message replaces the whole configuration, so leaving `labels` out of a later one restores the default wording.

`host:saved` is optional. The editor clears its unsaved-changes flag optimistically when it posts a save, so a host that never acks behaves exactly as it did before the message existed. Only `ok: false` buys anything.

### Origin checks

Both directions are pinned, and neither is advisory:

* The widget only accepts messages from the `base-url` origin.
* The deployment only accepts `host:load` and `host:config` from the origin pinned as `embedOrigin` when the credential was handed over. An unrelated framing page cannot inject a template into someone else's session.

[Embedding and origins](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md) covers how that pinning is established, and the rule that `embedOrigin` can only be repinned together with fresh credentials.

### Ordering you can rely on

* `ready` precedes everything else. Configuration sent earlier is not lost, but it is not applied until the editor exists.
* In stateless mode, `content-request` means the editor is up and idle. Answer it with `host:load`, or mount the element before your fetch resolves and answer when it does.
* Saves are serialized. Save messages arrive in the order the editor posted them.
* Under [`dam-store`](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md) a save whose upload is still in flight arrives **after** `close`. That is the one case where a message follows the close.

### The blank document

`BLANK_TEMPLATE_XML`, exported from `@scaleflex/template-builder`, is an empty template: no layouts, no layers, no variables. It is what the widget sends as `host:load` content when you set `new-template`, so starting from scratch costs you no knowledge of the template format.

It is sent as ordinary `host:load` content rather than as a new message, so it works against deployments that predate the feature - the document is the whole signal, and any deployment that can parse a template can parse this one.

The editor opens on its empty state, and save is refused until a layout exists. So the first save you receive is a fully-formed document serialized by the deployment, not this skeleton.

### Where to go next

* [API reference](https://docs.scaleflex.com/developers-headless/studio/template-builder/api-reference.md) - the widget's own event and error surface
* [Storage modes](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) - what the two save messages mean in practice
