@panphora/clayjs 1.0.0 → 1.2.0

package/src/sync/live-sync.js

@@ -44,6 +44,7 @@ import { serializeForSync, captureForComparisonAndDirty, captureSnapshot } from
 import { isTabLocalRootAttr } from '../lib/root-attrs.js';
 import { protectPeerDoc, protectDiskDoc, activateIncomingDoc } from './splice-merge.js';
 import { hostMeta } from '../core/host-meta.js';
+import { recordEtag, seedEtag, lastSeenEtag } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate } from '../lib/dirty-gate.js';
 
 // The page just took a frame verified clean against its baseline, so it now IS
@@ -113,6 +114,15 @@ class LiveSync {
 
     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
+    // pairing a fresh stamp with older bytes is the one thing spec §10 forbids.
+    this._savedSnapshot = null;
     this._sendInFlight = false;
     this._queuedSend = null;
 
@@ -154,13 +164,17 @@ class LiveSync {
     this._pendingHtml = null;
     this._pendingSeq = null;
     this._pendingIdentityMap = null;
+    // The stamp a pending frame carries, adopted only if that frame applies
+    // cleanly. It rides in the slot beside the bytes it describes so the two can
+    // never be separated, which is the whole rule (§6, and §22 of the plan).
+    this._pendingEtag = null;
     this._morphInFlight = false;
     this._rafHandle = null;
 
     // Disk-sourced external changes (htmlclay watcher content) get their own
     // one-deep slot so a peer frame arriving in the same window can't
     // displace them. Drained in seq order alongside the peer slot.
-    this._pendingExternal = null;   // { html, seq, saveEpoch }
+    this._pendingExternal = null;   // { html, seq, saveEpoch, etag }
 
     // Newest external-change seq accepted for apply. Replayed or reordered
     // disk frames (and their fetch fallbacks) are dropped against this.
@@ -273,6 +287,7 @@ class LiveSync {
     // so mint a fresh resume id — this stream must not resume the previous one.
     this.lastHtml = null;
     this._lastIdentityMap = null;
+    this._savedSnapshot = null;
     this._applyGen++;
     this.lastSeenSeq = 0;
     this._lastExternalSeq = 0;
@@ -294,7 +309,10 @@ class LiveSync {
     // snapshot listener would never fire — skip registering it.
     if (this.lane === 'live') {
       this.listenForSnapshots();
-      this._saveSavedHandler = () => { this._saveEpoch++; };
+      this._saveSavedHandler = () => {
+        this._saveEpoch++;
+        this._relayCommit();
+      };
       document.addEventListener('clay:save-saved', this._saveSavedHandler);
     }
   }
@@ -517,11 +535,51 @@ class LiveSync {
     const key = lane === 'live' ? '_heldLive' : '_heldExt';
     if (this[key] === isHeld) return;
     this[key] = isHeld;
+    // A hold that clears leaves this tab back in step, but every stamp frame that
+    // arrived while it was held was refused and nothing re-sends them: stamps are
+    // broadcast on a save, not on a merge. So the tab would go on holding a stamp
+    // from before the hold and have its next save refused over a conflict that has
+    // already resolved itself, which is this notice crying wolf. Ask the host for
+    // the current one instead. Only once BOTH lanes are clear, because one lane
+    // resuming while the other still holds means the tab is still behind.
+    if (!isHeld && !this._heldLive && !this._heldExt) {
+      seedEtag({ fresh: true, clearIfMissing: false });
+    }
     document.dispatchEvent(new CustomEvent(isHeld ? 'clay:sync-held' : 'clay:sync-resumed', {
       detail: { lane, el: el || null },
     }));
   }
 
+  /**
+   * Drop a stamp that arrived with no document (spec §6).
+   *
+   * ⚠️ This used to TAKE it, and taking it was wrong. A stamp says "disk is at this
+   * version"; adopting it says "and I hold those bytes". Only the second claim
+   * makes the next save safe, and a frame with no content is no evidence for it.
+   *
+   * The race is real and it loses work. A peer's save and that peer's snapshot
+   * relay are two concurrent requests, so a stamp travelling on its own can arrive
+   * first. This tab would record it while its DOM still held the older content,
+   * and its next save would then pass If-Match and overwrite the save it had never
+   * received. The hold flags cannot cover that: a lane holds when an incoming
+   * change could NOT be merged, not when one has yet to arrive.
+   *
+   * So a stamp now rides on the snapshot the saving tab relays after its save
+   * returns, and `_doApplyUpdate` records it only once that content has merged.
+   * Nothing sends a bare stamp any more — hyperclay's was deleted, and it had
+   * never reached anyone, because the relay library refuses a payload with no
+   * document in it. This stays as the rule rather than as compatibility: if some
+   * host does send one, dropping it is correct.
+   *
+   * @param {Object} data - The decoded frame
+   * @returns {boolean} True when this was a stamp-only frame and nothing should morph
+   */
+  _applyEtagFrame(data) {
+    if (typeof data.etag !== 'string' || typeof data.html === 'string') return false;
+    this._log('Dropping a stamp that arrived with no document: nothing proves this tab holds those bytes');
+    return true;
+  }
+
   /**
    * Connect to the SSE endpoint
    * Uses native EventSource reconnection behavior
@@ -609,6 +667,8 @@ class LiveSync {
         return;
       }
 
+      if (this._applyEtagFrame(data)) return;
+
       const { html, sender, identityMap } = data;
 
       // Ignore own changes — already reflected in the DOM, nothing to morph
@@ -623,9 +683,21 @@ class LiveSync {
         return;
       }
 
+      const etag = typeof data.etag === 'string' && data.etag ? data.etag : null;
+
+      // 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
+      // being equal IS the proof that this tab holds those bytes.
+      if (etag && html === this.lastHtml) {
+        this._log(`Taking the stamp from a peer save of content already applied (seq=${seq})`);
+        recordEtag(etag);
+        return;
+      }
+
       this._log(`Received update from: ${sender} (my clientId: ${this.clientId}, seq=${seq})`);
-      this.applyUpdate(html, seq, identityMap);
-      if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap });
+      this.applyUpdate(html, seq, identityMap, etag);
+      if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap, etag });
     };
 
     // Native EventSource auto-reconnects on transient errors
@@ -662,6 +734,12 @@ class LiveSync {
       this._log('snapshot-ready received, preparing to send');
       const html = serializeForSync(clone);
       const identityMap = this._buildIdentityMap(document.documentElement, clone);
+
+      // The save that follows this capture stores these bytes, so this is the
+      // 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);
     };
 
@@ -708,6 +786,77 @@ class LiveSync {
     this._postUpdate(queued.html, queued.identityMap);
   }
 
+  /**
+   * Tell the other editors what this tab's save stored, and under which stamp.
+   *
+   * 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.
+   */
+  _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.
+    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
+    // older save's bytes under a newer stamp.
+    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.
+    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));
+    });
+  }
+
   _postUpdate(html, identityMap) {
     // Skip if unchanged
     if (html === this.lastHtml) {
@@ -775,7 +924,7 @@ class LiveSync {
     const info = data.data;
     if (info && info.kind === 'external-change') {
       if (typeof info.html === 'string') {
-        this._enqueueExternal(info.html, data.seq);
+        this._enqueueExternal(info.html, data.seq, info.etag);
       } else {
         this._fetchExternalChange(data.seq);
       }
@@ -788,7 +937,7 @@ class LiveSync {
     return false;
   }
 
-  _enqueueExternal(html, seq) {
+  _enqueueExternal(html, seq, etag) {
     if (typeof seq === 'number') {
       if (seq <= this._lastExternalSeq) {
         this._log(`Dropping replayed external change: seq=${seq}`);
@@ -796,7 +945,12 @@ class LiveSync {
       }
       this._lastExternalSeq = seq;
     }
-    this._pendingExternal = { html, seq, saveEpoch: this._saveEpoch };
+    this._pendingExternal = {
+      html,
+      seq,
+      saveEpoch: this._saveEpoch,
+      etag: typeof etag === 'string' && etag ? etag : null,
+    };
     this._scheduleNextFrame();
   }
 
@@ -847,7 +1001,10 @@ class LiveSync {
           }
           return;
         }
-        this._pendingExternal = { html, seq, saveEpoch: epoch };
+        // No stamp: this body came from a GET of the served page, which nobody
+        // stamped, so the apply leaves the held stamp alone and etag.js asks the
+        // host for a replacement.
+        this._pendingExternal = { html, seq, saveEpoch: epoch, etag: null };
         this._scheduleNextFrame();
       })
       .catch((err) => {
@@ -875,11 +1032,15 @@ class LiveSync {
    * @param {number} [seq] - Optional monotonic seq from the server
    * @param {Object} [identityMap] - Optional element-identity map from sender
    */
-  applyUpdate(html, seq, identityMap) {
+  applyUpdate(html, seq, identityMap, etag) {
     if (this.isDestroyed) return;
     this._pendingHtml = html;
     this._pendingSeq = seq;
     this._pendingIdentityMap = identityMap;
+    // A newer frame replacing this one takes its stamp with it, and that is
+    // correct: the stamp belongs to bytes that are no longer what will apply.
+    // Losing it costs one honest 412 later, which is the safe direction.
+    this._pendingEtag = etag ?? null;
     this._scheduleNextFrame();
   }
 
@@ -937,7 +1098,7 @@ class LiveSync {
       } else {
         this._morphInFlight = true;
         try {
-          await this._doApplyExternal(ext.html, ext.seq);
+          await this._doApplyExternal(ext.html, ext.seq, ext.etag);
         } catch (err) {
           console.error('[LiveSync] applyExternal failed:', err);
         } finally {
@@ -948,14 +1109,16 @@ class LiveSync {
       const html = this._pendingHtml;
       const seq = this._pendingSeq;
       const identityMap = this._pendingIdentityMap;
+      const etag = this._pendingEtag;
       this._pendingHtml = null;
       this._pendingSeq = null;
       this._pendingIdentityMap = null;
+      this._pendingEtag = null;
       if (html == null) return;
 
       this._morphInFlight = true;
       try {
-        await this._doApplyUpdate(html, seq, identityMap);
+        await this._doApplyUpdate(html, seq, identityMap, etag);
       } catch (err) {
         console.error('[LiveSync] applyUpdate failed:', err);
       } finally {
@@ -996,7 +1159,7 @@ class LiveSync {
    * @param {Object} [identityMap]
    * @returns {Promise<void>}
    */
-  async _doApplyUpdate(html, seq, identityMap) {
+  async _doApplyUpdate(html, seq, identityMap, etag) {
     this._log('applyUpdate - pausing mutations and morphing');
     this.isPaused = true;
 
@@ -1093,6 +1256,18 @@ class LiveSync {
 
       this._setHeld('live', false);
 
+      // The frame merged, so this tab may take its stamp — but not yet. Adopting
+      // the stamp and applying the bytes have to be the same event, and they only
+      // are once the apply has actually happened. The morph below is awaited and
+      // can reject, and a stamp recorded before it would sit on the old DOM with
+      // nothing to undo it, so the next save would pass If-Match and replace a
+      // version this tab never received. It is recorded after the await, beside
+      // `lastHtml`, on the one path where the bytes definitely landed.
+      //
+      // The hold path above returns before that point, deliberately. A held tab is
+      // knowingly missing what disk holds, and a stamp there would let its next
+      // save replace that change with nobody told.
+
       // Morph entire document. We MUST await — HyperMorph.morph returns a
       // Promise when `scripts: { handle: true }` needs to wait for external
       // scripts to load. If we don't await, Mutation.resume() fires before
@@ -1148,6 +1323,13 @@ class LiveSync {
           : null;
       this._applyGen++;
 
+      // The stamp of section 6, taken now that the bytes it describes are the
+      // bytes this tab is holding. Same line of reasoning as lastHtml directly
+      // 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);
+
       // Cross-lane baseline: the DOM now holds this frame's content, but the
       // DISK baseline (lastSavedContents) still describes pre-frame state. A
       // later dirty disk apply diffing against that stale baseline would
@@ -1210,7 +1392,7 @@ class LiveSync {
    * holds or a later dirty peer apply misclassifies this frame's content as
    * local edits.
    */
-  async _doApplyExternal(html, seq) {
+  async _doApplyExternal(html, seq, etag = null) {
     this._log(`applyExternal - external disk change (seq=${seq})`);
     this.isPaused = true;
 
@@ -1250,7 +1432,7 @@ class LiveSync {
           this._holdRetryExt = setTimeout(() => {
             this._holdRetryExt = null;
             if (this.isDestroyed || this._pendingExternal != null) return;
-            this._pendingExternal = { html, seq, saveEpoch: epochAtHold };
+            this._pendingExternal = { html, seq, saveEpoch: epochAtHold, etag };
             this._scheduleNextFrame();
           }, 3000);
           return;
@@ -1287,6 +1469,17 @@ class LiveSync {
 
       window.scrollTo(scrollX, scrollY);
 
+      // The stamp of section 6, adopted here and nowhere else: this is the moment
+      // the bytes it describes reached this tab. It is taken on the retained-roots
+      // path too, because a merge still incorporates the disk bytes, and the
+      // convergence save at the bottom needs a stamp the host will accept or the
+      // merge is refused and lost.
+      //
+      // 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 (this.lane === 'live' && retainedRoots === 0 && !pageMaybeDirty()) {
         // Clean apply: the DOM now IS the disk state, so a local comparison
         // capture of it is the truthful baseline. The next no-op save skips,
@@ -1308,7 +1501,7 @@ class LiveSync {
       }
 
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'disk' }
+        detail: { seq, source: 'disk', etag: typeof etag === 'string' && etag ? etag : null }
       }));
     } finally {
       this._log('applyExternal - morph complete, resuming mutations');

package/src/ui/index.js

@@ -23,6 +23,13 @@ if (typeof window.toastPersistent === "undefined") window.toastPersistent = toas
 document.addEventListener("clay:save-saved", (e) =>
   toast(e.detail?.msg || "Saved", e.detail?.msgType === "warning" ? "warning" : "success"));
 document.addEventListener("clay:save-error", () => toastPersistent("Couldn't save", "error"));
+// Spec §6. Persistent, and carrying the host's own words, because this is the one
+// save outcome the person has to act on: their edits are safe and unsaved, and
+// autosave has stopped until they choose. Deliberately a toast and not a dialog:
+// most conflicts surface on an autosave nobody asked for, and a modal thrown over
+// the page a person is typing into is worse than the problem it reports.
+document.addEventListener("clay:save-conflict", (e) =>
+  toastPersistent(e.detail?.msg || "This document changed since you opened it", "warning"));
 document.addEventListener("clay:save-offline", () => toastPersistent("Offline, not saved", "warning"));
 
 export { toast, toastPersistent, ask, consent, tell, snippet, themodal };