@scaleflex/template-builder 0.1.1 → 0.2.0

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

@@ -43,7 +43,8 @@ storage and does not want to map them onto Scaleflex tenants. Pick
 
 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.
+asset browsing, and metadata variables — so a stateless embed still needs a
+credential (Step 7).
 
 ## Step 2 — Detect the target framework
 
@@ -144,6 +145,39 @@ 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.
@@ -232,6 +266,19 @@ 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,
@@ -270,8 +317,9 @@ template document.
 | `company-uuid`, `project-uuid` | no | Company / project scoping (session auth only) |
 | `template-id` / `templateId` | no | DAM: Filerobot 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 |
@@ -294,7 +342,8 @@ template document.
 ## 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:

package/CHANGELOG.md

@@ -8,6 +8,28 @@ 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.
 
+## [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`

package/README.md

@@ -30,9 +30,11 @@
 - [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)
+  - [Starting a template from scratch](#starting-a-template-from-scratch)
   - [Reporting a failed save](#reporting-a-failed-save)
 - [Configuration](#configuration)
   - [Attributes & properties](#attributes--properties)
@@ -77,6 +79,9 @@ protocol adapter.
   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
@@ -108,7 +113,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.scaleflex.com/design-template-builder/0.2.0/template-builder.min.js"></script>
 ```
 
 The CDN bundle is self-registering — it defines `<sfx-template-builder>` on
@@ -134,6 +139,15 @@ load, with Lit bundled in. Pin the major version.
 
 ## Quick Start
 
+You need two things from your Filerobot 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 +157,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 +188,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="FILEROBOT_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 +230,7 @@ import { TemplateBuilder } from '@scaleflex/template-builder/react'
   onSave={(data) => console.log(data)}
 />
 ```
+<!-- internal:end -->
 
 ---
 
@@ -203,9 +260,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>
 
@@ -270,9 +326,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}
@@ -357,7 +412,8 @@ you navigated away from.
 Statelessness applies to the **document**, not to the infrastructure. The editor
 still needs an authenticated Filerobot 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,6 +426,135 @@ 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 Filerobot 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 — widget iframe                     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 Filerobot at all.
+
+### 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` —
@@ -411,8 +596,9 @@ without it a failed write is invisible to the user.
 | `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` |
 | `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. |
 | `brand-color` / `brandColor` | no | Accent colour for the editor chrome, `#rgb` / `#rrggbb` |
@@ -432,18 +618,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:
+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,6 +664,16 @@ 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:
@@ -479,20 +684,20 @@ before you pick it:
 - **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.
-
-If the key is rejected — revoked, wrong project token, typo — the widget emits
-`error` with code `auth`.
+<!-- internal:end -->
 
 ### 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`.
+iframe — Chrome shows "refused to connect" in place of the editor, 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
 
@@ -509,6 +714,7 @@ without CHIPS support that block third-party cookies will fail with `auth` or
 | `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). |
+| `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`),
@@ -636,10 +842,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 +874,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 frames 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.
 
 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,
@@ -707,11 +926,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/scaleflex/design-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

package/dist/define.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./template-builder-CSyPZni9.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-CK2Zlo7E.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-S33H_d5T.js";
+import { S as e } from "./template-builder-De0hRO4s.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-CSyPZni9.cjs");exports.AUTH_MODES=E.AUTH_MODES;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-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;
 //# sourceMappingURL=index.cjs.map

package/dist/index.js

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

package/dist/protocol.d.ts

@@ -150,6 +150,30 @@ export interface HostLoadMessage {
     type: typeof HOST_LOAD;
     data: HostLoadData;
 }
+/**
+ * An empty `.fdt` document: no layouts, no layers, no variables. What the
+ * widget sends as `HOST_LOAD` content when the host asked for a new template
+ * (`new-template`) instead of supplying one, so starting from scratch costs a
+ * host no knowledge of the template format.
+ *
+ * The editor opens on its empty state — "No layouts yet. Click + Add to create
+ * one." — and the user picks the canvas size there. Save is refused until a
+ * layout exists, and hands back a fully-formed document serialized by the app,
+ * not this skeleton.
+ *
+ * Sent as ordinary `HOST_LOAD` content rather than a new message so it works
+ * against app deployments that predate this widget version: the document is
+ * the whole signal, and every app that can parse a template can parse this.
+ *
+ * `version` tracks the app's `TEMPLATE_VERSION` for the benefit of whoever
+ * reads this next: nothing consumes it. The parser never looks at it, and the
+ * backend never sees this document — the app refuses to save a template with
+ * no layouts, so what reaches the render pipeline was re-serialized by the app
+ * with a layout present. A widget lagging the app by a version still loads.
+ * `design-templates` pins the pair in
+ * `src/lib/xml/__tests__/blank-template.test.ts`.
+ */
+export declare const BLANK_TEMPLATE_XML: string;
 /**
  * Stateless mode only (protocol v2). Reports whether the host managed to
  * persist the content it received in `BUILDER_CONTENT`.

package/dist/react.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react");require("./define.cjs");const h=o.forwardRef(function(y,v){const{className:U,style:b,onReady:c,onOpen:d,onClose:m,onSave:i,onError:p,onDirtyChange:f,...e}=y,l=o.useRef(null);return o.useImperativeHandle(v,()=>l.current,[]),o.useLayoutEffect(()=>{const t=l.current;t&&(t.baseUrl=e.baseUrl,t.token=e.token,t.sassKey=e.sassKey??"",t.sessionUuid=e.sessionUuid??"",t.secTemplate=e.secTemplate??"",t.companyUuid=e.companyUuid??"",t.projectUuid=e.projectUuid??"",t.templateId=e.templateId??"",t.mode=e.mode??"inline",t.stateless=e.stateless??!1,t.templateName=e.templateName??"",t.templateQuery=e.templateQuery??"",t.brandColor=e.brandColor??"",t.theme=e.theme??"",t.content=e.content??"",e.readyTimeout!==void 0&&(t.readyTimeout=e.readyTimeout))},[e.baseUrl,e.token,e.sassKey,e.sessionUuid,e.secTemplate,e.companyUuid,e.projectUuid,e.templateId,e.mode,e.stateless,e.content,e.templateName,e.templateQuery,e.brandColor,e.theme,e.readyTimeout]),o.useLayoutEffect(()=>{const t=l.current;if(!t)return;const u=[],a=(r,s)=>{if(!s)return;const n=(T=>s(T.detail));t.addEventListener(r,n),u.push([r,n])};if(a("ready",c),a("open",d),a("close",m),a("error",p),a("dirtychange",f),i){const r=(s=>{Promise.resolve().then(()=>i(s.detail)).then(n=>t.confirmSave(n!==!1)).catch(n=>{console.error("[sfx-template-builder] onSave failed:",n),t.confirmSave(!1)})});t.addEventListener("save",r),u.push(["save",r])}return()=>{for(const[r,s]of u)t.removeEventListener(r,s)}},[c,d,m,i,p,f]),o.createElement("sfx-template-builder",{ref:l,class:U,style:b})});exports.TemplateBuilder=h;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react");require("./define.cjs");const h=a.forwardRef(function(y,v){const{className:T,style:U,onReady:m,onOpen:c,onClose:d,onSave:i,onError:p,onDirtyChange:f,...e}=y,l=a.useRef(null);return a.useImperativeHandle(v,()=>l.current,[]),a.useLayoutEffect(()=>{const t=l.current;t&&(t.baseUrl=e.baseUrl,t.token=e.token,t.sassKey=e.sassKey??"",t.sessionUuid=e.sessionUuid??"",t.secTemplate=e.secTemplate??"",t.companyUuid=e.companyUuid??"",t.projectUuid=e.projectUuid??"",t.templateId=e.templateId??"",t.mode=e.mode??"inline",t.stateless=e.stateless??!1,t.templateName=e.templateName??"",t.templateQuery=e.templateQuery??"",t.brandColor=e.brandColor??"",t.theme=e.theme??"",t.newTemplate=e.newTemplate??!1,t.content=e.content??"",e.readyTimeout!==void 0&&(t.readyTimeout=e.readyTimeout))},[e.baseUrl,e.token,e.sassKey,e.sessionUuid,e.secTemplate,e.companyUuid,e.projectUuid,e.templateId,e.mode,e.stateless,e.content,e.newTemplate,e.templateName,e.templateQuery,e.brandColor,e.theme,e.readyTimeout]),a.useLayoutEffect(()=>{const t=l.current;if(!t)return;const u=[],o=(s,r)=>{if(!r)return;const n=(b=>r(b.detail));t.addEventListener(s,n),u.push([s,n])};if(o("ready",m),o("open",c),o("close",d),o("error",p),o("dirtychange",f),i){const s=(r=>{Promise.resolve().then(()=>i(r.detail)).then(n=>t.confirmSave(n!==!1)).catch(n=>{console.error("[sfx-template-builder] onSave failed:",n),t.confirmSave(!1)})});t.addEventListener("save",s),u.push(["save",s])}return()=>{for(const[s,r]of u)t.removeEventListener(s,r)}},[m,c,d,i,p,f]),a.createElement("sfx-template-builder",{ref:l,class:T,style:U})});exports.TemplateBuilder=h;
 //# sourceMappingURL=react.cjs.map