@panphora/clayjs 0.6.0 → 0.7.0

package/src/lib/authored-url.js

@@ -0,0 +1,96 @@
+/**
+ * authored-url.js — keeping a runtime URL rewrite out of the saved file.
+ *
+ * cacheBust and refetch-on-save both rewrite an href/src after a save, so the
+ * browser re-fetches the asset. That write lands AFTER the save baseline was
+ * taken, so without help it reads as an edit the person made: the page goes
+ * dirty the instant a save succeeds, warns on close about work that was already
+ * written, and on an autosave page saves again immediately.
+ *
+ * The old answer stamped the element `no-trigger-autosave` on the way past. It
+ * worked only from the SECOND save on — the baseline already held the element
+ * unmarked, so the first comparison stripped something the baseline contained
+ * and the page read dirty anyway. It also spent a region marker, which changes
+ * how undo, autosave and live-sync treat that subtree forever, to paper over a
+ * serialization problem.
+ *
+ * This fixes the bytes instead. Remember what the URL was authored as, restore
+ * it on every snapshot clone, and leave the region model alone. The live DOM
+ * keeps the busted URL, the file keeps the authored one, and no comparison ever
+ * sees a difference.
+ */
+
+const AUTHORED = 'clay-authored-url';
+const RUNTIME = 'clay-runtime-url';
+const ATTR = 'clay-url-attr';
+const SUPERSEDED = 'clay-superseded';
+
+// Every attribute this module owns. They live on the live element and are
+// stripped from every clone, so none of them ever reaches the file.
+const OWNED = [AUTHORED, RUNTIME, ATTR, SUPERSEDED];
+
+/** Which attribute carries this element's URL, matching both call sites' rule. */
+export function urlAttrFor(el) {
+  return el.hasAttribute('href') ? 'href' : el.hasAttribute('src') ? 'src' : null;
+}
+
+/**
+ * Write a clay-generated URL to the live DOM, remembering the authored one.
+ *
+ * Record-if-absent is the important part. A second cache-bust must not record
+ * the first bust's output as the authored value, or the file accumulates `?v=`
+ * stamps and the restore puts back a stale URL. It also makes the two helpers
+ * compose: when refetch clones an element cacheBust already touched, the clone
+ * carries the original authored value and keeps it.
+ */
+export function writeRuntimeUrl(el, attr, value) {
+  if (!el.hasAttribute(AUTHORED)) {
+    el.setAttribute(AUTHORED, el.getAttribute(attr) ?? '');
+    el.setAttribute(ATTR, attr);
+  }
+  el.setAttribute(attr, value);
+  el.setAttribute(RUNTIME, value);
+}
+
+/**
+ * Mark an element that a replacement has been inserted next to.
+ *
+ * refetch-on-save leaves the old element in the DOM until the new one loads, so
+ * for up to two seconds the page holds both. Every snapshot taken in that window
+ * must serialize exactly one, or a capture differs from the baseline by a whole
+ * duplicated element.
+ */
+export function markSuperseded(el) {
+  el.setAttribute(SUPERSEDED, '');
+}
+
+export function isSuperseded(el) {
+  return el.hasAttribute(SUPERSEDED);
+}
+
+/**
+ * Restore authored URLs on a snapshot clone and drop every attribute this
+ * module owns. Runs inside captureSnapshot, so it reaches the save clone, both
+ * comparison clones, and the live-sync broadcast alike.
+ */
+export function restoreAuthoredUrls(clone) {
+  for (const el of clone.querySelectorAll(`[${SUPERSEDED}]`)) {
+    el.remove();
+  }
+
+  for (const el of clone.querySelectorAll(`[${AUTHORED}]`)) {
+    const attr = el.getAttribute(ATTR);
+    const authored = el.getAttribute(AUTHORED);
+    const runtime = el.getAttribute(RUNTIME);
+
+    // Restore only while the live value is still the one clay wrote. If the page
+    // has changed it since, that is a real authored edit: restoring would
+    // discard it silently, and keep discarding it on every save afterwards.
+    if (attr && el.getAttribute(attr) === runtime) {
+      if (authored) el.setAttribute(attr, authored);
+      else el.removeAttribute(attr);
+    }
+
+    for (const name of OWNED) el.removeAttribute(name);
+  }
+}

