@bygga.dev/editor 1.3.0 → 1.5.0

package/README.md

@@ -10,6 +10,15 @@ styles can't leak out.
 
 The editor is built and maintained by [Memlist CRM](https://memlist.se)
 
+**Contents** — [Install](#install) · [Licence key](#you-need-a-licence-key) ·
+[Quick start](#quick-start) · [Host contract](#host-contract) ·
+[Document kinds](#document-kinds-email-and-page) · [Saved blocks](#saved-blocks) ·
+[Block plugins](#block-plugins) · [AI assistance](#ai-assistance) ·
+[Dynamic content](#dynamic-content-per-recipient-blocks) ·
+[Sending & publishing](#sending-and-publishing) · [Compile API](#the-compile-api) ·
+[Theming](#theming) · [TypeScript](#typescript) ·
+[Framework integration](#framework-integration)
+
 ## Install
 
 ```sh
@@ -60,6 +69,11 @@ editor.config = {
   async uploadImage(blob) {
     return await uploadToYourStorage(blob)
   },
+  // Optional push-save. `compiled` is this version's sendable HTML — or null if the
+  // compile did not happen. Store the two together; see Sending and publishing.
+  async saveDocument(document, compiled) {
+    await api.saveTemplate({ document, compiled })
+  },
 }
 
 editor.locale = 'en'
@@ -74,47 +88,111 @@ editor.style.height = '100vh' // it is display:block/height:100% — give it a s
 document.body.append(editor) // config is set, so it's safe to connect
 ```
 
+**Sizing.** The element is `display: block; height: 100%`, which degrades to `auto`
+if nothing sizes it — an unsized parent yields a collapsed editor. Give it a height
+(a `100vh` container, a flex child with `min-height: 0`, or an explicit pixel height).
+
 ## Host contract
 
+### `license-key` attribute
+Your licence key (see [You need a licence key](#you-need-a-licence-key)). Reactive: changing it
+re-activates, so a host that fetches its key can set it after the element is connected. Omit it on
+`localhost`, which is licensed without one.
+
 ### `locale` attribute
 `sv` (default) or `en`. Reactive, and also sets the shadow tree's `lang` for
-assistive technology. Settable as the attribute or the `.locale` property.
+assistive technology. Settable as the attribute or the `.locale` property. An
+unsupported value warns and falls back to the default. The supported set is exported
+as `SUPPORTED_LOCALES` / `DEFAULT_LOCALE`.
 
 ### `config` property *(required)*
 Host callbacks. Assign it **before** connecting the element (the editor throws at
-mount if `uploadImage` is missing):
+mount if `uploadImage` is missing). It's a plain object, re-read on assignment, so
+you can swap it at runtime.
 
 - **`uploadImage(blob: Blob): Promise<string>`** *(required)* — store the image and
-  resolve with a public URL. The Blob arrives already compressed and scaled, so don't
+  resolve with a public URL. The Blob arrives already compressed and scaled (content
+  images to 600px wide, full-width backgrounds to 1920px, JPEG quality 0.82), so don't
   re-encode it; it may be called concurrently. The URL is written into the document
   and then into sent email, so it must be absolute, unauthenticated, and permanent (a
   presigned GET that expires will break in the inbox). Rejecting shows the user an
   alert, keeps the block's previous image, and reports through `onImageError`.
-- **`saveDocument(document: Document): Promise<void>`** *(optional)* — push-save hook
-  invoked by `save()`; on success the editor marks the document saved. Rejecting
-  leaves the document dirty.
+- **`saveDocument(document: Document, compiled: string | null): Promise<void>`**
+  *(optional)* — push-save hook invoked by `save()`; on success the editor marks the
+  document saved. `compiled` is this version's sendable HTML, or `null` when the
+  compile did not happen (our server unreachable, or the licence's compile quota
+  spent). **Persist the pair together or persist nothing** — storing them separately
+  and updating only the non-null one is how a document ends up beside the previous
+  version's HTML, and the send goes out with content the author no longer sees.
+  Rejecting propagates out of `save()` and leaves the document dirty.
 - **`onImageError(error: unknown): void`** *(optional)* — called after the editor has
-  already told the user and recovered, for your own logging.
+  already told the user and recovered, for your own logging. Without it, an upload
+  failure is invisible to your backend.
+- **`saveBlock(saved: SavedBlock): Promise<void>`** *(optional)* — persist a Saved
+  block. Supplying it is what puts the Save control on a block's toolbar. See
+  [Saved blocks](#saved-blocks).
+- **`deleteSavedBlock(id: string): Promise<void>`** *(optional)* — delete the Saved
+  block with that id. Supplying it puts a delete control on each library entry.
+- **`plugins: readonly BlockPlugin[]`** *(optional)* — custom block types this embed
+  registers. See [Block plugins](#block-plugins).
+- **`ai: AiAssistant`** *(optional)* — AI assistance for authors, powered by **your**
+  backend. See [AI assistance](#ai-assistance).
 
 ### `document` property
 Assign a `Document` to load one; unset or `null` starts a blank document. It's a
 property, not an attribute — objects can't pass through an HTML attribute.
 
+Assigning always re-baselines the unsaved-changes state ("this is the truth now"), so
+handing back exactly what you stored does not leave the editor dirty. The tree is only
+replaced when the JSON actually differs, so re-assigning an identical document won't
+remount live editors or drop undo history.
+
 ### `mergeTags` property
-The personalization tags this host offers, keyed by the id the document stores, with
-per-locale labels (`{ firstName: { en: 'First name', sv: 'Förnamn' } }`). Populates
-the merge-tag picker; your backend must later resolve every id it sees. A missing
-locale label falls back to the default locale, then to the bare id.
+The personalization tags this host offers, keyed by the id the document stores. Ids
+must match `[A-Za-z0-9._-]+`. The value carries per-locale labels plus two optional
+fields:
+
+```js
+editor.mergeTags = {
+  firstName: { en: 'First name', sv: 'Förnamn' },
+
+  memberAttributes: {
+    en: 'Member attributes',
+    // Declared values. When a condition on this tag uses a set-membership operator,
+    // the condition UI offers these as a multiselect instead of a free-text field.
+    options: [
+      { value: 'board', label: 'Board member' },
+      { value: 'newsletter', label: 'Newsletter' },
+    ],
+    // Offered for conditions, hidden from the content-insert picker — for tags whose
+    // value is machinery (an id list, a flag) that would read as garbage in a body.
+    conditionOnly: true,
+  },
+}
+```
+
+A missing locale label falls back to the default locale, then to the bare id. Your
+backend must later resolve every id it sees; see
+[Sending and publishing](#sending-and-publishing).
 
 ### `brand` property
-The colours and fonts your embed permits — a menu for the pickers, never a rewrite of a
-document. All halves are optional; an absent one is unrestricted.
+The colours and fonts your embed permits — a **menu for the pickers, never a rewrite of
+a document**. It bounds what can be picked next; it never rejects or edits a document,
+and a value already in a document that the Brand doesn't contain keeps rendering. All
+halves are optional; an absent one is unrestricted.
 
 ```js
 editor.brand = {
-  colors: ['#2f2a72', '#a28c67'],          // replaces the free spectrum with swatches
-  fonts: ['georgia', 'arial'],             // narrows the email-safe faces; first seeds new documents
-  customFonts: [                           // appends your own faces after the email-safe set
+  // Replaces the free spectrum with exactly these swatches, everywhere a colour is
+  // picked. Hex with or without '#', shorthand expanded, case-insensitive.
+  colors: ['#2f2a72', '#a28c67'],
+
+  // Narrows the email-safe faces the font pickers offer, in your order. The FIRST is
+  // the font a new blank document starts on.
+  fonts: ['georgia', 'arial'],
+
+  // Appends your own faces after the email-safe set.
+  customFonts: [
     {
       name: 'Acme Sans',                   // picker label; @font-face family for a font-file href
       href: 'https://static.example.com/fonts/acme-sans.css', // stylesheet URL (e.g. a Google Fonts embed), or a .woff2/.ttf file
@@ -124,43 +202,50 @@ editor.brand = {
 }
 ```
 
+The email-safe faces are `arial`, `tahoma`, `trebuchet`, `verdana`, `georgia`,
+`times`, `courier`. Invalid entries (an unparseable colour, a non-http(s) font href)
+are dropped with a `[bygga-editor]` console warning rather than throwing — one typo
+must not take down your editor. The Transparent option stays available beside a
+restricted palette, since "no fill" is a structural choice rather than a brand colour.
+
 A custom face renders in the editor and wherever the compiled HTML is shown in a real
-browser engine (a view-online page, Apple Mail); most email clients strip remote fonts
+browser engine (a published page, Apple Mail); most email clients strip remote fonts
 and fall back through the stack, so give `fontFamily` sensible fallbacks. The document
-carries what it uses (`customFonts` in its JSON), so it keeps rendering even if you later
-change the registration. Only http(s) hrefs register.
+carries what it uses, so it keeps rendering even if you later change the registration.
 
-### `license-key` attribute
-Your licence key (see [You need a licence key](#you-need-a-licence-key)). Reactive: changing it
-re-activates, so a host that fetches its key can set it after the element is connected. Omit it on
-`localhost`, which is licensed without one.
+### `savedBlocks` property
+The Saved block library this embed offers — see [Saved blocks](#saved-blocks). An
+array property (arrays can't arrive through an attribute). This is the **only** thing
+the Saved tab renders; the editor keeps no library of its own.
 
 ### Events
-- **`change`** — a `CustomEvent` fired whenever the document changes; `event.detail[0]`
-  is a detached JSON snapshot (persist it with `JSON.stringify`).
-- **`dirtychange`** — a `CustomEvent` fired when the unsaved-changes state flips;
-  `event.detail[0]` is a boolean. Drives, e.g., a Save button's enabled state.
-- **`licenseerror`** — a `CustomEvent` fired once when the editor refuses to open;
-  `event.detail[0]` is `{ reason }`, one of `key`, `domain`, `origin`, `malformed`,
-  `unreachable`, `invalid`, `insecure-context`. The panel and a fuller `console.error`
-  diagnostic are already handled — this is so you can route it into your own telemetry.
-  Events do not bubble, so listen on the element itself.
+Events do not bubble — listen on the element itself.
+
+- **`change`** — fired whenever the document changes; `event.detail[0]` is a detached
+  JSON snapshot. A *notification*, not a request: a host that echoes every payload back
+  into the `document` property is declaring each keystroke saved and will never see the
+  editor dirty.
+- **`dirtychange`** — fired when the unsaved-changes state flips; `event.detail[0]` is
+  a boolean. Drives, e.g., a Save button's enabled state.
+- **`licenseerror`** — fired once when the editor refuses to open; `event.detail[0]` is
+  `{ reason }`, one of `key`, `domain`, `origin`, `malformed`, `unreachable`,
+  `invalid`, `insecure-context`. The panel and a fuller `console.error` diagnostic are
+  already handled — this is so you can route it into your own telemetry.
 
 ### Methods
-- **`getDocument(): Document`** — the current document.
+- **`getDocument(): Document`** — the current document, detached.
 - **`isDirty(): boolean`** — the current unsaved-changes state.
 - **`markSaved(): void`** — clear the unsaved-changes state after you persist.
 - **`save(): Promise<void>`** — routes through `config.saveDocument`, then marks
-  saved. Overlapping calls share one in-flight save.
+  saved. Rejects if `config.saveDocument` isn't configured. Overlapping calls share one
+  in-flight save, so awaiting it always means "the current document is saved".
 
 `getDocument()` throws and `save()` rejects while the editor is unlicensed, because there is no
 document behind them that anyone has edited — the editor never mounted. That matters if you autosave
 on a timer: without it, a licence outage would write a blank document over the stored one.
 
 Two ways to save: **pull** (`getDocument()`, persist it yourself, then `markSaved()`)
-or **push** (`save()`). `change` is a *notification*, not a request — a host that
-echoes every `change` payload back into the `document` property is declaring each
-keystroke saved and will never see the editor dirty.
+or **push** (`save()`, which also gives you the compiled HTML).
 
 ### The `Document`
 Opaque by design: persist it (it's plain JSON — `JSON.stringify` it) and hand it
@@ -168,37 +253,453 @@ back, but don't reach into it, since the shape is the editor's to evolve. Two wa
 get one:
 
 - **`createEmptyDocument(kind?)`** — a fresh blank document; `'email'` (the default) or
-  `'page'` decides what it compiles to.
+  `'page'`.
 - **`parseDocument(json)`** — the supported path from stored JSON back to a
   `Document`. Throws if the editor can't open it, so a corrupt row fails at your load
   boundary rather than deep inside the editor. Use what it returns, not what you
   passed in.
 
-### Theming
+## Document kinds: email and page
+
+The kind is a property of the *document*, not a mode of the editor — an editor opening
+a page document is the website builder for it. One licence, one embed, one save flow
+covers both, and both kinds can live in one store (the JSON carries its own kind).
+
+```js
+editor.document = createEmptyDocument('page')
+```
+
+What differs for a page: no email-size figure or spam warning (nothing clips a web
+page), Saved blocks are kept apart by kind, the HTML block accepts `<iframe>` embeds,
+and per-recipient conditions are unavailable (see
+[Dynamic content](#dynamic-content-per-recipient-blocks)). Everything else — blocks,
+columns, backgrounds, fonts, merge tags — behaves identically.
+
+## Saved blocks
+
+A Saved block is one block, with its whole subtree, lifted out of a document and kept
+by *you* under a name, for inserting into any document later. The editor stores
+nothing: you own the library.
+
+```js
+editor.config = {
+  ...config,
+  async saveBlock(saved) {          // the editor mints the whole record, id included
+    await api.saveBlock(saved)      // store it as given; `content` is opaque JSON
+    library = [...library, saved]
+    editor.savedBlocks = library    // reassigning is what makes it appear
+  },
+  async deleteSavedBlock(id) {
+    await api.deleteBlock(id)
+    library = library.filter((entry) => entry.id !== id)
+    editor.savedBlocks = library
+  },
+}
+
+// On load, validate stored rows at your boundary:
+editor.savedBlocks = rows.map(parseSavedBlock)
+```
+
+`id` and `name` are ordinary strings you can key rows by and show in your own admin;
+`content` is an opaque blob to write verbatim and hand back untouched. Resolving
+`saveBlock` does **not** put the block in the Saved tab — `savedBlocks` is the only
+truth the editor renders, so reassign it. A malformed or duplicate-id entry is dropped
+with a warning rather than taking down the editor. Entries are offered only in
+documents of the kind they were saved from.
+
+## Block plugins
+
+Custom block types — a video embed, a product card — registered per embed through
+`config.plugins`. A plugin owns a JSON `data` value per block, draws its own settings
+UI, and *bakes* that data into email HTML at edit time; the baked HTML is stored in the
+document and rendered verbatim, so our servers never run your code.
+
+```js
+const artifact = await import('https://static.example.com/plugins/acme.js')
+editor.config = { ...config, plugins: [artifact.createProductCardPlugin(apiBase)] }
+```
+
+Plugins are **loaded objects, not URLs** — you do the import, which keeps plugin
+deployment a static-file update that rebuilds nothing. The contract is `BlockPlugin`
+(`name`, `label`, `icon?`, `create`, `parse`, `email`, `settings`, `preview?`,
+`globalSettings?`); `name` is stored in every document that uses the block, so treat it
+as permanent and namespace it (`acme.product-card`). `email()` must be deterministic
+and `data` must be plain JSON — the editor re-bakes on load and on every change.
+
+## AI assistance
+
+The editor can offer authors AI help on the text they're writing — but it ships **the UI
+and none of the intelligence**. Every request goes to a callback you implement, against
+whatever model and account you choose. We hold no AI credential, meter no usage, and
+never see the content: the same division as `uploadImage`, where you own the storage and
+we own the experience.
+
+Supply no `ai` and there are no AI controls at all — the default for every embed.
+
+```js
+editor.config = {
+  ...config,
+  ai: {
+    // WHICH features this embed offers. The editor renders exactly this list, so turning
+    // one off means removing it here — there is no separate flag to keep in step.
+    actions: ['proofread', 'rewrite', 'shorten'],
+
+    // Called with the author's selection. Answer with the replacement text.
+    async run({ action, text, locale }) {
+      const res = await fetch('/api/ai', {           // YOUR endpoint, your model, your key
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ action, text, locale }),
+      })
+      if (!res.ok) throw new Error(`AI backend said ${res.status}`)
+      return (await res.json()).text
+    },
+  },
+}
+```
+
+**The four actions**, each text-in/text-out: `proofread` (fix spelling and grammar,
+keep the wording), `rewrite` (say it differently), `shorten`, `expand`. An action the
+editor doesn't know is dropped with a console warning, and an empty `actions` array
+means no controls — same as no `ai` at all.
+
+**What the author sees:** an AI button in the text toolbar listing exactly your declared
+actions. It runs on their selection, or on the whole block when nothing is selected. The
+button is disabled while a request is in flight.
+
+### Implementing the endpoint
+
+The callback is the easy half; the endpoint behind it is where the work is. Two rules
+shape everything below:
+
+> **Whatever you return is spliced into the author's email verbatim.** Not shown for
+> approval, not parsed for an answer — inserted. A model that helpfully replies *"Sure!
+> Here's the corrected text:"* puts that sentence in the email.
+
+> **Merge tags travel through as `{{tagId}}`.** The editor sends them as tokens and
+> rebuilds them as chips from whatever you return, so your prompt must instruct the model
+> to keep them **exactly** as-is. A model that "corrects" `{{firstName}}` to `{{ firstName }}`
+> or translates it breaks the personalization for that block.
+
+A worked Node endpoint, using the Anthropic SDK and structured outputs so the response
+*cannot* carry a preamble:
+
+```ts
+import Anthropic from '@anthropic-ai/sdk'
+import { zodOutputFormat } from '@anthropic-ai/sdk/helpers/zod'
+import { z } from 'zod'
+
+const client = new Anthropic() // reads ANTHROPIC_API_KEY — server-side only, never the browser
+
+// Structured output is the robust fix for the preamble problem: the model must fill this
+// schema, so there is nowhere for "Here's your text:" to live.
+const Result = z.object({ text: z.string() })
+
+const INSTRUCTIONS: Record<string, string> = {
+  proofread:
+    'Correct spelling, grammar and punctuation. Preserve the wording, tone and meaning — do not rephrase.',
+  rewrite:
+    'Rephrase to read more clearly and naturally. Preserve the meaning, tone and approximate length.',
+  shorten:
+    'Make it shorter while keeping every essential point. Aim for roughly half the length.',
+  expand:
+    'Add relevant detail in the same voice. Aim for roughly 1.5x the length.',
+}
+
+export async function handleAi(req, res) {
+  const { action, text, locale } = req.body
+  const instruction = INSTRUCTIONS[action]
+  if (!instruction) return res.status(400).json({ error: 'unknown action' })
+  if (text.length > 5000) return res.status(413).json({ error: 'selection too long' })
+
+  const message = await client.messages.parse({
+    model: 'claude-opus-5',
+    // These are short transforms on an email selection; a low cap bounds both latency
+    // and a runaway bill. Raise it if you allow long selections.
+    max_tokens: 4000,
+    system: [
+      `You edit marketing email copy. ${instruction}`,
+      `Reply in the same language as the input (the author is writing in "${locale}").`,
+      'Return ONLY the edited text — no commentary, no explanation, no quotes around it.',
+      'Preserve any {{merge_tag}} placeholders EXACTLY as they appear, including spelling and position.',
+      'Return plain text: no Markdown, no HTML.',
+    ].join(' '),
+    messages: [{ role: 'user', content: text }],
+    output_config: { format: zodOutputFormat(Result) },
+  })
+
+  res.json({ text: message.parsed_output?.text ?? text })
+}
+```
+
+**Clean what you return anyway.** Even with structured output, trim whitespace and strip
+matched surrounding quotes — models add them. If the result is empty, return the original
+text rather than an empty string; the editor treats an empty answer as nothing to do, but
+returning the input makes that explicit.
+
+### Security, cost and abuse
+
+- **Never put a model key in the browser.** The callback runs in your page — anything it
+  holds is public. Call your own authenticated endpoint, as above.
+- **Authenticate and authorise the endpoint** with the same session your app already
+  uses, and check the user may edit that document. Without it you've published an open
+  proxy to your model account.
+- **Rate limit per user**, not per IP — this is a button an author can hold down. A short
+  per-user quota (say N requests/minute) plus a max input length is enough.
+- **Cap the input**: reject selections beyond a size you're willing to pay for (the
+  editor sends the whole block when nothing is selected, so this is reachable by
+  accident).
+- **Log for support, not surveillance**: the action, size and outcome are enough to debug
+  "the AI button doesn't work"; the copy itself is your customer's content.
+
+### Failure and timeouts
+
+**Rejecting is a first-class outcome, not a bug.** The editor shows the author an error,
+logs your reason to the console, and leaves their text exactly as it was. Throw with a
+message worth reading — a quota refusal and a network blip shouldn't look the same to
+whoever supports the author:
+
+```js
+async run({ action, text, locale }) {
+  const res = await fetch('/api/ai', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ action, text, locale }),
+    signal: AbortSignal.timeout(20_000), // authors abandon a spinner long before a gateway does
+  })
+  if (res.status === 429) throw new Error('AI quota reached — try again in a minute')
+  if (!res.ok) throw new Error(`AI backend said ${res.status}`)
+  return (await res.json()).text
+}
+```
+
+### Testing without a model
+
+Wire a fake first — the editor can't tell the difference, and it's the fastest way to see
+the whole flow (including the failure path):
+
+```js
+ai: {
+  actions: ['proofread', 'rewrite', 'shorten', 'expand'],
+  run: async ({ action, text }) => {
+    await new Promise((r) => setTimeout(r, 400))     // see the pending state
+    if (text.includes('boom')) throw new Error('mock failure')
+    return `[${action}] ${text}`
+  },
+}
+```
+
+### Reference
+
+| | |
+| --- | --- |
+| `run` receives | `{ action, text, locale }` — `text` is plain text with merge tags as `{{tagId}}`; `locale` is the editor's current locale |
+| `run` returns | `Promise<string>` — the replacement text |
+| Applied as | plain text plus rebuilt merge-tag chips. **Formatting marks inside the replaced range are lost**; merge tags survive |
+| On rejection | author sees an error, console gets your reason, text is unchanged |
+| TypeScript | `AiAssistant`, `AiAction`, `AiRequest` are exported |
+
+## Dynamic content: per-recipient blocks
+
+A columns block in an **email** can carry a condition — a test on one merge tag that
+decides, per recipient, whether that block appears. Authors set it in the block's
+"Show to" controls; operators are `is` / `is not` (against one value) and
+`has any of` / `has none of` (against a list, matched as a comma-separated set).
+Pages have no conditions: a page is served, not sent, so there is no recipient to
+resolve against.
+
+**This affects your send pipeline.** A document using dynamic content compiles to HTML
+containing `{{!region_N}}` placeholders that must be resolved per recipient — the editor
+cannot resolve them, because it has no recipient. Resolving them needs the region list,
+which the editor's `compiled` string does not carry, so a pipeline that sends dynamic
+content compiles from the backend and substitutes per recipient:
+[the compile API](#the-compile-api).
+
+## Sending and publishing
+
+The editor only edits and previews. Turning a document into sendable HTML happens on
+our compile servers. There are two ways to reach them, and which you need depends on
+whether your documents use [dynamic content](#dynamic-content-per-recipient-blocks):
+
+- **The editor compiles while saving** — the `compiled` argument to
+  `config.saveDocument`. One complete HTML string. Sufficient on its own for documents
+  with **no** conditional blocks.
+- **Your backend compiles** — `POST /v1/compile`, below. Returns the same HTML **plus
+  the region list** that conditional blocks need. Required if you use dynamic content,
+  and the right call for a sendout pipeline generally: compile once per campaign, then
+  substitute per recipient.
+
+Store `document` and `compiled` **together, atomically**, and handle `compiled: null`
+(compile unavailable) by re-compiling later rather than pairing new JSON with stale
+HTML — that mismatch is how a send goes out with content the author no longer sees.
+
+### The compile API
+
+```http
+POST https://api.bygga.dev/v1/compile
+Authorization: Bearer <your licence key>
+Content-Type: application/json
+
+{ "document": { …the stored Document JSON, verbatim… } }
+```
+
+Your backend has no browser origin to attest, so it presents the **licence key** itself
+(the editor, in a browser, presents the token its activation already earned). The
+response:
+
+```jsonc
+{
+  // The whole standalone email or page. Merge tags appear as {{tagId}}; each
+  // conditional block appears as its own {{!region_N}}.
+  "html": "<!DOCTYPE html …>",
+
+  // One entry per conditional block, flat — a region's html never contains another
+  // region's placeholder, so substitution is a single unordered pass.
+  "regions": [
+    {
+      "placeholder": "{{!region_0}}",   // the exact string to find; never rebuild it yourself
+      "html": "<table>…</table>",       // the block's own HTML, may contain {{tagId}} of its own
+      "condition": {
+        "tagId": "company_id",
+        "operator": "equals",           // or notEquals | anyOf | noneOf
+        "value": "abc123"               // anyOf/noneOf carry "values": [...] instead
+      }
+    }
+  ]
+}
+```
+
+Failures answer `{ "error": "…" }` with the status carrying the retry semantics:
+**400** the document is invalid (permanent — never retry), **401** bad or missing
+credential, **413** body over the 4 MB cap, **429** rate limited, **503** busy, **500**
+our fault. Retry `5xx` and `429` (both send `retry-after`); never retry `4xx`.
+
+There is deliberately no list of merge-tag ids in the response — the string is the
+contract. See the tag-set rule below.
+
+### Substituting, per recipient
+
+Two passes, **regions first** (a region's HTML can contain merge tags of its own), then
+merge tags:
+
+```js
+function personalize({ html, regions }, values) {
+  let out = html
+  for (const region of regions) {
+    out = out.replaceAll(
+      region.placeholder,
+      matches(region.condition, values) ? region.html : '',
+    )
+  }
+  for (const [id, value] of Object.entries(values)) {
+    out = out.replaceAll(`{{${id}}}`, escapeHtml(value))
+  }
+  return out
+}
+
+// Equality: trim and lower-case BOTH sides; notEquals is exactly !equals, with no
+// special case for the empty string. Set membership: read the recipient's value as a
+// comma-separated set (trim + lower-case each element, drop empties); anyOf matches on
+// a non-empty intersection, noneOf is exactly !anyOf. Each pair therefore partitions
+// your audience — nobody receives a message with a hole in it.
+function matches(condition, values) {
+  const raw = values[condition.tagId] ?? ''
+  if (condition.operator === 'anyOf' || condition.operator === 'noneOf') {
+    const assigned = new Set(
+      raw.split(',').map((v) => v.trim().toLowerCase()).filter(Boolean),
+    )
+    const any = (condition.values ?? []).some((v) =>
+      assigned.has(v.trim().toLowerCase()),
+    )
+    return condition.operator === 'anyOf' ? any : !any
+  }
+  const equal =
+    raw.trim().toLowerCase() === (condition.value ?? '').trim().toLowerCase()
+  return condition.operator === 'equals' ? equal : !equal
+}
+```
+
+Three rules that have no error signal behind them, so build them in deliberately:
+
+1. **Which values to load.** Every `{{id}}` in `html` **and** in each `regions[].html`
+   — scan with `/\{\{([A-Za-z0-9._-]+)\}\}/g`, which skips region placeholders because
+   `!` is outside the id character class — **plus every `regions[].condition.tagId`**.
+   Condition tags are compared, never rendered: they appear in no HTML, so a scan alone
+   misses them, the comparison then runs against an empty string, and the block silently
+   shows for nobody.
+2. **Escape every value you splice.** Values land in raw markup and inside attributes;
+   an unescaped `<`, `&` or `"` breaks the markup or injects into it.
+3. **Lint before sending.** Anything still matching `/\{\{/` after both passes is a tag
+   you had no value for or a region you missed — it reaches the recipient as literal
+   text. Fail the send instead.
+
+### Pages
+
+A page compiles through the same endpoint and returns the same shape, substituted at
+serve time rather than send time; its `regions` array is always empty, since conditions
+are email-only. Its HTML ships with an empty `<title>` and no meta description — inject
+your own before serving — and it must never be sent as an email: it deliberately omits
+the email-client armour, and the document's kind is there so your send queue can refuse.
+
+## Theming
+
 Design tokens are CSS custom properties (`--bygga-*`) read through the shadow boundary,
 so a host retheme is just setting them on the element:
 
 ```css
-bygga-editor { --bygga-color-accent: #b00; }
+bygga-editor {
+  --bygga-color-accent: #b00;
+  --bygga-color-border: #333;
+  --bygga-radius-sm: 4px;
+  --bygga-font-family: 'Acme Grotesk', sans-serif; /* your page loads the face */
+}
 ```
 
+Tokens cover surfaces, text, accent, borders, warning/danger/success, radii, shadows,
+the tool-column width and the UI font. They restyle the editor's **chrome** only —
+what goes *into the document* is bounded by `brand`, not by the theme. High-contrast
+and forced-colors modes are handled behind the tokens and keep working under a retheme.
+
 ## TypeScript
 
 The package augments `HTMLElementTagNameMap`, so
 `document.querySelector('bygga-editor')` is typed as `ByggaEditorElement` — its
-properties, methods, and a typed `addEventListener` for `change` / `dirtychange`
-included.
-
-- **Types:** `Document`, `EditorConfig`, `Brand`, `BrandFont`, `BrandCustomFont`,
-  `MergeTags`, `MergeTagLabels`, `Locale`, `ByggaEditorElement`, `ByggaEditorEventMap`.
-- **Values:** `createEmptyDocument`, `parseDocument`, `SUPPORTED_LOCALES`,
-  `DEFAULT_LOCALE`, `EDITOR_TAG`, and `ByggaEditor` (the element constructor,
-  already registered on import).
-
-## Rendering to email
-
-The editor only edits and previews. Turning a saved document into sendable,
-email-client-safe HTML is done for you: the editor compiles while saving and hands it to
-`config.saveDocument(document, compiled)` as one standalone HTML string with `{{tag}}`
-placeholders. Substitute them with a find-and-replace at send time — escaping each value
-yourself, since they are spliced in raw.
+properties, methods, and a typed `addEventListener` for `change` / `dirtychange` /
+`licenseerror` included.
+
+- **Types:** `Document`, `EditorConfig`, `ByggaEditorElement`, `ByggaEditorEventMap`,
+  `Brand`, `BrandFont`, `BrandCustomFont`, `MergeTags`, `MergeTagEntry`,
+  `MergeTagLabels`, `MergeTagOption`, `SavedBlock`, `SavedBlockContent`, `BlockPlugin`,
+  `BlockPluginSettingsContext`, `BlockPluginGlobalsContext`,
+  `BlockPluginGlobalSettings`, `AiAssistant`, `AiAction`, `AiRequest`, `Locale`,
+  `LicenseError`, `LicenseErrorReason`.
+- **Values:** `createEmptyDocument`, `parseDocument`, `parseSavedBlock`,
+  `SUPPORTED_LOCALES`, `DEFAULT_LOCALE`, `EDITOR_TAG`, and `ByggaEditor` (the element
+  constructor, already registered on import).
+
+## Framework integration
+
+`config`, `document`, `mergeTags`, `brand` and `savedBlocks` are **JS properties**, not
+attributes — objects and arrays can't pass through HTML attributes. Frameworks that set
+attributes by default need a ref.
+
+```jsx
+// React
+function Editor({ doc, onChange }) {
+  const ref = useRef(null)
+  useEffect(() => {
+    const el = ref.current
+    el.config = { uploadImage }        // set before it matters; el is already connected
+    el.document = doc
+    const handler = (e) => onChange(e.detail[0])
+    el.addEventListener('change', handler)
+    return () => el.removeEventListener('change', handler)
+  }, [doc, onChange])
+  return <bygga-editor ref={ref} license-key="bk_live_…" style={{ height: '100vh' }} />
+}
+```
+
+In **Vue**, `:config`, `:document` and `@change` work directly on the element (mark it
+as a custom element in your build config). In **Angular**, use property binding
+(`[config]`) with `CUSTOM_ELEMENTS_SCHEMA`. In plain HTML, create the element, assign
+the properties, then append it — the order in [Quick start](#quick-start).