@panphora/clayjs 0.7.3 → 1.0.0

package/README.md

@@ -4,39 +4,63 @@
 
 Self-saving, malleable HTML in one classic `<script>`. Load `clay.js` on a page and it
 becomes editable in place, snapshots its own DOM, and saves that DOM back to the file it
-came from. No build step, no framework.
+came from. No build step, no framework, no account.
+
+The document is the app *and* the database. State lives in the DOM, and a save is one POST
+of the entire serialized document. There is no data layer, no JSON on a server, no schema.
+Open the saved file in a text editor and your edit is right there in the HTML.
+
+## See it save itself
+
+[`examples/notes.html`](https://github.com/panphora/clayjs/blob/main/examples/notes.html) is a complete self-saving document. Two
+attributes do the work: `autosave` on `<html>`, and `editable` on the parts you type into.
+
+```html
+<!DOCTYPE html>
+<html lang="en" autosave>
+<head><meta charset="utf-8"><title>Notes</title></head>
+<body>
+  <h1 editable>My notes</h1>
+  <div editable><p>Type anything here.</p></div>
+  <script src="https://clayjs.com/v1/clay.js"></script>
+</body>
+</html>
+```
+
+Type into it, then open the file in a text editor: your words are in the HTML.
+
+**Something has to write the bytes.** clayjs runs in the browser; it makes the document
+and posts it, and a host puts it on disk. The shortest path is
+[HTML Clay](https://htmlclay.com), a desktop app: rename the file to `.htmlclay` and
+double-click it, and it serves the file at `http://127.0.0.1` and writes every save back.
+[hyperclay.com](https://hyperclay.com) hosts the same file online. Your own server needs
+one route, about twenty lines: see [the endpoint spec](https://clayjs.com/docs#endpoint).
+Full walkthrough: [the tutorial](https://clayjs.com/get-started) and
+[`examples/`](https://github.com/panphora/clayjs/tree/main/examples).
 
 ## Use
 
 ```html
-<script src="https://clayjs.com/clay.js"></script>
+<script src="https://clayjs.com/v1/clay.js"></script>
 ```
 
 The loader detects edit vs view mode and pulls only the modules it needs. Tune it with
 query params on the script URL:
 
 ```html
-<script src="/clay.js?plugins=sync,cms&exclude=indicator"></script>
+<script src="https://clayjs.com/v1/clay.js?plugins=sync,cms&exclude=indicator"></script>
 ```
 
 - `?plugins=` — add optional plugins: `sync`, `cms`, `undo`, `sortable`, `indicator`, `quickcrop`, `upload`, `wire`, `demo`.
   Only `richclay` loads by default, and only in edit mode. `cms` brings `quickcrop` with it, because
   the CMS uses it for `data-hcms-crop` image fields.
 - `?exclude=` — drop a plugin that would otherwise load (a default, or one another plugin pulled in).
-- `?editmode=false` — force view mode (URL param wins over everything below).
-
-## Host attributes
+- `?editmode=false` — force view mode (URL param wins over everything else).
 
-A host can put these on `<html>` in the response it serves. They are ephemeral:
-the host injects them and strips them back out of whatever gets saved, so they
-never reach the file on disk.
-
-- `savetoken="…"` — the per-document save credential. clayjs posts to
-  `/_/save/{token}` and sends no cookies, because the token is the credential.
-  A token also implies edit mode, which is the only such signal a sandboxed
-  document can see. `htmlclaytoken` is the older spelling of the same thing.
-Edit mode is decided in this order: the `?editmode` param, then
-`window.clayEditMode`, then a save token, then the platform's owner cookie.
+Edit mode is decided in this order: the `?editmode` param, then `window.clayEditMode`,
+then a save token stamped on `<html>` by the host, then the platform's owner cookie. Hosts
+and save tokens are covered in [the reference](https://github.com/panphora/clayjs/blob/main/docs/reference.md) and on
+[clayjs.com/docs](https://clayjs.com/docs#editmode).
 
 ## Readiness
 
@@ -48,12 +72,6 @@ await clay.ready;      // or: document.addEventListener("clay:ready", ...)
 clay.save();
 ```
 
-Edit mode exposes `clay.save()` (+ `clay.save.force()`), `clay.getHTML()`, `clay.addDocumentTransform(fn)`,
-`clay.onSnapshot(fn)`, `clay.toggleEditMode()`, `clay.isEditMode`, `clay.isOwner`, `clay.Mutation`,
-`clay.region`, `clay.cacheBust(el)`, plus `clay.undo` / `clay.cms` / `clay.morph` / `clay.RichClay` /
-`clay.quickcrop` when those plugins load. View mode keeps only the always-available members (`toggleEditMode`, `isEditMode`, `isOwner`,
-`Mutation`, `region`, `ready`); edit-only members are simply absent.
-
 ## API
 
 Three tiers. The first two are a promise; the third is not.
@@ -64,55 +82,23 @@ Three tiers. The first two are a promise; the third is not.
 | `clay.*` from a satellite (`clay-ui`, `clay-utils`, `clay-dom`, `clay-events`, `clay-options`, `clay-internals`) | opt-in, one script tag each | stable |
 | anything else under `src/` | reachable by direct import, because `src/` ships | **may change in any release** |
 
-The contract starts at **0.3.0**: no name below changes without a major version.
+The contract starts at **1.0.0**: no name below changes without a major version.
 
 **`clay.js`** — `ready`, `save()`, `save.force()`, `getHTML()`, `addDocumentTransform(fn)`, `onSnapshot(fn)`,
 `toggleEditMode()`, `isEditMode`, `isOwner`, `Mutation`, `region`, `cacheBust(el)`, plus `undo` / `cms` / `morph` /
-`RichClay` / `quickcrop` when those plugins load. View mode keeps only the always-available members, as above.
-
-`addDocumentTransform(fn)` runs your callback over a detached clone whenever the page
-prepares to save AND whenever it checks whether anything changed. Keep it pure and
-repeatable: it is a transform, not a "a save is happening" event.
-
-`quickcrop(file, options)` opens a crop modal over a File or Blob and resolves
-`{ blob, dataURL, width, height }`, or `null` if the person cancels. `aspect` (a number,
-or null for freeform), `type`, `quality`, `maxWidth`/`maxHeight` and `labels.confirm` are
-the options worth knowing. Its modal and injected stylesheet carry `save-remove`, so they
-never reach the saved file.
-
-`region` is the region-policy model: `resolveRegionPolicy`, `isInert`, `skipForPolicy`,
-`strictestPolicy`, the `PERSIST` and `REGION_ATTRS` token constants, and the
-`STRIP_FROM_SAVE`, `FREEZE_SELECTOR` and `STRIP_FROM_COMPARISON` selectors.
-`clay.internals.region` is a different shape, narrower in aim, built for snapshot work.
+`RichClay` / `quickcrop` when those plugins load. View mode keeps only the always-available members
+(`toggleEditMode`, `isEditMode`, `isOwner`, `Mutation`, `region`, `ready`); edit-only members are simply absent.
 
 **Satellites** — one script tag each, and each resolves its own `clay.loaded.*` promise. `clay-ui` adds
 `toast`, `toastPersistent`, `ask`, `confirm`, `tell`, `snippet`, `modal`; `clay-utils` adds `clay.utils`
 (`throttle`, `debounce`, `cookie`, `slugify`, `copyToClipboard`); `clay-internals` adds `clay.internals`,
-below. `clay-events`, `clay-dom`, `clay-options` and `all.js` add HTML attributes and DOM helpers rather
+the low-level surface for code that needs to sit *inside* the save lifecycle rather than call it.
+`clay-events`, `clay-dom`, `clay-options` and `all.js` add HTML attributes and DOM helpers rather
 than members on `clay`.
 
-**`clay.internals`** — the pieces the library builds itself out of, for code that needs to sit inside the
-save lifecycle rather than call it. Lower level than `clay.*` deliberately: it assumes you know the
-lifecycle.
-
-```html
-<script src="https://clayjs.com/clay-internals.js"></script>
-```
-
-- `captureSnapshot()`, `captureForSave()` — the snapshot pipeline, read side.
-  `captureSnapshot` gives you the clone before any stripping; `captureForSave` gives you the
-  bytes a save would send.
-- `addDocumentTransform(fn)` — the same registry as `clay.addDocumentTransform`. Core only
-  publishes that name in edit mode, so reach for this one from a view-mode page or from the
-  satellite with no core loaded.
-- `region.addRegionToken(el, token)`, `region.resolveRegionPolicy(node)`, `region.isInert(node)`,
-  `region.isSnapshotRemoved(el)`, `region.PERSIST`, `region.REGION_ATTRS`, and
-  `region.selectors.stripFromSave` / `.stripFromComparison` / `.stripFromDirtyCheck` /
-  `.noTriggerAutosave` / `.noDirty` / `.snapshotRemove` / `.freeze` — write your own attribute
-  without hardcoding our selectors.
-- `save.saveHtml(html, cb, opts)`, `save.replacePageWith(url, cb)`, `save.isSaveInProgress()` — the save
-  lane under `clay.save`. **`saveHtml` writes the bytes you hand it straight to the file**, bypassing the
-  snapshot pipeline entirely; check `isSaveInProgress()` first.
+Every member, every attribute, and the endpoint spec: **[docs/reference.md](https://github.com/panphora/clayjs/blob/main/docs/reference.md)**,
+also served at [clayjs.com/llms.txt](https://clayjs.com/llms.txt) and rendered as
+[clayjs.com/docs](https://clayjs.com/docs).
 
 ## Regions
 
@@ -133,41 +119,46 @@ and live sync will not overwrite it, while a `no-dirty` region renders itself fr
 so it never warns and an incoming sync frame may replace it. Use `no-dirty` for filter bars,
 projections and drag previews; use `no-trigger-autosave` for a heavy editor you save by hand.
 
+## Repo map
+
+**Everything in `entries/` is served under a version prefix on clayjs.com.**
+`entries/clay.js` is `https://clayjs.com/v1/clay.js`, which rolls forward within major
+version 1, and `https://clayjs.com/1.0.0/clay.js`, which never changes. Same for each
+satellite. A saved document hardcodes its script URL and has no update channel, which is
+why the version is in the URL and why a served path, once published, is permanent. Repo
+paths are not: `build.js` flattens `entries/` into each prefix on the way out. `clay.js`
+derives its own base URL from its script tag and imports `<base>/src/loader.js`, so `src/`
+is public surface too and ships inside every prefix as its sibling.
+
+| | |
+|---|---|
+| `entries/clay.js` | the bootstrap: everything starts here |
+| `entries/clay-ui.js`, `-dom`, `-events`, `-options`, `-utils`, `-internals` | satellites, one script tag each |
+| `entries/all.js` | `All(selector)`, a chainable `querySelectorAll` wrapper |
+| `entries/sap.js` | reactive templating, **generated** from the `sapjs` repo |
+| `entries/clay-data.js` | the HTML data API, **generated** from the `hyper-html-api` repo |
+| `src/` | the implementation, and public surface by direct import |
+| `conformance/` | the byte-exact gate: real browser, pinned Chromium, goldens from the spec |
+| `tests/` | jest unit suite, fixtures, and a stub save server |
+| `website/` | the source of clayjs.com |
+| `docs/reference.md` | the full reference, served as `/llms.txt` |
+| `build.js`, `wrangler.jsonc` | assemble and deploy `public/`, which is a gitignored build output |
+
 ## Develop
 
 ```bash
 npm test                   # jest unit suite
 npm run test:conformance   # byte-for-byte fixture gate, in a real browser
 npm run dev                # stub save server on :4601 for the tests/fixtures pages
+npm run build              # rebuild public/, the deploy output
 ```
 
-## Deploy
-
-`public/` is what wrangler serves to clayjs.com. It is a build output: gitignored,
-disposable, and rebuilt from scratch every time.
-
-```bash
-npm run build    # rebuild public/ from source
-npm run deploy   # rebuild, then wrangler deploy
-```
-
-Never edit `public/` by hand, and never copy a file into it. Its contents are
-**derived**:
-
-```
-public/  =  package.json "files"  (minus THIRD-PARTY-NOTICES.md, which nothing requests)
-         +  website/*             (flattened to the root, so /docs.html works)
-```
-
-That derivation is the point. `files` is the list npm publishes, so it is already
-the line you edit to ship a new satellite, and deriving from it means a file cannot
-reach npm and miss the site. Before this script existed the mirror was hand-copied,
-and it drifted exactly that way: `src/core/host-attrs.js` never made it across, and
-since `loader.js` imports `is-edit-mode.js`, which imports it, the deployed
-`clay.js` could not boot at all.
+Setup, the pinned-browser requirement, and the things about this repo that will surprise
+you are in [CONTRIBUTING.md](https://github.com/panphora/clayjs/blob/main/CONTRIBUTING.md).
 
 ## License
 
 Our code is MIT-0 (MIT No Attribution): use it, remix it, ship it, no attribution
 needed. Vendored third-party files keep their original permissive licenses; see
-[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). Security reports go through
+[the security policy](https://github.com/panphora/clayjs/blob/main/.github/SECURITY.md).

package/THIRD-PARTY-NOTICES.md

@@ -12,15 +12,13 @@ or carry third-party code, and keep their original licenses.
 
 ## Squire 2.4.8 (MIT)
 
-- Carried inside src/vendor/richclay.vendor.js and website/vendor/richclay.min.js
-  (richclay bundles Squire)
+- Carried inside src/vendor/richclay.vendor.js (richclay bundles Squire)
 - Copyright (c) 2011-2023 by Neil Jenkins
 - https://github.com/fastmail/Squire
 
 ## DOMPurify 3.4.11 (Apache-2.0 OR MPL-2.0)
 
-- Carried inside src/vendor/richclay.vendor.js and website/vendor/richclay.min.js
-  (richclay bundles DOMPurify)
+- Carried inside src/vendor/richclay.vendor.js (richclay bundles DOMPurify)
 - (c) Cure53 and other contributors
 - https://github.com/cure53/DOMPurify
 

package/{all.js → entries/all.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   clay.loaded.all = import(base + "/src/dom/all.js")
     .then(function (m) {

package/{clay-dom.js → entries/clay-dom.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   clay.loaded.dom = import(base + "/src/dom/dom-helpers.js")
     .catch(function (err) { console.error("clay-dom failed to load:", err); throw err; });

package/{clay-events.js → entries/clay-events.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   // The mutation-backed attrs subscribe to a hub that observes document.body, so
   // wait for DOM ready before importing (same gate as clay.js).

package/{clay-internals.js → entries/clay-internals.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   // No DOM gate: nothing here touches document.body at import time, unlike clay-ui.
   clay.loaded.internals = import(base + "/src/internals/index.js")

package/{clay-options.js → entries/clay-options.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   // Subscribes to the mutation hub (observes document.body); wait for DOM ready.
   function domReady() {

package/{clay-ui.js → entries/clay-ui.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   // Toasts and dialogs append to document.body, so `loaded.ui` must not resolve
   // before the DOM is ready (same gate as clay-events).

package/{clay-utils.js → entries/clay-utils.js}

@@ -9,7 +9,13 @@
     return;
   }
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // Query and fragment off first, then step out of the tarball's entries/ directory
+  // so package-path CDNs resolve src/. See clay.js for the full reason on both.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
 
   clay.loaded.utils = import(base + "/src/utils/index.js")
     .catch(function (err) { console.error("clay-utils failed to load:", err); throw err; });

package/{clay.js → entries/clay.js}

@@ -31,7 +31,21 @@
   clay.__booted = true;
 
   var url = new URL(script.src, location.href);
-  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  // The query and the fragment come off before the last slash is found. Leaving them
+  // on split the base inside them, so clay.js?next=/a/b imported ".../clay.js?next=/a/src/loader.js"
+  // and the library never booted.
+  var path = url.href.split("#")[0].split("?")[0];
+  var base = path.slice(0, path.lastIndexOf("/"));
+  // In the npm tarball the entry scripts sit in entries/ while src/ stays beside it
+  // at the package root, so a CDN that serves package paths literally (jsDelivr,
+  // unpkg) would look for src/ one directory too deep and load nothing. Stepping out
+  // of an "entries" segment makes those URLs resolve. clayjs.com never has the
+  // segment: build.js flattens entries/ into each version prefix, so this is a no-op
+  // there. The question is asked of the pathname, because asking it of the whole URL
+  // matched a host merely named "entries" and sent the import to another origin.
+  if (url.pathname.slice(0, url.pathname.lastIndexOf("/")).slice(-8) === "/entries") {
+    base = base.slice(0, -8);
+  }
   import(base + "/src/loader.js")
     .then(function (m) { return m.boot(base, url.searchParams, clay.__readyResolve); })
     .catch(function (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "0.7.3",
+  "version": "1.0.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",
@@ -9,18 +9,32 @@
     "type": "git",
     "url": "git+https://github.com/panphora/clayjs.git"
   },
+  "bugs": {
+    "url": "https://github.com/panphora/clayjs/issues"
+  },
+  "keywords": [
+    "html",
+    "self-saving",
+    "malleable",
+    "local-first",
+    "no-build",
+    "contenteditable",
+    "dom",
+    "autosave",
+    "single-file",
+    "static-site",
+    "vanilla-javascript",
+    "html-editor"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./THIRD-PARTY-NOTICES.md": "./THIRD-PARTY-NOTICES.md",
+    "./src/*": "./src/*",
+    "./entries/*": "./entries/*",
+    "./*": "./entries/*"
+  },
   "files": [
-    "clay.js",
-    "clay-ui.js",
-    "clay-internals.js",
-    "clay-events.js",
-    "clay-options.js",
-    "clay-dom.js",
-    "all.js",
-    "clay-utils.js",
-    "sap.js",
-    "clay-data.js",
-    "_headers",
+    "entries/",
     "THIRD-PARTY-NOTICES.md",
     "src/"
   ],
@@ -29,8 +43,8 @@
   },
   "scripts": {
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "test:conformance": "UPDATE_GOLDENS=0 web-test-runner",
-    "conformance:update": "UPDATE_GOLDENS=1 web-test-runner",
+    "test:conformance": "UPDATE_GOLDENS=0 web-test-runner --config conformance/wtr.config.mjs",
+    "conformance:update": "UPDATE_GOLDENS=1 web-test-runner --config conformance/wtr.config.mjs",
     "prepublishOnly": "npm test && npm run test:conformance",
     "dev": "node tests/stub-server.mjs",
     "build": "node build.js",
@@ -49,5 +63,15 @@
     "kind": "lib",
     "status": "active",
     "url": "https://clayjs.com"
+  },
+  "jest": {
+    "testEnvironment": "jsdom",
+    "testMatch": [
+      "**/tests/unit/**/*.test.js"
+    ],
+    "transform": {},
+    "setupFiles": [
+      "<rootDir>/tests/jest.setup.js"
+    ]
   }
 }

package/src/core/autosave.js

@@ -15,6 +15,7 @@ import { isEditMode } from "./is-edit-mode.js";
 import { savePageThrottled } from "./save.js";
 import { markUserDriven } from "../lib/user-gesture.js";
 import { resolveRegionPolicy, skipForPolicy } from "../lib/region-policy.js";
+import { PERSIST, AUTOSAVE } from "../lib/attr-aliases.js";
 
 /**
  * Initialize auto-save on DOM changes
@@ -47,7 +48,7 @@ function initSavePageOnChange() {
 let inputSaveTimer = null;
 function initSaveOnPersistInput() {
   document.addEventListener('input', (e) => {
-    if (!e.target.closest('[persist]')) return;
+    if (!e.target.closest(PERSIST)) return;
     // A trusted input on a [persist] field is itself a user-driven change the
     // Mutation hub can't see (form values aren't DOM mutations). Attribute it,
     // but only when the field is inside the dirty domain: a [persist] control in
@@ -62,7 +63,7 @@ function initSaveOnPersistInput() {
 }
 
 function init() {
-  if (!document.documentElement.hasAttribute("autosave")) return;
+  if (!document.documentElement.matches(AUTOSAVE)) return;
   if (!isEditMode) return;
   // initUserGesture moved to save.js's init: gesture provenance belongs to every
   // editable page, not only the ones with <html autosave>.

package/src/core/persist.js

@@ -1,5 +1,6 @@
 import { onSnapshot } from './snapshot.js';
 import { serializeControlToAttributes, finalizeControlForSave } from '../vendor/control-serialize.vendor.js';
+import { PERSIST } from '../lib/attr-aliases.js';
 
 // Persistent Form Input Values
 //
@@ -51,7 +52,7 @@ import { serializeControlToAttributes, finalizeControlForSave } from '../vendor/
 // When event-attrs is loaded, its cloneNode() intercept (onclone.js) patches
 // data-value into textContent on cloned textareas automatically.
 
-export default function enablePersistentFormInputValues(filterBySelector = "[persist]") {
+export default function enablePersistentFormInputValues(filterBySelector = PERSIST) {
   const inputSelector = `input${filterBySelector}:not([type="password"]):not([type="hidden"]):not([type="file"])`;
   const textareaSelector = `textarea${filterBySelector}`;
   const selectSelector = `select${filterBySelector}`;
@@ -106,7 +107,7 @@ export default function enablePersistentFormInputValues(filterBySelector = "[per
 
 // Auto-initialize with default selector
 export function init() {
-  enablePersistentFormInputValues("[persist]");
+  enablePersistentFormInputValues(PERSIST);
 }
 
 // Auto-init when module is imported

package/src/lib/attr-aliases.js

@@ -0,0 +1,13 @@
+// clayjs spells its attributes without a prefix, which is the whole pitch:
+// <h1 editable> reads like HTML rather than like a framework. No attribute in the
+// HTML standard uses these names and no proposal does either, so the risk of the
+// spelling being taken is small. It is not zero, and a saved document hardcodes
+// the attribute and can never be reached to migrate it.
+//
+// These clay- spellings are read everywhere the bare name is read, and are left
+// out of the documentation on purpose. Their only job is to already exist in every
+// 1.x build: if a bare name ever stops being ours, a file written today can be
+// repaired by adding one attribute instead of needing a migration that cannot
+// reach it. An escape hatch added after the collision would be worthless.
+export const PERSIST = ":is([persist], [clay-persist])";
+export const AUTOSAVE = ":is([autosave], [clay-autosave])";

package/src/lib/dirty-gate.js

@@ -28,13 +28,14 @@
 import Mutation from './mutation.js';
 import { isEditMode } from '../core/is-edit-mode.js';
 import { STRIP_FROM_DIRTY_CHECK, SNAPSHOT_REMOVE_SELECTOR } from './region-policy.js';
+import { PERSIST } from './attr-aliases.js';
 
 let changes = 0;
 let clearedAt = 0;
 let paused = false;
 let started = false;
 
-const PERSIST_CONTROLS = 'input[persist], textarea[persist], select[persist]';
+const PERSIST_CONTROLS = `input${PERSIST}, textarea${PERSIST}, select${PERSIST}`;
 
 // Regions the loss oracle never sees. The hub feed already skips them, through
 // `require: 'dirty'`, and the input feed has to skip them for the same reason:

package/src/plugins/demo.js

@@ -3,7 +3,7 @@
 //
 //   <html autosave demo-key="my-page-v1">          <!-- both attributes optional -->
 //   <script>window.clayEditMode = true;</script>   <!-- before the clay.js tag -->
-//   <script src="https://clayjs.com/clay.js?plugins=demo"></script>
+//   <script src="https://clayjs.com/v1/clay.js?plugins=demo"></script>
 //
 // The fetch shim answers POST /_/save the way a clayjs server would, so the
 // whole real pipeline (savestatus, events, autosave, ⌘S) runs unchanged. The
@@ -112,7 +112,7 @@ async function restore() {
   // attribute, never the element: [contenteditable] cannot join CHROME_SELECTOR,
   // whose matches are removed outright, and doing that deletes real content.
   if (!isEditMode) {
-    for (const el of doc.querySelectorAll("[editable][contenteditable]")) {
+    for (const el of doc.querySelectorAll(":is([editable], [clay-editable])[contenteditable]")) {
       el.removeAttribute("contenteditable");
     }
   }