@panphora/clayjs 1.5.0 → 1.5.2

package/package.json

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

package/src/core/etag.js

@@ -82,7 +82,10 @@ export function forgetEtag() {
 export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
   const at = generation;
   const meta = await hostMeta({ fresh });
-  conditional = meta.extensions.includes("conditional");
+  // Only a real answer (spec is a number) says what the host supports: a refresh
+  // that failed comes back as a bare host with no extensions, and must not switch
+  // conditional saves off for the rest of the page's life.
+  if (typeof meta.spec === "number") conditional = meta.extensions.includes("conditional");
 
   if (generation !== at) return lastSeen;
 

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

@@ -185,6 +185,7 @@ function init() {
   if (!isEditMode) return;
   document.addEventListener("clay:save-conflict", show);
   document.addEventListener("clay:save-saved", hide);
+  document.addEventListener("clay:save-conflict-resolved", hide);
   document.addEventListener("keydown", onKeydown);
 }
 

package/src/core/save-core.js

@@ -208,6 +208,10 @@ function errorResult(err) {
     // 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,
+    // The stamp the host refused this save against: the version that beat it.
+    // Live sync compares it with the frames it merges to know when the refusal
+    // is answered.
+    conflictEtag: conflicted ? (err.etag ?? null) : null,
     etag: null
   };
 }

package/src/core/save.js

@@ -22,7 +22,8 @@ import {
 } 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 { gateCaptureToken, gateClearIfUnchanged, pageMaybeDirty } from "../lib/dirty-gate.js";
+import { autosaveActive } from "../lib/autosave-state.js";
 import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 import { initUserGesture, markExplicitSave, clearExplicitSave } from "../lib/user-gesture.js";
