@panphora/clayjs 0.4.3 → 0.6.0

package/src/sync/live-sync.js

@@ -40,8 +40,11 @@ import Mutation from "../lib/mutation.js";
 import { isSnapshotRemoved } from "../lib/region-policy.js";
 import { isEditMode } from "../core/is-edit-mode.js";
 import { mergeTagRecognizers } from "./merge-tags.js";
-import { serializeForSync } from '../core/snapshot.js';
+import { serializeForSync, captureForComparison, captureSnapshot } from '../core/snapshot.js';
 import { isTabLocalRootAttr } from '../lib/root-attrs.js';
+import { protectPeerDoc, protectDiskDoc, activateIncomingDoc } from './splice-merge.js';
+import { pageMaybeDirty, pauseGate, resumeGate } from '../lib/dirty-gate.js';
+import { savePageThrottled, setLastSavedContents, setUnsavedChanges } from '../core/save.js';
 
 class LiveSync {
   constructor() {
@@ -94,6 +97,38 @@ class LiveSync {
     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 }
+
+    // Newest external-change seq accepted for apply. Replayed or reordered
+    // disk frames (and their fetch fallbacks) are dropped against this.
+    this._lastExternalSeq = 0;
+
+    // Bumped on every own save success. A queued disk frame older than our
+    // own landed save is stale by construction: the save just made disk
+    // equal our state.
+    this._saveEpoch = 0;
+    this._saveSavedHandler = null;
+
+    // The identityMap that came with lastHtml, so the peer-lane dirty diff
+    // can resolve synthetic identities on its base tree.
+    this._lastIdentityMap = null;
+
+    // Bumped whenever an APPLY (or a reset) rewrites lastHtml. A POST's
+    // success callback carries no ordering guarantee against the SSE stream,
+    // so a delayed response must not rewind lastHtml past a frame that
+    // applied while it was on the wire.
+    this._applyGen = 0;
+
+    // Hold-retry timers, one per pending slot. A held frame's slot and seq
+    // watermark have already advanced, so nothing redelivers it; the retry
+    // re-queues the same payload so it applies if the blocking local edit is
+    // undone, and is dropped by the seq/epoch checks if it went stale.
+    this._holdRetryPeer = null;
+    this._holdRetryExt = null;
+
     // Identity tracking for content-based morphing across live-sync updates.
     // Synthetic IDs (`<clientId>:<counter>`) live here only — never written to
     // the DOM, never serialized into saved HTML. The WeakMap holds them
@@ -171,7 +206,11 @@ class LiveSync {
     // Reset state for new connection. Resetting lastSeenSeq is a new baseline,
     // so mint a fresh resume id — this stream must not resume the previous one.
     this.lastHtml = null;
+    this._lastIdentityMap = null;
+    this._applyGen++;
     this.lastSeenSeq = 0;
+    this._lastExternalSeq = 0;
+    this._pendingExternal = null;
     this.resumeId = this.generateResumeId();
 
     console.log(`[LiveSync] Starting for: ${this.currentFile} (lane=${this.lane})`);
@@ -180,6 +219,8 @@ class LiveSync {
     // snapshot listener would never fire — skip registering it.
     if (this.lane === 'live') {
       this.listenForSnapshots();
+      this._saveSavedHandler = () => { this._saveEpoch++; };
+      document.addEventListener('clay:save-saved', this._saveSavedHandler);
     }
   }
 
@@ -198,6 +239,11 @@ class LiveSync {
       this._snapshotHandler = null;
     }
 
+    if (this._saveSavedHandler) {
+      document.removeEventListener('clay:save-saved', this._saveSavedHandler);
+      this._saveSavedHandler = null;
+    }
+
     clearTimeout(this.debounceTimer);
     this._queuedSend = null;
 
@@ -211,6 +257,11 @@ class LiveSync {
     this._pendingHtml = null;
     this._pendingSeq = null;
     this._pendingIdentityMap = null;
+    this._pendingExternal = null;
+    clearTimeout(this._holdRetryPeer);
+    clearTimeout(this._holdRetryExt);
+    this._holdRetryPeer = null;
+    this._holdRetryExt = null;
   }
 
   _mintId() {
@@ -295,21 +346,23 @@ class LiveSync {
    * the same logical elements, breaking convergence for newly-added
    * ambiguous siblings — exactly the case identity-map exists to fix.
    *
-   * Walks live and parsed in lockstep using the same path scheme as
-   * _buildIdentityMap. Filters [snapshot-remove] from the live side to
-   * stay aligned with the sender's clone view. Aborts a subtree on
-   * child-count divergence (e.g. local save-ignore additions) — those
-   * elements fall through to content scoring on the next round, which
-   * is the same fallback as a sender-side lockstep skip.
+   * Walks live and parsed in lockstep, reading ids off the parsed NODES
+   * (parsedWeakMap) rather than re-deriving dot-paths: a protected splice
+   * shifts paths, but the WeakMap entries ride the nodes and stay correct.
+   * Filters [snapshot-remove] from the live side to stay aligned with the
+   * sender's clone view. Aborts a subtree on child-count divergence (e.g.
+   * local save-ignore additions) — those elements fall through to content
+   * scoring on the next round, which is the same fallback as a sender-side
+   * lockstep skip.
    *
    * @param {Element} liveRoot - post-morph live tree root
-   * @param {Element} parsedRoot - parsed-tree root (still has identityMap WeakMap entries)
-   * @param {Object} identityMap - path → id map from the SSE payload
+   * @param {Element} parsedRoot - parsed-tree root
+   * @param {WeakMap} parsedWeakMap - parsed node → synthetic id
    */
-  _fillInIdsAfterMorph(liveRoot, parsedRoot, identityMap) {
-    if (!liveRoot || !parsedRoot || !identityMap) return;
-    const visit = (live, parsed, path) => {
-      const id = identityMap[path];
+  _fillInIdsAfterMorph(liveRoot, parsedRoot, parsedWeakMap) {
+    if (!liveRoot || !parsedRoot || !parsedWeakMap) return;
+    const visit = (live, parsed) => {
+      const id = parsedWeakMap.get(parsed);
       if (id && !this.liveWeakMap.has(live)) {
         this.liveWeakMap.set(live, id);
       }
@@ -320,10 +373,10 @@ class LiveSync {
       const parsedKids = parsed.children;
       if (liveKids.length !== parsedKids.length) return;
       for (let i = 0; i < liveKids.length; i++) {
-        visit(liveKids[i], parsedKids[i], path === '' ? String(i) : `${path}.${i}`);
+        visit(liveKids[i], parsedKids[i]);
       }
     };
-    visit(liveRoot, parsedRoot, '');
+    visit(liveRoot, parsedRoot);
   }
 
   /**
@@ -370,6 +423,34 @@ class LiveSync {
       if (this.onConnect) this.onConnect();
     };
 
+    // The cursor frame is a NAMED SSE event, so it never reaches onmessage and
+    // never looks like data. Its `resync` flag says the server could not retain
+    // everything between where this client resumed and the baseline it is
+    // sending: what this page holds is stale in a way no replay will fix.
+    //
+    // The repair is the token-free fetch of the served document this class
+    // already runs for a change too large to send, so noticing the flag is the
+    // whole of the work.
+    this.sse.addEventListener('cursor', (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      if (!data || data.resync !== true) return;
+      console.log('[LiveSync] Server could not replay everything; refetching the document');
+      // _fetchServedDocument, deliberately, and not _fetchExternalChange: that
+      // one drops a fetch whose seq is at or below the external watermark, and
+      // the cursor baseline routinely is, since it is the server's high-water
+      // mark and our own last applied change may already have reached it. A
+      // resync that skipped itself for being "already seen" would leave the page
+      // permanently stale, which is the exact failure the flag exists to report.
+      this._fetchServedDocument(typeof data.seq === 'number' ? data.seq : undefined, {
+        repair: true,
+      });
+    });
+
     this.sse.onmessage = (event) => {
       const data = JSON.parse(event.data);
 
@@ -393,8 +474,11 @@ class LiveSync {
         this.lastSeenSeq = seq;
       }
 
-      // Handle notifications (show toast, don't morph)
+      // External disk changes ride the notification channel as first-class
+      // content (data.kind === 'external-change'). They apply silently —
+      // Google-Docs-style — so a handled one never reaches the toast branch.
       if (data.type === "notification") {
+        if (this._maybeAcceptExternalChange(data)) return;
         this.handleNotification(data);
         return;
       }
@@ -499,6 +583,7 @@ class LiveSync {
     this._log(`Sending update (HTML length: ${html.length}, lastHtml length: ${this.lastHtml?.length || 0})`);
 
     this._sendInFlight = true;
+    const gen = this._applyGen;
 
     // Absolute against the real origin, so a <base href> in the page cannot
     // redirect the whole document to an origin the author picked.
@@ -512,7 +597,16 @@ class LiveSync {
       })
     }).then(response => {
       if (response.ok) {
-        this.lastHtml = html;
+        // A frame that applied while this POST was on the wire has already
+        // advanced lastHtml past this snapshot; assigning would rewind the
+        // diff base to pre-frame state and misclassify the frame's content
+        // as local edits on the next dirty apply.
+        if (this._applyGen === gen) {
+          this.lastHtml = html;
+          this._lastIdentityMap = identityMap || null;
+        } else {
+          this._log('Skipping lastHtml advance: a frame applied during the POST');
+        }
       } else {
         console.warn('[LiveSync] Save returned status:', response.status);
       }
@@ -527,6 +621,107 @@ class LiveSync {
     });
   }
 
+  /**
+   * Route an external disk change (htmlclay watcher) out of the notification
+   * path. Returns true when the notification was consumed — the caller must
+   * then skip the toast branch entirely (silent UX).
+   *
+   * New servers mark these with data.kind === 'external-change' and embed the
+   * disk HTML (omitted only when it exceeds the server's size cap). Old
+   * servers send a bare warning with the watcher's fixed message shape; both
+   * content-less forms fall back to a token-free fetch of the served page.
+   */
+  _maybeAcceptExternalChange(data) {
+    if (this.lane !== 'live') return false;
+    const info = data.data;
+    if (info && info.kind === 'external-change') {
+      if (typeof info.html === 'string') {
+        this._enqueueExternal(info.html, data.seq);
+      } else {
+        this._fetchExternalChange(data.seq);
+      }
+      return true;
+    }
+    if (typeof data.msg === 'string' && data.msg.endsWith('changed on disk outside this tab')) {
+      this._fetchExternalChange(data.seq);
+      return true;
+    }
+    return false;
+  }
+
+  _enqueueExternal(html, seq) {
+    if (typeof seq === 'number') {
+      if (seq <= this._lastExternalSeq) {
+        this._log(`Dropping replayed external change: seq=${seq}`);
+        return;
+      }
+      this._lastExternalSeq = seq;
+    }
+    this._pendingExternal = { html, seq, saveEpoch: this._saveEpoch };
+    this._scheduleNextFrame();
+  }
+
+  /**
+   * Content-less fallback: fetch the served document. The request carries no
+   * Sec-Fetch-Dest: document, so htmlclay serves it token-free; the morph's
+   * root-attribute veto keeps this tab's own token either way. The result is
+   * stamped with the triggering notification's seq and dropped if a newer
+   * external change (or our own save) landed while it was in flight.
+   */
+  _fetchExternalChange(seq) {
+    if (typeof seq === 'number') {
+      if (seq <= this._lastExternalSeq) return;
+      this._lastExternalSeq = seq;
+    }
+    this._fetchServedDocument(seq);
+  }
+
+  /**
+   * GET the served document and queue it as an external change. No watermark
+   * check of its own — callers own that — so it can also re-materialize a
+   * frame the epoch check refused (the fetched body is whatever disk holds
+   * NOW, which is always safe to apply).
+   */
+  _fetchServedDocument(seq, { attempt = 0, repair = false } = {}) {
+    const epoch = this._saveEpoch;
+    fetch(new URL(window.location.href), { cache: 'no-store' })
+      .then((response) => (response.ok ? response.text() : null))
+      .then((html) => {
+        if (this.isDestroyed || html == null) return;
+        if (typeof seq === 'number' && seq < this._lastExternalSeq) {
+          // A newer external change superseded this one, and its own fetch will
+          // queue a body. Except for a repair: that one exists because the server
+          // said replay cannot fix this page, so if the newer fetch fails there is
+          // nothing else coming. Refetch rather than drop the only repair.
+          if (repair && attempt < 3) {
+            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
+          }
+          return;
+        }
+        if (this._saveEpoch > epoch) {
+          // An own save landed while the GET was in flight, so this body may
+          // predate it. Save-response order proves nothing about disk-write
+          // order — refetch for the newest bytes instead of dropping.
+          if (attempt < 3) {
+            console.log('[LiveSync] Refetching external change: own save landed mid-fetch');
+            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
+          }
+          return;
+        }
+        this._pendingExternal = { html, seq, saveEpoch: epoch };
+        this._scheduleNextFrame();
+      })
+      .catch((err) => {
+        this._log('External-change fetch failed', err);
+        // The watermark already advanced for this seq; leaving it there
+        // would drop the change forever. Roll back so a replay or a later
+        // duplicate can redeliver it.
+        if (typeof seq === 'number' && this._lastExternalSeq === seq) {
+          this._lastExternalSeq = seq - 1;
+        }
+      });
+  }
+
   /**
    * Apply an update received from the server. Morphs the entire document.
    *
@@ -562,34 +757,79 @@ class LiveSync {
   }
 
   /**
-   * Drain the pending slot once. Errors are caught and logged so a single
-   * failed morph does not stop the queue.
+   * Drain one pending payload per frame. Errors are caught and logged so a
+   * single failed morph does not stop the queue.
+   *
+   * Two slots feed this: peer frames and disk-sourced external changes. When
+   * both are pending, the lower seq applies first so the two lanes land in
+   * server order; the other stays queued for the next frame.
    */
   async _runPending() {
     this._rafHandle = null;
     if (this.isDestroyed) return;
 
-    const html = this._pendingHtml;
-    const seq = this._pendingSeq;
-    const identityMap = this._pendingIdentityMap;
-    this._pendingHtml = null;
-    this._pendingSeq = null;
-    this._pendingIdentityMap = null;
-    if (html == null) return;
+    const ext = this._pendingExternal;
+    let runExternal = false;
+    if (ext != null) {
+      if (this._pendingHtml == null) {
+        runExternal = true;
+      } else {
+        runExternal = !(
+          typeof ext.seq === 'number' &&
+          typeof this._pendingSeq === 'number' &&
+          this._pendingSeq < ext.seq
+        );
+      }
+    }
 
-    this._morphInFlight = true;
-    try {
-      await this._doApplyUpdate(html, seq, identityMap);
-    } catch (err) {
-      console.error('[LiveSync] applyUpdate failed:', err);
-    } finally {
-      this._morphInFlight = false;
+    if (runExternal) {
+      this._pendingExternal = null;
+      // Stale-at-drain checks: a newer external change already superseded
+      // this frame, or our own save landed after it was queued.
+      if (typeof ext.seq === 'number' && ext.seq < this._lastExternalSeq) {
+        this._log('Dropping superseded external change at drain');
+      } else if (ext.saveEpoch !== this._saveEpoch) {
+        // The epoch moved, but save-response order does not prove disk-write
+        // order: the frame's content may still be newer than our save.
+        // Refetch the served document — applying what disk holds NOW is
+        // always safe — instead of dropping the frame.
+        console.log('[LiveSync] Refetching external change: own save landed after queue');
+        this._fetchServedDocument(ext.seq);
+      } else {
+        this._morphInFlight = true;
+        try {
+          await this._doApplyExternal(ext.html, ext.seq);
+        } catch (err) {
+          console.error('[LiveSync] applyExternal failed:', err);
+        } finally {
+          this._morphInFlight = false;
+        }
+      }
+    } else {
+      const html = this._pendingHtml;
+      const seq = this._pendingSeq;
+      const identityMap = this._pendingIdentityMap;
+      this._pendingHtml = null;
+      this._pendingSeq = null;
+      this._pendingIdentityMap = null;
+      if (html == null) return;
+
+      this._morphInFlight = true;
+      try {
+        await this._doApplyUpdate(html, seq, identityMap);
+      } catch (err) {
+        console.error('[LiveSync] applyUpdate failed:', err);
+      } finally {
+        this._morphInFlight = false;
+      }
     }
 
-    // A newer payload may have arrived during the morph. Schedule another
-    // frame to drain it. Without this, late-arriving updates would sit
-    // forever until the next applyUpdate call.
-    if (!this.isDestroyed && this._pendingHtml != null) {
+    // A newer payload may have arrived during the morph, or the other slot
+    // is still holding one. Schedule another frame to drain it. Without
+    // this, late-arriving updates would sit forever until the next
+    // applyUpdate call.
+    if (!this.isDestroyed &&
+        (this._pendingHtml != null || this._pendingExternal != null)) {
       this._scheduleNextFrame();
     }
   }
@@ -630,6 +870,7 @@ class LiveSync {
 
     // Pause mutation observer so morph doesn't trigger autosave
     Mutation.pause();
+    pauseGate();
 
     // Parse as full document
     const parser = new DOMParser();
@@ -666,7 +907,50 @@ class LiveSync {
     const beforeAttributeUpdated = (name, element) =>
       isTabLocalRootAttr(name, element) ? false : undefined;
 
+    let retainedRoots = 0;
     try {
+      // Scoped sync: when this tab might hold unsaved edits, splice them into
+      // the incoming document BEFORE the morph so it cannot clobber them.
+      // The clean path skips every capture and stays byte-identical to a
+      // plain full morph.
+      if (this.lane === 'live' && pageMaybeDirty()) {
+        const protection = protectPeerDoc({
+          newDoc,
+          parsedWeakMap,
+          baseHtml: this.lastHtml,
+          baseIdentityMap: this._lastIdentityMap,
+          liveWeakMap: this.liveWeakMap,
+        });
+        if (!protection.ok) {
+          // Hold the whole frame: a dirty section couldn't be safely merged
+          // (or no baseline exists yet). Nothing morphs and no baseline
+          // moves; the tab keeps its local state and converges through its
+          // own next save. Deliberately NO proactive save here — a hold can
+          // fire on a manual-save page, which must never auto-write. The
+          // retry re-queues the same frame so it still applies if the
+          // blocking edit is undone; the slot-empty check and the drain's
+          // staleness checks drop it once superseded.
+          console.log('[LiveSync] Holding incoming update: unsaved local section cannot be safely merged', protection.held?.el || '');
+          const epochAtHold = this._saveEpoch;
+          const seenAtHold = this.lastSeenSeq;
+          clearTimeout(this._holdRetryPeer);
+          this._holdRetryPeer = setTimeout(() => {
+            this._holdRetryPeer = null;
+            if (this.isDestroyed || this._pendingHtml != null) return;
+            // Only while the world hasn't moved: an own save or any newer
+            // frame since the hold makes this payload stale.
+            if (this._saveEpoch !== epochAtHold) return;
+            if (this.lastSeenSeq !== seenAtHold) return;
+            this._pendingHtml = html;
+            this._pendingSeq = seq;
+            this._pendingIdentityMap = identityMap;
+            this._scheduleNextFrame();
+          }, 3000);
+          return;
+        }
+        retainedRoots = protection.entries.length;
+      }
+
       // 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
@@ -701,7 +985,7 @@ class LiveSync {
       // would mint fresh IDs on its next save for those elements,
       // breaking convergence exactly for newly-added ambiguous siblings.
       if (identityMap && typeof identityMap === 'object' && !Array.isArray(identityMap)) {
-        this._fillInIdsAfterMorph(document.documentElement, newDoc.documentElement, identityMap);
+        this._fillInIdsAfterMorph(document.documentElement, newDoc.documentElement, parsedWeakMap);
       }
 
       // Only mark lastHtml after a successful morph so that a failed apply
@@ -709,7 +993,31 @@ class LiveSync {
       // mistakenly skipped as "unchanged". Note: lastSeenSeq is advanced at
       // receive time (in onmessage) so the staleness check covers own-save
       // echoes even when they don't reach this point.
+      //
+      // lastHtml is the RAW incoming frame even after a protected apply. A
+      // patched serialization would poison the next frame's diff base (frame
+      // two of a burst would read the protected section as clean and clobber
+      // it) and could dedupe away the convergence send. Convergence is driven
+      // by the explicit save below instead.
       this.lastHtml = html;
+      this._lastIdentityMap =
+        identityMap && typeof identityMap === 'object' && !Array.isArray(identityMap)
+          ? identityMap
+          : null;
+      this._applyGen++;
+
+      // 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
+      // classify everything this frame brought as unsaved local edits and
+      // splice it over newer disk bytes. A verified-clean apply is the one
+      // moment the DOM is truthfully "as if saved", so the comparison
+      // baseline advances here too. Skipped whenever the gate reports dirty
+      // (including typing that arrived during the morph's async wait, which
+      // must never be recorded as saved).
+      if (this.lane === 'live' && retainedRoots === 0 && !pageMaybeDirty()) {
+        setLastSavedContents(captureForComparison({ flushUndo: false }));
+      }
 
       // Announce that a remote morph just landed, so document-level listeners
       // that are deaf to Mutation.pause (e.g. the hypercms form panel) can
@@ -718,17 +1026,159 @@ class LiveSync {
       // onmessage before applyUpdate is ever called. Covers every SSE morph
       // source (peer edit, version restore, body-swap) since they all funnel
       // through this single choke point.
+      //
+      // `source` is what lets a listener tell the two apply paths apart. clay.wire
+      // waits for a DISK frame to call an agent's write landed, and another tab's
+      // edit arriving first would otherwise report the wrong bytes as delivered.
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq }
+        detail: { seq, source: 'peer' }
       }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
       Mutation.resume();
+      resumeGate();
       // Defer past microtask boundary — MutationObserver callbacks fire before
       // this, so isPaused catches any stray snapshots from the morph itself.
       await new Promise((resolve) => setTimeout(resolve, 0));
       this.isPaused = false;
     }
+
+    // Convergence: a protected apply produced a merged state (our sections +
+    // 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.
+    if (retainedRoots > 0) {
+      savePageThrottled();
+    }
+  }
+
+  /**
+   * Apply an external disk change to this edit-mode tab. Same shape as
+   * _doApplyUpdate with three differences: the incoming document is save
+   * domain, so it is edit-mode ACTIVATED before the morph (inert attribute
+   * forms flipped live, as boot does on page load); dirty protection diffs
+   * against the save baseline instead of lastHtml; and on a clean apply the
+   * save baseline advances to a post-morph local comparison capture — true by
+   * construction, where any wire-derived baseline permanently mismatches
+   * (token, doctype, transform and parse divergences). A dirty apply leaves
+   * both baselines alone so the convergence save below sees its own changes
+   * (and, via the save pipeline, refreshes both). A clean apply also rebuilds
+   * lastHtml, because the peer lane's diff base must track what the DOM now
+   * holds or a later dirty peer apply misclassifies this frame's content as
+   * local edits.
+   */
+  async _doApplyExternal(html, seq) {
+    this._log(`applyExternal - external disk change (seq=${seq})`);
+    this.isPaused = true;
+
+    const scrollX = window.scrollX;
+    const scrollY = window.scrollY;
+
+    Mutation.pause();
+    pauseGate();
+
+    let retainedRoots = 0;
+    try {
+      const parser = new DOMParser();
+      const newDoc = parser.parseFromString(html, 'text/html');
+
+      // Lane-guarded exactly like the peer path. A view-mode tab has no save
+      // baseline — every writer of lastSavedContents is edit-gated — so
+      // protectDiskDoc can only ever refuse, and the frame would hold, retry
+      // every 3s, and hold again forever. The gate still reads dirty there,
+      // because persistProbeDirty inspects the live DOM and a visitor can type
+      // into a [persist] field. Before the resync repair this path was
+      // unreachable outside the live lane; now it is the repair's own route.
+      if (this.lane === 'live' && pageMaybeDirty()) {
+        const protection = protectDiskDoc({ newDoc });
+        if (!protection.ok) {
+          // Hold: nothing morphs, no baseline moves, and deliberately NO
+          // proactive save (a hold can fire on a manual-save page, which
+          // must never auto-write). The frame's seq watermark has already
+          // advanced, so nothing redelivers it on its own; the retry
+          // re-queues it with the epoch captured NOW, so the drain's epoch
+          // check turns an intervening own save into a refetch of current
+          // disk instead of a stale re-apply, and the seq check drops it
+          // once a newer external change supersedes it.
+          console.log('[LiveSync] Holding external change: unsaved local section cannot be safely merged', protection.held?.el || '');
+          const epochAtHold = this._saveEpoch;
+          clearTimeout(this._holdRetryExt);
+          this._holdRetryExt = setTimeout(() => {
+            this._holdRetryExt = null;
+            if (this.isDestroyed || this._pendingExternal != null) return;
+            this._pendingExternal = { html, seq, saveEpoch: epochAtHold };
+            this._scheduleNextFrame();
+          }, 3000);
+          return;
+        }
+        retainedRoots = protection.entries.length;
+      }
+
+      activateIncomingDoc(newDoc.documentElement);
+
+      const liveWeakMap = this.liveWeakMap;
+      const key = (el) =>
+        liveWeakMap.get(el) ||
+        (el.getAttribute && el.getAttribute('data-id')) ||
+        (el.getAttribute && el.getAttribute('id')) ||
+        null;
+      const beforeAttributeUpdated = (name, element) =>
+        isTabLocalRootAttr(name, element) ? false : undefined;
+
+      await HyperMorph.morph(document.documentElement, newDoc.documentElement, {
+        morphStyle: 'outerHTML',
+        ignoreActiveValue: true,
+        head: { style: 'merge' },
+        scripts: {
+          handle: true,
+          matchMode: 'smart',
+          mergeBase: this.lastHtml,
+          mergeTags: mergeTagRecognizers
+        },
+        key,
+        callbacks: { beforeAttributeUpdated }
+      });
+
+      window.scrollTo(scrollX, scrollY);
+
+      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,
+        // beforeunload stays quiet. The dirty re-check matters: typing that
+        // arrived during the morph's async wait would otherwise be captured
+        // into the baseline and recorded as saved without reaching disk.
+        setLastSavedContents(captureForComparison({ flushUndo: false }));
+        setUnsavedChanges(false);
+
+        // Cross-lane baseline: the PEER diff base (lastHtml) would otherwise
+        // still describe pre-frame state, and a later dirty peer apply would
+        // classify this frame's content as local edits and splice it over a
+        // newer peer frame. Rebuild it exactly the way the send pipeline
+        // does, so it stays in the snapshot domain.
+        const clone = captureSnapshot({ flushUndo: false });
+        this.lastHtml = serializeForSync(clone);
+        this._lastIdentityMap = this._buildIdentityMap(document.documentElement, clone);
+        this._applyGen++;
+      }
+
+      document.dispatchEvent(new CustomEvent('clay:sync-applied', {
+        detail: { seq, source: 'disk' }
+      }));
+    } finally {
+      this._log('applyExternal - morph complete, resuming mutations');
+      Mutation.resume();
+      resumeGate();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      this.isPaused = false;
+    }
+
+    // Convergence: disk holds the writer's version, this DOM holds the merge.
+    // The baseline was left pre-external, so the save sees both our retained
+    // sections and the external content as changes and writes the merge back.
+    if (retainedRoots > 0) {
+      savePageThrottled();
+    }
   }
 
   /**