@panphora/clayjs 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",

package/src/core/etag.js

@@ -15,8 +15,9 @@
  *   - an accepted save replaces it with the one that response carried, and clears
  *     it when a response carries none: after our own write, any stamp still held
  *     here is known to describe bytes the host has stopped storing,
- *   - a disk-sourced live-sync frame clears it and asks for a fresh one, because
- *     the file changed under a tab that never saved.
+ *   - a disk-sourced live-sync frame replaces it with the stamp that frame
+ *     carried, because the file changed under a tab that never saved. A frame
+ *     with no stamp on it falls back to clearing and asking the host.
  *
  * A peer's SNAPSHOT does not move it. §10 relays never write to disk, so the
  * stamp is still true after one lands, and treating one as a disk change would
@@ -99,8 +100,19 @@ export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
 // A disk-sourced frame is the one live-sync outcome that changes the file under a
 // tab which did not save it. Holding the old stamp would refuse this tab's next
 // save against bytes it has already morphed to and is looking at, so the stamp
-// goes immediately and the replacement is asked for in the background: the save
-// lane never waits on it.
+// has to move.
+//
+// The frame's own stamp is the right one, and live-sync has already taken it as
+// part of applying the frame's content. Nothing is left to do here: this listener
+// exists for the frames that carry no stamp.
+//
+// Asking the host is the fallback and not the rule, because discovery answers
+// about whatever is on disk when the ANSWER is built, which is a later moment
+// than the frame. If a second write lands in between, the reply describes bytes
+// this tab has never seen, and adopting it makes the next save overwrite that
+// write silently. The frames without a stamp are an old host, and the fetch
+// fallback for a change too large to send, whose body is the served page rather
+// than anything the host stamped.
 //
 // A frame that live-sync HELD is deliberately not covered, because it never
 // dispatches this event. That tab has unsaved local edits and has not seen the
