@panphora/clayjs 1.1.0 → 1.3.0

package/src/core/stale-host-notice.js

@@ -0,0 +1,95 @@
+import { servedStaleToken } from "./host-attrs.js";
+import { isEditMode } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { set, make } from "../lib/hostile-css.js";
+
+// The page's only visible word on a host too old to save to.
+//
+// This library reads one save-token name. A host older than that rename sends the
+// other one, so there is no token here, and it also sets the owner cookie, so without
+// help the page would open fully editable and 404 every save against a route that no
+// longer matches. is-edit-mode.js takes editing away for that reason. This says why.
+//
+// It loads in the ALWAYS wave, not the edit-only one, which is the whole point: the
+// case it exists for is precisely the case where edit mode is off, so a module gated on
+// edit mode could never run in it. host-attrs.js also logs a line, and that line is for
+// a developer. Somebody editing a document in a desktop app has no console open, and
+// "why can I not edit this any more" is the question they are actually holding.
+//
+// One line, no choice to make: nothing on this page can fix it, so offering a button
+// would be a lie. Dismissable, because after you have read it, it is only in the way.
+
+const BG = "var(--clay-notice-bg,#222)";
+const INK = "var(--clay-notice-ink,#fff)";
+const EDGE = "var(--clay-notice-edge,rgba(255,255,255,.28))";
+const FONT = "14px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif";
+
+const MESSAGE =
+  "This page can't be edited: the app serving it is out of date. " +
+  "Update HTML Clay to 1.9.0 or newer.";
+
+let root = null;
+
+// A phone keyboard shrinks the visual viewport but leaves fixed elements pinned to the
+// layout viewport, so a bottom-anchored bar parks itself behind the keyboard. Same fix
+// as the conflict notice.
+function place() {
+  if (!root) return;
+  const vv = window.visualViewport;
+  const lift = vv ? Math.max(0, window.innerHeight - vv.height - vv.offsetTop) : 0;
+  set(root, "bottom", `calc(${16 + lift}px + env(safe-area-inset-bottom,0px))`);
+}
+
+function dismiss() {
+  if (!root) return;
+  set(root, "display", "none");
+  window.visualViewport?.removeEventListener("resize", place);
+  window.visualViewport?.removeEventListener("scroll", place);
+}
+
+function build() {
+  root = make("div", [
+    "position:fixed", "left:50%", "transform:translateX(-50%)",
+    "z-index:2147483001", "display:flex", "align-items:center", "gap:10px",
+    "max-width:calc(100vw - 24px)", "flex-wrap:wrap", "justify-content:center",
+    "padding:9px 12px", "border-radius:10px",
+    `background:${BG}`, `color:${INK}`, `border:1px solid ${EDGE}`,
+    "box-shadow:0 6px 24px rgba(0,0,0,.32),0 1px 2px rgba(0,0,0,.24)",
+    `font:${FONT}`, "text-align:left",
+  ]);
+  // Three markers, and each is load-bearing on a page that CAN save: this element is
+  // injected, so it is in no document on disk and must never reach one, never wake the
+  // watcher, and never ride out in a snapshot to somebody else's browser.
+  root.setAttribute("clay", "no-save no-watch no-snapshot");
+  root.setAttribute("data-clay-stale-host", "");
+  root.setAttribute("role", "alert");
+
+  root.append(make("span", ["margin-right:2px"], MESSAGE));
+
+  const close = make("button", [
+    "all:initial", "box-sizing:border-box", "cursor:pointer", `font:${FONT}`,
+    "color:" + INK, "opacity:.72", "padding:2px 6px", "border-radius:6px", "flex:none",
+  ], "Dismiss");
+  close.type = "button";
+  close.setAttribute("aria-label", "Dismiss this message");
+  close.addEventListener("click", dismiss);
+  root.append(close);
+
+  document.body.appendChild(root);
+  place();
+  window.visualViewport?.addEventListener("resize", place);
+  window.visualViewport?.addEventListener("scroll", place);
+}
+
+function init() {
+  if (!servedStaleToken()) return;
+  // ?editmode=true outranks the stale-host check by design: that is a person at the
+  // keyboard asking for editing on this load, and is-edit-mode.js gives it to them.
+  // This notice never consulted that, so it appeared on a page that IS editable and
+  // told its reader the opposite. The message is only true while editing is actually
+  // off, so it is shown only then.
+  if (isEditMode) return;
+  build();
+}
+
+onDomReady(init);

