@panphora/clayjs 1.17.0 → 1.18.0

package/docs/guide.md

@@ -4,7 +4,7 @@ This is the complete reference for building malleable documents with ClayJS: one
 
 It is written for a developer or an LLM building full apps with inline editing and inline controls: kanban boards with card detail, block writers, finance trackers, CRMs, flashcards, trackers. It covers the CMS plugin only in passing ([cms: content-managed pages](https://clayjs.com/docs/guide/components/#cms-content-managed-pages)), because an app whose product is editing should not route editing through a form sidebar.
 
-Every behavior stated here was read from ClayJS 1.8.2 source or executed. The four example files below are complete, tested apps that this guide quotes. A [test suite](https://github.com/panphora/clayjs/tree/main/tests/unit/guide-examples) boots each one in jsdom with the real loader and checks what it saves, how it merges a peer's edit, and what a viewer receives. Open any of them and view source, or download one and open it in HTML Clay to edit it:
+Every behavior stated here was read from ClayJS 1.17.0 source or executed. The four example files below are complete, tested apps that this guide quotes. A [test suite](https://github.com/panphora/clayjs/tree/main/tests/unit/guide-examples) boots each one in jsdom with the real loader and checks what it saves, how it merges a peer's edit, and what a viewer receives. Open any of them and view source, or download one and open it in HTML Clay to edit it:
 
 | File | What it shows |
 |---|---|
@@ -117,7 +117,7 @@ Templates are blueprints. `item-tpl` holds a new row in its active form (`conten
 <script src="https://clayjs.com/v1/clay-ui.js"></script>
 ```
 
-The script tags load core with `sync,sortable,undo,indicator`, `exclude=richclay` because this app has no rich text, and then the `clay-options` and `clay-ui` satellites. ([Add ClayJS to a page](https://clayjs.com/docs/guide/loading/))
+The script tags load core with `sync,sortable,undo,indicator`, `exclude=richclay` because this app has no rich text, and then the `clay-options` and `clay-ui` satellites. ([Add ClayJS to a page](https://clayjs.com/docs/guide/loading/)) The file opens in view mode, even for its owner. Press Cmd+Shift+E (Ctrl+Shift+E elsewhere) to edit, or add `menu` to the plugin list for an Edit switch ([How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided)).
 
 #### Starting the app
 
@@ -260,7 +260,7 @@ Follow these rules to keep record, chrome, and derived state separate.
 2. **Chrome is authored in the file and hidden from viewers with `show-when:editmode="true"`.** This default needs no script and is in place before ClayJS loads. Use `clay="editor-ui"` only for UI a script fills or changes while the page is open, or that viewers must not receive ([Chrome](https://clayjs.com/docs/guide/architecture/#chrome)).
 3. **Derived values are recomputed, never stored as edits.** Store the value once as the record (`bind`), and declare every other place it shows as a sapjs paint: `attr:data-state="item.state"`, `class:done="item.done"`, `text`, `show` ([sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup)). ClayJS loads the sapjs core for any page with a `[sap]` root and treats painted values as derived. Without sapjs, write derived values into `editor-ui` elements, or into `clay="no-dirty"` elements when the saved file must show them. Never copy a record into a second attribute with a script. The copy goes stale in the file, and a merge brings the stale copy back.
 4. **Every repeated item has a unique `data-id` from birth.** Mint a fresh one on every create and every duplicate. Sync pairs elements by it.
-5. **Per-tab state stays out of the record.** Keep which card is open, the filter, and the current view in the URL hash, `localStorage`, or memory. Paint them through `ephemeral` attributes ([Ephemeral state: per-tab state on saved elements](https://clayjs.com/docs/guide/record/#ephemeral-state-per-tab-state-on-saved-elements)), a runtime `<style>`, or `editor-ui` elements.
+5. **Per-tab state stays out of the record.** Keep which card is open, the filter, and the current view in the URL hash, `clay.storage`, or memory. Paint them through `ephemeral` attributes ([Ephemeral state: per-tab state on saved elements](https://clayjs.com/docs/guide/record/#ephemeral-state-per-tab-state-on-saved-elements)), a runtime `<style>`, or `editor-ui` elements.
 6. **A command writes the record once, in one place, wrapped in an undo commit.** The mutation is what autosave, undo, and sync see.
 7. **Adopt the file as it is on load.** Never rewrite the record at boot. Doing so makes the page dirty, can fall outside the save baseline, and races peers.
 8. **Reconcile after changes you did not make.** A peer's frame, an agent's disk edit, and an undo replay change the DOM under you. Rebuild derived and chrome state on `clay:sync-applied` and on undo and redo.
@@ -308,7 +308,7 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 | `live` | off | yes | `clay.live(name)`: a `clay="live"` JSON tag as a live object |
 | `sortable` | off | no | the `sortable` attribute, `window.Sortable`, `clay:sorted` |
 | `undo` | off | no | `clay.undo` (whole-page undo, takes Cmd+Z for the window) |
-| `indicator` | off | no | the save status chip |
+| `indicator` | off | no | the save status chip, drawn by a module fetched at the first input or save state |
 | `upload` | off | no | `clay.upload` |
 | `quickcrop` | off | yes | `clay.quickcrop` |
 | `cms` | off | yes | `clay.cms`; implies `quickcrop` and `upload` |
@@ -318,8 +318,14 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 | `demo` | off | yes | fakes saving into `localStorage` for public demos |
 | `visitor-drafts` | off | yes | `clay.visitorDrafts`; in draft mode, the draft store, download prompt and intro area; outside it, only the owner chip, fetched when the owner edits ([Free documents for visitors](https://clayjs.com/docs/guide/free-documents/)) |
 | `derive` | on for any page with a `[sap]` root | yes | the sapjs core: records and paints, treated as derived ([sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup)) |
-
-- Edit-only plugins never load in view mode, even when named. Their members are absent there: test `clay.isEditMode` or `'save' in clay`, never `clay.RichClay` alone.
+| `page` | off | reader half only (`page-view`) | the page editor, `clay.page`; implies `live`, `sync` and `upload`, and drops `richclay` unless named |
+| `unsent` | off | no | `unsent="<name>"`: unsent text in chrome survives a redraw and a reload, `clay.unsent` |
+| `bind-text` | off | no | `clay.bindText`: an editor textarea outside the records, bound to one record's text |
+| `people` | off | yes | who is editing and who wrote what |
+| `menu` | off | yes | an Edit switch and claygoo in the top right for anyone who can edit, with the SEO settings |
+| `upgrade` | off; added for a copy of a hyperclay.com starter template that this person can edit | yes | the template upgrade notice |
+
+- Edit-only plugins do not load in a tab that booted in view, even when named. Their members are absent there. Test `clay.isEditMode` (or `clay.modeLifecycle.canWrite()` before a write), never `'save' in clay` or `clay.RichClay` alone, because a live exit leaves those members attached. On a `<html clay-mode-switch="live">` document, entering edit imports them while the tab still shows view, and they stay loaded after the exit ([Leaving edit](https://clayjs.com/docs/guide/edit-mode/#leaving-edit)).
 - `exclude` wins over implications. `exclude=wire` also drops `ai-edit`.
 - Load order is fixed regardless of how you list them.
 - Use `exclude=richclay` when the app has no rich text. `exclude=source` saves one request and about 48 KB, at the cost of saves reprinting the whole document instead of keeping hand formatting.
@@ -328,7 +334,9 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 - `derive` loads automatically when the page has a `[sap]` root at boot, and stays idle when full sapjs is on the page. `exclude=derive` opts out; `plugins=derive` loads it for a page that adds its `[sap]` root later.
 - `visitor-drafts` loads its draft store only in draft mode. A reader or an owner editing the original gets a small module that publishes an inert `clay.visitorDrafts` and, for the owner, the owner chip. On a page with no `visitor-drafts` slot, no `api` rules tag, or a rules tag this version cannot read (not `data-rules-version="1"`, or not JSON), it warns in the console and draws nothing. [Free documents for visitors](https://clayjs.com/docs/guide/free-documents/) covers the opt in.
 
-**A good default for apps:** `?plugins=sync,sortable,undo,indicator`, plus `upload` for images or attachments, plus `exclude=richclay` when there is no rich text.
+Measure what each mode you ship downloads, and keep a byte budget and a test that fails when one grows: [Keep a byte budget per boot, and fail a test when it grows](https://clayjs.com/docs/practices/#keep-a-byte-budget-per-boot-and-fail-a-test-when-it-grows).
+
+**A good default for apps:** `?plugins=sync,sortable,undo,indicator`, plus `upload` for images or attachments, plus `exclude=richclay` when there is no rich text. A document opens in view even for its owner, so add `menu` for the Edit switch, or declare `<html opens-in="edit">` on a tool page that must edit as soon as it opens.
 
 ### 2.3 Satellites
 
@@ -348,13 +356,13 @@ Satellites are separate classic script tags. Each publishes a readiness promise
 
 Satellites do not wait for `clay.ready` and work without `clay.js`, including in view mode and on a static host. In code that runs early, await the promise before using what it adds (`await clay.loaded.ui` before `clay.toast`). Inside a `clay.ready` callback, satellites have usually finished loading, so `clay.toast?.(...)` is safe and the optional call costs nothing.
 
-`clay.standalone.js` bundles the loader, every plugin, and every satellite into one 2 MB file for offline use. `plugins=` still decides what runs. With it, remove the satellite tags and always `await clay.loaded.sap` or `.data` before use.
+`clay.standalone.js` bundles the loader, every plugin, and every satellite into one file of about 5 MB for offline use. `plugins=` still decides what runs. With it, remove the satellite tags and always `await clay.loaded.sap` or `.data` before use.
 
 In Hyperclay Local and HTML Clay, a document needs no special loading to work offline. Keep the ordinary `https://clayjs.com/v1/` tags and the host serves them from its bundled release. Use `clay.standalone.js` for a file opened with no host at all. [Offline in a local host](https://clayjs.com/docs/guide/hosts/#offline-in-a-local-host) covers the route and what a host must do.
 
 ### 2.4 `clay.ready`
 
-`clay.ready` is a promise that resolves with `window.clay` once boot is done and every plugin has loaded. `clay:ready` fires on `document` at the same moment. Before it resolves, members like `clay.save` and `clay.undo` do not exist. Start app code with `clay.start(...)`: it waits for `clay.ready` and runs once per page ([Starting the app once](https://clayjs.com/docs/guide/architecture/#starting-the-app-once)).
+`clay.ready` is a promise that resolves with `window.clay` once boot is done and every plugin that loads at boot has started; the late plugins ([Plugins that load late](#plugins-that-load-late)) arrive after it. `clay:ready` fires on `document` at the same moment. Before it resolves, members like `clay.save` and `clay.undo` do not exist. Start app code with `clay.start(...)`: it waits for `clay.ready` and runs once per page ([Starting the app once](https://clayjs.com/docs/guide/architecture/#starting-the-app-once)).
 
 `clay.plugins` is the frozen list of plugin names in the plan the loader resolved, late plugins included. It says what the page asked for, not what has finished loading.
 
@@ -379,6 +387,17 @@ Boot moves through `loading` (the saved article is read and validated), `joining
 
 A failed or cancelled installation never emits `document:input-ready`. Blocked readiness still resolves: `clay.page.ready` settles, `clay.page.status.phase` is `blocked` with a `reason`, the saved article stays as the host served it, and no editable page appears. [When the page editor is ready](https://clayjs.com/docs/guide/edit-mode/#when-the-page-editor-is-ready) covers the reasons and what a page can offer instead.
 
+**The two waits overlap.** The editor's code downloads while authority is prepared, so the boot waits for the longer of the two plus adoption, never for their sum. Neither branch touches the page: only the coordinator mounts, adopts, and then enables input.
+
+```js
+const settled = await settleBranches(inst, [
+  branch(steps.loadEditorAssets(inst, source), inst, "editor-assets-failed", "document:assets-ready"),
+  branch(steps.prepareAuthority(inst, source), inst, "authority-failed", "document:authority-ready"),
+]);
+```
+
+The first branch to fail answers the wait at once, and the branch still on the wire is aborted instead of being left to subscribe anything. Input opens only after adoption, so the faster start creates no temporary document and no second undo history.
+
 You can set configuration before the tag, and the loader merges into it: `window.clay = { saveToast: true }`.
 
 ### 2.5 Theming ClayJS's own UI
@@ -406,7 +425,7 @@ Your stylesheet cannot reach these elements: every declaration is inline and `!i
 
 ### 2.6 Plugins that load late
 
-`source`, `sortable`, and `menu` load after `clay:ready`, one at a time, in the order the plan resolves them. Nothing on first paint or the first keystroke waits for them. A late plugin that fails to load is logged and left absent, like any other.
+`source`, `sortable`, `menu` and `upgrade` load after `clay:ready`, one at a time, in the order the plan resolves them. Nothing on first paint or the first keystroke waits for them. A late plugin that fails to load is logged and left absent, like any other.
 
 Each late plugin fires `clay:plugin-ready` on `document` once its own `ready` settles, with `detail.plugin` naming it. Use this event to tune something the plugin built for itself. For example, a Kanban board waits for `sortable` and then sets the drag delay its cards need on a phone:
 
@@ -425,7 +444,7 @@ Do not read `window.Sortable` in a `clay.ready` callback: the plugin may not hav
 
 ### 2.7 Libraries on demand
 
-`clay.assets.load(name)` loads a library from the same release that served `clay.js` the first time a page asks for it. The document needs no vendor URL, so a copy served by another host or opened from disk still finds it. The names are `overtype`, `marked`, and `highlight`, plus one grammar per `highlight/<language>` for `bash`, `css`, `javascript`, `json`, `python`, and `xml`. `clay.assets.names()` lists them.
+`clay.assets.load(name)` loads a library from the same release that served `clay.js` the first time a page asks for it. The document needs no vendor URL, so a copy served by another host or opened from disk still finds it. The names are `overtype`, `marked`, `highlight`, and `uimotion`, plus one grammar per `highlight/<language>` for `bash`, `css`, `javascript`, `json`, `python`, and `xml`. `clay.assets.names()` lists them.
 
 ```js
 const { Marked } = await clay.assets.load("marked");
@@ -434,7 +453,15 @@ const { default: javascript } = await clay.assets.load("highlight/javascript");
 hljs.registerLanguage("javascript", javascript);
 ```
 
-`overtype` resolves the vendored OverType editor with its toolbar buttons. `marked` resolves the `Marked` class. `highlight` resolves the core with no grammar of its own, so a page registers only the grammars it uses. Each name loads once: a second call before the first settles shares it, a failed one is forgotten and can be tried again, and an unknown name rejects with `clay.assets: no asset named "<name>"`. The [`window.clay` reference](https://clayjs.com/docs/api/) lists what each name resolves to.
+`overtype` resolves the vendored OverType editor with its toolbar buttons. `marked` resolves the `Marked` class. `highlight` resolves the core with no grammar of its own, so a page registers only the grammars it uses. `uimotion` resolves the engine the free apps' intros animate with: `scene(stage, options)` builds a looping scene, `mount(stage, build, options)` plays it while the stage is on screen and stops it when the stage leaves the page, `rewind(scene, keep)` returns a scene to its start, and `ease` holds the curves. Each name loads once: a second call before the first settles shares it, a failed one is forgotten and can be tried again, and an unknown name rejects with `clay.assets: no asset named "<name>"`. The [`window.clay` reference](https://clayjs.com/docs/api/) lists what each name resolves to.
+
+### 2.8 Editor commands load on first use
+
+The page editor's optional commands are separate modules under `src/page/features/`, listed in `COMMAND_FEATURES` with one literal import each: `mentions`, `dates`, `emoji`, `titleIcon`, `titleCover`, `exportHtml`, `importMarkdown` and `exportMarkdown`. The build splits each into its own files, and the editor fetches one the first time a person invokes that command. A plain document that never uses them fetches none: opening a page, reading it and typing in it asks for no picker, no parser and no exporter. The emoji list arrives with the first picker that needs it (`page/emoji-data.js`), and `marked` arrives with the first Markdown import.
+
+An installed command shares the page lease's disposal. Leaving edit, or a refused exit that closes admission, disposes what the commands installed and aborts whatever was still arriving, and the next entry installs fresh against the module the browser already holds. A command asked for while its module is still on the way runs only if the edit is still open, the document revision has not moved and the selection is where it was; otherwise it refuses with `stale-target` and writes nothing. A failed fetch is reported and asked for again on the next request.
+
+The load report and the offline manifest both carry them. `node scripts/measure-load.mjs` counts what a command fetches in its `firstUse` phase, printed as the `phase first use` row, so the editor's ready bytes never include a module nobody asked for, and `dist/offline-manifest.json` lists their files, so a host that serves a release offline still loads one on first use.
 
 ---
 
@@ -442,28 +469,266 @@ hljs.registerLanguage("javascript", javascript);
 
 ### 3.1 How the mode is decided
 
-`clay.isEditMode` is decided once at load by the first rule that matches:
+Three separate facts:
 
-1. `?editmode=true` or `?editmode=false` in the URL. Only the literal `true` enables edit mode.
-2. `<html viewonly>` in the file forces view mode. So does a response carrying only the pre-1.9.0 token `htmlclaytoken` (an out-of-date HTML Clay, which also shows an update bar).
-3. `window.clayEditMode`, set by a script before boot.
-4. A `savetoken` attribute the host put on `<html>` (HTML Clay 1.9.0 and newer).
-5. **Draft mode**, on a page that opted in ([Free documents for visitors](https://clayjs.com/docs/guide/free-documents/)). The visitor gets the editing UI, and their work stays in their own browser. `?editmode=false`, a `viewonly` attribute, a stale token, `window.clayEditMode`, or a save token all turn draft mode off. Only the owner cookie plus `?editmode=true` edits the original. On a `viewonly` document or one with a stale token, `?editmode=true` is plain edit mode as usual ([The mode ladder](https://clayjs.com/docs/guide/free-documents/#the-mode-ladder)).
-6. The `isAdminOfCurrentResource` cookie (hyperclay.com, Hyperclay Local).
+- `clay.canEdit` is permission: whether this person may edit the document at all.
+- `clay.mode` is `"view"`, `"edit"` or `"draft"`, and it is a live getter.
+- `clay.modeLifecycle.state.destination` is where edits land: `"host"`, `"draft"`, or `"demo"` when the demo plugin saves to `localStorage`.
+
+Permission alone does not open edit. An owner on hyperclay.com opens in view, with `clay.canEdit === true`. The host's own answer about the document, `document.writable` in `/_/meta`, is the last word on `canEdit`, and a change to it fires `clay:capabilitychange`.
+
+The mode this tab starts in is decided once, in this order:
+
+1. **Draft mode**, on a page that opted in ([Free documents for visitors](https://clayjs.com/docs/guide/free-documents/)). The visitor gets the editing UI, and their work stays in their own browser. `?editmode=false`, a `viewonly` attribute, a stale token, `window.clayEditMode`, or a save token all turn draft mode off. Only the owner cookie plus `?editmode=true` edits the original. On a `viewonly` document or one with a stale token, `?editmode=true` is plain edit mode as usual ([The mode ladder](https://clayjs.com/docs/guide/free-documents/#the-mode-ladder)).
+2. **The reload receipt.** A deliberate switch writes `sessionStorage` entry `clay:doc:<pathname>:mode-receipt` just before it reloads. Boot reads it once and removes it, accepts it only within 30 seconds and only for a reload of the same path, and then starts the tab in the mode it names. A tab that can edit also leaves a receipt when the page is hidden, and boot accepts it only for a browser reload, so reloading an editing tab comes back in edit. On a page that declares `<html opens-in="edit">`, that hide receipt never keeps a tab in view, so adding the attribute takes effect on the next reload; a deliberate switch to view still does. A receipt keeps a reload in the same tab, not a lasting preference.
+3. **`?editmode=`.** Only the literal `true` asks for edit.
+4. **`window.clayEditMode === true`** or `<html opens-in="edit">`.
+5. **Otherwise** the tab starts in view.
+
+Nothing else opens edit, including a page whose own script makes text editable. An editor library such as OverType or CodeMirror, a `persist` field, and `contenteditable` set by your code all accept typing in view mode, and none of that typing is saved, because the save path runs only in edit. A tool page that must be editable the moment it opens, such as a journal or a notes pad, declares `<html opens-in="edit">`. Every other document needs a way into edit: the `menu` plugin, or a control that calls `clay.setMode("edit")`.
+
+When someone who can edit types into a document in view anyway, ClayJS shows a notice on the first edit to a field that would save in edit mode: a `persist` control, or `contenteditable` content outside `editor-ui`, `no-save` and `freeze`. A field that edit mode would unlock (`editmode:contenteditable`, `viewmode:readonly`, `viewmode:disabled`) raises it on the first attempt to type into it or press it. The notice reads "In view mode, so edits won't be saved." and stays until the tab enters edit, with a **Switch to edit** button that calls `clay.setMode("edit")`. A document without `clay-mode-switch="live"` reloads to switch, so the characters typed before the notice appeared are lost. A visitor who cannot edit never sees it, and a page with its own handled single-key shortcuts does not set it off. It also writes one warning to the console.
+
+`<html viewonly>` in the file forces view mode. So does a response carrying only the pre-1.9.0 token `htmlclaytoken` (an out-of-date HTML Clay, which also shows an update bar).
+
+`clay.canEdit` follows its own ladder: `?editmode=` first, then `viewonly` and a stale token, which take edit off the table, then `window.clayEditMode`, then a save token or the owner cookie.
+
+`clay.isOwner` reflects the cookie alone. On HTML Clay, an editable page has `isOwner === false`. Use `clay.canEdit` for whether a person may edit, and `clay.mode` for whether this tab is editing.
+
+### 3.2 Switching modes: clay.setMode
+
+`await clay.setMode("edit")` and `await clay.setMode("view")` switch this tab. `setMode` takes one argument, and anything else throws a `TypeError`.
+
+Three answers:
+
+- `{ ok: true, mode, changed }`: the switch committed. `changed` is `false` when the tab was already in that mode.
+- `{ ok: true, mode, changed: true, reloading: true }`: a reload is on its way.
+- `{ ok: false, mode, code }`: it refused, and `mode` is still the committed one.
+
+The refusal codes:
+
+- `busy`: another switch to the other mode is already running.
+- `not-allowed`: this person may not edit, or the page is in draft mode.
+- `permission-denied`: the host answered that this caller may not write the document.
+- `cancelled`: the page moved to another document while the host answered.
+- `host-failed`: the workspace shell threw instead of answering.
+- `host-refused`: the workspace shell answered without success.
+- `save-failed`: the save before leaving edit failed or did not settle as saved.
+- `pending-input`: text or a composition is still uncommitted in the page.
+- `conflict`: the file has an unresolved save conflict.
+- `save-unknown`: the outcome of the last save could not be established.
+- `stale-document`: the file moved on while the session was being prepared.
+- `timeout`: the 15 second deadline passed.
+- `load-failed`: a module the entry needed failed to import.
+- `unsupported-plugin`: a queued entry was not a participant.
 
-Edit mode only turns on the editing UI. The host decides who writes. On a host that has not authorized the current user, every save is refused (`savestatus="error"`).
+An undeclared document saves, writes the receipt and reloads. A document with `<html clay-mode-switch="live">` and supported participants switches live. A workspace frame hands the change to its shell, whose reload owns it.
 
-`clay.isOwner` reflects the cookie alone. On HTML Clay, an editable page has `isOwner === false`. Check `clay.isEditMode` for whether the page can be edited, never `isOwner`.
+Draft mode always answers `not-allowed`: a draft stays local.
 
-`clay.toggleEditMode()` flips `?editmode=` and reloads.
+Keep the control on the committed value while a switch is pending, and show the code when it refuses:
+
+```js
+const toggle = document.querySelector("[clay-mode-toggle]");
+const status = document.querySelector("[data-mode-status]");
+let busy = false;
+
+function paint() {
+  toggle.setAttribute("aria-checked", clay.mode === "edit" ? "true" : "false");
+}
+paint();
+document.addEventListener("clay:modechange", paint);
+
+toggle.addEventListener("click", async () => {
+  if (busy) return;
+  busy = true;
+  toggle.disabled = true;
+  status.textContent = "";
+  const result = await clay.setMode(clay.mode === "edit" ? "view" : "edit");
+  // A reload is coming: stay busy until the page goes.
+  if (result.reloading) return;
+  busy = false;
+  toggle.disabled = false;
+  if (result.ok === false) status.textContent = `Stayed in ${clay.mode}: ${result.code}`;
+});
+```
+
+Never switch by writing the root `editmode` attribute. That attribute reports the committed mode; it does not change it.
+
+`clay.toggleEditMode()` is the one-line form. In draft mode it opens `?editmode=true`, and otherwise it calls `setMode`.
+
+Every page answers Cmd+Shift+E (Ctrl+Shift+E elsewhere) with `setMode` for a person who can edit. A page with no switch of its own shows that person a one-time note pointing to the shortcut. Mark your own control `clay-mode-toggle` to replace the note, or load the `menu` plugin for a ready-made Edit switch in the top right ([menu](https://clayjs.com/docs/plugins/menu/)).
+
+### 3.3 Switching without a reload: clay-mode-switch="live"
+
+`<html clay-mode-switch="live">` is the author's promise that every edit resource can be taken back. Without it, `setMode` takes the guarded reload: it saves, writes the receipt and reloads.
+
+A document registers participants with `clay.modeLifecycle.register(...)`, or before the loader runs through the `window.clay.modeParticipants` array, which survives the boot and is drained by the first entry.
+
+A participant is `{ id, order, prepare }`. `order` decides prepare order and defaults to `0`. `prepare(context)` returns a lease:
+
+- `ready`: a promise the entry awaits before it goes on, or nothing.
+- `enable`: runs synchronously, once every preparation has succeeded.
+- `quiesce`: stops admission without losing buffers.
+- `resume`: takes the very same lease back after a refused exit.
+- `dispose`: runs only after a committed exit.
+
+`context` is `{ generation, destination, signal, represented, reader, initial, isCurrent() }`.
+
+`clay.modeLifecycle.canWrite()` is true while this tab is in edit or draft and no transition is running. `clay.modeLifecycle.state` reports `phase` as `idle`, `entering`, `leaving` or `blocked`, beside `mode`, `destination`, `generation` and `reason`. A committed change fires `clay:modechange`, and a refusal is the returned code plus `state.reason`.
+
+An id that starts with `clay:` is reserved for the built-in sessions.
+
+One 15 second deadline covers the whole transition: every import a participant prepares from, the preparation itself and the commit.
+
+`prepare` must not await `clay.ready`. The loader awaits `activateInitialMode()` before it resolves `ready`, and `activateInitialMode()` awaits every `prepare`, so a `prepare` that awaits `ready` waits on itself.
+
+An asynchronous callback checks `context.isCurrent()` and `clay.modeLifecycle.canWrite()` before it changes a record.
+
+A participant registered before the loader runs, with a lease that has all five members:
+
+```js
+window.clay.modeParticipants = [
+  {
+    id: "board",
+    order: 10,
+    prepare: async (context) => {
+      const editor = await openEditor(context.signal);
+      return {
+        ready: null,
+        enable: () => editor.adopt(),
+        quiesce: async () => editor.flush(),
+        resume: () => editor.resume(),
+        dispose: () => editor.teardown(),
+      };
+    },
+  },
+];
+```
 
-### 3.2 The root attributes
+### 3.4 Leaving edit
 
-At load, ClayJS sets `editmode="true|false"` and `pageowner="true|false"` on `<html>` in both modes. In edit mode, it also sets `savestatus` (`saving`, `saved`, `error`, `offline`, `conflict`) once the page settles. **All three are removed on every save**, along with the host's `savetoken` and `documentetag`. The saved file's `<html>` carries none of them.
+The exit waits for the writes it is allowed to wait for, and refuses with a code when it cannot finish:
+
+- an unsent composer or an unresolved IME composition answers `pending-input`.
+- an unresolved conflict answers `conflict`.
+- a save whose outcome is unknown answers `save-unknown`.
+- a failed save answers `save-failed`.
+- a pending upload is flushed first, and one that is still running answers `pending-input`.
+
+A refused exit resumes the very same leases and leaves the page in edit, with `clay.modeLifecycle.state.reason` naming why. Nothing blur-submits: the exit never commits text a person did not commit.
+
+Entering edit writes nothing. The session adopts the file it shows as its baseline (`save.adoptEntryBaseline`), so a clean enter and exit leaves the file byte for byte the same. The recorded case is `enter-leave-zero-writes` in the clayjs corpus.
+
+### 3.5 Attributes across a mode change
+
+The four controlled families, `editmode:contenteditable`, `editmode:onclick`, `viewmode:disabled` and `viewmode:readonly`, are handed back with their authored values after a cycle.
+
+Frozen regions keep their saved contents.
+
+`editmode` on `<html>` follows each commit, and it is stripped from every save.
+
+A committed live switch drops `?editmode=` from the URL.
+
+`opens-in` is read once at boot and never rewritten.
+
+### 3.6 A complete example
+
+One persisted note, a participant registered before the loader, an explicit initial edit, and a composer that holds a comment until it is sent or discarded. The participant's script goes above the loader in the same document.
+
+```html example=mode-cycle-page
+<!DOCTYPE html>
+<html clay-mode-switch="live">
+<head>
+  <meta charset="utf-8">
+  <title>Notes</title>
+</head>
+<body>
+  <article data-id="note">
+    <div id="content" editmode:contenteditable inert-contenteditable="plaintext-only">A note kept in the file.</div>
+    <div class="composer" clay="editor-ui">
+      <input id="comment" unsent="comment" placeholder="Add a comment">
+      <button id="send" type="button">Send</button>
+      <button id="discard" type="button">Discard</button>
+      <span id="count" aria-live="polite"></span>
+    </div>
+  </article>
+  <script src="https://clayjs.com/v1/clay.js?plugins=unsent&exclude=richclay"></script>
+</body>
+</html>
+```
+
+The record is a controlled element, so a save writes the inert spelling back and no reader receives an editable note. The lease hands that surface to the session and takes it back on the way out, and a write that lands in a later turn checks the session is still current and still admits writes:
+
+```js example=mode-cycle-participant
+window.clay = window.clay ?? {};
+window.clay.modeParticipants = window.clay.modeParticipants ?? [];
+
+window.clay.modeParticipants.push({
+  id: "notes",
+  order: 10,
+  prepare: async (context) => {
+    const content = document.getElementById("content");
+    const count = document.getElementById("count");
+    const editable = "plaintext-only";
+
+    const paint = () => {
+      setTimeout(() => {
+        if (!context.isCurrent() || !clay.modeLifecycle.canWrite()) return;
+        count.textContent = `${content.textContent.trim().length} characters`;
+      }, 0);
+    };
+
+    return {
+      ready: null,
+      enable() {
+        content.setAttribute("contenteditable", editable);
+        content.removeAttribute("inert-contenteditable");
+        content.addEventListener("input", paint);
+      },
+      quiesce: async () => {},
+      resume() {
+        content.setAttribute("contenteditable", editable);
+        content.removeAttribute("inert-contenteditable");
+      },
+      dispose() {
+        content.removeEventListener("input", paint);
+        content.removeAttribute("contenteditable");
+        content.setAttribute("inert-contenteditable", editable);
+      },
+    };
+  },
+});
+```
+
+```js example=mode-cycle-submit
+const comment = document.getElementById("comment");
+
+document.getElementById("send").addEventListener("click", async () => {
+  const content = document.getElementById("content");
+  const line = document.createElement("p");
+  line.textContent = comment.value;
+  content.append(line);
+  clay.unsent.clear(comment);
+  comment.value = "";
+  await clay.save();
+});
+
+document.getElementById("discard").addEventListener("click", () => {
+  clay.unsent.clear(comment);
+  comment.value = "";
+});
+```
+
+Leaving edit is refused while the composer holds unsent text, and it succeeds once Send or Discard clears that text.
+
+### 3.7 The root attributes
+
+At load, ClayJS sets `editmode="true|false"` and `pageowner="true|false"` on `<html>` in both modes, `canedit="true"` while this person may edit (kept current on `clay:capabilitychange`), and `draftmode="true"` in draft mode. In edit mode, it also sets `savestatus` (`saving`, `saved`, `error`, `offline`, `conflict`) once the page settles, and `unsaved="true"` while there is work a save has not written. **All of them are removed on every save**, along with the host's `savetoken` and `documentetag`. The saved file's `<html>` carries none of them.
 
 Before ClayJS runs, `editmode` is **absent**, not `"false"`. CSS keyed on `html[editmode="false"]` shows edit chrome to visitors until boot. Key on `html:not([editmode="true"])` instead.
 
-### 3.3 Showing and hiding edit controls: clay-options
+### 3.8 Showing and hiding edit controls: clay-options
 
 Load the `clay-options.js` satellite and mark edit-only controls with `show-when:editmode="true"`:
 
@@ -493,9 +758,9 @@ Visibility attributes:
 - For viewer-only content, use `hide-when:editmode="true"`, which is visible when `editmode` is absent. `show-when:editmode="false"` stays hidden until boot and then appears.
 - The attribute that switches views is ordinary saved content. Setting `view="list"` on a saved element saves and syncs it to every collaborator. [Per-tab state](https://clayjs.com/docs/guide/architecture/#per-tab-state) covers tab-local views.
 
-### 3.4 Mode attributes: one file for editors and viewers
+### 3.9 Mode attributes: one file for editors and viewers
 
-Four attributes make an element behave differently by mode. A **save transform** writes the inert form into the file, and **edit mode** activates it on load. View mode never loads the activation code, so a viewer sees what the file holds.
+Four attributes make an element behave differently by mode. A **save transform** writes the inert form into the file, and **edit mode** activates it on load. A view boot never loads the activation code, so a viewer sees what the file holds.
 
 | Attribute | In the saved file | In edit mode |
 |---|---|---|
@@ -525,9 +790,9 @@ There is no general `editmode:<anything>`. Only these four attributes exist.
 
 Use `contenteditable="plaintext-only"` for titles, labels, and cells to prevent formatting and pasted markup. Make Enter blur instead of inserting a line break, as in the skeleton's keydown handler. Use `editable` ([richclay: rich text (`editable`)](https://clayjs.com/docs/guide/components/#richclay-rich-text-editable)) only where you need rich text.
 
-### 3.5 What works in view mode
+### 3.10 What works in view mode
 
-In view mode, `window.clay` keeps `ready`, `isEditMode`, `isOwner`, `toggleEditMode`, `Mutation`, `region`, `readData`, `writeData`, and `hasUnsavedChanges` (always `false`). It also includes whatever view-mode plugins and satellites add (`clay.conflicts` and `clay.morph` with `sync`, `clay.cms`, `clay.quickcrop`, `clay.toast`, and others). There is no `save`, `getHTML`, `addDocumentTransform`, `onSnapshot`, `undo`, `RichClay`, or `upload`, and no `markDirty` unless `sync` is loaded (where it is harmless).
+`window.clay` keeps `ready`, `setMode`, `mode`, `canEdit`, `modeLifecycle`, `isEditMode`, `isDraftMode`, `isOwner`, `toggleEditMode`, `Mutation`, `region`, `readData`, `writeData`, `assets`, `ephemeral`, `storage`, `host`, `trash`, `derived`, `effect`, `style`, `morph`, and `hasUnsavedChanges` (always `false`) in both modes. It also includes whatever view-mode plugins and satellites add (`clay.conflicts` and `clay.morph` with `sync`, `clay.cms`, `clay.quickcrop`, `clay.toast`, and others). There is no `save`, `getHTML`, `addDocumentTransform`, `onSnapshot`, `undo`, `RichClay`, or `upload`, and no `markDirty` unless `sync` is loaded (where it is harmless). On a template copy whose tab can edit, the `upgrade` plugin loads in view and `clay.save` holds only `replace`, so test `clay.isEditMode`, never `'save' in clay`.
 
 - Guard edit-only APIs with optional chaining (`clay.addDocumentTransform?.(fn)`), or return early with `if (!clay.isEditMode) return`. An unguarded call throws and stops the rest of the script for viewers.
 - Click handlers run for viewers too. Hidden buttons cannot be clicked, but guard edit actions anyway with `if (!clay.isEditMode) return`, as the examples do.
@@ -535,9 +800,9 @@ In view mode, `window.clay` keeps `ready`, `isEditMode`, `isOwner`, `toggleEditM
 - With `sync` loaded, a viewer rides the saved lane and receives each accepted save, so a published page updates live ([What sync is](https://clayjs.com/docs/guide/live-sync/#what-sync-is)).
 - Clicking inside `[trigger-save]` in view mode dispatches `clay:view-save-attempt`, so you can explain why nothing saved.
 
-### 3.6 When the page editor is ready
+### 3.11 When the page editor is ready
 
-Edit mode is decided at load, but a `page` document is ready to edit later. `clay.page.ready` resolves when its editor is mounted and accepts typing. `clay.page.status` holds that boot result: `{ phase, reason, installId, at }`.
+The mode this tab starts in is decided at load, but a `page` document is ready to edit later. `clay.page.ready` resolves when its editor is mounted and accepts typing. `clay.page.status` holds that boot result: `{ phase, reason, installId, at }`.
 
 `clay.ready` does not wait for the page editor. Because `plugins/page.js` exports no `ready`, `await clay.ready` can resolve while the saved article is still on screen. Late plugins do wait, so a page that ships with them needs nothing extra.
 
@@ -557,7 +822,7 @@ if (boot?.phase !== "ready") document.documentElement.setAttribute("read-only",
 
 `clay.page.install()` disposes the last installation and starts a fresh one with its own id, letting a page retry after a failure without reloading.
 
-### 3.7 The page editor on a phone
+### 3.12 The page editor on a phone
 
 At widths up to 560 px, the page editor's toolbar keeps four controls: Bold, Italic, Link, and More. Each is at least 44 by 44 CSS px inside a 204 px bar with 4 px gaps and 8 px padding. The selection bubble is hidden so two bars never appear at once.
 
@@ -565,13 +830,13 @@ More holds the rest: Strikethrough, Code, bulleted, numbered, and checklist list
 
 The bar is positioned from the visual viewport, not the layout viewport. Its top and horizontal bounds come from the visible area, so an on-screen keyboard cannot cover it and panning the visual viewport moves it with the page. The safe-area inset is read once per layout frame. Menus stay inside the visual viewport, open above the bar when there is room, and scroll internally. Desktop layouts are unchanged.
 
-### 3.8 Keyboard navigation in the page editor
+### 3.13 Keyboard navigation in the page editor
 
 Escape closes an open menu or the link popover first, returning focus to the control that opened it or to the editor.
 
 From a block selection, Escape moves focus from the writing surface to the first toolbar control while keeping the selection, so the keyboard is never trapped in `contenteditable`. In the toolbar, Left and Right move between controls, and Escape returns to the editor. The toolbar is a single tab stop with a roving tabindex: Tab leaves it forward and Shift-Tab leaves it backward. Inside a table, Tab moves across cells and Shift-Tab moves back. The editor takes Tab for nothing else.
 
-A table's column resize handle is a focusable vertical separator named for its column, with `aria-valuemin` 48, `aria-valuemax` 1200, and the current width in `aria-valuenow`. Left and Right preview a 10 px change (50 px with Shift), while Home and End preview the minimum and maximum. Enter commits the change, and Escape cancels it. Holding an arrow key previews across repeated keydowns. The keyup that ends the repeat, Enter, or leaving the handle commits one command, so a held arrow key records a single undo item. Double-click fits the column, and pointer dragging is unchanged. On a phone, the column's Width menu (Wider, Narrower, Fit to content, and Reset width once the column has a width) does the same job.
+A table's column resize handle is a focusable vertical separator named for its column, with `aria-valuemin` 48, `aria-valuemax` 1200, and the current width in `aria-valuenow`. Left and Right preview a 10 px change (50 px with Shift), while Home and End preview the minimum and maximum. Enter commits the change, and Escape cancels it. Holding an arrow key previews across repeated keydowns. The keyup that ends the repeat, Enter, or leaving the handle commits one command, so a held arrow key records a single undo item. A table with no widths fills the page; the first width you set pins the other columns at their drawn widths, in the same undo step. Double-clicking a handle resets the table to the page width, and pointer dragging is unchanged. On a phone, the column's Width menu (Wider, Narrower, Fit to content, and Reset widths once the table has widths) does the same job.
 
 ---
 
@@ -583,7 +848,7 @@ A save writes the current DOM with these changes:
 
 - Subtrees marked `no-save`, `no-snapshot`, or `editor-ui` are removed.
 - `freeze` elements write the inner HTML they had when they first appeared (at load or on insertion). Their live contents are a per-tab scratchpad.
-- Mode attributes go inert ([Mode attributes: one file for editors and viewers](https://clayjs.com/docs/guide/edit-mode/#mode-attributes-one-file-for-editors-and-viewers)). Root attributes `editmode`, `pageowner`, `savestatus`, `savetoken`, and `documentetag` are removed.
+- Mode attributes go inert ([Mode attributes: one file for editors and viewers](https://clayjs.com/docs/guide/edit-mode/#mode-attributes-one-file-for-editors-and-viewers)). Root attributes `editmode`, `pageowner`, `canedit`, `draftmode`, `savestatus`, `unsaved`, `savetoken`, and `documentetag` are removed.
 - `persist` controls write their live values ([`persist`: form controls](https://clayjs.com/docs/guide/record/#persist-form-controls)).
 - Runtime residue from ClayJS editors (richclay attributes, toolbars) and browser extensions (password managers, Grammarly, Dark Reader) is stripped.
 - Your hooks run ([Hooks](https://clayjs.com/docs/guide/saving/#hooks)).
@@ -638,6 +903,7 @@ Put `persist` on every `<input>`, `<textarea>`, and `<select>` whose value belon
 ```
 
 - On `input` (text-like fields) and `change` (checkbox, radio, select), ClayJS mirrors the live value into `value`, `checked`, or `selected`. A textarea's value goes into a `data-value` attribute while typing and becomes its text content in the save.
+- A `<textarea>` merges as one value, so do not use `<textarea persist>` for long text several people edit. Keep the text in a record element (`<pre><code>`) and bind an editor outside the records to it with `clay.bindText` ([OverType: a markdown editor](https://clayjs.com/docs/guide/components/#overtype-a-markdown-editor)).
 - A snapshot also copies every `persist` control's live state, so a value set from script with no event is saved too.
 - Password, hidden, and file inputs are never persisted. An authored `value` on them stays in the file.
 - `persist` goes on the control itself, never on a wrapper.
@@ -686,6 +952,7 @@ Live sync and undo pair elements across versions by **`data-id`, then `id`**, us
 - **Leave `data-id` off templates.** The command that clones a template assigns one. For a plain "add an item" button, `<button add-from="#item-tpl" add-to="#list">` handles the clone, the id, and the focus with no script.
 - **Never stamp ids on open.** Opening an old file must not rewrite it. Add an id when an item is created or first changed.
 - **Make ids without `crypto.randomUUID`** unless the file is only ever served over https or localhost, because it is missing in insecure contexts. The examples use `prefix + "-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6)`.
+- **A `data-id` is also what presence names.** A record target `{ kind: "record", id }` carries it, so a stable id is what lets a peer's badge find the row again after a reload or a merge ([Presence](https://clayjs.com/docs/guide/live-sync/#presence)).
 - **Use ids to find records in commands:** `` board.querySelector(`.card[data-id="${CSS.escape(id)}"]`) ``. Never find a record by position.
 
 ### 4.6 Assets
@@ -714,6 +981,33 @@ clay.ephemeral.toggle(card, "selected");   // add, remove, toggle(el, word, forc
 
 Use `ephemeral` for state on one element. State that comes from the URL hash and spans many records (the open card, a filter) is still painted with a runtime stylesheet ([Per-tab state](https://clayjs.com/docs/guide/architecture/#per-tab-state)).
 
+### 4.8 A template is an ordinary record with a tag
+
+A reusable template is a record like any other, marked with a tag. It stays editable, searchable, exported, synced and in a visitor's draft, and it needs no second store and no new format. The app reads the tag off the body it already has:
+
+```js
+const templates = open => Entries.live().filter(a => a !== open && summary({ body: Entries.body(a), $el: a }).tags.includes('template'));
+```
+
+The tag is matched outside code spans and fences, so a template entry that shows a `#template` example does not become a template itself. Using one copies its text into the page, and the new record is written by the same save as everything else.
+
+### 4.9 Keep a helper that reads the text beside the editor, in an `editor-ui` row
+
+A helper that reacts to the text being written belongs in a row a script builds beside the editor, marked `clay="editor-ui"`, and refreshed on a debounce. Nothing it draws is saved, printed or synced, and no keystroke pays for it beyond the debounce:
+
+```js
+el = document.createElement('div');
+el.className = 'starters';
+el.setAttribute('clay', 'editor-ui');
+$('#writer').before(el);
+
+function start(on) {
+  on($('#writer'), 'input', () => { clearTimeout(timer); timer = setTimeout(refresh, 300); });
+}
+```
+
+The row is built on demand and refreshed on that debounce. Everything it draws lives in the row, so it is never saved, printed or synced.
+
 ---
 
 ## 5. Saving
@@ -722,6 +1016,8 @@ Use `ephemeral` for state on one element. State that comes from the URL hash and
 
 In edit mode, ClayJS saves the whole document to `POST /_/save` on the page's origin (or `/_/save/<savetoken>` on HTML Clay). Cmd+S (Ctrl+S elsewhere) and clicks inside any `[trigger-save]` element call `clay.save()` on every edit-mode page, with or without autosave. A close warning appears whenever there are unsaved changes.
 
+Leaving edit saves first. If that save fails, or text is still unsent, or a conflict is open, the switch is refused with a code and the page stays in edit ([Leaving edit](https://clayjs.com/docs/guide/edit-mode/#leaving-edit)).
+
 #### 5.1.1 The saved title
 
 ClayJS derives the saved `<title>` from the document rather than keeping the authored `<title>`. The save projection reads the captured model and takes the first top-level H1, collapsing and trimming whitespace runs. A page with no top-level H1 gets the title `Untitled`. The server checkpoint renderer runs the same function on the same model, so a room checkpoint writes the same title a client save would.
@@ -734,7 +1030,7 @@ Title changes only update the document's content. ClayJS never derives or change
 
 `<html autosave>` present at load turns on autosave. Adding or removing it later changes nothing.
 
-- A watched DOM change or a `persist` input starts a 1500 ms debounce. Continuous changes save at most 10 s after the first one. Saves are throttled to one per 1.2 s.
+- A watched DOM change or a `persist` input starts a 1500 ms debounce. Continuous changes save at most 10 s after the first one. After each save, the next automatic save waits at least 1.2 s, and at least four times as long as that save took to prepare, up to 30 s, so a page whose saves are expensive saves less often instead of saving between keystrokes.
 - Measured: one edit saves at about 1.5 s, 50 edits in a second save once at about 2.5 s, and an edit every 300 ms saves at about 10 s.
 - Template content edits never trigger autosave.
 - A save that fails (500 or network) is **not retried** until the next edit or the browser's `online` event. `savestatus="error"` stays up. If your app can sit idle after a failure, retry yourself:
@@ -745,12 +1041,63 @@ Title changes only update the document's content. ClayJS never derives or change
   });
   ```
 
+A save is admitted before the page is captured. The spacing is decided first, and only an admitted attempt takes a snapshot, so nothing captures the page for a save that is still only an intention:
+
+```js
+const cooldown = Math.min(MAX_COOLDOWN_MS, Math.max(MIN_GAP_MS, COST_MULTIPLIER * costMs));
+const quietAt = Math.max(last, finished) + IDLE_MS;
+const continuousAt = Math.max(first + CONTINUOUS_MS, finished + cooldown);
+return Math.max(finished + MIN_GAP_MS, Math.min(quietAt, continuousAt));
+```
+
+The quiet window and the continuous ceiling are both computed from the clock, and the cooldown after a save scales with what that save cost.
+
 **The load-settle window.** At load, ClayJS takes a baseline of the document. It retakes the baseline once the page is quiet for 500 ms (at most 3 s), unless the user typed or a save ran. It then sets `savestatus="saved"` and fires `clay:baseline-settled`. Anything app code writes to the record during that window becomes part of the baseline: it is not saved, not autosaved, and not counted as unsaved. It reaches the file only when a later edit triggers a save:
 
 - Do not seed defaults, migrate a schema, or stamp ids at startup. Author defaults in the file.
 - If an app must write at startup, write after `clay:baseline-settled` (or once `<html savestatus>` exists), or follow the write with `await clay.save.force()`.
 
-### 5.3 Manual-save pages and batching
+### 5.3 Two baselines from one capture
+
+A page keeps two saved baselines from one save: the bytes a comparison uses, and the bytes the dirty check uses. Both domains are taken from one capture, because a comparison that borrowed the dirty domain would lose a batching region's edit, and a dirty baseline that borrowed the comparison domain would call a page clean while a `clay="no-trigger-autosave"` region still held new work.
+
+```js
+const { forComparison, forDirty } = captureForComparisonAndDirty();
+setLastSavedBaselines(forComparison, forDirty);
+```
+
+Both baselines advance from the same capture taken before the request, never from the live DOM, so an edit made while the save was on the wire stays unsaved. A caller with one string is a page with no batching region, and passes it for both: `setLastSavedContents(val)`.
+
+### 5.4 Reuse a verified parse only for the accepted capture
+
+Verifying the bytes a save will send already parses them, and a second parse of the accepted bytes pairs the whole page again. Keep the parse the verification paid for, and adopt its model only when the candidate is still this document:
+
+```js
+function withCandidate(verdict, errors, rendered, liveDocument) {
+  if (!errors.doc) return verdict;
+  const candidate = modelFromParsed(rendered, errors.doc, errors.parseErrors);
+  if (checkSource(candidate, liveDocument)) return verdict;
+  verdict.model = candidate;
+  return verdict;
+}
+```
+
+`checkSource` compares what a tree comparison cannot see: the doctype and the document-level comments outside `<html>`. A model that fails it is not this document, whatever the render verified as, so the save keeps its fallback path and adopts nothing. The model is only kept for the capture the acknowledgement is about, never for newer typing.
+
+### 5.5 Measure typing across several accepted saves
+
+Input to view timing alone misses the work that blocks the next input from arriving. Type continuously across several accepted saves, hold each response so typing continues while the request is on the wire, and report the input delivery gaps between key events beside the input to frame times:
+
+```js
+// node scripts/measure-save-pipeline.mjs --entries 5000 --typing-ms 60000 --pause-ms 3000 --response-delay-ms 2000
+inputGapsMs: stats(gaps),
+inputToFrameMs: stats(meter.inputs.map((input) => input.raf)),
+inputToViewsMs: stats(meter.inputs.map((input) => input.views)),
+```
+
+The gaps inside a save window are the ones that matter. A save that only shifts input to the next frame has still blocked the input that never arrived, and only a run across several accepted saves shows it.
+
+### 5.6 Manual-save pages and batching
 
 To disable autosave, such as for a long-form writer where frequent saves are unwelcome, omit `autosave`. Cmd+S, `[trigger-save]`, and the close warning still work. Save when the tab hides:
 
@@ -768,7 +1115,7 @@ To batch saves in part of an autosaving page, wrap that region in `clay="no-trig
 
 `clay.Mutation.pause()` and `resume()` hide DOM mutations from the mutation hub's listeners, including autosave's mutation trigger, while paused. The next save still writes those mutations. They do not pause input: `input` and `change` events on controls, including synthetic ones, still mark the page dirty and start autosave. Pair them in `try/finally`. An unbalanced pause silences mutation-driven autosave for the rest of the session.
 
-### 5.4 The save API
+### 5.7 The save API
 
 `clay.save()` returns `Promise<{ ok, msg, msgType, code, etag }>` and never rejects. One exception in 1.8.2: when capturing the page fails because a registered hook threw ([Hooks](https://clayjs.com/docs/guide/saving/#hooks)), the result has `msgType: "error"` and no `ok` field.
 
@@ -783,6 +1130,7 @@ To batch saves in part of an autosaving page, wrap that region in `clay="no-trig
 
 **Branch on `msgType`, not `ok`.** `ok: false` also means "nothing to save" or "queued behind another save". To ensure the host holds what the page holds now, use `flush`:
 
+- `clay.save.soon()` saves a discrete action (a moved card, a toggled checkbox) within about 250 ms instead of after the autosave wait. Calls within a second share one save, and each resolves with that save's result. A save you asked for with Cmd+S or `soon()` that an incoming merge cancels mid preparation is captured again once, after the merge settles (150 ms of quiet, at most 2 s); an autosave cancelled the same way is not retried. Leave typing on autosave.
 - `clay.save.flush({ keepalive, timeoutMs })` resolves `{ state: "view" | "clean" | "saved", etag }` only when the host holds the current bytes. It waits out the settle window and any in-flight save, and retries while the page keeps changing. It rejects with `err.state` of `failed`, `conflict`, or `blocked`.
 - `clay.save.force()` saves without the dirty check, writing `no-dirty` and `no-watch` edits. Template content edits need no force: `save()` and the close warning see them, and only autosave does not.
 - `clay.save.overwrite()` re-reads the host's current version stamp and force-saves over it. This is "keep mine" after a conflict.
@@ -791,7 +1139,42 @@ To batch saves in part of an autosaving page, wrap that region in `clay="no-trig
 - `clay.registerUnsavedState({ id, isPending })` registers work held outside the DOM (such as an unapplied form) so the close warning and `flush` respect it. Call the returned `changed()` when it changes and `dispose()` when done.
 - `clay.markDirty()` tells the dirty gate about an edit no mutation shows, for an editor whose surface is `editor-ui` and which writes the record itself.
 
-### 5.5 Conflicts on save (412)
+### 5.8 Size limits
+
+The limit comes from the host's `/_/meta` answer, `document.maxBytes`: the most bytes of uncompressed UTF-8 HTML one save body may have, inclusive. It counts only as a positive safe integer. A missing, zero, negative, fractional or non-numeric value means the limit is unknown, and `clay.save.limits()` resolves `{ maxBytes: null }`. Draft mode answers the same without asking the host at all. See [Hosts, assets and privacy](https://clayjs.com/docs/guide/hosts/#what-each-host-gives).
+
+A save is measured on the exact UTF-8 bytes it is about to send, after hooks, transforms and cleanup, and refused before anything is sent when it is over. The result is `{ ok: false, code: "save-too-large", sent: false, size }`, where `size` holds `{ bytes, maxBytes, state: "over" }`. Nothing is written: no accepted listener runs, no baseline moves and no recovery copy is cleared. A host that answers 413 maps to the same code.
+
+The host stays authoritative. A client that predates this check, a first save sent before discovery answers, and a limit that changed after it was read are all decided by the host's own refusal, which leaves the writing recoverable.
+
+`clay.save.inspect(html)` measures bytes that are not this page, such as a file you are about to import, without capturing, sending or moving a baseline:
+
+```js
+const size = await clay.save.inspect(candidateHTML);
+if (size.state === "over") return say("That is larger than this host can save.");
+```
+
+A real save that measures `near` or `over` fires `clay:save-size` and loads a small notice into the editor UI. It reports the last measurement, never a live size:
+
+- Near: `This file is getting large. At the last save attempt: 1.6 MB of 2.0 MB. Download a copy, then reduce its size; saving still works.`
+- Over: `This host can't save a file this size. At the last save attempt: 2.1 MB of 2.0 MB. Download a copy to keep your work.`
+
+**Download my copy** appears only when the measurement is over. The notice is hidden by a later save measurement below the threshold, and when the page leaves edit mode. It is loaded only when a measurement is near or over, so most pages never fetch it.
+
+To make a copy of the page without some of its records, remove them from the clone with `clay.getHTML({ transform })`:
+
+```js
+const html = clay.getHTML({
+  transform: (root) => {
+    for (const el of root.querySelectorAll("#entries > article.entry[data-drop]")) el.remove();
+  },
+  flushUndo: false
+});
+```
+
+The transform must be synchronous and its return value is ignored. The live page, the baselines and the network are untouched. See [Importing and exporting records](https://clayjs.com/docs/guide/architecture/#importing-and-exporting-records).
+
+### 5.9 Conflicts on save (412)
 
 On hosts that announce `conditional` (all three hosts in [What the host does](https://clayjs.com/docs/guide/model/#what-the-host-does)), every save sends `If-Match` with the version the tab last saw. If the file changed elsewhere and live sync has not merged that change yet, the host answers 412 and writes nothing.
 
@@ -801,7 +1184,7 @@ On hosts that announce `conditional` (all three hosts in [What the host does](ht
 - The first save after load can go out without `If-Match` on a slow host because version discovery is not awaited. That save is last-write-wins.
 - If you hide the built-in notice, you must still offer overwrite and reload.
 
-### 5.6 Hooks
+### 5.10 Hooks
 
 Hooks shape the saved bytes without touching the live page. Except for `onaftersave`, they run on a clone.
 
@@ -841,7 +1224,7 @@ clay.onSnapshot?.((root) => {
 
 Only strip `draggable="false"` if your own markup never authors it.
 
-### 5.7 Save status
+### 5.11 Save status
 
 ClayJS reflects save state on `<html>`, so you can style a status indicator with CSS alone:
 
@@ -860,7 +1243,7 @@ html[unsaved="true"]:not([savestatus="error"]):not([savestatus="offline"]) .chip
 
 In draft mode, nothing is saved on purpose, and `html[draftmode="true"]` indicates why the page is not marked saved.
 
-Put `#status` in chrome, or load the `indicator` plugin for a ready-made chip. With `clay-ui.js` loaded, save errors and offline states become persistent toasts. Without the `indicator` plugin, `clay-ui.js` also toasts "Saved" after every save; with it, set `clay.saveToast = true` to get those toasts too.
+Put `#status` in chrome, or load the `indicator` plugin for a ready-made chip. The chip's drawing arrives on demand, at the first input or the first save state, so it costs nothing at edit ready. With `clay-ui.js` loaded, save errors and offline states become persistent toasts. Without the `indicator` plugin, `clay-ui.js` also toasts "Saved" after every save; with it, set `clay.saveToast = true` to get those toasts too.
 
 Events, all on `document`:
 
@@ -883,7 +1266,7 @@ Events, all on `document`:
 
 A save writes only the document's own bytes, so a downloaded HTML file links to its images rather than embedding them. When the file opens, the browser fetches uploaded images from the host's URLs. Opening a copy where those URLs do not resolve shows broken images.
 
-### 5.8 Recovery copies
+### 5.12 Recovery copies
 
 `clay.recovery` keeps a local copy of edits the host has not accepted. It is not a save, and ClayJS never renders a page directly from it. After a reload, ClayJS compares the stored copies with the loaded file and asks before restoring one. A document is covered only for the channels its adapters register, so a page that registers no channel keeps no local copy.
 
@@ -960,7 +1343,7 @@ When an incoming frame (B) meets unsaved edits in this tab (A), ClayJS merges th
 
 More engine rules:
 
-- Text merges word by word inside a block, and formatting merges per character. Inline `<style>` and textarea text merge word by word. Scripts and comments merge as whole values.
+- Text merges word by word inside a block, and formatting merges per character. Inline `<style>` text merges word by word, while a `<textarea>` merges as one value. Scripts and comments merge as whole values.
 - Matched live nodes are moved, not recreated, so listeners, focus, caret, and iframes survive. An element that matches nothing (re-keyed, or changed beyond recognition among similar siblings) is removed and inserted fresh, and listeners attached directly to it are gone. **Use delegated listeners** on `document` or a stable root.
 - A new or changed inline `<script>` in the frame runs once after the merge. Guard one-time setup with `clay.start` ([Starting the app once](https://clayjs.com/docs/guide/architecture/#starting-the-app-once)).
 - Window scroll is restored. Inner scroll containers are not, except the focused element's own.
@@ -1061,9 +1444,98 @@ The built-in notice reads "Another edit replaced N changes" and offers **Revert
 
 ### 6.7 Presence
 
-hyperclay.com shows a fixed avatar stack (initials in hollow squares, a "+N viewing" count) when two or more people have the file open. **There is no API**: no event, no roster, no cursor or section data. An app cannot build its own "who is here" or "X is editing this card" from it; share that through a never-saved live store instead ([Live data: `clay="live"`](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live)). HTML Clay and Hyperclay Local have no presence.
+`?plugins=sync` loads presence. `clay.presence` is the facade (`clayjs/src/sync/presence-store.js`), installed on `window.clay.presence` when the store loads. It has three page-facing methods:
+
+```js
+const snapshot = clay.presence.getSnapshot();  // the same object until something changes
+const stop = clay.presence.subscribe(render);  // the current snapshot at once, then every change
+clay.presence.setTarget({ kind: "record", id: "card-1", field: "title" });
+```
+
+`subscribe(listener)` returns an unsubscribe function. It emits the current snapshot at once, even before the host answers, so a page never waits for a first frame. `setTarget(null)` clears this tab's target and publishes nobody anywhere; it does not fall back to the generic editing marker.
+
+**The snapshot.** `{ supported, recordAwareness, pageAwareness, people, anonymous }`. Each person is `{ id, name, you, canEdit, editing, sessions }`, and each session is `{ id, you, n, editing }`:
+
+```js
+{
+  supported: true, recordAwareness: true, pageAwareness: true,
+  people: [{
+    id: "p_ada", name: "Ada Lovelace", you: false, canEdit: true,
+    editing: { kind: "record", id: "card-1", field: "title" },
+    sessions: [{ id: "s1", you: false, n: 12, editing: { kind: "page", v: 1, epoch, generation, selection } }],
+  }],
+  anonymous: 0,
+}
+```
+
+Before discovery answers, the snapshot is unsupported with no people. The host decides who appears: each recipient gets a roster filtered by its own access, and nothing in the page can widen it (`src/sync/live-sync.js`, the `presence` event).
 
-### 6.8 Agents
+**Targets.** A target is `null`, a legacy dotted path string, a record target `{ kind: "record", id, field }` with `field` optional, or a page target `{ kind: "page", v: 1, epoch, generation, selection }`. A page selection is `text` (`anchor` and `head`, each `{ block, rel }`), `blocks` (`{ ids }`), or `cell` (`{ block, row, col }`).
+
+The bounds come from `src/sync/presence-target.js`:
+
+- A record id of 1 to 128 printable ASCII characters.
+- A field of `title`, `description`, `labels`, `members`, `dates`, `checklist`, `comment`, or `attachments`.
+- 8 KiB per target.
+- 256 bytes per page id.
+- 1 KiB per decoded relative position.
+- At most 128 block ids.
+
+An invalid target is refused, never repaired. Updates are coalesced to one every 250 ms, a stable target renews every 5 seconds, and it expires 15 seconds after the host receives it.
+
+**A record target from a focused control.** Publish a target only while the control that writes the record has focus, and publish `null` the moment it stops: on blur, when the open record changes, when the page is hidden, when the record goes to Trash, and when the tab leaves edit mode or enters draft mode. After a blur, check again on the next microtask, so focus moving inside the same control does not flash `null`. A record with one writing control sends the fieldless shape, `{ kind: "record", id }`, where `id` is the record's `data-id`. A target never carries a title, text or date. The Journal template does this in `RecordPresence` (`templates/00-journal/journal.html`):
+
+```js
+function reconcile() {
+  const id = capable && clay.isEditMode && !clay.isDraftMode && !document.hidden && writerHasFocus()
+    ? openEntryId() : null;
+  if (id === sentId) return;
+  sentId = id;
+  clay.presence.setTarget(id ? { kind: "record", id } : null);
+}
+```
+
+`capable` is the snapshot's `recordAwareness`, so a host without `record-awareness-v1` is sent nothing. Renewal and expiry belong to ClayJS: a page sets a target once and keeps no timer of its own.
+
+**Showing who is on a record.** Build a map from record id to people out of each snapshot. Skip `you: true`, keep only targets with `kind: "record"` whose id is a live record on this page, and count a person once however many tabs they have. Write names with `textContent`. A slot a script creates carries `clay="no-save no-watch no-snapshot"`. A slot inside a repeated row's `<template>` carries only `clay="no-save no-watch"`: a save removes `no-snapshot` nodes from template content too, which would delete the slot from the file, and the rows sapjs renders from the template are marked `editor-ui`, which already keeps them out of snapshots. Repaint only when the names change, so a renewal announces nothing. A badge is advisory: it never blocks editing and never reaches a record.
+
+**Hosts.** The client picks exactly one transport from `/_/meta` (`connect` in `presence-store.js`):
+
+- hyperclay.com relays presence through the host. The target goes to `POST /_/presence`, and the roster comes back as a named `presence` event on the document's stream, with one person per account and one session per tab.
+- HTML Clay announces `awareness: { transport: "broadcast", scope }`. Its presence travels between tabs of the same browser on a channel named for the document scope (`src/sync/local-presence.js`). Each tab is a fresh random session, not an account, shown under the label "This computer". Two documents that share a file name never meet.
+- Hyperclay Local likewise shows tabs on this computer, not authenticated people.
+
+In view mode the reader draws the roster too. It takes the roster from the stream it already follows, as a named `presence` event, so it opens no second connection. The roster UI is a first-use download that comes with the first presence frame, and a reader that receives no frame downloads none of it. A reader publishes no target and joins no writable room, because its lease has no write half: a target a page sets in view mode sends nothing. Its roster goes away when its stream closes.
+
+Each part needs its own extension: `presence` for the roster, `presence-editing` for the generic editing marker, `record-awareness-v1` for record targets, and `page-awareness-v1` for remote carets.
+
+**Runtime only.** The roster UI is marked `clay="no-save no-watch no-snapshot"` (`RUNTIME_ONLY` in `src/ui/bevel-controls.js`, applied in `src/sync/presence.js`). It never reaches a save, a snapshot, or the page's own change detection, and a roster change is not an edit. Remote carets are editor decorations, not document content ([Remote carets](https://clayjs.com/docs/plugins/page/#remote-carets)). All three tokens are needed: `no-save` alone only keeps a name out of the file, and the snapshot clone that peers receive is emitted before the save-only regions are stripped, so `no-snapshot` is what keeps a name out of that clone, while `no-watch` is what keeps a roster change from counting as an edit (`src/sync/presence.js:15-28`).
+
+Presence is not for app data. For state that must be shared and is not presence, use a live store ([Live data: `clay="live"`](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live)).
+
+### 6.8 The page format floor
+
+A document records the lowest page format a writer must understand, in document metadata outside the page value:
+
+```html
+<meta name="clay-page-format" content="1">
+```
+
+No marker means floor 0, and a floor only ever rises: a later save cannot remove the marker or lower it. The value is protocol capability, not permission. The host still applies every access check it applied before, and the marker cannot be used to discover a private document.
+
+**Every page write declares its capability.** A save and a live write carry `X-Clay-Page-Format: 1`, the format the runtime knows rather than the format this document uses, so even an ordinary document's save declares it.
+
+**A host refuses a write below the floor.** Nothing is mutated. The answer is HTTP `409` with a body carrying the code `page-format-upgrade-required`, the same string as its `reason` on the save lanes, and `minimum`, the floor the document requires. That covers the ordinary save, the live data lanes, a checkpoint, a version restore and the relay, on all three hosts, and a refused live request ends that tab's stream so it receives no newer content. The stored file, its version history and its page state stay as they were, and the refused tab keeps its own unsaved work.
+
+**A writer raises the floor on its first new format, through one real save.** The gate reads the floor the document already has, asks the host, and adds the marker to an otherwise equivalent capture. Activation is idempotent. It is refused while any admitted live page editor declares a capability below the floor it would set, and that check happens under the host's per-document write lock, so an editor that registers between the check and the save is refused rather than missed. A refused activation leaves ordinary writing available and every unsaved store as it was, and says **This document uses a newer page format; update the editor in the other tabs to keep writing**. The command that asked applies only if the same editor installation and document revision still exist once activation succeeds; otherwise the answer is retryable and the content is untouched.
+
+**A host announces `page-format-v1` only when it can hold the floor**, meaning its enforcement and its tolerant checkpoint renderer are installed. On a host that does not announce it, a new format command is refused as `page-format-unsupported` and writes nothing.
+
+**Who reads what.** ClayJS 1.16.0 and later keep floor 1 content, so those tabs are the cohort that can stay open while a floor 1 document is written. The published 1.15.x tabs cannot be changed: once a document's floor rises they are refused writes with `page-format-upgrade-required` instead of saving a version that would drop the new content, and their own unsaved work stays in the tab. A floor 0 document keeps working on all of them.
+
+Opening a document that is already at floor 1 asks for nothing: only a command that writes a newer format raises a floor, and a document that never uses one never records one.
+
+### 6.9 Agents
 
 An agent edits a malleable file the way a person in another tab does:
 
@@ -1072,7 +1544,7 @@ An agent edits a malleable file the way a person in another tab does:
 - **`ai-edit`** (`?plugins=ai-edit`): select text, press Cmd+J, and describe the change. The rewrite is previewed in place; Keep saves it, Revert discards it. Available where the host offers the `ai-edit` helper: HTML Clay, Hyperclay Local, and hyperclay.com (for the owner and team editors on a paid plan, billed to the document's AI credits).
 - **The data API**: a host that announces `data-read`/`data-write` serves `/_/api/<file>`, a JSON read and write interface over the file defined by a rules tag ([Import and export](https://clayjs.com/docs/guide/architecture/#import-and-export)). `clay.readData()` and `clay.writeData()` call it from the page; `writeData` is for agents and other processes, and refuses while the page has unsaved edits.
 
-### 6.9 Live data: `clay="live"`
+### 6.10 Live data: `clay="live"`
 
 Everything above moves at save speed: a peer sees your change after your next save. A live store is for state that changes faster than that, such as a game board, a score, a cursor, or a timer. It is one JSON script that ClayJS holds as an object in memory. Page code changes it through ops, every tab of the document sees each change at once, and ClayJS writes the value back into the file at checkpoints.
 
@@ -1235,6 +1707,7 @@ Traps:
 | `> ` | toggle |
 | ` ``` ` | code block, when the whole paragraph is the fence |
 | `---` | divider, when the whole paragraph is the dashes |
+| `" ` | quote, when the document's format gate allows it; otherwise the space is typed as itself |
 
 | Typed around text | Becomes |
 |---|---|
@@ -1248,7 +1721,7 @@ An opening delimiter must follow the start of the line, whitespace, or opening p
 
 **Backspace immediately after a shortcut restores the typed characters**, delimiters included, through input-rule undo. It is a single history step, does not drop a peer's concurrent edit, and reapplies on redo. After another keystroke, the shortcut is plain text and Backspace deletes one character as usual.
 
-None of this loads for a reader. The input rules, menus, and title adapter are editor code, and a Document's view mode fetches none of them.
+None of this loads for a reader. The input rules, menus, and title adapter are editor code, and a Document that never enters edit fetches none of them. A live entry fetches them while the tab still shows view ([switching without a reload](https://clayjs.com/docs/guide/edit-mode/#switching-without-a-reload-clay-mode-switch-live)).
 
 ### 7.2 sortable: drag to reorder
 
@@ -1273,6 +1746,7 @@ None of this loads for a reader. The input rules, menus, and title adapter are e
 - `onsorted="code"` runs on drop with `this` and `evt`.
 - Containers added later bind after about 200 ms.
 - `window.Sortable` is SortableJS 1.15.6. `Sortable.get(el).option(name, value)` changes an instance.
+- `clay.sortable.move(item, toContainer, beforeItem = null)` makes the reorder a drag makes, without dragging and without waiting for SortableJS. It fires the same `clay:sorted`, records the same undo step, and answers `{ ok: true, moved }` or `{ ok: false, code }` with `not-editable`, `detached`, `item`, `group` or `anchor`. Resolve `beforeItem` by `data-id` at the moment of the move, and use it for keyboard and touch moves.
 
 Traps:
 
@@ -1297,12 +1771,12 @@ Traps:
 
 - `commit` must be synchronous. For async work (an upload or fetch), `await` it first, then make every DOM write in one synchronous `commit`. Pausing undo across an `await` loses the mutations made before the `await`.
 - Not recorded: `editor-ui`, `no-undo`, `no-watch` regions, `richclay` regions, and every change a merge brings in.
-- Attribute and text steps are skipped if what they would restore has changed since (for example, by a peer). Structural steps are not: undoing "Add card" removes the card even if a peer edited it since, and redo replays without checking. In a collaborative file, treat undo as safe only for the person's own recent work. If that matters, call `clay.undo.clear()` when a `clay:sync-applied` frame touches records in the history.
+- Every step is checked against the document as it stands before either stack moves, so a step applies whole or changes nothing. Undoing "Add card" checks that the card is still the node the step added and still holds what the step recorded; if a peer edited it, the undo is refused with `content-changed` and the card stays as the peer left it. A moved neighbour refuses with `structure-changed`, and a reused `data-id` with `duplicate-id`. A refused step stays on top and fires `clay:undo-refused`; replay it once the conflict is gone, or drop it with `clay.undo.discard(entryId)`. [undo](https://clayjs.com/docs/plugins/undo/) lists every code.
 - Also exposed: `clay.undo.on("undo" | "redo" | "commit" | "clear", fn)`, `canUndo`, `canRedo`, and `history`.
 
 Traps:
 
-- **It takes Cmd+Z in every text field**, including inputs it does not record (such as a non-persist input), so their native undo is lost.
+- **It leaves Cmd+Z to text fields.** Inside an `input`, `textarea`, `select` or `contenteditable` subtree, the browser's own undo runs. A plain control's typed value is not content until `persist` or a command writes it, so page undo has nothing to replay for it.
 - History is per tab, capped at 100, and not saved.
 - Undoing a delete re-inserts the original node even if a peer re-created an equivalent. Dedupe by `data-id` on `clay:sync-applied` if needed.
 
@@ -1335,7 +1809,7 @@ async function imageSource(file) {
 - Events: `clay:upload-start`, `clay:upload-progress`, `clay:upload-done`, and `clay:upload-error`.
 - Host limits: HTML Clay and Hyperclay Local allow 25 MB per file; hyperclay.com allows 10, 20, or 100 MB by plan.
 - The URL is a host path: `/_/uploads/assets-<document>/<name>`. Write it exactly as returned. Every address of the host serves it, so it survives renaming or moving the document. Never rebuild it from parts.
-- Uploaded assets on hyperclay.com are publicly reachable by URL even when the document is private.
+- On hyperclay.com, an upload made from a document follows that document's read access once `document.upload.access` is `document`; before the account's protection migration it stays reachable by URL. To refuse private media on a host that cannot protect it, start the upload with `clay.upload.start(file, { requiredAccess: "document-or-local" })` ([Privacy](https://clayjs.com/docs/guide/hosts/#privacy)).
 
 `clay.quickcrop(file, { aspect, maxWidth, maxHeight, type, quality })` opens a crop dialog and resolves `{ blob, dataURL, width, height }`, or `null` on cancel. It does not upload; wrap the blob as a `File` and pass it to `clay.upload`. Only one cropper opens at a time, and it sets `body.style.overflow = "hidden"` while open, which a save at that moment writes into the file.
 
@@ -1381,7 +1855,7 @@ For fixed content, such as code samples in a docs page, mark the block `clay="fr
 
 ### 7.9 OverType: a markdown editor
 
-For a notes or journal app where Markdown is the format, OverType (`https://cdn.jsdelivr.net/npm/overtype@2.6.1/dist/overtype.min.js`) is a textarea under a styled preview. **The textarea is not the record.** Keep each entry's text in a text element of the record, put the editor in a `clay="freeze"` region outside the saved records, and bind it to the open record with `clay.bindText` (`?plugins=bind-text`):
+For a notes or journal app where Markdown is the format, OverType is a textarea under a styled preview. Load it with `await clay.assets.load("overtype")`, which takes it from the release that served `clay.js` ([Libraries on demand](https://clayjs.com/docs/guide/loading/#libraries-on-demand)). **The textarea is not the record.** Keep each entry's text in a text element of the record, put the editor in a `clay="freeze"` region outside the saved records, and bind it to the open record with `clay.bindText` (`?plugins=bind-text`):
 
 ```html
 <article data-id="a"><pre><code class="entry-body"># Morning
@@ -1475,7 +1949,6 @@ Rules for sapjs in a malleable file:
 - **Give records a `data-id`**, and `data-id=""` on blueprints so `$add` and `trigger-add` mint fresh IDs. Live sync pairs elements by it.
 - **Put `persist` on bound inputs inside records** so typed values reach the attributes a save captures.
 - **Undo, redo, and sync merges restore `persist` controls' live values** from their attributes, so sapjs reads what the file says. Controls without `persist` are not restored; give them `persist` or re-sync them yourself.
-- **`viewmode:` attributes log `W03`** (unknown attribute) in sapjs, such as [Mode attributes: one file for editors and viewers](https://clayjs.com/docs/guide/edit-mode/#mode-attributes-one-file-for-editors-and-viewers)'s `viewmode:readonly`. The warning is harmless, though it makes a "no warnings" check fail.
 - **Hide blueprints in your own CSS** (`[item][template] { display: none }`); sapjs's own rule arrives only with the script. Sapjs also adds `[hidden] { display: none !important }` page-wide.
 - A pass is batched: after a write, call `Sap.refresh()` before reading painted output. Expressions compile with `new Function`, so a Content Security Policy without `unsafe-eval` breaks them.
 
@@ -1491,7 +1964,7 @@ Rules for sapjs in a malleable file:
 
 It fits fixed-layout content sites such as landing pages, menus, pricing, FAQs, and team pages, where a non-developer changes copy and images. It does not fit apps where editing is the product: its form is a separate surface from the content, new list items clone the first item's attributes (including its state), and rich text inside lists is flattened in the sidebar. A file can use both if the CMS owns the header copy, the app owns `<main>`, and the rules never reach into the app's region. Give every list that can become empty a `cms-template` seed hidden by CSS, not by the `hidden` attribute (which is copied into every new item). Add `sortable` to the plugin list for drag in the sidebar.
 
-The rules tag can declare which editor opens. `data-cms-view="inline"` edits text in place and opens small popovers for everything else, while no attribute (or `"sidebar"`) opens the form in a side panel. The "Edit content" button opens whichever the page declares.
+The rules tag can declare which editor opens. `data-cms-view="inline"` edits text in place and opens small popovers for everything else, while no attribute (or `"sidebar"`) opens the form in a side panel. The "Edit content" button opens whichever the page declares. The CMS edits only in edit mode: while the page is in view, `clay.cms.open()` answers `{ ok: false, code: "not-allowed" }`, so a button of your own calls `clay.setMode("edit")` first.
 
 The CMS also edits how a page looks. A rule ending in `@--name` reads and writes one CSS custom property in an element's `style` attribute. For example, `"accent": "html@--color-accent"` with `a { color: var(--color-accent) }` in your CSS gives the owner a color picker. Any `--color-*` name gets a color picker, any `--font-*` name gets a list of 40 Google Fonts, and the CMS keeps one `<link data-hcms-fonts>` loading the fonts in use. For a layout choice, put `data-hcms-component:data-layout="variant"` and `data-hcms-options:data-layout="1:cols-1 2:cols-2 3:cols-3"` on a section and key your grid CSS on `[data-layout]`: the owner gets icon tiles, and the choice writes only the attribute. Style fields on `html`, `body`, or `:root` gather in a "Page style" group at the top of the form.
 
@@ -1638,7 +2111,7 @@ Open on a click that is not on an editable field, handle, input, or link. Close
 
 When a dialog must aggregate several records, render it into `editor-ui` and write each change back to its record by id. Call `clay.markDirty()` per edit if the record is not written immediately, and re-render it on `clay:sync-applied` without disturbing the focused field.
 
-**Half-typed text in a detail field outlives the view.** A comment box or description being edited sits in chrome (`clay="editor-ui"` or `clay="freeze"`) and carries `unsent="<name>"`. ClayJS keeps its value per record (the nearest `[data-id]`) and name in this tab, outside the file. Close the detail, take a sync redraw, or reload, and the text is back with the close warning on until it is sent.
+**Half-typed text in a detail field outlives the view.** A comment box or description being edited sits in chrome (`clay="editor-ui"` or `clay="freeze"`) and carries `unsent="<name>"`, with the `unsent` plugin loaded (`?plugins=unsent`). ClayJS keeps its value per record and name in this tab, outside the file. The record is named by the nearest `unsent-key` attribute, and by the nearest `[data-id]` when there is none, so a composer for a record that does not exist yet can name its destination (`unsent-key="capture:board"`). While a draft is held, leaving edit is refused with `pending-input`. Close the detail, take a sync redraw, or reload, and the text is back with the close warning on until it is sent.
 
 ```html
 <div class="detail" clay="editor-ui">
@@ -1757,7 +2230,27 @@ Sap.batch("Import CSV", () => {
 
 A rules tag with `data-rules-name="api"` gives agents and the host's data API the same shape your export uses.
 
-### 8.10 Starting the app once
+### 8.10 Importing and exporting records
+
+The Journal keeps every record in one container, so a backup, an import, a selected export and a print are four ways of copying or writing that same set. Each one is a named function in `journal.html`.
+
+- **Back up the exact fields, blanks and Trash included.** `Backup.records` reads every record with all of its fields, and `Backup.envelope` wraps them as `{ format, version, exportedAt, entries }`. An empty body and a trashed record are still records, so a backup restores what the file holds rather than what the view shows. Markdown is not an exact data backup.
+- **Parse, preview and revalidate before committing.** `Backup.parse` reads a file inertly and refuses unknown fields, missing fields, duplicate ids and bad dates with a code. `Backup.plan` sorts the rows into fresh, identical and conflicting ones, `planRestore` offers `keepBoth` for a row that changed here, and `Backup.verify` reads a candidate back field for field. A refusal at any of those points changes nothing.
+- **Commit once, synchronously.** `confirmImport` re-reads the limit, compares the current capture with the preview's baseline, replans and re-verifies, then appends the prepared records in one synchronous step followed by one `clay.save.soon()`. There is no await between the last check and that step, so a refusal leaves the page, the route, the selection and the dirty state as they were.
+- **Measure the candidate against the host's limit.** `candidateWith` builds the bytes a save would send with the new records already in place, and `measureHTML` asks `clay.save.inspect` about them. An over-limit import is refused before a single record enters the document.
+- **Export only the bytes selected.** `selectedCopy` removes every unselected article from the copy inside `clay.getHTML({ transform })`, so the records left out are gone from the file rather than hidden by CSS. `verifySelectedCopy` reads the result back and checks the exact id set.
+- **Move a year out only after the copy you kept checks out.** `YearArchive.archive` downloads the year as a `.htmlclay` copy and an exact JSON backup and removes nothing; starting a download proves nothing about a second copy. **Finish moving this year** asks for the file the person kept, reads it inertly, and requires exactly the reviewed records, field for field. A different file, a changed record or a record that joined the year since the review refuses with nothing removed. Before removing, `ArchiveMoves.stage` keeps the reviewed records in the `journal.archive-moves` recovery channel and awaits its durable receipt; a browser that cannot keep it refuses and offers the copy only. The removal itself is one synchronous step after a last re-check, followed by one `clay.save.soon()`. The move is cleared only by a saved file whose bytes lack every reviewed id, so a save that never lands leaves **Archive move awaiting save** after a reload. A year whose entries link pictures kept in the journal's own files can be copied but not moved, because a copy cannot carry them yet.
+- **Print the canonical records.** `printSelected` flags the chosen live articles with the ephemeral `print-pick` word and print CSS narrows the printout to them, so a printout is the records themselves, not the filtered list or an open editor. The flag is never saved, and another tab's sync never carries it.
+
+```js
+const attempt = candidateWith(added);
+if (!Backup.verify(attempt.html, attempt.expected).ok) return;
+const size = await measureHTML(attempt.html, limit);
+if (size.state === "over") return;
+store.append(fragment);
+```
+
+### 8.11 Starting the app once
 
 Start the app with `clay.start` so initialization runs once per page. A live-sync merge can re-insert an inline script and run it again, which doubles every listener and every chrome element. `clay.start` runs its function once after `clay.ready`, and a repeat call does nothing:
 
@@ -1769,7 +2262,7 @@ clay.start(() => {
 
 A page with more than one app script names each one so they do not share a slot: `clay.start("board", fn)`.
 
-### 8.11 Document size and record limits
+### 8.12 Document size and record limits
 
 Every save captures and serializes the whole document, every change check captures it again, and every peer merges the whole document per accepted save. Measured in jsdom and scaled to a browser (estimates):
 
@@ -1780,9 +2273,11 @@ Every save captures and serializes the whole document, every change check captur
 | 3,000 | 1.3 MB | ~120 ms | ~300 ms | ~190 ms |
 | 6,000 | 2.6 MB | ~250 ms | ~650 ms | ~400 ms |
 
+Typing also costs one Sap pass, and a pass visits every record. Sap skips rereading unchanged record values, but it still builds fresh objects for every record, so the pass grows with the record count: at 5,000 records in jsdom, a body edit's pass takes about 27 ms ([Cost at size](https://clayjs.com/docs/plugins/sap/#cost-at-size)).
+
 Up to about 1,000 records feels instant. From 1,000 to 3,000 there is a visible hitch at each save. Past about 3,000 records or 1.5 MB, autosave stalls typing and peers lag. Hosts cap a save at 5 MB (hyperclay.com), 20 MB (Hyperclay Local), and 50 MB (HTML Clay). Design for archiving: one file per year, a hidden archive section that can move to another file, or one file per project.
 
-### 8.12 Styles a script writes
+### 8.13 Styles a script writes
 
 Use `clay.style` when a script owns CSS that should stay in the saved document. The saved style paints the next load before the script runs. When the script runs, it refreshes that same tag with its current CSS:
 
@@ -1815,16 +2310,20 @@ Use `clay="editor-ui"` instead for CSS that viewers must not receive or that rep
 | Who edits | the local user | the local user; teammates through device sync | owner, team editors, edit-link holders |
 | Live sync | tabs on this machine | tabs, plus other devices through the sync engine | every editor and viewer |
 | Outside disk edits reach open tabs | yes (agents, text editors) | yes | no disk except through device sync |
-| Presence | none | none | avatar stack, no API |
+| Presence (`clay.presence`) | tabs of this browser, shown as "This computer" | tabs on this computer, relayed by the app | one person per account and one session per tab, filtered per recipient |
 | `by` on frames, editing marker | no | no | yes |
 | Live stores ([Live data: `clay="live"`](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live)) | tabs of one browser at full speed | tabs of one browser at full speed; other devices at save speed | every editor at full speed |
-| Page editor merge state ([Live data: `clay="live"`](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live)) | none in the file: open tabs share it, a fresh open rebuilds it from the article | kept beside the file | kept beside the file |
+| Page editor merge state ([Live data: `clay="live"`](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live)) | kept beside the file: `document.pageState.href` returns the state stored with the exact bytes on disk | kept beside the file | kept beside the file |
 | Wire and ai-edit | yes | yes | ai-edit only, for owners and team editors on a paid plan |
 | Data API write | yes | yes | read only |
 | Uploads | 25 MB, in `~/htmlclay/uploads/` | 25 MB, in the root's `uploads/` | 10, 20 or 100 MB by plan, in the account's `uploads/` |
 | Upload access (`document.upload.access`) | `local` | `local` | `document` once the account's uploaded files are protected; no field before that |
 | Version history | yes | 60 days, newest 20 | a version per save; a restore does not reach open editors' tabs, so reload after restoring |
-| Max save | 50 MB | 20 MB | 5 MB |
+| Max save (`document.maxBytes`) | 50 MB | 20 MB | 5 MB |
+
+The `/_/meta` answer carries `document.maxBytes`: the maximum uncompressed UTF-8 HTML save body, inclusive. All three hosts send it, and ClayJS measures a save against it before sending, so a document that is over the limit is refused instead of lost ([Size limits](https://clayjs.com/docs/guide/saving/#size-limits)). A missing or unusable value means the limit is unknown, and the host's own refusal is the only answer.
+
+On hyperclay.com only, the same block carries `document.maxBytesMeasures: "file"`. It means the limit is measured without the `<script merge="page">` tag that holds the document's live state. HTML Clay and Hyperclay Local send no such field.
 
 A plain static server or a file opened from disk can show the file in view mode, but cannot save it. Use the `demo` plugin for a public demo that saves into each visitor's browser.
 
@@ -1855,6 +2354,7 @@ Hyperclay Local and HTML Clay each bundle one exact, published ClayJS release, c
 - **Canonicalization on every write.** Save, data API writes, restore, export and live-sync frames turn those local addresses back into the public `https://clayjs.com/...` URLs and remove the descriptor before anything reaches disk. A saved or downloaded file never contains a `/_/clayjs/` address, so it stays portable to any host. A request with `Clay-Source: 1` receives the canonical bytes unprojected.
 - **Versions.** A rolling `https://clayjs.com/v1/` URL is served from the host's bundled release. If a document pins a release the host does not bundle, or names a runtime file the bundled release lacks, every runtime URL is left public. It loads online, is not promised offline, and the response carries a `Clay-Runtime-Unavailable` header that says why. The host never substitutes another release's files into a page.
 - **Older Journals.** Journals created before the release bundled its libraries load OverType and highlight.js from other CDNs, and their fonts from Google Fonts. The release maps three exact URLs to copies it ships: `https://cdn.jsdelivr.net/npm/overtype@2.6.1/dist/overtype.min.js` and `https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js` to the same classic builds (which define `window.OverType` and `window.hljs`, with their licenses and pinned hashes in `compat/journal-assets.lock.json`), and the Journal's Google Fonts stylesheet URL to a stylesheet over the bundled IBM Plex files. Each match is the whole URL. Another version, a query string, another file or another host stays on the network. A Journal saved with those URLs edits offline, and a document that names anything else from those CDNs does not.
+- **The first switch to edit.** A document opened offline in view can switch to edit without the network. The switch reloads into an edit boot, and every file that boot loads (the mode controller, the plugins, the Document editor and their late imports) is in the bundled release. Both hosts serve that set from the release with its index digest, the first edit saves the canonical public URLs, and the reopened file is projected again. ClayJS checks it per release: a mode file missing from the release fails the closure check.
 - **What stays online.** Pictures and media hosted elsewhere, AI features and collaboration with other people need the network. A picture uploaded into the local folder is a local file and works offline.
 - **Checking a host.** `node scripts/verify-offline-closure.mjs` in the ClayJS repository checks a release's closure: every listed file is present with its recorded hash, and every module import resolves inside the release. It runs in three modes: `--package-root <dir>` for a built checkout, `--published-root <dir>` for an unpacked release tree and `--base-url <url>` for a running host's `/_/clayjs/<version>/` prefix. With `--base-url`, pass `--index <file>` naming the host's own bundled index. Without it, the check compares the host against the checkout's index.
 
@@ -1870,7 +2370,7 @@ ClayJS gives you one file per document that edits and saves itself. Here is what
 
 Two plugins replace the old advice to hand-build a [block writer](https://clayjs.com/docs/guide/recipes/#block-writer) or wait for autosave:
 
-- **The [page editor](https://clayjs.com/docs/plugins/page/)** (`?plugins=page`) is a Notion-like block editor for one `article[data-page]`, backed by Yjs, where typing reaches other people as they type. It includes headings, lists, checklists, toggles, callouts, code, images, files, typed tables, boards, charts from a table, and CSV import.
+- **The [page editor](https://clayjs.com/docs/plugins/page/)** (`?plugins=page`) is a Notion-like block editor for one `article[data-page]`, backed by Yjs, where typing reaches other people as they type. It includes headings, toggle headings, lists, checklists, toggles, callouts, code, images, files, typed tables, boards, charts from a table, mentions of people and dates, emoji, a page icon and cover, CSV and Markdown import, and Markdown and self-contained HTML export.
 - **[Live stores](https://clayjs.com/docs/plugins/live-sync/)** (`clay="live"` and `clay.live()`) move fast-changing state at network speed (25 frames per second) instead of save speed. Use [live data](https://clayjs.com/docs/guide/live-sync/#live-data-clay-live) for games, scores, and shared state.
 
 The old limits apply elsewhere. Ordinary `editable` regions and DOM records have no CRDT and merge at save time. Rich text outside the page editor has no tables, and without `live-data`, the page editor falls back to file saves.
@@ -1879,7 +2379,7 @@ The old limits apply elsewhere. Ordinary `editable` regions and DOM records have
 
 | What you are comparing to | What ClayJS gives | What is missing | What to build instead |
 |---|---|---|---|
-| **Google Docs** | Keystroke co-editing, tables, code, callouts, and images in the [page editor](https://clayjs.com/docs/plugins/page/); word-level save merge in `editable`; recoverable conflicts; version history; `ai-edit` | Comments, suggestion mode, live cursors, pagination, footnotes, `.docx` export, tables in `editable` rich text | The [page editor](https://clayjs.com/docs/plugins/page/) or a [block writer](https://clayjs.com/docs/guide/recipes/#block-writer); comments as `<aside data-id data-anchor>`; print CSS for PDF |
+| **Google Docs** | Keystroke co-editing, tables, code, callouts, and images in the [page editor](https://clayjs.com/docs/plugins/page/); word-level save merge in `editable`; recoverable conflicts; version history; `ai-edit` | Comments, suggestion mode, live cursors outside the page editor, pagination, footnotes, `.docx` export, tables in `editable` rich text | The [page editor](https://clayjs.com/docs/plugins/page/) or a [block writer](https://clayjs.com/docs/guide/recipes/#block-writer); comments as `<aside data-id data-anchor>`; print CSS for PDF |
 | **Google Sheets** | Persisted inputs, sap formulas over named fields, aggregates, formats, CSV, page tables and charts from a table, 10,000-row pages saving in about 400 ms | A1 references, ranges, fill-down, recalculation graph, virtualization, range selection, pivots | A page table and chart, or a [typed table](https://clayjs.com/docs/guide/recipes/#typed-table-a-spreadsheet-you-can-be-honest-about) of a few thousand rows, one file per year |
 | **Google Slides** | Slides as sections, sortable, uploads, view mode as the published deck | Free positioning, guides, masters, presenter view in a second window, transitions, PPTX export | A flow-layout deck with fixed layouts per slide ([slides](https://clayjs.com/docs/guide/recipes/#slides)) |
 | **Trello and Linear** | Page boards where cards have an owner and a due date; sortable columns, inline editing, checklists, attachments, undo, per-card sync | Notifications, reminders, cross-board search, mentions, integrations, boards past a few thousand cards | A page board, or the [kanban with card detail](https://clayjs.com/docs/guide/recipes/#kanban-with-card-detail) with labels, due dates, and a due-soon projection |
@@ -1891,10 +2391,11 @@ The old limits apply elsewhere. Ordinary `editable` regions and DOM records have
 ### 10.3 Limits that apply to every document
 
 - **No comments.** ClayJS has no comment model (`ai-edit` is an AI prompt, not stored comments). Store comments as `<aside data-id data-anchor>` elements.
-- **No live cursors.** Presence shows who is here in an avatar stack and outlines which block someone is editing. There are no character cursors and no app-facing presence API.
+- **Live cursors only in the page editor.** The page editor draws other people's carets and selections where the host announces `page-awareness-v1`. Elsewhere, `clay.presence` tells a page who is here and which record they are writing in, and the page draws its own badges ([Presence](https://clayjs.com/docs/guide/live-sync/#presence)).
 - **No suggestion mode, pagination, footnotes, or `.docx` and PPTX export.** Edits apply directly without tracked changes, page breaks, footnotes, or Office exporters. Use print CSS for PDF.
 - **Per-file edit access.** There are no per-row permissions. Split data for different audiences into separate files.
 - **No background work in a closed file.** Nothing runs in a closed file, and a live room ends after two minutes with nobody connected. Compute due states on open.
+- **Large record sets cost every keystroke.** Each change runs a Sap pass that visits every record. Sap rereads only changed values, but the pass still grows with the record count, about 27 ms for a body edit at 5,000 records in jsdom. See [Document size and record limits](https://clayjs.com/docs/guide/architecture/#document-size-and-record-limits).
 - **Undo is per tab.** History is capped at 100 steps per tab, is not saved, and never reverts a peer's merged edits.
 
 > [!NOTE]
@@ -1915,12 +2416,14 @@ The old limits apply elsewhere. Ordinary `editable` regions and DOM records have
 - `clay:sorted` logs "Moved to *Column*" in the card when it changes column.
 - Templates: card, checklist item, column, chrome.
 
-Extend with labels (a settings element listing `<li data-label="bug" data-color="…">`, cards carrying `data-labels="bug ui"`), due dates (`data-due` plus a hash filter "due this week"), WIP limits (an attribute on the column, a warning in an `editor-ui` badge), and a list view (a projection or `display: contents`).
+Extend with labels (a settings element listing `<li data-label="bug" data-color="…">`, cards carrying `data-labels="bug ui"`, and `merge-tokens="data-labels"` on the board so two people adding labels both keep theirs, [Declared attribute merges](https://clayjs.com/docs/guide/live-sync/#declared-attribute-merges)), due dates (`data-due` plus a hash filter "due this week"), WIP limits (an attribute on the column, a warning in an `editor-ui` badge), and a list view (a projection or `display: contents`).
 
 With sapjs, the counts and progress badges become paints, the filters an `each=` view or a frozen stylesheet, and checklists nested `items=` lists with a shared blueprint: sapjs guide section [Chrome](https://clayjs.com/docs/guide/architecture/#chrome) builds a smaller version as a complete, tested app.
 
 ### 11.2 Block writer
 
+For a Notion-like document, use the [page editor](https://clayjs.com/docs/plugins/page/) (`?plugins=page`) instead. This recipe is for a block app whose blocks are your own records.
+
 [`examples/writer.html`](https://clayjs.com/examples/writer.html). Plugins `sync,sortable,undo,upload,indicator`, satellite `clay-ui`.
 
 **One `editable` per block**, not one big editor. The document is `#blocks[sortable="blocks"]`, a list of sibling `.block[data-id][data-type]` elements:
@@ -1984,16 +2487,16 @@ A **free document** is a published app anyone can use and keep. The visitor gets
 
 ### 12.1 What a visitor gets
 
-On a page that opts in ([The contract](https://clayjs.com/docs/guide/free-documents/#the-contract)), a visitor who is not the owner is in **draft mode**. Every edit-only module loads, so `editable`, `persist`, undo, sortable and the rest behave as they do for the owner, and the autosave pipeline still runs. The save lane is swapped: instead of sending the document to the host, ClayJS extracts the page's `api` JSON out of the bytes a real save would write and stores `{ "v": 1, "savedAt": "2026-10-15T00:00:00.000Z", "data": { ... } }` under `localStorage["clay:visitor-drafts:<slot>"]`. The next load applies that JSON over the file the host served, so an owner's later fix reaches a returning visitor while the visitor's own work stays. The host is never told: no save, no sync, no upload, and no `/_/meta` discovery. Two tabs on the same page share that record: a save takes what only the other tab changed, and when both changed the same thing, this tab's version is saved and the other tab's record is kept under `clay:visitor-drafts:<slot>:conflict`.
+On a page that opts in ([The contract](https://clayjs.com/docs/guide/free-documents/#the-contract)), a visitor who is not the owner is in **draft mode**. Every edit-only module loads, so `editable`, `persist`, undo, sortable and the rest behave as they do for the owner, and the autosave pipeline still runs. The save lane is swapped: instead of sending the document to the host, ClayJS extracts the page's `api` JSON out of the bytes a real save would write and stores `{ "v": 1, "savedAt": "2026-10-15T00:00:00.000Z", "data": { ... } }` under `localStorage["clay:visitor-drafts:<slot>@<path>"]`. The next load applies that JSON over the file the host served, so an owner's later fix reaches a returning visitor while the visitor's own work stays. The host is never told: no save, no sync, no upload, and no `/_/meta` discovery. Two tabs on the same page share that record: a save takes what only the other tab changed, and when both changed the same thing, this tab's version is saved and the other tab's record is kept under `clay:visitor-drafts:<slot>@<path>:conflict`.
 
-The owner is a visitor here too. Signed in, they get the same private draft unless the URL carries `?editmode=true`, which edits the original file and shows every visitor the change. Two things always edit the file itself: a document opened from `file:`, where draft mode never applies, and HTML Clay, which stamps a save token on the response. Hyperclay Local is not one of them. It serves the folder over `http:` and injects no save token, so its owner is in draft mode like anyone else and adds `?editmode=true` to edit the file ([The mode ladder](https://clayjs.com/docs/guide/free-documents/#the-mode-ladder)).
+The owner is a visitor here too. Signed in, they get the same private draft unless the URL carries `?editmode=true`, which edits the original file and shows every visitor the change. Two things never put the owner in draft mode: a document opened from `file:`, where draft mode never applies, and HTML Clay, which stamps a save token on the response. On HTML Clay the owner opens the file in view and edits the original after switching to edit. Hyperclay Local is not one of them. It serves the folder over `http:` and injects no save token, so its owner is in draft mode like anyone else and adds `?editmode=true` to edit the file ([The mode ladder](https://clayjs.com/docs/guide/free-documents/#the-mode-ladder)).
 
 ### 12.2 The contract
 
 A page that wants draft mode needs all of this. The example in [A complete example](https://clayjs.com/docs/guide/free-documents/#a-complete-example) carries every item, and its test proves the round trip:
 
 1. An `api` rules tag naming every saved field, with a `cms-template` seed row for every list the rules describe. Hide the seed in your own CSS (`[cms-template] { display: none !important }`), never with `hidden`, which the CMS reads as data ([cms: content-managed pages](https://clayjs.com/docs/guide/components/#cms-content-managed-pages)).
-2. `<html visitor-drafts="<site-stem>-v1" autosave>`. The value is the slot: letters, digits, dot, underscore and hyphen, up to 100 characters. It names this app's corner of `localStorage`, so two apps on one origin never mix.
+2. `<html visitor-drafts="<site-stem>-v1" autosave>`. The value is the slot: letters, digits, dot, underscore and hyphen, up to 100 characters. It names this app's drafts. ClayJS keys each draft by the slot and the document's path, so two documents on one origin never share a visitor's draft, even with the same slot.
 3. `plugins=visitor-drafts` on the loader tag, plus whatever else the app needs.
 4. `persist` on every control the rules name. A typed value without `persist` is lost at save ([`persist`: form controls](https://clayjs.com/docs/guide/record/#persist-form-controls)), and in draft mode a save is the visitor's own copy.
 5. `data-id` on every record and `data-id=""` on every blueprint. New rows mint their own (`trigger-add` does it, [sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup)).
@@ -2013,14 +2516,14 @@ Bump the slot (`-v2`) only when an old draft cannot fit the new rules. A draft t
 3. `window.clayEditMode`, set by a script before boot.
 4. A `savetoken` attribute the host put on `<html>`.
 5. **Draft mode**, on a page that opted in ([The contract](https://clayjs.com/docs/guide/free-documents/#the-contract)).
-6. The `isAdminOfCurrentResource` cookie (hyperclay.com, Hyperclay Local).
+6. The `isAdminOfCurrentResource` cookie (hyperclay.com, Hyperclay Local). It grants permission, so `clay.canEdit` is true, and the page still opens in view: the person opens it for editing with `clay.setMode("edit")` ([How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided)).
 
 The rung is where a free document lives, so the details matter:
 
 - `?editmode=false` is view mode, and nothing below it changes that.
 - `?editmode=true` edits the original **only with the owner cookie**, and only on a page that draft mode would otherwise claim. A query parameter on its own never grants writes to the host: an anonymous visitor with `?editmode=true` stays in draft mode.
 - The owner cookie alone is not enough either. The signed in owner gets the same draft as everyone else until they open the page with `?editmode=true`, and the owner chip ([The download prompt and the intro area](https://clayjs.com/docs/guide/free-documents/#the-download-prompt-and-the-intro-area)) is their way there.
-- `viewonly`, a stale token, `window.clayEditMode` or a `savetoken` the host stamped on `<html>` all turn draft mode off. The first two leave it in view mode; the last two switch the load to edit mode against the host, which still decides who may write ([How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided)). On a `viewonly` document or one with a stale token, `?editmode=true` is not draft mode either: it is the same edit mode as before, saving to a host that refuses the write.
+- `viewonly`, a stale token, `window.clayEditMode` or a `savetoken` the host stamped on `<html>` all turn draft mode off. The first two leave it in view mode. `window.clayEditMode = true` starts the load in edit mode against the host, and a `savetoken` grants permission, so the page opens in view and `clay.setMode("edit")` edits the original. The host still decides who may write ([How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided)). On a `viewonly` document or one with a stale token, `?editmode=true` is not draft mode either: it is the same edit mode as before, saving to a host that refuses the write.
 - Draft mode needs all four of the plugin name in `plugins=`, a valid slot, an `http:` or `https:` page and an `api` rules tag. That tag also has to carry `data-rules-version="1"` and hold JSON that parses; a newer version or unreadable JSON leaves the page out of draft mode with one console warning naming the problem. On `file:` it never applies, which is exactly why the download is a real file.
 - `<html draftmode="true">` says which mode this load is in, beside `editmode` and `pageowner` ([The root attributes](https://clayjs.com/docs/guide/edit-mode/#the-root-attributes)), and is removed from every save.
 
@@ -2028,7 +2531,7 @@ The rung is where a free document lives, so the details matter:
 
 `clay.isDraftMode` is true, and everything else follows from it:
 
-- **The plugins that talk to the host are dropped**, even when the page names them: `sync`, `live`, `upload`, `quickcrop`, `cms`, `people`, `wire`, `ai-edit`, `demo` and `source`. `clay.upload`, `clay.cms`, `clay.conflicts` and `clay.source` are absent, and code that guards them (`clay.upload?.(...)`) behaves as it does for a viewer. The `[refetch-on-save]` attribute is dropped too, since it would fetch its element from the host again after every save.
+- **The plugins that talk to the host are dropped**, even when the page names them: `sync`, `live`, `page`, `upload`, `quickcrop`, `cms`, `people`, `menu`, `upgrade`, `wire`, `ai-edit`, `demo` and `source`. `clay.upload`, `clay.cms`, `clay.conflicts` and `clay.source` are absent, and code that guards them (`clay.upload?.(...)`) behaves as it does for a viewer. The `[refetch-on-save]` attribute is dropped too, since it would fetch its element from the host again after every save.
 - **The save lane is the browser.** `clay.save()` and autosave both run, `savestatus` moves as usual, and the save answers `msgType: "success"` with `msg: "Saved in this browser"`. A storage failure answers the 507 path with `code: "draft-storage"` and fires `clay:drafts-store-failed`; the next good write clears it.
 - **No request reaches the host.** The download link goes to the host's download page, which holds the email sign-up. The prompt's own stylesheet is a Google Fonts link.
 - **`clay.readData()` and `clay.writeData()` refuse.** Both reject with `code: "DataUnavailableInDraft"`: the saved file belongs to the owner, and this visitor's work is in their browser, so there is nothing for them to read or write there. A page that calls them in draft mode gets that refusal instead of a request ([Import and export](https://clayjs.com/docs/guide/architecture/#import-and-export)).
@@ -2038,7 +2541,7 @@ The rung is where a free document lives, so the details matter:
 |---|---|
 | `active` | `true` when the plugin found a slot and the rules tag, `false` otherwise |
 | `slot` | the slot from `<html visitor-drafts="...">` |
-| `key` | the `localStorage` key, `clay:visitor-drafts:<slot>` |
+| `key` | the `localStorage` key, `clay:visitor-drafts:<slot>@<path>`, where `<path>` is the document's path up to its `.html` or `.htmlclay` file (`/` for the root and for a host that serves one document at every path) |
 | `hasDraft()` | is there a stored draft for this slot |
 | `restored()` | `{ restored, hadDraft, parked }` for this load, or `null` when the plugin is not active |
 | `saveNow()` | write the page to the slot now; `true` when it landed, `false` when it did not |
@@ -2057,16 +2560,24 @@ The restore runs while ClayJS boots, before `clay.ready` resolves, and applies t
 
 Code that drew before `clay.ready` has two ways to hear about the restore: listen for `clay:drafts-restored` on `document`, or call `clay.visitorDrafts.onRestore(fn)`, which runs `fn` at once when the restore already happened. Either way the detail is `{ restored, hadDraft, parked }`.
 
-A draft that no longer fits the page is never overwritten. When the stored JSON is not `{ v, data }` (garbage, a bare array, a missing `data`), the raw value is moved to `localStorage["clay:visitor-drafts:<slot>:unreadable:<ISO timestamp>"]`, the slot is cleared, and the page loads as authored with `parked: true` in the detail. When the write is refused only for keys the rules do not know, those keys are dropped and the rest is applied, so adding a field to the rules never costs a visitor their work.
+A draft that no longer fits the page is never overwritten. When the stored JSON is not `{ v, data }` (garbage, a bare array, a missing `data`), the raw value is moved to `localStorage["clay:visitor-drafts:<slot>@<path>:unreadable:<ISO timestamp>"]`, the slot is cleared, and the page loads as authored with `parked: true` in the detail. When the write is refused only for keys the rules do not know, those keys are dropped and the rest is applied, so adding a field to the rules never costs a visitor their work.
+
+**Drafts saved by an older ClayJS.** A draft stored under the slot alone is copied into the document's key on its first load, with its intro and prompt memory, and the old key is left as it is. Code outside ClayJS that reads a draft should read `clay.visitorDrafts.key`; a script that must run before `clay.js` uses the same path rule.
+
+### 12.6 Two tabs
 
-### 12.6 The download prompt and the intro area
+Each save merges what the other tab saved. Fields merge one by one, and lists of rows with ids merge row by row: a row added or removed in one tab is kept or removed, and rows changed in different tabs both keep their change. When both tabs changed the same field, reordered a list, or moved one row to different places, this tab's value is saved and the other tab's whole record is kept under `<key>:conflict`.
+
+### 12.7 The download prompt and the intro area
 
 Both are runtime chrome: `clay="editor-ui"` and `sap-ignore`, built by the plugin on every load. Neither is in the file, neither is saved or synced, and neither is read by sapjs.
 
-Both remember themselves per slot in `localStorage["clay:visitor-drafts:<slot>:ui"]`, as `{ "v": 1, "prompt": { "shown": ..., "dismissed": ..., "uses": ..., "downloaded": ... }, "intro": { "done": null | "closed" | "scrolled" }, "src": ... }`. Clearing that key shows the intro and the prompt again.
+Both remember themselves per slot and path in `localStorage["clay:visitor-drafts:<slot>@<path>:ui"]`, as `{ "v": 1, "prompt": { "shown": ..., "dismissed": ..., "uses": ..., "downloaded": ... }, "intro": { "done": null | "closed" | "scrolled" }, "src": ... }`. Clearing that key shows the intro and the prompt again.
 
 **The intro** is authored per app as a `<template visitor-intro>`. The template holds the author's whole strip: its markup and any `<style>` it needs. The plugin clones it into a section at the very top of the page body, before the app's own content, and adds a quiet close (`x`) in the corner. The intro leaves for good when the visitor closes it or scrolls it past the top of the viewport; the ui memory records `"closed"` or `"scrolled"` as the reason.
 
+A `<script type="module">` inside the template runs when the intro mounts. Animate it with `clay.assets.load('uimotion')`, never an engine copied into the file, so a visitor the intro skips loads no motion code.
+
 ```html
 <template visitor-intro>
   <p>One paragraph on what the app does and who it is for.</p>
@@ -2087,13 +2598,34 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 
 **The owner chip** shows only to the signed in owner, at the bottom left: it says whether this load is their private draft ("Edit the original") or the original ("Back to my draft") and switches with `clay.visitorDrafts.editOriginal()` and `backToDraft()`.
 
-### 12.7 Migrating an app's own storage
+### 12.8 Migrating an app's own storage
 
 **Not supported yet:** the plugin reads no migration hook, so an app that kept its earlier data under its own `localStorage` key has to move those values into the page from its own code, on the first load after the switch.
 
-### 12.8 A complete example
+**Change a key only after every reader reads both.** A reader that spells the key by hand keeps reading the old one, and an old key stops changing the moment ClayJS writes the new one. The download page and the calculator's row reset both spell the draft key themselves, so both learned to read the new key and the old one before the key changed:
+
+```js
+function readDrafts(win, slot, path) {
+  if (!slot) return null;
+  try {
+    var legacy = 'clay:visitor-drafts:' + slot;
+    var key = legacy + '@' + draftPath(path);
+    var raw = win.localStorage.getItem(key);
+    if (raw == null && win.localStorage.getItem(key + ':legacy') == null) raw = win.localStorage.getItem(legacy);
+    var stored = raw ? JSON.parse(raw) : null;
+    var data = stored && stored.data;
+    return data && typeof data === 'object' && !Array.isArray(data) && Object.keys(data).length ? data : null;
+  } catch (e) {
+    return null;
+  }
+}
+```
+
+The `:legacy` marker is what stops a reset from coming back: once ClayJS has copied the old draft, a reader that still saw the old key would restore work the visitor asked to clear. A reader that can run before `clay.js` uses the same path rule, so it finds the same key ClayJS writes.
+
+### 12.9 A complete example
 
-[`examples/free-reading-list.html`](https://clayjs.com/examples/free-reading-list.html). Plugins `visitor-drafts,indicator&exclude=richclay`, satellites `clay-options` and `sap.js`. A reading list: a title, an author and a status select per book, one scalar goal for the year, and sapjs counting the books that are read. It is the shortest file that carries every item of the contract, and `tests/unit/guide-examples/free-document.test.js` runs it end to end: edit a title, add a book, check the slot, then load the file again with that storage and check the books and the counts come back. The record is authored in the saved form, so sapjs logs its harmless W03 warning for each `viewmode:` attribute ([sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup)). The `reading` option of a status select carries no `selected`: it is the first option, which is the default, and the row that is `read` marks it.
+[`examples/free-reading-list.html`](https://clayjs.com/examples/free-reading-list.html). Plugins `visitor-drafts,indicator&exclude=richclay`, satellites `clay-options` and `sap.js`. A reading list: a title, an author and a status select per book, one scalar goal for the year, and sapjs counting the books that are read. It is the shortest file that carries every item of the contract, and `tests/unit/guide-examples/free-document.test.js` runs it end to end: edit a title, add a book, check the slot, then load the file again with that storage and check the books and the counts come back. The record is authored in the saved form, with its `viewmode:` attributes. The `reading` option of a status select carries no `selected`: it is the first option, which is the default, and the row that is `read` marks it.
 
 ```html
 <!DOCTYPE html>
@@ -2183,26 +2715,41 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 1. Loads with `clay.js` as a classic script at the end of `<body>`, every tag on the same version prefix.
 2. `<html autosave>` unless it is a deliberate manual-save writer.
 3. `sync` is in the plugin list, and `exclude=richclay` if there is no rich text.
-4. The fallback rule `html:not([editmode="true"]) [show-when\:editmode="true"] { display: none }` is in the stylesheet, and every edit-only control has `show-when:editmode="true"`.
-5. Records are authored in the saved form (`inert-contenteditable`, `disabled`, `readonly`); templates in the active form.
-6. Every repeated record has a unique `data-id`; templates carry none; every create and duplicate mints a fresh one.
-7. Every control whose value matters has `persist`; no filter or search box does.
-8. All chrome is cloned from a `<template>` into `clay="editor-ui"` after `clay.ready`; nothing in the file is chrome.
-9. Tab-local state is in the hash, `localStorage` or memory, painted through a runtime style; opening, filtering and searching leave `clay.hasUnsavedChanges()` false.
-10. Derived values are sapjs paints, in `editor-ui`, or `no-dirty` when the file must show them; every hand-written derived write is guarded, and no script copies a record into a second attribute.
-11. Commands are wrapped in `clay.undo.commit`; derived views are drawn in `clay.effect`, with no effect warnings in the console.
-12. Views whose record a peer deleted are closed, in the effect or a `clay:sync-applied` handler.
-13. The app script starts with `clay.start`; all listeners are delegated.
-14. Nothing writes the record at boot.
-15. Edit-only calls are guarded for view mode, and edit actions check `clay.isEditMode`.
-16. `clay.confirm` calls have a rejection handler.
-17. Save failures are visible (indicator, `savestatus` CSS or clay-ui).
-18. Library residue (Sortable, third-party editors) is stripped in a snapshot hook.
-19. Images use `clay.upload`, embedding only on `unsupported`.
-20. The file opens in view mode with JavaScript disabled and shows correct content and no edit controls.
-21. With sap: `Sap.status().ok`, the live root matches the file after load (no computed value rewritten), no `[sap-error]`, rows with your own ids.
-
-### 13.2 Trap index
+4. The owner has a way into edit: the `menu` plugin, or a control of your own that calls `clay.setMode()` and carries `clay-mode-toggle`. Without either, ClayJS shows a one-time note pointing to Cmd+Shift+E (Ctrl+Shift+E elsewhere).
+5. The fallback rule `html:not([editmode="true"]) [show-when\:editmode="true"] { display: none }` is in the stylesheet, and every edit-only control has `show-when:editmode="true"`.
+6. Records are authored in the saved form (`inert-contenteditable`, `disabled`, `readonly`); templates in the active form.
+7. Every repeated record has a unique `data-id`; templates carry none; every create and duplicate mints a fresh one.
+8. Every control whose value matters has `persist`; no filter or search box does.
+9. All chrome is cloned from a `<template>` into `clay="editor-ui"` after `clay.ready`; nothing in the file is chrome.
+10. Tab-local state is in the hash, `clay.storage.local` or `clay.storage.session`, or memory, painted through a runtime style; opening, filtering and searching leave `clay.hasUnsavedChanges()` false.
+11. Derived values are sapjs paints, in `editor-ui`, or `no-dirty` when the file must show them; every hand-written derived write is guarded, and no script copies a record into a second attribute.
+12. Commands are wrapped in `clay.undo.commit`; derived views are drawn in `clay.effect`, with no effect warnings in the console.
+13. Views whose record a peer deleted are closed, in the effect or a `clay:sync-applied` handler.
+14. The app script starts with `clay.start`; all listeners are delegated.
+15. Nothing writes the record at boot.
+16. Edit-only calls are guarded for view mode, and edit actions check `clay.isEditMode`.
+17. `clay.confirm` calls have a rejection handler.
+18. Save failures are visible (indicator, `savestatus` CSS or clay-ui).
+19. Library residue (Sortable, third-party editors) is stripped in a snapshot hook.
+20. Images use `clay.upload`, embedding only on `unsupported`.
+21. The file opens in view mode with JavaScript disabled and shows correct content and no edit controls.
+22. With sap: `Sap.status().ok`, the live root matches the file after load (no computed value rewritten), no `[sap-error]`, rows with your own ids.
+23. A tool page whose script opens an editor at load (a journal, a notes pad) declares `<html opens-in="edit">`. Without it the page opens in view, accepts typing and saves none of it.
+
+### 13.2 Testing a document that changes modes
+
+Each check names the clayjs test that proves the library side.
+
+- **It opens in view by default.** `tests/unit/mode-decision.test.js` pins the table, including an owner cookie alone opening in view with permission kept.
+- **An explicit edit enters edit.** The same file covers `?editmode=true`, `window.clayEditMode = true` and `<html opens-in="edit">`, and `tests/unit/mode-transition.test.js` covers an explicit initial edit preparing the session a live first entry does.
+- **A draft document stays a draft.** `tests/unit/mode-draft.test.js` shows a declared draft refusing both directions.
+- **A refused exit can be retried.** `tests/unit/mode-lifecycle.test.js` covers a quiesce that refuses and resumes the same leases, and `tests/unit/mode-transition.test.js` covers the next entry starting a fresh session.
+- **Pending work refuses the exit.** `tests/unit/mode-transition.test.js` covers a registered pending source, and `tests/unit/mode-save-barrier.test.js` covers the barrier's codes.
+- **A clean enter and exit writes nothing.** `tests/unit/mode-transition.test.js` asserts it, and the corpus case `enter-leave-zero-writes` records the same run.
+
+`tests/mode-counterexamples/` is a set of recorded cases. Each one boots a fixture in jsdom through the real loader, applies a schedule with the transport, the chunk imports and the clock supplied by the harness, and judges the result from what the run left behind. It is not a browser run: no phone, no keyboard and no real network appears in it.
+
+### 13.3 Trap index
 
 | Trap | Section |
 |---|---|
@@ -2213,6 +2760,10 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 | Records authored with live `contenteditable` stay editable for viewers until the first save | [Mode attributes: one file for editors and viewers](https://clayjs.com/docs/guide/edit-mode/#mode-attributes-one-file-for-editors-and-viewers) |
 | Templates in the inert form give clones that cannot be edited until reload | [Mode attributes: one file for editors and viewers](https://clayjs.com/docs/guide/edit-mode/#mode-attributes-one-file-for-editors-and-viewers) |
 | Unguarded edit-only API calls throw in view mode | [What works in view mode](https://clayjs.com/docs/guide/edit-mode/#what-works-in-view-mode) |
+| A page whose script opens an editor at load accepts typing in view mode and saves nothing | [How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided) |
+| Reading `clay.mode` once at boot and keeping it | [How the mode is decided](https://clayjs.com/docs/guide/edit-mode/#how-the-mode-is-decided) |
+| Using `clay.canEdit` as the guard for writing; use `clay.modeLifecycle.canWrite()` | [Switching without a reload: clay-mode-switch="live"](https://clayjs.com/docs/guide/edit-mode/#switching-without-a-reload-clay-mode-switch-live) |
+| Switching modes by writing the root `editmode` attribute | [Switching modes: clay.setMode](https://clayjs.com/docs/guide/edit-mode/#switching-modes-clay-setmode) |
 | `hidden`, `.selected`, `<details open>` and library inline styles save; use `ephemeral` | [What a save writes](https://clayjs.com/docs/guide/record/#what-a-save-writes), [Ephemeral state: per-tab state on saved elements](https://clayjs.com/docs/guide/record/#ephemeral-state-per-tab-state-on-saved-elements) |
 | `no-save` chrome still reaches peers; use `editor-ui` | [Regions: the `clay` attribute](https://clayjs.com/docs/guide/record/#regions-the-clay-attribute) |
 | Edits in `no-watch` or `no-dirty` are invisible to `save()` and the close warning | [Regions: the `clay` attribute](https://clayjs.com/docs/guide/record/#regions-the-clay-attribute) |
@@ -2243,12 +2794,13 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 | A peer's frame re-runs inline scripts | [What a merge does](https://clayjs.com/docs/guide/live-sync/#what-a-merge-does), [Starting the app once](https://clayjs.com/docs/guide/architecture/#starting-the-app-once) |
 | A `no-dirty` region replaced by a peer raises a false conflict notice (1.8.2) | [Regions and JSON under sync](https://clayjs.com/docs/guide/live-sync/#regions-and-json-under-sync) |
 | Same-key JSON edits under `merge`: incoming wins, yours goes to the notice | [Regions and JSON under sync](https://clayjs.com/docs/guide/live-sync/#regions-and-json-under-sync) |
+| Two tabs changing one shared `data-*` attribute (labels, a counter) conflict unless a container declares `merge-tokens` or `merge-max` | [Declared attribute merges](https://clayjs.com/docs/guide/live-sync/#declared-attribute-merges) |
 | Rewriting the record at boot makes incoming frames hold | [Focus, typing and long-running editors](https://clayjs.com/docs/guide/live-sync/#focus-typing-and-long-running-editors) |
 | Parsed JSON goes stale after a merge | [Reconciling in app code](https://clayjs.com/docs/guide/live-sync/#reconciling-in-app-code) |
 | A script that copies a record into a styling attribute goes stale in the file, and a merge brings the stale copy back | [Rules for DOM state](https://clayjs.com/docs/guide/model/#rules-for-dom-state), [sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup) |
 | An `api` rule that reads a painted value can read a stale one until a tab repaints and saves | [sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup) |
 | Full sapjs markup under the sapjs core halts with `E50` | [sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup) |
-| There is no presence API | [Presence](https://clayjs.com/docs/guide/live-sync/#presence) |
+| Presence is runtime only: the host filters the roster, and a caret it cannot place is not drawn | [Presence](https://clayjs.com/docs/guide/live-sync/#presence) |
 | `data-richclay` card mode deletes images on load | [richclay: rich text (`editable`)](https://clayjs.com/docs/guide/components/#richclay-rich-text-editable) |
 | The richclay toolbar is unusable inside `showModal()` and popovers | [richclay: rich text (`editable`)](https://clayjs.com/docs/guide/components/#richclay-rich-text-editable) |
 | Rich text has its own undo; page undo never records it | [richclay: rich text (`editable`)](https://clayjs.com/docs/guide/components/#richclay-rich-text-editable), [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
@@ -2258,8 +2810,8 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 | Sortable handle mode is fixed at bind time | [sortable: drag to reorder](https://clayjs.com/docs/guide/components/#sortable-drag-to-reorder) |
 | `onsorting` cannot veto a move | [sortable: drag to reorder](https://clayjs.com/docs/guide/components/#sortable-drag-to-reorder) |
 | Sortable residue saves | [sortable: drag to reorder](https://clayjs.com/docs/guide/components/#sortable-drag-to-reorder), [Hooks](https://clayjs.com/docs/guide/saving/#hooks) |
-| The undo plugin takes Cmd+Z in every text field | [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
-| Undoing an add removes the record even after a peer edited it | [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
+| A plain input's typed value is not content until `persist` or a command writes it, so page undo has nothing to replay for it | [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
+| A refused undo or redo stays on top of the stack until it is replayed or discarded | [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
 | Pausing undo across an `await` loses the earlier mutations | [undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo) |
 | Sap reads live control values: undo without re-syncing inputs saves the undone number | [`persist`: form controls](https://clayjs.com/docs/guide/record/#persist-form-controls), [sap.js: records, views and totals in markup](https://clayjs.com/docs/guide/components/#sap-js-records-views-and-totals-in-markup) |
 | `clay.upload` is not a picker; embed only on `unsupported` | [upload and quickcrop](https://clayjs.com/docs/guide/components/#upload-and-quickcrop) |