@panphora/clayjs 1.0.0 → 1.2.0

package/src/core/save-core.js

@@ -10,6 +10,8 @@
 import { isEditMode } from "./is-edit-mode.js";
 import { consumeUserDriven, consumeExplicitSave, markUserDriven } from "../lib/user-gesture.js";
 import { saveToken } from "./host-attrs.js";
+import { lastSeenEtag, conditionalSaves, recordEtag } from "./etag.js";
+import { hostMeta } from "./host-meta.js";
 import {
   getPageContents,
   onSnapshot,
@@ -60,15 +62,118 @@ function successResult(data) {
   };
 }
 
+// =============================================================================
+// THE ATTEMPT ID (spec §6, `receipts`)
+// =============================================================================
+// A save that times out leaves two questions open at once: did our write land,
+// and did somebody else write. The client cannot answer either from the outside.
+// Guessing "it was me" is what the old reconcile-on-timeout did, and when the
+// guess was wrong it adopted a stamp describing a peer's bytes this tab had never
+// seen, so the next save overwrote them with no refusal and no notice. Refusing to
+// guess is safe but shows a person a conflict bar for a few seconds of bad wifi.
+//
+// So this tab stamps every attempt with an opaque id and asks the host the one
+// question only the host can answer: are the bytes you are storing the ones this
+// save sent? A host that answers turns an indeterminate save into a determinate
+// one, and the person sees nothing at all.
+//
+// The ids this tab has sent, newest last. A 412 carrying one of them is the host
+// saying "your OWN earlier save is what moved this document", which is a late
+// duplicate and not a conflict with anybody. Bounded because it is only ever
+// searched for a recent send.
+const sentIds = [];
+const SENT_ID_MEMORY = 8;
+
+// The attempt whose answer never arrived, or null. It holds only what is needed to
+// ask about it later: which id it carried, and which stamp it was sent against.
+//
+// It survives ONLY while the question is genuinely open. A host that answers, in
+// either direction, closes it, which is what keeps the conflict bar from claiming
+// a refusal might be the person's own save when the host has already said it is
+// not. An unreachable host leaves it set, and that is the honest old behaviour:
+// the stamp is kept, the next save is refused rather than accepted, and the notice
+// says so.
+let unknownAttempt = null;
+
+/** True while an earlier save may or may not have landed (spec §7). */
+export function saveFateIsUnknown() {
+  return unknownAttempt !== null;
+}
+
+/**
+ * A fresh id for one save attempt.
+ *
+ * Uniqueness per attempt is the whole property: two tabs sharing an id would each
+ * read the other's receipt as proof of their own write. `getRandomValues` into a
+ * zeroed array is the failure that would do exactly that, silently, so a missing
+ * crypto implementation falls back to something random rather than to zeros.
+ */
+function mintSaveId() {
+  const uuid = window.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  if (window.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    window.crypto.getRandomValues(bytes);
+    return Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+  }
+  // Three segments, not one: §6 asks for at least 128 bits, and one `Math.random()`
+  // truncated to ten base-36 characters carries about 52. A timestamp is not entropy,
+  // so it cannot make up the difference between two tabs minting in the same
+  // millisecond, which is the collision that matters.
+  const segment = () => Math.random().toString(36).slice(2, 12).padEnd(10, "0");
+  return `${Date.now().toString(36)}-${segment()}${segment()}${segment()}`;
+}
+
+function rememberSentId(saveId) {
+  sentIds.push(saveId);
+  if (sentIds.length > SENT_ID_MEMORY) sentIds.shift();
+}
+
+/**
+ * Did this tab send this id at all?
+ *
+ * The weaker of the two questions asked of a receipt, and it belongs only to the
+ * late-duplicate rule: a 412 naming ANY id this tab sent means this tab's own
+ * earlier save is what moved the document, which is enough to adopt that stamp and
+ * send again, because sending again is all that follows. It is never enough to
+ * conclude that a particular save landed. That needs identity with that save's own
+ * id, which is what recoverUnknownSave asks.
+ */
+function sentByThisTab(saveId) {
+  return typeof saveId === "string" && saveId !== "" && sentIds.includes(saveId);
+}
+
+/** Test-only: forget every id and any open question. */
+export function resetSaveAttempts() {
+  sentIds.length = 0;
+  unknownAttempt = null;
+}
+
 function errorResult(err) {
   const timedOut = err.name === 'AbortError';
+  // Spec §6: a 412 is a REFUSED save, not a failed one. The host wrote nothing and
+  // its document is byte-identical to what it was, and the bytes we tried to write
+  // are still on this page. Reporting that as 'error' would give the one outcome
+  // where nothing went wrong the one severity that means something did, and would
+  // put it through the same retry-and-toast path as a dead server.
+  // The status is authoritative (§3), so the 412 alone decides this. Reading `code`
+  // as well let any other status claim a conflict, and it bought nothing: a proxy
+  // answering 412 with no body carries no code to read, so the fallback never
+  // covered the case it was written for. What it did cover was htmlclay's
+  // truncation refusal, a 409 that lifts itself within a second, which suspended
+  // autosave over a condition that had already cleared.
+  const conflicted = !timedOut && err.status === 412;
   return {
     ok: false,
     msg: timedOut ? 'Server not responding' : (err.message || 'Save failed'),
     // A timeout is not evidence the write failed. The request may well have landed,
     // so this reports "we do not know" rather than asserting something false.
-    msgType: timedOut ? 'unknown' : 'error',
-    code: timedOut ? 'timeout' : (err.code ?? null),
+    msgType: timedOut ? 'unknown' : (conflicted ? 'conflict' : 'error'),
+    code: timedOut ? 'timeout' : (conflicted ? 'conflict' : (err.code ?? null)),
+    changedBy: conflicted ? (err.changedBy ?? null) : null,
+    // A refusal that may be answering this tab's own timed-out write. Only the
+    // notice uses it, and only to word itself; nothing decides anything on it.
+    afterTimeout: conflicted && unknownAttempt !== null,
     etag: null
   };
 }