package/src/lib/cache-bust.js

@@ -1,22 +1,26 @@
 // cacheBust.js
 // Cache-bust an element's href or src attribute by adding/updating a version query param
 
-import { addRegionToken } from './region-policy.js';
+import Mutation from './mutation.js';
+import { urlAttrFor, writeRuntimeUrl } from './authored-url.js';
 
 function cacheBust(el) {
-  const attr = el.hasAttribute('href') ? 'href' : 'src';
-  const currentValue = el.getAttribute(attr);
-  const url = new URL(currentValue, location.href);
+  const attr = urlAttrFor(el);
+  if (!attr) return;
+
+  const url = new URL(el.getAttribute(attr), location.href);
   url.searchParams.set('v', Date.now());
-  el.setAttribute(attr, url.href);
 
-  // This runs from [onaftersave], i.e. after the save baseline was taken, so the
-  // rewrite would otherwise read as a user edit and leave the page dirty forever.
-  // Marking the element instead of re-reading the whole live DOM afterwards is what
-  // lets the baseline stay equal to the bytes actually sent: a post-save re-read
-  // cannot tell this rewrite apart from something the user typed mid-save, and used
-  // to record the latter as saved without sending it.
-  addRegionToken(el, 'no-trigger-autosave');
+  // Paused because this is clay writing, not the person editing: it must not
+  // schedule an autosave. Keeping it out of the SAVED FILE is a separate job,
+  // done by remembering the authored URL and restoring it on every snapshot
+  // clone (see authored-url.js) rather than by marking the region.
+  Mutation.pause();
+  try {
+    writeRuntimeUrl(el, attr, url.href);
+  } finally {
+    Mutation.resume();
+  }
 }
 
 export default cacheBust;

package/src/lib/dirty-gate.js

@@ -8,7 +8,7 @@
  * a false "clean" full-morphs over a real unsaved edit.
  *
  * Two feeds, because neither alone sees everything:
- *   - the mutation hub (require: 'autosave'), which sees DOM changes but not
+ *   - the mutation hub (require: 'dirty'), which sees DOM changes but not
  *     value-property writes on form controls (typing fires no MutationRecord
  *     for .value), and
  *   - capture-phase input/change listeners on ALL form controls, not just
@@ -27,7 +27,7 @@
 
 import Mutation from './mutation.js';
 import { isEditMode } from '../core/is-edit-mode.js';
-import { STRIP_FROM_COMPARISON, SNAPSHOT_REMOVE_SELECTOR } from './region-policy.js';
+import { STRIP_FROM_DIRTY_CHECK, SNAPSHOT_REMOVE_SELECTOR } from './region-policy.js';
 
 let changes = 0;
 let clearedAt = 0;
@@ -36,13 +36,18 @@ let started = false;
 
 const PERSIST_CONTROLS = 'input[persist], textarea[persist], select[persist]';
 
-// Regions the comparison never sees. The hub feed already skips them, through
-// `require: 'autosave'`, and the input feed has to skip them for the same
-// reason: their content is stripped from the comparison clone, so an edit inside
+// 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:
+// their content is stripped from the merge's compare clone, so an edit inside
 // one can never produce a dirty root, and counting it marks the page dirty with
 // nothing for the oracle to find — permanently, since only a save clears the
 // counter and churn in these regions triggers none.
 //
+// The gate and the oracle must key off the SAME domain. This is the dirty
+// domain, so no-trigger-autosave is deliberately absent: the oracle can now
+// report an unsaved batching edit, so the gate has to arm for one. Disposable
+// churn leaves via no-dirty, which is in both.
+//
 // This is not a relaxation of "never under-report". A control here is absent
 // from the clone by definition, so there is nothing about it to under-report.
 // It matters because a mounted tool (redpen's answer field, any panel that
@@ -50,9 +55,22 @@ const PERSIST_CONTROLS = 'input[persist], textarea[persist], select[persist]';
 // it used to freeze the live-sync save baseline for the rest of the session,
 // after which every incoming disk change was diffed against a stale base, and
 // the previous change was spliced back over the newer one and written to disk.
-const GATE_IGNORE = `${STRIP_FROM_COMPARISON}, ${SNAPSHOT_REMOVE_SELECTOR}`;
+const GATE_IGNORE = `${STRIP_FROM_DIRTY_CHECK}, ${SNAPSHOT_REMOVE_SELECTOR}`;
 const probeCache = new WeakMap();
 
