@panphora/clayjs 1.13.1 → 1.14.0

package/dist/server/rooms.mjs

@@ -0,0 +1,66 @@
+import rooms from './rooms.cjs';
+export default rooms;
+export const {
+  LIVE_LIMITS,
+  PageConversionError,
+  PageFormatError,
+  PersistentReservationError,
+  RANGE_LIMIT,
+  RECEIPT_LIMIT,
+  REFUSED_MS,
+  applyOp,
+  applyOps,
+  applyTracked,
+  assignDeep,
+  checkOp,
+  checkPageConversion,
+  checkPageInitial,
+  checkPageWriteAdmission,
+  checkPageWriteFormat,
+  cloneJson,
+  closestBase,
+  coalesce,
+  composePage,
+  contains,
+  createRooms,
+  descendants,
+  diffOps,
+  documentEtag,
+  formatBy,
+  frameSet,
+  hasNumber,
+  identitySet,
+  ifMatchSatisfied,
+  inspectPage,
+  isHybridPageValue,
+  isYPageValue,
+  liveTags,
+  makePageTransition,
+  overlaps,
+  pageBaseline,
+  pageLineageLost,
+  pageRev,
+  pageTransitionState,
+  parseBy,
+  parsePageConversion,
+  parsePath,
+  parseStamp,
+  postReceipt,
+  rangeCount,
+  rebasePage,
+  receiptBytes,
+  receiptHas,
+  replaceReceipt,
+  retireReceipt,
+  roomIsDirty,
+  saveReceipt,
+  serializeLive,
+  sizeChange,
+  splitPage,
+  stampOf,
+  stampPageRev,
+  textHash,
+  undoTracked,
+  unionRanges,
+  validateOp,
+} = rooms;

package/docs/guide.md

@@ -2,7 +2,7 @@
 
 This is the complete reference for building malleable documents with ClayJS: one HTML file that is the whole app, edits itself in place, saves itself back to its host, and merges edits from other tabs, other people and agents. Read it top to bottom once. After that, sections 2 (the skeleton), 9 (architecture) and 13 (checklist and trap index) are the parts to return to.
 
-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 (section 8.13), because an app whose product is editing should not route editing through a form sidebar.
+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 (section 8.12), 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:
 
