@scaleflex/template-builder 0.4.1 → 0.4.2

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

@@ -12,7 +12,7 @@ metadata:
   - design-templates
   - web-component
   status: ready
-  version: 1
+  version: 2
 ---
 
 # Scaleflex Template Builder Integration Skill
@@ -24,6 +24,10 @@ metadata:
 - User asks how to use `@scaleflex/template-builder` in their project
 - User wants a banner / creative editor backed by Scaleflex rendering
 
+A complete working React host (gallery, save round trip, live render
+preview) is published at <https://stackblitz.com/edit/sotacrwx> — read its
+`App.tsx` for the whole contract in one file.
+
 ## Step 1 — Decide who stores the template
 
 This is the first question, and it changes everything downstream. Ask if it is
@@ -43,7 +47,7 @@ storage and does not want to map them onto Scaleflex tenants. Pick
 Statelessness applies to the **document only**. The editor still needs an
 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).
+credential (Step 8).
 
 ## Step 2 — Detect the target framework
 
@@ -213,7 +217,46 @@ try {
 
 The React wrapper does this from what `onSave` returns or throws.
 
-## Step 6 — Guard against losing edits
+## Step 6 — Render links and previews (optional): `dam-store`
+
+The CDN renders only files it stores, so a stateless host that wants image
+URLs out of its templates (previews, production banners) needs a copy in
+Filerobot too. Set `dam-store` and the element uploads that copy itself on
+every save, before the `save` event fires — the host writes no upload code:
+
+```html
+<sfx-template-builder stateless dam-store store-folder="/my-app" …>
+```
+
+```js
+builder.addEventListener('save', (e) => {
+  const { content, templateQuery, stored, storeError } = e.detail
+  // stored = { uuid, url } — append templateQuery to url and it IS an image:
+  //   <img src=`${stored.url}&${templateQuery}&force_format=png`>
+  // storeError replaces stored when the copy failed; the raw content
+  // arrives either way — whether that fails the save is your confirmSave call.
+})
+```
+
+Wiring rules that matter:
+
+- **Branch on the detail** (`'stored' in e.detail || 'storeError' in e.detail`),
+  never on the live `damStore` property — saves arrive from a serialized
+  upload queue and the property can change before a queued event lands.
+- **Persist `stored.uuid` and pass it back as `stored-uuid` / `storedUuid`
+  (or the `storedUuid` field of `load()`) when reopening the template.** The
+  element's memory of its copy dies with the page; the seed is what lets a
+  re-save version the existing file in place instead of erroring on
+  unchanged content. Do NOT echo the uuid into `template-id` — an id change
+  deliberately reloads the editor.
+- **A save can arrive after `close`** when its upload is still in flight —
+  keep the `save` listener attached until it does. Removing the element from
+  the DOM flushes pending saves to still-attached listeners immediately.
+- The credential needs **upload rights**, or every save reports `storeError`.
+- `store-folder` names where templates with no existing DAM file land; an
+  existing file's own folder always wins.
+
+## Step 7 — Guard against losing edits
 
 Assigning a new `content` / `templateId` / `templateName` / `templateQuery`
 reloads the editor and
@@ -229,7 +272,7 @@ builder.addEventListener('dirtychange', (e) => {
 Re-assigning an identical template is a no-op, so an unrelated re-render cannot
 destroy work by accident.
 
-## Step 7 — Authentication
+## Step 8 — Authentication
 
 Two credentials work. Both are minted **server-side** and injected into the
 page; neither belongs in a public bundle.
@@ -278,7 +321,7 @@ server-side, so it authenticates on the handed-over credential and returns
 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)
+## Step 9 — Register the embedding origin (required)
 
 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.
@@ -288,7 +331,7 @@ This is baked in at build time, so it needs a redeploy.
 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)
+## Step 10 — Theming (optional)
 
 ```html
 <sfx-template-builder brand-color="#FF6600" theme="dark" ...>
@@ -312,7 +355,7 @@ template document.
 | `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) |
