efficient-easel 0.99.1 → 0.100.0

package/README.md

@@ -21,7 +21,7 @@ it since 0.93.0.
 The storefront editor (`efficient-storefront`, 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
+20px, radius 9 vs 8, a CSS-var accent vs a Tailwind one. `EaselRail` is the one
 rail they converge on.
 
 ## The leaf
@@ -36,14 +36,14 @@ it.
 // A client component in any editor:
 'use client';
 import {
-  EditorRail,
+  EaselRail,
   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
+    <EaselRail
       ariaLabel="Left panel views"
       items={[
         { id: 'pages',  label: 'Pages',  icon: <PagesIcon />,  active: view === 'pages',  onSelect: () => onView('pages') },
@@ -59,14 +59,14 @@ export function LeftRail({ view, onView, onAdd }) {
 
 ## API
 
-### `<EditorRail items ariaLabel? className? orientation? />`
+### `<EaselRail 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 |
+| `items` | `EaselRailItem[]` | — | 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 |
@@ -85,17 +85,17 @@ 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} />
+<EaselRail 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`
+### `EaselRailItem`
 
 ```ts
-interface EditorRailItem {
+interface EaselRailItem {
   id: string;            // React key + selection correlation
   label: string;         // aria-label + hover title
   icon: React.ReactNode; // an 18px currentColor glyph — use the shipped icons
@@ -109,7 +109,7 @@ 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
+`EaselRailButton` — the single-button building block `EaselRail` maps to — is
 exported too, for bespoke layouts.
 
 ## Tokens
@@ -216,7 +216,7 @@ email. Framework-free: no React, no DOM, no imports.
 | `- ` at the start of a line | a bullet line, one level | yes |
 | `1. ` at the start of a line | a numbered line, one level: 1-3 digits, `. `, words; the number is kept as typed | yes |
 | `[x]{underline}`, `[x]{sup}`, `[x]{sub}` | underline, superscript, subscript (tree only) | not yet — `applyMark` writes them; the buttons come with the final text box |
-| `[x]{color=name}` | a theme colour, by name only (`isColorName`; never a hex) (tree only) | not yet — `applyColor` writes it |
+| `[x]{color=name}` / `[x]{color=#rrggbb}` | a theme colour by name (`isColorName`), or any colour as exactly six hex digits (`isColorValue`; saved lowercase) (tree only) | not yet — `applyColor` writes it |
 | `@@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 |
 
@@ -235,7 +235,7 @@ not learned them prints the delimiters.
 | `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. |
-| `applyColor(text, start, end, name)`, `isColorName`, `spanFor` | A colour carries a name, so it has its own writer: it writes, renames and (`null`) takes off `[x]{color=name}`, and changes nothing for a name `isColorName` refuses. |
+| `applyColor(text, start, end, name)`, `isColorName`, `isColorValue`, `spanFor` | A colour carries a value, so it has its own writer: it writes, changes and (`null`) takes off `[x]{color=name}` — a theme name or a 6-digit hex, saved lowercase — and changes nothing for a value `isColorValue` refuses (`#f00`, `rgb()`, a typo). |
 | `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
@@ -263,7 +263,7 @@ export const pageEditLock = createEditLock({
 
 The plain half needs no binding: `canWriteDocument`, `holderOf`,
 `readLockHolder`, `accessForNewDocument`, `documentPermissions`, `describeAge`,
-`nameOrSomeone`, `newEditorClientId`, `shouldReleaseHeldWrite`,
+`nameOrSomeone`, `newEaselClientId`, `shouldReleaseHeldWrite`,
 `shouldReloadAfterTakeover`, `documentVersionMoved`, `reloadIfVersionMoved`.
 The bound half —
 `accessAfterClaimFailure`, `accessAfterTakeoverFailure`,
@@ -296,16 +296,16 @@ the editor owns the device, the save status, the widths and which panels are ope
 
 ```tsx
 import {
-  EditorTopBar, TopBarCluster, TopBarDivider, EditorIconButton, DeviceSwitch,
-  SaveState, PanelResizeHandle, InspectorHead, DEFAULT_PANEL_W, panelWidthVars,
+  EaselTopBar, TopBarCluster, TopBarDivider, EaselIconButton, DeviceSwitch,
+  SaveState, PanelResizeHandle, InspectorHead, DEFAULT_PANEL_W, panelWidthVars, setPanelWidthVars,
 } 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>
+  <EaselTopBar>
+    <TopBarCluster kind="rail"><EaselRail orientation="row" items={items} /></TopBarCluster>
     <TopBarCluster>
-      <EditorIconButton label="Undo" onClick={undo}><UndoIcon /></EditorIconButton>
+      <EaselIconButton label="Undo" onClick={undo}><UndoIcon /></EaselIconButton>
       <TopBarDivider />
       <DeviceSwitch devices={devices} value={device} onChange={setDevice} />
     </TopBarCluster>
@@ -313,18 +313,29 @@ import 'efficient-easel/chrome.css'; // once, after shell.css
       <SaveState tone="saved" label="" />
       <button className="es-btn-primary">Done</button>
     </TopBarCluster>
-  </EditorTopBar>
+  </EaselTopBar>
   …
 </div>
 ```
 
+A server renders that `style` prop as a `style=""` attribute. Under a
+Content-Security-Policy with no `'unsafe-inline'` for styles the browser refuses
+it, so a **server-rendered** editor writes the widths through the CSSOM instead:
+
+```tsx
+<div className="es-editor" ref={(el) => { if (el) setPanelWidthVars(el, widths); }}>
+```
+
+Until that runs, chrome.css draws the panels at `DEFAULT_PANEL_W`. See
+[Server rendering and a strict Content-Security-Policy](#server-rendering-and-a-strict-content-security-policy).
+
 ## 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 { LayersTree, TreeGroupLabel, Subtree, TreeRow, TreeRowAction, TreeEmptySlot } from 'efficient-easel/tree';
 import 'efficient-easel/tree.css';
 
 <LayersTree>
@@ -335,9 +346,17 @@ import 'efficient-easel/tree.css';
   <Subtree>
     <TreeRow icon={<TextLinesIcon />} name="Text" preview="BACK IN STOCK NOW" />
   </Subtree>
+  <Subtree>
+    <TreeEmptySlot onAdd={addToColumn} />   {/* a list with nothing in it */}
+  </Subtree>
 </LayersTree>
 ```
 
+`TreeEmptySlot` is an **empty list as a place**: a dashed box the size of a row
+that says "Add a block", takes a drop and says "Drop here" while one may land.
+With no `onAdd` (a read-only tree) it says "No blocks yet". The three words are
+`tree.addBlock`, `tree.dropHere` and `tree.emptySlot` in the strings catalogue.
+
 ## Copy style, paste style — one rule for both editors
 
 `efficient-easel/style-clipboard` (added in 0.50.0) is the right-click menu's
@@ -566,9 +585,9 @@ 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';
+import { useCanvasFrame, useCanvasEvent, useCanvasStyle, useCanvasLayout, frameRectToHost, isTypingTarget, nodeIdAt, LIST_SELECTOR } from 'efficient-easel/canvas';
 
-const canvas = useCanvasFrame(editorRootRef, { readySelector: BLOCK_SELECTOR });
+const canvas = useCanvasFrame(editorRootRef, { readySelector: LIST_SELECTOR });    // see the note below
 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
@@ -576,7 +595,7 @@ const tick = useCanvasLayout(canvas);                                    // re-m
 
 | 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. |
+| `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 canvas to be drawn 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). |
@@ -587,6 +606,13 @@ const tick = useCanvasLayout(canvas);                                    // re-m
 | `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. |
 
+⚠️ **Wait for a list, not for a block.** `LIST_SELECTOR` matches every list
+the canvas draws, and the page's own is there with nothing in it.
+`readySelector: BLOCK_SELECTOR` means "ready once the canvas holds a block", so
+the canvas of a page with **no blocks** is never published: the drag layer,
+canvas stylesheets and context menus do nothing on the one page a first block
+has to be dropped on. `BLOCK_SELECTOR` is for a canvas that is never empty.
+
 ## Node operations — `efficient-easel/node-ops`
 
 `efficient-easel/node-ops` (added in 0.71.0, blueprint step 2.2) is what can be
@@ -612,7 +638,7 @@ const items = nodeMenuItems({
 });
 
 const up = ops.parentOf(selection);                   // null → render nothing
-{up && <InspectorUpLevel name={nameOf(up)} onSelect={() => select(up)} icon={<UpGlyph />} />}
+{up && <InspectorUpLevel name={nameOf(up)} onSelect={() => select(up)} />}   // ← Section
 ```
 
 - **One action, one commit.** Every operation (remove, duplicate, move, step,
@@ -677,6 +703,14 @@ onChange={(doc) => canWrite && autosave.push(doc)}
   (after saving or discarding it); a save still out for the old document can
   no longer change the new one's state.
 
+- **Feed it from `createEasel({ onChange })`, not from `easel.subscribe`.**
+  `onChange` is called for a change to the document and never for `load()`. A
+  subscriber is also told of a load, a selection and a permission, and pushing
+  each of those saves a document nobody edited.
+- **`autosave.indicator` is always English.** Autosave does not read the
+  strings provider. In another language, build the pill from the state:
+  `<SaveState {...saveIndicator(autosave.state, useEaselStrings().save)} />`.
+
 `createAutosave` is the same engine without React, with the clock passed in —
 the specs run minutes of debounce and backoff on a fake one.
 
@@ -691,7 +725,7 @@ land (`canDrop`) and what it writes (`onDrop`, `onStep`).
 
 ```tsx
 import { useTreeDrag, gapToMoveIndex } from 'efficient-easel/drag';
-import { LayersTree, TreeRow, TreeSeam } from 'efficient-easel/tree';
+import { LayersTree, Subtree, TreeEmptySlot, TreeRow, TreeSeam } from 'efficient-easel/tree';
 
 const drag = useTreeDrag<Item>({
   keyOf: (item) => item.id,
@@ -704,6 +738,9 @@ const drag = useTreeDrag<Item>({
 <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={…} />
+  <Subtree>   {/* a list with nothing in it: not a seam */}
+    <TreeEmptySlot {...drag.seam({ place: { ...column, index: 0 } })} onAdd={() => openAdd(column, 0)} />
+  </Subtree>
 ```
 
 - **The whole row is picked up**, and the drag picture is the row, raised.
@@ -718,6 +755,17 @@ const drag = useTreeDrag<Item>({
 - **⌥↑ / ⌥↓** 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.
+- **An empty list is not a seam.** A seam hands its height back to the rows
+  either side of it; alone in a list it is a strip a few pixels tall, and a
+  drop aimed at "into this empty column" lands on whatever is really under the
+  pointer. Draw `TreeEmptySlot` (`efficient-easel/tree`) there, with the same
+  `drag.seam()`.
+- **A target names an effect its source allowed.** A row or a block picked up
+  is a move; a tile from the Add list is a copy (`effectAllowed = 'copy'`), and
+  a browser refuses a drop whose `dropEffect` the source did not allow: the
+  line is drawn and `drop` never fires. The tree and the canvas both answer
+  with `dropEffectFor(e.dataTransfer.effectAllowed)`; a drop target of a
+  host's own in the same session should too.
 
 **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:
@@ -740,12 +788,172 @@ const drag = useTreeDrag({ …, session });                  // the tree
   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.
+  mid-drag. It follows the CONTENT, not the last mouse move: it is picked
+  again whenever the canvas is measured again (a wheel in a frame that scrolls
+  itself, a block added above) and when a drag ends, so a host has no reason
+  to nudge it with a mouse move of its own.
 - **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.
+- **A drop the innermost list refuses falls through to the list outside it.**
+  A section held over a column lands between sections, and the line is drawn
+  where it will land before it is let go. Without that a page covered by its
+  inner lists could take a section only on the few pixels between sections.
+  A host for whom a refusal is final says so per drop:
+  `fallThrough={(item, refused, from) => …}` is asked only about a place
+  `canDrop` has just refused, and `false` ends it there: no line, nothing
+  lands. For example, a Columns block over a column, or a block about to
+  leave the container it was picked up in (`from`). Left out, every refusal
+  falls through. A drop back where the thing already is never falls through.
+- **The canvas scrolls at its edges,** like the tree: the host's pane around a
+  frame as tall as its content, and the frame's own document when the frame
+  fills its pane and scrolls itself (`EaselCanvas height="fill"`).
+- **One tile can be off:** `AddTile.disabled`, with `disabledReason` as its
+  tooltip ("A page has one header"). The tile stays in the list, dimmed, is
+  still found by search and counted; a click adds nothing and a drag does not
+  start. It is `aria-disabled`, so it keeps the focus and its reason can be
+  reached. `readOnly` is still the whole panel's.
 - Styles: `import 'efficient-easel/drag.css'`.
 
+## The store, its keys and its permissions — `efficient-easel/easel`
+
+```tsx
+import { createEasel, EaselProvider, EaselCanvas, useSelectedFields } from 'efficient-easel/easel';
+import 'efficient-easel/easel.css';
+
+const easel = createEasel<EaselConfig>({ config, data, onChange: (doc) => autosave.push(doc) });
+
+<EaselProvider easel={easel} hotkeys={ownsThePage}>
+  <EaselCanvas height="fill" />
+</EaselProvider>
+```
+
+- **Say the type: `createEasel<EaselConfig>(…)`.** `createEasel` infers its
+  type from the config it is handed, and a config typed more narrowly (a
+  `Config<…>` from `efficient-easel/blocks`) gives an `Easel<ThatConfig>`,
+  which `EaselProvider` does not accept.
+- **The store enforces no permission.** `dispatch`, `run`, `undo` and `redo`
+  write whatever they are asked to. Permissions are what the PARTS read: the
+  settings panel (`useSelectedFields().readOnly`), the menus, the undo keys. A
+  host that must not write, because somebody else holds the document, gates
+  its own calls.
+- **`setPermissions` replaces, and tells its readers.** It is not merged over
+  the last value (name every key: `documentPermissions` in
+  `efficient-easel/edit-lock` does). A panel reading
+  `useSelectedFields().readOnly` or `useEasel((s) => s.getPermissions)`
+  re-renders when the permissions change, and only then; the same permissions
+  again tell nobody, so it is safe to call from an effect.
+- **Undo and redo on the keyboard.** `EaselProvider` binds ⌘Z / Ctrl+Z and
+  the redo keys to the page, and `EaselCanvas` binds them in the frame's own
+  document, because a key pressed in the frame never reaches the page.
+  - `hotkeys={false}` on the provider turns **both** off, for a host that binds
+    its own.
+  - `<EaselCanvas hotkeys>` says otherwise for the frame alone: a host that
+    binds the page's keys itself (to its own root, because the page is another
+    app's) and still wants the frame's passes `hotkeys` there.
+  - Whatever those say, the keys do nothing while the easel-wide `edit`
+    permission is off. An undo is a write. `bindUndoKeys(target, editor)`, for
+    a host's own target, is held the same way.
+- **`planFields().rows` holds `slot` rows.** They draw nothing and are there so
+  the slot's name has a bucket. Filter `row.field.type !== 'slot'` before
+  drawing or counting rows of your own.
+- **Inserting a block runs no resolver; `easel.resolveNode` does.** The
+  `insert` action puts the block in with its `defaultProps`, as Puck's reducer
+  did. What ran a new block's `resolveData` in Puck was its own drop from the
+  component list, and the engine has no drop of its own: the Add list's click
+  and the drag's drop are the host's. So follow an insert with it:
+
+  ```ts
+  easel.dispatch({ type: 'insert', componentType, destinationZone, destinationIndex, id });
+  void easel.resolveNode(id, { trigger: 'insert' });   // or after `easel.run(…)`
+  ```
+
+  The block is told `trigger: 'insert'`, what it holds is resolved with it,
+  and what changed is written into the insert's own undo step. A block
+  changed by hand, or taken out, while its resolver ran is left as it is.
+- **`InspectorUpLevel` draws its own `←`** (the one up-level look, Lewis
+  2026-10-06): a blue text link, the arrow and the parent's name, no box and
+  no hover change. `icon` is ignored. Inside a panel body, pass `inline`. The
+  icon set has no back arrow, on purpose: nothing needs one now, and a glyph
+  enters the set by the owner's icon standard, not for a host.
+
+### What an accessibility audit of a second host found
+
+A host built only from the parts, audited with axe-core in a real Chromium.
+What follows is how the parts answer it; `scripts/second-host-clickthrough.mjs`
+runs the same rules (`--axe <axe.min.js>`).
+
+- **The right-click menu lives on `<body>`, and a host may move it into its
+  own landmarks.** On the body the box is page content outside every landmark
+  (axe `region`, a best-practice rule). It is not wrapped in a region or a
+  dialog to satisfy that: a menu is neither. A host that wants it inside its
+  landmarks portals it into its editor's root, through the check:
+
+  ```tsx
+  import { EaselContextMenu, menuPortalTarget } from 'efficient-easel/menu';
+
+  <EaselContextMenu portalTo={menuPortalTarget(rootRef.current)} … />
+  ```
+
+  The box is `position: fixed` at the pointer, and an ancestor that is
+  transformed, filtered or contained places and clips a fixed box inside it.
+  `menuPortalTarget` gives the root back only when none does, and `null` (the
+  body) otherwise, so a root that is scaled on one screen and not on another
+  is right on both. The body stays the default because it is the one place
+  that cannot go wrong. The root's stacking is the host's: the box is
+  `z-index: 9999` inside it.
+- **A dropdown's open list has a name.** In a settings row
+  (`InspectorField`) the list is `aria-labelledby` the row's own label. A
+  `FieldSelect` on its own is named by `ariaLabelledBy` or `ariaLabel`, and
+  with neither the list takes its button's name, so it is never nameless.
+- **Small grey words can be read.** The Add panel's group count, a menu
+  row's shortcut, a read-only or disabled field's value and an empty slot's
+  note are at least 4.5:1 on their ground (WCAG AA), held by ratio in
+  `tests/contrast-small-text.test.ts`. A host that overrode
+  `.es-add-group-count` or `--es-menu-shortcut-fg` can drop the override.
+- **The rail says which words it draws.** The width decides in CSS between
+  every word, the open panel's word, and glyphs only, so a longer language
+  folds sooner (German "Zurück", "Ebenen"). `<TopBarRail onWords={…}>` is told
+  `'all' | 'chosen' | 'none'`, read back from what the stylesheet drew, when
+  it changes. Every button keeps its name as `title` and `aria-label`.
+- **A list's drag hint is drawn whole under its last row.** A list in the
+  settings panel (`ListField`) is not a scroll box of its own; the panel
+  around it scrolls.
+
+### Server rendering and a strict Content-Security-Policy
+
+A policy with no `'unsafe-inline'` for styles (`style-src 'self'`, or by nonce)
+refuses every `style=""` **attribute** in the HTML a server sends. It does not
+govern the CSSOM, which is how React writes a `style` prop in the browser, so a
+client-rendered editor is not affected. And React does not repair it when it
+hydrates: an attribute it finds matching is left alone, so a refused style stays
+refused until its value changes.
+
+So the frame's parts write no `style` of their own into a server's HTML:
+
+- **The canvas frame's look is a class** (`.es-canvas-frame`, `.is-fill`, in
+  `efficient-easel/easel.css`): no border, the pane's width, and the pane's
+  height when it fills.
+- **The panel widths have their default in the stylesheet** wherever chrome.css
+  reads them, and a host writes its own with `setPanelWidthVars(el, widths)`
+  from a ref rather than `style={panelWidthVars(widths)}`.
+- **Stylesheets in the frame** take the page's nonce: `<EaselCanvas nonce>`.
+
+What still writes a `style`, and where it matters:
+
+| Part | When | Under such a policy |
+|---|---|---|
+| The drag layer's handle, line and cells; context menus; the rail's measured words | In the browser only, from state or a measurement | Nothing to do: never in a server's HTML |
+| Everything inside the canvas frame (lists, block wrappers, outlines) | In the browser only: the frame is filled once it mounts | Nothing to do |
+| `EaselCanvas frame={false}` | Server-rendered with the page | Mount it on the client |
+| `ColourPicker`'s swatch, when it has a value | Server-rendered with a settings panel that holds a colour | Mount that panel on the client |
+| `SaveState` with `counting` and `waitMs` | Only while a save waits, which a server render is not | Nothing to do |
+| A `style` or a slot's `style` you pass (`CanvasFrame`, `TopBarCluster`, `Render`) | As you wrote it | Yours to move to a class |
+
+`tests/csp-server-render.test.tsx` server-renders a frame built from the parts
+and fails on any `style` attribute; `scripts/second-host-clickthrough.mjs`
+serves one under a real policy in Chrome.
+
 ## The engine's words — `efficient-easel/strings`
 
 `efficient-easel/strings` (added in 0.95.0) is every word the engine itself
@@ -754,24 +962,24 @@ 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';
+import { EaselStringsProvider, useEaselStrings, type DeepPartial, type EaselStrings } from 'efficient-easel/strings';
 
-const german: DeepPartial<EditorStrings> = {
+const german: DeepPartial<EaselStrings> = {
   save: { failed: 'Speichern fehlgeschlagen' },
   lock: { minutesAgo: ({ count }) => `vor ${count} Min.` },   // a value or a plural: a function
 };
 
-<EditorStringsProvider value={german} locale="de">
+<EaselStringsProvider value={german} locale="de">
   <Editor />
-</EditorStringsProvider>;
+</EaselStringsProvider>;
 ```
 
-- **`EditorStrings`** is grouped by the module that says the word (`notice`,
+- **`EaselStrings`** 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
+  does its own plural. `DEFAULT_EASEL_STRINGS` is the English.
+- **What is left out falls back** (`mergeEaselStrings`), 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
@@ -784,9 +992,9 @@ const german: DeepPartial<EditorStrings> = {
   argument:
 
   ```tsx
-  const strings = useEditorStrings();
+  const strings = useEaselStrings();
 
-  <EditorRail items={items} ariaLabel={strings.rail.label} />
+  <EaselRail items={items} ariaLabel={strings.rail.label} />
   <TreeRow … words={strings.tree} />
   <ColourPicker … words={strings.pick.colour} />
   <ImageBox … words={strings.pick.image} />
@@ -799,17 +1007,44 @@ const german: DeepPartial<EditorStrings> = {
   styleMenuItems({ …, words: strings.styleClipboard });
   pasteMessage(plan, source, target, strings.styleClipboard);
   ```
-- **`useEditorLocale()`** is the provider's `locale` (`'en'` with none), for a
+- **`useEaselLocale()`** 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
+  catalogue, its types and `mergeEaselStrings` 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`.
 
+## The names before the Easel rename
+
+The package took the name `efficient-easel` at 0.96.0. Its exports followed at
+0.99.2: every `Editor…` name is an `Easel…` one, and the store's subpath is
+`efficient-easel/easel`. From 0.99.2 to 0.99.x the old names were kept as
+deprecated aliases. **They are removed in 0.100.0**: a host must be on the new
+names, and on `efficient-web-builder` 0.7.1 or later, before it takes 0.100.0.
+
+| Subpath | Was | Is |
+| --- | --- | --- |
+| `efficient-easel/editor` | the subpath itself, and `editor.css` | `efficient-easel/easel`, `easel.css` |
+| `/easel` | `createEditor`, `Editor`, `EditorOptions` | `createEasel`, `Easel`, `EaselOptions` |
+| `/easel` | `EditorProvider` (prop `editor`) | `EaselProvider` (prop `easel`) |
+| `/easel` | `useEditor`, `useEditorApi`, `createUseEditor`, `useEditorNodeOps` | `useEasel`, `useEaselApi`, `createUseEasel`, `useEaselNodeOps` |
+| `/easel` | `EditorCanvas`, `EditorCanvasProps` | `EaselCanvas`, `EaselCanvasProps` |
+| `/easel` | `EditorConfig`, `EditorView`, `EditorUi`, `EditorAction`, `EditorCore`, `EditorHistory` | `EaselConfig`, `EaselView`, `EaselUi`, `EaselAction`, `EaselCore`, `EaselHistory` |
+| `/rail` | `EditorRail`, `EditorRailButton`, `EditorRailItem`, `EditorRailProps`, `EditorRailButtonProps`, `EditorRailOrientation` | `EaselRail`, `EaselRailButton`, `EaselRailItem`, `EaselRailProps`, `EaselRailButtonProps`, `EaselRailOrientation` |
+| `/menu` | `EditorContextMenu`, `EditorContextMenuItem`, `EditorContextMenuProps`, `EditorContextMenuSkin` | `EaselContextMenu`, `EaselContextMenuItem`, `EaselContextMenuProps`, `EaselContextMenuSkin` |
+| `/chrome` | `EditorTopBar`, `EditorIconButton`, `EditorIconButtonProps` | `EaselTopBar`, `EaselIconButton`, `EaselIconButtonProps` |
+| `/strings` | `EditorStrings`, `DEFAULT_EDITOR_STRINGS`, `mergeEditorStrings`, `EditorStringsProvider`, `EditorStringsProviderProps`, `useEditorStrings`, `useEditorLocale` | `EaselStrings`, `DEFAULT_EASEL_STRINGS`, `mergeEaselStrings`, `EaselStringsProvider`, `EaselStringsProviderProps`, `useEaselStrings`, `useEaselLocale` |
+| `/edit-lock` | `newEditorClientId` | `newEaselClientId` |
+
+Not renamed, because other code holds them: the `.es-editor` class and every
+other `es-` class, the `--es-*` variables, the `editor-shell:style-clipboard`
+storage key, and the rail's default label, the word "Editor", which a screen
+reader says to the person using a host's editor.
+
 ## Develop
 
 Node is native on the dev Mac (v26.8.1) — run these in your own worktree; a
@@ -826,3 +1061,13 @@ docker run --rm -v "$PWD":/w -w /w node:26-slim \
   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.
+- `node scripts/second-host-clickthrough.mjs [out-dir]` — what jsdom cannot
+  hold. It server-renders a lean editor built only from the parts
+  (`tests/fixtures/second-host-page.tsx`), serves it under a
+  Content-Security-Policy with no `'unsafe-inline'`, and drives it in headless
+  Chrome with real drags and keys: a tile dropped on the tree, the canvas
+  scrolling under a drag, undo keys with editing held, a permission reaching
+  the settings panel, no refused `style` attribute, an empty slot taking a
+  drop. One PASS or FAIL per step and a screenshot of each. Not part of
+  `npm test`: CI has no Chrome. Run it when you touch `drag`, `editor`,
+  `chrome` or `tree`.

package/dist/autosave/index.d.ts

@@ -1,8 +1,8 @@
-import { A as Autosave, a as AutosaveSnapshot, b as SaveIndicator, c as AutosaveOptions } from '../words-Cqmyey0s.js';
-export { d as AutosaveClock, S as SaveWords, e as createAutosave, s as saveIndicator } from '../words-Cqmyey0s.js';
-import '../types-CnRzp9oc.js';
-import '../types-DNrn_w4V.js';
-import '../wordFit-9B9nqyf3.js';
+import { A as Autosave, a as AutosaveSnapshot, b as SaveIndicator, c as AutosaveOptions } from '../words-BMzV04b1.js';
+export { d as AutosaveClock, S as SaveWords, e as createAutosave, s as saveIndicator } from '../words-BMzV04b1.js';
+import '../types-DGcCsxs8.js';
+import '../types-DWS-s9z-.js';
+import '../wordFit-D4S36PvB.js';
 import 'react';
 import '../edit-lock/index.js';
 
@@ -16,7 +16,13 @@ type UseAutosaveOptions<T> = Omit<AutosaveOptions<T>, 'save' | 'onFailure'> & {
 };
 type UseAutosave<T> = Omit<Autosave<T>, 'setSave' | 'getSnapshot' | 'subscribe' | 'dispose'> & {
     state: AutosaveSnapshot;
-    /** The pill's tone and words — `<SaveState {...indicator} />`. */
+    /**
+     * The pill's tone and words — `<SaveState {...indicator} />`.
+     *
+     * ⚠️ ALWAYS ENGLISH. Autosave is held to its own lane and does not read the
+     * strings provider. A host in another language builds the pill from the
+     * state instead: `saveIndicator(autosave.state, useEaselStrings().save)`.
+     */
     indicator: SaveIndicator;
 };
 declare function useAutosave<T>(options: UseAutosaveOptions<T>): UseAutosave<T>;

package/dist/blocks/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement, FC, CSSProperties, ReactNode, JSX } from 'react';
-import { P as Permissions, A as AppState } from '../types-Dy6oR6Z2.js';
+import { P as Permissions, A as AppState } from '../types-E3HrTPg2.js';
 import '../data/index.js';
 import '../types-41704JE4.js';
 import '../resolve-D68pb3Bx.js';
@@ -21,7 +21,7 @@ import '../plan-DChbUXdS.js';
  *   - the `ConfigParams` form of `Config<{ components, root, fields }>` and the
  *     user field-type extension it carries (neither app uses it);
  *   - everything about Puck's own editor — its store, overrides, plugins and
- *     history. Those are the engine's now (`efficient-easel/editor`).
+ *     history. Those are the engine's now (`efficient-easel/easel`).
  *
  * The `puck` prop keeps its name: it is what every block's `render` destructures
  * (`puck.isEditing`, `puck.renderDropZone`), and renaming it is the block rewrite

package/dist/canvas/index.d.ts

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
-import { C as CanvasTarget, W as WatchOptions } from '../watch-DmasQA61.js';
-export { B as BLOCK_SELECTOR, a as CANVAS_SELECTOR, i as isFrameReady, w as watchCanvasFrame } from '../watch-DmasQA61.js';
+import { C as CanvasTarget, W as WatchOptions } from '../watch-BTYOJpQU.js';
+export { B as BLOCK_SELECTOR, a as CANVAS_SELECTOR, L as LIST_SELECTOR, i as isFrameReady, w as watchCanvasFrame } from '../watch-BTYOJpQU.js';
 
 /**
  * The small facts every canvas surface needs, written once — pure DOM, no
@@ -103,7 +103,7 @@ declare function fitCanvas({ available, width, maxScale, }: {
  * 'nonce-…'`), where a `<style>` without it is refused. Every sheet
  * `upsertCanvasStyle` / `useCanvasStyle` creates in `doc` afterwards wears it.
  *
- * `CanvasFrame` (`efficient-easel/editor`) calls this with its `nonce` prop as
+ * `CanvasFrame` (`efficient-easel/easel`) calls this with its `nonce` prop as
  * it builds the frame, so a host says it once; a host that builds its own
  * frame calls it itself. `undefined` (or `''`) forgets it.
  */

package/dist/canvas/index.js

@@ -1 +1 @@
-export{BLOCK_SELECTOR,CANVAS_SELECTOR,isFrameReady,useCanvasEvent,useCanvasFrame,useCanvasLayout,useCanvasStyle,watchCanvasFrame}from"../chunk-MCLBHENY.js";export{BLOCK_ATTRIBUTE,clientPointToLayer,elementScale,fitCanvas,framePointToHost,frameRectToHost,frameRectToLayer,frameScale,isTypingTarget,nodeIdAt,removeCanvasStyle,setCanvasNonce,upsertCanvasStyle}from"../chunk-ZNCEOSXO.js";
+export{BLOCK_SELECTOR,CANVAS_SELECTOR,LIST_SELECTOR,isFrameReady,useCanvasEvent,useCanvasFrame,useCanvasLayout,useCanvasStyle,watchCanvasFrame}from"../chunk-PAELDYYS.js";export{BLOCK_ATTRIBUTE,clientPointToLayer,elementScale,fitCanvas,framePointToHost,frameRectToHost,frameRectToLayer,frameScale,isTypingTarget,nodeIdAt,removeCanvasStyle,setCanvasNonce,upsertCanvasStyle}from"../chunk-ZNCEOSXO.js";