@scaleflex/template-builder 0.1.1 → 0.4.0

package/.claude/skills/integrate-template-builder/SKILL.md

@@ -8,7 +8,6 @@ metadata:
   category: integration
   tags:
   - scaleflex
-  - filerobot
   - template-builder
   - design-templates
   - web-component
@@ -23,7 +22,7 @@ metadata:
 - User says "add the template builder", "embed the design template editor",
   "let users edit templates in our app"
 - User asks how to use `@scaleflex/template-builder` in their project
-- User wants a banner / creative editor backed by Filerobot rendering
+- User wants a banner / creative editor backed by Scaleflex rendering
 
 ## Step 1 — Decide who stores the template
 
@@ -32,18 +31,19 @@ not already clear from the project.
 
 | | **DAM-backed** (default) | **Stateless** |
 |---|---|---|
-| Template lives in | Filerobot, as a `.fdt` file | The host's own database |
-| `template-id` is | a Filerobot file uuid | any string the host chooses |
+| Template lives in | Scaleflex, as a `.fdt` file | The host's own database |
+| `template-id` is | a DAM file uuid | any string the host chooses |
 | Save does | uploads a new version, returns `{ uuid }` | hands back `{ content }` for the host to store |
 | Needs per-user Scaleflex identities | yes | no — one service tenant is enough |
 
 Pick **stateless** when the host already has its own users, permissions and
 storage and does not want to map them onto Scaleflex tenants. Pick
-**DAM-backed** when templates are a Filerobot asset like any other.
+**DAM-backed** when templates are a Scaleflex asset like any other.
 
 Statelessness applies to the **document only**. The editor still needs an
-authenticated Filerobot tenant for server-side text rendering, custom fonts,
-asset browsing, and metadata variables.
+authenticated Scaleflex tenant for server-side text rendering, custom fonts,
+asset browsing, and metadata variables — so a stateless embed still needs a
+credential (Step 7).
 
 ## Step 2 — Detect the target framework
 
@@ -61,7 +61,7 @@ npm i @scaleflex/template-builder
 Or via CDN (self-registering, Lit bundled in — pin the major):
 
 ```html
-<script type="module" src="https://cdn.scaleflex.com/plugins/scaleflex/template-builder/0.1.0/template-builder.min.js"></script>
+<script type="module" src="https://cdn.cloudimage.io/template-builder/0.4.0/template-builder.min.js"></script>
 ```
 
 **SSR caution:** the element extends `HTMLElement`, so importing `.`,
@@ -82,7 +82,7 @@ in, take the edited XML back out.**
 <sfx-template-builder
   stateless
   base-url="https://<deployment>"
-  token="FILEROBOT_TOKEN"
+  token="PROJECT_TOKEN"
   sass-key="SASS_KEY"
   session-uuid="SESSION_UUID"
   style="display:block;height:800px"
@@ -144,15 +144,48 @@ import { TemplateBuilder } from '@scaleflex/template-builder/react'
 />
 ```
 
+### Stateless — a template that does not exist yet
+
+A host whose user is creating their first template has no XML to pass in, and
+should not have to author any. Set `new-template` instead of `content` and the
+widget supplies the empty document:
+
+```html
+<sfx-template-builder stateless new-template template-name="Untitled" …>
+```
+
+```js
+builder.createNew({ templateId: 'your-own-id-43', name: 'Untitled' })
+```
+
+```tsx
+<TemplateBuilder stateless newTemplate templateName="Untitled" … />
+```
+
+The editor opens on its empty state, the user adds the first layout (canvas
+size, background, preset), and the first `save` hands back a complete `.fdt`
+document — store that and every later open is the ordinary load flow. Save is
+refused until a layout exists.
+
+- `templateId` is optional; without one the `save` payload just arrives without
+  an id, and the host allocates one when storing.
+- `templateQuery` stays empty — a new document has no layouts or variables for
+  a query to select. It comes back on the first save.
+- `content` wins when both are set, so one element can serve both cases.
+- Empty `content` alone does **not** start a blank template: it means the host
+  is still fetching, and the editor keeps waiting. Only the flag changes that.
+- For a house-style starting point (standard canvas, locked logo layer), pass
+  it as ordinary `content` — a starter template is just a template.
+
 ### DAM-backed
 
-`template-id` is a Filerobot file uuid; omit it to open the new-template flow.
+`template-id` is a DAM file uuid; omit it to open the new-template flow.
 The app loads and saves the file itself.
 
 ```html
 <sfx-template-builder
   base-url="https://<deployment>"
