@bygga.dev/editor 1.8.3 → 1.9.3

package/README.md

@@ -105,6 +105,15 @@ 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`.
 
+### `permission` attribute
+What this user may do with [locked blocks](#locked-blocks): `admin` (may lock, unlock,
+and edit a locked block like any other) or `creator` (a content creator: may edit the
+text inside a locked block and nothing else about it). Reactive; settable as the
+attribute or the `.permission` property. **Absent — or anything unrecognised — is
+`creator`**, the permission that can do least, so an embed that never mentions it offers
+no lock controls at all, and a typo'd `admn` warns rather than handing every user the
+keys.
+
 ### `config` property *(required)*
 Host callbacks. Assign it **before** connecting the element (the editor throws at
 mount if `uploadImage` is missing). It's a plain object, re-read on assignment, so
@@ -176,10 +185,11 @@ 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**. 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.
+The colours and fonts your embed permits, the look new blocks start with, values for
+your block plugins, and which block tiles to offer — a **menu, never a rewrite of a
+document**. It bounds and seeds what is added 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 = {
@@ -224,7 +234,56 @@ never appears. Set `type: 'file'` on those:
 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
+must not take down your editor.
+
+#### Block styles, plugin values and hidden tiles
+
+```js
+editor.brand = {
+  ...brand,
+  // The look a newly placed Header, Text or Button block starts with. Every field is
+  // optional. `font` is an email-safe face or the `name` of one of your customFonts;
+  // `fontSize` is one of 10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 48; colours are hex.
+  styles: {
+    header: { font: 'georgia', fontSize: 32, color: '#2f2a72', bold: true,
+              align: 'center', level: 2, padding: 8, background: '#ffffff',
+              margin: { top: 0, right: 0, bottom: 16, left: 0 } },
+    text:   { font: 'arial', fontSize: 16, color: '#333333', align: 'left',
+              paragraphSpacing: 8 },
+    button: { background: '#2f2a72', textColor: '#ffffff', font: 'arial',
+              fontSize: 16, bold: true, align: 'center',
+              padding: { top: 12, right: 24, bottom: 12, left: 24 },
+              // One number rounds every corner; name the corners for a shape.
+              borderRadius: { topLeft: 0, topRight: 12, bottomRight: 0, bottomLeft: 0 },
+              border: { width: 2, color: '#064c70', style: 'solid' } },
+  },
+  // Anything your block plugins read to style their own blocks (see Block plugins).
+  custom: { cardRadius: 8, accent: '#a28c67' },
+  // Block tiles not to offer: built-in types and/or plugin names.
+  hiddenBlocks: ['html', 'acme.legacy-banner'],
+}
+```
+
+Each style can also set the block's box — `margin` and `padding` (a number or
+`{ top, right, bottom, left }`), `borderRadius` (a number, or
+`{ topLeft, topRight, bottomRight, bottomLeft }`), and `border`
+(`{ width, color?, style? }`, `style` one of `solid`, `dashed`, `dotted`) — plus
+`underline` for header and text, and `paragraphSpacing` (`0`, `4`, `8`, `12`, `16`,
+`20`, `24` or `32` px) for text.
+
+A style is a **starting value, written into the block when it is placed** — exactly as
+if the author had chosen each setting by hand. Revising your Brand changes the blocks
+placed next, never the ones already in your documents, and the compiled email knows
+nothing about Brands. A header's title and a button carry their whole style from the
+moment they appear; a text block is placed with its alignment, background and padding,
+and the face, size, colour and weight are applied to what the author types into an
+empty paragraph (a mark needs text to sit on). The author can change any of it
+afterwards, as with any block.
+
+A hidden tile only narrows the menu: a hidden block type already in a document still
+renders and edits. An entry naming neither a built-in type nor a registered plugin is
+warned about, as is any style field the editor can't use — that field is dropped and
+the rest of the style kept. 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
@@ -235,7 +294,7 @@ carries what it uses, so it keeps rendering even if you later change the registr
 ### `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.
+the Saved blocks section renders; the editor keeps no library of its own.
 
 ### Events
 Events do not bubble — listen on the element itself.
@@ -246,6 +305,34 @@ Events do not bubble — listen on the element itself.
   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.
