@scaleflex/template-builder 0.1.1

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

@@ -0,0 +1,356 @@
+---
+name: integrate-template-builder
+description: Integrate @scaleflex/template-builder into any project — install, choose
+  DAM-backed or stateless storage, wire the save round trip, theme, and register the
+  embedding origin. Works with vanilla JS, React, Vue, Angular, Svelte.
+user_invocable: true
+metadata:
+  category: integration
+  tags:
+  - scaleflex
+  - filerobot
+  - template-builder
+  - design-templates
+  - web-component
+  status: ready
+  version: 1
+---
+
+# Scaleflex Template Builder Integration Skill
+
+## When to Use
+
+- 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
+
+## Step 1 — Decide who stores the template
+
+This is the first question, and it changes everything downstream. Ask if it is
+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 |
+| 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.
+
+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.
+
+## Step 2 — Detect the target framework
+
+Read the project's `package.json`:
+
+- **React** (18+): use `@scaleflex/template-builder/react`
+- **Vue / Angular / Svelte / vanilla JS**: use `@scaleflex/template-builder/define`
+
+## Step 3 — Install
+
+```bash
+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>
+```
+
+**SSR caution:** the element extends `HTMLElement`, so importing `.`,
+`./define` or `./react` from a server-rendered module throws. In Next.js use
+`dynamic(() => import(...), { ssr: false })`; in Nuxt use `<client-only>`.
+
+## Step 4 — Add the builder
+
+Size the element — in `inline` mode it fills the box it is given, and a
+zero-height parent renders nothing.
+
+### Stateless (host owns the template)
+
+The flow is always these three steps: **fetch the XML from your API, pass it
+in, take the edited XML back out.**
+
+```html
+<sfx-template-builder
+  stateless
+  base-url="https://<deployment>"
+  token="FILEROBOT_TOKEN"
+  sass-key="SASS_KEY"
+  session-uuid="SESSION_UUID"
+  style="display:block;height:800px"
+></sfx-template-builder>
+
+<script type="module">
+  import '@scaleflex/template-builder/define'
+
+  const builder = document.querySelector('sfx-template-builder')
+  const id = 'your-own-id-42'
+
+  // 1 — get the template XML from your API
+  const { content, name } = await fetch(`/api/templates/${id}`).then((r) => r.json())
+
+  // 2 — pass it in. `content` is a property, never an attribute: templates
+  //     routinely exceed what fits in markup or a URL.
+  builder.load({ templateId: id, name, content })
+
+  // 3 — take the edited template back out and store it
+  builder.addEventListener('save', async (e) => {
+    const { templateId, content, name, templateQuery } = e.detail
+    const ok = await fetch(`/api/templates/${templateId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ content, name, templateQuery }),
+    }).then((r) => r.ok)
+
+    // Reporting the outcome is not optional in practice — see Step 5.
+    builder.confirmSave(ok)
+  })
+</script>
+```
+
+### Stateless, React
+
+`content` is a prop, and the outcome of `onSave` is acked automatically:
+
+```tsx
+import { TemplateBuilder } from '@scaleflex/template-builder/react'
+
+<TemplateBuilder
+  stateless
+  baseUrl="https://<deployment>"
+  token={token}
+  sassKey={sassKey}
+  sessionUuid={sessionUuid}
+  templateId={id}
+  content={xml}
+  templateName={name}
+  style={{ height: 800 }}
+  onSave={async (data) => {
+    const res = await fetch(`/api/templates/${data.templateId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data),
+    })
+    return res.ok // false → the editor restores its unsaved-changes flag
+  }}
+/>
+```
+
+### DAM-backed
+
+`template-id` is a Filerobot 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"
+  sass-key="SASS_KEY"
+  session-uuid="SESSION_UUID"
+  template-id="TEMPLATE_UUID"
+  style="display:block;height:800px"
+></sfx-template-builder>
+```
+
+`save` then carries `{ uuid, name }` — the uuid of the version just written.
+
+## 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.
+**Call `confirmSave(false)` when your write fails**, or a failed save silently
+looks successful and the user loses work:
+
+```js
+try {
+  await yourApi.save(...)
+  builder.confirmSave(true)
+} catch {
+  builder.confirmSave(false, 'Could not save — please try again.')
+}
+```
+
+The React wrapper does this from what `onSave` returns or throws.
+
+## Step 6 — Guard against losing edits
+
+Assigning a new `content` / `templateId` / `templateName` / `templateQuery`
+reloads the editor and
+**discards unsaved edits without prompting** — the host is authoritative. Watch
+`dirtychange` (or read `isDirty`) before swapping:
+
+```js
+builder.addEventListener('dirtychange', (e) => {
+  hasUnsavedEdits = e.detail.isDirty
+})
+```
+
+Re-assigning an identical template is a no-op, so an unrelated re-render cannot
+destroy work by accident.
+
+## Step 7 — Authentication
+
+Two credentials work. Both are minted **server-side** and injected into the
+page; neither belongs in a public bundle.
+
+**Hub session** — `token` + `sass-key` + `session-uuid`. Full features, both
+storage modes. Issue short-lived per-user sessions; never put a long-lived
+master credential in client-side code.
+
+**Security template** — `token` + `sec-template`, no Hub account involved. Use
+it when the host has no Scaleflex identity to hand over per user:
+
+```html
+<sfx-template-builder
+  base-url="https://<deployment>"
+  token="FILEROBOT_TOKEN"
+  sec-template="SEC_TEMPLATE_KEY"
+  stateless
+></sfx-template-builder>
+```
+
+The app exchanges the key for a short-lived access key and renews it on expiry.
+What it costs:
+
+- **`stateless` is required.** Without it the widget reports `error` with code
+  `invalid-config` and never mounts. The DAM-backed editor keeps needing a
+  session.
+- **Hub-project features come back empty** — metadata fields, regional variants,
+  dynamic fields, project branding. Theme with `brand-color` / `theme` instead.
+- **Scope the template to what the editor needs**: `LIST` on browsable folders,
+  plus `LIST` + `UPLOAD` on `/.studio/fonts*` for custom fonts. Prefer short
+  TTLs — expiry is handled, over-permission is not.
+
+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.
+
+## 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.
+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.
+
+## Step 9 — Theming (optional)
+
+```html
+<sfx-template-builder brand-color="#FF6600" theme="dark" ...>
+```
+
+- `brand-color` must be `#rgb` / `#rrggbb`; anything else is ignored and the
+  Scaleflex accent is kept.
+- Label colour on top of the brand is chosen automatically by contrast.
+- Pick a colour readable on white: one accent token serves both filled surfaces
+  and link text, so a very pale brand gives good buttons and weak links.
+- `theme` is `light` / `dark` / `auto`.
+
+Themes the **editor chrome only** — colours inside the design live in the
+template document.
+
+## Attributes Reference
+
+| Attribute / property | Required | Description |
+|---|---|---|
+| `base-url` / `baseUrl` | yes | Origin of the design-templates-app deployment |
+| `token` | yes | Filerobot 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 |
+| `mode` | no | `inline` (default) or `modal` (starts closed — call `open()`) |
+| `stateless` | no | Host owns the document; requires `content` |
+| `content` (property only) | stateless | Template as `.fdt` XML |
+| `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 |
+| `ready-timeout` / `readyTimeout` | no | Ms before `handshake-timeout` (default 20000) |
+
+## Events Reference
+
+| Event | `detail` |
+|---|---|
+| `ready` | — (editor mounted, auth valid) |
+| `open` | — |
+| `save` | `{ uuid, name }` (DAM) or `{ templateId, content, name, templateQuery }` (stateless) |
+| `dirtychange` | `{ isDirty }` (stateless) |
+| `close` | — (user left the editor, or it unmounted) |
+| `error` | `{ code, message? }` |
+
+`error` codes: `auth`, `invalid-content`, `invalid-config`,
+`handshake-timeout`, `invalid-base-url`, `unknown`.
+
+## Public Methods
+
+`open(templateId?)`, `close()`, `load({ content, 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:
+
+```tsx
+const builder = useRef<SfxTemplateBuilder>(null)
+<TemplateBuilder ref={builder} mode="modal" ... />
+<button onClick={() => builder.current?.open()}>Edit</button>
+```
+
+## About `templateQuery`
+
+`save` returns a `templateQuery` next to the content — the query string that
+renders the template at its defaults (layout, variable values, locale):
+
+```
+https://<tenant>.filerobot.com/<path>/<template>.fdt?<templateQuery>&force_format=png
+```
+
+Persist it alongside `content`, then pass it back on the next load:
+
+```js
+builder.load({ templateId, name, content, templateQuery })
+```
+
+Omitting it opens the template on the `default=` values in the XML, which is a
+different render whenever the query overrode any of them. It is applied as
+display state — layout and variable values — and does not mark the document
+dirty. Entries naming a variable or layout the document no longer defines are
+ignored, so a stale query still opens.
+
+Inbound limits, where the preview can differ from the CDN render of the same
+query: `$locale` is not applied (seeded from Hub project info, which guest
+embeds lack); an explicitly empty value (`$headline=`) falls back to the XML
+default instead of clearing — omit the key rather than sending it blank;
+metadata-sourced variables keep the query's value under a guest session but are
+re-resolved from the linked asset under a Hub session; `$layout_color` is
+ignored; and `layout` / `locale` / `force_format` are reserved slugs.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `error` code `handshake-timeout`, blank frame | Host origin not in `frame-ancestors` (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) |
+| Metadata / regional / branding panels empty | Expected under `sec-template` — those come from the Hub project (Step 7) |
+| 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) |
+| Images in the template fail to render | Their host is not in the deployment's `RENDER_ALLOWED_HOSTS_EXTRA` |
+
+## Browser Support
+
+Chrome/Edge 114+, Firefox 131+, Safari 18.4+. The floors come from partitioned
+cookies (CHIPS), which cross-site embedding depends on — not from web
+components. Older browsers that block third-party cookies fail with `auth` /
+`handshake-timeout`.

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to `@scaleflex/template-builder` are documented here. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the package follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+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.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.
+
+### Added
+
+- `sec-template` attribute — authenticate with a Filerobot 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
+  *Authentication* in the README. In React the credential props are a
+  discriminated union, so mixing the two modes is a type error.
+- `invalid-config` error code — reported when attributes contradict each other,
+  currently `sec-template` without `stateless`.
+- `AUTH_MODES` / `AuthMode` protocol exports, and `EMBED_PARAMS.SEC_TEMPLATE`.
+- `brand-color` and `theme` attributes — restyle the editor chrome from a single
+  accent colour and pick the colour scheme. Themes the editor UI only; template
+  colours live in the document.
+- `confirmSave(ok, message?)` and the `HOST_SAVED` protocol message. Stateless
+  hosts can report a failed write, and the editor restores its unsaved-changes
+  flag instead of showing the template as saved. The React wrapper reports it
+  automatically from what `onSave` returns or throws.
+- `invalid-content` error code — the app now reports a template it could not
+  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
+  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.
+- `.claude/skills/integrate-template-builder` — an integration skill shipped in
+  the package, matching `@scaleflex/asset-picker`.
+- End-to-end coverage of the embed boundary (`e2e/embed-widget.spec.ts` in the
+  app repo): a cross-origin host page loads the built CDN bundle, fetches
+  template XML from its own API, and gets the edited document back on save.
+
+### Changed
+
+- CDN bundle moved from `dist/cdn/template-builder.js` to
+  `dist-cdn/template-builder.min.js`, matching `@scaleflex/asset-picker`. It no
+  longer ships inside the npm tarball, where it duplicated the library and Lit.
+- `build` now produces only the npm artifact; use `build:cdn` / `build:all`.
+- `license` corrected from `MIT` to `SEE LICENSE IN LICENSE`.
+
+### Fixed
+
+- The React wrapper kept its ref private, so `open()`, `close()`, `load()` and
+  `confirmSave()` were unreachable — which made `mode="modal"` unusable from
+  React, since nothing renders until `open()` is called. It now forwards a ref
+  to the element.
+- An unparseable `base-url` emitted `error` on every render pass instead of once.
+- The editor's close button navigated an embedded editor to the Scaleflex
+  dashboard inside the host page. It now posts `builder:close` and leaves the
+  decision to the embedder.

package/LICENSE

@@ -0,0 +1,50 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2025 Scaleflex SAS. All Rights Reserved.
+
+NOTICE: This software and associated documentation files (the "Software") are
+the exclusive property of Scaleflex SAS. The Software is protected by copyright
+laws, international treaties, and other intellectual property laws.
+
+RESTRICTIONS
+
+You may NOT, without prior written permission from Scaleflex SAS:
+
+  1. Copy, reproduce, or duplicate the Software, in whole or in part.
+  2. Modify, adapt, translate, reverse engineer, decompile, or disassemble the
+     Software, or create derivative works based on the Software.
+  3. Distribute, sublicense, lease, rent, loan, sell, or otherwise transfer the
+     Software or any rights therein to any third party.
+  4. Remove, alter, or obscure any proprietary notices, labels, or marks on the
+     Software.
+  5. Use the Software for any purpose other than as expressly authorised under
+     a separate written licence agreement with Scaleflex SAS.
+
+GRANT OF LICENCE
+
+Use of this Software is permitted only under a separate written licence
+agreement between the licensee and Scaleflex SAS. Installing or downloading
+this Software does not, by itself, grant any licence or right to use the
+Software.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+SCALEFLEX SAS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ENFORCEMENT
+
+Unauthorised use, reproduction, or distribution of this Software, or any
+portion thereof, may result in severe civil and criminal penalties and will be
+prosecuted to the maximum extent permitted by applicable law.
+
+CONTACT
+
+For licensing enquiries:
+  Scaleflex SAS
+  Email: sales@scaleflex.com
+  Web:   https://www.scaleflex.com