-  token="FILEROBOT_TOKEN"
+  token="PROJECT_TOKEN"
   sass-key="SASS_KEY"
   session-uuid="SESSION_UUID"
   template-id="TEMPLATE_UUID"
@@ -164,8 +197,8 @@ The app loads and saves the file itself.
 
 ## Step 5 — Handle the save outcome (stateless only)
 
-The editor clears its unsaved-changes state as soon as it posts `save`, because
-a delivered postMessage says nothing about whether the host stored anything.
+The editor clears its unsaved-changes state as soon as it emits `save`, because
+receiving the event says nothing about whether the host stored anything.
 **Call `confirmSave(false)` when your write fails**, or a failed save silently
 looks successful and the user loses work:
 
@@ -211,7 +244,7 @@ it when the host has no Scaleflex identity to hand over per user:
 ```html
 <sfx-template-builder
   base-url="https://<deployment>"
-  token="FILEROBOT_TOKEN"
+  token="PROJECT_TOKEN"
   sec-template="SEC_TEMPLATE_KEY"
   stateless
 ></sfx-template-builder>
@@ -232,15 +265,28 @@ What it costs:
 In stateless mode a single service tenant is usually right either way: one
 machine credential, with all per-user permission logic staying in the host app.
 
+**If asked why a stateless embed needs a credential at all** — because the
+preview is not drawn by the browser. A `.fdt` is rendered server-side with
+ImageMagick when its CDN URL is requested, and browser text APIs cannot
+reproduce that layout (kerning, letter spacing, wrapping, baselines,
+antialiasing differ per browser and from the export), so the editor rasterizes
+every text and shape layer through the same engine via
+`POST /api/render-layers` on the `base-url` deployment — batched, debounced,
+supersampled 3×, composited with CSS. That endpoint fetches fonts and images
+server-side, so it authenticates on the handed-over credential and returns
+`401` without one: no credential, no visible text or shape layers. The security
+template is what authorizes it when there is no Hub session. Full explanation:
+*Why the editor still calls a server* in the README.
+
 ## Step 8 — Register the embedding origin (required)
 
-The host page's origin must be in the deployment's `frame-ancestors` allowlist,
-via `NEXT_PUBLIC_TRUSTED_HUB_ORIGINS` on the `design-templates-app` deployment.
+The host page's origin must be in the deployment's embedding allowlist, via
+`NEXT_PUBLIC_TRUSTED_HUB_ORIGINS` on the `design-templates-app` deployment.
 This is baked in at build time, so it needs a redeploy.
 
-**If this is missed**, the browser refuses to render the iframe and the widget
-reports `error` with code `handshake-timeout`. That is the single most common
-first-integration failure — check it before anything else.
+**If this is missed**, the browser refuses to load the editor on the host page
+and the widget reports `error` with code `handshake-timeout`. That is the
+single most common first-integration failure — check it before anything else.
 
 ## Step 9 — Theming (optional)
 
@@ -263,15 +309,16 @@ template document.
 | 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 | Security-template key, instead of sass key + session uuid. Stateless only (Step 7) |
 | `company-uuid`, `project-uuid` | no | Company / project scoping (session auth only) |
-| `template-id` / `templateId` | no | DAM: Filerobot uuid. Stateless: opaque host id |
+| `template-id` / `templateId` | no | DAM: the file uuid. Stateless: opaque host id |
 | `mode` | no | `inline` (default) or `modal` (starts closed — call `open()`) |
-| `stateless` | no | Host owns the document; requires `content` |
+| `stateless` | no | Host owns the document; requires `content`, or `new-template` |
 | `content` (property only) | stateless | Template as `.fdt` XML |
+| `new-template` / `newTemplate` | no | Stateless: open on a new, empty template — the widget supplies the blank document. Ignored when `content` is set |
 | `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. |
 | `brand-color`, `theme` | no | See Step 9 |
@@ -291,10 +338,18 @@ template document.
 `error` codes: `auth`, `invalid-content`, `invalid-config`,
 `handshake-timeout`, `invalid-base-url`, `unknown`.
 
