@panphora/clayjs 1.1.0 → 1.3.0

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,
@@ -25,6 +26,17 @@ let saveInProgress = false;
 const SAVE_PATH = '/_/save';
 const SAVE_TIMEOUT_MS = 12000;
 
+// Listeners for "the host took these exact bytes". This is the only place in the
+// library that knows both the body that went out and that the host accepted it, and
+// the two together are what make the bytes a fact about the file rather than a guess:
+// a capture says what we would send, a success says a write happened, and only their
+// conjunction says what is on disk. The source map uses it to re-model, so the next
+// save is measured from the file as it now is.
+//
+// Not a DOM event, deliberately. The whole document rides in the argument, and a
+// CustomEvent would put it on a bus any script on the page can listen to.
+const saveAcceptedHooks = [];
+
 /**
  * Check if a save is currently in progress.
  * @returns {boolean}
@@ -33,6 +45,29 @@ export function isSaveInProgress() {
   return saveInProgress;
 }
 
+/**
+ * Run a callback with the bytes the host just accepted.
+ *
+ * Called once per accepted save, after the response, with the exact body that was
+ * sent. Never called for a refused, failed or skipped save, and never in test mode,
+ * where nothing reached a host.
+ *
+ * @param {Function} callback - Receives the accepted HTML string
+ */
+export function onSaveAccepted(callback) {
+  saveAcceptedHooks.push(callback);
+}
+
+function notifySaveAccepted(html) {
+  for (const hook of saveAcceptedHooks) {
+    try {
+      hook(html);
+    } catch (err) {
+      console.error('clayjs: onSaveAccepted hook failed:', err);
+    }
+  }
+}
+
 // =============================================================================
 // RE-EXPORTS FROM SNAPSHOT (for backwards compat)
 // =============================================================================
@@ -61,6 +96,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 +190,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 +204,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 +252,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 +270,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 +340,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 +353,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 +370,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 +409,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
 // =============================================================================
@@ -304,6 +603,7 @@ export function saveHtml(html, callback = () => {}) {
       // is busy by the save that just finished.
       .then(result => {
         saveInProgress = false;
+        if (result.ok) notifySaveAccepted(html);
         done(result);
       });
   });

package/src/core/save.js

@@ -17,7 +17,8 @@ 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";
@@ -54,8 +55,9 @@ let savingTimeout = null;
  * @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;
@@ -64,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);
 }
@@ -261,7 +263,10 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
     releaseConflictHold();
   } else if (result.msgType === 'conflict') {
     holdForConflict();
-    setSaveState('conflict', result.msg, result.msgType);
+    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);
@@ -274,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();
 }