@@ -108,6 +120,7 @@ export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
 if (isEditMode) {
   document.addEventListener("clay:sync-applied", (event) => {
     if (event.detail?.source !== "disk") return;
+    if (typeof event.detail.etag === "string" && event.detail.etag) return;
     forgetEtag();
     seedEtag({ fresh: true });
   });

package/src/core/host-attrs.js

@@ -7,7 +7,33 @@
  * cannot drift between the edit-mode ladder and the save lane.
  */
 
-import { SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
+import { SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
+
+let warnedAboutLegacyToken = false;
+
+/**
+ * Say so, once, when this response carries only the pre-rename save token.
+ *
+ * Dropping the old spelling is a deliberate break (see root-attrs.js), and its failure
+ * mode is the kind worth spending five lines on: the host that serves the old name also
+ * sets the edit-mode cookie, so the page stays editable and every save 404s. Without
+ * this the reader sees a working page that quietly keeps nothing. With it the console
+ * names the cause and the fix, which is the whole difference between a break and a bug.
+ */
+function warnAboutLegacyToken() {
+  if (warnedAboutLegacyToken) return;
+  const carries = LEGACY_SAVE_TOKEN_ATTRS.some(
+    (attr) => document.documentElement.getAttribute(attr)
+  );
+  if (!carries) return;
+  warnedAboutLegacyToken = true;
+  console.warn(
+    "[clay] This page was served with the pre-1.9.0 save token (" +
+      LEGACY_SAVE_TOKEN_ATTRS.join(", ") +
+      "), which this version no longer accepts. Saving will fail until the host is " +
+      "updated. If this is HTML Clay, upgrade it to 1.9.0 or newer."
+  );
+}
 
 /**
  * The per-document save token this response carries, or null.
@@ -24,13 +50,37 @@ export function saveToken() {
     const value = document.documentElement.getAttribute(attr);
     if (value) return value;
   }
+  warnAboutLegacyToken();
   return null;
 }
 
 /**
- * True when the host handed this response a save token of either spelling.
+ * True when the host handed this response a save token this version accepts.
+ *
+ * Only `savetoken` counts. A response carrying nothing but the pre-rename spelling is
+ * FALSE here and true from `servedStaleToken()`, which is the whole point of the pair.
+ *
  * @returns {boolean}
  */
 export function hasSaveToken() {
   return saveToken() !== null;
 }
+
+/**
+ * True when this response carries ONLY the pre-rename save token.
+ *
+ * That combination means one thing: the host is older than the rename and cannot be
+ * saved to by this version. It is worth its own name because two separate things act
+ * on it. Edit mode goes off, so the page does not offer editing it cannot keep, and
+ * stale-host-notice.js says why on the page, since the console line reaches a
+ * developer and nobody else.
+ *
+ * @returns {boolean}
+ */
+export function servedStaleToken() {
+  if (typeof document === "undefined") return false;
+  if (saveToken() !== null) return false;
+  return LEGACY_SAVE_TOKEN_ATTRS.some(
+    (attr) => document.documentElement.getAttribute(attr)
+  );
+}

package/src/core/is-edit-mode.js

@@ -1,11 +1,11 @@
 import cookie from "../lib/cookie.js";
 import query from "../lib/query.js";
-import { hasSaveToken } from "./host-attrs.js";
+import { hasSaveToken, servedStaleToken } from "./host-attrs.js";
 
 // Edit-mode precedence: an explicit ?editmode=true|false URL param wins, then an
 // opt-in window.clayEditMode global (with the legacy window.__hyperclayEditMode
 // still honored as a fallback for older standalone embedders — htmlclay itself
-// uses the injected htmlclaytoken plus the admin cookie, not this global), then
+// uses its injected save token plus the admin cookie, not this global), then
 // a save token the host put on the root, then the isAdminOfCurrentResource cookie. The
 // global is for standalone uses (demos, htmlclay, any self-saving file) that are
 // always editable and have no owner cookie; setting it before clayjs loads turns
@@ -25,11 +25,20 @@ if (typeof window !== "undefined") {
   }
 }
 
+// A host older than the save-token rename takes edit mode off the table, above every
+// rung below it. Such a host still sets the owner cookie, so without this the page
+// would look fully editable while every save 404s against a route that no longer
+// matches: an editable page that keeps nothing is worse than a read-only one. Only an
+// explicit ?editmode=true outranks it, because that is a person at the keyboard asking
+// for it this load, not a decision baked into the document by an author who could not
+// have known. stale-host-notice.js puts the reason on the page.
 const isEditMode = query.editmode
   ? query.editmode === "true" // takes precedence over the global, token and cookie
-  : forcedEditMode != null
-    ? forcedEditMode
-    : hasSaveToken() || Boolean(cookie.get("isAdminOfCurrentResource"));
+  : servedStaleToken()
+    ? false
+    : forcedEditMode != null
+      ? forcedEditMode
+      : hasSaveToken() || Boolean(cookie.get("isAdminOfCurrentResource"));
 
 const isOwner = Boolean(cookie.get("isAdminOfCurrentResource"));
 

package/src/core/save-conflict-notice.js

@@ -1,5 +1,6 @@
 import { isEditMode } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
+import { style, set, make } from "../lib/hostile-css.js";
 
 // The page's only word on a refused save. Without it a document whose host said no
 // looks exactly like one that is saving fine, while autosave sits suspended: the
@@ -33,31 +34,6 @@ let armTimer = null, armed = false, busy = false;
 
 const still = () => !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
 
-// Every declaration goes on as !important, and this is the whole reason the notice
-// survives a stranger's page. A plain inline style loses to an author rule that
-// carries !important, and `button { ... !important }` is a thing real pages do: the
-// first browser run of this module had both controls repainted in the host's colours
-// and font. Only an inline !important outranks an author !important.
-function style(el, rules) {
-  for (const rule of rules) {
-    const at = rule.indexOf(":");
-    el.style.setProperty(rule.slice(0, at).trim(), rule.slice(at + 1).trim(), "important");
-  }
-}
-
-// Same reason: a later assignment must be able to beat the !important one already
-// sitting on the element, and a plain style.foo = x silently cannot.
-function set(el, prop, value) {
-  el.style.setProperty(prop, value, "important");
-}
-
-function make(tag, rules, text) {
-  const el = document.createElement(tag);
-  style(el, rules);
-  if (text) el.textContent = text;
-  return el;
-}
-
 // all:initial first, because a page restyling every button is the normal case, not
 // the adversarial one. Everything the control needs is restated after it.
 function button(label, rules) {
@@ -171,8 +147,27 @@ function onKeydown(e) {
 function show(e) {
   if (!root) build();
   set(root, "display", "flex");
-  const where = SOURCES[e?.detail?.changedBy] || "elsewhere";
-  line.textContent = `This page was updated ${where}. Saving is paused.`;
+  const named = SOURCES[e?.detail?.changedBy];
+  // Reassurance first, then the fact. What a person needs to know at this moment
+  // is that nothing of theirs is gone and nothing is about to be overwritten; the
+  // detail of what happened is the second half of the sentence, not the first.
+  // "Saving is paused" led here once and read as a failure, which it is not: the
+  // page is holding a version, and the two buttons below are the whole decision.
+  //
+  // An earlier save of this tab's timed out and the host could not say what became
+  // of it, so this refusal may be answering that write rather than anybody else's.
+  // Saying so is the whole reason the stamp is kept across a timeout instead of
+  // quietly reconciled. A host that NAMED the writer, or that answered the question
+  // with a receipt, knows better than this guess, so the name wins.
+  if (!named && e?.detail?.afterTimeout) {
+    line.textContent =
+      "This page changed elsewhere, possibly by your own save that timed out. " +
+      "Your edits here are safe, and nothing will be overwritten until you choose.";
+  } else {
+    line.textContent =
+      `This page changed ${named || "elsewhere"}. ` +
+      "Your edits here are safe, and nothing will be overwritten until you choose.";
+  }
   keep.textContent = "Keep mine";
   set(keep, "opacity", "1");
   busy = false;

package/src/core/save-core.js

@@ -10,7 +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, seedEtag } from "./etag.js";
+import { lastSeenEtag, conditionalSaves, recordEtag } from "./etag.js";
+import { hostMeta } from "./host-meta.js";
 import {
   getPageContents,
   onSnapshot,
@@ -61,6 +62,93 @@ 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
@@ -68,9 +156,13 @@ function errorResult(err) {
   // 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), and `code` is honoured too because a proxy
-  // can answer 412 on the host's behalf with no body at all.
-  const conflicted = !timedOut && (err.status === 412 || err.code === 'conflict');
+  // 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'),
@@ -78,6 +170,10 @@ function errorResult(err) {
     // so this reports "we do not know" rather than asserting something false.
     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
   };
 }
@@ -122,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 = {
@@ -138,25 +236,36 @@ 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
   };
 
-  // Spec §6: the stamp this tab last saw, so a host that advertises `conditional`
-  // can refuse rather than overwrite a version nobody here has read.
-  //
-  // 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 this header's PRESENCE, so an empty value is
-  // not a softer version of the request, it is a save asking to be refused.
-  const etag = lastSeenEtag();
-  if (conditionalSaves() && etag) options.headers['If-Match'] = etag;
+  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.
  *
@@ -197,7 +306,7 @@ function resolveSaveUrl(path) {
  * @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);
 
@@ -210,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 => {
@@ -226,24 +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, so this write may well have landed,
-      // and the stamp held here may already describe bytes the host has replaced.
-      // Reconcile against the host before anything retries, or a save that times
-      // out and lands is followed by a 412 the person cannot explain and did not
-      // cause. The only save that can have moved the document inside that window
-      // is almost always this one, so taking the host's current stamp is taking
-      // back our own.
-      if (err.name === 'AbortError') seedEtag({ fresh: true });
+      // 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();
@@ -254,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
 // =============================================================================