@scaleflex/template-builder 0.1.1

package/README.md

@@ -0,0 +1,775 @@
+<p align="center">
+  <a href="https://www.scaleflex.com">
+    <img src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/logo.png?vh=b0a502&radius=25&w=700" alt="Scaleflex" width="350">
+  </a>
+</p>
+
+<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>
+  Drop a full multi-layout template editor into any page, in any frontend stack.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@scaleflex/template-builder"><img src="https://img.shields.io/npm/v/@scaleflex/template-builder.svg?style=flat-square" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/license-proprietary-red?style=flat-square" alt="license">
+</p>
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [npm / yarn / pnpm](#npm--yarn--pnpm)
+  - [CDN](#cdn)
+  - [Package exports](#package-exports)
+- [Quick Start](#quick-start)
+  - [Vanilla JS / Web Component](#vanilla-js--web-component)
+  - [React](#react)
+- [Modes](#modes)
+  - [DAM-backed](#dam-backed-default)
+  - [Stateless](#stateless)
+  - [Reporting a failed save](#reporting-a-failed-save)
+- [Configuration](#configuration)
+  - [Attributes & properties](#attributes--properties)
+  - [Authentication](#authentication)
+  - [Origin registration](#origin-registration)
+  - [Cookies](#cookies)
+- [Public Methods](#public-methods)
+- [Events](#events)
+- [React API](#react-api)
+- [Theming](#theming)
+  - [Brand Color](#brand-color)
+  - [Colour scheme](#colour-scheme)
+- [Browser Support](#browser-support)
+- [Claude Code Integration](#claude-code-integration)
+- [Development](#development)
+  - [The demo site](#the-demo-site)
+- [Release](#release)
+- [License](#license)
+
+---
+
+## 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.
+
+All the heavy lifting — server-side text rendering, font resolution, asset
+browsing, template XML — stays inside the app deployment. The widget is a
+protocol adapter.
+
+## Features
+
+- **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
+  entirely on your side ([Stateless](#stateless)) and never map your users onto
+  Scaleflex identities.
+- **Two ways in** — a Hub session, or a Filerobot [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.
+- **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.
+
+## Requirements
+
+- A [Filerobot](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
+  guest access; see [Authentication](#authentication)
+- Your page's origin registered in the deployment's `frame-ancestors` allowlist
+  — see [Origin registration](#origin-registration)
+- Modern browser with Custom Elements v1 support (see
+  [Browser Support](#browser-support))
+
+## Installation
+
+### npm / yarn / pnpm
+
+```bash
+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>
+```
+
+The CDN bundle is self-registering — it defines `<sfx-template-builder>` on
+load, with Lit bundled in. Pin the major version.
+
+### Package exports
+
+| Entry | Contents |
+|---|---|
+| `@scaleflex/template-builder` | The element class and every protocol constant / type. Does **not** register the tag. |
+| `@scaleflex/template-builder/define` | Side-effect import that registers `<sfx-template-builder>`. |
+| `@scaleflex/template-builder/react` | The `<TemplateBuilder>` React wrapper (also registers the tag). |
+
+> **Client-only:** the element extends `HTMLElement`, so importing `.`,
+> `./define`, or `./react` in a server-rendered module will throw. In SSR
+> frameworks, import dynamically on the client (e.g. Next.js `dynamic(...,
+> { ssr: false })` or a `useEffect` import).
+
+> **Protocol constants:** there is also a `./protocol` subpath, but it resolves
+> to TypeScript source and exists for the `design-templates-app` workspace,
+> which compiles it. External consumers should take the same constants from the
+> package root, which is compiled.
+
+## Quick Start
+
+### Vanilla JS / Web Component
+
+```html
+<script type="module">
+  import '@scaleflex/template-builder/define' // registers <sfx-template-builder>
+</script>
+
+<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>
+
+<script>
+  const builder = document.querySelector('sfx-template-builder')
+  builder.addEventListener('save', (e) => console.log('saved', e.detail)) // { uuid, name }
+  builder.addEventListener('error', (e) => console.error(e.detail)) // { code, message }
+</script>
+```
+
+Size the element yourself — in `inline` mode it fills the box you give it.
+
+### React
+
+```tsx
+import { TemplateBuilder } from '@scaleflex/template-builder/react'
+
+<TemplateBuilder
+  baseUrl="https://<deployment>"
+  token={token}
+  sassKey={sassKey}
+  sessionUuid={sessionUuid}
+  templateId={templateId}
+  style={{ height: 800 }}
+  onSave={(data) => console.log(data)}
+/>
+```
+
+---
+
+## Modes
+
+### DAM-backed (default)
+
+`template-id` is a Filerobot 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.
+
+### Stateless
+
+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,
+tenancy and access control, and `template-id` becomes an opaque string that is
+echoed back untouched.
+
+#### The template comes from your API
+
+The whole flow is three steps: **fetch the XML from your endpoint, pass it in,
+take the edited XML back out.** Nothing is stored on the Scaleflex side at any
+point.
+
+```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">
+  const builder = document.querySelector('sfx-template-builder')
+  const id = 'your-own-id-42'
+
+  // 1 — get the template XML from your API.
+  const res = await fetch(`/api/templates/${id}`)
+  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.
+  //     `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 })
+
+  // 3 — take the edited template back out and store it yourself.
+  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)
+
+    // Tell the editor whether it landed — see Reporting a failed save.
+    builder.confirmSave(ok)
+  })
+
+  // Loading a different template discards unsaved edits — check before you do.
+  builder.addEventListener('dirtychange', (e) => {
+    unsavedBanner.hidden = !e.detail.isDirty
+  })
+</script>
+```
+
+`templateId` is **your** identifier, not a Filerobot 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.
+
+The [demo page](./demo) runs exactly this against a real HTTP endpoint and logs
+every call, so you can watch the XML cross the boundary in both directions.
+
+React — `content` is a prop, and the outcome of `onSave` is reported back
+automatically:
+
+```tsx
+function TemplateEditor({ id }: { id: string }) {
+  const [tpl, setTpl] = useState<{ content: string; name: string } | null>(null)
+
+  // 1 — get the template XML from your API.
+  useEffect(() => {
+    fetch(`/api/templates/${id}`).then((r) => r.json()).then(setTpl)
+  }, [id])
+
+  if (!tpl) return null
+
+  return (
+    <TemplateBuilder
+      stateless
+      baseUrl="https://<deployment>"
+      token={token}
+      sassKey={sassKey}
+      sessionUuid={sessionUuid}
+      // 2 — pass it in.
+      templateId={id}
+      content={tpl.content}
+      templateName={tpl.name}
+      style={{ height: 800 }}
+      // 3 — take it back out. Returning false (or throwing) tells the editor
+      //     the save failed, and it restores its unsaved-changes flag.
+      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
+      }}
+      onDirtyChange={({ isDirty }) => setHasUnsavedEdits(isDirty)}
+    />
+  )
+}
+```
+
+#### About `templateQuery`
+
+`save` returns a `templateQuery` next to the content. It is the query string
+that renders the template at its defaults — layout, variable values, locale —
+and you append it to the template's CDN URL when you want an image out:
+
+```
+https://<tenant>.filerobot.com/<path>/<template>.fdt?<templateQuery>&force_format=png
+```
+
+**Persist it alongside `content`.** DAM-backed saves store it as file metadata;
+a stateless host that drops it gets renders that fall back to whatever the XML
+alone implies.
+
+**Pass it back in.** `load()` takes a `templateQuery` too, so the query you
+stored reopens the template on the render it was left at:
+
+```js
+builder.load({ templateId, name, content, templateQuery })
+```
+
+Omit it and the editor falls back to the `default=` attributes in the XML —
+a different render whenever the query overrode any of them, which is the usual
+case for a template driven by metadata or URL variables.
+
+It is applied as display state, not as an edit: it selects the layout and fills
+variable values without marking the document dirty, so opening a template and
+closing it again is not an unsaved change. Entries naming a variable or layout
+the document no longer defines are ignored rather than treated as an error, so
+a stale query still opens the template.
+
+Known limits on the way in — all of them cases where the editor's preview can
+differ from what the same query renders on the CDN:
+
+- **`$locale` is not applied.** Regional selection is seeded from Hub project
+  info, which a guest embed never receives.
+- **An explicitly empty value (`$headline=`) does not clear a variable.** The
+  editor resolves `value || default`, so it falls back to the XML default,
+  while the backend treats explicit-empty as empty. Omit the key instead of
+  sending it blank.
+- **Metadata-sourced variables behave differently by session.** Under a guest
+  (security-template) session the query's value stands. Under a Hub session the
+  editor re-resolves them from the linked asset shortly after load, overwriting
+  it — that automation is the DAM behaviour and takes precedence.
+- **`$layout_color` is ignored**; the layout's own colour is used. Queries this
+  editor produced always agree, so this only bites a hand-built one.
+- **`layout`, `locale` and `force_format` are reserved.** A variable whose slug
+  is one of those cannot be addressed by a query.
+
+**Swapping templates.** Assigning a new `content`, `templateId`, `templateName`
+or `templateQuery` reloads the editor and **discards unsaved edits without
+prompting** — the host is treated as authoritative. Watch `dirtychange` (or read
+the `isDirty` property) and ask the user first. Re-assigning an identical
+template is a no-op, so a host re-render can't destroy work by accident. Note
+that the id is part of that identity check: moving between two records whose
+content is byte-identical does reload, so a save can never land on the record
+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:
+
+- **text rendering** — text layers are rasterized server-side,
+- **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**.
+
+What it does let you avoid is mapping *your users* onto Scaleflex identities:
+point every embed at one service tenant with a single machine credential minted
+server-side, and do all per-user permission work yourself.
+
+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`.
+
+### 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:
+
+```js
+builder.addEventListener('save', async (e) => {
+  try {
+    await yourApi.saveTemplateXml(e.detail.templateId, e.detail.content)
+    builder.confirmSave(true)
+  } catch (err) {
+    builder.confirmSave(false, 'Could not save — please try again.')
+  }
+})
+```
+
+The React wrapper does this for you: return (or resolve to) `false` from
+`onSave`, or throw, and the failure is reported automatically.
+
+Acking is optional. A host that never calls `confirmSave` keeps the optimistic
+behaviour, so this is additive — but only `ok: false` carries information, and
+without it a failed write is invisible to the user.
+
+---
+
+## Configuration
+
+### Attributes & properties
+
+| 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 | Filerobot 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` |
+| `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` |
+| `content` (property only) | stateless | The template to edit, as `.fdt` XML. Assigning a new value loads it into a running editor |
+| `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` |
+| `theme` | no | `light`, `dark` or `auto` |
+| `ready-timeout` / `readyTimeout` | no | Ms to wait for the app handshake before `error` (default 20000, 0 disables) |
+
+### Authentication
+
+Two credentials get you in. Both go into the page from your server; neither is
+something to hardcode in a public bundle.
+
+| | Hub session | Security template |
+| --- | --- | --- |
+| Attributes | `token` + `sass-key` + `session-uuid` | `token` + `sec-template` |
+| Needs a Hub account per embed | yes | **no** |
+| Storage modes | DAM-backed and stateless | **stateless only** |
+| Metadata fields, regional variants, project branding | yes | **empty** |
+| Rendering, fonts, asset picker | yes | yes, within the template's scope |
+
+#### 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.
+
+#### 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:
+
+```html
+<sfx-template-builder
+  base-url="https://templates.example.com"
+  token="PROJECT_TOKEN"
+  sec-template="SEC_TEMPLATE_KEY"
+  stateless
+></sfx-template-builder>
+```
+
+```jsx
+<TemplateBuilder
+  stateless
+  baseUrl="https://templates.example.com"
+  token={projectToken}
+  secTemplate={secTemplateKey}
+  templateId={id}
+  content={xml}
+  onSave={async (data) => (await saveToYourApi(data)).ok}
+/>
+```
+
+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.
+
+**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.
+- **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`.
+
+### 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`.
+
+### Cookies
+
+The app stores auth in partitioned (CHIPS) cookies scoped to your site. Browsers
+without CHIPS support that block third-party cookies will fail with `auth` or
+`handshake-timeout`.
+
+---
+
+## Public Methods
+
+| 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). |
+| `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`),
+`isDirty` (stateless; unsaved edits pending).
+
+In React these are reached through a ref — see [React API](#react-api).
+
+## Events
+
+All events are `CustomEvent`s; the payload is in `detail`.
+
+| Event | `detail` | Fired when |
+| --- | --- | --- |
+| `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. |
+| `dirtychange` | `{ isDirty }` | Stateless: the unsaved-changes flag flipped. |
+| `close` | — | The user left the editor, or it unmounted. |
+| `error` | `{ code, message? }` | See below. |
+
+`error` codes:
+
+| Code | Means |
+| --- | --- |
+| `auth` | The app could not authenticate — blocked cookies, an expired session, or a security template the Filerobot 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-base-url` | `base-url` is not a URL. |
+| `unknown` | Anything the app reported that this version does not name. |
+
+`close` fires when the user leaves the editor as well as when it unmounts. In
+`modal` mode the element tears its overlay down; in `inline` mode it is yours to
+act on — the editor never navigates itself anywhere.
+
+## React API
+
+Props mirror the attributes in camelCase, plus `className` and `style`.
+Callbacks: `onReady`, `onOpen`, `onSave`, `onDirtyChange`, `onClose`, `onError`.
+
+The credential props are a discriminated union, so the two
+[auth modes](#authentication) are enforced at compile time: `sassKey` +
+`sessionUuid`, or `secTemplate` with `stateless` — mixing them, or passing
+`secTemplate` without `stateless`, is a type error rather than a runtime one.
+
+`onSave` may return `false` or a promise; see
+[Reporting a failed save](#reporting-a-failed-save).
+
+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:
+
+```tsx
+import { useRef } from 'react'
+import { TemplateBuilder } from '@scaleflex/template-builder/react'
+import type { SfxTemplateBuilder } from '@scaleflex/template-builder'
+
+const builder = useRef<SfxTemplateBuilder>(null)
+
+<TemplateBuilder ref={builder} mode="modal" baseUrl={...} {...auth} />
+<button onClick={() => builder.current?.open('tpl-1')}>Edit template</button>
+```
+
+`react` and `react-dom` (>= 18) are optional peer dependencies — the package
+works without React installed.
+
+---
+
+## Theming
+
+### Brand Color
+
+`brand-color` restyles the editor chrome — buttons, focus rings, highlights,
+selected states — from a single accent colour.
+
+```html
+<sfx-template-builder brand-color="#FF6600" ...></sfx-template-builder>
+```
+
+- Must be `#rgb` or `#rrggbb`. Anything else is rejected by the app and the
+  default Scaleflex accent is kept — the value ends up inside a stylesheet, so
+  the shape is enforced rather than escaped.
+- Text drawn *on top of* the brand colour (primary button labels) is chosen for
+  you, white or near-black, by contrast ratio. A pale brand colour gets dark
+  labels rather than invisible ones.
+- Surfaces, borders and body text keep the design system's neutrals; only the
+  accent ramp follows your colour.
+
+**Pick a colour that is readable on white.** The design system uses one accent
+token for both filled surfaces and link text, so a very pale brand colour gives
+you a good-looking button and low-contrast links. Tinted accents are darkened
+automatically where they are unambiguously text, but a link rendered in the
+accent colour itself cannot be — darkening it would mean not showing your brand
+colour on the button either. Mid-tone colours (roughly, anything that passes
+4.5:1 on white) avoid the trade-off entirely.
+
+### Colour scheme
+
+`theme` is `light`, `dark` or `auto` (follows the viewer's OS setting). It
+overrides the user's own stored preference, which in an embed lives in
+partitioned storage your page cannot reach.
+
+**Theming applies to the editor UI, not the template.** Colours in the design
+itself live in the document and are edited through the builder — a brand colour
+never changes what gets rendered or exported.
+
+---
+
+## Browser Support
+
+| Browser | Minimum version |
+|---|---|
+| Chrome | 114+ |
+| Firefox | 131+ |
+| Safari | 18.4+ |
+| Edge (Chromium) | 114+ |
+
+Requires native support for Custom Elements v1, Shadow DOM, and ES2020+.
+Internet Explorer is **not** supported.
+
+The floors are higher than a plain web component would need because cross-site
+embedding depends on **partitioned cookies (CHIPS)**. On an older browser that
+blocks third-party cookies the editor cannot authenticate and the widget reports
+`auth` / `handshake-timeout`. Same-site embeds work further back.
+
+---
+
+## Development
+
+```bash
+yarn dev:demo      # demo site (expects the app on http://localhost:3000)
+yarn test          # vitest
+yarn typecheck     # tsc --noEmit
+yarn build         # dist/ — npm artifact (ESM + CJS + types)
+yarn build:cdn     # dist-cdn/template-builder.min.js — self-registering bundle
+yarn build:demo    # demo-dist/ — the static demo site
+yarn preview:demo  # serve demo-dist/ as a client would
+yarn build:all     # build + build:cdn
+```
+
+From the repo root, `yarn widget <script>` runs any of these, and the root
+`yarn test` / `yarn typecheck` include this package.
+
+### The demo site
+
+`demo/` is two pages: `index.html`, the live widget with a configuration panel
+and a wire log, and `docs.html`, this README. `scripts/vite-plugin-docs.mjs`
+renders the markdown at build time — the shipped page is static HTML with no
+markdown runtime, and this file stays the only place the documentation is
+written. Headings get GitHub's anchor slugs so the links above keep resolving,
+the "Table of Contents" section is replaced by a generated sidebar, and editing
+the README reloads the dev server.
+
+`yarn build:demo` emits the pair to `demo-dist/` with relative asset paths, so
+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.
+
+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,
+name and template query from the file you choose. Both auth modes list: a
+security template is exchanged for a sass key first, so the listing sees
+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.
+
+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
+app running with the fixture origin allowlisted:
+
+```bash
+yarn build:widget
+export NEXT_PUBLIC_TRUSTED_HUB_ORIGINS=http://127.0.0.1:4321
+yarn build && yarn start
+yarn test:e2e:embed
+```
+
+The postMessage 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.
+
+## Release
+
+```bash
+yarn release            # patch bump (0.1.0 → 0.1.1)
+yarn release -- minor   # minor bump (0.1.0 → 0.2.0)
+yarn release -- major   # major bump (0.1.0 → 1.0.0)
+```
+
+This handles the full pipeline: version bump, CDN build + upload, library build,
+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}/
+```
+
+Update [CHANGELOG.md](./CHANGELOG.md) before releasing.
+
+---
+
+## Claude Code Integration
+
+If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), this
+package ships a ready-made skill that walks Claude through adding the builder to
+your project — choosing DAM-backed vs stateless storage, wiring the save round
+trip, theming, and registering your embedding origin.
+
+### Option 1: Project-level (recommended)
+
+Copy the skill into your project so everyone on the team gets it:
+
+```bash
+mkdir -p .claude/skills/integrate-template-builder
+cp node_modules/@scaleflex/template-builder/.claude/skills/integrate-template-builder/SKILL.md \
+   .claude/skills/integrate-template-builder/SKILL.md
+```
+
+Commit the `.claude/skills/` directory to version control.
+
+### Option 2: Global (personal)
+
+Install it once for all your projects:
+
+```bash
+mkdir -p ~/.claude/skills/integrate-template-builder
+cp node_modules/@scaleflex/template-builder/.claude/skills/integrate-template-builder/SKILL.md \
+   ~/.claude/skills/integrate-template-builder/SKILL.md
+```
+
+### Usage
+
+Type `/integrate-template-builder` in Claude Code and it will take you through
+the whole integration, tailored to your stack.
+
+---
+
+## License
+
+**PROPRIETARY** &mdash; All Rights Reserved.
+
+Copyright &copy; 2025 [Scaleflex SAS](https://www.scaleflex.com).
+
+This software and associated documentation are the exclusive property of
+Scaleflex SAS. No part of this software may be copied, modified, distributed,
+sublicensed, sold, or otherwise made available to any third party without prior
+written permission from Scaleflex SAS.
+
+This package is distributed via npm solely for the convenience of licensed
+customers. Installing or using this package does not grant any licence to use
+the software. Use is permitted only under a separate written licence agreement
+with Scaleflex SAS.
+
+For licensing enquiries, contact [sales@scaleflex.com](mailto:sales@scaleflex.com).
+
+---
+
+<p align="center">
+  Made with care by <a href="https://www.scaleflex.com">Scaleflex</a>
+</p>