efficient-easel 0.0.0 → 0.96.0

package/README.md

@@ -1,6 +1,725 @@
 # efficient-easel
 
-Reserved by Efficient Pty Ltd for Efficient Easel, the EFFICIENT editors' engine,
-published as `efficient-editor` up to 0.95.0. This 0.0.0 release only holds the
-name; do not install it. Real releases under this name start at 0.96.0 and are
-published by CI.
+**Efficient Easel** is the engine under every EFFICIENT editor. An easel holds
+the canvas and has no say in what is painted on it: the engine never learns
+what a section is, and each editor brings its own blocks and its own data.
+
+The EFFICIENT editors' shared engine and chrome — the campaign designer
+(`efficient-admin-portal`) and the website editor (`efficient-shop`) draw from
+one source instead of hand-rolling and drifting — and the engine both run on,
+which replaced Puck (`@measured/puck`) layer by layer and has carried none of
+it since 0.93.0.
+
+> **Published as `efficient-easel`** on public npm from 0.96.0 (it was
+> `efficient-editor` from 0.69.0 to 0.95.0, and `editor-shell` up to 0.66.0).
+> Released by CI from a GitHub Release — see [PUBLISHING.md](./PUBLISHING.md).
+> Moving from the old name without touching an import:
+> `"efficient-editor": "npm:efficient-easel@^0.96.0"`.
+
+## Why
+
+The storefront editor (`efficient-shop`, Next 16 + Puck) and the campaign
+designer (`efficient-admin-portal`, Vite/React) each hand-rolled their own narrow
+left icon-rail. They had already drifted — button 34px vs 36px, icon 18px vs
+20px, radius 9 vs 8, a CSS-var accent vs a Tailwind one. `EditorRail` is the one
+rail they converge on.
+
+## The leaf
+
+The storefront's editor chrome renders in **Next-16 server components**, so the
+rail is a **self-contained leaf** at `efficient-easel/rail`: it imports nothing heavy
+and touches no `document` / `window` / `localStorage` at import or render, so a
+server component can pull it in safely. `tests/rail-leaf-safety.test.tsx` proves
+it.
+
+```tsx
+// A client component in any editor:
+'use client';
+import {
+  EditorRail,
+  PagesIcon, LayersIcon, StylesIcon, MediaIcon, SitemapIcon, AddIcon,
+} from 'efficient-easel/rail';
+import 'efficient-easel/rail.css'; // once, from a client/global entry
+
+export function LeftRail({ view, onView, onAdd }) {
+  return (
+    <EditorRail
+      ariaLabel="Left panel views"
+      items={[
+        { id: 'pages',  label: 'Pages',  icon: <PagesIcon />,  active: view === 'pages',  onSelect: () => onView('pages') },
+        { id: 'layers', label: 'Layers', icon: <LayersIcon />, active: view === 'layers', onSelect: () => onView('layers') },
+        { id: 'styles', label: 'Styles', icon: <StylesIcon />, active: view === 'styles', onSelect: () => onView('styles') },
+        { id: 'media',  label: 'Media',  icon: <MediaIcon />,  onSelect: onOpenMedia },
+        { id: 'add',    label: 'Add page', icon: <AddIcon />,  onSelect: onAdd },
+      ]}
+    />
+  );
+}
+```
+
+## API
+
+### `<EditorRail items ariaLabel? className? orientation? />`
+
+A **pure presentational** toolbar. It owns the look, never the app state — you
+decide which item is `active` and what each `onSelect` does.
+
+| prop | type | default | notes |
+|---|---|---|---|
+| `items` | `EditorRailItem[]` | — | buttons, in render order |
+| `ariaLabel` | `string` | `"Editor"` | names the toolbar for assistive tech |
+| `className` | `string` | — | merged onto `.es-rail` |
+| `orientation` | `'column' \| 'row'` | `'column'` | which way the buttons run |
+
+#### `orientation`
+
+`'column'` is the rail every editor draws today: a fixed 46px strip wearing its
+own card. It is the default, and it renders exactly what it rendered before this
+prop existed.
+
+`'row'` lays the same buttons left to right for a top bar — **no fixed width**
+(as wide as its buttons) and **no card** (no background, radius or shadow),
+because the bar already has its own surface. The button size, icon size, gap and
+every hover/active colour are identical in both directions; only the container
+changes. A row is 34px tall, so a 52px bar centres it with 9px to spare.
+
+```tsx
+// The same rail, in the top bar's empty middle.
+<EditorRail orientation="row" ariaLabel="Editor views" items={items} />
+```
+
+`aria-orientation` follows the layout (`vertical` / `horizontal`); the `toolbar`
+role does not change, because a rail that mixes view toggles with plain actions
+is a toolbar whichever way it runs.
+
+### `EditorRailItem`
+
+```ts
+interface EditorRailItem {
+  id: string;            // React key + selection correlation
+  label: string;         // aria-label + hover title
+  icon: React.ReactNode; // an 18px currentColor glyph — use the shipped icons
+  active?: boolean;      // present ⇒ view toggle (renders aria-pressed); omit for actions
+  disabled?: boolean;
+  onSelect?: () => void;
+}
+```
+
+A **view item** passes `active: true | false` and renders as a toggle
+(`aria-pressed`, `.is-active` highlight). An **action item** (the quick-add "+")
+omits `active` and renders as a plain button.
+
+`EditorRailButton` — the single-button building block `EditorRail` maps to — is
+exported too, for bespoke layouts.
+
+## Tokens
+
+The same values, two ways — `railTokens` (JS) and `rail.css` (CSS custom
+properties on `.es-rail`). Taken verbatim from the storefront editor's `.sf-rail`
+(the visual reference).
+
+| token | value | CSS var |
+|---|---|---|
+| rail width | `46px` | `--es-rail-w` |
+| rail padding (y) | `8px` | `--es-rail-pad-y` |
+| button gap | `4px` | `--es-rail-gap` |
+| rail radius | `12px` | `--es-rail-radius` |
+| button size | `34px` | `--es-rail-btn-size` |
+| button radius | `9px` | `--es-rail-btn-radius` |
+| icon size | `18px` | `--es-rail-icon-size` |
+| background | `#ffffff` | `--es-rail-bg` |
+| idle icon | `#6b7280` | `--es-rail-fg` |
+| hover bg / fg | `#f3f4f6` / `#111827` | `--es-rail-hover-bg` / `--es-rail-hover-fg` |
+| accent (active) | `#2563eb` | `--es-rail-accent` |
+| accent tint (active bg) | `#eff6ff` | `--es-rail-accent-tint` |
+
+`orientation="row"` adds **no new token**. It re-points three of the ones above
+— `--es-rail-bg` to `transparent`, `--es-rail-shadow` to `none`,
+`--es-rail-radius` to `0` — so the card look stays declared in one place, and it
+reuses `--es-rail-pad-y` rotated onto the row's ends and `--es-rail-gap` as-is.
+
+Re-theme without new CSS by overriding a var on the element:
+`style={{ ['--es-rail-accent']: brand }}`.
+
+## The gold layer — type in place
+
+`GoldTextInput` (subpath `efficient-easel/gold`, added in 0.3.0) is the surface a
+merchant types INTO on the page, with the markup formatting appearing as they
+type. A textarea whose own text is transparent sits on top of a layer holding the
+same characters, painted; what you read is the layer, what the caret walks is the
+box. Both inherit their type from whatever the host renders them inside, so the
+glyphs land on top of each other.
+
+It is **controlled and writes nothing** — no document, no sections, no Puck. The
+host owns the string and decides what a finished edit means.
+
+```tsx
+'use client';
+import { GoldTextInput } from 'efficient-easel/gold';
+import { STOREFRONT_MARKUP } from 'efficient-easel/markup';
+import 'efficient-easel/gold.css'; // once, from a client/global entry
+
+<GoldTextInput
+  value={draft}
+  rules={STOREFRONT_MARKUP}
+  placeholder="Add a heading"
+  ariaLabel="Section heading"
+  onInput={setDraft}
+  onCommit={(value) => save(value)}   // blur, or Enter on a single-line field
+  onCancel={(restored) => setDraft(restored)}
+/>;
+```
+
+| prop | type | default | notes |
+|---|---|---|---|
+| `value` | `string` | — | the authored string, delimiters and all |
+| `onInput` | `(value: string) => void` | — | every keystroke; the layer repaints from what you send back |
+| `onCommit` | `(value: string) => void` | — | blur, or Enter when `multiline` is false. Once per session, never if nothing was typed |
+| `onCancel` | `(restored: string) => void` | — | Escape. The argument is the value held at focus time; the host puts it back |
+| `multiline` | `boolean` | `false` | what Enter means, **not** how the text wraps — both modes wrap |
+| `placeholder` | `string` | — | visible until the first keystroke |
+| `className` | `string` | — | merged onto `.es-gold` |
+| `rules` | `readonly InlineRule[]` | `STANDARD_MARKUP` | pass your product's set — `STOREFRONT_MARKUP` / `CAMPAIGN_MARKUP` |
+| `ariaLabel` | `string` | — | in-place editing has no visible label |
+
+**The grammar is ours, and there is one.** Runs are parsed by
+`efficient-easel/markup`, which this package owns since 2026-09-28 (it started as
+`efficient-shell/markup`). The published page and the campaign email render from
+the same module, so a toolbar button, a page and this box can never disagree
+about what a delimiter means. It is framework-free and imports nothing. See
+[the text grammar](#the-text-grammar--efficient-easelmarkup) below.
+
+**Two deliberate limits.** The asterisks are FADED, never removed. They go to
+nothing while the box is unfocused, so a merchant who is not typing does not read
+`**` in their own page text, and they come back dimmed while the caret is in the
+box — but the characters stay in the layer at their full width in both states.
+Actually removing them needs a second text engine, and is out of scope. And the
+layer only paints what cannot move a glyph: colour, opacity, decoration, a
+faux-bold shadow. A real `font-weight: 600` is wider, so a marked line would wrap
+earlier than the transparent box on top of it and every following line would be
+drawn over the wrong text. The real weight and slant appear on the page the
+moment the merchant clicks away.
+
+## The text grammar — `efficient-easel/markup`
+
+The ONE rule for copy a merchant types, in both editors, on the page and in the
+email. Framework-free: no React, no DOM, no imports.
+
+| Mark | Means | Written by a button |
+|---|---|---|
+| `**x**` | **Strong** (bold) | yes, ⌘B |
+| `==x==` | **Emphasis** (the brand accent) | yes |
+| `^^x^^` | **Quiet** | yes |
+| `_x_` | italic, only at a word edge | yes |
+| `~~x~~` | strikethrough | yes |
+| `[words](href)` | a link — `http`, `https`, `mailto`, `tel` or no scheme only | yes |
+| `- ` at the start of a line | a bullet line, one level | yes |
+| `@@x@@`, `++x++` | Emphasis, Strong (the storefront's old word styles) | no — read only |
+| `*x*`, `#x#`, `[x]` | legacy accent, bold, italic (per product set) | no — read only |
+
+The three names a merchant sees are in `MARK_NAMES`. A run never crosses a line
+break, and a run may hold one more run or link (`**bold _with italic_**`); a third
+level stays as typed.
+
+| Export | Notes |
+|---|---|
+| `parseMarkup(value, rules)` → `MarkupLine[]` | The whole grammar as a tree. Each run keeps the delimiters that were saved. |
+| `serializeMarkup(lines)` | The inverse: `serializeMarkup(parseMarkup(s, rules)) === s`, for every string. Pinned by `tests/markup-round-trip.test.ts` (made-up strings in the shape of saved copy). All 917 saved production strings were checked once, off-repo, on 2026-09-29 (editor-shell #89). |
+| `isSafeLinkHref(href)` | The link rule. Call it before writing any `href`. |
+| `tokenizeInline(value, rules)`, `stripInline` | The flat reading older renderers use: runs only, no links, no nesting. |
+| `applyMark(text, start, end, style)`, `MARKUP_TOOLS`, `markupTools`, `COPY_FIELD_TOOLS` | The writer behind a toolbar button, and the button descriptors. |
+| `STANDARD_MARKUP`, `STOREFRONT_MARKUP`, `CAMPAIGN_MARKUP` | The rule sets. The last two add each product's legacy runs. |
+
+## The edit lock — two operators, one document
+
+`efficient-easel/edit-lock` (added in 0.32.0) is the answer to "is the save path
+allowed to run", shared by every editor in the house. It is pure TypeScript: no
+React, no browser global, no dependency at all, so a server component may import
+it.
+
+It exists because the storefront editor and the campaign designer had written
+the same rules twice, in two repos, and the two copies had already drifted — the
+take-over half only existed on one side and the claim driver only on the other.
+Both are here now, and neither editor keeps a copy.
+
+```ts
+import { createEditLock, canWriteDocument, documentPermissions } from 'efficient-easel/edit-lock';
+
+// The only two things that differ between one editor and the next.
+export const pageEditLock = createEditLock({
+  readFailure: (err) =>
+    err instanceof ApiError ? { status: err.status, data: err.data } : null,
+  conflictCode: 'page_changed_elsewhere',
+});
+```
+
+The plain half needs no binding: `canWriteDocument`, `holderOf`,
+`readLockHolder`, `accessForNewDocument`, `documentPermissions`, `describeAge`,
+`nameOrSomeone`, `newEditorClientId`, `shouldReleaseHeldWrite`,
+`shouldReloadAfterTakeover`, `documentVersionMoved`, `reloadIfVersionMoved`.
+The bound half —
+`accessAfterClaimFailure`, `accessAfterTakeoverFailure`,
+`accessAfterHeartbeatFailure`, `isAuthRejection`, `readSaveConflict`,
+`readLockTaken`, `makeClaimBeat` — comes back from `createEditLock`.
+
+**A take-over stops the other tab at its next save** (0.77.0). A document write
+that carries the tab's `client_id` (the one its claim sends) is refused with
+`EDIT_LOCK_TAKEN` once somebody else has taken the document from that tab.
+`readLockTaken` reads the holder out of that refusal: set `takenover` and HOLD
+the edit, never retry it as a failed save. The other half is the taker's: when
+a take-over is granted and nothing of theirs is waiting (`shouldReloadAfterTakeover`,
+or `makeClaimBeat`'s optional `reloadIfMoved`), load the stored copy if it moved
+while they could only look (`reloadIfVersionMoved`, which re-checks that nothing
+was typed while the version was being read).
+
+**Two things this module will not do.** It never takes the ability to edit away
+because a courtesy call failed: every claim failure that is not a 409 naming a
+holder falls back to `editing`, because the save-time version check is what
+actually protects the work. And a failed TAKE-OVER is a different question from a
+failed first claim — it keeps the state it was pressed from, so a take-over that
+did not land never puts two people in one document with the holder untold.
+
+## The editor frame — top bar, panels, inspector head
+
+`efficient-easel/chrome` (added in 0.41.0) is the frame both editors wear: the 52px
+top bar and its three clusters, the icon-only device switch, the save pill, flat
+side panels with drag grips, and the inspector head. Every part is controlled —
+the editor owns the device, the save status, the widths and which panels are open.
+
+```tsx
+import {
+  EditorTopBar, TopBarCluster, TopBarDivider, EditorIconButton, DeviceSwitch,
+  SaveState, PanelResizeHandle, InspectorHead, DEFAULT_PANEL_W, panelWidthVars,
+} from 'efficient-easel/chrome';
+import 'efficient-easel/chrome.css'; // once, after shell.css
+
+<div className="es-editor" style={panelWidthVars(widths)}>   {/* the vars go on the ROOT */}
+  <EditorTopBar>
+    <TopBarCluster kind="rail"><EditorRail orientation="row" items={items} /></TopBarCluster>
+    <TopBarCluster>
+      <EditorIconButton label="Undo" onClick={undo}><UndoIcon /></EditorIconButton>
+      <TopBarDivider />
+      <DeviceSwitch devices={devices} value={device} onChange={setDevice} />
+    </TopBarCluster>
+    <TopBarCluster kind="right">
+      <SaveState tone="saved" label="" />
+      <button className="es-btn-primary">Done</button>
+    </TopBarCluster>
+  </EditorTopBar>
+  …
+</div>
+```
+
+## The Layers tree — one row at every depth
+
+`efficient-easel/tree` (added in 0.42.0) is the Layers tree both editors draw. Every
+row has the same shape; only `Subtree` says depth.
+
+```tsx
+import { LayersTree, TreeGroupLabel, Subtree, TreeRow, TreeRowAction } from 'efficient-easel/tree';
+import 'efficient-easel/tree.css';
+
+<LayersTree>
+  <TreeGroupLabel>Body</TreeGroupLabel>
+  <TreeRow icon={<SectionGlyph />} name="Section" preview="FUSION FORGED · GTS-8"
+    selected fold={{ open, label: 'section', onToggle }}
+    actions={<TreeRowAction kind="eye" label="Hide Section" onClick={hide}><EyeIcon /></TreeRowAction>} />
+  <Subtree>
+    <TreeRow icon={<TextLinesIcon />} name="Text" preview="BACK IN STOCK NOW" />
+  </Subtree>
+</LayersTree>
+```
+
+## Copy style, paste style — one rule for both editors
+
+`efficient-easel/style-clipboard` (added in 0.50.0) is the right-click menu's
+**Copy style** / **Paste style from …** pair (⌥⌘C / ⌥⌘V, Ctrl+Alt+C / Ctrl+Alt+V).
+The host says which of a node's rows are Style or Layout and saves the new props
+through its own op; everything else is here, once:
+
+```ts
+import { copyStyle, heldStyle, planPaste, pasteMessage, styleMenuItems, styleShortcut, fieldKind, withStyleKind } from 'efficient-easel/style-clipboard';
+
+copyStyle({ scope: `site:${siteId}`, type, label, rows, props });   // rows: { path, kind }[]
+const held = heldStyle(`site:${siteId}`);                            // null in any other scope
+const plan = planPaste(held, { type, rows, props });                 // → { props, pasted, changed }
+toast(pasteMessage(plan, held.sourceLabel, label));                  // "Pasted 4 settings from Heading."
+```
+
+A row pastes only when the **key and the kind** match (`fieldKind`: a tagged
+factory's kind, `number`/`text`, or a choice row's control plus the values it
+offers). Two **choice** rows of the same control are the same setting, and the
+value decides: it pastes when the target offers it (0.51.0). A row whose kind is
+unknown pastes only between two components of the same type. An empty
+(inherited) value pastes as empty, so the target inherits too.
+
+## The document — `efficient-easel/data`
+
+`efficient-easel/data` (added in 0.67.0) is the bottom layer of the engine that
+replaces Puck (the blueprint's step 1.1): the saved document as pure
+functions. It imports nothing and touches no browser global, so the editor's
+store, a Next server component, a Node script and a test all call the same
+code.
+
+**The format does not change.** A document is exactly what Puck 0.20 saves —
+`{ root: { props }, content: [...], zones: {} }`, with a block's children
+inline in its slot props — so no campaign or page migrates when Puck goes.
+
+```ts
+import { normalizeData, find, insert, move, remove, duplicate, setProps, setRoot, createNode, walk, ROOT_LIST } from 'efficient-easel/data';
+
+const doc = normalizeData(saved, config);                 // what the editor does on open
+const at = find(doc, config, id);                         // { node, place, path } | null
+let next = insert(doc, config, { ...ROOT_LIST, index: 2 }, createNode(config, 'EmailSection'));
+next = move(next, config, id, { parentId: sectionId, slot: 'col2', index: 0 });
+next = duplicate(next, config, id, { strip: releaseBakedImage });
+next = setProps(next, config, id, { level: 3 });
+```
+
+| Export | Notes |
+|---|---|
+| `normalizeData(data, config)` | Puck's load: missing top-level slots become `[]`, `zones` becomes `{}`, the root's `defaultProps` fill what is missing. Older formats (props written on `root`, children parked in `zones`) are converted the way Puck's `migrate()` converts them. **A document already in shape comes back as the same object.** |
+| `find`, `walk`, `slotsOf`, `getList` | Read. `walk` visits parent before children, slots in declaration order; returning a node from the visitor replaces it. |
+| `insert`, `move`, `remove`, `duplicate` | Change the tree. `move` within one list takes the index AFTER the move (Puck's rule). |
+| `setProps`, `setRoot` | Merge props. A key keeps its place; a patch that changes nothing returns the same document. |
+| `createNode(config, type, props?)`, `newId(type)` | A new block the way the Add panel makes one: `{ ...defaultProps, id }`, ids `<Type>-<uuid>`. |
+| `zoneKey`, `parseZoneKey`, `ROOT_LIST` | A place is `{ parentId, slot, index }`; the top-level list is `{ parentId: 'root', slot: 'default-zone' }` — the two halves of Puck's zone key. |
+
+`config` is the app's block config: only `fields` (which props are slots, including
+slots inside `object` / `array` fields) and `defaultProps` are read, so a Puck
+`Config` works as it is. A type the config does not know is kept whole.
+
+Every edit copies only the path to the change, so an untouched block is the
+same object before and after. An edit that names a missing node or slot, an
+index off the end, a move into the node's own subtree, or an insert that
+would put a second copy of an id into the document throws a `DataError` with a
+`code`.
+
+Key order is not part of the saved format — the backend stores these in
+Postgres `jsonb` — but an edited key keeps its place and a new one goes on the
+end, so a save diffs as the lines that changed.
+
+## Block writing — `efficient-easel/blocks`
+
+`efficient-easel/blocks` (added in 0.92.0) holds the types a block is written
+with: Puck 0.20's `Config`, `ComponentConfig`, `Fields`, `Field`,
+`CustomField`, `ComponentData`, `Data`, `Slot` and `SlotComponent`, with the
+same generics. An app that typed its blocks with Puck's imports them from here
+instead, and no block changes. It is types only: nothing in it exists at
+runtime.
+
+```ts
+import type { Config, CustomField, Slot } from 'efficient-easel/blocks';
+
+type HeroProps = { title: string; content: Slot };
+const config: Config<{ Hero: HeroProps }> = {
+  components: {
+    Hero: {
+      fields: { title: { type: 'text' }, content: { type: 'slot' } },
+      render: ({ title, content: Content }) => (
+        <section><h1>{title}</h1><Content /></section>
+      ),
+    },
+  },
+};
+```
+
+## The published renderer — `efficient-easel/render`
+
+`efficient-easel/render` (added in 0.68.0) draws a saved document the way the
+published site does — the drop-in for Puck's `<Render>` (the blueprint's step
+1.2). Same config, same document, **the same HTML**: the specs hold it to
+Puck 0.20.2's markup, recorded from Puck's own `<Render>`, byte for byte.
+
+```tsx
+import { Render } from 'efficient-easel/render';
+
+<Render config={config} data={page} metadata={{ site }} />;
+```
+
+It is a plain function: **no hook, no context, no `'use client'`**. It runs in a
+server component, a client component or a script, and `Render(props)` called
+directly returns the element tree. (Puck's reads the document from a context
+and builds props in hooks, so it only runs as a client component.) Whether the
+blocks themselves can run on the server is up to the blocks.
+
+The block authoring shape is Puck's, so an app passes the config it has: a
+block's `render` gets its props, `puck`, and each slot as a component —
+`render: ({ content: Content }) => <Content className="grid" />` — which draws
+`<div className style>` around its blocks. The top-level list is wrapped in one
+plain `<div>`, and `puck` carries exactly what Puck's client `<Render>` gives at
+each level. A type the config does not know draws nothing.
+
+`className` (0.95.0) is an opt-in class for that top-level wrapper, for a host
+whose stylesheet has to reach it: `<Render … className="page" />`. Left out,
+the wrapper is bare and the markup is Puck's.
+
+## The canvas — `efficient-easel/canvas`
+
+`efficient-easel/canvas` (added in 0.70.0, blueprint step 2.1) is the one way
+into the editor's canvas iframe — `#preview-frame`, the engine's own
+same-origin canvas frame (Puck's, until the editors left it). It replaces the
+editors' own polling loops, host-head style injection and hand-written
+coordinate maths.
+
+```tsx
+import { useCanvasFrame, useCanvasEvent, useCanvasStyle, useCanvasLayout, frameRectToHost, isTypingTarget, nodeIdAt, BLOCK_SELECTOR } from 'efficient-easel/canvas';
+
+const canvas = useCanvasFrame(editorRootRef, { readySelector: BLOCK_SELECTOR });
+useCanvasStyle(canvas, 'hidden-blocks', hiddenBlockCss(ids));          // canvas document only
+useCanvasEvent(canvas, 'contextmenu', (e) => open(nodeIdAt(e.target)));  // follows a document swap
+const tick = useCanvasLayout(canvas);                                    // re-measure when this changes
+```
+
+| Export | What it answers |
+|---|---|
+| `useCanvasFrame(rootRef, { selector?, readySelector? })` | `{ frame, document, window }` or `null`. Found by a MutationObserver and the frame's `load` event — never a timer. `readySelector` waits for the blocks to arrive in a loaded-but-empty document. |
+| `useCanvasEvent(canvas, type, handler, { on?, capture? })` | A listener on the canvas document (or window) that moves to a replacement document and always calls the latest handler, without re-binding on every render. |
+| `useCanvasStyle(canvas, key, css)` | A `<style>` in the canvas document's head only — re-injected into a replacement, put back if something empties the head (Puck's AutoFrame does, once), removed on unmount, never written to the host page. |
+| `useCanvasLayout(canvas)` | A number that changes when the canvas scrolls, resizes, is replaced, or the host scrolls or resizes (plus two settle passes). |
+| `frameRectToHost`, `framePointToHost`, `frameScale` | A box or point measured inside the frame, on the host page — through the frame's SCALE (a phone view drawn small). |
+| `fitCanvas({ available, width, maxScale })` | The canvas width and the scale that fits it into the pane. |
+| `isTypingTarget(target)` | Is this key pressed somewhere a person types (text inputs, textarea, select, editable regions)? A shortcut must stay out. |
+| `nodeIdAt(target, attribute?)` | The block a pointer event landed on. |
+| `watchCanvasFrame(root, onChange, options)` | The watcher the hook wraps, for code outside React. |
+| `setCanvasNonce(document, nonce)` | The CSP nonce every `<style>` created in that canvas document carries (0.95.0). `CanvasFrame`'s `nonce` prop sets it; a host that builds its own frame calls it. |
+
+## Node operations — `efficient-easel/node-ops`
+
+`efficient-easel/node-ops` (added in 0.71.0, blueprint step 2.2) is what can be
+done TO a block, once for both editors: the operations, the right-click rows,
+the clipboard, and the "up one level" answer.
+
+```tsx
+import { useNodeOps, nodeMenuItems, createNodeClipboard, toItemSelector } from 'efficient-easel/node-ops';
+import { InspectorUpLevel } from 'efficient-easel/chrome';
+
+const clipboard = createNodeClipboard();              // once, at module scope
+
+const ops = useNodeOps({
+  data, config, clipboard, readOnly,
+  commit: (next, { select }) => store.write(next, select),  // ONE write per action
+  strip: releaseBakedImage, afterRemove: 'none', stepBounds: bodyBand,
+});
+
+const items = nodeMenuItems({
+  title: 'Heading',
+  actions: { duplicate: () => ops.duplicate(id), delete: () => ops.remove(id) /* … only what is allowed */ },
+  style: styleMenuItems({ … }),
+});
+
+const up = ops.parentOf(selection);                   // null → render nothing
+{up && <InspectorUpLevel name={nameOf(up)} onSelect={() => select(up)} icon={<UpGlyph />} />}
+```
+
+- **One action, one commit.** Every operation (remove, duplicate, move, step,
+  setProps, cut, paste) is planned whole on `efficient-easel/data` and handed
+  to `host.commit` ONCE, with the selection it leaves — so it is one undo step.
+  Two operations in one handler chain correctly: the second is planned on the
+  first's result.
+- **Selection is by id** (or a slot, for the campaign designer's columns),
+  never by position. After a delete: nothing (default) or a neighbour — never
+  whatever slid into the gap. `toItemSelector` / `fromItemSelector` translate
+  to and from `itemSelector` (`{ zone, index }`, the shape the store's
+  `ui.itemSelector` reads in), and a stale selector reads as `null`, not a throw.
+- **Rows are offered by presence.** `nodeMenuItems` fixes the order and groups
+  (`title | pick | make | style | change | remove`); the host passes the
+  actions it allows and nothing else. Labels, glyphs and shortcuts can be
+  overridden per row, so each editor keeps its own words.
+- **Read-only** makes every write a no-op; Copy still works.
+
+The plain functions (`planRemove`, `planDuplicate`, `planMove`, `planStep`,
+`planPaste`, `planSetProps`, `canStep`, `parentStep`) are exported too, and
+`efficient-easel/data` gains `copyNode` — a block with fresh ids, what a paste
+inserts.
+
+## Autosave — `efficient-easel/autosave`
+
+`efficient-easel/autosave` (added in 0.72.0, blueprint step 2.5) is how both
+editors save: a second after the operator stops, silently when it works, and
+without losing the edit when it does not.
+
+```tsx
+import { useAutosave } from 'efficient-easel/autosave';
+import { EditNotice, SaveState } from 'efficient-easel/chrome';
+
+const autosave = useAutosave<Data>({
+  save: (doc) => api.saveDocument(id, doc, version),   // read at call time
+  onFailure: (_err, attempt) => attempt === 0 && toast.error('Could not save — retrying'),
+});
+
+onChange={(doc) => canWrite && autosave.push(doc)}
+<SaveState {...autosave.indicator} />
+{autosave.state.failed && <button onClick={() => void autosave.retryNow()}>Retry now</button>}
+<EditNotice access={access} conflict={conflict} noun="page"
+  onTakeOver={takeOver} onViewReadOnly={viewReadOnly} onReload={reload} />
+```
+
+- **One save at a time, the newest edit.** A save that lands never clears an
+  edit made while it was out; that edit goes next.
+- **1 s after the last edit, at least every 3 s while typing.** So "Unsaved
+  changes" — shown only once the oldest unsaved edit is 5 s old — never appears
+  on a healthy connection.
+- **A failed save retries at 2 / 5 / 15 / 30 s, then every 30 s, for ever.**
+  New edits do not bring the retry forward; `retryNow()` does, and restarts the
+  backoff.
+- **`pause()` holds, `resume()` catches up.** Paused, nothing is written on a
+  timer, on tab-away or on unmount; `flush()` still writes, because someone
+  asked.
+- **`stop()` on a refused save.** Call it where your save reads the version
+  conflict, then rethrow: nothing more is written and the edit is kept, so the
+  close-tab warning still fires. `resume()` does not undo it; a reload does.
+- **`reset()` on a document switch.** An editor that changes documents without
+  remounting drops the old document's pending edit, failure and refusal here
+  (after saving or discarding it); a save still out for the old document can
+  no longer change the new one's state.
+
+`createAutosave` is the same engine without React, with the clock passed in —
+the specs run minutes of debounce and backoff on a fake one.
+
+`EditNotice` (in `efficient-easel/chrome`) is what to TELL the operator when the
+save cannot go: a bar, never a dialog, with a refused save outranking the lock.
+
+## Drag-and-drop — `efficient-easel/drag`
+
+`efficient-easel/drag` (added in 0.74.0, blueprint step 3.1) is the one drag
+engine for both editors. The host keeps what is its own: whether a drop may
+land (`canDrop`) and what it writes (`onDrop`, `onStep`).
+
+```tsx
+import { useTreeDrag, gapToMoveIndex } from 'efficient-easel/drag';
+import { LayersTree, TreeRow, TreeSeam } from 'efficient-easel/tree';
+
+const drag = useTreeDrag<Item>({
+  keyOf: (item) => item.id,
+  canDrop: (item, to) => rules.canDrop(item, to),          // refused: no line, no drop
+  onDrop: (item, to) => ops.move(item.id, { ...to, index: gapToMoveIndex(item.place, to) }),
+  onStep: (item, dir) => ops.step(item.id, dir),           // ⌥↑ / ⌥↓
+  canStep: (item, dir) => ops.canStep(item.id, dir),
+});
+
+<LayersTree rootProps={drag.rootProps()}>
+  <TreeSeam {...drag.seam({ place: { ...list, index: 0 } })} onAdd={() => openAdd(list, 0)} label="Add block here" />
+  <TreeRow {...drag.row({ item, place, into: containerPlace, pinned })} icon={…} name={…} onSelect={…} />
+```
+
+- **The whole row is picked up**, and the drag picture is the row, raised.
+- **One hit rule:**
+  - a seam (the gap) is "between";
+  - a container's whole row is "into", at the place you name (its start or
+    end is your call);
+  - an ordinary row splits in half;
+  - a `pinned: 'first' | 'last'` row never moves, and a drop on it lands on its
+    inner side.
+- **One drop line**, in the middle of the gap, wherever the pointer is.
+- **⌥↑ / ⌥↓** step a row. The list **scrolls at its edges**.
+- **A seam is the gap:** seams in every gap of a list, or in none. The list's
+  spacing does not change either way.
+
+**The canvas and the Add list** (0.75.0, step 3.2) join the same drag through a
+shared session, so a thing picked up on one surface can land on another:
+
+```tsx
+const session = useMemo(() => createDragSession<Item>(), []);
+const drag = useTreeDrag({ …, session });                  // the tree
+
+<div style={{ position: 'relative' }}>                      // holds the canvas frame
+  <CanvasFrame … />
+  <CanvasDragLayer canvas={canvas} session={session} model={toModel}
+    canDrop={canDrop} onDrop={onDrop} onSeamAdd={openAddAt} onZoneAdd={openAddAt} />
+</div>
+
+<AddPanel groups={blocks} session={session} itemFor={(type) => ({ kind: 'new', type })}
+  onInsert={insertAtOpenPlace} at={openPlace && { label: 'Adding to Column 2', onClear }} />
+```
+
+- **The canvas measures itself:** `measureCanvas` reads the canvas's lists and
+  blocks. Your `model` says what may be picked up (leave out what cannot move)
+  and where "+ Add section" goes (`seamsBetween`).
+- **One handle,** on the smallest box under the pointer, never unmounted
+  mid-drag.
+- **The line** runs across a list, or down between columns (a slot laid out
+  across).
+- **An empty slot** is a dashed "+ Add block" cell that also takes drops.
+- Styles: `import 'efficient-easel/drag.css'`.
+
+## The engine's words — `efficient-easel/strings`
+
+`efficient-easel/strings` (added in 0.95.0) is every word the engine itself
+draws or returns — visible text, `aria-label`s, tooltips, placeholders — as one
+typed catalogue, so a host in another language can translate it. A host that
+does nothing sees the English it always saw.
+
+```tsx
+import { EditorStringsProvider, useEditorStrings, type DeepPartial, type EditorStrings } from 'efficient-easel/strings';
+
+const german: DeepPartial<EditorStrings> = {
+  save: { failed: 'Speichern fehlgeschlagen' },
+  lock: { minutesAgo: ({ count }) => `vor ${count} Min.` },   // a value or a plural: a function
+};
+
+<EditorStringsProvider value={german} locale="de">
+  <Editor />
+</EditorStringsProvider>;
+```
+
+- **`EditorStrings`** is grouped by the module that says the word (`notice`,
+  `lock`, `save`, `chrome`, `rail`, `tree`, `panel`, `fields`, `pick`, `drag`,
+  `menu`, `styleClipboard`, `copy`, `canvas`). A plain word is a `string`;
+  anything with a value in it is a function, so the host places the value and
+  does its own plural. `DEFAULT_EDITOR_STRINGS` is the English.
+- **What is left out falls back** (`mergeEditorStrings`), and a provider inside
+  another lays its words over the outer one's.
+- **The provider reaches the parts that have hooks:** the edit notice, the device
+  switch, "up one level", the panel grip and the top-bar rail; the copy box, its
+  bar and its link window; `Inspector`, the number box, the dropdown and the list
+  field; the canvas frame's title.
+- **The leaves are handed their words.** The rail, the settings-panel
+  primitives and the Layers tree are hook-free; the pickers, the Add panel and
+  the canvas layer may import only their own folder. None of them reads the
+  provider. Each takes its group as a prop, and the plain functions as an
+  argument:
+
+  ```tsx
+  const strings = useEditorStrings();
+
+  <EditorRail items={items} ariaLabel={strings.rail.label} />
+  <TreeRow … words={strings.tree} />
+  <ColourPicker … words={strings.pick.colour} />
+  <ImageBox … words={strings.pick.image} />
+  <AddPanel … words={strings.drag.add} />
+  <CanvasDragLayer … words={strings.drag.canvas} />
+
+  editNotice(access, conflict, noun, strings);
+  saveIndicator(snapshot, strings.save);
+  nodeMenuItems({ …, words: strings.menu });
+  styleMenuItems({ …, words: strings.styleClipboard });
+  pasteMessage(plan, source, target, strings.styleClipboard);
+  ```
+- **`useEditorLocale()`** is the provider's `locale` (`'en'` with none), for a
+  host's own blocks and fields. The engine does not read it.
+- **A server file may import it.** Importing the entry runs nothing — the React
+  context is made on first use. `efficient-easel/strings/catalogue` is the
+  catalogue, its types and `mergeEditorStrings` with no React in its graph at
+  all: what a host's own test imports to check its languages against the
+  engine's keys.
+
+What a host supplies was never the engine's and is not in the catalogue: a
+block's name, a field's label, a tile's caption, the document's `noun`.
+
+## Develop
+
+Node is native on the dev Mac (v26.8.1) — run these in your own worktree; a
+shared checkout's node_modules are linux-only. Docker stays as the fallback:
+
+```bash
+docker run --rm -v "$PWD":/w -w /w node:26-slim \
+  sh -lc "npm install && npm run typecheck && npm test && npm run build"
+```
+
+- `npm run typecheck` — `tsc` over `src` and the specs.
+- `npm test` — the leaf-safety, gold-layer and rail-shape gates. The gold-layer
+  spec is the one that needs a DOM (focus, keys, blur); it stands up a single
+  jsdom window in `tests/_dom-env.ts` and runs in its own process.
+- `npm run build` — `tsup` → `dist/` (root + the `rail`, `shell` and `gold`
+  subpaths) + the copied CSS.