+Post-0.3.0 additions (check the CHANGELOG against your pinned bundle):
+`custom-metadata-label` renames the "Custom metadata" value source in the
+editor's UI (wording only); `dam-store` makes the element store each stateless
+save in Filerobot and adds `stored: { uuid, url }` (or `storeError`) to the
+`save` detail — `url` + `templateQuery` is a render URL, and `store-folder`
+names where templates with no existing DAM file land.
+
 ## Public Methods
 
 `open(templateId?)`, `close()`, `load({ content, templateId?, name? })`,
-`confirmSave(ok, message?)`. Read-only: `status`, `isDirty`.
+`createNew({ templateId?, name? })`, `confirmSave(ok, message?)`. Read-only:
+`status`, `isDirty`.
 
 In React these are reached through a forwarded ref — **required for
 `mode="modal"`**, which renders nothing until `open()` is called:
@@ -338,7 +393,7 @@ ignored; and `layout` / `locale` / `force_format` are reserved slugs.
 
 | Symptom | Cause |
 |---|---|
-| `error` code `handshake-timeout`, blank frame | Host origin not in `frame-ancestors` (Step 8), or third-party cookies blocked |
+| `error` code `handshake-timeout`, nothing rendered | Host origin not in the deployment's embedding allowlist (Step 8), or third-party cookies blocked |
 | `error` code `auth` | Bad/expired session credentials, a rejected security template, or cookies blocked |
 | `error` code `invalid-content` | The `content` handed over is not parseable `.fdt` XML |
 | `error` code `invalid-config` | `sec-template` without `stateless` (Step 7) |

package/CHANGELOG.md

@@ -8,15 +8,201 @@ Protocol message *values* are wire format: an existing string is never changed,
 only new messages added, so an older widget keeps working against a newer app
 deployment and vice versa.
 