@@ -104,10 +104,7 @@ Start every app from [`examples/skeleton.html`](https://clayjs.com/examples/skel
 <script src="https://clayjs.com/v1/clay-options.js"></script>
 <script src="https://clayjs.com/v1/clay-ui.js"></script>
 <script>
-clay.ready.then(() => {
-  if (window.__appStarted) return;
-  window.__appStarted = true;
-
+clay.start(() => {
   const items = document.getElementById("items");
   const newId = (prefix) => prefix + "-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
   const command = (label, fn) => (clay.undo ? clay.undo.commit(label, fn) : fn());
@@ -142,10 +139,6 @@ clay.ready.then(() => {
     setText(chrome.querySelector("#view-state"), hidden.map((li) => `#items > [data-id="${CSS.escape(li.dataset.id)}"]{display:none}`).join("\n"));
   }
 
-  function syncCheckboxes() {
-    for (const box of items.querySelectorAll("input[type=checkbox]")) box.checked = box.hasAttribute("checked");
-  }
-
   document.addEventListener("click", (event) => {
     const button = event.target.closest("[data-action]");
     if (!button || !clay.isEditMode) return;
@@ -168,12 +161,8 @@ clay.ready.then(() => {
     }
   });
 
-  document.addEventListener("clay:sync-applied", () => { syncCheckboxes(); render(); });
-  clay.undo?.on("undo", syncCheckboxes);
-  clay.undo?.on("redo", syncCheckboxes);
   window.addEventListener("hashchange", () => { filter.value = new URLSearchParams(location.hash.slice(1)).get("q") || ""; render(); });
-  new MutationObserver(render).observe(items, { subtree: true, childList: true, attributes: true, characterData: true });
-  render();
+  clay.effect(render);
 });
 </script>
 </body>
@@ -188,13 +177,12 @@ What each part does, and the section that explains it:
 - **The templates** are blueprints. `item-tpl` holds a new row in its **active form** (`contenteditable="plaintext-only"`, no `disabled`), because a clone is inserted while the owner is editing and the mode transform never touches template content (4.4).
 - **`chrome-tpl`** is cloned once into a `clay="editor-ui"` wrapper. The summary, the filter and the `#view-state` style live there, so none of them is saved, synced or undone (5.2, 9.3).
 - **The script tags**: core with `sync,sortable,undo,indicator`, `exclude=richclay` because this app has no rich text, then the `clay-options` and `clay-ui` satellites (3).
-- **The boot guard** `window.__appStarted` stops a second run if a live-sync merge re-inserts the script (9.10).
+- **`clay.start`** runs the app code once, after boot. A live-sync merge can re-insert the script, and the repeat call does nothing (9.10).
 - **`newId`** makes ids from a timestamp and random suffix. `crypto.randomUUID` exists only in secure contexts, so it fails on a file served over plain http from another machine (5.5).
 - **`command`** wraps every record write in an undo step when the undo plugin is loaded (8.3).
 - **The `onSnapshot` hook** strips Sortable's drag residue (`draggable="false"`, empty `style`, drag classes) from every snapshot, so a drag never writes it into the file (6.6).
 - **`render`** derives the summary and the filter style from the record. It writes only when text changes, because writing the same text is still a mutation (9.4).
-- **`syncCheckboxes`** puts each checkbox's displayed state back in step with its `checked` attribute after undo, redo or a merge, which change the attribute but not the property (8.3).
-- **The `MutationObserver`** re-renders on any record change: local typing, drag, merge or undo. It observes only the record, so the chrome's own writes do not feed back.
+- **`clay.effect(render)`** runs `render` now and again after any change to the document: local typing, a drag, a merge, undo or redo. `render` writes only into the chrome, and an effect's own writes never re-trigger it (7.5).
 
 The test suite checks this file opens without becoming dirty, saves the record and no chrome, keeps the filter out of the file, keeps undo and the screen in step, mints unique ids, merges a peer's edit beside an unsaved local edit, and gives a viewer inert text and disabled checkboxes.
 
@@ -231,7 +219,7 @@ The test suite checks this file opens without becoming dirty, saves the record a
 | `quickcrop` | off | yes | `clay.quickcrop` |
 | `cms` | off | yes | `clay.cms`; implies `quickcrop` and `upload` |
 | `wire` | off | yes | `clay.wire`, the channel to a local agent process |
-| `message` | off | yes | `message-form`: a visitor's contact form to the owner, `clay.message` (8.14) |
+| `message` | off | yes | `message-form`: a visitor's contact form to the owner, `clay.message` (8.13) |
 | `ai-edit` | off | no | select text, ask an agent to rewrite it; implies `wire` |
 | `demo` | off | yes | fakes saving into `localStorage` for public demos |
 | `visitor-drafts` | off | yes | the draft store, `clay.visitorDrafts`, the download prompt, the intro area and the owner chip on a page that opted in (14) |
@@ -259,7 +247,7 @@ Satellites are separate classic script tags. Each publishes a promise on `clay.l
 | `clay-utils.js` | `clay.loaded.utils` | `clay.utils.debounce`, `throttle`, `cookie.get/remove`, `slugify`, `copyToClipboard` | |
 | `clay-internals.js` | `clay.loaded.internals` | `clay.internals`: capture, transforms, raw save | |
 | `clay-data.js` | `clay.loaded.data` | `clay.extractData`, `clay.applyData` | 9.9 |
-| `sap.js` | `clay.loaded.sap` | `Sap`, the reactive attribute layer | 8.12 |
+| `sap.js` | `clay.loaded.sap` | `Sap`, the reactive attribute layer | 8.11 |
 
 Satellites do not wait for `clay.ready` and work without `clay.js` at all, including in view mode and on a static host. Await the promise before using what it adds: `await clay.loaded.ui` before `clay.toast` in code that runs early. Code inside a `clay.ready` callback can usually use `clay.toast?.(...)` safely, since the satellites finish loading at about the same time, but the optional call costs nothing.
 
@@ -267,13 +255,13 @@ Satellites do not wait for `clay.ready` and work without `clay.js` at all, inclu
 
 ### 3.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.ready.then(...)`.
+`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 (9.10).
 
 You can set configuration before the tag, and the loader merges into it: `window.clay = { saveToast: true }`.
 
 ### 3.5 Theming ClayJS's own UI
 
-ClayJS draws a few things on your page: dialogs (`clay.ask`, `clay.confirm`, `clay.tell`, `clay.snippet`, `clay.modal`) and the people plugin's name prompt. By default they take your page's font, and on a page with a plain solid background, its background and text colours. Everything else comes from ClayJS's own look, Bevel.
+ClayJS draws a few things on your page: dialogs (`clay.ask`, `clay.confirm`, `clay.tell`, `clay.snippet`, `clay.modal`) and the people plugin's name prompt. By default they take your page's font, and on a page with a plain solid background, its background and text colours. Everything else comes from ClayJS's own built-in look.
 
 To match them to your design, set `window.clayTheme` before the loader tag:
 
@@ -289,8 +277,8 @@ window.clayTheme = {
 
 - **Tokens** set the basics: `font`, `headingFont`, `text`, `mutedText`, `background`, `surface`, `border`, `accent`, `accentText`, `danger`, `dangerText`, `success`, `warning`, `radius`, `shadow`, `overlay`, `spacing`, `buttonHeight`. Each is a CSS value, and `var(--your-variable, fallback)` works. A page can also set a token in CSS as `--clay-ui-<name>` (`--clay-ui-accent-text` for `accentText`). `spacing` is one length, such as `20px`.
 - **Parts** set anything else. Every element ClayJS draws has a stable name, such as `dialog.panel`, `dialog.title`, `button.primary` or `people.choice`, and each takes `base`, `hover`, `active`, `focus` and `disabled` declarations. A part names its surface, so `people.title` overrides `dialog.title` in the name prompt only. The names are in `data-clay-part` on each element, and the full list is in `docs/injected-ui.md`.
-- A value wins in this order: `tokens`, then `--clay-ui-*` properties, then the page's sampled font and colours, then Bevel.
-- `window.clayTheme = false` keeps the exact Bevel look. After loading, `clay.theme(options)` replaces the theme, `clay.theme(false)` and `clay.theme(null)` restore Bevel or the default, and `clay.theme()` returns the current one. A change affects the next dialog, not one already open.
+- A value wins in this order: `tokens`, then `--clay-ui-*` properties, then the page's sampled font and colours, then the built-in look.
+- `window.clayTheme = false` keeps the exact built-in look. After loading, `clay.theme(options)` replaces the theme, `clay.theme(false)` and `clay.theme(null)` restore the built-in look or the default, and `clay.theme()` returns the current one. A change affects the next dialog, not one already open.
 
 Your stylesheet still cannot reach these elements: every declaration is inline and `!important`, so a stray `button { ... }` rule never breaks a prompt. On a phone, dialog buttons stay at least 44px tall whatever the theme asks for.
 
@@ -346,7 +334,7 @@ The family:
 | `option-not:NAME="a"` | some ancestor has `NAME` with a value other than `a`; hidden when no ancestor has `NAME` |
 
 - It matches **any** ancestor, not the nearest. Nested views need different attribute names (`view` on the app, `cardview` on a card).
-- It compares literal strings only. Expressions belong to sap's `show=` (8.12).
+- It compares literal strings only. Expressions belong to sap's `show=` (8.11).
 - `show-when:savestatus="error|offline"` shows a "not saved" warning. `show-when:pageowner="true"` shows owner links.
 - For content only viewers should see, use `hide-when:editmode="true"`: it is visible when `editmode` is absent. `show-when:editmode="false"` is hidden until boot and then appears.
 - The attribute you switch views with is ordinary saved content. Setting `view="list"` on a saved element saves it and syncs it to every collaborator. Section 9.3 covers tab-local views.
@@ -465,32 +453,7 @@ A control's typed value is a property, not an attribute, and serialization only
 - A persist control's value change counts as an edit and starts autosave.
 - Do not persist a filter or search box. Those are tab-local: put them in chrome (9.3).
 
-**After undo, redo or a merge, the screen can disagree with the file.** Undo and sync restore the attribute, but the browser's checkbox and input display follow the property once the user has touched the control. Re-sync the property from the attribute on all three events, as the skeleton and kanban do for checkboxes:
-
-```js
-function syncCheckboxes() {
-  for (const box of root.querySelectorAll("input[type=checkbox][persist]")) box.checked = box.hasAttribute("checked");
-}
-document.addEventListener("clay:sync-applied", syncCheckboxes);
-clay.undo?.on("undo", syncCheckboxes);
-clay.undo?.on("redo", syncCheckboxes);
-```
-
-Text and number inputs need the same for `value`, and it matters more there: a save copies the live value into the file, so after an undo that left the old number on screen, the next save writes the undone value back. The finance tracker re-syncs every persisted input, skipping the focused one after a merge (7.4), then refreshes sap:
-
-```js
-function syncControls({ keepFocused = false } = {}) {
-  for (const input of app.querySelectorAll("input[persist]")) {
-    if (keepFocused && input === document.activeElement) continue;
-    const value = input.getAttribute("value") ?? "";
-    if (input.value !== value) input.value = value;
-  }
-  Sap.refresh();
-}
-clay.undo?.on("undo", () => syncControls());
-clay.undo?.on("redo", () => syncControls());
-document.addEventListener("clay:sync-applied", () => syncControls({ keepFocused: true }));
-```
+**After undo, redo or a merge, ClayJS puts each control's display back in step with its attributes.** A control the user has touched shows its live property, not its attribute, so a merge and the undo plugin copy `checked`, `value` and `selected` back onto the property (undo does this for `persist` controls outside `no-undo` regions). A merge leaves the focused text field alone; undo, which the user asked for, restores it too.
 
 ### 5.4 Where to keep data that is not visible text
 
@@ -744,9 +707,9 @@ More engine rules:
 
 - Text merges word by word inside a block, and formatting merges per character. Inline `<style>` text merges word by word. Scripts, textarea text 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. Hence the boot guard (9.10).
+- A new or changed inline `<script>` in the frame runs once after the merge. Hence `clay.start` (9.10).
 - Window scroll is restored. Inner scroll containers are not, except the focused element's own.
-- The merge runs with the mutation hub, the dirty gate and undo paused: incoming changes never autosave and never enter undo history. Your own `MutationObserver` still sees them, which is how the examples re-render.
+- The merge runs with the mutation hub, the dirty gate and undo paused: incoming changes never autosave and never enter undo history. `clay.effect` re-runs after it through `clay:sync-applied`, which is how the examples re-render (7.5).
 
 ### 7.3 Regions and JSON under sync
 
@@ -777,16 +740,33 @@ document.addEventListener("clay:sync-applied", () => {
 
 ### 7.5 Reconciling in app code
 
-After `clay:sync-applied`, rebuild everything derived from the record and every piece of chrome that points into it:
+Draw everything derived from the record inside `clay.effect(fn)`. It runs `fn` on the next microtask, then again after every change the mutation hub observes (local edits, drags, undo and redo) and after every merge, batched to one run per microtask. Changes inside `editor-ui` or `no-watch` regions, ephemeral attributes and live properties with no attribute change do not re-run it. `fn` runs with the hub paused, so its own writes never re-trigger it, start an autosave or enter undo history. It returns a function that stops it.
+
+```js
+clay.effect(() => {
+  const rows = items.querySelectorAll(":scope > li");
+  const done = items.querySelectorAll("input[checked]").length;
+  setText(summary, `${done} of ${rows.length} read`);
+});
+```
+
+Rules for `fn`:
+
+- **Keep it synchronous.** Writes after an `await` land outside the pause and would re-trigger it forever, so an effect whose `fn` returns a promise is stopped with a console error.
+- **Do not call `clay.undo.commit` inside it.** A commit drains the hub's records, so the effect's writes reach autosave and the effect again.
+- **One effect does not see another's writes**, because each runs paused. Draw values that depend on each other in one effect.
+- **A derived value saved in the record** (a count painted in markup, 9.4) is written with the hub paused, so a repaint after a merge leaves the page dirty with no save scheduled. Put saved derived values in `clay="no-dirty"`, or in chrome.
+
+In edit mode each effect warns once in the console when it breaks one of these rules: a write to saved content outside `no-dirty` and `editor-ui`, a `clay.undo.commit` call, an effect created inside it, or more than 50 runs in a second (usually a timer or async callback it started that keeps changing the document). The effect keeps running; the warning names the element or command.
+
+Work that belongs to a merge alone goes in a `clay:sync-applied` listener:
 
 ```js
 document.addEventListener("clay:sync-applied", (event) => {
-  syncCheckboxes();
-  render();
+  if (openId && !cardById(openId)) closeCard();
 });
 ```
 
-- Re-render derived values and projections.
 - Close or repoint any view whose record a peer deleted. The kanban closes the open card when its id is gone: `if (openId && !cardById(openId)) return writeHash({ card: "" }, { replace: true });`
 - Re-parse any JSON you parsed earlier.
 - Re-attach any per-element setup that a re-created element lost (the writer re-injects block gutters on every render).
@@ -813,7 +793,7 @@ An agent edits a malleable file the way a person in another tab does.
 
 - **Editing the file on disk** (HTML Clay, Hyperclay Local): the host notices the change and pushes a `disk` frame. The open tab merges it three ways, so the person's unsaved typing in other paragraphs survives, and an overlap goes to the ledger. Tell agents to address elements by `data-id`, never by position, and to leave chrome alone (it is not in the file anyway).
 - **`clay.wire`** (`?plugins=wire`, HTML Clay and Hyperclay Local): `clay.wire.send(payload)` sends a request to a local process started with `htmlclay wire serve file.htmlclay -- my-agent`. The page saves first, so the agent reads what the person sees, and autosave pauses until the agent's edit lands as a disk frame. `run.done` resolves then.
-- **`ai-edit`** (`?plugins=ai-edit`): select text, press Cmd+J, 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).
+- **`ai-edit`** (`?plugins=ai-edit`): select text, press Cmd+J, 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 face over the file defined by a rules tag (9.9). `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.
 
 ### 7.9 Live data: `clay="live"`
@@ -848,7 +828,7 @@ function render() {
 }
 ```
 
-**The tag.** A `<script type="application/json">` with `merge="name"` and `clay="live"`, holding a JSON object or list. The name is 1 to 64 letters, digits, `_`, `.`, `:` or `-`, and two live tags with the same name are both ignored. Write the tag into the file before people share it: a tag added later is not in the rooms of tabs that loaded before. Checkpoints add a `live-at` attribute to the tag (the room position the value was saved at, and a hash of the text). Leave it in place when you or an agent edit the tag's JSON by hand: the room then merges your edit with the play since that checkpoint. Without it, the edit is merged over what the room last saved. A save hook (`onbeforesave`) may reformat a live tag's JSON, but must not change its value.
+**The tag.** A `<script type="application/json">` with `merge="name"` and `clay="live"`, holding a JSON object or list. The name is 1 to 64 letters, digits, `_`, `.`, `:` or `-`, and two live tags with the same name are both ignored. Write the tag into the file before people share it: a tag added later is not in the rooms of tabs that loaded before. Checkpoints add a `live-at` attribute to the tag (the room position the value was saved at, and a hash of the text). A save made while the tab is out of the room also adds `live-by` (that tab and the last update it sent), so the room does not apply those updates a second time. The room trusts `live-by` only while the value still matches the hash in `live-at`, and never on a restored version. Leave both in place when you or an agent edit the tag's JSON by hand: the room then merges your edit with the play since that checkpoint. Without it, the edit is merged over what the room last saved. A save hook (`onbeforesave`) may reformat a live tag's JSON, but must not change its value. A tag is written in the layout it was loaded with: one line, or indented when the authored JSON had line breaks. `live-format="lines"` writes each entry of each top-level object on its own line instead, so the file's version history shows only the entries that changed, which suits a large store keyed by id (the page editor's blocks).
 
 **The API.** `clay.live(name)` returns the same handle every time.
 
@@ -875,11 +855,13 @@ Two rules for the proxy:
 
 `game.status.mode` is `fast` on the first two lanes and `file` on the third. In view mode a store reads normally, but writes stay in the tab and are never sent or saved.
 
+**The page editor's own store.** A Document's blocks are a live store named `page`, and its merge state is not in the file: hyperclay.com and Hyperclay Local keep it beside the file and hand it back to an editor only while it still belongs to the article (the article's `data-rev` matches), and HTML Clay keeps none, so open tabs share it and a fresh open rebuilds it from the article. Saved files and downloads never carry it. A page changed outside the editor (the code editor, an agent, a version restore, another device, a text editor) merges into the page tabs that are open, the way a peer's edit does: each block is merged three ways against the article the change started from, so edits on both sides survive. Where both sides changed the same words, the outside change wins, and the tab offers a download of what it had. An edit beats a delete. Only a change with no article this host can trace it back to shows a reload notice, and the tab stops saving so the old article is not written back over the new one.
+
 **When a room is lost.** A room lives in memory: a server restart, or two minutes with nobody connected, ends it. The next room starts from the last checkpoint, so up to 8 seconds of play can be gone. A change of yours that the old room may already have taken is not sent to the new one, even when its answer was lost: if the old room's last checkpoint lands afterwards, it brings that change back, and sending it again would count it twice. A change that never left the tab is sent as usual. Closing the tab that runs a local room is not a loss: the next tab takes over the room with every move.
 
 **Load the plugin wherever a live tag exists.** A page without `?plugins=live` still leaves live tags out of the merge, so an incoming save does not update them and the next save writes the old text back.
 
-**Limits on hyperclay.com.** A frame carries at most 128 ops and 16 KB. A store holds at most 128 KB of JSON, a document at most 512 KB across at most 16 stores. One person sends at most 25 frames a second per document (bursts to 40), and ClayJS paces itself to stay under that. A change the room refuses is undone in the tab, with a console warning.
+**Limits on hyperclay.com.** A frame carries at most 128 ops and 64 KB, except that one value larger than that is sent in a request of its own of up to 5 MB, so a single change can write a value up to the store's 4 MB; the page editor splits its changes into 12 KB pieces, so a Document's size is not limited by the frame. A store holds at most 4 MB of JSON, a document at most 6 MB across at most 16 stores, which gives a Document roughly 900 KB of text that keeps compacting. One person sends at most 25 frames a second per document (bursts to 40), and ClayJS paces itself to stay under that. A change the room refuses is undone in the tab, with a warning. When the server holds as much live data as it can, a document without a room, or a change that would grow one, moves at save speed and tries the room again a minute later.
 
 **A two-player example.** The board above plus a never-saved lobby for pointers:
 
@@ -1012,7 +994,6 @@ Traps:
 
 Traps:
 
-- **Undo of a `persist` control restores the attribute, not what is shown** (5.3). Re-sync `.checked` and `.value` on `undo` and `redo`.
 - **It takes Cmd+Z in every text field**, including inputs it does not record (a non-persist input), so their native undo is lost.
 - 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 that matters.
@@ -1094,15 +1075,11 @@ For fixed content, such as code samples in a docs page, mark the block `clay="fr
 
 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. With `new OverType(el, { persist: true })` the saved file holds only a `<textarea persist>` and its wrapper; everything else is `editor-ui`. Keep one live instance at a time, and normalize OverType's layout state in an `onbeforesave` on the container. A journal built this way keeps entries as `<article data-id>` records, clones its chrome from a `<template>`, and paints the open entry with a runtime stylesheet.
 
-### 8.10 Bevel components
-
-Bevel (`@panphora/bevel`) is a separate component library with a kanban board, an editable data grid, inline edit, upload dropzone and modal, all with state in markup. ClayJS does not load it. Load `bevel.css` and `bevel.js` yourself and register `Bevel.prepareForSave` with `clay.onSnapshot`. It has its own drag and events and is not wired to ClayJS undo or sortable. Use it when a ready-made grid or board is acceptable; build from this guide when the app needs its own shape.
+### 8.10 Attributes from older Hyperclay files
 
-### 8.11 Attributes from older Hyperclay files
+Older Hyperclay files can carry attributes ClayJS ignores: `movable`, `movable-handle`, `prevent-enter`, `autosize`, `ajax-form`, `ajax-button`, `send-message`, `upgrade`. Replace them with a few lines of code (`prevent-enter`: a keydown handler; `autosize`: CSS `field-sizing: content`; `movable`: pointer events writing `data-x`/`data-y`; `send-message`: the `message` plugin, 8.13). Old saved `<html editmode="false">` and hand-written `option-visibility-styles` style tags are dead weight; ClayJS strips the root attributes on the next save.
 
-Older Hyperclay files can carry attributes ClayJS ignores: `movable`, `movable-handle`, `prevent-enter`, `autosize`, `ajax-form`, `ajax-button`, `send-message`, `upgrade`. Replace them with a few lines of code (`prevent-enter`: a keydown handler; `autosize`: CSS `field-sizing: content`; `movable`: pointer events writing `data-x`/`data-y`; `send-message`: the `message` plugin, 8.14). Old saved `<html editmode="false">` and hand-written `option-visibility-styles` style tags are dead weight; ClayJS strips the root attributes on the next save.
-
-### 8.12 sap.js: records, views and totals in markup
+### 8.11 sap.js: records, views and totals in markup
 
 `sap.js` (a satellite, also published standalone as `@panphora/sapjs`) is a reactive attribute layer whose only store is the DOM. Every change runs one pass: it reads the app out of the live page, computes `calc:` fields in dependency order, and writes only the paints that changed. It is the way to build the reactive parts of a malleable document app: totals, filtered and sorted views, a form that adds records, an editor for the selected record.
 
@@ -1134,12 +1111,12 @@ Rules for sapjs in a malleable file:
 - **Every `detail=` panel and `<dialog>` sits inside a `clay="freeze"` wrapper.** Its controls are painted with the open record's values; outside freeze they would save a second copy. Not `editor-ui`, which removes the element from the file. sapjs warns `W31` for a dialog without the wrapper.
 - **Give records a `data-id`**, and `data-id=""` on blueprints: `$add` and `trigger-add` mint fresh ids. Live sync pairs elements by it.
 - **`persist` on bound inputs inside records**, so typed values reach the attributes a save captures.
-- **Re-sync controls after undo and redo**: they restore the attribute, not the live value sapjs reads (a sync merge moves live values itself). Use the `syncControls` script in [sapjs guide section 8](https://saphtml.com/guide.html#8-work-with-clayjs), which restores inputs, checkboxes, textareas and selects.
+- **Undo and redo restore `persist` controls' live values** from their attributes, and a sync merge does the same, 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, for example 4.4's `viewmode:readonly`. The warning is harmless, but 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.
 
-### 8.13 The CMS, in passing
+### 8.12 The CMS, in passing
 
 `?plugins=cms` turns a page into a content-managed page: a JSON rules tag maps field names to selectors, and an "Edit content" button opens a sidebar form (or edits text in place) that writes straight into the DOM.
 
@@ -1153,7 +1130,7 @@ It fits content sites: landing pages, menus, pricing, FAQs, team pages, where th
 
 ---
 
-### 8.14 message: contact forms
+### 8.13 message: contact forms
 
 `?plugins=message` sends a visitor's form to the document's owner. On hyperclay.com the owner gets it by email and in their messages.
 
@@ -1245,7 +1222,7 @@ Never put per-viewer state on `<html>` or any record element without that: it au
 
 Pick by whether the saved file must show the value:
 
-- **Computed only from the records** (counts, progress badges, totals, a card's face): ordinary saved content. Write it into the record markup, ship the file pre-painted, and recompute on every change; every tab computes the same value, so a merge never fights over it. With sap this is just a paint (8.12). The starter Kanban paints its list counts and card faces this way.
+- **Computed only from the records** (counts, progress badges, totals, a card's face): ordinary saved content. Write it into the record markup, ship the file pre-painted, and recompute on every change; every tab computes the same value, so a merge never fights over it. With sap this is just a paint (8.11). The starter Kanban paints its list counts and card faces this way.
 - **Different per tab** (search results, which entry is open, "overdue" against today's date, OS shortcut labels, names loaded from the people plugin): write it inside a `clay="freeze"` scratchpad (5.2). The element saves and syncs; its contents never do.
 - **Pure UI** (buttons, menus, handles): `editor-ui`, created from a `<template>` (9.2).
 - **Optionally, `no-dirty`** for a computed value the saved file shows: it saves with the next real edit, never counts as an edit itself, and remote wins under sync. Apply the 7.3 workaround. The finance tracker does this.
@@ -1257,7 +1234,7 @@ Always write derived text through a guard, because writing the same text is stil
 const setText = (el, text) => { if (el.textContent !== text) el.textContent = text; };
 ```
 
-Recompute on three triggers: record mutations (a `MutationObserver` on the record container, coalesced with a microtask), `clay:sync-applied`, and `hashchange` when the hash affects the view. Observe the record, not the chrome, so derived writes do not trigger themselves.
+Recompute inside `clay.effect(render)`, which covers record mutations, merges, undo and redo (7.5), and call `render()` from a `hashchange` listener when the hash affects the view.
 
 With sapjs, every derived value here is a paint. sapjs recomputes on record mutations and `clay:sync-applied` by itself, and on hash changes only through `clay-router.js` (`clay:route`); an app with its own hash format keeps a `hashchange` listener that calls `Sap.refresh()`. See [sapjs guide section 6](https://saphtml.com/guide.html).
 
@@ -1333,7 +1310,7 @@ document.addEventListener("click", (event) => {
 
 ### 9.7 Filters and view switching
 
-- **Filter by hiding** records with a runtime stylesheet (skeleton, kanban), or with sapjs through an `each=` view or a frozen stylesheet (8.12). The finance example still uses sap `show=` plus snapshot normalization, an older pattern: `show=` writes `hidden` into saved records. Never remove records to filter.
+- **Filter by hiding** records with a runtime stylesheet (skeleton, kanban), or with sapjs through an `each=` view or a frozen stylesheet (8.11). The finance example still uses sap `show=` plus snapshot normalization, an older pattern: `show=` writes `hidden` into saved records. Never remove records to filter.
 - **Switch layouts with CSS** over the same records where possible: a list view can be the board with `display: contents` on columns.
 - **Projection views** (a table of all cards, a calendar, a due-today list) render into an `editor-ui` container and rebuild on record mutation, `clay:sync-applied` and `hashchange`. Edits made in a projection write to the record by id.
 
@@ -1341,7 +1318,7 @@ With sapjs, a projection view is an `each=` attribute, and its rows edit the rec
 
 ### 9.8 Computed totals
 
-Plain JavaScript into `editor-ui` (9.4) for a count or two. Sapjs for anything with arithmetic across rows, categories and formats (8.12, and the expense tracker in sapjs guide section 9). Store money as integers or as plain numbers in `value` attributes, never as formatted strings.
+Plain JavaScript into `editor-ui` (9.4) for a count or two. Sapjs for anything with arithmetic across rows, categories and formats (8.11, and the expense tracker in sapjs guide section 9). Store money as integers or as plain numbers in `value` attributes, never as formatted strings.
 
 ### 9.9 Import and export
 
@@ -1380,18 +1357,18 @@ 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.
 
-### 9.10 The boot guard
+### 9.10 Starting the app once
 
-A live-sync merge can re-insert an inline script, which runs it again: every listener doubles and every chrome element appears twice. Guard the app script:
+A live-sync merge can re-insert an inline script, which runs it again: every listener doubles and every chrome element appears twice. Start the app with `clay.start`. It runs its function once per page, after `clay.ready`, and a repeat call does nothing:
 
 ```js
-clay.ready.then(() => {
-  if (window.__boardStarted) return;
-  window.__boardStarted = true;
+clay.start(() => {
   …
 });
 ```
 
+A page with more than one app script names each one so they do not share a slot: `clay.start("board", fn)`.
+
 ### 9.11 Size
 
 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):
@@ -1405,6 +1382,28 @@ Every save captures and serializes the whole document, every change check captur
 
 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.
 
+### 9.12 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:
+
+```js
+await clay.ready;
+clay.style("app-colors", ".status { color: blue; }");
+```
+
+The name identifies a `<style data-name="app-colors" clay="no-dirty">` in the document's head. A repeated call updates the existing tag in place. Refreshing it does not add an undo step, start an autosave, or raise the close warning. The next real save includes the current CSS. On the first load, before any save has carried the tag, the script creates it.
+
+The one-argument form keeps an external stylesheet link current:
+
+```js
+await clay.ready;
+const link = clay.style("/app.css?v=2");
+```
+
+If the saved file has `/app.css?v=1`, this updates that link's `href` to `/app.css?v=2`. Matching uses the URL's origin and path, ignoring its query and fragment. The link is also `no-dirty` and travels with the next real save. Both forms return the element synchronously; the link form does not wait for the stylesheet to load. Both work in edit and view mode.
+
+Use `clay="editor-ui"` instead for CSS that viewers must not receive or that represents per-tab state, such as a temporary filter. Those styles are stripped from saved HTML. `clay.style` is for CSS that belongs in the file; changing its name on every load creates another saved tag. Adding or rewriting a plain style tag without `no-dirty` can raise the leave warning even though the person edited nothing.
+
 ---
 
 ## 10. Recipes
@@ -1455,7 +1454,7 @@ Missing pieces to add on the same model: a table block (`<table>` with `editmode
 - `main#app[sap]` with a summary of `no-dirty` outputs (budgeted, spent, left), a categories table (`items="categories"`, each row a name, a persisted budget input, computed spent and left, a progress bar via `css:used`) and a transactions table (`items="txns"`, each row date, memo, category with a datalist, amount).
 - Category spent: `calc:spent="sum(root.txns.filter(t => t.cat === item.name), 'amount')"`.
 - Search: a `transient` bound input, `calc:match` and `show="item.match"` per row, `hidden` stripped from snapshots.
-- Rows get stable ids from `claimRowIds`, a workaround from before sapjs minted unique ids. A new app writes `data-id=""` on the blueprint and lets `trigger-add` mint ids (8.12).
+- Rows get stable ids from `claimRowIds`, a workaround from before sapjs minted unique ids. A new app writes `data-id=""` on the blueprint and lets `trigger-add` mint ids (8.11).
 - CSV import (edit only) and export (both modes).
 - The 7.3 acknowledge workaround for `no-dirty` totals.
 
@@ -1479,7 +1478,7 @@ One `<section class="slide" data-id data-layout="title|bullets|image|quote">` pe
 
 ### 10.8 Content site
 
-Without the CMS: `editable` regions for copy, upload and quickcrop for images, `sortable` lists for features. With the CMS: a rules tag and `?plugins=cms` (8.13).
+Without the CMS: `editable` regions for copy, upload and quickcrop for images, `sortable` lists for features. With the CMS: a rules tag and `?plugins=cms` (8.12).
 
 ---
 
@@ -1519,7 +1518,8 @@ Cross-cutting:
 | Presence | none | none | avatar stack, no API |
 | `by` on frames, editing marker | no | no | yes |
 | Live stores (7.9) | tabs of one browser at full speed | tabs of one browser at full speed; other devices at save speed | every editor at full speed |
-| Wire and ai-edit | yes | yes | no |
+| Page editor merge state (7.9) | none in the file: open tabs share it, a fresh open rebuilds it from the article | 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/` |
 | Version history | yes | 60 days, newest 20 | a version per save; a restore does not reach open editors' tabs, so reload after restoring |
@@ -1560,9 +1560,9 @@ The saved file is the data. Everyone who can download it can read everything in
 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 in `editor-ui`, or `no-dirty` when the file must show them; every derived write is guarded.
-11. Commands are wrapped in `clay.undo.commit`; checkboxes and inputs are re-synced from attributes on undo, redo and `clay:sync-applied`.
-12. A `clay:sync-applied` handler re-renders and closes views whose record vanished.
-13. The app script has a boot guard; all listeners are delegated.
+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.
@@ -1628,7 +1628,7 @@ The saved file is the data. Everyone who can download it can read everything in
 | The undo plugin takes Cmd+Z in every text field | 8.3 |
 | Undoing an add removes the record even after a peer edited it | 8.3 |
 | Pausing undo across an `await` loses the earlier mutations | 8.3 |
-| Sap reads live control values: undo without re-syncing inputs saves the undone number | 5.3, 8.12 |
+| Sap reads live control values: undo without re-syncing inputs saves the undone number | 5.3, 8.11 |
 | `clay.upload` is not a picker; embed only on `unsupported` | 8.5 |
 | `clay.confirm` rejects with `undefined` on cancel | 8.6 |
 | A live element passed to `clay.modal.html` is deleted | 8.6 |
@@ -1636,15 +1636,16 @@ The saved file is the data. Everyone who can download it can read everything in
 | `onclone` does not fire for template fragments | 8.7 |
 | `el.nearest` reads a neighbour record's field | 8.7 |
 | `hide()`, `show()`, `css()` write saved inline styles | 8.7 |
-| A file whose painted values do not match sap's state writes at load | 8.12 |
+| A file whose painted values do not match sap's state writes at load | 8.11 |
 | Dialog prompts are HTML: record text in `clay.confirm` runs a collaborator's markup | 8.6 |
 | `editmode:resource type="inert/javascript"` activates as `javascript` and never runs | 4.4 |
-| Sap's template row shows before sap loads | 8.12 |
-| CMS `cms-template` with `hidden` makes every new item invisible | 8.13 |
+| Sap's template row shows before sap loads | 8.11 |
+| CMS `cms-template` with `hidden` makes every new item invisible | 8.12 |
 | Records stored twice drift | 9.1 |
 | `applyData` pairs rows by content and order, not by id | 9.9 |
 | Activity logged from a mutation observer also logs peers and undo | 9.6 |
 | Saves slow down past about 1,000 records and stall past 3,000 | 9.11 |
+| Updating a runtime style tag without `no-dirty` can raise the leave warning | 9.12 |
 | A version restore on hyperclay.com does not reach open editors | 12.1 |
 | Hidden is not private | 12.3 |
 | Typed values vanish from a visitor's draft: the control has no `persist` | 14.2 |
@@ -1664,11 +1665,11 @@ The owner is a visitor here too. Signed in, they get the same private draft unle
 
 A page that wants draft mode needs all of this. The example in 14.8 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 (8.13).
+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 (8.12).
 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.
 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 (5.3), 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, 8.12).
+5. `data-id` on every record and `data-id=""` on every blueprint. New rows mint their own (`trigger-add` does it, 8.11).
 6. `<meta name="application-name" content="...">`. The prompt, the intro and the download name the app from it, falling back to the title before the first `:` or `|`.
 7. A feedback link the visitor can use: a `mailto:` address in the page, not in the plugin.
 8. Optional: a `<template visitor-intro>` (14.6). No template, no intro; the prompt still shows.
@@ -1725,7 +1726,7 @@ The rung is where a free document lives, so the details matter:
 
 ### 14.5 Restoring and redrawing
 
-The restore runs while ClayJS boots, before `clay.ready` resolves, and applies the stored JSON to the live page with `applyData`. sapjs and any code that waits for `clay.ready` therefore see the restored values, not the authored ones, and sapjs re-derives on the mutations the restore makes, so a count or a total painted in markup is right on the first paint after it. Load `clay.js` before `sap.js` for that: sapjs mounts when `clay.ready` resolves, and a page that mounts it first paints the authored values with no later mutation to correct them (8.12).
+The restore runs while ClayJS boots, before `clay.ready` resolves, and applies the stored JSON to the live page with `applyData`. sapjs and any code that waits for `clay.ready` therefore see the restored values, not the authored ones, and sapjs re-derives on the mutations the restore makes, so a count or a total painted in markup is right on the first paint after it. Load `clay.js` before `sap.js` for that: sapjs mounts when `clay.ready` resolves, and a page that mounts it first paints the authored values with no later mutation to correct them (8.11).
 
 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 }`.
 
@@ -1765,7 +1766,7 @@ An element inside the template with `[visitor-intro-start]` scrolls to the app,
 
 ### 14.8 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 (8.12). 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, so sapjs logs its harmless W03 warning for each `viewmode:` attribute (8.11). 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>

package/entries/clay.js

@@ -23,6 +23,28 @@
 
   if (!clay.ready) mintReady();
 
+  // clay.start runs app code once per page, after boot. A live-sync merge can
+  // re-insert an inline script and run it again; the repeat call is a no-op.
+  // It lives in the bootstrap so an inline script can call it before boot ends.
+  if (!clay.start) {
+    var started = Object.create(null);
+    clay.start = function (name, fn) {
+      if (typeof name === "function") { fn = name; name = ""; }
+      if (started[name]) return;
+      started[name] = true;
+      // A failed boot rejects the old promise after minting a new one, so a call
+      // made before the failure waits for the corrected tag's boot instead.
+      var wait = function () {
+        var ready = clay.ready;
+        return ready.then(fn, function (err) {
+          if (clay.ready === ready) throw err;
+          return wait();
+        });
+      };
+      return wait();
+    };
+  }
+
   var script = document.currentScript;
   if (!script || !script.src) {
     console.error("clayjs: could not determine my own URL (load me with a classic <script src=...>, not type=\"module\")");