+- **`autosave`** — fired when the author pauses after editing (about five seconds of
+  quiet), or after about thirty seconds of editing without a pause; `event.detail[0]`
+  is `{ document, digest }`. Never per keystroke (that is `change`), never for a
+  document with nothing unsaved, and never twice for the same content. The editor saves
+  nothing itself: persist the payload and call `markSaved()`, or call `save()` to store
+  it with its compiled HTML — though each `save()` spends a compile from your licence's
+  quota. Edits made within the last pause have not autosaved yet, so guard page exits
+  with `isDirty()` (a `beforeunload` handler) rather than relying on the event alone.
+
+  `digest` fingerprints the document's *content* — SHA-256, as lowercase hex, over its
+  [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) canonical JSON — so you can skip a
+  write when you already hold that content (another tab saved it, or your last save
+  did). Equal content always has an equal digest, whatever order your storage keeps the
+  keys in. Keep the digest of what you last stored, or compute it for any document with
+  the exported `documentDigest(document)`; a backend can compute the same value with any
+  JCS library.
+
+  ```js
+  import { documentDigest } from '@bygga.dev/editor'
+
+  let storedDigest = await documentDigest(storedDocument)
+  editor.addEventListener('autosave', async (event) => {
+    const [{ document, digest }] = event.detail
+    if (digest === storedDigest) return        // already saved — nothing changed
+    await api.saveDraft(document)
+    storedDigest = digest
+  })
+  ```
 - **`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
@@ -321,11 +408,15 @@ 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
+`saveBlock` does **not** put the block in the library — `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.
 
