@panphora/clayjs 1.21.0 → 1.23.0

package/docs/guide.md

@@ -315,7 +315,7 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 | `sync` | off | yes | live sync, `clay.conflicts`, `clay.morph`, presence and the editing marker |
 | `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) |
+| `undo` | off | no | `clay.undo` (whole-page undo over DOM mutations; leaves Cmd+Z to text fields) |
 | `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` |
@@ -326,6 +326,7 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 | `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 | `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/)) |
+| `visitor-menu` | off | no (draft mode only) | `clay.menu` and `clay.variants` in draft mode: **Download a copy**, [DOM menu items](https://clayjs.com/docs/plugins/menu/#menu-items-from-the-page) and [looks](https://clayjs.com/docs/plugins/menu/#looks), with no owner or host actions ([The visitor menu](https://clayjs.com/docs/plugins/menu/#the-visitor-menu)) |
 | `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)) |
 | `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` |
@@ -337,15 +338,20 @@ Plugins add editing, sync, and UI features to `clay.js`. Most are off by default
 - 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.
-- Nothing implies `undo`, on purpose: name it when the page should have whole-page undo. It leaves Cmd+Z to text fields ([undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo)).
+- Use `exclude=richclay` when the document 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.
+- Nothing implies `undo`, on purpose: name it only when the document has discrete DOM commands that should undo as whole-page steps. It leaves Cmd+Z to text fields ([undo: whole-page undo](https://clayjs.com/docs/guide/components/#undo-whole-page-undo)).
 - In view mode, `page` loads only its reader half and nothing it implies. A Document on `plugins=page` resolves to `page-view`, with no live data service, no generic `sync`, and no `upload`. Name `sync` as well (`plugins=page,sync`) when the reader should take its saved files from sync's lane instead of its own.
 - `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.
+- `visitor-menu` loads only in draft mode (`draftOnly` and `editOnly`). A reader in view mode and an owner editing the original skip it and download zero bytes ([The visitor menu](https://clayjs.com/docs/plugins/menu/#the-visitor-menu)).
 
 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:** `?plugins=sync,undo,indicator,menu&exclude=richclay`. It gives a page of plain text live sync, whole-page undo, a save status chip and an Edit switch. Then add by task: `sortable` for drag-to-reorder lists, and `upload` for images or attachments. For formatted text, drop `exclude=richclay` and use `editable`. A document opens in view even for its owner, which is why `menu` is in the default. Declare `<html opens-in="edit">` on a tool page that must edit as soon as it opens.
+**Defaults by document kind:**
+
+- **Owned document:** `?plugins=sync,indicator,menu&exclude=richclay`. It gives a plain-text document live sync, a save status chip, and an Edit switch (`source` is on by default in edit mode, and `derive` turns on when `[sap]` is present). A document opens in view even for its owner, which is why `menu` is in the default; declare `<html opens-in="edit">` on a tool document that must edit as soon as it opens.
+- **Free document:** `?plugins=visitor-drafts,visitor-menu,menu&exclude=richclay`. In draft mode, ClayJS drops `menu`, `sync`, `upload`, `people`, `source`, and the other host plugins while `visitor-drafts` and `visitor-menu` run; when the owner edits the original, `visitor-menu` is skipped and `menu` and `source` run; for a view-mode reader, neither menu renders.
+- **Add by task on either kind:** `sortable` for `[sortable]` lists, `upload` for attachments, `people` for collaborator names, `bind-text` for a bound `<textarea>`, `unsent` for `[unsent]` inputs, `indicator` when a free document has no `savestatus` UI of its own, `sync` when the owner of a free document co-edits across tabs, and `undo` only when the document runs discrete DOM commands (adding, removing, or moving records) that should undo as whole-page steps. Leave `undo` off when editing happens inside text inputs, textareas, or `contenteditable`, which already use the browser's native undo; otherwise `undo` also groups idle DOM mutations into page steps on Cmd+Z outside the field. For formatted rich text, drop `exclude=richclay` and use `editable`.
 
 ### 2.3 Satellites
 
@@ -1979,7 +1985,7 @@ Rules for sapjs in a malleable file:
 
 ### 7.12 cms: content-managed pages
 
-`?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.
+`?plugins=cms` turns a page into a content-managed page. It brings ClayJS's menu plugin automatically; the menu is a small dock in a corner of the page, shown only to someone who can edit. A JSON rules tag maps field names to selectors, and **Open the CMS (Edit content)** in the menu opens a sidebar form (or edits text in place) that writes straight into the DOM.
 
 ```html
 <script data-rules-name="cms" data-rules-version="1" type="application/json">
@@ -1989,7 +1995,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 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 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. **Open the CMS (Edit content)** in the menu 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.
 
@@ -2518,17 +2524,17 @@ The owner is a visitor here too. Signed in, they get the same private draft unle
 
 ### 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:
+A document 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 the data contract, 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 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.
+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 document'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,visitor-menu` on the loader tag (plus `menu` when the owner also edits the hosted or local file, `exclude=richclay` when there is no rich text, and whatever else the document needs; see [The visitor menu](https://clayjs.com/docs/plugins/menu/#the-visitor-menu)).
 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)).
-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>` ([The download prompt and the intro area](https://clayjs.com/docs/guide/free-documents/#the-download-prompt-and-the-intro-area)). No template, no intro; the prompt still shows.
-9. A round trip test in your own repo: write a draft, load the page again with that storage, and check that the values and the computed counts come back.
+6. `<meta name="application-name" content="...">`. The prompt, the intro and the download name the document from it, falling back to the title before the first `:` or `|`.
+7. An appreciation or feedback link in the document, not in the plugin: a `mailto:` `<a clay-menu-item data-id="...">` element with its `cms-template` seed row in a hidden container outside `clay="freeze"`, covered by the `api` rules tag ([Menu items from the page](https://clayjs.com/docs/plugins/menu/#menu-items-from-the-page)).
+8. Optional: a `<template visitor-intro>` or `<template visitor-intro="manual">` ([The download prompt and the intro area](https://clayjs.com/docs/guide/free-documents/#the-download-prompt-and-the-intro-area)). No template, no intro; the prompt still shows.
+9. A round trip test in your own repo: write a draft, load the document again with that storage, and check that the values and the computed counts come back.
 
 Bump the slot (`-v2`) only when an old draft cannot fit the new rules. A draft that no longer fits is parked, not thrown away ([Restoring and redrawing](https://clayjs.com/docs/guide/free-documents/#restoring-and-redrawing)).
 
@@ -2556,10 +2562,11 @@ 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`, `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 plugins that talk to the host are dropped**, even when the document 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.
+- **`menu` stays dropped for visitors, and `visitor-menu` runs instead.** `menu` carries the Edit switch, SEO settings, presence, look deletion (`keep()`), and `/_/meta` capability checks, all of which belong to the owner. When the loader tag names `visitor-menu`, draft mode loads `visitor-menu` in its place and mounts `clay.menu` with **Download a copy**, [DOM menu items](https://clayjs.com/docs/plugins/menu/#menu-items-from-the-page), and [looks](https://clayjs.com/docs/plugins/menu/#looks), with no owner code and no host requests ([The visitor menu](https://clayjs.com/docs/plugins/menu/#the-visitor-menu)).
 - **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)).
+- **`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 document 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)).
 - **`clay.visitorDrafts`** is the plugin's whole surface:
 
 | Member | What it is |
