@scaleflex/template-builder 0.2.0 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@
 <h1 align="center">@scaleflex/template-builder</h1>
 
 <p align="center">
-  Framework-agnostic Design Template Builder Web Component for <a href="https://www.scaleflex.com/page/digital-asset-management">Filerobot</a>.<br>
+  Framework-agnostic Design Template Builder Web Component for <a href="https://www.scaleflex.com/page/digital-asset-management">Scaleflex</a>.<br>
   Drop a full multi-layout template editor into any page, in any frontend stack.
 </p>
 
@@ -34,11 +34,13 @@
 - [Modes](#modes)
   - [DAM-backed](#dam-backed-default)
   - [Stateless](#stateless)
+  - [Storing a rendering copy (dam-store)](#storing-a-rendering-copy-dam-store)
   - [Starting a template from scratch](#starting-a-template-from-scratch)
   - [Reporting a failed save](#reporting-a-failed-save)
 - [Configuration](#configuration)
   - [Attributes & properties](#attributes--properties)
   - [Authentication](#authentication)
+  - [Custom metadata fields](#custom-metadata-fields)
   - [Origin registration](#origin-registration)
   - [Cookies](#cookies)
 - [Public Methods](#public-methods)
@@ -58,11 +60,11 @@
 
 ## Overview
 
-`<sfx-template-builder>` embeds the Filerobot design-templates builder in a page
-on any origin. The element owns an iframe pointed at a `design-templates-app`
-deployment, hands over the credentials, and translates the app's
-postMessage protocol into ordinary DOM `CustomEvent`s — so from your side it
-behaves like any other component.
+`<sfx-template-builder>` embeds the Scaleflex design-templates builder in a page
+on any origin. The element loads the editor from a `design-templates-app`
+deployment, hands over the credentials, and surfaces everything the editor does
+as ordinary DOM `CustomEvent`s — so from your side it behaves like any other
+component.
 
 All the heavy lifting — server-side text rendering, font resolution, asset
 browsing, template XML — stays inside the app deployment. The widget is a
@@ -72,10 +74,10 @@ protocol adapter.
 
 - **Framework-agnostic** — a custom element; works in vanilla JS, React, Vue,
   Angular, Svelte. A thin React wrapper ships in the box.
-- **Two storage modes** — let Filerobot own the template, or keep the document
+- **Two storage modes** — let Scaleflex own the template, or keep the document
   entirely on your side ([Stateless](#stateless)) and never map your users onto
   Scaleflex identities.
-- **Two ways in** — a Hub session, or a Filerobot [security
+- **Two ways in** — a Hub session, or a Scaleflex [security
   template](#security-template-guest-auth) when you have no Hub account to hand
   over per user.
 - **Inline or modal** — fill a box in your layout, or cover the viewport.
@@ -88,17 +90,17 @@ protocol adapter.
   origin; the app only accepts a template from the origin pinned when the
   session was handed over.
 - **Diagnosable failures** — auth, blocked cookies, bad content and handshake
-  timeouts all surface as an `error` event instead of a stuck iframe.
+  timeouts all surface as an `error` event instead of a stuck editor.
 
 ## Requirements
 
-- A [Filerobot](https://www.scaleflex.com/page/digital-asset-management) account
+- A [Scaleflex](https://www.scaleflex.com/page/digital-asset-management) account
   and a running `design-templates-app` deployment to point `base-url` at
 - Credentials minted server-side — either a Hub session (`session-uuid` +
-  **SASS key** + **Filerobot token**) or a **security template** + token for
+  **SASS key** + **Scaleflex token**) or a **security template** + token for
   guest access; see [Authentication](#authentication)
-- Your page's origin registered in the deployment's `frame-ancestors` allowlist
-  — see [Origin registration](#origin-registration)
+- Your page's origin registered in the deployment's embedding allowlist — see
+  [Origin registration](#origin-registration)
 - Modern browser with Custom Elements v1 support (see
   [Browser Support](#browser-support))
 
@@ -113,7 +115,7 @@ npm i @scaleflex/template-builder
 ### CDN
 
 ```html
-<script type="module" src="https://cdn.scaleflex.com/design-template-builder/0.2.0/template-builder.min.js"></script>
+<script type="module" src="https://cdn.cloudimage.io/template-builder/0.4.1/template-builder.min.js"></script>
 ```
 
 The CDN bundle is self-registering — it defines `<sfx-template-builder>` on
@@ -139,7 +141,7 @@ load, with Lit bundled in. Pin the major version.
 
 ## Quick Start
 
-You need two things from your Filerobot project: its **token**, and a
+You need two things from your Scaleflex project: its **token**, and a
 **security template** key — a named, permission-scoped credential you define
 once, the same guest-auth mechanism the other Scaleflex widgets use. No Hub
 account, and no user of yours ever needs a Scaleflex identity. See
@@ -211,7 +213,7 @@ Mint the session server-side; never put a long-lived credential in client code.
 ```html
 <sfx-template-builder
   base-url="https://<your-design-templates-deployment>"
-  token="FILEROBOT_TOKEN"
+  token="PROJECT_TOKEN"
   sass-key="SASS_KEY"
   session-uuid="SESSION_UUID"
   template-id="TEMPLATE_UUID"
@@ -238,7 +240,7 @@ Mint the session server-side; never put a long-lived credential in client code.
 
 ### DAM-backed (default)
 
-`template-id` is a Filerobot file uuid. The app loads the template itself, and
+`template-id` is a DAM file uuid. The app loads the template itself, and
 Save uploads a new version and reports the resulting uuid on the `save` event.
 Leave `template-id` empty to open the new-template flow.
 
@@ -246,7 +248,9 @@ Leave `template-id` empty to open the new-template flow.
 
 Set `stateless` to keep the document entirely on your side: you pass the
 template in, the user edits it, and you get the edited template back. Nothing is
-stored on the Scaleflex side, so your app keeps its own storage, versioning,
+stored on the Scaleflex side (unless you opt into
+[`dam-store`](#storing-a-rendering-copy-dam-store) for a rendering copy), so
+your app keeps its own storage, versioning,
 tenancy and access control, and `template-id` becomes an opaque string that is
 echoed back untouched.
 
@@ -274,8 +278,8 @@ point.
   const { content, name, templateQuery } = await res.json()
 
   // 2 — pass it in. `content` is a property, never an attribute: templates
-  //     routinely exceed what fits in markup or a URL, which is also why the
-  //     widget delivers it over postMessage rather than the iframe src.
+  //     routinely exceed what fits in markup or a URL, so the widget hands the
+  //     document to the editor directly rather than through either.
   //     `templateQuery` is what you stored on the last save; it reopens the
   //     template on the same layout and variable values.
   builder.load({ templateId: id, name, content, templateQuery })
@@ -301,7 +305,7 @@ point.
 </script>
 ```
 
-`templateId` is **your** identifier, not a Filerobot uuid. The app never
+`templateId` is **your** identifier, not a DAM uuid. The app never
 resolves it against anything — it is carried alongside the content and handed
 straight back on save, so use whatever key maps to your own record.
 
@@ -410,7 +414,7 @@ you navigated away from.
 #### What stateless does *not* remove
 
 Statelessness applies to the **document**, not to the infrastructure. The editor
-still needs an authenticated Filerobot tenant for:
+still needs an authenticated Scaleflex tenant for:
 
 - **text rendering** — text and shape layers are rasterized server-side (see
   [the render round-trip](#why-the-editor-still-calls-a-server) below),
@@ -432,7 +436,7 @@ This is the reason a stateless embed still needs a credential, so it is worth
 being concrete about.
 
 A `.fdt` template is not an image. The image only exists once someone requests
-the template's CDN URL, and it is Filerobot that renders it there — server-side,
+the template's CDN URL, and it is Scaleflex that renders it there — server-side,
 with ImageMagick:
 
 ```
@@ -456,8 +460,8 @@ editor drives a WebAssembly build of it), and each layer comes back as a
 transparent PNG that the canvas positions with CSS:
 
 ```
-  browser — widget iframe                     app deployment (base-url)
-  ───────────────────────                     ─────────────────────────
+  browser — the widget                        app deployment (base-url)
+  ────────────────────                        ─────────────────────────
   edit a text layer
       │  batched across layers, debounced
       ├──────  POST /api/render-layers  ─────▶  ImageMagick (WASM)
@@ -497,7 +501,64 @@ session to hand over — and that is exactly the gap a
 [security template](#security-template-guest-auth) fills: a permission-scoped,
 project-level guest credential that authorizes rendering, fonts and asset
 browsing without authenticating any particular user, and without your users
-existing in Filerobot at all.
+existing in Scaleflex at all.
+
+### Storing a rendering copy (dam-store)
+
+The raw XML in the `save` event is yours to keep — but the CDN renders only
+files it stores, so previews and production banners need a copy in Filerobot
+too. Set `dam-store` and the element makes that copy itself on every stateless
+save, with the same multipart upload the DAM-backed editor uses, before the
+`save` event fires. The detail then carries the links next to the raw data:
+
+```ts
+builder.damStore = true
+builder.addEventListener('save', (e) => {
+  const { content, templateQuery, stored, storeError } = e.detail
+  // stored = { uuid, url } — the DAM copy. `url` is the .fdt's CDN URL with
+  // its current ?vh= cache key; append templateQuery and it IS a render:
+  //   <img src=`${stored.url}&${templateQuery}`>
+  // (`url` can rarely come back empty — the record read-back after the
+  // upload failed; the file is stored regardless, under stored.uuid. And
+  // join with '?' instead of '&' if your URL happens to carry no query.)
+})
+```
+
+Added after 0.3.0 — if your pinned CDN bundle predates it, the attribute is
+silently ignored; check the [changelog](./CHANGELOG.md).
+
+What to know:
+
+- **The raw `content` arrives either way.** A failed upload replaces `stored`
+  with `storeError` (a message) — whether a save without a rendering copy
+  counts as saved is your call, made where it always is: the save ack
+  (`confirmSave(false)` / returning `false` from React's `onSave`).
+- **The raw content never dies with the element.** Closing the editor changes
+  nothing: the element outlives a close, so a save still inside its upload
+  window simply emits moments later with its real outcome — possibly after
+  the `close` event. Only *removing* the element mid-upload flushes the
+  pending `save` immediately, raw content with a `storeError` note (the copy,
+  if it lands, goes unreported); the React wrapper does the same from its
+  unmount cleanup. And rapid saves are serialized, so `save` events always
+  arrive in the order the editor posted them.
+- **Same name + folder versions the file in place.** When `template-id` names
+  an existing DAM file, its own folder is reused; otherwise new templates land
+  in `store-folder` (default `/`). Under a VERSION conflict policy each save is
+  its own file row — `stored.uuid` is always the current one, so persist it
+  (don't echo it into `template-id`: an id change deliberately reloads the
+  editor). The element remembers the copy it last made, so follow-up saves —
+  including unchanged re-saves, which resolve to that copy instead of
+  erroring — keep working against it even while your own id stays opaque.
+  That memory lives in the element instance: to carry it across a page
+  reload or remount, pass the persisted uuid back in as `stored-uuid` /
+  `storedUuid` (or the `storedUuid` field of `load()`) alongside the content.
+- **The stored `template_query` is record-agnostic.** Values of
+  [custom-metadata-bound](#custom-metadata-fields) variables are stripped
+  before the query is attached as file metadata, so one record's data never
+  becomes the template's own default.
+- **The credential needs upload rights.** A
+  [security template](#security-template-guest-auth) must have a scope that
+  allows uploads, or every save reports `storeError`.
 
 ### Starting a template from scratch
 
@@ -557,10 +618,10 @@ template is just a template, and `BLANK_TEMPLATE_XML` is exported from
 
 ### Reporting a failed save
 
-The editor clears its unsaved-changes state as soon as it posts `save` —
-delivery of a postMessage says nothing about whether you stored anything. Tell
-it when you didn't, and it restores the dirty flag and warns the user instead of
-showing a failed write as saved:
+The editor clears its unsaved-changes state as soon as it emits `save` —
+receiving the event says nothing about whether you stored anything. Tell it when
+you didn't, and it restores the dirty flag and warns the user instead of showing
+a failed write as saved:
 
 ```js
 builder.addEventListener('save', async (e) => {
@@ -589,18 +650,23 @@ without it a failed write is invisible to the user.
 | Attribute / property | Required | Description |
 | --- | --- | --- |
 | `base-url` / `baseUrl` | yes | Origin of the design-templates-app deployment |
-| `token` | yes | Filerobot token (`ftoken`) |
+| `token` | yes | Scaleflex token (`ftoken`) |
 | `sass-key` / `sassKey` | session auth | Project sass key |
 | `session-uuid` / `sessionUuid` | session auth | Hub session uuid |
-| `sec-template` / `secTemplate` | guest auth | Filerobot security-template key, *instead of* `sass-key` + `session-uuid`. Stateless only — see [Authentication](#authentication) |
+| `sec-template` / `secTemplate` | guest auth | Scaleflex security-template key, *instead of* `sass-key` + `session-uuid`. Stateless only — see [Authentication](#authentication) |
 | `company-uuid`, `project-uuid` | no | Company / project scoping (session auth only) |
-| `template-id` / `templateId` | no | DAM-backed: Filerobot uuid to edit, empty opens the new-template flow. Stateless: opaque id echoed back on `save` |
+| `template-id` / `templateId` | no | DAM-backed: the file uuid to edit, empty opens the new-template flow. Stateless: opaque id echoed back on `save` |
 | `mode` | no | `inline` (default; size the element) or `modal` (fullscreen overlay, starts closed — call `open()`) |
 | `stateless` | no | Pass the template in and take it back out instead of using the DAM (see [Stateless](#stateless)). Requires `content`, or `new-template` |
 | `content` (property only) | stateless | The template to edit, as `.fdt` XML. Assigning a new value loads it into a running editor |
 | `new-template` / `newTemplate` | no | Stateless: open on a new, empty template instead of supplying `content` — the widget provides the blank document. Ignored when `content` is set. See [Starting a template from scratch](#starting-a-template-from-scratch) |
 | `template-name` / `templateName` | no | Stateless: header title |
 | `template-query` / `templateQuery` | no | Stateless: the render to open on — the `templateQuery` from the last save. Empty uses the XML's `default=` values. |
+| `custom-metadata` / `customMetadata` | no | Metadata model offered as the **Custom metadata** value source: `[{ key, title?, group? }]`, as an array (property) or JSON (attribute). See [Custom metadata fields](#custom-metadata-fields) |
+| `custom-metadata-label` / `customMetadataLabel` | no | Renames the **Custom metadata** value source in the editor's UI (e.g. `External metadata`). Wording only — the stored template is unaffected. Empty uses the default |
+| `dam-store` / `damStore` | no | Stateless only: the element stores each save in Filerobot too, and `save`'s detail carries `stored: { uuid, url }` (or `storeError`) next to the raw `content`. See [Storing a rendering copy](#storing-a-rendering-copy-dam-store) |
+| `store-folder` / `storeFolder` | no | `dam-store`: folder for templates whose id names no existing DAM file (default `/`); an existing file's own folder always wins |
+| `stored-uuid` / `storedUuid` | no | `dam-store`: the `stored.uuid` you persisted for this document, passed back in so re-saves after a reload resolve to (and version) the existing copy. Per-document — `load()` clears it when omitted |
 | `brand-color` / `brandColor` | no | Accent colour for the editor chrome, `#rgb` / `#rrggbb` |
 | `theme` | no | `light`, `dark` or `auto` |
 | `ready-timeout` / `readyTimeout` | no | Ms to wait for the app handshake before `error` (default 20000, 0 disables) |
@@ -628,9 +694,9 @@ long-lived master credential in client-side code.
 
 #### Security template (guest auth)
 
-A Filerobot **security template** is a named, permission-scoped credential you
-define once in your Filerobot project — the same guest-auth mechanism the other
-Scaleflex widgets use. Hand one to the widget and no Hub session is involved at
+A **security template** is a named, permission-scoped credential you define once
+in your Scaleflex project — the same guest-auth mechanism the other Scaleflex
+widgets use. Hand one to the widget and no Hub session is involved at
 all.
 
 It is what makes a stateless embed work without Hub accounts. Even when the
@@ -680,17 +746,85 @@ before you pick it:
 
 - **Stateless only.** Setting `sec-template` without `stateless` is a config
   error — the widget reports `error` with code `invalid-config` and never mounts
-  the iframe. The dashboard and the DAM-backed editor keep requiring a session.
+  the editor. The dashboard and the DAM-backed editor keep requiring a session.
 - **Hub-project features come back empty** — metadata fields, regional variants
   and dynamic fields have no model to read, and project branding does not apply
   (theme the chrome with `brand-color` / `theme` instead).
 <!-- internal:end -->
 
+### Custom metadata fields
+
+A text variable normally takes its value from the render query (**Free text**),
+or from the source asset's DAM metadata (**File metadata**, which needs a
+Hub session — it is unavailable under `sec-template`). `custom-metadata` adds a
+third source: your own field names, so an author binds a variable to `sku`
+instead of having to remember which slug happens to mean the SKU.
+
+```html
+<sfx-template-builder
+  base-url="https://templates.example.com"
+  token="…"
+  sec-template="…"
+  stateless
+  custom-metadata='[
+    { "key": "sku",      "title": "SKU",           "group": "Product" },
+    { "key": "price",    "title": "Price",         "group": "Product" },
+    { "key": "campaign", "title": "Campaign name" }
+  ]'
+></sfx-template-builder>
+```
+
+```ts
+// Or as a property, which is nicer for anything built at runtime:
+builder.customMetadata = fields.map((f) => ({ key: f.id, title: f.label }))
+```
+
+Fields appear in the editor's picker in the order you declare them, grouped
+under `group` where present, with `title` (or the bare `key`) as the label. Set
+no model and the source is not offered at all.
+
+The source is called **Custom metadata** in the editor by default;
+`custom-metadata-label` renames it to fit your domain — `External metadata`,
+`Product attributes`, whatever your authors know it as. Wording only: the saved
+template carries the same `custom_ckey` either way. (The label is another
+post-0.3.0 addition — an older pinned bundle ignores it.)
+
+**Names only — no values travel with the model, and the editor resolves nothing
+against it.** The binding is stored in the saved `.fdt` on the variable as
+`custom_ckey`, and the variable renders exactly like a free-text one: your
+pipeline substitutes the value by putting `$slug=value` in the render query.
+
+```xml
+<variable annotation_id="text_1" display="Product code" name="code"
+          type="text_placeholder" source="URL" custom_ckey="sku"
+          default="AB-1234" />
+```
+
+So the round trip is: read `custom_ckey` back from the template you stored, look
+up that field in your own data, and render with `$code=<that value>`. Until you
+do, the editor and any render show the variable's default value.
+
+A few consequences worth knowing:
+
+- **The model can change between sessions.** A variable bound to a key your
+  current model does not list keeps its binding — the editor shows it read-only
+  and says so — so opening a template with a narrower model never silently
+  rewrites it.
+- **Nothing is validated against the model at render time.** A key you stop
+  sending simply stops being substituted, and the default shows instead.
+- **Send it whenever you like.** The widget delivers the model as soon as the
+  editor is ready and re-sends it whenever you change it; assigning an equal
+  model is a no-op. It applies to DAM-backed embeds as well as stateless ones.
+- **Malformed fields are dropped, not fatal.** An entry with no `key`, a
+  duplicate `key` (first one wins), or a `key` containing a character XML cannot
+  carry — a C0 control, an unpaired surrogate — is skipped; the rest of the model
+  still works. Ordinary text, punctuation, accents and emoji are all fine.
+
 ### Origin registration
 
-Your page's origin must be in the deployment's `frame-ancestors` allowlist
-(`NEXT_PUBLIC_TRUSTED_HUB_ORIGINS`), otherwise the browser refuses to render the
-iframe — Chrome shows "refused to connect" in place of the editor, and the
+Your page's origin must be in the deployment's embedding allowlist
+(`NEXT_PUBLIC_TRUSTED_HUB_ORIGINS`), otherwise the browser refuses to load the
+editor on your page — Chrome shows "refused to connect" in its place, and the
 widget reports `handshake-timeout`.
 
 A deployment allows `'self'`, `https://*.scaleflex.com`,
@@ -711,9 +845,10 @@ without CHIPS support that block third-party cookies will fail with `auth` or
 
 | Method | Description |
 | --- | --- |
-| `open(templateId?)` | Open the editor, loading the iframe. Optionally switch template first. |
-| `close()` | Close the editor and unload the iframe. Does not emit `close`. |
-| `load({ content, templateId?, name?, templateQuery? })` | Stateless: load a template, opening the editor if needed. `templateQuery` picks the render to open on — see [About `templateQuery`](#about-templatequery). |
+| `open(templateId?)` | Open the editor, loading it if it isn't loaded yet. Optionally switch template first. |
+| `close()` | Close the editor and unload it. Does not emit `close`. |
+| `load({ content, templateId?, name?, templateQuery?, storedUuid? })` | Stateless: load a template, opening the editor if needed. `templateQuery` picks the render to open on — see [About `templateQuery`](#about-templatequery). `storedUuid` seeds the [dam-store](#storing-a-rendering-copy-dam-store) memory; omitting it clears the seed. |
+| `flushPendingSaves(reason?)` | Emit any `dam-store` saves still waiting on their upload, raw content with `storeError` in place of the links. Only for framework wrappers that unsubscribe listeners before removing the element — the React wrapper calls it for you. |
 | `createNew({ templateId?, name? })` | Stateless: open on a new, empty template — no XML needed. See [Starting a template from scratch](#starting-a-template-from-scratch). |
 | `confirmSave(ok, message?)` | Stateless: report whether you persisted the content. See [Reporting a failed save](#reporting-a-failed-save). |
 
@@ -730,7 +865,7 @@ All events are `CustomEvent`s; the payload is in `detail`.
 | --- | --- | --- |
 | `ready` | — | The editor mounted and auth validated. Clears the handshake timeout. |
 | `open` | — | The editor UI opened. |
-| `save` | `{ uuid, name }` (DAM-backed) or `{ templateId, content, name, templateQuery }` (stateless) | The user saved. |
+| `save` | `{ uuid, name }` (DAM-backed) or `{ templateId, content, name, templateQuery }` (stateless; under [`dam-store`](#storing-a-rendering-copy-dam-store) also `stored: { uuid, url }` or `storeError`) | The user saved. |
 | `dirtychange` | `{ isDirty }` | Stateless: the unsaved-changes flag flipped. |
 | `close` | — | The user left the editor, or it unmounted. |
 | `error` | `{ code, message? }` | See below. |
@@ -739,10 +874,10 @@ All events are `CustomEvent`s; the payload is in `detail`.
 
 | Code | Means |
 | --- | --- |
-| `auth` | The app could not authenticate — blocked cookies, an expired session, or a security template the Filerobot API refused. |
+| `auth` | The app could not authenticate — blocked cookies, an expired session, or a security template the Scaleflex API refused. |
 | `invalid-content` | Stateless: the `content` you sent is not a parseable `.fdt` document. |
-| `invalid-config` | Attributes that contradict each other, e.g. `sec-template` without `stateless`. The iframe never mounts. |
-| `handshake-timeout` | No ready signal in time — usually a missing `frame-ancestors` entry or blocked third-party cookies. |
+| `invalid-config` | Attributes that contradict each other, e.g. `sec-template` without `stateless`. The editor never mounts. |
+| `handshake-timeout` | No ready signal in time — usually a missing entry in the deployment's embedding allowlist, or blocked third-party cookies. |
 | `invalid-base-url` | `base-url` is not a URL. |
 | `unknown` | Anything the app reported that this version does not name. |
 
@@ -750,6 +885,13 @@ All events are `CustomEvent`s; the payload is in `detail`.
 `modal` mode the element tears its overlay down; in `inline` mode it is yours to
 act on — the editor never navigates itself anywhere.
 
+Under [`dam-store`](#storing-a-rendering-copy-dam-store), a save whose upload
+is still in flight emits **after** `close`, with its real outcome. Keep your
+`save` listener attached until it arrives — or, if your close handler tears the
+element down anyway, removing it from the DOM flushes the pending save to your
+still-attached listeners; call `flushPendingSaves()` yourself only if you
+detach listeners without removing the element.
+
 ## React API
 
 Props mirror the attributes in camelCase, plus `className` and `style`.
@@ -763,6 +905,10 @@ The credential props are a discriminated union, so the two
 `onSave` may return `false` or a promise; see
 [Reporting a failed save](#reporting-a-failed-save).
 
+`customMetadata` is an array prop, compared by identity like the rest — hoist it
+to module scope or memoise it, or every render counts as a change (harmless; the
+element de-dupes by value before it says anything to the editor).
+
 The component forwards a ref to the underlying element, which is how you reach
 the [imperative API](#public-methods) — required for `mode="modal"`, which
 renders nothing until `open()` is called:
@@ -877,15 +1023,15 @@ only thing it needs at runtime is a reachable `design-templates-app` for the
 demo page's Base URL field to point at; it defaults to
 `https://design-templates.scaleflex.com`.
 
-That default frames successfully only from an origin that deployment allows —
+That default loads successfully only from an origin that deployment allows —
 `'self'`, `*.scaleflex.com`, `*.filerobot.com` and `http://localhost:5173`,
 which covers both the demo as published to the CDN and `yarn dev:demo`. Serving
 it anywhere else — another port (`yarn preview:demo` uses 4173), or a copy on
 your own domain — gets "refused to connect" until that origin joins the
 deployment's allowlist, which is baked in at build time and so needs a rebuild
 (see [Origin registration](#origin-registration)). Driving a *locally* running
-app has the same requirement in reverse: `'self'` does not cover
-`localhost:5173` framing `localhost:3000`, but the default list now does.
+app has the same requirement in reverse: `'self'` does not cover a page on
+`localhost:5173` embedding `localhost:3000`, but the default list now does.
 
 The demo page takes its XML from a URL, from a paste, or from a picker listing
 the `.fdt` files in the project its credentials point at, which fills the id,
@@ -895,6 +1041,15 @@ whatever that template's scope allows. The picker is demo scaffolding standing
 in for a host's own template store — the widget itself only ever sees the XML
 the page hands it.
 
+It also plays the host half of
+[custom metadata](#custom-metadata-fields). The panel carries a switch and an
+editable JSON model — sample fields to start from, and add whatever of your own
+you like. Each field takes an optional `value`, which never reaches the editor:
+the page substitutes it into the render query for any variable bound to that
+field, on the way in and again on the way out, and logs each substitution. That
+is exactly the work a real integration does, so binding a variable to `sku` and
+reloading shows the host's SKU on the canvas rather than the variable's default.
+
 End-to-end cover for the embed boundary lives in the app repo at
 `e2e/embed-widget.spec.ts` — a cross-origin host page loads the built CDN
 bundle, pulls template XML from its own API and gets the edit back. It needs the
@@ -907,7 +1062,7 @@ yarn build && yarn start
 yarn test:e2e:embed
 ```
 
-The postMessage protocol lives in `src/protocol.ts` and is shared with the app
+The host↔app protocol lives in `src/protocol.ts` and is shared with the app
 via the `./protocol` export, so the two sides cannot drift. Message *values* are
 wire format: never change an existing string, only add new messages, so an older
 widget keeps working against a newer app deployment and vice versa.
@@ -926,7 +1081,7 @@ npm publish, git commit + tag + push. It needs a `.env.local` in this package:
 ```env
 FILEROBOT_CDN_TOKEN=scaleflex
 FILEROBOT_CDN_SECU=<secu key>
-FILEROBOT_CDN_FOLDER=/plugins/scaleflex/design-template-builder/{version}/
+FILEROBOT_CDN_FOLDER=/plugins/cloudimage/template-builder/{version}/
 ```
 
 Update [CHANGELOG.md](./CHANGELOG.md) before releasing.

package/dist/dam-store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The `dam-store` save path: upload an edited template to Filerobot so the
+ * CDN can render it.
+ *
+ * A stateless save hands the host raw XML — but the CDN renders only stored
+ * files, so a host that wants render URLs (previews, production banners) needs
+ * a copy in the DAM too. With `dam-store` the element makes that copy itself,
+ * with the same multipart upload the DAM-backed editor uses, and the `save`
+ * event carries the stored file's links next to the raw data.
+ *
+ * The raw `content` remains the host's copy of record: nothing here changes
+ * what the save event has always carried.
+ */
+import type { BuilderContentData } from './protocol';
+export declare const FILEROBOT_API = "https://api.filerobot.com";
+/** Credentials the element already holds; one of sassKey / secTemplate. */
+export interface DamStoreAuth {
+    token: string;
+    sassKey?: string;
+    secTemplate?: string;
+    sessionUuid?: string;
+    companyUuid?: string;
+    projectUuid?: string;
+}
+/** The stored copy's links, carried on the `save` event as `detail.stored`. */
+export interface StoredTemplate {
+    /** DAM file uuid of the stored `.fdt`. */
+    uuid: string;
+    /**
+     * CDN URL of the stored file, with its current `?vh=` cache key — append a
+     * template query to render it. Empty when the file record could not be read
+     * back after the upload (the file is stored regardless).
+     */
+    url: string;
+}
+export interface FileRecord {
+    uuid?: string;
+    name?: string;
+    folder?: {
+        name?: string;
+    };
+    url?: {
+        cdn?: string;
+        public?: string;
+        path?: string;
+    };
+}
+/**
+ * A security template is not a key — it is exchanged for a short-lived sass
+ * key first, the template authenticating its own exchange. Same call the app
+ * and the asset picker make.
+ *
+ * Exported (with `apiHeaders` / `getFileRecord`) for the demo page, which
+ * plays the host half of the same API conversation — one implementation of
+ * the auth rules, not two drifting copies.
+ */
+export declare function resolveKey(auth: DamStoreAuth): Promise<string>;
+/**
+ * Session scope only: a minted key carries its own, and pairing it with a
+ * session's uuids would mix one mode's key with the other mode's scope.
+ */
+export declare function apiHeaders(auth: DamStoreAuth, key: string): Record<string, string>;
+/**
+ * Whether a template id plausibly names a DAM file (hex-and-dashes uuid).
+ * Opaque host ids ('demo-1', 'sample-spring-banner') never do — looking them
+ * up would waste a round trip per save and couple every save to whichever
+ * status the API happens to answer a malformed id with.
+ */
+export declare function looksLikeDamFileUuid(id: string): boolean;
+/**
+ * One file's record. `null` means the identifier names nothing — a 404/gone,
+ * a 4xx rejecting the id itself, or the API's not-found envelope — all normal
+ * answers here. What THROWS is a failure to answer (auth, rate limit, 5xx,
+ * network): collapsing those into null would make a transient blip read as
+ * "file gone", and the callers act on that — re-homing an existing template
+ * into the fallback folder as a duplicate, or failing an unchanged re-save.
+ */
+export declare function getFileRecord(auth: DamStoreAuth, key: string, uuid: string): Promise<FileRecord | null>;
+/**
+ * Store one save in the DAM and return the stored copy's links.
+ *
+ * Uploads into the folder the file this template is already stored as lives
+ * in — the host's `templateId` when it names a DAM file, else `knownUuid`
+ * (the copy a previous save in this session made; hosts persist `stored.uuid`
+ * rather than echoing it into `template-id`, which would reload the editor) —
+ * so same name + folder makes the backend version the template in place. New
+ * templates land in `fallbackFolder`. Unchanged content resolves to the
+ * already-stored file rather than failing. Throws with a human-readable
+ * message when the copy could not be made; the caller decides what a save
+ * without a stored copy means.
+ */
+export declare function storeTemplateInDam(data: BuilderContentData, auth: DamStoreAuth, fallbackFolder: string, knownUuid?: string): Promise<StoredTemplate>;

package/dist/define.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./template-builder-CK2Zlo7E.cjs");typeof customElements<"u"&&!customElements.get("sfx-template-builder")&&customElements.define("sfx-template-builder",e.SfxTemplateBuilder);exports.SfxTemplateBuilder=e.SfxTemplateBuilder;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./template-builder-Byqg1q93.cjs");typeof customElements<"u"&&!customElements.get("sfx-template-builder")&&customElements.define("sfx-template-builder",e.SfxTemplateBuilder);exports.SfxTemplateBuilder=e.SfxTemplateBuilder;
 //# sourceMappingURL=define.cjs.map

package/dist/define.js

@@ -1,4 +1,4 @@
-import { S as e } from "./template-builder-De0hRO4s.js";
+import { S as e } from "./template-builder-B9Cwo_Q-.js";
 typeof customElements < "u" && !customElements.get("sfx-template-builder") && customElements.define("sfx-template-builder", e);
 export {
   e as SfxTemplateBuilder

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const E=require("./template-builder-CK2Zlo7E.cjs");exports.AUTH_MODES=E.AUTH_MODES;exports.BLANK_TEMPLATE_XML=E.BLANK_TEMPLATE_XML;exports.BRAND_COLOR_PATTERN=E.BRAND_COLOR_PATTERN;exports.BUILDER_CLOSE=E.BUILDER_CLOSE;exports.BUILDER_CONTENT=E.BUILDER_CONTENT;exports.BUILDER_CONTENT_REQUEST=E.BUILDER_CONTENT_REQUEST;exports.BUILDER_DIRTY=E.BUILDER_DIRTY;exports.BUILDER_ERROR=E.BUILDER_ERROR;exports.BUILDER_OPEN=E.BUILDER_OPEN;exports.BUILDER_READY=E.BUILDER_READY;exports.BUILDER_SAVE=E.BUILDER_SAVE;exports.EMBED_PARAMS=E.EMBED_PARAMS;exports.EMBED_ROUTE=E.EMBED_ROUTE;exports.HOST_LOAD=E.HOST_LOAD;exports.HOST_SAVED=E.HOST_SAVED;exports.PROTOCOL_VERSION=E.PROTOCOL_VERSION;exports.SfxTemplateBuilder=E.SfxTemplateBuilder;exports.builderRoute=E.builderRoute;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const E=require("./template-builder-Byqg1q93.cjs");exports.AUTH_MODES=E.AUTH_MODES;exports.BLANK_TEMPLATE_XML=E.BLANK_TEMPLATE_XML;exports.BRAND_COLOR_PATTERN=E.BRAND_COLOR_PATTERN;exports.BUILDER_CLOSE=E.BUILDER_CLOSE;exports.BUILDER_CONTENT=E.BUILDER_CONTENT;exports.BUILDER_CONTENT_REQUEST=E.BUILDER_CONTENT_REQUEST;exports.BUILDER_DIRTY=E.BUILDER_DIRTY;exports.BUILDER_ERROR=E.BUILDER_ERROR;exports.BUILDER_OPEN=E.BUILDER_OPEN;exports.BUILDER_READY=E.BUILDER_READY;exports.BUILDER_SAVE=E.BUILDER_SAVE;exports.EMBED_PARAMS=E.EMBED_PARAMS;exports.EMBED_ROUTE=E.EMBED_ROUTE;exports.HOST_CONFIG=E.HOST_CONFIG;exports.HOST_LOAD=E.HOST_LOAD;exports.HOST_SAVED=E.HOST_SAVED;exports.PROTOCOL_VERSION=E.PROTOCOL_VERSION;exports.SfxTemplateBuilder=E.SfxTemplateBuilder;exports.builderRoute=E.builderRoute;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { SfxTemplateBuilder, type TemplateBuilderStatus, type TemplateBuilderEventMap, type TemplateBuilderSaveDetail, } from './template-builder';
+export { SfxTemplateBuilder, type TemplateBuilderStatus, type TemplateBuilderEventMap, type TemplateBuilderSaveDetail, type StoredTemplate, type DamStoreAuth, } from './template-builder';
 export * from './protocol';

package/dist/index.js

@@ -1,22 +1,23 @@
-import { A as a, B as _, a as s, b as D, c as O, d as T, e as L, f as B, g as A, h as S, i as U, E as I, j as N, H as e, k as M, P, S as C, l } from "./template-builder-De0hRO4s.js";
+import { A as a, B as _, a as s, b as O, c as T, d as D, e as L, f as B, g as A, h as S, i as I, E as U, j as N, H as e, k as C, l as M, P, S as H, m as l } from "./template-builder-B9Cwo_Q-.js";
 export {
   a as AUTH_MODES,
   _ as BLANK_TEMPLATE_XML,
   s as BRAND_COLOR_PATTERN,
-  D as BUILDER_CLOSE,
-  O as BUILDER_CONTENT,
-  T as BUILDER_CONTENT_REQUEST,
+  O as BUILDER_CLOSE,
+  T as BUILDER_CONTENT,
+  D as BUILDER_CONTENT_REQUEST,
   L as BUILDER_DIRTY,
   B as BUILDER_ERROR,
   A as BUILDER_OPEN,
   S as BUILDER_READY,
-  U as BUILDER_SAVE,
-  I as EMBED_PARAMS,
+  I as BUILDER_SAVE,
+  U as EMBED_PARAMS,
   N as EMBED_ROUTE,
-  e as HOST_LOAD,
+  e as HOST_CONFIG,
+  C as HOST_LOAD,
   M as HOST_SAVED,
   P as PROTOCOL_VERSION,
-  C as SfxTemplateBuilder,
+  H as SfxTemplateBuilder,
   l as builderRoute
 };
 //# sourceMappingURL=index.js.map