@@ -227,8 +228,10 @@ export function resumeAutosave() {
 // 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;
+let conflictEtag = null;
 
-function holdForConflict() {
+function holdForConflict(etag) {
+  conflictEtag = etag ?? null;
   if (conflictHold) return;
   conflictHold = true;
   suspendAutosave();
@@ -237,6 +240,7 @@ function holdForConflict() {
 function releaseConflictHold() {
   if (!conflictHold) return;
   conflictHold = false;
+  conflictEtag = null;
   resumeAutosave();
 }
 
@@ -245,6 +249,33 @@ export function isSaveConflicted() {
   return conflictHold;
 }
 
+/**
+ * Live sync merged the version the host refused this tab over, and the tab now
+ * holds that version's stamp, so the next save carries a stamp the host accepts.
+ * Only that version answers the refusal: a frame with any other stamp (an older
+ * save arriving late) leaves the hold alone. Autosave resumes, replaying one
+ * missed save. On a manual-save page with unsaved work the root stays in
+ * 'conflict' and the notice stays up until the person saves, since nothing has
+ * been written yet. Not clay:save-saved: no save happened, and that event runs
+ * every [onaftersave] handler.
+ */
+export function conflictResolvedBySync(etag) {
+  if (!conflictHold) return;
+  if (conflictEtag && etag !== conflictEtag) return;
+  conflictHold = false;
+  conflictEtag = null;
+  const awaitingManualSave = !autosaveActive() && pageMaybeDirty();
+  if (!awaitingManualSave) {
+    if (document.documentElement.getAttribute('savestatus') === 'conflict') {
+      document.documentElement.setAttribute('savestatus', 'saved');
+    }
+    document.dispatchEvent(new CustomEvent('clay:save-conflict-resolved', {
+      detail: { timestamp: Date.now() }
+    }));
+  }
+  resumeAutosave();
+}
+
 function skipped_(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
@@ -275,10 +306,11 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken, forS
     logBaseline(label, `${lastSavedContents.length} chars`);
     releaseConflictHold();
   } else if (result.msgType === 'conflict') {
-    holdForConflict();
+    holdForConflict(result.conflictEtag);
     setSaveState('conflict', result.msg, result.msgType, {
       changedBy: result.changedBy ?? null,
       afterTimeout: result.afterTimeout === true,
+      etag: result.conflictEtag ?? null,
     });
   } else if (result.msgType !== 'skipped') {
     if (!navigator.onLine) {

package/src/core/snapshot.js

@@ -464,7 +464,7 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
   // and a baseline the dirty check cannot reproduce warns on close forever.
   if (emitForSync) {
     document.dispatchEvent(new CustomEvent('clay:snapshot-ready', {
-      detail: { documentElement: clone }
+      detail: { documentElement: clone, forSave: true }
     }));
   }
 

package/src/sync/live-sync.js

@@ -11,7 +11,7 @@
  *                              ▼
  *   ┌─────────────────────────────────────────────────────────┐
  *   │  2. SEND          POST snapshot to the relay address    │
- *   │                        (debounced, skip if unchanged)   │
+ *   │                 (after the save lands, with its stamp)  │
  *   └─────────────────────────────────────────────────────────┘
  *                              │
  *                              ▼
@@ -55,7 +55,7 @@ import { presence } from './presence.js';
 // `clay:sync-applied`, which this file is the only dispatcher of.
 import './section-notice.js';
 import { hostMeta } from '../core/host-meta.js';
-import { recordEtag, seedEtag, lastSeenEtag } from '../core/etag.js';
+import { recordEtag, seedEtag, lastSeenEtag, conditionalSaves } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate, gateCaptureToken, gateClearIfUnchanged, gateMarkDirty } from '../lib/dirty-gate.js';
 import { SyncStream } from './stream.js';
 
@@ -144,7 +144,7 @@ function pairedBaseline() {
   const { forComparison, forDirty } = captureForComparisonAndDirty({ flushUndo: false });
   return [forComparison, forDirty];
 }
-import { savePageThrottled, setLastSavedBaselines, setUnsavedChanges, getLastSavedBytes } from '../core/save.js';
+import { savePageThrottled, setLastSavedBaselines, setUnsavedChanges, getLastSavedBytes, conflictResolvedBySync, isSaveConflicted } from '../core/save.js';
 
 /**
  * The two live-sync wires, and the rule for choosing between them.
@@ -227,15 +227,12 @@ class LiveSync {
     // durable per-tab identity used for echo suppression.
     this.resumeId = null;
 
-    this.debounceMs = 150;
-    this.debounceTimer = null;
-
     // The sync serialization of the clone the CURRENT save was captured from,
     // held so the commit relay can pair the host's stamp with the content that
     // stamp actually describes. Set at snapshot-ready, which fires before the
     // save POST goes out, and consumed by _relayCommit when the response lands.
     // Never reconstructed from lastHtml: that is the last relay that COMPLETED,
-    // which lags the save whenever the response beats the 150ms debounce, and
+    // which lags the save whenever an earlier relay is still in flight, and
     // pairing a fresh stamp with older bytes is the one thing spec §10 forbids.
     this._savedSnapshot = null;
     this._sendInFlight = false;
@@ -305,6 +302,7 @@ class LiveSync {
     // equal our state.
     this._saveEpoch = 0;
     this._saveSavedHandler = null;
+    this._saveConflictHandler = null;
 
     // The identityMap that came with lastHtml, so the peer-lane dirty diff
     // can resolve synthetic identities on its base tree.
@@ -467,6 +465,23 @@ class LiveSync {
         this._relayCommit();
       };
       document.addEventListener('clay:save-saved', this._saveSavedHandler);
+      // A 412 can arrive after this tab already merged the version that beat it:
+      // the winner's relay overtook the refusal. The refusal then names a stamp
+      // this tab already holds, and nothing else would ever release the hold.
+      // Deferred a microtask so the conflict notice's own listener has shown the
+      // bar before this hides it.
+      this._saveConflictHandler = (event) => {
+        const refusedBy = event.detail && event.detail.etag;
+        if (!refusedBy) return;
+        queueMicrotask(() => {
+          if (this.isDestroyed) return;
+          if (refusedBy !== lastSeenEtag()) return;
+          if (this.unresolvedConflicts.length) return;
+          conflictResolvedBySync(refusedBy);
+          this._saveAfterMerge(pageMaybeDirty(), false);
+        });
+      };
+      document.addEventListener('clay:save-conflict', this._saveConflictHandler);
     }
   }
 
@@ -494,7 +509,11 @@ class LiveSync {
       this._saveSavedHandler = null;
     }
 
-    clearTimeout(this.debounceTimer);
+    if (this._saveConflictHandler) {
+      document.removeEventListener('clay:save-conflict', this._saveConflictHandler);
+      this._saveConflictHandler = null;
+    }
+
     this._queuedSend = null;
 
     // Cancel any pending frame and clear the queue. A morph already in
@@ -751,6 +770,14 @@ class LiveSync {
 
       const etag = typeof data.etag === 'string' && data.etag ? data.etag : null;
 
+      // On a host that stamps saves, every landed save is relayed with its stamp.
+      // A live-lane frame without one is an older client's preview of a save that
+      // may yet be refused; the stamped frame follows if it lands.
+      if (this.lane === 'live' && !etag && conditionalSaves()) {
+        this._log(`Dropping an unstamped live frame on a stamping host (seq=${seq})`);
+        return;
+      }
+
       // The common case, and it costs nothing: a peer saved bytes this tab has
       // already applied, so the frame's only news is the stamp. Taking it without
       // a morph is exactly as safe as taking it after one, because the baseline
@@ -758,6 +785,10 @@ class LiveSync {
       if (etag && html === this.lastHtml) {
         this._log(`Taking the stamp from a peer save of content already applied (seq=${seq})`);
         recordEtag(etag);
+        if (isSaveConflicted() && this.unresolvedConflicts.length === 0) {
+          conflictResolvedBySync(etag);
+          this._saveAfterMerge(pageMaybeDirty(), false);
+        }
         return;
       }
 
@@ -785,15 +816,15 @@ class LiveSync {
    */
   listenForSnapshots() {
     this._snapshotHandler = (event) => {
+      // Only a save's own capture names what the next landed save stored, and
+      // when. A capture made for any other reason (the public captureForSave)
+      // must not replace the payload that save will relay, nor move its ticket.
+      if (!event.detail || event.detail.forSave !== true) return;
       // Every save captures through this event, before its request goes out,
-      // so this is the moment the save's bytes were true of the document. Taken
-      // ahead of the pause check: a save made during a frame's await is still a
-      // save, and it is newer than that frame.
+      // so this is the moment the save's bytes were true of the document. A
+      // save made during a frame's await is still a save, and it is newer than
+      // that frame.
       this._saveTicket = this._ticket();
-      if (this.isPaused) {
-        this._log('snapshot-ready received but isPaused, skipping');
-        return;
-      }
 
       const { documentElement: clone } = event.detail;
       if (!clone) return;
@@ -810,43 +841,33 @@ class LiveSync {
       // content its stamp will describe. Held for _relayCommit, and overwritten
       // by the next capture, so it always names the save currently in flight.
       this._savedSnapshot = { html, identityMap };
-
-      this.sendUpdate(html, identityMap);
     };
 
     document.addEventListener('clay:snapshot-ready', this._snapshotHandler);
   }
 
   /**
-   * Send full HTML to the server (debounced, single-flight).
+   * Send a landed save's HTML to the relay (single-flight).
    *
    * One POST on the wire at a time, with at most one newer payload queued; a
    * fresher snapshot replaces the queued one, because peers only ever need the
    * latest state. Two concurrent fetches could reach the server in either order,
    * and last-write-wins then stored the OLDER snapshot for every peer.
    */
-  sendUpdate(html, identityMap) {
-    clearTimeout(this.debounceTimer);
-
-    this.debounceTimer = setTimeout(() => {
-      this._enqueueSend(html, identityMap);
-    }, this.debounceMs);
-  }
-
-  _enqueueSend(html, identityMap) {
+  _enqueueSend(html, identityMap, etag = null) {
     // Same one-deep queue the in-flight case uses, for the same reason: peers only
     // ever need the newest state, so a fresher snapshot replaces the waiting one.
     // Sending before the profile is known would have to guess an address.
     if (!this._profile) {
-      this._queuedSend = { html, identityMap };
+      this._queuedSend = { html, identityMap, etag };
       this._resolveProfile().then(() => this._flushQueuedSend());
       return;
     }
     if (this._sendInFlight) {
-      this._queuedSend = { html, identityMap };
+      this._queuedSend = { html, identityMap, etag };
       return;
     }
-    this._postUpdate(html, identityMap);
+    this._postUpdate(html, identityMap, etag);
   }
 
   _flushQueuedSend() {
@@ -854,7 +875,7 @@ class LiveSync {
     const queued = this._queuedSend;
     if (!queued) return;
     this._queuedSend = null;
-    this._postUpdate(queued.html, queued.identityMap);
+    this._postUpdate(queued.html, queued.identityMap, queued.etag);
   }
 
   /**
@@ -862,23 +883,14 @@ class LiveSync {
    *
    * Runs on clay:save-saved, by which point the save response has already been
    * recorded, so `lastSeenEtag()` is the stamp for the bytes that just landed.
-   *
-   * The content is `lastHtml`, the snapshot this tab most recently relayed, which
-   * is the state the save was taken from: the save pipeline dispatches
-   * clay:snapshot-ready on its way to capturing what to send, so that relay has
-   * already gone out. Re-sending those same bytes is not redundant, because the
-   * stamp is the new information and a stamp may never travel without the content
-   * it describes. A receiver whose baseline already matches takes the stamp and
-   * skips the morph.
+   * The content is `_savedSnapshot`, captured by that save's own snapshot-ready
+   * event, never `lastHtml`: a capture is not relayed until its save lands, so
+   * peers only ever see versions the host accepted, each descending from the one
+   * before. A host that returns no stamp still gets the relay, without one.
    */
   _relayCommit() {
-    // Holding a stamp is the whole condition. It is set only from a save response
-    // that carried one, and a host that does not do conditional saves returns
-    // none, so this is the same test as "the host stamps what it stores" without
-    // a second flag that would have to be reached through discovery to exercise.
+    if (this.isDestroyed) return;
     const etag = lastSeenEtag();
-    if (!etag) return;
-    if (this.isDestroyed || this.isPaused) return;
 
     // The content this save stored, captured with it. Consumed rather than left
     // behind, so a save-saved with no capture of its own can never reuse an
@@ -886,51 +898,18 @@ class LiveSync {
     const pending = this._savedSnapshot;
     this._savedSnapshot = null;
 
-    // No captured snapshot means nothing here knows which bytes this stamp
-    // describes, and §10 is explicit that a stamp must never travel on its own.
-    // Staying silent costs the other editors one refusal they recover from;
-    // guessing costs somebody their work.
+    // No captured snapshot means nothing here knows which bytes this save
+    // stored, and §10 is explicit that a stamp must never travel on its own.
     if (!pending || typeof pending.html !== 'string') return;
 
-    this._postCommit(pending.html, etag, pending.identityMap);
-  }
-
-  /**
-   * Post a snapshot whose point is the stamp attached to it.
-   *
-   * Deliberately not `_postUpdate`: that one returns early when the html matches
-   * `lastHtml`, and the whole point here is that the stamp is the new information
-   * even when the bytes are not. It also does not touch `lastHtml` or the
-   * single-flight queue, because it must not displace a real snapshot waiting to
-   * go out. It carries the identityMap captured with these bytes, so a receiver
-   * that morphs on this frame pairs elements the same way it would on the
-   * ordinary relay of the same content.
-   */
-  _postCommit(html, etag, identityMap) {
-    const profile = this._profile;
-    if (!profile) return;
-    fetch(new URL(profile.relayPath, window.location.origin).href, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        [profile.documentHeader]: window.location.href,
-      },
-      body: JSON.stringify({
-        [profile.snapshotKey]: html,
-        sender: this.clientId,
-        identityMap,
-        etag
-      })
-    }).catch(err => {
-      // Losing this costs the other editors one spurious refusal on their next
-      // save, which they recover from. It is not worth surfacing as an error.
-      this._log('Commit relay failed: ' + (err && err.message));
-    });
+    this._enqueueSend(pending.html, pending.identityMap, etag || null);
   }
 
-  _postUpdate(html, identityMap) {
-    // Skip if unchanged
-    if (html === this.lastHtml) {
+  _postUpdate(html, identityMap, etag = null, attempt = 0) {
+    // Skip only an unstamped repeat. A landed save is news even when its bytes
+    // equal the last relay: "Keep mine" can restore exactly those bytes after
+    // the peers moved on, and they must hear it.
+    if (!etag && html === this.lastHtml) {
       this._log('Skipping send - HTML unchanged');
       return;
     }
@@ -939,6 +918,7 @@ class LiveSync {
 
     this._sendInFlight = true;
     const gen = this._applyGen;
+    let retry = false;
 
     // Absolute against the real origin, so a <base href> in the page cannot
     // redirect the whole document to an origin the author picked.
@@ -952,7 +932,8 @@ class LiveSync {
       body: JSON.stringify({
         [profile.snapshotKey]: html,
         sender: this.clientId,
-        identityMap: identityMap
+        identityMap: identityMap,
+        ...(etag ? { etag } : {})
       })
     }).then(response => {
       if (response.ok) {
@@ -968,15 +949,33 @@ class LiveSync {
         }
       } else {
         console.warn('[LiveSync] Save returned status:', response.status);
+        retry = response.status >= 500 || response.status === 408 || response.status === 429;
       }
     }).catch(err => {
       console.error('[LiveSync] Save failed:', err);
       if (this.onError) this.onError(err);
+      retry = true;
     }).finally(() => {
       this._sendInFlight = false;
       const queued = this._queuedSend;
       this._queuedSend = null;
-      if (queued) this._postUpdate(queued.html, queued.identityMap);
+      if (queued) {
+        this._postUpdate(queued.html, queued.identityMap, queued.etag);
+        return;
+      }
+      // The relay of a landed save is the only one peers get, so a transient
+      // failure is retried a few times. A newer save queued meanwhile replaces
+      // it: peers only need the latest.
+      if (!retry || !etag || attempt >= 3 || this.isDestroyed) return;
+      this._sendInFlight = true;
+      setTimeout(() => {
+        this._sendInFlight = false;
+        if (this.isDestroyed) return;
+        const newer = this._queuedSend;
+        this._queuedSend = null;
+        if (newer) this._postUpdate(newer.html, newer.identityMap, newer.etag);
+        else this._postUpdate(html, identityMap, etag, attempt + 1);
+      }, 500 * 2 ** attempt);
     });
   }
 
@@ -1445,6 +1444,7 @@ class LiveSync {
 
     let diverged = false;
     let typedDuringWait = false;
+    let stamped = false;
     try {
       // Hold the whole frame only when this tab has unsaved edits and no
       // baseline to merge them against (the first frame of a fresh
@@ -1522,7 +1522,10 @@ class LiveSync {
       // above, and deliberately the same moment: the two claims a page makes
       // when it adopts a stamp are "the host stores this version" and "I hold
       // it", and only the second one is this tab's to make.
-      if (typeof etag === 'string' && etag) recordEtag(etag);
+      if (typeof etag === 'string' && etag) {
+        recordEtag(etag);
+        stamped = true;
+      }
 
       // Cross-lane baseline: the DOM now holds this frame's content, but the
       // DISK baseline (lastSavedContents) still describes pre-frame state. A
@@ -1593,9 +1596,12 @@ class LiveSync {
     // edits + their frame) that exists only in this DOM. Push it out explicitly
     // — the morph ran under Mutation.pause, so no autosave was triggered, and a
     // pending autosave debounce may already have fired mid-flight. Runs after
-    // isPaused is lifted so the save's snapshot-ready relay reaches peers.
+    // isPaused is lifted so the convergence save's relay reaches peers.
     // Only where autosave is on: a manual-save page must never auto-write, so
     // there the merge stays local, still dirty, until the person saves.
+    // Not over a lost conflict: the hold and its bar stay up as the signal that
+    // this tab lost text, until the person saves.
+    if (stamped && this.unresolvedConflicts.length === 0) conflictResolvedBySync(etag);
     this._saveAfterMerge(diverged, typedDuringWait);
   }
 
@@ -1626,6 +1632,7 @@ class LiveSync {
 
     let diverged = false;
     let typedDuringWait = false;
+    let stamped = false;
     try {
       // Hold the whole frame only when this tab has unsaved edits and no
       // baseline to merge them against. Lane-guarded like the peer path: a
@@ -1682,7 +1689,10 @@ class LiveSync {
       // A frame with no stamp (an older host, or the content-less fetch fallback,
       // which serves bytes nobody stamped) leaves this alone, and the listener in
       // etag.js falls back to asking the host.
-      if (typeof etag === 'string' && etag) recordEtag(etag);
+      if (typeof etag === 'string' && etag) {
+        recordEtag(etag);
+        stamped = true;
+      }
 
       if (
         this.lane === 'live' &&
@@ -1733,6 +1743,9 @@ class LiveSync {
     // (our edits + their bytes). The baseline was left pre-external, so the
     // save sees both as changes and writes the merge back. Only where
     // autosave is on, as in the peer lane.
+    // Not over a lost conflict: the hold and its bar stay up as the signal that
+    // this tab lost text, until the person saves.
+    if (stamped && this.unresolvedConflicts.length === 0) conflictResolvedBySync(etag);
     this._saveAfterMerge(diverged, typedDuringWait);
   }