@@ -2569,12 +2576,13 @@ The rung is where a free document lives, so the details matter:
 | `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 |
+| `saveNow()` | write the document to the slot now; `true` when it landed, `false` when it did not |
 | `reset()` | delete this slot and reload the page; nothing outside draft mode |
 | `onRestore(fn)` | call `fn(detail)` at once when the restore already ran, otherwise on `clay:drafts-restored` |
 | `editOriginal()` | navigate to this page with `?editmode=true` |
 | `backToDraft()` | navigate back with `editmode` removed |
 | `downloadUrl()` | the download link the prompt is using, with `src` |
+| `download()` | flush the draft store and trigger the prompt's download |
 | `source` | the `?src=` this slot remembers, or `null` ([The download prompt and the intro area](https://clayjs.com/docs/guide/free-documents/#the-download-prompt-and-the-intro-area)) |
 
 - **Three events** on `document`: `clay:drafts-restored` with `{ restored, hadDraft, parked }`, `clay:drafts-saved` with `{ data }`, and `clay:drafts-store-failed` with `{ error }`.
@@ -2599,13 +2607,16 @@ Both are runtime chrome: `clay="editor-ui"` and `sap-ignore`, built by the plugi
 
 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.
+**The intro** is authored per document as `<template visitor-intro>` (the default) or `<template visitor-intro="manual">`. The template holds the author's whole strip: its markup and any `<style>` it needs. The plugin clones it into `<section class="clay-intro">` at the very top of `document.body`, before the document's own content.
+
+- **Default (`<template visitor-intro>`):** adds a quiet `x` button (`Hide this introduction`) in the corner and dismisses for good when the visitor clicks `x` or scrolls the strip past the top of the viewport. UI memory records `"closed"` or `"scrolled"`, and no menu item is added.
+- **Manual (`<template visitor-intro="manual">`):** adds a **Hide intro** button in the corner instead of `x`, and never collapses or dismisses on scroll. Clicking **Hide intro** (or `[visitor-intro-dismiss]`) records `"closed"` in UI memory, removes the section, focuses the document, and adds **Show intro** (`id: "clay.intro"`) to `clay.menu` (waiting for `clay:menu-ready` when the menu mounts later, and also adding **Show intro** on loads where the intro starts hidden because a draft already exists or `done` is `"closed"`). Choosing **Show intro** clears `intro.done`, prepends the same `<section>` back onto `document.body` without re-cloning the template, removes **Show intro** from the menu, and scrolls to the top.
 
-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.
+A `<script type="module">` inside the template runs when the intro first 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>
+<template visitor-intro="manual">
+  <p>One paragraph on what the document does and who it is for.</p>
 </template>
 ```
 
