@scaleflex/template-builder 0.1.1 → 0.4.0

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>
 
@@ -30,13 +30,17 @@
 - [Quick Start](#quick-start)
   - [Vanilla JS / Web Component](#vanilla-js--web-component)
   - [React](#react)
+  - [Hub session (internal)](#hub-session-internal)
 - [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)
@@ -56,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
@@ -70,30 +74,33 @@ 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.
+- **New templates without the format** — [`new-template`](#starting-a-template-from-scratch)
+  starts an empty document for the user to build; you only ever store what
+  comes back.
 - **Themeable** — one [brand colour](#brand-color) drives the editor's whole
   accent ramp; light, dark, or follow the OS.
 - **Origin-checked both ways** — the widget only accepts messages from the app
   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))
 
@@ -108,7 +115,7 @@ npm i @scaleflex/template-builder
 ### CDN
 
 ```html
-<script type="module" src="https://cdn.scaleflex.com/design-template-builder/0.1.1/template-builder.min.js"></script>
+<script type="module" src="https://cdn.cloudimage.io/template-builder/0.4.0/template-builder.min.js"></script>
 ```
 
 The CDN bundle is self-registering — it defines `<sfx-template-builder>` on
@@ -134,6 +141,15 @@ load, with Lit bundled in. Pin the major version.
 
 ## Quick Start
 
+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
+[Authentication](#authentication) for how to scope one.
+
+The template document stays on your side: you hand the widget its XML, and the
+edit comes back to you on save. That is [stateless](#stateless) mode.
+
 ### Vanilla JS / Web Component
 
 ```html
@@ -143,16 +159,26 @@ load, with Lit bundled in. Pin the major version.
 
 <sfx-template-builder
   base-url="https://<your-design-templates-deployment>"
-  token="FILEROBOT_TOKEN"
-  sass-key="SASS_KEY"
-  session-uuid="SESSION_UUID"
-  template-id="TEMPLATE_UUID"
+  token="PROJECT_TOKEN"
+  sec-template="SEC_TEMPLATE_KEY"
+  stateless
   style="display:block;height:800px"
 ></sfx-template-builder>
 
 <script>
   const builder = document.querySelector('sfx-template-builder')
-  builder.addEventListener('save', (e) => console.log('saved', e.detail)) // { uuid, name }
+
+  // 1 — hand it the template to edit
+  const { content, name } = await fetch(`/api/templates/${id}`).then((r) => r.json())
+  builder.load({ templateId: id, name, content })
+
+  // 2 — take the edit back and store it
+  builder.addEventListener('save', async (e) => {
+    const { templateId, content, name, templateQuery } = e.detail
+    const ok = await saveToYourApi(templateId, { content, name, templateQuery })
+    builder.confirmSave(ok) // false → the editor keeps its unsaved-changes warning
+  })
+
   builder.addEventListener('error', (e) => console.error(e.detail)) // { code, message }
 </script>
 ```
@@ -164,6 +190,38 @@ Size the element yourself — in `inline` mode it fills the box you give it.
 ```tsx
 import { TemplateBuilder } from '@scaleflex/template-builder/react'
 
+<TemplateBuilder
+  stateless
+  baseUrl="https://<deployment>"
+  token={projectToken}
+  secTemplate={secTemplateKey}
+  templateId={id}
+  name={name}
+  content={xml}
+  style={{ height: 800 }}
+  onSave={async (data) => (await saveToYourApi(data)).ok}
+/>
+```
+
+<!-- internal:start -->
+### Hub session (internal)
+
+Scaleflex-side embeds inside the Hub authenticate with a session instead of a
+security template, which unlocks DAM-backed storage and Hub-project features.
+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="PROJECT_TOKEN"
+  sass-key="SASS_KEY"
+  session-uuid="SESSION_UUID"
+  template-id="TEMPLATE_UUID"
+  style="display:block;height:800px"
+></sfx-template-builder>
+```
+
+```tsx
 <TemplateBuilder
   baseUrl="https://<deployment>"
   token={token}
@@ -174,6 +232,7 @@ import { TemplateBuilder } from '@scaleflex/template-builder/react'
   onSave={(data) => console.log(data)}
 />
 ```
+<!-- internal:end -->
 
 ---
 
@@ -181,7 +240,7 @@ import { TemplateBuilder } from '@scaleflex/template-builder/react'
 
 ### 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.
 
@@ -189,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.
 
@@ -203,9 +264,8 @@ point.
 <sfx-template-builder
   stateless
   base-url="https://<deployment>"
-  token="FILEROBOT_TOKEN"
-  sass-key="SASS_KEY"
-  session-uuid="SESSION_UUID"
+  token="PROJECT_TOKEN"
+  sec-template="SEC_TEMPLATE_KEY"
   style="display:block;height:800px"
 ></sfx-template-builder>
 
@@ -218,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 })
@@ -245,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.
 
@@ -270,9 +330,8 @@ function TemplateEditor({ id }: { id: string }) {
     <TemplateBuilder
       stateless
       baseUrl="https://<deployment>"
-      token={token}
-      sassKey={sassKey}
-      sessionUuid={sessionUuid}
+      token={projectToken}
+      secTemplate={secTemplateKey}
       // 2 — pass it in.
       templateId={id}
       content={tpl.content}
@@ -355,9 +414,10 @@ 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 layers are rasterized server-side,
+- **text rendering** — text and shape layers are rasterized server-side (see
+  [the render round-trip](#why-the-editor-still-calls-a-server) below),
 - **fonts** — custom fonts are served from the tenant's `.studio/fonts/`,
 - **asset browsing and upload** — image layers are picked from the DAM,
 - **metadata variables and regional settings**.
@@ -370,12 +430,198 @@ Images referenced by a template may live on your own CDN, but the render
 service only fetches from allowlisted hosts — add yours to the deployment's
 `RENDER_ALLOWED_HOSTS_EXTRA`.
 
+#### Why the editor still calls a server
+
+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 Scaleflex that renders it there — server-side,
+with ImageMagick:
+
+```
+https://<tenant>.filerobot.com/<path>/<template>.fdt?<templateQuery>&force_format=png
+```
+
+The editor's contract is that what you see while editing is what that URL will
+return. That rules out drawing the text in the browser. Line breaking, kerning,
+letter spacing, baseline placement, shrink-to-fit and antialiasing are FreeType
+and ImageMagick behaviours; canvas `fillText` and DOM text go through the
+browser's own shaping and hinting instead, so the same layer lands differently
+in Chrome, Safari and Firefox — and differently from the export in all three. A
+few pixels of drift is enough to move a headline off a product shot. There is
+no JS library that reimplements that layout either: the only faithful
+implementation of ImageMagick's text rendering is ImageMagick.
+
+So the editor does not approximate the export — it runs the same engine.
+Text and shape layers are rasterized by an ImageMagick 7 build hosted in your
+`base-url` deployment (the export pipeline drives ImageMagick 7 from PHP; the
+editor drives a WebAssembly build of it), and each layer comes back as a
+transparent PNG that the canvas positions with CSS:
+
+```
+  browser — the widget                        app deployment (base-url)
+  ────────────────────                        ─────────────────────────
+  edit a text layer
+      │  batched across layers, debounced
+      ├──────  POST /api/render-layers  ─────▶  ImageMagick (WASM)
+      │        layers + fonts + variables       ├─ resolve fonts: bundled,
+      │                                         │  then tenant /.studio/fonts
+      │                                         ├─ draw at 3×, downscale
+      ◀──────  transparent PNG per layer  ─────┘
+      │
+      └─ position / rotate / fade with CSS — no round trip
+```
+
+Consequences you can observe from the outside:
+
+- **Content edits cost a round trip; placement edits do not.** Text, font,
+  weight, colour, alignment, letter spacing and box size re-render. Dragging,
+  rotating and opacity are CSS transforms on the PNG already in the page, so
+  they stay at pointer speed.
+- **Bursts collapse.** Requests are debounced (~300 ms) and batched across
+  layers, and an in-flight batch is aborted when you keep typing — so a
+  sentence typed at speed costs one render, not one per keystroke.
+- **Layers are drawn at 3× and downscaled**, so preview antialiasing matches
+  the export rather than the browser's rasterizer.
+- **Fonts are resolved server-side** against the tenant's `/.studio/fonts`
+  folder and cached there, so the page never downloads a rendering engine or a
+  font binary per weight. Image layers are the exception — they are plain
+  `<img>` elements, drawn by the browser.
+
+**That endpoint is authenticated, and it has to be.** It fetches fonts and
+images by URL on the server's behalf, so it is not open to anonymous callers:
+`POST /api/render-layers` requires the credential the widget handed over, and
+without a valid one it answers `401` and text and shape layers simply never
+appear. The same credential authorizes the font list/upload calls and the asset
+picker.
+
+In DAM-backed mode a Hub session covers that. A stateless embed has no Hub
+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 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
+
+A template your user has not created yet has no XML to pass in, and you should
+not have to author one. In [stateless](#stateless) mode, set `new-template`
+instead of `content` and the widget supplies the empty document itself.
+(DAM-backed mode has its own new-template flow — leave `template-id` empty.)
+
+```html
+<sfx-template-builder
+  stateless
+  new-template
+  template-name="Untitled"
+  base-url="https://<deployment>"
+  token="PROJECT_TOKEN"
+  sec-template="SEC_TEMPLATE_KEY"
+  style="display:block;height:800px"
+></sfx-template-builder>
+```
+
+```js
+// Or imperatively, on an element that is already showing something else.
+builder.createNew({ templateId: 'your-own-id-43', name: 'Untitled' })
+```
+
+```tsx
+<TemplateBuilder stateless newTemplate templateName="Untitled" … />
+```
+
+The editor opens on its empty state — *"No layouts yet. Click + Add to create
+one."* — and the user picks the canvas size, background and preset there. Save
+is refused until at least one layout exists, so the first `save` you receive
+already carries a complete, well-formed `.fdt` document; store it as `content`
+and every later open is the ordinary [load flow](#the-template-comes-from-your-api).
+
+- **`templateId` is optional.** Pass one if your record already exists and you
+  want it echoed back; otherwise the `save` payload simply arrives without an
+  id and you allocate one when you store it.
+- **`templateQuery` stays empty.** A new document has no layouts and no
+  variables, so there is no render for a query to select. You get one back on
+  the first save — persist it then.
+- **`content` wins when both are set,** so a host that renders one element for
+  both cases can simply pass the XML when it has one.
+- **Empty `content` on its own does not start a blank template.** It means "the
+  host has nothing yet" — the editor keeps waiting, which is what lets you
+  mount the builder while your fetch is still in flight. Only `new-template`
+  turns that wait into a document.
+
+Calling `createNew()` again while the blank template is already open does
+nothing: resending would discard whatever the user has built since. Close and
+reopen the editor to genuinely start over.
+
+If you would rather ship your own starting point — a house style, a standard
+canvas size, a locked logo layer — pass it as ordinary `content`. A starter
+template is just a template, and `BLANK_TEMPLATE_XML` is exported from
+`@scaleflex/template-builder/protocol` if you want the empty document as a base.
+
 ### 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) => {
@@ -404,17 +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` |
+| `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) |
@@ -432,18 +684,27 @@ something to hardcode in a public bundle.
 | Metadata fields, regional variants, project branding | yes | **empty** |
 | Rendering, fonts, asset picker | yes | yes, within the template's scope |
 
+<!-- internal:start -->
 #### Hub session
 
 Mint the Hub session **server-side** and inject `session-uuid` / `sass-key` /
 `token` into your page. Issue short-lived per-user sessions; never embed a
 long-lived master credential in client-side code.
+<!-- internal:end -->
 
 #### 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
-all:
+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
+document never leaves your side, the editor rasterizes every text and shape
+layer on the server to stay pixel-identical to the CDN render, and resolves
+fonts and assets from your tenant — all of it authenticated. See
+[why the editor still calls a server](#why-the-editor-still-calls-a-server) for
+what those calls are.
 
 ```html
 <sfx-template-builder
@@ -469,30 +730,108 @@ all:
 The app exchanges the key for a short-lived access key itself and renews it when
 it expires, so the embed does not die mid-session.
 
+**Scoping the template.** Grant it `LIST` on the folders you want browsable,
+plus `LIST` + `UPLOAD` on `/.studio/fonts*` if users are to see or add custom
+fonts — anything the template cannot reach simply isn't there. Prefer a short
+TTL: the app re-exchanges the key when it expires, so a short-lived template
+costs you nothing and limits the blast radius if one leaks.
+
+If the key is rejected — revoked, wrong project token, typo — the widget emits
+`error` with code `auth`.
+
+<!-- internal:start -->
 **What it costs.** A security template authenticates *nobody in particular*: no
 user identity, no Hub project behind it. That has consequences worth knowing
 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).
-- **Its scope is the app's scope.** Grant the template `LIST` on the folders you
-  want browsable, plus `LIST` + `UPLOAD` on `/.studio/fonts*` if users are to
-  see or add custom fonts. Anything it cannot reach simply isn't there.
-- **Prefer short TTLs.** The app re-exchanges on expiry, so a short-lived
-  template costs you nothing but limits the blast radius of a leaked key.
+<!-- internal:end -->
 
-If the key is rejected — revoked, wrong project token, typo — the widget emits
-`error` with code `auth`.
+### 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 and the widget reports `handshake-timeout`.
+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`,
+`https://*.filerobot.com` and `http://localhost:5173` (the demo's dev server)
+out of the box, plus whatever its `NEXT_PUBLIC_TRUSTED_HUB_ORIGINS` names. Your
+own domain has to be added there — the list is baked in at build time, so it
+takes a rebuild of the app, not just a restart.
 
 ### Cookies
 
@@ -506,9 +845,11 @@ 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). |
 
 **Read-only properties:** `status` (`idle` \| `loading` \| `ready` \| `error`),
@@ -524,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. |
@@ -533,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. |
 
@@ -544,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`.
@@ -557,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:
@@ -636,10 +988,12 @@ blocks third-party cookies the editor cannot authenticate and the widget reports
 
 ---
 
+<!-- internal:start -->
 ## Development
 
 ```bash
-yarn dev:demo      # demo site (expects the app on http://localhost:3000)
+yarn dev:demo      # demo site (defaults to the deployed app; point Base URL at
+                   # http://localhost:3000 to drive a local one)
 yarn test          # vitest
 yarn typecheck     # tsc --noEmit
 yarn build         # dist/ — npm artifact (ESM + CJS + types)
@@ -666,7 +1020,18 @@ the README reloads the dev server.
 the folder can be zipped and handed to a client, or dropped behind any static
 host at any path — GitHub Pages, S3, a subdirectory of an existing site. The
 only thing it needs at runtime is a reachable `design-templates-app` for the
-demo page's Base URL field to point at.
+demo page's Base URL field to point at; it defaults to
+`https://design-templates.scaleflex.com`.
+
+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 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,
@@ -676,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
@@ -688,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.
@@ -707,11 +1081,23 @@ 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/template-builder/{version}/
+FILEROBOT_CDN_FOLDER=/plugins/cloudimage/template-builder/{version}/
 ```
 
 Update [CHANGELOG.md](./CHANGELOG.md) before releasing.
 
+`yarn release:demo` publishes the demo site into `<that folder>/demo/`, next to
+the bundle it demonstrates. `yarn release:demo:probe` sends a single file first,
+reporting the content-type the CDN serves it as. The pages are built as
+self-contained HTML with their JS and CSS inlined, because the CDN project
+refuses `.js` uploads.
+
+Note the CDN caches for 24h: re-uploading over a path that has already been
+fetched keeps serving the old copy until it expires. Version folders are the
+way around it — don't overwrite a published one.
+
+<!-- internal:end -->
+
 ---
 
 ## Claude Code Integration