@panphora/clayjs 0.6.1 → 0.7.1

package/src/core/save.js

@@ -19,10 +19,11 @@ import {
   addDocumentTransform,
   isSaveInProgress
 } from "./save-core.js";
-import { captureForComparison, captureForSaveAndComparison } from "./snapshot.js";
+import { captureForComparison, captureForComparisonAndDirty, captureForSaveAndComparison } from "./snapshot.js";
 import { gateCaptureToken, gateClearIfUnchanged } from "../lib/dirty-gate.js";
 import { ROOT_LIBRARY_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
+import { initUserGesture, markExplicitSave, clearExplicitSave } from "../lib/user-gesture.js";
 
 // Keep this library's own root state out of the saved bytes.
 //
@@ -99,9 +100,18 @@ window.addEventListener('offline', () => {
 });
 
 window.addEventListener('online', () => {
-  if (document.documentElement.getAttribute('savestatus') === 'offline') {
-    savePage();
-  }
+  if (document.documentElement.getAttribute('savestatus') !== 'offline') return;
+  savePage().then((result) => {
+    // The page went offline with everything already saved, so there is nothing
+    // to send and the offline chip is simply stale. Clear it directly rather
+    // than through setSaveState: no save happened, and dispatching
+    // clay:save-saved would run every [onaftersave] handler and light every
+    // status chip as though one had.
+    if (result.msgType === 'skipped' &&
+        document.documentElement.getAttribute('savestatus') === 'offline') {
+      document.documentElement.setAttribute('savestatus', 'saved');
+    }
+  });
 });
 
 // ============================================
@@ -116,16 +126,36 @@ window.addEventListener('online', () => {
 // ever sending them: the edit was gone, with no error, no dirty flag, and no
 // close-tab warning.
 //
-// Post-save mutators are made invisible to the comparison instead — they mark what
-// they touch `no-trigger-autosave`, which strips it from every comparison capture
-// (see cache-bust.js and refetch-on-save.js). That leaves the baseline free to stay
-// exactly what savePage sent, which is the only value that is true by construction.
+// Post-save mutators are made invisible to the comparison instead. They remember
+// what the URL was authored as and restore it on every snapshot clone, so the live
+// DOM carries the busted URL and the file carries the authored one (authored-url.js,
+// used by cache-bust.js and refetch-on-save.js). That leaves the baseline free to
+// stay exactly what savePage sent, which is the only value true by construction.
+//
+// They used to mark what they touched `no-trigger-autosave` instead. That hid the
+// rewrite from the comparison only once the marker had reached the baseline, so the
+// FIRST save on any page using either helper was followed by a spurious dirty state
+// and a false close warning. It self-healed on the next save, which is why it went
+// unnoticed.
 
 // Re-export from core for backward compatibility
 export { addDocumentTransform, getPageContents };
 
 let unsavedChanges = false;
+// TWO SAVED BASELINES, one per comparison domain.
+//
+//   lastSavedContents — the AUTOSAVE domain (no-trigger-autosave stripped).
+//     Answers "should this edit start a save on its own?" Autosave, the load
+//     settle guard, the live-sync baseline and the scoped-sync merge oracle all
+//     read this one, and none of them changes.
+//   lastSavedDirty — the DIRTY domain (no-trigger-autosave kept). Answers "is
+//     there anything here the person would lose?" Only an explicit savePage()
+//     and the close warning read it.
+//
+// On a page with no batching region the two are byte-identical, so nothing about
+// the split is observable there.
 let lastSavedContents = '';
+let lastSavedDirty = '';
 // A save was requested while one was on the wire; run one more when it settles.
 let pendingSave = false;
 
@@ -173,9 +203,12 @@ function skipped_(msg) {
  * where the write may or may not have landed, so it is not treated as success
  * either.
  */
-function applySaveResult(result, forComparison, label, gateToken) {
+function applySaveResult(result, forComparison, forDirty, label, gateToken) {
   if (result.ok) {
+    // Both baselines advance from the SAME pre-request capture, never from the
+    // live DOM, so an edit made while the request was on the wire stays unsaved.
     lastSavedContents = forComparison;
+    lastSavedDirty = forDirty;
     unsavedChanges = false;
     // Generation-checked: clears the scoped-sync dirty gate only if nothing
     // changed while this save was on the wire.
@@ -206,7 +239,28 @@ function drainPendingSave() {
 export function getUnsavedChanges() { return unsavedChanges; }
 export function setUnsavedChanges(val) { unsavedChanges = val; }
 export function getLastSavedContents() { return lastSavedContents; }
-export function setLastSavedContents(val) { lastSavedContents = val; }
+export function getLastSavedDirty() { return lastSavedDirty; }
+
+/**
+ * Install both saved baselines from one post-morph capture.
+ *
+ * live-sync calls this after applying a frame it verified clean, where the page
+ * now IS the file on disk. Setting only the autosave baseline would leave the
+ * dirty baseline describing the pre-frame page, and the close warning would then
+ * warn about the frame's own content.
+ */
+export function setLastSavedBaselines(forComparison, forDirty) {
+  lastSavedContents = forComparison;
+  lastSavedDirty = forDirty;
+}
+
+// Kept for back-compat: a caller with one string means the page has no batching
+// region, or it does not know about the split. Setting both from it is the safe
+// reading, since the domains coincide exactly when there is no such region.
+export function setLastSavedContents(val) {
+  lastSavedContents = val;
+  lastSavedDirty = val;
+}
 
 /**
  * Save the current page with change detection and state management.
@@ -221,6 +275,7 @@ export function setLastSavedContents(val) { lastSavedContents = val; }
 export function savePage(callback = () => {}) {
   return new Promise((resolve) => {
     if (!isEditMode && !window.clay?.testMode) {
+      clearExplicitSave();
       const skipped = skipped_('Not in edit mode');
       callback(skipped);
       return resolve(skipped);
@@ -230,6 +285,8 @@ export function savePage(callback = () => {}) {
     // than dropping it: the in-flight request carries the older bytes, and if no
     // further mutation happens to retrigger autosave, the newer ones would never
     // reach disk at all.
+    // Not cleared here: pendingSave means this request is deferred, not
+    // abandoned, and drainPendingSave is what eventually sends it.
     if (isSaveInProgress()) {
       pendingSave = true;
       const skipped = skipped_('Save already in progress');
@@ -247,12 +304,13 @@ export function savePage(callback = () => {}) {
     // Single capture: clone once, get both versions
     // forSave strips non-persisted regions ([no-save]/[save-remove])
     // forComparison additionally strips every autosave-off region
-    let forSave, forComparison, snapshotHtml;
+    let forSave, forComparison, forDirty;
     const gateToken = gateCaptureToken();
     try {
-      ({ forSave, forComparison, snapshotHtml } = captureForSaveAndComparison());
+      ({ forSave, forComparison, forDirty } = captureForSaveAndComparison());
     } catch (err) {
       console.error('savePage: captureForSaveAndComparison failed', err);
+      clearExplicitSave();
       setSaveState('error', err.message);
       const result = { msg: err.message, msgType: 'error', code: null, etag: null };
       if (typeof callback === 'function') {
@@ -261,12 +319,18 @@ export function savePage(callback = () => {}) {
       return resolve(result);
     }
 
-    // Compare directly - lastSavedContents is already stripped
-    unsavedChanges = (forComparison !== lastSavedContents);
+    // An explicit save asks the DIRTY question: write anything the person would
+    // otherwise lose, including an edit inside a batching region that was never
+    // going to autosave itself.
+    unsavedChanges = (forDirty !== lastSavedDirty);
     logSaveCheck('savePage dirty check', !unsavedChanges);
 
-    // Skip if content hasn't changed
+    // Skip if content hasn't changed. Clearing the explicit intent here is the
+    // whole point of scoping it: pressing Save on a clean page sends nothing, and
+    // leaving "a human asked for this" armed would hand it to the next
+    // background write and hide exactly the clobber the guard watches for.
     if (!unsavedChanges) {
+      clearExplicitSave();
       gateClearIfUnchanged(gateToken);
       const skipped = skipped_('No changes to save');
       callback(skipped);
@@ -278,13 +342,13 @@ export function savePage(callback = () => {}) {
 
     // Use saveHtml directly with our pre-captured content (avoids double capture)
     saveHtml(forSave, (result) => {
-      applySaveResult(result, forComparison, 'updated after save', gateToken);
+      applySaveResult(result, forComparison, forDirty, 'updated after save', gateToken);
       if (typeof callback === 'function') {
         callback(result);
       }
       resolve(result);
       drainPendingSave();
-    }, { snapshotHtml });
+    });
   });
 }
 
@@ -314,10 +378,10 @@ export function savePageForce(callback = () => {}) {
       setOfflineStateQuiet();
     }
 
-    let forSave, forComparison, snapshotHtml;
+    let forSave, forComparison, forDirty;
     const gateToken = gateCaptureToken();
     try {
-      ({ forSave, forComparison, snapshotHtml } = captureForSaveAndComparison());
+      ({ forSave, forComparison, forDirty } = captureForSaveAndComparison());
     } catch (err) {
       console.error('savePageForce: captureForSaveAndComparison failed', err);
       setSaveState('error', err.message);
@@ -331,13 +395,13 @@ export function savePageForce(callback = () => {}) {
     setSavingState();
 
     saveHtml(forSave, (result) => {
-      applySaveResult(result, forComparison, 'updated after force save', gateToken);
+      applySaveResult(result, forComparison, forDirty, 'updated after force save', gateToken);
       if (typeof callback === 'function') {
         callback(result);
       }
       resolve(result);
       drainPendingSave();
-    }, { snapshotHtml });
+    });
   });
 }
 
@@ -403,8 +467,9 @@ function initBaselineCapture() {
   // Take immediate snapshot and set as baseline right away
   // This ensures saves during settle window work correctly
   // Store stripped version so comparisons are direct (no parsing needed)
-  const immediateContents = captureForComparison();
+  const { forComparison: immediateContents, forDirty: immediateDirty } = captureForComparisonAndDirty();
   lastSavedContents = immediateContents;
+  lastSavedDirty = immediateDirty;
   baselineContents = immediateContents;
   logBaseline('immediate capture', `${immediateContents.length} chars`);
 
@@ -429,13 +494,18 @@ function initBaselineCapture() {
     if (unsubscribeMutation) unsubscribeMutation();
     userEditEvents.forEach(evt => document.removeEventListener(evt, markUserEdited, true));
 
-    // Only update if no user edits AND no saves occurred during settle
-    // (if a save happened, lastSavedContents would differ from immediateContents)
-    if (!userEdited && lastSavedContents === immediateContents) {
+    // Only update if no user edits AND no saves occurred during settle.
+    // BOTH baselines have to be untouched, not just the autosave one: a save
+    // whose only change was inside a batching region advances lastSavedDirty
+    // while leaving lastSavedContents byte-identical to the immediate capture.
+    // Checking one would let a second, unsent edit in that region be captured
+    // here as though it had been saved.
+    if (!userEdited && lastSavedContents === immediateContents && lastSavedDirty === immediateDirty) {
       // Store stripped version so comparisons are direct (no parsing needed)
       const gateToken = gateCaptureToken();
-      const contents = captureForComparison();
+      const { forComparison: contents, forDirty: contentsDirty } = captureForComparisonAndDirty();
       lastSavedContents = contents;
+      lastSavedDirty = contentsDirty;
       baselineContents = contents;
       // Boot churn (modules rewriting attributes at DOM-ready) counted toward
       // the scoped-sync gate; the settled baseline is the proof it wasn't edits.
@@ -547,6 +617,9 @@ export function initSaveKeyboardShortcut() {
     let metaKeyPressed = isMac ? event.metaKey : event.ctrlKey;
     if (metaKeyPressed && event.keyCode == 83) {
       event.preventDefault();
+      // isTrusted, so a script calling dispatchEvent cannot manufacture human
+      // provenance for a write the person never asked for.
+      if (event.isTrusted) markExplicitSave();
       savePage();
     }
   });
@@ -559,6 +632,8 @@ export function initSaveKeyboardShortcut() {
 export function initHyperclaySaveButton() {
   document.addEventListener("click", event => {
     if (event.target.closest("[trigger-save]")) {
+      // el.click() is isTrusted:false, so this cannot be faked from script.
+      if (event.isTrusted) markExplicitSave();
       savePage();
     }
   });
@@ -571,6 +646,10 @@ export function initHyperclaySaveButton() {
 export function init() {
   if (!isEditMode) return;
 
+  // Every editable page, not just autosave pages. A manual-save page makes
+  // exactly the saves a person asked for, and used to report all of them as
+  // background writes because this was installed behind the autosave gate.
+  initUserGesture();
   initSaveKeyboardShortcut();
   initHyperclaySaveButton();
 }

package/src/core/snapshot.js

@@ -37,8 +37,8 @@
  */
 
 import { stripExtensionNoise } from '../lib/extension-noise.js';
-import { STRIP_FROM_SAVE, STRIP_FROM_COMPARISON, SNAPSHOT_REMOVE_SELECTOR } from '../lib/region-policy.js';
-import { saveTransport, DESKTOP_JSON } from './host-attrs.js';
+import { restoreAuthoredUrls } from '../lib/authored-url.js';
+import { STRIP_FROM_SAVE, STRIP_FROM_COMPARISON, STRIP_FROM_DIRTY_CHECK, NO_TRIGGER_AUTOSAVE_SELECTOR, SNAPSHOT_REMOVE_SELECTOR } from '../lib/region-policy.js';
 import { TAB_LOCAL_ROOT_ATTRS } from '../lib/root-attrs.js';
 
 // =============================================================================
@@ -135,6 +135,11 @@ export function captureSnapshot({ flushUndo = true } = {}) {
     hook(clone);
   }
 
+  // Put back any URL clay rewrote at runtime (cache-bust, refetch-on-save) so
+  // the file keeps what the page author wrote. Before onbeforesnapshot, so an
+  // authored handler sees the same URLs the file will.
+  restoreAuthoredUrls(clone);
+
   runAuthoredHandlers(clone, 'onbeforesnapshot');
 
   for (const el of clone.querySelectorAll(SNAPSHOT_REMOVE_SELECTOR)) {
@@ -203,6 +208,78 @@ export function captureForComparison({ flushUndo = true } = {}) {
   return "<!DOCTYPE html>" + clone.outerHTML;
 }
 
+/**
+ * Capture in the DIRTY domain: like captureForComparison, but it KEEPS
+ * no-trigger-autosave regions.
+ *
+ * The two domains answer different questions. "Should this edit start an
+ * autosave?" is the autosave domain (captureForComparison). "Is there anything
+ * here the person would lose?" is this one — an edit inside a batching region is
+ * a real edit that an explicit save must write and a close must warn about.
+ *
+ * On a document with no such region this returns bytes identical to
+ * captureForComparison, which is what keeps the two baselines comparable.
+ *
+ * @returns {string}
+ */
+export function captureForDirtyCheck({ flushUndo = true } = {}) {
+  const clone = captureSnapshot({ flushUndo });
+
+  runAuthoredHandlers(clone, 'onbeforesave');
+
+  for (const el of clone.querySelectorAll(STRIP_FROM_DIRTY_CHECK)) {
+    el.remove();
+  }
+
+  for (const hook of documentTransforms) {
+    hook(clone);
+  }
+
+  return "<!DOCTYPE html>" + clone.outerHTML;
+}
+
+/**
+ * Both comparison domains from ONE snapshot, with no save clone and no
+ * snapshot-ready event.
+ *
+ * For the callers that need to install or check both baselines without sending
+ * anything: the load-time baseline capture and live-sync's post-morph baseline
+ * setter. Taking two separate snapshots there would cost two full DOM clones per
+ * boot and per applied frame, for bytes that are usually identical.
+ *
+ * @returns {{ forComparison: string, forDirty: string }}
+ */
+export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
+  const clone = captureSnapshot({ flushUndo });
+
+  runAuthoredHandlers(clone, 'onbeforesave');
+
+  const dirtyClone = clone.querySelector(NO_TRIGGER_AUTOSAVE_SELECTOR)
+    ? clonePreventingOnclone(clone)
+    : null;
+
+  for (const el of clone.querySelectorAll(STRIP_FROM_COMPARISON)) {
+    el.remove();
+  }
+  for (const hook of documentTransforms) {
+    hook(clone);
+  }
+  const forComparison = "<!DOCTYPE html>" + clone.outerHTML;
+
+  let forDirty = forComparison;
+  if (dirtyClone) {
+    for (const el of dirtyClone.querySelectorAll(STRIP_FROM_DIRTY_CHECK)) {
+      el.remove();
+    }
+    for (const hook of documentTransforms) {
+      hook(dirtyClone);
+    }
+    forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
+  }
+
+  return { forComparison, forDirty };
+}
+
 /**
  * Single-capture function for both saving and comparison.
  *
@@ -211,23 +288,11 @@ export function captureForComparison({ flushUndo = true } = {}) {
  *
  * @param {Object} options
  * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
- * @returns {{ forSave: string, forComparison: string, snapshotHtml: ?string }}
+ * @returns {{ forSave: string, forComparison: string, forDirty: string }}
  */
 export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   const clone = captureSnapshot();
 
-  // The unstripped snapshot, for a host that asked for the desktop JSON envelope:
-  // the save then sends both the stripped document and this. Returned to the caller
-  // rather than parked on a window global, so it can only ever be paired with the
-  // content captured alongside it. As a global it was cleared on success only, so
-  // two captures without an intervening successful save shipped a stale snapshot
-  // next to fresh content. Captured only when the document DECLARES the transport;
-  // this used to key off `location.hostname`, which set it on every localhost page
-  // whether or not its host wanted it.
-  const snapshotHtml = saveTransport() === DESKTOP_JSON
-    ? '<!DOCTYPE html>' + clone.outerHTML
-    : null;
-
   // Emit for live-sync before any stripping
   if (emitForSync) {
     document.dispatchEvent(new CustomEvent('clay:snapshot-ready', {
@@ -241,6 +306,15 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   // Clone for comparison before stripping (cheaper than cloning live DOM)
   const compareClone = clonePreventingOnclone(clone);
 
+  // The dirty domain differs from the autosave domain only inside
+  // no-trigger-autosave regions, so a document without one pays nothing: the two
+  // strip sets remove exactly the same nodes and one string serves both. The
+  // predicate reads the captured clone after authored handlers have run, and
+  // covers all three spellings via the policy's own selector.
+  const dirtyClone = clone.querySelector(NO_TRIGGER_AUTOSAVE_SELECTOR)
+    ? clonePreventingOnclone(clone)
+    : null;
+
   // Save clone: run hooks (freeze restore lives here), THEN strip [no-save]/[save-remove]
   // LAST (snapshot-algorithm step 7) so freeze-restored [no-save] content can't leak to disk.
   for (const hook of documentTransforms) {
@@ -260,21 +334,42 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   }
   const forComparison = "<!DOCTYPE html>" + compareClone.outerHTML;
 
-  return { forSave, forComparison, snapshotHtml };
+  // Dirty clone: same shape as the compare clone, one selector weaker.
+  let forDirty = forComparison;
+  if (dirtyClone) {
+    for (const el of dirtyClone.querySelectorAll(STRIP_FROM_DIRTY_CHECK)) {
+      el.remove();
+    }
+    for (const hook of documentTransforms) {
+      hook(dirtyClone);
+    }
+    forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
+  }
+
+  return { forSave, forComparison, forDirty };
 }
 
 /**
- * Capture for a protected live-sync merge: the save-domain and comparison-
- * domain clones of ONE snapshot, plus a WeakMap pairing every comparison
- * element to its save-clone twin.
+ * Capture for a protected live-sync merge: the save-domain and loss-domain
+ * clones of ONE snapshot, plus a WeakMap pairing every loss-domain element to
+ * its save-clone twin.
  *
- * The pairing is recorded immediately after the comparison clone is created,
+ * The pairing is recorded immediately after the compare clone is created,
  * while the two trees are still isomorphic; each side's strips then remove
- * nodes independently without disturbing it. The scoped-sync dirty diff runs
- * on the comparison clone (the same domain as lastSavedContents), and dirty
- * roots map through pairMap to save-domain subtrees (the same domain as the
- * file on disk), which still carry the no-trigger-autosave / freeze / no-watch
- * children the comparison strips.
+ * nodes independently without disturbing it.
+ *
+ * The compare clone strips STRIP_FROM_DIRTY_CHECK, not STRIP_FROM_COMPARISON:
+ * the merge asks "would applying this frame destroy work?", which is the same
+ * question the close warning asks, so it must use the same domain. The autosave
+ * domain is the wrong one here because it strips no-trigger-autosave, and an
+ * unsaved edit in a batching region is exactly the work the merge exists to
+ * protect. Disposable churn stays out of both domains via no-dirty, which is
+ * what keeps a self-churning region from promoting a dirty root to <body> and
+ * holding every frame forever.
+ *
+ * Dirty roots map through pairMap to save-domain subtrees (the same domain as
+ * the file on disk), which still carry the freeze / no-watch children the
+ * compare clone strips.
  *
  * Never emits snapshot-ready (this capture must not feed the send pipeline)
  * and never flushes the undo batch (it runs per incoming frame, not per save).
@@ -305,7 +400,7 @@ export function captureForMerge() {
     el.remove();
   }
 
-  for (const el of compareClone.querySelectorAll(STRIP_FROM_COMPARISON)) {
+  for (const el of compareClone.querySelectorAll(STRIP_FROM_DIRTY_CHECK)) {
     el.remove();
   }
   for (const hook of documentTransforms) {

package/src/core/unsaved-warning.js

@@ -7,15 +7,17 @@
  * Works independently of autosave - no mutation observer needed during editing,
  * just a single comparison when the user tries to leave.
  *
- * Both current and stored content have [save-remove] and [save-ignore] stripped,
- * so comparison is direct with no parsing needed.
+ * Both current and stored content have [save-remove] stripped, so comparison is
+ * direct with no parsing needed. [save-ignore] / no-trigger-autosave regions are
+ * KEPT here: they don't trigger an autosave, so an edit in one is precisely the
+ * kind that would be lost without a warning.
  *
  * Requires the 'save-system' module (automatically included as dependency).
  */
 
 import { isEditMode } from "./is-edit-mode.js";
-import { captureForComparison } from "./snapshot.js";
-import { getLastSavedContents } from "./save.js";
+import { captureForDirtyCheck } from "./snapshot.js";
+import { getLastSavedDirty } from "./save.js";
 import { logUnloadDiffSync, preloadIfEnabled } from "../lib/autosave-debug.js";
 
 // Pre-load diff library if debug mode is on (so it's ready for unload)
@@ -30,9 +32,11 @@ preloadIfEnabled();
 window.addEventListener('beforeunload', (event) => {
   if (!isEditMode) return;
 
-  // Compare directly - both are already stripped
-  const currentForCompare = captureForComparison();
-  const lastSaved = getLastSavedContents();
+  // The DIRTY domain, not the autosave domain. An edit inside a
+  // no-trigger-autosave region never starts a save by itself, which is exactly
+  // why closing the tab on one has to warn: nothing else is going to write it.
+  const currentForCompare = captureForDirtyCheck();
+  const lastSaved = getLastSavedDirty();
 
   if (currentForCompare !== lastSaved) {
     // Debug: log what's different before showing the warning

package/src/internals/index.js

@@ -12,18 +12,7 @@
 
 import { captureSnapshot, captureForSave, addDocumentTransform } from "../core/snapshot.js";
 import { saveHtml, replacePageWith, isSaveInProgress } from "../core/save-core.js";
-import {
-  addRegionToken,
-  resolveRegionPolicy,
-  isInert,
-  isSnapshotRemoved,
-  PERSIST,
-  REGION_ATTRS,
-  STRIP_FROM_SAVE,
-  STRIP_FROM_COMPARISON,
-  SNAPSHOT_REMOVE_SELECTOR,
-  FREEZE_SELECTOR,
-} from "../lib/region-policy.js";
+import { regionShape } from "../lib/region-policy.js";
 
 const clay = (window.clay = window.clay || {});
 
@@ -40,20 +29,8 @@ clay.internals = {
 
   // Write your own attribute without hardcoding our selectors. Doing it by hand is
   // how a custom attribute quietly stops respecting [no-save] two releases later.
-  region: {
-    addRegionToken,
-    resolveRegionPolicy,
-    isInert,
-    isSnapshotRemoved,
-    PERSIST,
-    REGION_ATTRS,
-    selectors: {
-      stripFromSave: STRIP_FROM_SAVE,
-      stripFromComparison: STRIP_FROM_COMPARISON,
-      snapshotRemove: SNAPSHOT_REMOVE_SELECTOR,
-      freeze: FREEZE_SELECTOR,
-    },
-  },
+  // The same object clay.region holds, so the two can no longer drift.
+  region: regionShape,
 
   // The save lane under clay.save. saveHtml sends bytes you supply, so it bypasses
   // the snapshot pipeline entirely: whatever you hand it is what lands in the

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);
+  }
+}