@@ -2615,11 +2626,11 @@ When there is a release video, add it as the first element of the template, and
 <video src="/_/uploads/assets/kanban/release.mp4" poster="/_/uploads/assets/kanban/release-poster.jpg" controls playsinline preload="metadata"></video>
 ```
 
-An element inside the template with `[visitor-intro-start]` scrolls to the app, and one with `[visitor-intro-dismiss]` closes the intro the same way the `x` does. A deep link (a URL with a `#...`) skips the intro so a shared link opens where it points, a draft skips it too, and `?intro=1` forces it.
+An element inside the template with `[visitor-intro-start]` scrolls smoothly to the document below the intro, and one with `[visitor-intro-dismiss]` closes the intro the same way the corner button does. A deep link (a URL with a `#...`) skips the intro on load so a shared link opens where it points, an existing draft skips it too, and `?intro=1` forces it open.
 
-**The prompt** needs nothing from the app but its name: a small tab at the bottom right ("This app is free to keep") that opens into a card holding the download link and "Don't show again", with a minimize button in its corner. The tab's X and the card's minimize button leave a small "Keep" button with the download icon that reopens the download card. That choice survives reload. It opens itself once after the visitor has touched three fields. "Don't show again" stops those reminders for that slot but keeps the icon, including for previously dismissed notices. A storage failure opens it in its error state, and the next good save clears it. In that error state the download link does not go to the host, whose download page would read the stored copy that just failed to be written: the plugin builds the file from the live page in the browser instead, named after the page file with `.htmlclay` at the end.
+**The prompt** needs nothing from the document but its name: a small tab at the bottom right ("This app is free to keep") that opens into a card holding the download link and "Don't show again", with a minimize button in its corner. The tab's X and the card's minimize button leave a small "Keep" button with the download icon that reopens the download card. That choice survives reload. It opens itself once after the visitor has touched three fields. "Don't show again" stops those reminders for that slot but keeps the icon, including for previously dismissed notices. A storage failure opens it in its error state, and the next good save clears it. In that error state the download link does not go to the host, whose download page would read the stored copy that just failed to be written: the plugin builds the file from the live page in the browser instead, named after the page file with `.htmlclay` at the end.
 