+| `sec-template` / `secTemplate` | guest auth | Security-template key, instead of sass key + session uuid. Stateless only (Step 8) |
 | `company-uuid`, `project-uuid` | no | Company / project scoping (session auth only) |
 | `template-id` / `templateId` | no | DAM: the file uuid. Stateless: opaque host id |
 | `mode` | no | `inline` (default) or `modal` (starts closed — call `open()`) |
@@ -321,7 +364,12 @@ template document.
 | `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 |
+| `dam-store` / `damStore` | no | Stateless: store each save in Filerobot too; the `save` detail gains `stored: { uuid, url }` or `storeError` (Step 6) |
+| `store-folder` / `storeFolder` | no | `dam-store`: folder for templates with no existing DAM file (default `/`) |
+| `stored-uuid` / `storedUuid` | no | `dam-store`: the persisted `stored.uuid`, passed back so re-saves version the existing copy across reloads (Step 6) |
+| `custom-metadata` / `customMetadata` | no | Metadata model offered as the **Custom metadata** value source: `[{ key, title?, group? }]` — names only, values go into the render query as `$slug=value` |
+| `custom-metadata-label` / `customMetadataLabel` | no | Renames that value source in the editor's UI (wording only) |
+| `brand-color`, `theme` | no | See Step 10 |
 | `ready-timeout` / `readyTimeout` | no | Ms before `handshake-timeout` (default 20000) |
 
 ## Events Reference
@@ -330,26 +378,27 @@ template document.
 |---|---|
 | `ready` | — (editor mounted, auth valid) |
 | `open` | — |
-| `save` | `{ uuid, name }` (DAM) or `{ templateId, content, name, templateQuery }` (stateless) |
+| `save` | `{ uuid, name }` (DAM) or `{ templateId, content, name, templateQuery }` (stateless; under `dam-store` also `stored: { uuid, url }` or `storeError`) |
 | `dirtychange` | `{ isDirty }` (stateless) |
-| `close` | — (user left the editor, or it unmounted) |
+| `close` | — (user left the editor, or it unmounted). A `dam-store` save whose upload is still in flight emits **after** `close` — keep listening |
 | `error` | `{ code, message? }` |
 
 `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.
+`dam-store`, `stored-uuid` and `custom-metadata-label` need bundle/package
+**0.4.0+** — an older pinned bundle silently ignores the attributes. Check
+the CHANGELOG against what the host pins.
 
 ## Public Methods
 
-`open(templateId?)`, `close()`, `load({ content, templateId?, name? })`,
-`createNew({ templateId?, name? })`, `confirmSave(ok, message?)`. Read-only:
-`status`, `isDirty`.
+`open(templateId?)`, `close()`,
+`load({ content, templateId?, name?, templateQuery?, storedUuid? })`
+(omitting `storedUuid` clears the seed — it belongs to the document),
+`createNew({ templateId?, name? })`, `confirmSave(ok, message?)`, and
+`flushPendingSaves(reason?)` (only for framework wrappers that detach
+listeners without removing the element; the React wrapper calls it itself).
+Read-only: `status`, `isDirty`.
 
 In React these are reached through a forwarded ref — **required for
 `mode="modal"`**, which renders nothing until `open()` is called:
@@ -393,11 +442,11 @@ ignored; and `layout` / `locale` / `force_format` are reserved slugs.
 
 | Symptom | Cause |
 |---|---|
-| `error` code `handshake-timeout`, nothing rendered | Host origin not in the deployment's embedding allowlist (Step 8), or third-party cookies blocked |
+| `error` code `handshake-timeout`, nothing rendered | Host origin not in the deployment's embedding allowlist (Step 9), 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) |
-| Metadata / regional / branding panels empty | Expected under `sec-template` — those come from the Hub project (Step 7) |
+| `error` code `invalid-config` | `sec-template` without `stateless` (Step 8) |
+| Metadata / regional / branding panels empty | Expected under `sec-template` — those come from the Hub project (Step 8) |
 | Nothing renders, no events | `inline` mode inside a zero-height parent — size the element |
 | Modal never appears | `open()` never called; in React that needs a ref |
 | Saves look successful but nothing is stored | `confirmSave(false)` not wired (Step 5) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scaleflex/template-builder",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Embeddable web component (<sfx-template-builder>) for the Filerobot design-templates builder",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",