+The library appears under the block tiles, in view whenever they are. A Saved block
+keeps any [lock](#locked-blocks) it was saved with, so an admin can curate locked
+sections — a masthead, a legal footer — for content creators to drop in.
+
 ## Block plugins
 
 Custom block types — a video embed, a product card — registered per embed through
@@ -345,6 +436,45 @@ deployment a static-file update that rebuilds nothing. The contract is `BlockPlu
 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.
 
+**The Brand reaches a plugin where it chooses values.** `create(context)` receives
+`context.brand` — your Brand after validation: `colors`, `fonts`, `customFonts`,
+`styles`, `custom` (whatever you put in `brand.custom`), and `css`, the block styles
+as ready-to-use CSS — so a new block can start on your look; the settings contexts
+carry the same `brand`, to offer your palette or a "reset to brand". `css.header`
+is how a custom header of your own takes the look the Brand gives the built-in one:
+`css.header.cssText` is a string like `font-family:Georgia, 'Times New Roman', serif;font-size:32px`
+to write into your heading's `style` (escape it like any attribute value), with each
+property also available on its own. A custom font written there is carried into the
+compiled email automatically, as long as your baked HTML names it. Copy what you use into the block's `data`: `email()` and `preview()`
+deliberately do not receive the Brand, because a block's HTML must follow from its
+stored data alone — otherwise the same document would bake differently in two embeds,
+and revising your Brand would silently rewrite every document it touched.
+
+```js
+create(context) {
+  return { title: '', accent: context.brand.custom.accent ?? context.brand.colors[0] }
+},
+```
+
+## Locked blocks
+
+An admin can **lock** a columns block from its settings. For a content creator (the
+`creator` [permission](#permission-attribute)) a locked block is fixed: it can't be
+moved, duplicated, removed, restyled or relaid out, nothing can be added to or taken
+out of it, and its images, buttons and other blocks can't be changed — but **the text
+inside it stays editable** — including a button's label, and whether it is bold,
+through the button's own cut-down settings. A block that *holds* a locked block can't be moved,
+duplicated, removed or hidden (per device or per recipient) by a creator either, since
+that would take the lock with it, and a layout change that would drop a column holding
+one isn't offered. An admin edits
+locked blocks like any other and sees the same "Locked" marker.
+
+The lock is stored on the block (`locked: true`) and travels with the document and
+with Saved blocks. It is **guidance for the people editing, not a security boundary**:
+the editor enforces it in its own UI, but you receive the whole document on every
+save, so anything that must hold against a determined user has to be checked where
+you store documents.
+
 ## AI assistance
 
 The editor can offer authors AI help on the text they're writing — but it ships **the UI
@@ -363,7 +493,7 @@ editor.config = {
     // 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.
+    // Called once per paragraph of the author's selection. Answer with its replacement text.
     async run({ action, text, locale }) {
       const res = await fetch('/api/ai', {           // YOUR endpoint, your model, your key
         method: 'POST',
@@ -383,8 +513,11 @@ editor doesn't know is dropped with a console warning, and an empty `actions` ar
 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.
+actions. It runs on their selection, or on the whole block when nothing is selected, one
+paragraph at a time: each paragraph or heading is its own `run` call, all sent at once, so
+a block keeps its paragraphs, heading level, line breaks and styling. The answers land
+together as one undo step, around anything the author typed while waiting. The button is
+disabled while requests are in flight.
 
 ### Implementing the endpoint
 
@@ -432,29 +565,28 @@ export async function handleAi(req, res) {
   if (text.length > 5000) return res.status(413).json({ error: 'selection too long' })
 
   const message = await client.messages.parse({
-    model: 'claude-opus-5',
+    model: 'claude-opus-5-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}").`,
+      `Reply in the same language as the input (the author's interface language is "${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.',
+      'Return plain text: no Markdown, no HTML. Keep line breaks where they are; add none.',
     ].join(' '),
     messages: [{ role: 'user', content: text }],
     output_config: { format: zodOutputFormat(Result) },
   })
 
-  res.json({ text: message.parsed_output?.text ?? text })
+  res.json({ text: message.parsed_output?.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.
+matched surrounding quotes — models add them. An empty answer, or the text unchanged, is
+nothing to do: the editor leaves that paragraph exactly as it was, formatting included.
 
 ### Security, cost and abuse
 
@@ -463,18 +595,19 @@ returning the input makes that explicit.
 - **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).
+- **Rate limit per user**, not per IP — this is a button an author can hold down, and one
+  click sends one request per paragraph, all at once. Allow a burst (say ten) inside a
+  short per-user quota, plus a max input length.
+- **Cap the input**: reject a paragraph beyond a size you're willing to pay for — one long
+  paragraph is still one request.
 - **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
+logs your reason to the console, and leaves their text exactly as it was — every paragraph
+of it, since an action's answers land together or not at all. Throw with a
 message worth reading — a quota refusal and a network blip shouldn't look the same to
 whoever supports the author:
 
@@ -512,9 +645,9 @@ ai: {
 
 | | |
 | --- | --- |
-| `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 |
+| `run` receives | `{ action, text, locale }`, once per paragraph in range, all at once — `text` is that paragraph's plain text with merge tags as `{{tagId}}` and line breaks as `\n`; `locale` is the editor's interface language |
+| `run` returns | `Promise<string>` — the paragraph's replacement text |
+| Applied as | plain text in the paragraph's main formatting, with merge-tag chips and line breaks rebuilt; every paragraph in one undo step. **Formatting within a paragraph is flattened**; merge tags survive; an empty or unchanged answer changes nothing |
 | On rejection | author sees an error, console gets your reason, text is unchanged |
 | TypeScript | `AiAssistant`, `AiAction`, `AiRequest` are exported |
 
@@ -684,17 +817,22 @@ and forced-colors modes are handled behind the tokens and keep working under a r
 The package augments `HTMLElementTagNameMap`, so
 `document.querySelector('bygga-editor')` is typed as `ByggaEditorElement` — its
 properties, methods, and a typed `addEventListener` for `change` / `dirtychange` /
-`licenseerror` included.
+`autosave` / `licenseerror` included.
 
 - **Types:** `Document`, `EditorConfig`, `ByggaEditorElement`, `ByggaEditorEventMap`,
-  `Brand`, `BrandFont`, `BrandCustomFont`, `MergeTags`, `MergeTagEntry`,
-  `MergeTagLabels`, `MergeTagOption`, `SavedBlock`, `SavedBlockContent`, `BlockPlugin`,
+  `AutosaveDetail`,
+  `Brand`, `BrandFont`, `BrandCustomFont`, `BrandStyles`, `BrandTextStyle`,
+  `BrandHeaderStyle`, `BrandButtonStyle`, `BrandBox`, `BrandCorners`, `BrandBorder`,
+  `BrandBlockType`, `Permission`,
+  `MergeTags`, `MergeTagEntry`, `MergeTagLabels`, `MergeTagOption`, `SavedBlock`,
+  `SavedBlockContent`, `BlockPlugin`, `BlockPluginCreateContext`, `BlockPluginBrand`,
+  `BlockPluginStyleCss`,
   `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).
+  `documentDigest`, `SUPPORTED_LOCALES`, `DEFAULT_LOCALE`, `EDITOR_TAG`, and
+  `ByggaEditor` (the element constructor, already registered on import).
 
 ## Framework integration