+// The [persist] probe has to honour GATE_IGNORE too. It scans by attribute, not
+// through the mutation hub, so without this a programmatic .value write inside a
+// no-dirty region pins the gate dirty forever even though every DOM mutation
+// there is ignored — the one hole that would survive the domain switch.
+function gatedPersistControls() {
+  const out = [];
+  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+    if (el.closest(GATE_IGNORE)) continue;
+    out.push(el);
+  }
+  return out;
+}
+
 function onUserInput(event) {
   // Deliberately NOT gated on `paused`: a morph never dispatches input or
   // change events, so anything arriving here is the user — including typing
@@ -68,7 +86,7 @@ export function startDirtyGate() {
   if (started) return;
   started = true;
   Mutation.onAnyChange(
-    { omitChangeDetails: true, require: 'autosave' },
+    { omitChangeDetails: true, require: 'dirty' },
     () => {
       if (!paused) changes++;
     }
@@ -115,7 +133,7 @@ function serializedStateMatches(el) {
 }
 
 export function persistProbeDirty() {
-  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+  for (const el of gatedPersistControls()) {
     const sig = controlSignature(el);
     if (probeCache.get(el) === sig) continue;
     if (serializedStateMatches(el)) {
@@ -129,7 +147,7 @@ export function persistProbeDirty() {
 
 /** Call after the oracle verified the whole page clean against its baseline. */
 export function probeMarkClean() {
-  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+  for (const el of gatedPersistControls()) {
     probeCache.set(el, controlSignature(el));
   }
 }
@@ -145,7 +163,7 @@ export function pageMaybeDirty() {
  */
 export function gateCaptureToken() {
   const probe = [];
-  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+  for (const el of gatedPersistControls()) {
     probe.push([el, controlSignature(el)]);
   }
   return { gen: changes, probe };

package/src/lib/mutation.js

@@ -604,12 +604,14 @@ const localMutation = {
       });
 
       // Data-guard provenance: if a trusted gesture drove this turn (or one
-      // happened within the recency window) and any change is autosave-relevant
-      // (matches the save's region scope), mark the pending save user-driven.
+      // happened within the recency window) and any change is dirty-relevant
+      // (i.e. it reaches the saved bytes), mark the pending save user-driven.
+      // The DIRTY domain, not the autosave one: an edit inside a batching region
+      // is still the person's work, and the save that carries it is still human.
       // Runs synchronously in the MO callback; skipped during paused-morph drains.
       if (!onlyNonPausable && isUserDrivenNow()) {
         for (const change of changes) {
-          if (!skipForPolicy(this._policyForChange(change), 'autosave')) {
+          if (!skipForPolicy(this._policyForChange(change), 'dirty')) {
             markUserDriven();
             break;
           }

package/src/lib/region-policy.js

@@ -7,7 +7,10 @@
  * resolved for back-compat. They apply to an element and its descendants:
  *
  *   no-save               — not written to the saved file (stripped). Live at runtime.
- *   no-trigger-autosave   — saved, but editing it doesn't trigger an autosave / mark dirty.
+ *   no-trigger-autosave   — saved, and still counts as unsaved work, but editing it does
+ *                           not start an autosave. Durable work the person batches by hand.
+ *   no-dirty              — saved, but its content is disposable: no autosave, no close
+ *                           warning, and an incoming sync frame may replace it.
  *   no-undo               — edits here are not recorded in the undo stack.
  *   no-watch              — invisible to the whole mutation system (high-churn regions). Still saved.
  *   freeze                — saved as authored (runtime changes not persisted). Live at runtime.
@@ -17,9 +20,15 @@
  *
  *   mutations-ignore  ->  no-watch
  *   save-remove       ->  no-save  no-undo
- *   save-ignore       ->  no-trigger-autosave  no-undo
+ *   save-ignore       ->  no-dirty  no-undo
  *   save-freeze       ->  freeze  no-undo
  *
+ * save-ignore maps to no-dirty, NOT to no-trigger-autosave. hyper-morph has always
+ * defined it as local-instance chrome ("explicit leave me alone") and sync-ignores
+ * it, and every real use of it in the wild is a generated stylesheet <link>. Calling
+ * it a spelling of no-trigger-autosave gave clayjs a durable region that hyper-morph
+ * refuses to sync, which is a contradiction no merge domain can express.
+ *
  * Separately, a snapshot-layer marker controls whether an element appears in any
  * snapshot at all (save file, live-sync broadcast, and dirty-comparison):
  *
@@ -31,7 +40,7 @@
  *
  * resolveRegionPolicy() walks an element's self-or-ancestor chain once and
  * returns the four independent axes the rest of the framework keys off:
- *   { watched, autosaveTriggered, undoable, persist, extension }
+ *   { watched, autosaveTriggered, dirtyTracked, undoable, persist, extension }
  */
 
 import { EXTENSION_NODE_SELECTOR } from './extension-noise.js';
@@ -39,10 +48,12 @@ import { EXTENSION_NODE_SELECTOR } from './extension-noise.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-undo', 'no-watch', 'freeze'];
+export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'freeze'];
 
-// Canonical tokens spellable inside the space-separated `clay` attribute.
-const CLAY_TOKENS = ["no-save", "no-snapshot", "no-trigger-autosave", "no-watch", "no-undo", "freeze"];
+// 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"];
 
 // True when a region marker is present, whether spelled as a `clay` token
 // (whitespace-token semantics, matching [clay~=token]) or a legacy bare attribute.
@@ -75,7 +86,32 @@ export const FREEZE_SELECTOR = '[clay~="freeze"], [freeze], [save-freeze]';
 // mutations-ignore footgun (their content stays in the saved file, but is no
 // longer counted as a change).
 export const STRIP_FROM_COMPARISON =
-  '[clay~="no-save"], [clay~="no-trigger-autosave"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-trigger-autosave], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
+  '[clay~="no-save"], [clay~="no-trigger-autosave"], [clay~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-trigger-autosave], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
+
+// Every spelling of no-trigger-autosave: the ONE difference between the autosave
+// domain and the dirty domain. A document containing none of these has identical
+// domains, which is what lets captureForSaveAndComparison short-circuit.
+// Derived here rather than written out at the call site so a page using the
+// legacy `save-ignore` spelling cannot get a dirty domain the policy disagrees
+// with — the split-brain where savePage() skips while the close warning fires.
+export const NO_TRIGGER_AUTOSAVE_SELECTOR =
+  '[clay~="no-trigger-autosave"], [no-trigger-autosave]';
+
+// Disposable regions: saved, but their content is explicitly not work. Stripped
+// from BOTH comparison domains, skipped by the merge on both sides, and never
+// counted by the close warning. This is the declared signal that lets the merge
+// stop guessing whether churn inside a batching region was a person or a renderer.
+export const NO_DIRTY_SELECTOR =
+  '[clay~="no-dirty"], [no-dirty], [save-ignore]';
+
+// forDirtyCheck strips everything forComparison does EXCEPT no-trigger-autosave.
+// An edit inside such a region is a real edit: the person can save it by hand and
+// must be warned about it on close. It just doesn't start an autosave by itself.
+// no-watch stays stripped — a region invisible to the mutation system cannot be
+// dirty-tracked either, and counting it would re-freeze the live-sync baseline
+// the way the mounted-tool bug did (see dirty-gate.js).
+export const STRIP_FROM_DIRTY_CHECK =
+  '[clay~="no-save"], [clay~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
 
 // Snapshot-layer marker: removed from EVERY snapshot (save, live-sync broadcast,
 // dirty-comparison) in snapshot.js. `no-snapshot` is the consistent alias for the
@@ -83,8 +119,13 @@ export const STRIP_FROM_COMPARISON =
 // 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 function isSnapshotRemoved(el) {
-  return hasRegionToken(el, 'snapshot-remove') || hasRegionToken(el, 'no-snapshot');
+// 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
+// snapshot as the region itself, and answering false for it was a lie callers
+// acted on.
+export function isSnapshotRemoved(node) {
+  const element = startElement(node);
+  return !!(element && element.closest && element.closest(SNAPSHOT_REMOVE_SELECTOR));
 }
 
 const PERSIST_RANK = { full: 0, frozen: 1, none: 2 };
@@ -98,19 +139,20 @@ function startElement(node) {
  * Walk an element's self-or-ancestor chain once and resolve its region axes.
  *
  * @param {Node} node
- * @returns {{watched:boolean, autosaveTriggered:boolean, undoable:boolean, persist:string, extension:boolean}}
+ * @returns {{watched:boolean, autosaveTriggered:boolean, dirtyTracked:boolean, undoable:boolean, persist:string, extension:boolean}}
  */
 export function resolveRegionPolicy(node) {
   let element = startElement(node);
 
   // Browser-extension injected content is never page content, for any consumer.
   if (element && element.closest && element.closest(EXTENSION_NODE_SELECTOR)) {
-    return { watched: false, autosaveTriggered: false, undoable: false, persist: PERSIST.FULL, extension: true };
+    return { watched: false, autosaveTriggered: false, dirtyTracked: false, undoable: false, persist: PERSIST.FULL, extension: true };
   }
 
   let watched = true;
   let undoable = true;
   let autosaveOff = false;
+  let dirtyOff = false;
   let persistRank = 0;
 
   while (element && element.nodeType === 1) {
@@ -118,13 +160,14 @@ export function resolveRegionPolicy(node) {
       // new naked attributes
       if (hasRegionToken(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 (hasRegionToken(element, 'freeze')) persistRank = Math.max(persistRank, PERSIST_RANK.frozen);
       // legacy markers -> bundles
       if (hasRegionToken(element, 'mutations-ignore')) watched = false;
       if (hasRegionToken(element, 'save-remove')) { persistRank = Math.max(persistRank, PERSIST_RANK.none); undoable = false; }
-      if (hasRegionToken(element, 'save-ignore')) { autosaveOff = true; undoable = false; }
+      if (hasRegionToken(element, 'save-ignore')) { autosaveOff = true; dirtyOff = true; undoable = false; }
       if (hasRegionToken(element, 'save-freeze')) { persistRank = Math.max(persistRank, PERSIST_RANK.frozen); undoable = false; }
     }
     element = element.parentElement;
@@ -133,12 +176,18 @@ export function resolveRegionPolicy(node) {
   // Implication rules (no-save wins over freeze automatically via Math.max above):
   //   no-watch  ⟹ no autosave + no undo (can't track what isn't watched)
   //   no-save / freeze ⟹ no autosave (nothing live to persist)
-  if (!watched) { autosaveOff = true; undoable = false; }
-  if (persistRank > 0) autosaveOff = true;
+  //   no-watch  ⟹ not dirty-tracked either (can't track what isn't watched)
+  //   no-save / freeze ⟹ not dirty-tracked (nothing live to persist)
+  // no-trigger-autosave deliberately does NOT clear dirtyTracked: that is the
+  // whole distinction between the two axes. no-dirty is the token that clears
+  // both, for content that is saved but is not work.
+  if (!watched) { autosaveOff = true; undoable = false; dirtyOff = true; }
+  if (persistRank > 0) { autosaveOff = true; dirtyOff = true; }
 
   return {
     watched,
     autosaveTriggered: !autosaveOff,
+    dirtyTracked: !dirtyOff,
     undoable,
     persist: RANK_PERSIST[persistRank],
     extension: false,
@@ -176,6 +225,7 @@ export function strictestPolicy(a, b) {
   return {
     watched: a.watched && b.watched,
     autosaveTriggered: a.autosaveTriggered && b.autosaveTriggered,
+    dirtyTracked: a.dirtyTracked && b.dirtyTracked,
     undoable: a.undoable && b.undoable,
     persist: PERSIST_RANK[a.persist] >= PERSIST_RANK[b.persist] ? a.persist : b.persist,
     extension: a.extension || b.extension,
@@ -191,7 +241,8 @@ const SKIP_TOKEN_PREDICATES = {
   'freeze': p => p.persist === PERSIST.FROZEN,
   'save-freeze': p => p.persist === PERSIST.FROZEN,
   'no-trigger-autosave': p => !p.autosaveTriggered,
-  'save-ignore': p => !p.autosaveTriggered,
+  'no-dirty': p => !p.dirtyTracked,
+  'save-ignore': p => !p.dirtyTracked,
   'no-undo': p => !p.undoable,
 };
 
@@ -199,7 +250,7 @@ const SKIP_TOKEN_PREDICATES = {
  * Should a consumer skip a change in this region?
  *
  * @param {object} policy   resolved region policy
- * @param {string} [require] axis the consumer needs: 'observed' | 'autosave' | 'undo'
+ * @param {string} [require] axis the consumer needs: 'observed' | 'autosave' | 'dirty' | 'undo'
  * @param {string[]} [skip]  literal attribute escape-hatch (any match -> skip)
  * @returns {boolean}
  */
@@ -211,6 +262,7 @@ export function skipForPolicy(policy, require, skip) {
   switch (require) {
     case 'observed': return !policy.watched;
     case 'autosave': return !policy.autosaveTriggered;
+    case 'dirty': return !policy.dirtyTracked;
     case 'undo': return !policy.undoable;
     default:
       // No require declared: preserve the legacy four-marker skip so unmodified
@@ -222,14 +274,42 @@ export function skipForPolicy(policy, require, skip) {
 // The canonical region API the vendored hyper-undo (a separate bundle that can't
 // import this module) delegates "is this undoable?" to via clay.region, so the two
 // can no longer drift. The loader assembles this onto clay in assembleCore.
-export const windowRegionShape = {
+// ONE object, served to both clay.region and clay.internals.region.
+//
+// They had drifted into two shapes with different key spellings for the same
+// selectors, and both are documented, so this is an additive union rather than a
+// choice between them: every name either surface published still resolves.
+export const regionShape = {
   resolveRegionPolicy,
   isInert,
+  isSnapshotRemoved,
   skipForPolicy,
   strictestPolicy,
+  addRegionToken,
   PERSIST,
+  TOKENS,
   REGION_ATTRS,
+
+  // Flat UPPERCASE names: what clay.region has always published.
   STRIP_FROM_SAVE,
-  FREEZE_SELECTOR,
   STRIP_FROM_COMPARISON,
+  STRIP_FROM_DIRTY_CHECK,
+  NO_TRIGGER_AUTOSAVE_SELECTOR,
+  NO_DIRTY_SELECTOR,
+  SNAPSHOT_REMOVE_SELECTOR,
+  FREEZE_SELECTOR,
+
+  // Nested camelCase: what clay.internals.region has always published.
+  selectors: {
+    stripFromSave: STRIP_FROM_SAVE,
+    stripFromComparison: STRIP_FROM_COMPARISON,
+    stripFromDirtyCheck: STRIP_FROM_DIRTY_CHECK,
+    noTriggerAutosave: NO_TRIGGER_AUTOSAVE_SELECTOR,
+    noDirty: NO_DIRTY_SELECTOR,
+    snapshotRemove: SNAPSHOT_REMOVE_SELECTOR,
+    freeze: FREEZE_SELECTOR,
+  },
 };
+
+// The name the loader imported before the two shapes merged.
+export const windowRegionShape = regionShape;

package/src/lib/root-attrs.js

@@ -18,10 +18,6 @@
 // content cannot strip this tab's copy, and a peer's copy is never applied.
 export const HOST_TOKEN_ATTRS = ["savetoken", "htmlclaytoken", "htmlclayid"];
 
-// Which save envelope this host's lane takes: a fact about the response, not
-// about the document.
-export const SAVE_TRANSPORT_ATTR = "clay-save-transport";
-
 // This library's own root state, and this tab's UI truth.
 export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];
 
@@ -36,7 +32,6 @@ export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];
 // can no longer save at all.
 export const TAB_LOCAL_ROOT_ATTRS = new Set([
   ...HOST_TOKEN_ATTRS,
-  SAVE_TRANSPORT_ATTR,
   ...ROOT_LIBRARY_ATTRS,
 ]);
 

package/src/lib/user-gesture.js

@@ -45,6 +45,7 @@ const RECENT_GESTURE_MS = 500;
 let gestureTaskActive = false;
 let lastTrustedGestureTs = -Infinity;
 let userDrivenSinceLastSave = false;
+let explicitSaveIntent = false;
 let installed = false;
 
 // Monotonic clock for the recency window — never moves backward, so a system
@@ -69,7 +70,9 @@ function onGesture(e) {
 
 /**
  * Install the capture-phase gesture listeners (idempotent). Call once in edit
- * mode (autosave.js and data-loss-panel both do this).
+ * mode. save.js does this for every editable page: gesture provenance is not an
+ * autosave feature, and gating it on <html autosave> left every manual-save page
+ * reporting its human edits as background writes.
  */
 export function initUserGesture() {
   if (installed || typeof document === 'undefined') return;
@@ -108,11 +111,40 @@ export function consumeUserDriven() {
   return v;
 }
 
+/**
+ * Record that a person asked for THIS save (Cmd+S, a [trigger-save] button).
+ *
+ * Deliberately NOT markUserDriven(). That bit accumulates until a save actually
+ * ships, which is right for "an edit happened in a human turn" but wrong here: a
+ * person pressing Save on a clean page produces no save at all, so the bit stays
+ * armed and rides whatever BACKGROUND write happens next, reporting it as human.
+ * That is precisely the write the recovery guard exists to catch.
+ *
+ * This one is scoped to a single save attempt. The send consumes it; an attempt
+ * that ends without sending clears it.
+ */
+export function markExplicitSave() {
+  explicitSaveIntent = true;
+}
+
+/** Read-and-reset, at the actual send. */
+export function consumeExplicitSave() {
+  const v = explicitSaveIntent;
+  explicitSaveIntent = false;
+  return v;
+}
+
+/** The save attempt ended without sending anything. */
+export function clearExplicitSave() {
+  explicitSaveIntent = false;
+}
+
 /** Test seam: force-reset state. */
 export function _resetUserGesture() {
   gestureTaskActive = false;
   lastTrustedGestureTs = -Infinity;
   userDrivenSinceLastSave = false;
+  explicitSaveIntent = false;
 }
 
 /**

package/src/loader-logic.js

@@ -21,11 +21,34 @@ export const PLUGIN_PATHS = {
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+  quickcrop: { path: "vendor/quickcrop.vendor.js", editOnly: false, default: false },
+  // editOnly, because a file picker only ever appears in edit mode: the cms
+  // injects its own editing toggle there and clayjs's edit-mode signal is a
+  // superset of the cms's, so the plugin is present exactly when it can be used.
+  upload:    { path: "plugins/upload.js",          editOnly: true,  default: false },
   wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "wire", "demo"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "demo"];
+
+// 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
+// finds nothing, so `plugins=cms` has to bring quickcrop with it or image crop is
+// dead with no error and no log. quickcrop loads BEFORE cms in the order above,
+// because the loader attaches each plugin's member as it lands and cms reads what
+// earlier plugins attached during its own evaluation.
+// `upload` rides the same reasoning one step further. Without it the cms has no
+// uploader to look up, so it embeds every picked image in the document as a data:
+// URL: a two megabyte photo costs 2.7 MB of base64 on that save, on every future
+// save, and in every stored version. With it the cms asks the host first and
+// embeds only when the host does not store files, which is still the right answer
+// on a plain file server.
+//
+// This is the only line in the capability that changes how an already-published
+// page behaves, which is why it shipped alone, one release after the plugin it
+// enables. Reverting it is reverting this line.
+const IMPLIES = { cms: ["quickcrop", "upload"] };
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);
@@ -50,6 +73,11 @@ export function resolveModules(params, isEditMode) {
     if (spec.default) enabled.add(name);
   }
   parseCsv(params, "plugins", enabled, (set, name) => set.add(name));
+  // Between the two: exclude still wins, so `plugins=cms&exclude=quickcrop` opts
+  // back out of the cropper.
+  for (const name of [...enabled]) {
+    for (const implied of IMPLIES[name] || []) enabled.add(implied);
+  }
   parseCsv(params, "exclude", enabled, (set, name) => set.delete(name));
 
   const plugins = [];

package/src/loader.js

@@ -102,12 +102,16 @@ function attachPluginMember(path, mod) {
     clay.morph = mod.morph;
   } else if (path === "vendor/hypercms.vendor.js") {
     clay.cms = mod.cms || mod.default;
+  } else if (path === "plugins/upload.js") {
+    clay.upload = mod.upload || mod.default;
   } else if (path === "plugins/wire.js") {
     clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/demo.js") {
     clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {
     clay.RichClay = mod.RichClay || mod.default;
+  } else if (path === "vendor/quickcrop.vendor.js") {
+    clay.quickcrop = mod.quickcrop || mod.default;
   }
 }