package/src/core/unsaved-warning.js

@@ -31,6 +31,9 @@ preloadIfEnabled();
 // the person editing it deserves the warning.
 window.addEventListener('beforeunload', (event) => {
   if (!isEditMode) return;
+  // The demo plugin saves into this browser's own storage, so leaving the page
+  // loses nothing a prompt could protect.
+  if (window.clay?.demo) return;
 
   // The DIRTY domain, not the autosave domain. An edit inside a
   // no-trigger-autosave region never starts a save by itself, which is exactly

package/src/dom/dom-helpers.js

@@ -1,8 +1,12 @@
 import nearest from "./nearest.js";
 import pipe from "./pipe.js";
+import { createContentView, cleanContentClone } from '../lib/content-dom.js';
 
 function init () {
 
+  window.clay = window.clay || {};
+  window.clay.dom = Object.assign(window.clay.dom || {}, { createContentView, cleanContentClone });
+
   // Bail if already initialized
   if (HTMLElement.prototype.hasOwnProperty('nearest')) {
     return;
@@ -214,5 +218,5 @@ function init () {
 // Auto-init when module is imported
 init();
 
-export { init };
+export { init, createContentView, cleanContentClone };
 export default init;

package/src/lib/content-dom.js

@@ -0,0 +1,108 @@
+import { capabilitySelector, hasCapability } from './region-capabilities.js'
+
+const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visited|defined)\b/i
+
+function copyControlState(source, copy) {
+  if (!/^(INPUT|TEXTAREA|SELECT|OPTION)$/.test(source.tagName || '')) return
+  const type = (source.getAttribute?.('type') || '').toLowerCase()
+  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio') copy.value = source.value
+  if ('checked' in source && 'checked' in copy) copy.checked = source.checked
+  if ('selected' in source && 'selected' in copy) copy.selected = source.selected
+  if (source.tagName === 'SELECT') {
+    for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
+  }
+  if ('indeterminate' in source && 'indeterminate' in copy) copy.indeterminate = source.indeterminate
+}
+
+function matchesWithin(node, selector, boundary, inherit) {
+  if (inherit) return !!node.closest?.(selector)
+  let current = node
+  while (current?.nodeType === 1) {
+    if (current.matches(selector)) return true
+    if (current === boundary) break
+    current = current.parentElement
+  }
+  return false
+}
+
+function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
+  if (source.nodeType === 1 && (
+    (inherit ? hasCapability(source, capability) : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    (exclude && matchesWithin(source, exclude, boundary, inherit))
+  )) return null
+  const copy = targetDocument.importNode(source, false)
+  maps.cloneToLive.set(copy, source)
+  maps.liveToClone.set(source, copy)
+  const sourceChildren = source.nodeType === 1 && source.tagName === 'TEMPLATE' ? source.content : source
+  const copyChildren = copy.nodeType === 1 && copy.tagName === 'TEMPLATE' ? copy.content : copy
+  if (sourceChildren !== source) {
+    maps.cloneToLive.set(copyChildren, sourceChildren)
+    maps.liveToClone.set(sourceChildren, copyChildren)
+  }
+  for (const child of sourceChildren.childNodes || []) {
+    const childCopy = importTree(child, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps)
+    if (childCopy) {
+      copyChildren.appendChild(childCopy)
+      if (child.nodeType === 1) copyControlState(child, childCopy)
+    }
+  }
+  if (source.nodeType === 1) copyControlState(source, copy)
+  return copy
+}
+
+export function createContentView(context, { capability = 'data', exclude = null, inherit = true } = {}) {
+  if (!context) throw new TypeError('createContentView requires a DOM context')
+  const sourceDocument = context.nodeType === 9 ? context : context.ownerDocument
+  if (!sourceDocument?.implementation?.createHTMLDocument) {
+    throw new TypeError('createContentView requires an HTML DOM implementation')
+  }
+  const inertDocument = sourceDocument.implementation.createHTMLDocument('')
+  const cloneToLive = new WeakMap()
+  const liveToClone = new WeakMap()
+  const sourceRoot = context.nodeType === 9 ? context.documentElement : context
+  if (exclude) inertDocument.documentElement.matches(exclude)
+  const capabilityMatch = capabilitySelector(capability)
+  const root = importTree(sourceRoot, inertDocument, capability, capabilityMatch, exclude, sourceRoot, inherit, { cloneToLive, liveToClone })
+  if (context.nodeType === 9 && root) {
+    inertDocument.replaceChild(root, inertDocument.documentElement)
+    liveToClone.set(context, inertDocument)
+    cloneToLive.set(inertDocument, context)
+  }
+
+  const assertSelector = selector => {
+    if (UNSUPPORTED_SELECTOR.test(selector)) {
+      throw new Error(`Filtered content queries do not support stateful selector: ${selector}`)
+    }
+  }
+
+  return {
+    root,
+    document: inertDocument,
+    capability,
+    selector: capabilitySelector(capability),
+    cloneToLive,
+    liveToClone,
+    original(node) { return cloneToLive.get(node) || null },
+    cloneOf(node) { return liveToClone.get(node) || null },
+    query(selector, queryRoot = root) {
+      assertSelector(selector)
+      return Array.from(queryRoot.querySelectorAll(selector), node => cloneToLive.get(node) || node)
+    },
+    text(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.textContent || ''
+    },
+    html(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.innerHTML ?? ''
+    },
+    clone(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected ? inertDocument.importNode(projected, true) : null
+    },
+  }
+}
+
+export function cleanContentClone(node, options) {
+  return createContentView(node, options).root
+}

package/src/lib/hostile-css.js

@@ -0,0 +1,49 @@
+// Styling that survives somebody else's stylesheet.
+//
+// Every declaration goes on as !important, and that is the whole reason anything this
+// library draws on a stranger's page looks the way it was written. A plain inline style
+// loses to an author rule carrying !important, and `button { ... !important }` is a
+// thing real pages do: the first browser run of the conflict notice had both of its
+// controls repainted in the host page's colours and font. Only an inline !important
+// outranks an author !important.
+
+/**
+ * Apply `prop:value` rules to an element, each one !important.
+ * @param {Element} el
+ * @param {string[]} rules
+ */
+export function style(el, rules) {
+  for (const rule of rules) {
+    const at = rule.indexOf(":");
+    el.style.setProperty(rule.slice(0, at).trim(), rule.slice(at + 1).trim(), "important");
+  }
+}
+
+/**
+ * Set one property, !important.
+ *
+ * Same reason as above, from the other direction: a later assignment has to be able to
+ * beat the !important already sitting on the element, and a plain `el.style.foo = x`
+ * silently cannot.
+ *
+ * @param {Element} el
+ * @param {string} prop
+ * @param {string} value
+ */
+export function set(el, prop, value) {
+  el.style.setProperty(prop, value, "important");
+}
+
+/**
+ * Build an element with those rules already on it.
+ * @param {string} tag
+ * @param {string[]} rules
+ * @param {string} [text]
+ * @returns {HTMLElement}
+ */
+export function make(tag, rules, text) {
+  const el = document.createElement(tag);
+  style(el, rules);
+  if (text) el.textContent = text;
+  return el;
+}

package/src/lib/mutation.js

@@ -68,6 +68,7 @@
 
 import { EXTENSION_ATTR_PATTERN } from './extension-noise.js';
 import { resolveRegionPolicy, isInert, strictestPolicy, skipForPolicy } from './region-policy.js';
+import { isPolicyAttribute } from './region-capabilities.js';
 import { ROOT_LIBRARY_ATTRS } from './root-attrs.js';
 
 import { isUserDrivenNow, markUserDriven } from './user-gesture.js';
@@ -186,7 +187,12 @@ const localMutation = {
       // doesn't participate in (no-save / no-trigger-autosave / no-undo / freeze
       // and their legacy equivalents), resolved against the callback's `require`.
       let filteredChanges = changes.filter(
-        change => !skipForPolicy(this._policyForChange(change), require, skip)
+        change => {
+          const currentSkipped = skipForPolicy(this._policyForChange(change), require, skip);
+          if (!change.policyTransition) return !currentSkipped;
+          const previousSkipped = skipForPolicy(change.previousPolicy, require, skip);
+          return !(currentSkipped && previousSkipped);
+        }
       );
       if (!filteredChanges.length) {
         this._log('No changes passed the region policy, skipping callback');
@@ -478,7 +484,8 @@ const localMutation = {
       // Intake drop: a no-watch / mutations-ignore subtree (or extension noise)
       // is invisible to every consumer, so skip it without walking. All other
       // region attributes are resolved per-consumer in _notify.
-      if (isInert(mutation.target)) {
+      const policyTransition = mutation.type === 'attributes' && isPolicyAttribute(mutation.attributeName);
+      if (!policyTransition && isInert(mutation.target)) {
         continue;
       }
 
@@ -586,7 +593,9 @@ const localMutation = {
           element: mutation.target,
           attribute: mutation.attributeName,
           oldValue: mutation.oldValue,
-          newValue: mutation.target.getAttribute(mutation.attributeName)
+          newValue: mutation.target.getAttribute(mutation.attributeName),
+          policyTransition,
+          previousPolicy: policyTransition ? policyBeforeMutation(mutation) : null,
         };
         changes.push(change);
         changesByType.attribute.push(change);
@@ -783,3 +792,17 @@ if (typeof window !== 'undefined' && !existingHub) {
 }
 
 export default Mutation;
+function policyBeforeMutation(record) {
+  let source = record.target;
+  let clone = source.cloneNode(false);
+  const leaf = clone;
+  while (source.parentElement) {
+    source = source.parentElement;
+    const parent = source.cloneNode(false);
+    parent.appendChild(clone);
+    clone = parent;
+  }
+  if (record.oldValue == null) leaf.removeAttribute(record.attributeName);
+  else leaf.setAttribute(record.attributeName, record.oldValue);
+  return resolveRegionPolicy(leaf);
+}

package/src/lib/region-capabilities.js

@@ -0,0 +1,69 @@
+export const CAPABILITIES = Object.freeze({
+  data: Object.freeze({ tokens: ['no-data'], bundles: ['editor-ui'] }),
+  save: Object.freeze({ tokens: ['no-save'], bundles: ['editor-ui'] }),
+  snapshot: Object.freeze({ tokens: ['no-snapshot'], bundles: ['editor-ui'] }),
+  watch: Object.freeze({ tokens: ['no-watch'], bundles: ['editor-ui'] }),
+  undo: Object.freeze({ tokens: ['no-undo'], bundles: ['editor-ui'] }),
+  history: Object.freeze({ tokens: [], bundles: ['editor-ui'] }),
+})
+
+export const BUNDLES = Object.freeze({
+  'editor-ui': Object.freeze(['no-data', 'no-save', 'no-snapshot', 'no-watch', 'no-undo']),
+})
+
+export const POLICY_TOKENS = Object.freeze([
+  'no-save',
+  'no-snapshot',
+  'no-trigger-autosave',
+  'no-dirty',
+  'no-watch',
+  'no-undo',
+  'no-data',
+  'freeze',
+  'editor-ui',
+])
+
+export function hasPolicyToken(element, token) {
+  if (!element || element.nodeType !== 1) return false
+  const clay = element.getAttribute?.('clay')
+  return !!(
+    (clay && clay.split(/\s+/).includes(token)) ||
+    element.hasAttribute?.(token)
+  )
+}
+
+export function expandsTo(element, token) {
+  if (hasPolicyToken(element, token)) return true
+  for (const [bundle, members] of Object.entries(BUNDLES)) {
+    if (members.includes(token) && hasPolicyToken(element, bundle)) return true
+  }
+  return false
+}
+
+export function capabilitySelector(capability) {
+  const definition = CAPABILITIES[capability]
+  if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+  return [...definition.tokens, ...definition.bundles]
+    .flatMap(token => [`[clay~="${token}"]`, `[${token}]`])
+    .join(', ')
+}
+
+export function closestWithCapability(node, capability) {
+  let element = node && node.nodeType === 1 ? node : node?.parentElement
+  while (element && element.nodeType === 1) {
+    const definition = CAPABILITIES[capability]
+    if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+    if (definition.tokens.some(token => expandsTo(element, token)) ||
+        definition.bundles.some(bundle => hasPolicyToken(element, bundle))) return element
+    element = element.parentElement
+  }
+  return null
+}
+
+export function hasCapability(node, capability) {
+  return !!closestWithCapability(node, capability)
+}
+
+export function isPolicyAttribute(name) {
+  return name === 'clay' || POLICY_TOKENS.includes(name)
+}

package/src/lib/region-policy.js

@@ -44,24 +44,21 @@
  */
 
 import { EXTENSION_NODE_SELECTOR } from './extension-noise.js';
+import { capabilitySelector, expandsTo, hasCapability, hasPolicyToken, POLICY_TOKENS } from './region-capabilities.js';
 
 export const PERSIST = { FULL: 'full', FROZEN: 'frozen', NONE: 'none' };
 
 // The canonical region tokens (spelled in the `clay` attribute or as bare attrs).
-export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'freeze'];
+export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'no-data', 'freeze', 'editor-ui'];
 
 // Every canonical token spellable inside the space-separated `clay` attribute.
 // Exported: this list used to exist as a private CLAY_TOKENS that nothing read,
 // while callers hardcoded their own copies.
-export const TOKENS = ["no-save", "no-snapshot", "no-trigger-autosave", "no-dirty", "no-watch", "no-undo", "freeze"];
+export const TOKENS = [...POLICY_TOKENS];
 
 // True when a region marker is present, whether spelled as a `clay` token
 // (whitespace-token semantics, matching [clay~=token]) or a legacy bare attribute.
-function hasRegionToken(el, token) {
-  const clay = el.getAttribute?.("clay");
-  if (clay && clay.split(/\s+/).includes(token)) return true;   // whitespace-token semantics, matches [clay~=…]
-  return !!el.hasAttribute?.(token);                            // legacy bare attribute
-}
+const hasRegionToken = hasPolicyToken;
 
 /**
  * Add a canonical region token to an element's `clay` attribute, preserving any
@@ -79,7 +76,7 @@ export function addRegionToken(el, token) {
 }
 
 // Serializer selectors (recognize the clay-token spelling FIRST, then new + legacy bare).
-export const STRIP_FROM_SAVE = '[clay~="no-save"], [no-save], [save-remove]';
+export const STRIP_FROM_SAVE = `${capabilitySelector('save')}, [save-remove]`;
 export const FREEZE_SELECTOR = '[clay~="freeze"], [freeze], [save-freeze]';
 // forComparison additionally strips every region whose autosave-trigger is off,
 // so their churn never marks the page dirty — including the no-watch /
@@ -117,7 +114,8 @@ export const STRIP_FROM_DIRTY_CHECK =
 // dirty-comparison) in snapshot.js. `no-snapshot` is the consistent alias for the
 // original `snapshot-remove`; hyper-morph treats both as sync-ignored so a
 // live-sync receiver keeps its own local copy instead of deleting it.
-export const SNAPSHOT_REMOVE_SELECTOR = '[clay~="no-snapshot"], [snapshot-remove], [no-snapshot]';
+export const SNAPSHOT_REMOVE_SELECTOR = `${capabilitySelector('snapshot')}, [snapshot-remove]`;
+export const NO_DATA_SELECTOR = capabilitySelector('data');
 
 // Ancestor-aware, because the strip removes a marked element together with its
 // whole subtree: a child of a no-snapshot region is just as absent from every
@@ -128,6 +126,10 @@ export function isSnapshotRemoved(node) {
   return !!(element && element.closest && element.closest(SNAPSHOT_REMOVE_SELECTOR));
 }
 
+export function isDataExcluded(node) {
+  return hasCapability(node, 'data');
+}
+
 const PERSIST_RANK = { full: 0, frozen: 1, none: 2 };
 const RANK_PERSIST = ['full', 'frozen', 'none'];
 
@@ -158,11 +160,11 @@ export function resolveRegionPolicy(node) {
   while (element && element.nodeType === 1) {
     if (element.hasAttribute) {
       // new naked attributes
-      if (hasRegionToken(element, 'no-watch')) watched = false;
+      if (expandsTo(element, 'no-watch')) watched = false;
       if (hasRegionToken(element, 'no-trigger-autosave')) autosaveOff = true;
       if (hasRegionToken(element, 'no-dirty')) { autosaveOff = true; dirtyOff = true; }
-      if (hasRegionToken(element, 'no-undo')) undoable = false;
-      if (hasRegionToken(element, 'no-save')) persistRank = Math.max(persistRank, PERSIST_RANK.none);
+      if (expandsTo(element, 'no-undo')) undoable = false;
+      if (expandsTo(element, 'no-save')) persistRank = Math.max(persistRank, PERSIST_RANK.none);
       if (hasRegionToken(element, 'freeze')) persistRank = Math.max(persistRank, PERSIST_RANK.frozen);
       // legacy markers -> bundles
       if (hasRegionToken(element, 'mutations-ignore')) watched = false;
@@ -209,7 +211,7 @@ export function isInert(node) {
   if (element && element.closest && element.closest(EXTENSION_NODE_SELECTOR)) return true;
   while (element && element.nodeType === 1) {
     if (element.hasAttribute &&
-        (hasRegionToken(element, 'no-watch') || hasRegionToken(element, 'mutations-ignore'))) {
+        (expandsTo(element, 'no-watch') || hasRegionToken(element, 'mutations-ignore'))) {
       return true;
     }
     element = element.parentElement;
@@ -283,6 +285,7 @@ export const regionShape = {
   resolveRegionPolicy,
   isInert,
   isSnapshotRemoved,
+  isDataExcluded,
   skipForPolicy,
   strictestPolicy,
   addRegionToken,
@@ -297,6 +300,7 @@ export const regionShape = {
   NO_TRIGGER_AUTOSAVE_SELECTOR,
   NO_DIRTY_SELECTOR,
   SNAPSHOT_REMOVE_SELECTOR,
+  NO_DATA_SELECTOR,
   FREEZE_SELECTOR,
 
   // Nested camelCase: what clay.internals.region has always published.
@@ -307,6 +311,7 @@ export const regionShape = {
     noTriggerAutosave: NO_TRIGGER_AUTOSAVE_SELECTOR,
     noDirty: NO_DIRTY_SELECTOR,
     snapshotRemove: SNAPSHOT_REMOVE_SELECTOR,
+    noData: NO_DATA_SELECTOR,
     freeze: FREEZE_SELECTOR,
   },
 };

package/src/lib/root-attrs.js

@@ -8,31 +8,70 @@
  * peer's copy of them must never be applied.
  */
 
-// The two spellings of the save token. Spec §9 bounds one to per-file and per-tab
-// and makes the host strip it before writing, so it never reaches disk. But §9
-// bounds only the save path, and §10 fans a snapshot out to other editors'
+// The save token, in the order a reader tries the two spellings. Spec §9 bounds it to
+// per-file and per-tab and makes the host strip it before writing, so it never reaches
+// disk. But §9 bounds only the save path, and §10 fans a snapshot out to other editors'
 // browsers, which is the hole this module closes.
 //
 // Save tokens ONLY. host-attrs.js returns the first name it finds here and puts it
 // straight into the save URL, so anything added to this list becomes a credential
-// in a path. Durable identities go in the list below, never in this one.
-export const SAVE_TOKEN_ATTRS = ["savetoken", "htmlclaytoken"];
+// in a path. Durable identities go in HOST_IDENTITY_ATTRS, never in this one.
+//
+// One name, deliberately. §9 names exactly one save-token attribute.
+//
+// This is a knowing break, not an oversight. htmlclay is the only host that mints a save
+// token at all (hyperclay and Hyperclay Local authorize by cookie and inject nothing),
+// it serves both spellings only from 1.9.0, and a document loads this library from a
+// rolling URL. So a document served by an htmlclay at or below 1.8.0 keeps edit mode,
+// because that host also sets the isAdminOfCurrentResource cookie, and every save 404s,
+// because that host registers only `POST /_/save/{token}`.
+//
+// Taken on purpose, and taken now because the cost only grows: htmlclay 1.8.0 is days
+// old, the product is pre-launch, and the alternative is carrying a second credential
+// name in the save path permanently, since "wait until the old hosts are gone" is a
+// condition nobody ever measures. host-attrs.js says so plainly in the console when it
+// finds the old name, so the failure names its own cause and its own fix.
+//
+// ⚠️ RELEASE ORDER: htmlclay 1.9.0, which injects both names, must publish BEFORE this.
+export const SAVE_TOKEN_ATTRS = ["savetoken"];
+
+// The pre-rename spelling. Never read as a credential, which is the point of it being
+// here rather than above, and never removed from HOST_TOKEN_ATTRS below, which is a
+// different job: a name a host may inject has to go on being stripped before a save and
+// kept out of a peer's morph, or a live token gets written into a document or handed to
+// another tab. htmlclay injects it forever, because documents frozen against an older
+// client read it, so this name never leaves this file.
+export const LEGACY_SAVE_TOKEN_ATTRS = ["htmlclaytoken"];
 
-// Host-injected, but NOT credentials. htmlclayid is htmlclay's durable file
-// identity, stamped on every serve and absent from disk bytes, so it rides in the
-// morph protection below for the same reason a token does: a morph of raw disk
-// content would otherwise strip this tab's copy, and a peer's copy must never be
-// applied.
+// Host-injected, but NOT credentials. This is htmlclay's durable file identity,
+// stamped on every serve and absent from disk bytes, so it rides in the morph
+// protection below for the same reason a token does: a morph of raw disk content
+// would otherwise strip this tab's copy, and a peer's copy must never be applied.
+//
+// Two spellings, permanently, mirroring the token list above. htmlclay serves
+// `documentid` and reads either, but a document saved before that rename holds
+// `htmlclayid` on disk forever, and this list is what a morph consults. Knowing
+// only the current name would leave every pre-rename file's identity unprotected,
+// which is the failure this list exists to prevent.
 //
 // It was previously in the token list, where saveToken() returned it whenever a
 // host minted no token of its own. That is reachable: htmlclay stamps the id on
 // every serve but injects a token only for top-level document loads, and its save
 // route strips only the token, so the id reaches disk. Any such file hosted
 // somewhere tokenless made this library POST to /_/save/{id} with no cookie and
-// hand edit mode to every visitor.
-export const HOST_IDENTITY_ATTRS = ["htmlclayid"];
+// hand edit mode to every visitor. Splitting this list off from the token list is
+// what fixed that, and the split holds whatever token spellings are read above.
+export const HOST_IDENTITY_ATTRS = ["documentid", "htmlclayid"];
 
-export const HOST_TOKEN_ATTRS = [...SAVE_TOKEN_ATTRS, ...HOST_IDENTITY_ATTRS];
+// What a host may have injected, and therefore what has to be stripped before a save
+// and kept out of an incoming morph. Wider than what is READ, on purpose: the old token
+// spelling is still injected by every htmlclay, so it still has to be stripped, whether
+// or not this library will accept it as a credential.
+export const HOST_TOKEN_ATTRS = [
+  ...SAVE_TOKEN_ATTRS,
+  ...LEGACY_SAVE_TOKEN_ATTRS,
+  ...HOST_IDENTITY_ATTRS,
+];
 
 // This library's own root state, and this tab's UI truth.
 export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];