@@ -113,9 +218,11 @@ function skippedResult(msg) {
  * @param {string} content - HTML to save
  * @param {boolean} userDriven - Whether a human gesture is behind this save
  * @param {AbortSignal} signal
+ * @param {string} saveId - this attempt's §6 receipt id
+ * @param {?string} etag - the stamp to send as If-Match, or null
  * @returns {{url: string, options: Object}}
  */
-function buildSaveRequest(content, userDriven, signal) {
+function buildSaveRequest(content, userDriven, signal, saveId, etag) {
   const token = saveToken();
   const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
   const options = {
@@ -129,12 +236,59 @@ function buildSaveRequest(content, userDriven, signal) {
       // Spec §9's name for the provenance bit. `X-Hyperclay-User-Driven` was the
       // pre-spec spelling; every host reads Save-Trigger first and falls back to
       // it, so stored documents running an older client keep working.
-      'Save-Trigger': userDriven ? 'user' : 'auto'
+      'Save-Trigger': userDriven ? 'user' : 'auto',
+      // Spec §6 (`receipts`): which attempt this is. Sent to every host, because a
+      // host that does not implement receipts ignores an unknown header, and
+      // gating it on discovery would mean holding the save until an async lookup
+      // resolved. Nothing is inferred from the header being accepted: only a host
+      // that ANSWERS with the id has said anything.
+      'Save-ID': saveId
     },
     body: content
   };
 
-  return { url: new URL(path, window.location.origin).href, options };
+  if (etag) options.headers['If-Match'] = etag;
+
+  return { url: resolveSaveUrl(path), options };
+}
+
+/**
+ * The stamp to send as If-Match, or null for a save that goes out unconditional.
+ *
+ * Two gates, and both are the point. The capability must have been announced by
+ * name, because §5 forbids inferring one any other way, and a host that never
+ * promised to honour If-Match may do anything at all with it. And a stamp must
+ * actually be held: a host reads the header's PRESENCE, so an empty value is not a
+ * softer version of the request, it is a save asking to be refused.
+ */
+function stampToSend() {
+  const etag = lastSeenEtag();
+  return conditionalSaves() && etag ? etag : null;
+}
+
+/**
+ * The absolute URL a save goes to.
+ *
+ * A relative path is resolved by fetch against the DOCUMENT's base URL, which
+ * `<base href>` sets and the author of a malleable document controls. Left
+ * relative, a `<base href="https://elsewhere.example/">` sends the document and
+ * the per-document token in the path to an origin the document picked. Pinning to
+ * the real origin is the whole fix.
+ *
+ * The guard is not defensive noise. `window.location.origin` is the STRING "null"
+ * on a file:// document, and `new URL(path, "null")` throws a TypeError, which
+ * would escape synchronously here rather than becoming a failed save. Documents
+ * opened from disk are a first-class case (an exported app is just a file), and
+ * there is no origin to pin to and no host to save to there anyway, so the
+ * relative path is both the honest answer and the one that cannot throw.
+ *
+ * @param {string} path - Root-relative save path
+ * @returns {string}
+ */
+function resolveSaveUrl(path) {
+  const origin = window.location.origin;
+  if (!origin || origin === "null") return path;
+  return new URL(path, origin).href;
 }
 
 /**
@@ -152,7 +306,7 @@ function buildSaveRequest(content, userDriven, signal) {
  * @param {string} content - HTML to save
  * @returns {Promise<Object>} The server's response body
  */
-function sendSave(content) {
+function sendOnce(content, saveId, etag) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), SAVE_TIMEOUT_MS);
 
@@ -165,7 +319,8 @@ function sendSave(content) {
   const gestureDriven = consumeUserDriven();
   const explicitlyAsked = consumeExplicitSave();
   const userDriven = gestureDriven || explicitlyAsked;
-  const { url, options } = buildSaveRequest(content, userDriven, controller.signal);
+  const { url, options } = buildSaveRequest(content, userDriven, controller.signal, saveId, etag);
+  rememberSentId(saveId);
 
   return fetch(url, options)
     .then(res => res.text().then(text => {
@@ -181,12 +336,35 @@ function sendSave(content) {
         const error = new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
         error.code = data.code ?? null;
         error.status = res.status;
+        // Spec §6: a conflict may name what moved the document. Only the host can
+        // know, and it often cannot, so this rides through as-is and the notice
+        // falls back to a phrase that is true either way.
+        error.changedBy = data.changedBy ?? null;
+        // §6: the stamp of the bytes that caused the refusal, and the receipt for
+        // them. Both are what let a refusal be recovered from instead of merely
+        // reported: the stamp is what the retry has to carry, and the receipt says
+        // whether the document was moved by this tab's own earlier save.
+        error.etag = data.etag ?? null;
+        error.saveId = data.saveId ?? null;
         throw error;
       }
+      // The one place a stamp is ever learned from a save (§6). A response with no
+      // etag clears it rather than keeping the old one, because the write we just
+      // made means any stamp held here describes bytes the host no longer stores.
+      recordEtag(data.etag ?? null);
+      // A write the host answered: whatever an earlier timeout left uncertain,
+      // this document's version is known again.
+      unknownAttempt = null;
       return data;
     }))
     .catch(err => {
       console.error('Failed to save page:', err);
+      // Spec §7: a timeout is INDETERMINATE. The stamp is deliberately NOT
+      // reconciled against the host here; what this records is the question, so
+      // recovery below can ask it. The old code adopted the host's current stamp
+      // on the guess that our own write was what moved the document, which was
+      // wrong exactly when somebody else wrote.
+      if (err.name === 'AbortError') unknownAttempt = { saveId, etag };
       // The save never landed: re-arm the user-driven bit so the next (retry)
       // save still reports the human gesture instead of reading as background.
       if (userDriven) markUserDriven();
@@ -197,6 +375,150 @@ function sendSave(content) {
     });
 }
 
+/**
+ * Ask the host what became of the attempt whose answer never arrived (spec §7).
+ *
+ * One question, one round trip, and only two things to do with the answer:
+ *
+ *   - the host's receipt is ours, so the bytes it stores are the ones this save
+ *     sent. The save landed. Adopt the stamp for those bytes and report success:
+ *     the person sees a save that worked, because one did.
+ *   - anything else, including a host that keeps no receipts at all: send the save
+ *     again, under the ORIGINAL If-Match.
+ *
+ * The second case looks like it needs to know more than it does, and it does not,
+ * because the stamp is what makes it safe. If our write did land, the stamp is now
+ * stale and the re-send is REFUSED, carrying the host's receipt for the bytes that
+ * refused it; that receipt is ours, and the late-duplicate rule in sendSave turns
+ * it back into a finished save without a word to anybody. If somebody else wrote,
+ * the same refusal carries their bytes and becomes an honest conflict. And if
+ * nothing landed, the stamp still matches and the save simply goes through.
+ *
+ * So there is no branch here that guesses. Every outcome is decided by a host
+ * answering a conditional request, which is the one thing in this protocol that
+ * cannot be wrong.
+ *
+ * A host that cannot be reached leaves the question open, which is the older
+ * behaviour and the honest one: the stamp is kept, the next save is refused rather
+ * than accepted, and the notice says the refusal may be answering this tab's own
+ * timed-out save.
+ *
+ * @returns {Promise<{landed: ?Object, resend: boolean}>}
+ */
+async function recoverUnknownSave() {
+  const attempt = unknownAttempt;
+  if (!attempt) return { landed: null, resend: false };
+
+  const meta = await hostMeta({ fresh: true });
+  const doc = meta.document;
+  const stored = typeof doc?.etag === 'string' && doc.etag ? doc.etag : null;
+  if (!stored) return { landed: null, resend: false };
+
+  // THIS attempt's id, and no other. A receipt is proof about the save that carried
+  // that exact id, so an earlier save of this same tab naming itself proves only
+  // that the earlier save landed, which is a thing already known and says nothing
+  // about this one. Matching any id this tab has sent turns the most ordinary
+  // failure there is, a request that never left the browser, into a reported
+  // success: the tab shows Saved, advances its baselines, drops the close warning,
+  // and the bytes are on no disk anywhere. Membership is the right test one line
+  // down in sendSave, where a 412 only ever leads to another conditional send.
+  if (doc.saveId && doc.saveId === attempt.saveId) {
+    // Proof, not inference: the host is saying the bytes it stores are the stored
+    // form of the body THIS save sent. §6 lets a client adopt a stamp on exactly that.
+    recordEtag(stored);
+    unknownAttempt = null;
+    return { landed: { msg: 'Saved', msgType: 'success', etag: stored }, resend: false };
+  }
+
+  // Positive proof, and nothing weaker, closes the question. A non-empty id that is
+  // not ours names another save as the author of these bytes. An ABSENT id proves
+  // nothing at all: §6 lets a host lose its pair to a restart or an eviction and stay
+  // conforming, so a host that keeps receipts can report none for bytes this tab
+  // really did write. Reading absence as "somebody else wrote" makes the notice tell
+  // a person their own save was somebody else's change.
+  if (doc.saveId) unknownAttempt = null;
+
+  // The re-send carries the stamp the ORIGINAL save carried, which is the normative
+  // rule and not a detail: the stamp this tab holds is mutable and moves for reasons
+  // that have nothing to do with this save, because a disk-sourced live-sync frame
+  // records the stamp of the bytes it applied. Re-sending under that one is a write
+  // conditional on a version this save was never judged against, and the host accepts
+  // it, replacing bytes the person has just been shown with bytes captured before
+  // they arrived.
+  //
+  // No stamp at all means there is nothing to re-send under, so nothing is re-sent.
+  // An unconditional recovery write has no comparison to refuse it and would replace
+  // whatever landed while this tab was waiting, which is the loss this whole
+  // capability exists to prevent.
+  return { landed: null, resend: !!attempt.etag, etag: attempt.etag };
+}
+
+/**
+ * Send one save, and see it through.
+ *
+ * Two things can happen that are not the save's own outcome, and both are handled
+ * here rather than reported:
+ *
+ *   - the request timed out, so the host is asked what became of it,
+ *   - the host refused with a receipt this tab recognises, which means its own
+ *     earlier save is what moved the document. That is a late duplicate, not a
+ *     conflict with anybody: take the stamp the refusal handed back and finish
+ *     the save that was refused.
+ *
+ * Each recovery sends at most one further request, so a save can never loop.
+ *
+ * @param {string} content - HTML to save
+ * @returns {Promise<Object>} The server's response body
+ */
+async function sendSave(content) {
+  // The re-send below is a RETRY of this attempt, so it carries this same id:
+  // whichever of the two requests the host ends up storing, its receipt then
+  // answers for this save. A fresh id on the re-send would leave the first
+  // request's landing unprovable.
+  let saveId = mintSaveId();
+  let etag = stampToSend();
+  // Each recovery runs at most once, and they are counted apart because they are
+  // different things. Re-sending after a timeout is worth doing once: a second
+  // timeout says the host is not answering this document in time, and sending a
+  // whole document a third time will not change that. Resolving a late duplicate
+  // is fast and conclusive, so it gets its own turn regardless.
+  let reSent = false;
+  let duplicateResolved = false;
+  for (;;) {
+    try {
+      return await sendOnce(content, saveId, etag);
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        if (reSent) throw err;
+        const { landed, resend, etag: original } = await recoverUnknownSave();
+        if (landed) return landed;
+        if (!resend) throw err;
+        // Explicitly the original, never `stampToSend()` again.
+        etag = original;
+        reSent = true;
+        continue;
+      }
+
+      if (err.status === 412 && !duplicateResolved && sentByThisTab(err.saveId)) {
+        // Our own earlier save is what the host is refusing us against: a late
+        // duplicate, not a conflict with anybody. Adopt the stamp for those bytes
+        // and send the current ones on top of it. The retry is still conditional,
+        // so anything that arrives in between still refuses it.
+        recordEtag(err.etag ?? null);
+        unknownAttempt = null;
+        saveId = mintSaveId();
+        // A new attempt, deliberately on the base the host just proved is this tab's
+        // own work, rather than on the stamp the refused attempt carried.
+        etag = stampToSend();
+        duplicateResolved = true;
+        continue;
+      }
+
+      throw err;
+    }
+  }
+}
+
 // =============================================================================
 // SAVE FUNCTIONS
 // =============================================================================

package/src/core/save.js

@@ -17,9 +17,11 @@ import {
   getPageContents,
   replacePageWith as replacePageWithCore,
   addDocumentTransform,
-  isSaveInProgress
+  isSaveInProgress,
+  saveFateIsUnknown
 } from "./save-core.js";
 import { captureForComparison, captureForComparisonAndDirty, captureForSaveAndComparison } from "./snapshot.js";
+import { seedEtag } from "./etag.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";
@@ -50,11 +52,12 @@ let savingTimeout = null;
 /**
  * Sets the save status on <html> and dispatches an event.
  *
- * @param {string} state - One of: 'saving', 'saved', 'offline', 'error'
+ * @param {string} state - One of: 'saving', 'saved', 'offline', 'error', 'conflict'
  * @param {string} msg - Optional message (e.g., error details)
  * @param {string} msgType - Optional severity from the server (e.g., 'warning')
+ * @param {Object} [extra] - Extra detail fields for the event (e.g. `changedBy`)
  */
-function setSaveState(state, msg = '', msgType = '') {
+function setSaveState(state, msg = '', msgType = '', extra = null) {
   if (savingTimeout) {
     clearTimeout(savingTimeout);
     savingTimeout = null;
@@ -63,7 +66,7 @@ function setSaveState(state, msg = '', msgType = '') {
   document.documentElement.setAttribute('savestatus', state);
 
   const event = new CustomEvent(`clay:save-${state}`, {
-    detail: { msg, msgType, timestamp: Date.now() }
+    detail: { msg, msgType, timestamp: Date.now(), ...(extra || {}) }
   });
   document.dispatchEvent(event);
 }
@@ -190,6 +193,46 @@ export function resumeAutosave() {
   savePageThrottled();
 }
 
+// ============================================
+// THE CONFLICT HOLD
+// ============================================
+//
+// A 412 refuses this tab's bytes because the document changed since this tab last
+// saw it (spec §6). Two things have to follow, and the second is the one that is
+// easy to leave out.
+//
+// Nothing may be thrown away. The baselines do not advance on a refused save, so
+// the edits stay dirty, the close warning still fires, and the person keeps what
+// they typed. That falls out of applySaveResult and needs no special case.
+//
+// And autosave has to stop. Every autosave from here sends the same stamp and is
+// refused for the same reason, so leaving it running means a save attempt every
+// throttle window, forever, each one toasting a failure the person can do nothing
+// about. The suspension clay.wire already owns is exactly the right lever: it
+// stops AUTOsave only, so an explicit Cmd+S still goes out, and it replays one
+// missed save on release so nothing typed during the hold is stranded.
+//
+// The hold is released when a save lands, whatever produced it: clay.save.overwrite,
+// a live-sync frame that brought the page back in step, or the other tab going away.
+let conflictHold = false;
+
+function holdForConflict() {
+  if (conflictHold) return;
+  conflictHold = true;
+  suspendAutosave();
+}
+
+function releaseConflictHold() {
+  if (!conflictHold) return;
+  conflictHold = false;
+  resumeAutosave();
+}
+
+/** True while this tab is refusing to autosave over a version it has not seen. */
+export function isSaveConflicted() {
+  return conflictHold;
+}
+
 function skipped_(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
@@ -217,6 +260,13 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
     // warning, and the UI module is what decides how to render that.
     setSaveState('saved', result.msg || 'Saved', result.msgType);
     logBaseline(label, `${lastSavedContents.length} chars`);
+    releaseConflictHold();
+  } else if (result.msgType === 'conflict') {
+    holdForConflict();
+    setSaveState('conflict', result.msg, result.msgType, {
+      changedBy: result.changedBy ?? null,
+      afterTimeout: result.afterTimeout === true,
+    });
   } else if (result.msgType !== 'skipped') {
     if (!navigator.onLine) {
       setSaveState('offline', result.msg);
@@ -229,8 +279,18 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
 // Run the save that arrived while this one was in flight. savePage does its own
 // dirty check, so if nothing actually changed it resolves 'skipped' and stops:
 // this cannot spin.
+//
+// Not while the last save's fate is still unknown, which happens only when the
+// save timed out AND the host could not be asked what became of it. Sending then
+// is sending into a question: the host is unreachable, so the save is most likely
+// to time out too, and if it does reach a host that took the first write it is
+// refused, which puts a conflict bar on screen seconds after a person typed,
+// unprompted, over what is really a network problem. The queued state is KEPT, not
+// dropped, so the newer bytes still go out on the next save; the page is still
+// dirty, so an edit or a close warning will produce one.
 function drainPendingSave() {
   if (!pendingSave) return;
+  if (saveFateIsUnknown()) return;
   pendingSave = false;
   savePage();
 }
@@ -405,6 +465,30 @@ export function savePageForce(callback = () => {}) {
   });
 }
 
+/**
+ * Keep this tab's version, over the one the host is holding.
+ *
+ * The only exit from a conflict that keeps what is on screen. It asks the host for
+ * the document's current stamp and force-saves with it, so the save that follows
+ * carries a value the host will accept. If the host answers with no stamp at all,
+ * the save goes out unconditional, which is last write wins, which is what the
+ * person just asked for by name.
+ *
+ * Deliberately not automatic, and deliberately not what a second Cmd+S does. A
+ * person pressing Save again has not been shown the other version, and reading
+ * that as consent to replace it destroys exactly the copy this capability exists
+ * to protect. The other two answers to a conflict need nothing from this library:
+ * `location.reload()` takes the host's version, and a page that wants to merge
+ * merges into its own DOM and then calls this.
+ *
+ * @param {Function} callback - Optional callback for custom handling
+ * @returns {Promise<{ok: boolean, msg: string, msgType: string}>}
+ */
+export async function saveOverwritingConflict(callback = () => {}) {
+  await seedEtag({ fresh: true });
+  return savePageForce(callback);
+}
+
 /**
  * Fetch HTML from a URL and save it, then reload
  * Emits error event if save fails
@@ -646,6 +730,16 @@ export function initHyperclaySaveButton() {
 export function init() {
   if (!isEditMode) return;
 
+  // §6's stamp for a page that has never saved. Fired here and never awaited: the
+  // request a person feels is the save, and a host with no /_/meta would make every
+  // first save wait out a discovery timeout for an answer that was never coming.
+  // Until the seed lands the first save goes out unconditional, which is last write
+  // wins, which is what every save did before this existed. This is also the only
+  // moment the seed can be useful at all: ask for it lazily at the first save and
+  // it can never arrive in time for that save, and from the second save onward the
+  // first save's own response has already supplied one.
+  seedEtag();
+
   // 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.

package/src/core/snapshot.js

@@ -109,10 +109,10 @@ export function addDocumentTransform(callback) {
  *
  * @returns {HTMLElement} Cloned document element with snapshot hooks applied
  */
-function clonePreventingOnclone(node) {
+function clonePreventingOnclone(node, deep = true) {
   const prev = window.__preventOnclone;
   window.__preventOnclone = true;
-  try { return node.cloneNode(true); }
+  try { return node.cloneNode(deep); }
   finally { window.__preventOnclone = prev; }
 }
 
@@ -293,7 +293,13 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
 export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   const clone = captureSnapshot();
 
-  // Emit for live-sync before any stripping
+  // Emit for live-sync before any stripping.
+  //
+  // A listener gets the very clone this function goes on to serialize into
+  // forSave, forComparison and forDirty — that sharing is the point, it saves a
+  // second full DOM clone per save. So a listener may READ it and must not write
+  // to it: anything it changes lands in the saved bytes and in both baselines,
+  // and a baseline the dirty check cannot reproduce warns on close forever.
   if (emitForSync) {
     document.dispatchEvent(new CustomEvent('clay:snapshot-ready', {
       detail: { documentElement: clone }
@@ -445,22 +451,37 @@ export function captureForSave({ emitForSync = true } = {}) {
  * (Not to be confused with captureBodyForSync below, which is the older
  * body-innerHTML helper and unrelated to the live-sync lane.)
  *
- * The clone is detached and unobserved, so removing the attributes in place and
- * putting them back is exact, and far cheaper than cloning the tree again. The
- * finally is load-bearing: the save path reads this same clone afterwards.
+ * It must not write to the clone. The caller derives forSave and both comparison
+ * baselines from this same object once every listener has returned, so anything
+ * left behind lands in the saved bytes and in both baselines.
+ *
+ * This used to strip the tab-local attributes in place and set them again in a
+ * finally, which looked exact and was not: an attribute list is ordered by
+ * insertion, so putting a name back appended it. On htmlclay, whose injectAttr
+ * splices the token and file id in right after `<html`, every save then installed
+ * a baseline whose root tag was ordered differently from the one any later dirty
+ * check builds off the live DOM — same names, same values, same length, never
+ * equal again. Closing an already-saved document warned every time, and
+ * savePageThrottled's "no changes to save" short-circuit never fired.
+ *
+ * The open tag is serialized from a childless copy instead, so the shared clone is
+ * never touched and there is no restore to get wrong. The copy is one element, not
+ * the tree.
  */
 export function serializeForSync(clone) {
-  const removed = [];
-  for (const name of TAB_LOCAL_ROOT_ATTRS) {
-    if (!clone.hasAttribute(name)) continue;
-    removed.push([name, clone.getAttribute(name)]);
-    clone.removeAttribute(name);
-  }
-  try {
-    return clone.outerHTML;
-  } finally {
-    for (const [name, value] of removed) clone.setAttribute(name, value);
-  }
+  const bareRoot = clonePreventingOnclone(clone, false);
+  for (const name of TAB_LOCAL_ROOT_ATTRS) bareRoot.removeAttribute(name);
+
+  // Split the end tag off by LENGTH rather than searching for one: an authored
+  // attribute value holding "</html>" would fool any indexOf-based split and
+  // truncate the broadcast.
+  const shell = bareRoot.outerHTML;
+  const endTag = `</${bareRoot.localName}>`;
+  // The doctype, so this artifact is a complete document like every other one this
+  // module produces. Spec section 2 asks for that, and it costs nothing on the wire:
+  // a receiver parses the string and morphs documentElement against documentElement,
+  // so the prologue is consumed by the parser and never reaches the morph.
+  return "<!DOCTYPE html>" + shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
 }
 
 /**