+## [Unreleased]
+
+## [0.4.0] - 2026-08-26
+
+### Added
+
+- `stored-uuid` attribute / `storedUuid` prop (and a `storedUuid` field on
+  `load()`) — seeds the element's `dam-store` memory with the copy a document
+  already has, so re-saves after a page reload resolve to (and version) the
+  existing file instead of reporting a spurious `storeError` on unchanged
+  content or starting a fresh file. Per-document: `load()` without it clears
+  the seed, `createNew()` always does.
+- `flushPendingSaves()` public method — emits any `dam-store` saves still
+  waiting on their upload, raw content with `storeError` in place of the
+  links. For framework wrappers that unsubscribe their listeners before the
+  element leaves the DOM; the React wrapper calls it from its cleanup, so a
+  host unmounting `<TemplateBuilder>` mid-upload no longer loses the save.
+
+### Changed
+
+- Closing the editor no longer flushes a `dam-store` upload still in flight
+  into a `storeError`: the element outlives a close (inline keeps rendering,
+  modal drops only its overlay), so the save emits its real outcome when the
+  copy lands — possibly after the `close` event. Element removal still
+  flushes immediately.
+- `dam-store` filenames: the element reuses its known copy's own filename so
+  versioning-in-place keeps matching; otherwise the name carries a
+  deterministic hash of the host's template id — the same document lands on
+  the same DAM file across page reloads (no fork per session, no stored-uuid
+  seed required), while two documents sharing a display name ("Untitled")
+  never collide. Only an id-less document falls back to a per-page unique
+  suffix.
+- `dam-store` document memory is now epoch-based and validated at read time:
+  the document epoch advances only when a genuinely different document ships,
+  never on iframe changes — a modal close or theme swap mid-save no longer
+  forgets the stored copy, a host echo followed by an in-place remount no
+  longer orphans it, and a late-landing upload is recorded under its own
+  document's epoch so it can never masquerade as another document's copy.
+- `dam-store` no longer looks up opaque (non-uuid-shaped) template ids
+  against the files API — one round trip saved per save, and the store no
+  longer depends on how the API answers a malformed id. The transient-failure
+  rule is role-aware: the required folder anchor still fails the copy, but a
+  transient failure of the optional freshness lookup no longer fails a save
+  the other anchor can carry.
+- An unchanged-content conflict with no anchor in hand (first save after a
+  reload without the stored-uuid seed) now resolves itself by finding the
+  document's own earlier copy by its deterministic filename; a genuinely
+  foreign duplicate reports an actionable error naming `stored-uuid` as the
+  fix.
+- Removing the element flushes pending saves one task later, skipped if the
+  element is reconnected — reparenting the mounted widget (e.g. a fullscreen
+  toggle) no longer reports a false `storeError` for an upload that lands
+  fine.
+- Demo page: the Filerobot API helpers (key exchange, scope headers, file
+  lookup) are imported from `dam-store.ts` instead of being hand copies.
+
+### Fixed
+
+- A host echoing the full save detail back into the props (content + name +
+  `templateQuery` — the documented controlled pattern) no longer triggers a
+  HOST_LOAD that reloads the editor and wipes undo history: the element now
+  also accepts the save's own identity, whose query nearly always differs
+  from the one the template was loaded with.
+- A transient Filerobot failure (5xx, 429, auth, network) during the
+  folder lookup no longer reads as "file does not exist" — which silently
+  re-homed an existing template into the fallback folder as a brand-new
+  file, or failed an unchanged re-save with a spurious `storeError`. Only a
+  clean 404 means missing; everything else fails the copy explicitly, and
+  the post-upload record read-back stays best-effort.
+- `dam-store` uploads now declare the template MIME type
+  (`text/xml+sfxtemplate`) the app's own uploads use, instead of plain
+  `text/xml`.
+- A queued `dam-store` upload captures `store-folder` and the credentials at
+  save time — an in-place document swap while a save is still queued no
+  longer re-targets that save's upload to the new document's folder or
+  tenant.
+- A `dam-store` upload finishing after the host swapped documents in place
+  (new `content`/`templateId` on the mounted element) no longer records the
+  old document's uuid into the new document's session memory — a follow-up
+  save can no longer version the wrong DAM file.
+- React wrapper: event listeners are now attached once per element and read
+  the latest callbacks at event time, instead of being re-bound on every
+  handler identity change. The unmount-time flush is guarded, so a page
+  whose older CDN bundle registered the element first degrades silently
+  instead of throwing from the effect cleanup.
+- Demo page: the save handler now detects a `dam-store` save from the event
+  detail itself (`stored`/`storeError` present) rather than the live
+  `damStore` property, which a "Load template" inside the upload window can
+  rewrite before the serialized save event arrives.
+- Demo sample template: the `$headline$` placeholder now renders — the
+  variable holds its value in the `default=` attribute as
+  `type="text_placeholder"`, the shape the app's parser actually reads
+  (CDATA text on a `type="text"` variable is ignored, leaving the layer
+  blank).
+
+- `dam-store` attribute / `damStore` prop (stateless only) — the element
+  stores each save in Filerobot itself, with the same multipart upload the
+  DAM-backed editor makes, before emitting `save`. The detail then carries
+  `stored: { uuid, url }` (the DAM copy's uuid and its CDN URL with a fresh
+  `?vh=`) next to the raw `content` — append the `templateQuery` to `url` and
+  it is a render. A failed copy emits `storeError` instead; the raw data
+  arrives either way, and the host decides via the save ack whether that
+  fails the save. `store-folder` / `storeFolder` names the folder for
+  templates whose id matches no existing DAM file (an existing file's own
+  folder always wins, so same-name saves version in place). The stored
+  `template_query` metadata has custom-metadata-bound values stripped —
+  record-agnostic, like the editor's own stores. Rapid saves are serialized
+  (events and acks keep post order); element removal mid-upload flushes the
+  pending save immediately — raw content with `storeError`, never a dropped
+  save (a mere close lets the upload finish and the save emit its real
+  outcome); and the element remembers the copy it last made, so unchanged
+  re-saves resolve to it instead of erroring even when the host's own
+  template id is opaque.
+- Demo page: the store checkbox now drives `dam-store` (on by default) — the
+  page writes no upload code; it reads `stored` off the save event, logs the
+  links, and the Template id / .fdt URL fields follow the stored file so the
+  preview always renders what was just saved. A failed copy fails the save
+  (`confirmSave(false)`).
+- Demo page: a **Show preview** button under the template-query field. It
+  renders the stored `.fdt` with the query applied and the host's
+  custom-metadata values substituted — the same image URL a host page would
+  embed. The file's CDN URL is filled in by a library pick, resolved from the
+  Template id via the API when the field is left empty (dam-store saves also
+  fill it), or pasted by hand. Renders the stored file, not unsaved local
+  edits.
+
+- `custom-metadata-label` attribute / `customMetadataLabel` prop — renames the
+  **Custom metadata** value source in the editor's UI (source dropdowns and the
+  properties-panel section), e.g. to `External metadata`. Wording only: the
+  saved template carries the same `custom_ckey` binding either way, and an
+  empty value keeps the editor's default label. Requires an app deployment
+  that understands `customMetadataLabel` in `HOST_CONFIG`; an older app
+  ignores it.
+
+## [0.3.0] - 2026-08-18
+
+### Added
+
+- `custom-metadata` attribute / `customMetadata` prop — a metadata model
+  (`[{ key, title?, group? }]`) offered in the editor as a third **Custom
+  metadata** value source, so authors 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 editor resolves nothing against it. The binding is saved on the
+  variable as `custom_ckey` while the variable stays `source="URL"`, so the
+  render pipeline is unchanged — you substitute the value with `$slug=value` as
+  you would for free text, and read `custom_ckey` back from the stored `.fdt` to
+  know which field each variable wants. Set no model and the source is not
+  offered. Its main use is `sec-template` / stateless embeds, where the Hub
+  project model — and with it the *File metadata* source — is unavailable.
+  Fields the editor cannot use are dropped rather than breaking the source: no
+  `key`, a duplicate `key`, or a `key` holding a character XML cannot represent
+  (a C0 control, an unpaired surrogate) — the last of which would otherwise make
+  the saved `.fdt` unparseable in its entirety.
+- The demo page plays the host half of it: a switch, an editable JSON model to
+  start from, and an optional `value` per field that the page substitutes into
+  the render query for any variable bound to that field — on load and on save,
+  with each substitution logged. Values never reach the editor.
+- `HOST_CONFIG` message and `CustomMetadataField` / `HostConfigData` protocol
+  types; `PROTOCOL_VERSION` is now 3. Additive: an app deployment that predates
+  it ignores the message, and a host that sends no model gets the previous
+  behaviour exactly. The widget delivers config on the editor's ready signal
+  (so it reaches DAM-backed embeds, which exchange no content messages) and
+  whenever the model changes.
+
+## [0.2.0] - 2026-08-11
+
+### Added
+
+- `new-template` attribute / `newTemplate` prop and `createNew({ templateId?,
+  name? })` — start a template from scratch in stateless mode. The widget
+  supplies the empty document (`BLANK_TEMPLATE_XML`, exported from
+  `./protocol`), so a host with nothing stored yet needs no knowledge of the
+  `.fdt` format: the editor opens on its empty state, the user adds the first
+  layout, and the first `save` hands back a complete document to store.
+  `content` wins when both are set. Empty `content` still means "the host is
+  still fetching" and keeps the editor waiting — only the flag turns that into
+  a blank document.
+
+### Changed
+
+- The demo's Base URL defaults to `https://design-templates.scaleflex.com`
+  instead of `http://localhost:3000`, so the published page is usable without
+  filling a field first. It also logs the full `.fdt` and `templateQuery` to the
+  console at both crossings — going into the editor, and coming back on save —
+  while the on-page panel keeps summarizing.
+
 ## [0.1.1] - 2026-08-10
 
 First published release. `<sfx-template-builder>` custom element, `./react`
-wrapper, `./define` registration, and the v2 postMessage protocol (DAM-backed
-and stateless modes). 0.1.0 was never published.
+wrapper, `./define` registration, and the v2 host protocol (DAM-backed and
+stateless modes). 0.1.0 was never published.
 
 ### Added
 
-- `sec-template` attribute — authenticate with a Filerobot security template
+- `sec-template` attribute — authenticate with a Scaleflex security template
   instead of a Hub session. The app exchanges the key for an access key itself
   and renews it on expiry. Stateless mode only, and Hub-project features
   (metadata fields, regional variants, project branding) come back empty; see
@@ -36,7 +222,7 @@ and stateless modes). 0.1.0 was never published.
   parse, rather than leaving the host on a loading state indefinitely.
 
 - Buildable demo (`build:demo` → `demo-dist/`) and a `release` script wrapping
-  the shared Filerobot CDN release pipeline. The demo fetches its template over
+  the shared Scaleflex CDN release pipeline. The demo fetches its template over
   HTTP from a bundled sample, so the "XML comes from your API, goes in, comes
   back out" round trip is visible end to end with no backend.
 - `LICENSE` (proprietary), shipped in the npm tarball.