-**The download link** is `/_/download<path>?as=htmlclay`, with the page's path (`/_/download?as=htmlclay` for `/`) and `&src=<src>` when this slot has one. `clay.visitorDrafts.downloadUrl()` returns it. **`?src=` is first touch**: the first valid value the page sees for this slot is kept and rides into the download link and every signup. Valid values match `/^[a-z0-9][a-z0-9-]{0,39}$/`.
+**The download link** is `/_/download<path>?as=htmlclay`, with the document's path (`/_/download?as=htmlclay` for `/`) and `&src=<src>` when this slot has one. `clay.visitorDrafts.downloadUrl()` returns it. **`?src=` is first touch**: the first valid value the page sees for this slot is kept and rides into the download link and every signup. Valid values match `/^[a-z0-9][a-z0-9-]{0,39}$/`.
 
 **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()`.
 
@@ -2739,7 +2750,7 @@ The `:legacy` marker is what stops a reset from coming back: once ClayJS has cop
 
 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.
+3. On an owned collaborative document, `sync` is in `plugins=`; on a [free document](https://clayjs.com/docs/guide/free-documents/), `visitor-drafts,visitor-menu,menu` is in `plugins=`. Add `exclude=richclay` if there is no rich text, and add task plugins (`sortable`, `upload`, `undo`, `indicator`) only when the document uses them.
 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.
@@ -2748,9 +2759,9 @@ The `:legacy` marker is what stops a reset from coming back: once ClayJS has cop
 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.
+12. When `undo` is loaded, commands are wrapped in `clay.undo?.commit(label, fn)` (falling back to `fn()` when `undo` is absent); 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.
+14. The document 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.
@@ -2759,7 +2770,7 @@ The `:legacy` marker is what stops a reset from coming back: once ClayJS has cop
 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.
+23. A tool document 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "type": "module",
   "description": "clayjs: malleable documents. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",
@@ -96,7 +96,7 @@
     "@fontsource-variable/work-sans": "5.3.0",
     "@fontsource/ibm-plex-mono": "5.3.0",
     "@fontsource/ibm-plex-sans": "5.3.0",
-    "@panphora/bevel": "0.1.0",
+    "@panphora/bevel": "0.3.2",
     "@web/test-runner": "^0.20.2",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.1",

package/src/core/save-replace.js

@@ -24,12 +24,15 @@ function failed() {
  *
  * @param {string} html - the whole document, as it should be stored
  * @param {Object} [options]
- * @param {?string} [options.etag] - the stamp to replace, defaulting to this tab's
+ * @param {?string} [options.etag] - the stamp to replace. Left out, it is this tab's
+ *   stamp at the moment of writing; given, even as null, it is exactly that stamp, so a
+ *   caller that captured the document earlier never writes against a later version.
  * @returns {Promise<{ok: true, etag: ?string}|{ok: false, code: "conflict"|"forbidden"|"unsupported"|"failed"}>}
  */
 export async function replace(html, { etag } = {}) {
   if (typeof html !== "string" || html === "") return failed();
 
+  const pinned = etag !== undefined;
   const given = typeof etag === "string" && etag ? etag : null;
   // Discovery is what says whether the capability exists, and it is also where a
   // tab that has never saved learns the stamp it is about to replace.
@@ -38,7 +41,7 @@ export async function replace(html, { etag } = {}) {
 
   // With no stamp the write would be unconditional, which is exactly what this lane
   // promises never to send. A reload gives the tab the stamp it is missing.
-  const stamp = given || lastSeenEtag();
+  const stamp = pinned ? given : lastSeenEtag();
   if (!stamp) return { ok: false, code: "conflict" };
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);

package/src/core/serialize-steps.js

@@ -103,7 +103,15 @@ export function* serializeForSyncSteps(clone) {
   const shell = bareRoot.outerHTML;
   const endTag = `</${bareRoot.localName}>`;
   const out = ["<!DOCTYPE html>", shell.slice(0, shell.length - endTag.length)];
-  yield* serializeChildrenSteps(clone, clonePreventingOnclone(clone, false), out, { bytes: 0 });
+  const blocks = noscriptBlocks(clone);
+  const raw = blocks.length ? swapNoscriptMarkers(blocks) : [];
+  try {
+    yield* serializeChildrenSteps(clone, clonePreventingOnclone(clone, false), out, { bytes: 0 });
+  } finally {
+    for (const [el, kids] of blocks) el.replaceChildren(...kids);
+  }
   out.push(endTag);
-  return out.join('');
+  let html = out.join('');
+  for (const [marker, text] of raw) html = html.split(marker).join(text);
+  return html;
 }

package/src/core/snapshot.js

@@ -294,6 +294,30 @@ export function noscriptBlocks(clone) {
   return blocks;
 }
 
+/**
+ * Each <noscript> of a document parsed with scripting off, given back the one text node a
+ * scripting parser keeps. DOMParser parses with scripting off, so a received <noscript>
+ * holds its markup as elements and its escaped text decoded: merged as elements, a fallback
+ * stylesheet would go live, and written raw, decoded text would become markup. Its
+ * innerHTML in that document is the source again, escaping included.
+ */
+export function noscriptsAsText(doc) {
+  const found = [];
+  const collect = (node) => {
+    for (const child of node.childNodes) {
+      if (child.nodeType !== 1) continue;
+      if (child.localName === 'noscript' && child.namespaceURI === XHTML_NS) {
+        if (child.firstChild) found.push(child);
+        continue;
+      }
+      collect(child.localName === 'template' && child.content ? child.content : child);
+    }
+  };
+  collect(doc.documentElement ?? doc);
+  for (const el of found) el.replaceChildren(el.ownerDocument.createTextNode(el.innerHTML));
+  return doc;
+}
+
 /** Swap each block's text for a marker, and answer the text each marker stands for. */
 export function swapNoscriptMarkers(blocks) {
   const nonce = Math.random().toString(36).slice(2);
@@ -941,11 +965,23 @@ export function serializeForSync(clone) {
   // truncate the broadcast.
   const shell = bareRoot.outerHTML;
   const endTag = `</${bareRoot.localName}>`;
+  // A <noscript>'s text is written raw, as serializeClone writes it: escaped, a head
+  // <noscript> parses as text on the receiving side, which closes the head and puts
+  // the fallback markup at the top of <body>, and that tab then saves it.
+  const blocks = noscriptBlocks(clone);
+  const raw = blocks.length ? swapNoscriptMarkers(blocks) : [];
+  let inner;
+  try {
+    inner = clone.innerHTML;
+  } finally {
+    for (const [el, kids] of blocks) el.replaceChildren(...kids);
+  }
+  for (const [marker, text] of raw) inner = inner.split(marker).join(text);
   // The doctype, so this artifact is a complete document like every other one this
   // module produces. Spec section 2 asks for that, and it costs nothing on the wire:
   // a receiver parses the string and morphs documentElement against documentElement,
   // so the prologue is consumed by the parser and never reaches the morph.
-  return "<!DOCTYPE html>" + shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
+  return "<!DOCTYPE html>" + shell.slice(0, shell.length - endTag.length) + inner + endTag;
 }
 
 /** A private deep copy of a capture's clone, for work that outlives the capture event. */

package/src/core/upgrade-run.js

@@ -1,5 +1,5 @@
 import { replace as replaceDocument } from "./save-replace.js";
-import { lastSeenEtag } from "./etag.js";
+import { lastSeenEtag, seedEtag } from "./etag.js";
 import { claimDocumentOperation, releaseDocumentOperation } from "./save-core.js";
 import { isNewerVersion } from "./version.js";
 import { upgrade, readMeta } from "../vendor/hyper-html-api-upgrade.vendor.js";
@@ -281,6 +281,16 @@ async function applyUnderSlot(update, { doc, loc, fetchFn, clay, reload, replace
     }
   }
 
+  // The stamp is read before the capture, so it can only be older than the bytes the
+  // upgrade starts from: a save that lands while the capture runs or the release
+  // downloads makes the write below fail instead of being overwritten by it.
+  // A tab that has never saved learns its stamp from discovery here, before the capture,
+  // not inside the write after the download, when it would describe a later version.
+  if (etag === undefined && !lastSeenEtag()) {
+    try { await seedEtag(); } catch {}
+  }
+  const stamp = etag !== undefined ? etag : lastSeenEtag();
+
   // An editing tab's live article holds the editor, not the page: the upgrade starts from
   // the document as a save writes it.
   let source = doc;
@@ -290,6 +300,10 @@ async function applyUnderSlot(update, { doc, loc, fetchFn, clay, reload, replace
     } catch {
       return { ok: false, code: "failed", message: SAVE_FAILED };
     }
+  } else {
+    // A view-mode tab's live document can change under the download (a disk frame from
+    // another tab), so it is copied now, at the same moment as the stamp.
+    source = new DOMParser().parseFromString("<!DOCTYPE html>\n" + doc.documentElement.outerHTML, "text/html");
   }
   const prepared = await prepare(update, { doc: source, loc, fetchFn });
   if (!prepared.ok) return prepared;
@@ -301,7 +315,7 @@ async function applyUnderSlot(update, { doc, loc, fetchFn, clay, reload, replace
       : replaceDocument;
   let result;
   try {
-    result = await save(prepared.html, { etag: etag !== undefined ? etag : lastSeenEtag() });
+    result = await save(prepared.html, { etag: stamp });
   } catch {
     return { ok: false, code: "failed", message: SAVE_FAILED };
   }

package/src/loader-logic.js

@@ -82,6 +82,9 @@ export const PLUGIN_PATHS = {
   // owner editing the original, gets the owner module: the chip when it applies and
   // the inert `clay.visitorDrafts`, without the drafts UI's 24 KB.
   "visitor-drafts": { path: "plugins/visitor-drafts.js", ownerPath: "plugins/visitor-drafts-owner.js", editOnly: false, default: false },
+  // `draft: true` loads it only in a visitor's draft. The key is short on purpose: every
+  // reader downloads this file, and the reader's Brotli ceiling counts it.
+  "visitor-menu": { path: "plugins/visitor-menu.js", editOnly: true, draft: true },
   // An editor textarea outside the saved records, bound to one record's text
   // element. Edit mode only: the page that asks for it is the page whose owner
   // writes in it.
@@ -147,6 +150,7 @@ export const MODULES = {
   "plugins/demo.js":            () => import("./plugins/demo.js"),
   "plugins/visitor-drafts.js": () => import("./plugins/visitor-drafts.js"),
   "plugins/visitor-drafts-owner.js": () => import("./plugins/visitor-drafts-owner.js"),
+  "plugins/visitor-menu.js":    () => import("./plugins/visitor-menu.js"),
   "plugins/bind-text.js":       () => import("./plugins/bind-text.js"),
   "plugins/source.js":          () => import("./plugins/source.js"),
   "plugins/derive.js":          () => import("./plugins/derive.js"),
@@ -155,7 +159,7 @@ export const MODULES = {
 
 // `source` is last on purpose: its install captures a save clone, so it wants every
 // plugin that registers a document transform to have registered it first.
-const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "undo", "unsent", "quickcrop", "upload", "people", "menu", "upgrade", "cms", "page-view", "sync", "live", "page", "message", "like", "wire", "ai-edit", "demo", "derive", "bind-text", "source"];
+const PLUGIN_ORDER = ["visitor-drafts", "visitor-menu", "richclay", "indicator", "sortable", "undo", "unsent", "quickcrop", "upload", "people", "menu", "upgrade", "cms", "page-view", "sync", "live", "page", "message", "like", "wire", "ai-edit", "demo", "derive", "bind-text", "source"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through
 // a capability lookup (`clay.quickcrop`) and silently uploads the raw file when it
@@ -182,7 +186,10 @@ const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "un
 // image and file blocks send through `clay.upload`: without the plugin every drop
 // ends in "File uploads are not available", while with it a host that stores no
 // files answers `unsupported` and the editor offers to embed the file instead.
-const IMPLIES = { cms: ["quickcrop", "upload"], "ai-edit": ["wire"], page: ["live", "sync", "upload"] };
+// The menu is how a person opens the CMS: hypercms adds no button of its own. It loads
+// in view too, because that is where a person starts, and it shows itself only to
+// someone who can edit. A page with its own control uses exclude=menu.
+const IMPLIES = { cms: ["quickcrop", "upload", "menu"], "ai-edit": ["wire"], page: ["live", "sync", "upload"] };
 
 // A Document's editor owns its article's rich text, so richclay (for [editable]) has
 // nothing to do there; plugins=page,richclay still loads it.
@@ -274,7 +281,7 @@ export function resolveModules(params, isEditMode, { isDraftMode = false, hasSap
   for (const name of PLUGIN_ORDER) {
     if (!enabled.has(name)) continue;
     const spec = PLUGIN_PATHS[name];
-    if (spec.editOnly && !isEditMode) continue;
+    if ((spec.editOnly && !isEditMode) || (spec.draft && !isDraftMode)) continue;
     (LATE.has(name) ? late : plugins).push(spec.ownerPath && !isDraftMode ? spec.ownerPath : spec.path);
   }
   return { core, plugins, late };

package/src/plugins/ai-edit.js

@@ -670,17 +670,13 @@ function buildChrome() {
 
   window.addEventListener('scroll', () => { positionChrome(); hideChip(); }, { passive: true, signal });
   window.addEventListener('resize', () => { placeBubble(); if (panel && !panel.hidden) fitTextarea(); positionChrome(); }, { passive: true, signal });
-  // The CMS toggle can arrive after this chrome, and a docked sidebar slides it left.
+  // A docked CMS sidebar shifts the page under this chrome.
   const replace = () => { placeBubble(); positionChrome(); };
   document.addEventListener('hcms:open', () => { replace(); setTimeout(replace, 350); }, { signal });
   document.addEventListener('hcms:close', () => { replace(); setTimeout(replace, 350); }, { signal });
-  const cmsToggle = new MutationObserver((records) => {
-    syncBubble();
-    const touched = (nodes) => [...nodes].some((n) => n.nodeType === 1 && n.hasAttribute('data-hcms-toggle-host'));
-    if (records.some((r) => touched(r.addedNodes) || touched(r.removedNodes))) replace();
-  });
-  cmsToggle.observe(document.body, { childList: true });
-  observers.push(cmsToggle);
+  const bodyChildren = new MutationObserver(() => syncBubble());
+  bodyChildren.observe(document.body, { childList: true });
+  observers.push(bodyChildren);
 
   // A target removed from the page ends its edit, so the save hold and the paused
   // observers never outlive it. A running bar is no exception: it is torn down with
@@ -748,17 +744,10 @@ function refreshHelperState() {
   }).catch(() => {});
 }
 
-// The bubble sits in the bottom-right corner, or just left of the CMS's "Edit content"
-// toggle when the page has one, bottoms aligned, so the two never overlap.
+// The bubble sits in the bottom-right corner.
 function placeBubble() {
   if (!docBubble) return;
-  const host = document.querySelector('[data-hcms-toggle-host]');
-  const rect = host && host.getBoundingClientRect();
-  const beside = !!rect && rect.width > 0 && rect.height > 0;
-  docBubble.pin({
-    right: beside ? `${Math.round((document.documentElement.clientWidth || window.innerWidth) - rect.left + 8)}px` : '16px',
-    bottom: beside ? `${Math.round((document.documentElement.clientHeight || window.innerHeight) - rect.bottom)}px` : '16px',
-  });
+  docBubble.pin({ right: '16px', bottom: '16px' });
   paintLook(docBubble);
 }
 

package/src/plugins/cms.js

@@ -1,16 +1,13 @@
-// The CMS shell, toggle, inline layer and ghost rows, with their --mirk-* tokens pinned
-// to Bevel and the Bevel system mono face. The CMS keeps its own stylesheet and its
-// own light/dark switching. The "Edit content" toggle also gets Bevel's button face, ink and hover (src/ui/skins/cms-toggle.js).
+// The CMS shell, inline layer and ghost rows, with their --mirk-* tokens pinned to Bevel
+// and the Bevel system mono face. The CMS keeps its own stylesheet and its own light/dark
+// switching.
 import { installSkin } from "../ui/vendor-skin.js";
 import { CSS } from "../ui/skins/cms.js";
-import { CSS as TOGGLE_CSS, ROOTS as TOGGLE_ROOTS } from "../ui/skins/cms-toggle.js";
 import { cms as hypercms } from "../vendor/hypercms.vendor.js";
 
 export { cms, default } from "../vendor/hypercms.vendor.js";
 
 installSkin("cms", CSS);
-// The toggle takes the page's scheme, so Bevel's face and ink resolve the way the page reads.
-installSkin("cms-toggle", TOGGLE_CSS, { roots: TOGGLE_ROOTS });
 
 const fault = (message, code) => Object.assign(new Error(`clay:cms: ${message}`), { code });
 

package/src/plugins/menu/dom-items.js

@@ -0,0 +1,45 @@
+const SELECTOR = "[clay-menu-item]:not([cms-template])";
+
+const canSave = () => window.clay?.mode === "edit" || window.clay?.mode === "draft";
+
+async function removeAndSave(el) {
+  await window.clay?.ready;
+  if (!canSave() || !el.isConnected) return false;
+  const undo = window.clay?.undo;
+  if (undo && typeof undo.commit === "function") undo.commit("Remove this item", () => el.remove());
+  else el.remove();
+  window.clay?.save?.soon?.();
+  return true;
+}
+
+export function attachDomItems({ addItem, removeItem, beforeOpen }) {
+  const shown = new Set();
+  function sync() {
+    const seen = new Set();
+    for (const el of document.querySelectorAll(SELECTOR)) {
+      const key = el.getAttribute("data-id") || el.id;
+      if (!key) {
+        console.warn("[clay] A clay-menu-item needs a data-id or an id.", el);
+        continue;
+      }
+      const id = `dom.${key}`;
+      seen.add(id);
+      const dismiss = el.getAttribute("clay-menu-dismiss");
+      addItem({
+        id,
+        label: el.textContent.trim(),
+        href: el.getAttribute("href") || "",
+        section: el.getAttribute("clay-menu-section") || undefined,
+        quiet: el.hasAttribute("clay-menu-quiet"),
+        run: el.hasAttribute("href") ? null : () => el.click(),
+        dismiss: dismiss && canSave() ? { label: dismiss, run: () => removeAndSave(el) } : undefined,
+      });
+    }
+    for (const id of shown) if (!seen.has(id)) removeItem(id);
+    shown.clear();
+    for (const id of seen) shown.add(id);
+  }
+  beforeOpen.push(sync);
+  for (const name of ["clay:drafts-restored", "clay:sync-applied", "clay:modechange"]) document.addEventListener(name, sync);
+  sync();
+}

package/src/plugins/menu/looks.js

@@ -0,0 +1,32 @@
+export const OFF = "not all";
+export const looks = () => [...document.querySelectorAll("head style[clay-variant]")];
+export const nameOf = (style) => style.getAttribute("clay-variant");
+export const labelOf = (style) => style.getAttribute("clay-variant-label") || `Variant ${nameOf(style)}`;
+
+export function wantedLook() {
+  const name = document.documentElement.getAttribute("look");
+  return name && looks().some((style) => nameOf(style) === name) ? name : null;
+}
+
+export function activeLook() {
+  const all = looks();
+  const wanted = wantedLook();
+  return all.find((style) => nameOf(style) === wanted) || all.find((style) => style.getAttribute("media") !== OFF) || all[0] || null;
+}
+
+export function paintLook(name = wantedLook()) {
+  document.querySelector("style[clay-look-hint]")?.remove();
+  if (!name) return;
+  for (const style of looks()) {
+    if (nameOf(style) === name) style.removeAttribute("media");
+    else if (style.getAttribute("media") !== OFF) style.setAttribute("media", OFF);
+  }
+}
+
+export const carriesLook = () => /"html@look"/.test(document.querySelector('script[data-rules-name~="api"]')?.textContent ?? "");
+
+export function recordLook(name) {
+  if (!carriesLook()) return;
+  if (name) document.documentElement.setAttribute("look", name);
+  else document.documentElement.removeAttribute("look");
+}