@scaleflex/template-builder 0.1.1 → 0.4.0

package/src/template-builder.ts

@@ -1,6 +1,7 @@
 import { LitElement, html, css, nothing, type PropertyValues } from 'lit'
 import { property, state } from 'lit/decorators.js'
 import {
+  BLANK_TEMPLATE_XML,
   BUILDER_CLOSE,
   BUILDER_CONTENT,
   BUILDER_CONTENT_REQUEST,
@@ -11,9 +12,11 @@ import {
   BUILDER_SAVE,
   EMBED_PARAMS,
   EMBED_ROUTE,
+  HOST_CONFIG,
   HOST_LOAD,
   HOST_SAVED,
   builderRoute,
+  type CustomMetadataField,
   type BuilderContentData,
   type BuilderContentMessage,
   type BuilderDirtyData,
@@ -24,6 +27,13 @@ import {
   type BuilderSaveMessage,
   type BuilderTheme,
 } from './protocol'
+import {
+  storeTemplateInDam,
+  type DamStoreAuth,
+  type StoredTemplate,
+} from './dam-store'
+
+export type { StoredTemplate, DamStoreAuth } from './dam-store'
 
 export type TemplateBuilderStatus = 'idle' | 'loading' | 'ready' | 'error'
 
@@ -33,11 +43,14 @@ export type TemplateBuilderStatus = 'idle' | 'loading' | 'ready' | 'error'
  * - DAM-backed (default) — `BuilderSaveData`; the app uploaded the template and
  *   reports the resulting `uuid`.
  * - `stateless` — `BuilderContentData`; nothing was stored, and `content` is
- *   the edited template for the host to persist.
+ *   the edited template for the host to persist. With `dam-store` the element
+ *   uploads a rendering copy to Filerobot first, and the detail additionally
+ *   carries `stored` (the copy's uuid + CDN URL) — or `storeError` when that
+ *   copy could not be made; the raw `content` arrives either way.
  */
 export type TemplateBuilderSaveDetail =
   | BuilderSaveData
-  | BuilderContentData
+  | (BuilderContentData & { stored?: StoredTemplate; storeError?: string })
   | undefined
 
 export interface TemplateBuilderEventMap {
@@ -74,7 +87,9 @@ export interface TemplateBuilderEventMap {
  *   template into the editor over postMessage and `save` returns the edited
  *   document; nothing is stored on the Scaleflex side, and `template-id` is
  *   just an opaque string echoed back. Rendering, fonts and asset browsing
- *   still use the session's Filerobot tenant.
+ *   still use the session's Filerobot tenant. To start a template from
+ *   scratch, set `new-template` (or call `createNew()`) instead of `content`
+ *   — the widget supplies the blank document.
  *
  * `brand-color` and `theme` restyle the editor chrome to match the host page.
  * They do not touch the rendered template — its colours live in the document.
@@ -149,7 +164,8 @@ export class SfxTemplateBuilder extends LitElement {
   @property({ reflect: true }) mode: 'inline' | 'modal' = 'inline'
   /**
    * Hand the template in and take it back out instead of letting the app read
-   * and write Filerobot. Requires `content`.
+   * and write Filerobot. Requires `content`, or `new-template` to start from
+   * scratch.
    */
   @property({ type: Boolean, reflect: true }) stateless = false
   /**
@@ -158,6 +174,21 @@ export class SfxTemplateBuilder extends LitElement {
    * Assigning a different value while open loads it into the running editor.
    */
   @property({ attribute: false }) content = ''
+  /**
+   * Stateless mode: open on a new, empty template rather than one of yours.
+   * The widget supplies the blank document ({@link BLANK_TEMPLATE_XML}), so
+   * nothing here needs to know the template format — the user picks the canvas
+   * size in the editor, and `save` hands back a complete document to store.
+   *
+   * `content` wins when both are set: a host with a real template to edit is
+   * not asking for a blank one.
+   *
+   * A flag rather than an inferred meaning for empty `content`, because empty
+   * already means "the host is still fetching" — the editor waits on a spinner
+   * for it, and blanking that case would flash an empty document in front of
+   * every host that mounts the builder before its request resolves.
+   */
+  @property({ type: Boolean, attribute: 'new-template' }) newTemplate = false
   /** Stateless mode: display name for the editor header. */
   @property({ attribute: 'template-name' }) templateName = ''
   /**
@@ -176,6 +207,81 @@ export class SfxTemplateBuilder extends LitElement {
   @property({ attribute: 'brand-color' }) brandColor = ''
   /** Colour scheme for the editor chrome. Empty leaves the app's own default. */
   @property() theme: BuilderTheme | '' = ''
+  /**
+   * Metadata model to offer in the editor as the **Custom metadata** value
+   * source: `[{ key, title?, group? }]`. Authors then bind a text variable to
+   * one of your field names instead of to a bare slug.
+   *
+   * Names only — no values travel with the model, and the app resolves nothing
+   * against it. The bound key is stored in the template as `custom_ckey`, and
+   * the variable renders like any free-text one: your pipeline puts
+   * `$slug=value` in the render query. Read the key back from the saved `.fdt`
+   * to know which of your fields each variable expects.
+   *
+   * Leave it empty and the source is not offered at all, so hosts that send
+   * nothing see the editor they always had. Its main use is `sec-template` /
+   * stateless embeds, where the Hub project model — and with it the "File
+   * metadata" source — is unavailable.
+   *
+   * Settable as a property (an array) or as a `custom-metadata` attribute
+   * holding that array as JSON. Neither is trusted to be well-formed:
+   * unparseable JSON is warned about, a value that is not an array is treated as
+   * no model, and individual fields the editor cannot use are dropped there —
+   * a config typo costs the field, not the editor.
+   *
+   * Lit compares by identity: assign a new array to change the model, don't
+   * mutate the one you passed.
+   */
+  @property({
+    attribute: 'custom-metadata',
+    converter: {
+      fromAttribute: (value: string | null): CustomMetadataField[] => {
+        if (!value) return []
+        try {
+          const parsed: unknown = JSON.parse(value)
+          return Array.isArray(parsed) ? (parsed as CustomMetadataField[]) : []
+        } catch {
+          console.warn('[sfx-template-builder] custom-metadata is not valid JSON — ignoring.')
+          return []
+        }
+      },
+      toAttribute: (value: CustomMetadataField[]): string => JSON.stringify(value ?? []),
+    },
+  })
+  customMetadata: CustomMetadataField[] = []
+  /**
+   * Display name for the custom-metadata value source in the editor's UI.
+   * Empty means the editor's default ("Custom metadata"); a host can rename
+   * it after its own domain — e.g. "External metadata". Pure wording: the
+   * stored template is unaffected.
+   */
+  @property({ attribute: 'custom-metadata-label' }) customMetadataLabel = ''
+  /**
+   * Stateless only: store each save in Filerobot too, so the CDN can render
+   * it. The `save` event then carries `stored: { uuid, url }` next to the raw
+   * `content` — or `storeError` when the copy failed (the raw data arrives
+   * either way; whether that fails the save is the host's call via the ack).
+   * Uses the element's own credentials; a security template needs a scope
+   * that allows uploads.
+   */
+  @property({ type: Boolean, attribute: 'dam-store' }) damStore = false
+  /**
+   * Folder new templates are stored into when `dam-store` is on and the
+   * template id names no existing DAM file (an existing file's own folder
+   * always wins, so same name + folder versions it in place).
+   */
+  @property({ attribute: 'store-folder' }) storeFolder = '/'
+  /**
+   * `dam-store`: the uuid of the rendering copy this document already has —
+   * the `stored.uuid` a previous session's save reported, passed back in by
+   * the host alongside the content. Without it the element only remembers
+   * copies it made itself, so after a reload an unchanged re-save cannot find
+   * its own file and reports a spurious `storeError`, and a changed one starts
+   * a fresh file instead of versioning the existing one. Set it when reopening
+   * a stored template; it belongs to the document, so hosts that swap
+   * documents must swap (or clear) it too — `load()` does this for you.
+   */
+  @property({ attribute: 'stored-uuid' }) storedUuid = ''
   /** Ms to wait for the app's ready signal before emitting `error`. 0 disables. */
   @property({ type: Number, attribute: 'ready-timeout' }) readyTimeout = 20000
 
@@ -197,6 +303,21 @@ export class SfxTemplateBuilder extends LitElement {
    * back on save.
    */
   private _sentKey?: string
+  /**
+   * Identity of the last SAVE the app handed back, in the same shape as
+   * `_sentKey`. A host echoing the full save detail into the props (content,
+   * name, templateQuery) matches this key rather than `_sentKey`, whose name
+   * and query still describe what the template was loaded with — without it
+   * the echo would post a HOST_LOAD that reloads the editor and wipes undo
+   * history on nearly every save (a save almost always changes the query).
+   */
+  private _sentSaveKey?: string
+  /**
+   * Identity of the config already delivered, so re-renders don't re-post it.
+   * Undefined means the app has not been told anything yet — set back to that
+   * whenever a new app instance loads.
+   */
+  private _sentConfigKey?: string
   /**
    * The `baseUrl` value already reported as unparseable. `_computeSrc()` runs
    * on every update cycle, so without this a bad URL re-emits `error` forever —
@@ -246,11 +367,13 @@ export class SfxTemplateBuilder extends LitElement {
     templateId,
     name,
     templateQuery,
+    storedUuid,
   }: {
     content: string
     templateId?: string
     name?: string
     templateQuery?: string
+    storedUuid?: string
   }): void {
     if (templateId !== undefined) this.templateId = templateId
     if (name !== undefined) this.templateName = name
@@ -258,10 +381,48 @@ export class SfxTemplateBuilder extends LitElement {
     // previous template's query in place while the new content goes out would
     // open the new document on the old layout and values.
     if (templateQuery !== undefined) this.templateQuery = templateQuery
+    // Omission clears rather than keeps: the seed names the DOCUMENT's stored
+    // copy, and carrying one document's uuid into the next would anchor its
+    // saves to the wrong file. "Unknown" is the safe reading of not saying.
+    this.storedUuid = storedUuid ?? ''
+    // A template of your own is not the blank one: clearing the flag lets a
+    // host alternate between `createNew()` and `load()` on one element.
+    this.newTemplate = false
     this.content = content
     this._open = true
   }
 
+  /**
+   * Stateless mode: open the editor on a new, empty template, opening it if
+   * needed. Equivalent to setting `new-template` and calling `open()`.
+   *
+   * The user chooses the canvas size from the editor's empty state; `save`
+   * then hands back a complete `.fdt` document — the first one you store for
+   * this record. Pass `templateId` if you have already allocated one; leave it
+   * out and the `save` payload simply comes back without an id.
+   *
+   * Calling it again on an editor that is already showing the blank document
+   * does nothing — resending would discard whatever the user has built since.
+   * To genuinely start over, `close()` and reopen.
+   */
+  createNew({
+    templateId,
+    name,
+  }: { templateId?: string; name?: string } = {}): void {
+    if (templateId !== undefined) this.templateId = templateId
+    if (name !== undefined) this.templateName = name
+    // A new document has no layouts and no variables, so there is no render
+    // for a query to select — and a leftover one would name layouts and
+    // variables of the previous template. Same for the stored-copy seed: a
+    // blank document has no copy, and a stale one would anchor the first save
+    // to the previous document's file.
+    this.templateQuery = ''
+    this.storedUuid = ''
+    this.newTemplate = true
+    this.content = ''
+    this._open = true
+  }
+
   /**
    * Stateless mode: report back whether a `save` was persisted on your side.
    *
@@ -297,6 +458,21 @@ export class SfxTemplateBuilder extends LitElement {
     super.disconnectedCallback()
     window.removeEventListener('message', this._onMessage)
     this._clearHandshakeTimer()
+    // Element-level listeners still fire on a detached element, so a vanilla
+    // host that removes the widget mid-upload still gets its raw save. (A
+    // framework wrapper unsubscribes its listeners before the node detaches,
+    // which is why the public `flushPendingSaves()` exists — the React wrapper
+    // calls it from its cleanup, while its listeners still hear the event.)
+    //
+    // Deferred a task: REPARENTING (appendChild into another container)
+    // detaches and reattaches synchronously, and flushing on the detach half
+    // would report a false storeError for an upload that lands fine. Only a
+    // detach that is still detached a tick later is a real removal.
+    setTimeout(() => {
+      if (!this.isConnected) {
+        this._flushPendingSaves('widget removed before the rendering copy completed')
+      }
+    }, 0)
   }
 
   protected willUpdate(changed: PropertyValues): void {
@@ -317,8 +493,14 @@ export class SfxTemplateBuilder extends LitElement {
       this._clearHandshakeTimer()
       // A new document means a new app instance: it has not asked for content
       // yet, and nothing has been delivered to it.
+      // Delivery state only — this is a new APP instance, not a new document.
+      // `_lastDocKey` / `_docEpoch` / `_storeMemory` describe the document and
+      // survive: resetting them here made every modal close or theme swap
+      // forget the stored copy and fork the file on the next save.
       this._contentRequested = false
       this._sentKey = undefined
+      this._sentSaveKey = undefined
+      this._sentConfigKey = undefined
       if (this._isDirty) {
         this._isDirty = false
         this._emit('dirtychange', { isDirty: false })
@@ -330,12 +512,23 @@ export class SfxTemplateBuilder extends LitElement {
     // templates must not leave the app saving under the previous id.
     if (
       changed.has('content') ||
+      changed.has('newTemplate') ||
       changed.has('templateId') ||
       changed.has('templateName') ||
       changed.has('templateQuery')
     ) {
       this._maybeSendContent()
     }
+    // Config is independent of the template: it also has to reach DAM-backed
+    // embeds, which never send a content request. Only once the app is ready,
+    // though — before that there is nothing listening, and the ready signal
+    // sends whatever the latest value is anyway.
+    if (
+      (changed.has('customMetadata') || changed.has('customMetadataLabel')) &&
+      this._status === 'ready'
+    ) {
+      this._maybeSendConfig()
+    }
   }
 
   render() {
@@ -477,6 +670,17 @@ export class SfxTemplateBuilder extends LitElement {
           this._status = 'ready'
           this._emit('ready')
         }
+        // Config rides the ready signal: the app has its listener attached by
+        // the time it announces, and a remount inside an unchanged iframe
+        // re-announces — so this is also the resend point after the editor
+        // reloads and forgets what it was told.
+        //
+        // Keyed on READY alone, because a single mount announces READY *and*
+        // OPEN and resetting on both would post the same config twice. OPEN
+        // still calls in, without the reset: after a READY that is a no-op, and
+        // it is the only signal an app deployment older than protocol v1 sends.
+        if (msg.type === BUILDER_READY) this._sentConfigKey = undefined
+        this._maybeSendConfig()
         if (msg.type === BUILDER_OPEN) this._emit('open')
         break
       case BUILDER_SAVE:
@@ -489,6 +693,7 @@ export class SfxTemplateBuilder extends LitElement {
         // iframe, so resend even if this content went out already — otherwise
         // the editor waits on a skeleton forever.
         this._sentKey = undefined
+        this._sentSaveKey = undefined
         this._maybeSendContent()
         break
       case BUILDER_CONTENT: {
@@ -496,11 +701,47 @@ export class SfxTemplateBuilder extends LitElement {
         // regardless of mode; the detail shape follows the mode they chose.
         const data = (msg as BuilderContentMessage).data
         // The saved document is what the editor now holds. A host that stores
-        // it and echoes it back into `content` — the natural controlled
+        // it and echoes it back into the props — the natural controlled
         // pattern — must not trigger a HOST_LOAD reload that wipes the
-        // editor's undo history behind a skeleton flash.
+        // editor's undo history behind a skeleton flash. TWO keys are
+        // recorded because hosts echo different subsets: the prop-based key
+        // covers "content only, other props untouched", and the detail-based
+        // key covers "the whole save detail" — whose name and templateQuery
+        // (a save nearly always changes the query) differ from the props the
+        // template was loaded with.
         this._sentKey = this._contentKey(data.content)
-        this._emit('save', data)
+        this._sentSaveKey = this._detailKey(data)
+        if (this.damStore) {
+          // Serialized, not fired in parallel: the app discards a failure ack
+          // that has newer saves still outstanding as superseded, which is
+          // only sound while acks come back in post order — and ack order
+          // follows save-event order. Two racing uploads could swap it.
+          this._pendingSaves.add(data)
+          // Epoch, folder and credentials are captured now, not when the
+          // queued upload runs: the save belongs to the document — and the
+          // configuration — the app posted it under, and the host may have
+          // swapped both by the time the queue reaches it. Only the
+          // known-uuid seed stays live (validated against the epoch), because
+          // an earlier queued save of the SAME document must be able to hand
+          // its uuid to the next one.
+          const session = this._docEpoch
+          const job = {
+            auth: {
+              token: this.token,
+              sassKey: this.sassKey,
+              secTemplate: this.secTemplate,
+              sessionUuid: this.sessionUuid,
+              companyUuid: this.companyUuid,
+              projectUuid: this.projectUuid,
+            },
+            storeFolder: this.storeFolder || '/',
+          }
+          this._storeQueue = this._storeQueue.then(() =>
+            this._storeAndEmitSave(data, session, job),
+          )
+        } else {
+          this._emit('save', data)
+        }
         break
       }
       case BUILDER_DIRTY: {
@@ -510,6 +751,13 @@ export class SfxTemplateBuilder extends LitElement {
         break
       }
       case BUILDER_CLOSE:
+        // Pending `dam-store` uploads are deliberately NOT flushed here: the
+        // element outlives a close (inline keeps rendering, modal just drops
+        // its overlay), so a save still inside its upload window emits with
+        // its real outcome moments later — flushing would hand the host a
+        // `storeError` for a copy that lands fine. The paths where waiting
+        // genuinely loses the event — element removal — are covered by
+        // `disconnectedCallback` and the React wrapper's cleanup flush.
         this._emit('close')
         if (this.mode === 'modal') this._open = false
         break
@@ -519,25 +767,219 @@ export class SfxTemplateBuilder extends LitElement {
     }
   }
 
+  /**
+   * Pending `dam-store` uploads, chained so saves emit in the order the app
+   * posted them. `_storeAndEmitSave` never rejects (its catch emits
+   * `storeError`), so the chain cannot wedge.
+   */
+  private _storeQueue: Promise<void> = Promise.resolve()
+
+  /**
+   * Saves handed over by the app whose `save` event has not fired yet — the
+   * upload window. Insertion-ordered; membership is what makes a flush and a
+   * completing upload not double-emit the same save.
+   */
+  private _pendingSaves = new Set<BuilderContentData>()
+
+  /**
+   * Identity (id, content, name — not query) of the last document posted to
+   * the app — updated on every ship, and on an accepted save echo (the echoed
+   * document IS the current one; leaving the pre-save key here would make a
+   * later content-request redelivery look like a new document and wipe the
+   * store memory below).
+   */
+  private _lastDocKey?: string
+
+  /**
+   * Monotonic id of the current DOCUMENT. Bumped in exactly one place: when
+   * `_maybeSendContent` ships a genuinely different document (docKey change).
+   * Deliberately NOT bumped on iframe/src changes — a modal close, a theme
+   * swap or an in-place remount is the same document, and treating it as new
+   * forked the file on every such boundary.
+   */
+  private _docEpoch = 0
+
+  /**
+   * The copy this element last stored, tagged with the epoch of the document
+   * it belongs to. Written when an upload lands (with the SAVE's epoch, so a
+   * late-landing upload can never masquerade as another document's copy) and
+   * validated at read time — there is no eager reset to get wrong.
+   */
+  private _storeMemory?: { epoch: number; uuid: string }
+
+  /**
+   * Emit every not-yet-emitted `dam-store` save immediately, raw content with
+   * `storeError` in place of the links. Called when waiting any longer risks
+   * the event finding no listener; a still-running upload for a flushed save
+   * is left to finish (the copy usually lands) but will not emit again.
+   *
+   * Public for framework wrappers: one that unsubscribes its listeners before
+   * unmounting must call this first, while they are still attached — the
+   * element's own disconnect-time flush fires only after the wrapper has
+   * stopped listening, and the raw save would be lost. The React wrapper does
+   * this; a vanilla host never needs to call it.
+   */
+  flushPendingSaves(
+    reason = 'widget removed before the rendering copy completed',
+  ): void {
+    this._flushPendingSaves(reason)
+  }
+
+  private _flushPendingSaves(reason: string): void {
+    for (const data of this._pendingSaves) {
+      this._pendingSaves.delete(data)
+      this._emit('save', { ...data, storeError: reason })
+    }
+  }
+
+  /**
+   * The `dam-store` save path: upload the edited template to Filerobot, then
+   * emit `save` with the stored copy's links on the detail. The upload is the
+   * render side of the save — the CDN renders only stored files — while the
+   * raw `content` stays the host's copy exactly as without the flag.
+   *
+   * A failed upload still emits `save` (the raw data must reach the host
+   * either way), with `storeError` in place of `stored`; whether a save
+   * without a rendering copy counts as saved is the host's decision, made
+   * where it always is — the save ack.
+   */
+  private async _storeAndEmitSave(
+    data: BuilderContentData,
+    session: number,
+    job: { auth: DamStoreAuth; storeFolder: string },
+  ): Promise<void> {
+    if (!this._pendingSaves.has(data)) return
+    // The seeds are validated against the save's own document epoch. The
+    // element's memory carries the epoch it was recorded under; the host's
+    // `storedUuid` property is live and describes the CURRENT document, so it
+    // only applies while the save's epoch is still the current one — anchoring
+    // a stale save's upload to it would put the old document into the new
+    // one's file. Folder and credentials come from the job captured at
+    // enqueue time, for the same reason.
+    const knownUuid =
+      (this._storeMemory?.epoch === session
+        ? this._storeMemory.uuid
+        : undefined) ||
+      (session === this._docEpoch ? this.storedUuid || undefined : undefined)
+    let stored: StoredTemplate | undefined
+    let storeError: string | undefined
+    try {
+      stored = await storeTemplateInDam(data, job.auth, job.storeFolder, knownUuid)
+    } catch (err) {
+      storeError = err instanceof Error ? err.message : String(err)
+    }
+    // A flush mid-upload already delivered this save; the copy (if it landed)
+    // is simply not reported. Emitting again would double the host's write —
+    // and recording the uuid would poison the session memory of whatever
+    // document has loaded since (the flush usually precedes a swap), pointing
+    // its next save at this document's file.
+    if (!this._pendingSaves.delete(data)) return
+    // Recorded under the SAVE's epoch, unconditionally: a copy always belongs
+    // to the document it was saved from. A later document's saves carry a
+    // higher epoch and simply never match this record — no current-vs-then
+    // comparison to get wrong. (Uploads complete in queue order, so the last
+    // write is always the newest save.)
+    if (stored) this._storeMemory = { epoch: session, uuid: stored.uuid }
+    this._emit('save', stored ? { ...data, stored } : { ...data, storeError })
+  }
+
   /**
    * Deliver `content` to the app once both sides are ready: it has asked, and
    * we have something new to give it. Skips a re-send of identical content so
    * an unrelated re-render can't discard the user's in-progress edits.
    */
   private _maybeSendContent(): void {
-    if (!this.stateless || !this._contentRequested || !this.content) return
+    if (!this.stateless || !this._contentRequested) return
+
+    // Empty `content` means the host has nothing to give yet — usually a fetch
+    // in flight — so the editor keeps waiting. Only `new-template` turns that
+    // into a document, and only until the host does supply one.
+    const content =
+      this.content || (this.newTemplate ? BLANK_TEMPLATE_XML : '')
+    if (!content) return
 
     const data = {
       templateId: this.templateId || undefined,
-      content: this.content,
+      content,
       name: this.templateName || undefined,
       templateQuery: this.templateQuery || undefined,
     }
-    const key = this._contentKey(this.content)
-    if (key === this._sentKey) return
+    const key = this._contentKey(content)
+    // The document's identity — id, content, name; NOT the query. A
+    // query-only resend ("same XML, different render") and a content-request
+    // redelivery after an in-place remount are the same document, and
+    // treating them as new would orphan the stored copy.
+    const docKey = JSON.stringify({
+      templateId: this.templateId || undefined,
+      content,
+      name: this.templateName || undefined,
+    })
+    // `_sentSaveKey` counts as delivered too: matching it means the host has
+    // echoed the last save back into the props, and the editor already holds
+    // exactly that document — reloading would wipe its undo history. The doc
+    // key is still refreshed: the echoed document IS the current one, and
+    // leaving the pre-save key in place would make the next redelivery of
+    // this same content look like a document change and orphan the copy.
+    if (key === this._sentKey || key === this._sentSaveKey) {
+      this._lastDocKey = docKey
+      return
+    }
 
     if (!this._postToApp({ type: HOST_LOAD, data })) return
+    // A genuinely different document starts a new epoch — the file the
+    // previous one made must not resolve this one's folder or unchanged
+    // re-saves.
+    if (docKey !== this._lastDocKey) this._docEpoch++
+    this._lastDocKey = docKey
     this._sentKey = key
+    // A new document shipped: the previous save's echo key no longer names
+    // what the editor holds, and matching it later would wrongly skip a load.
+    this._sentSaveKey = undefined
+  }
+
+  /**
+   * Deliver host config to the app. Unlike content this is not requested — the
+   * app has no way to know a host means to send any — so it goes out on the
+   * ready signal and on every later change.
+   *
+   * Sending an empty model is meaningful: it is how a host clears one it set
+   * before. What is skipped is only a *repeat* of what the app already holds,
+   * and the very first send when there was never anything to say.
+   */
+  private _maybeSendConfig(): void {
+    // Hosts are plain JS as often as not, and the property has no converter to
+    // vet what lands on it the way the attribute does. Anything that is not a
+    // list of fields is treated as no model rather than posted onward as
+    // something the app would have to make sense of.
+    const customMetadata = Array.isArray(this.customMetadata)
+      ? this.customMetadata
+      : []
+    const customMetadataLabel =
+      typeof this.customMetadataLabel === 'string'
+        ? this.customMetadataLabel.trim()
+        : ''
+    const key = JSON.stringify({ customMetadata, customMetadataLabel })
+    if (key === this._sentConfigKey) return
+    if (
+      this._sentConfigKey === undefined &&
+      customMetadata.length === 0 &&
+      customMetadataLabel === ''
+    ) {
+      return
+    }
+
+    if (
+      !this._postToApp({
+        type: HOST_CONFIG,
+        data: {
+          customMetadata,
+          ...(customMetadataLabel ? { customMetadataLabel } : {}),
+        },
+      })
+    ) {
+      return
+    }
+    this._sentConfigKey = key
   }
 
   /** Identity of a delivered template, as compared against `_sentKey`. */
@@ -550,6 +992,20 @@ export class SfxTemplateBuilder extends LitElement {
     })
   }
 
+  /**
+   * Identity of a save the app handed back — the same shape as
+   * `_contentKey`, but built from the save detail rather than the props, so
+   * a host echoing the detail (whose name/query the save changed) matches.
+   */
+  private _detailKey(data: BuilderContentData): string {
+    return JSON.stringify({
+      templateId: data.templateId || undefined,
+      content: data.content,
+      name: data.name || undefined,
+      templateQuery: data.templateQuery || undefined,
+    })
+  }
+
   /** Post into the iframe, targeted at the app origin. False if not mounted. */
   private _postToApp(message: unknown): boolean {
     const target = this.shadowRoot?.querySelector('iframe')?.contentWindow