@panphora/clayjs 1.15.2 → 1.17.0

package/src/sync/live-sync.js

@@ -35,35 +35,125 @@
  * INTEGRATES WITH: snapshot.js (receives snapshot-ready events)
  */
 
-import { HyperMorph, morph } from "../vendor/hyper-morph.vendor.js";
-
-const { createIdentityStore } = HyperMorph;
+import { createIdentityStore } from "../vendor/hyper-morph-identity.vendor.js";
+import { loadedEngine, mergeEngine } from "./merge-engine.js";
 import Mutation from "../lib/mutation.js";
 import { NO_DIRTY_SELECTOR, LIVE_SELECTOR } from "../lib/region-policy.js";
 import { EXTENSION_NODE_SELECTOR, EXTENSION_ATTR_PATTERN } from '../lib/extension-noise.js';
-import { isEditMode } from "../core/is-edit-mode.js";
-import { mergeTagRecognizers } from "./merge-tags.js";
-import { serializeForSync, captureForComparisonAndDirty, captureSnapshot, originalSnapshotNode, captureForMerge, captureForSaveAndComparison } from '../core/snapshot.js';
+import { isEditMode, modeState } from "../core/is-edit-mode.js";
+import { attributeMerge } from "./merge-declarations.js";
+import { serializeForSync, captureForComparisonAndDirty, canonicalizeReceived, captureSnapshot, originalSnapshotNode, captureForMerge, captureForSaveAndComparison } from '../core/snapshot.js';
 import { mergeIgnoresAttr, mergeVetoesAttr } from '../lib/root-attrs.js';
 import { autosaveActive } from '../lib/autosave-state.js';
-import { enableContentEditable } from '../core/admin-contenteditable.js';
-import { enableOnClick } from '../core/admin-onclick.js';
-import { enableAdminInputs } from '../core/admin-inputs.js';
-import { enableAdminResources } from '../core/admin-resources.js';
-import { presence } from './presence.js';
-import { editingMarker } from './editing-marker.js';
-import { hostMeta, hostSupports } from '../core/host-meta.js';
-import { EditingSender } from './editing-sender.js';
+import { hostSupports } from '../core/host-meta.js';
+import { PAGE_FORMAT, PAGE_FORMAT_HEADER } from '../core/page-format-wire.js';
 import { servedDocumentEtag } from '../core/host-attrs.js';
 import { recordEtag, seedEtag, lastSeenEtag, conditionalSaves, representedEtag, forgetRepresentedEtag } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate, gateCaptureToken, gateClearIfUnchanged } from '../lib/dirty-gate.js';
 import { gestureSeen } from '../lib/user-gesture.js';
 import { SyncStream } from './stream.js';
 import { streamOpened, streamClosed, streamEvent, LIVE_EVENTS } from '../live/stream-bridge.js';
-import { conflicts, beginApply, completeApply, failApply } from './conflicts.js';
-import { beginLineageCapture } from './conflict-footprints.js';
+import { conflicts, conflictLedger, loadConflicts } from './conflicts-facade.js';
+import { upgradeReplaces, stopForUpgrade } from './version-guard.js';
 import { isDerivedAttr, ownsDerivedText, stripDerived, repaintDerived, paintSignatureOfHtml, derivedActive } from '../lib/derived.js';
 
+// The edit-only half of live sync (save, admin and editing-sender code) is a
+// separate chunk. Edit mode starts it as live-sync evaluates, so its modules
+// stand where the old static imports left them before the first frame or save,
+// and view mode never fetches it.
+let edit = null;
+let editLoad = null;
+
+function loadEdit() {
+  editLoad ??= new Promise((resolve) => setTimeout(resolve, 0))
+    .then(() => import('./live-sync-edit.js'))
+    .then((loaded) => (edit = loaded))
+    .catch((error) => {
+      editLoad = null;
+      throw error;
+    });
+  return editLoad;
+}
+
+// The presence store is a first-use download for a reader too, so only the live lane
+// asks for it: a view-mode tab names it nowhere and fetches none of it.
+let presenceStore = null;
+let presenceLoad = null;
+
+function loadPresence() {
+  presenceLoad ??= import('./presence-store.js')
+    .then((mod) => (presenceStore = mod.presence))
+    .catch((error) => {
+      presenceLoad = null;
+      throw error;
+    });
+  return presenceLoad;
+}
+
+// `entering` means an entry is importing this module: the controller starts the
+// lane once the mode is committed, so this evaluation starts nothing and loads
+// nothing. An explicit initial edit, and a reader's saved lane, are untouched.
+const entering = modeState().phase === "entering";
+
+if (isEditMode && !entering) loadEdit().catch(() => {});
+
+// The conflict ledger is what a merge writes to, so an editor starts its download as
+// this file evaluates rather than at the first merge: nothing on the edit path pays
+// for it twice. A reader starts it with its first merged frame (or with the live lane).
+if (isEditMode) loadConflicts().catch(() => {});
+
+// Who else is on the document, and the block somebody else is editing: both are
+// a download of their own. A reader alone on a page draws neither, so they
+// arrive with the first roster frame; a frame that lands while the download is
+// in flight waits in order, and anything read before it is the empty state a
+// bare constructor gives.
+let roster = null;
+let rosterLoad = null;
+let rosterQueue = [];
+
+function applyRoster(data) {
+  roster.presence.update(data);
+  roster.editingMarker.update(data);
+}
+
+function loadRoster() {
+  rosterLoad ??= Promise.all([import('./presence.js'), import('./editing-marker.js')])
+    .then(([presenceMod, markerMod]) => {
+      roster = { presence: presenceMod.presence, editingMarker: markerMod.editingMarker };
+      const queued = rosterQueue;
+      rosterQueue = [];
+      for (const data of queued) applyRoster(data);
+      return roster;
+    })
+    .catch((error) => {
+      rosterLoad = null;
+      throw error;
+    });
+  return rosterLoad;
+}
+
+// A download that failed keeps the queue, so the next frame asks again.
+function takeRosterFrame(data) {
+  if (roster) {
+    applyRoster(data);
+    return;
+  }
+  rosterQueue.push(data);
+  loadRoster().catch(() => {});
+}
+
+// The receipt of a lane that has applied no saved file.
+const NO_FILE = Object.freeze({ bytes: null, etag: null, seq: null });
+
+// save.js returns this from savePageThrottled outside edit mode; a view-mode
+// tab that somehow asks for a merge save gets the same answer without loading it.
+const notInEditModeResult = () => ({
+  msg: 'Not in edit mode',
+  msgType: 'skipped',
+  code: null,
+  etag: null,
+});
+
 // What a live-sync merge never reads or touches on any side: editor chrome,
 // content kept out of the save or the snapshot, the contents of frozen regions,
 // and nodes browser extensions inject. The same set the 0.5 morph's sync policy
@@ -92,6 +182,7 @@ function emptyScratchpads(root) {
 function scratchpadsEmptied(input) {
   if (input == null) return input;
   const doc = typeof input === 'string' ? new DOMParser().parseFromString(input, 'text/html') : input;
+  canonicalizeReceived(doc);
   emptyScratchpads(doc);
   return doc;
 }
@@ -127,6 +218,7 @@ const authoredAttr = (el) => el.getAttribute('data-id') || el.getAttribute('id')
 function countAuthored(root) {
   const counts = new Map();
   const visit = (el) => {
+    if (el.matches(SYNC_IGNORE_SELECTOR)) return;
     const id = authoredAttr(el);
     if (id) counts.set(id, (counts.get(id) || 0) + 1);
     const kids = el.localName === 'template' && el.content ? el.content.children : el.children;
@@ -178,64 +270,24 @@ function readServedStamp(html) {
  * mid-edit. Root attributes (editmode, savestatus, tokens) need no reversal
  * here; the merge's attribute veto keeps the live root's own.
  */
-function activateIncomingDoc(rootEl) {
-  if (!isEditMode || !rootEl) return;
-  enableContentEditable(rootEl);
-  enableOnClick(rootEl);
-  enableAdminInputs(rootEl);
-  enableAdminResources(rootEl);
+function activateIncomingDoc(rootEl, lane) {
+  if (lane !== 'live' || !rootEl || !edit) return;
+  edit.enableContentEditable(rootEl);
+  edit.enableOnClick(rootEl);
+  edit.enableAdminInputs(rootEl);
+  edit.enableAdminResources(rootEl);
 }
 
 function pairedBaseline() {
   const { forComparison, forDirty } = captureForComparisonAndDirty({ flushUndo: false });
   return [forComparison, forDirty];
 }
-import { savePageThrottled, setLastSavedBaselines, setUnsavedChanges, getLastSavedBytes, conflictResolvedBySync, isSaveConflicted, baselineSettled, schedulePaintHeal } from '../core/save.js';
 
 /**
- * The two live-sync wires, and the rule for choosing between them.
- *
- * Spec §10 puts both halves on `/_/sync`. Not every host serves that yet, and the
- * ones that do not cannot be upgraded on our schedule: hyperclay-local ships behind
- * Apple notarization, while this library reaches every document within one 10-minute
- * cache TTL. So the client is the half that has to know both.
- *
- * The choice is DISCOVERED, never guessed. Spec §5 makes `/_/meta` the only way to
- * learn what a host can do, and §10 says a client that has not discovered `sync`
- * never opens either half of the route. Probing is also a bad instrument here: an
- * EventSource reports a 404, an auth refusal and an offline browser through one
- * error path, so a failed connection cannot tell you which address was wrong.
- *
- * One profile is chosen once and used for BOTH directions for the life of the page.
- * Letting send and receive decide independently is exactly the bug this replaces: a
- * client that posted to the spec address while streaming from the legacy one.
- *
- * Both stream addresses carry `client-id`, in the same kebab spelling as the rest of
- * the query. It is the tab's own sender id — the one every outbound frame already
- * carries — so a host that reads it at admission knows this connection by the value
- * its frames arrive under, and can tell two tabs of one cookie-less guest apart. A
- * host that does not read it ignores an unknown parameter.
+ * The wires live in wire-profile.js: both halves of one sync pick a single profile
+ * from `/_/meta`, and the reader's receive-only stream makes the same choice.
  */
-const WIRE_PROFILES = {
-  spec: {
-    name: 'spec',
-    relayPath: '/_/sync',
-    documentHeader: 'Document-URL',
-    snapshotKey: 'snapshot',
-    streamPath: (href, lane, resumeId, clientId) =>
-      `/_/sync?document-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
-  },
-  // What every published clayjs speaks, and what hyperclayjs and the inline script in
-  // every Collection dashboard hardcode. Hosts keep these addresses permanently.
-  legacy: {
-    name: 'legacy',
-    relayPath: '/_/live-sync/save',
-    documentHeader: 'Page-URL',
-    snapshotKey: 'html',
-    streamPath: (href, lane, resumeId, clientId) =>
-      `/_/live-sync/stream?page-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
-  },
-};
+import { WIRE_PROFILES, resolveWireProfile } from './wire-profile.js';
 
 class LiveSync {
   constructor() {
@@ -294,6 +346,7 @@ class LiveSync {
     this._sharedSync = false;
     this._liveData = false;
     this._editing = null;
+    this._presenceLease = null;
     this._ready = null;
     // Bumped by every start(), so a discovery that resolves after a stop/restart
     // cannot open a stream for the run that has already been torn down.
@@ -304,8 +357,13 @@ class LiveSync {
 
     // Lane on the shared per-file SSE channel. Edit mode: 'live' (owner-gated,
     // pre-strip peer snapshots + notifications). View mode: 'saved' (receive-
-    // only post-strip on-disk HTML). Overridable per-instance for tests.
-    this.lane = isEditMode ? 'live' : 'saved';
+    // only post-strip on-disk HTML). This is only the lane a page starts with:
+    // start() reads the committed mode, so one instance serves a reader's saved
+    // lane and, after an entry, the live lane.
+    this._lane = isEditMode ? 'live' : 'saved';
+    // A lane chosen by hand (a test, or a live switch handing one over) is never
+    // re-derived; otherwise every start() reads the committed mode.
+    this._laneChosen = false;
 
     // Store handler reference for cleanup
     this._snapshotHandler = null;
@@ -339,6 +397,15 @@ class LiveSync {
     this._morphInFlight = false;
     this._rafHandle = null;
 
+    // The saved file this lane last applied, `{ bytes, etag, seq }`: the receipt a
+    // switch is handed, and the only record of it a same-body frame may move. A
+    // metadata stamp is not a file, so it never advances this one.
+    this._represented = NO_FILE;
+    // A switch owns the queue from prepareHandoff() until it commits or resumes:
+    // frames keep filling their slots and nothing morphs.
+    this._handoff = null;
+    this._handoffHeld = false;
+
     // 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.
@@ -381,6 +448,7 @@ class LiveSync {
     // retries cannot pile up behind one another.
     this._servedFetchId = 0;
     this._startupRetry = null;
+    this._engineRetry = null;
 
     // Whether each lane is currently holding. A hold is a safe outcome but a
     // silent one: without an event the page simply stops updating and nothing
@@ -459,11 +527,26 @@ class LiveSync {
     this._setDiskBase(captureForSaveAndComparison({ emitForSync: false }).forSave, this._ticket());
   }
 
+  get lane() {
+    return this._lane;
+  }
+
+  set lane(value) {
+    this._lane = value;
+    this._laneChosen = true;
+  }
+
   /**
    * Start the LiveSync system
    * Can be called after stop() to restart with a new file
+   *
+   * The lane is read here, from the committed mode, unless the caller names one:
+   * the same instance rides a reader's saved lane, becomes the live lane at an
+   * entry, and comes back to the saved lane at an exit. `represented` is the
+   * `{bytes, etag, seq}` receipt a switch hands over, so a restarted saved lane
+   * has one before any frame arrives and a frame repeating it changes nothing.
    */
-  start(file = null) {
+  start(file = null, { lane, represented } = {}) {
     // Reset destroyed flag to allow restart after stop()
     this.isDestroyed = false;
 
@@ -479,6 +562,10 @@ class LiveSync {
       return;
     }
 
+    const committed = modeState().mode === 'edit' ? 'live' : 'saved';
+    const wasLive = this.lane === 'live';
+    this._lane = lane || (this._laneChosen ? this._lane : committed);
+
     // 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;
@@ -495,6 +582,13 @@ class LiveSync {
     this._applyGen++;
     this.lastSeenSeq = 0;
     this._lastExternalSeq = 0;
+    this._represented = represented
+      ? Object.freeze({ bytes: represented.bytes ?? null, etag: represented.etag ?? null, seq: represented.seq ?? null })
+      : NO_FILE;
+    // A saved lane a live session just gave back, holding no receipt, is the one case
+    // that has to fetch the served file for itself: an initial-edit exit that saved
+    // nothing still leaves a reader that can show and hand over a file.
+    this._acquireEmptySaved = wasLive && this.lane === 'saved' && this._represented.bytes === null;
     this._pendingExternal = null;
     this.resumeId = this.generateResumeId();
 
@@ -503,13 +597,16 @@ class LiveSync {
     // below: a base taken before a module built its DOM makes the first dirty merge
     // see both sides add that DOM, and keep it twice.
     if (this.lane === 'live') this._seedBases();
+    // The live lane merges from its first frame, and every merge there reads the
+    // ledger, so the download starts with the lane instead of delaying a frame.
+    if (this.lane === 'live') loadConflicts().catch(() => {});
 
     console.log(`[LiveSync] Starting for: ${this.currentFile} (lane=${this.lane})`);
     // One discovery request stands between here and the stream. It is memoized and
     // bounded, and it does not gate ordinary saves — /_/save is a separate lane that
     // never moved. Snapshots produced during the window are queued, not dropped.
     const gen = ++this._startGen;
-    if (this.lane === 'live' && !baselineSettled()) {
+    if (this.lane === 'live' && !(edit ? edit.baselineSettled() : false)) {
       const applyGen = this._applyGen;
       const morphTicket = this._morphTicket;
       const saveEpoch = this._saveEpoch;
@@ -550,7 +647,10 @@ class LiveSync {
     }
     // Exposed so a caller (and the tests) can await the point where the stream is
     // actually open, rather than counting microtasks behind the discovery request.
-    this._ready = this._resolveProfile().then(() => {
+    this._ready = Promise.all([
+      this.lane === 'live' ? loadEdit() : null,
+      this._resolveProfile(),
+    ]).then(() => {
       if (this.isDestroyed || this._startGen !== gen) return;
       this.connect();
     });
@@ -558,12 +658,10 @@ class LiveSync {
     // snapshot listener would never fire — skip registering it.
     if (this.lane === 'live') {
       this.listenForSnapshots();
-      hostSupports('presence-editing').then((supported) => {
-        if (!supported || this.isDestroyed || this._startGen !== gen || this._editing) return;
-        this._editing = new EditingSender({ send: (path) => this._postEditing(path) });
-        this._editing.start();
-        this._editing.roster(this._lastRoster);
-      }, () => {});
+      // One presence transport per document, chosen from the host's own answer, and
+      // one sender behind it: the generic marker publishes through the store, so a
+      // page target and a caret path never talk over each other.
+      loadPresence().then((store) => this._startPresence(store, gen), () => {});
       this._saveSavedHandler = () => {
         this._saveEpoch++;
         // The file now holds what this save wrote: the disk lane's new base,
@@ -574,7 +672,7 @@ class LiveSync {
         const ticket = this._saveTicket || this._ticket();
         this._saveTicket = 0;
         if (ticket > this._acceptedSaveTicket) this._acceptedSaveTicket = ticket;
-        const bytes = getLastSavedBytes();
+        const bytes = edit ? edit.getLastSavedBytes() : null;
         if (bytes != null) this._setDiskBase(bytes, ticket);
         this._relayCommit();
       };
@@ -590,7 +688,7 @@ class LiveSync {
         queueMicrotask(() => {
           if (this.isDestroyed) return;
           if (refusedBy !== lastSeenEtag()) return;
-          conflictResolvedBySync(refusedBy);
+          edit?.conflictResolvedBySync(refusedBy);
           this._saveAfterMerge(pageMaybeDirty(), false);
         });
       };
@@ -610,14 +708,24 @@ class LiveSync {
     streamClosed();
 
     // Nothing feeds the roster once the stream is gone, so leaving the stack up
-    // would show a list of people who may all have left.
-    presence.clear();
-    editingMarker.clear();
+    // would show a list of people who may all have left. A roster that never
+    // loaded has drawn nothing, and its queued frames are dropped with the
+    // stream that fed them.
+    rosterQueue = [];
+    if (roster) {
+      roster.presence.clear();
+      roster.editingMarker.clear();
+    }
 
     if (this._editing) {
       this._editing.stop();
       this._editing = null;
     }
+    // Only this run's lease: a successor that already attached keeps its roster.
+    if (this._presenceLease) {
+      this._presenceLease.detach();
+      this._presenceLease = null;
+    }
     this._lastRoster = null;
 
     if (this._snapshotHandler) {
@@ -654,6 +762,8 @@ class LiveSync {
     this._pendingIdentityMap = null;
     this._pendingBy = null;
     this._pendingExternal = null;
+    this._handoff = null;
+    this._handoffHeld = false;
     clearTimeout(this._holdRetryPeer);
     clearTimeout(this._holdRetryExt);
     this._holdRetryPeer = null;
@@ -663,6 +773,8 @@ class LiveSync {
     // fetch, if any, owns the question.
     clearTimeout(this._startupRetry);
     this._startupRetry = null;
+    clearTimeout(this._engineRetry);
+    this._engineRetry = null;
     this._servedFetchId++;
   }
 
@@ -704,23 +816,14 @@ class LiveSync {
    */
   _resolveProfile() {
     if (!this._profilePromise) {
-      this._profilePromise = hostMeta()
-        .then((meta) => {
-          const extensions = meta?.extensions || [];
-          const hasSync = extensions.includes('sync');
-          const hasLiveData = extensions.includes('live-data');
-          const hasPresence = extensions.includes('presence');
-          this._sharedData = hasSync && hasLiveData && extensions.includes('sync-worker-data') && !hasPresence;
-          this._sharedSync = hasSync && !hasPresence && (this._sharedData || (extensions.includes('sync-worker') && !hasLiveData));
-          this._liveData = hasLiveData;
-          return hasSync ? WIRE_PROFILES.spec : WIRE_PROFILES.legacy;
-        })
-        .catch(() => WIRE_PROFILES.legacy)
-        .then((profile) => {
-          this._profile = profile;
-          this._log(`Wire profile: ${profile.name}`);
-          return profile;
-        });
+      this._profilePromise = resolveWireProfile().then((resolved) => {
+        this._sharedData = resolved.sharedData;
+        this._sharedSync = resolved.sharedSync;
+        this._liveData = resolved.liveData;
+        this._profile = resolved.profile;
+        this._log(`Wire profile: ${resolved.profile.name}`);
+        return resolved.profile;
+      });
     }
     return this._profilePromise;
   }
@@ -809,9 +912,21 @@ class LiveSync {
       startupCheck: Boolean(servedDocumentEtag),
     });
 
+    // A saved reader that a live session handed back with no bytes has nothing to
+    // show and nothing to hand the next entry. Ask the host for the served file once,
+    // as a view boot does, so an initial-edit exit that saved nothing still leaves a
+    // receipt.
+    if (this._acquireEmptySaved) {
+      this._acquireEmptySaved = false;
+      this._fetchServedDocument(undefined, { repair: true });
+    }
+
     this.sse.onopen = () => {
       console.log('[LiveSync] Connected');
       if (this._editing) this._editing.reconnected();
+      // A reconnect is a new connection: the host issues it a new presence session,
+      // and nothing this tab sent under the old one may stand.
+      if (presenceStore) presenceStore.reconnect();
       if (this.onConnect) this.onConnect();
     };
 
@@ -886,8 +1001,7 @@ class LiveSync {
       } catch {
         return;
       }
-      presence.update(data);
-      editingMarker.update(data);
+      takeRosterFrame(data);
       this._lastRoster = data;
       if (this._editing) this._editing.roster(data);
     });
@@ -957,6 +1071,15 @@ class LiveSync {
         return;
       }
 
+      // A saved frame repeating the file this lane already applied: the receipt moves
+      // onto the new stamp and the page is not touched, because the bytes on screen
+      // ARE these bytes.
+      if (this.lane === 'saved' && html === this._represented.bytes) {
+        this._represented = Object.freeze({ bytes: html, etag: etag || null, seq: seq ?? null });
+        recordEtag(etag);
+        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
@@ -964,8 +1087,8 @@ 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()) {
-          conflictResolvedBySync(etag);
+        if (edit && edit.isSaveConflicted()) {
+          edit.conflictResolvedBySync(etag);
           this._saveAfterMerge(pageMaybeDirty(), false);
         }
         return;
@@ -1114,6 +1237,7 @@ class LiveSync {
       headers: {
         'Content-Type': 'application/json',
         [profile.documentHeader]: window.location.href,
+        [PAGE_FORMAT_HEADER]: String(PAGE_FORMAT),
       },
       body: JSON.stringify({
         [profile.snapshotKey]: html,
@@ -1154,13 +1278,45 @@ class LiveSync {
     });
   }
 
-  _postEditing(path) {
+  /**
+   * Take this run's presence transport and, behind its own capability, the generic
+   * editing marker that publishes through it. `gen` is the start() this belongs to,
+   * so a discovery that answers after a stop attaches nothing.
+   */
+  _startPresence(store, gen) {
+    if (this.isDestroyed || this._startGen !== gen || this._presenceLease) return null;
+    return store.connect({ send: (body) => this._postPresence(body) })
+      .then((transport) => {
+        if (this.isDestroyed || this._startGen !== gen) {
+          transport?.detach();
+          return null;
+        }
+        this._presenceLease = transport || null;
+        return hostSupports('presence-editing');
+      }, () => false)
+      .then((supported) => {
+        if (!supported || this.isDestroyed || this._startGen !== gen || this._editing) return;
+        return loadEdit().then((mod) => {
+          if (this.isDestroyed || this._startGen !== gen || this._editing) return;
+          this._editing = new mod.EditingSender({});
+          this._editing.start();
+          this._editing.roster(this._lastRoster);
+        });
+      });
+  }
+
+  /**
+   * The relay's half of a transport: one request carrying the body the store built.
+   * A page target arrives in the extended envelope, a legacy path exactly as it
+   * always has, and the host decides by the same connection ownership either way.
+   */
+  _postPresence(body) {
     const url = new URL('/_/presence', window.location.origin);
     url.searchParams.set('client-id', this.clientId);
     return fetch(url.href, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', 'Document-URL': window.location.href },
-      body: JSON.stringify({ editing: path }),
+      body: JSON.stringify(body),
     }).then((response) => response.ok, () => false);
   }
 
@@ -1319,7 +1475,15 @@ class LiveSync {
             // server could not replay, so it keeps its unstamped fallback.
             if (!repair) return;
           } else if (stamp === representedEtag()) {
-            // The file this tab was served, and nothing to do about it.
+            // The file this tab was served, and nothing to do about it. The exception is
+            // a saved-lane reader with no bytes: it has nothing to show and nothing to
+            // hand the next entry, and these bytes ARE the file it starts from, so the
+            // receipt moves even though the DOM is already showing them. That is the
+            // saved lane's acquisition, and it is also the startup check of a page booted
+            // in view, which is the same no-bytes reader asking which file it represents.
+            if ((repair || startup) && this.lane === 'saved') {
+              this._represented = Object.freeze({ bytes: html, etag: stamp, seq: seq ?? null });
+            }
             return;
           }
         } else if (typeof seq === 'number' && seq < this._lastExternalSeq) {
@@ -1440,13 +1604,35 @@ class LiveSync {
     this._scheduleNextFrame();
   }
 
+  /**
+   * Hand the saved lane's queue to a switch without stopping it: an apply already in
+   * flight finishes, a frame that arrives meanwhile keeps its slot, and a repair the
+   * host asked for stays owed. The protocol itself is a dynamic target, so a page that
+   * never switches modes never fetches it.
+   *
+   * @param {Object} [options] - `{ signal, deadline }`
+   * @returns {Promise<{represented: Object, reconcile: function(): Promise<void>, resume: function(), commit: function(): boolean}>}
+   */
+  prepareHandoff(options = {}) {
+    if (this._handoff) return Promise.resolve(this._handoff);
+    if (this.isDestroyed) return Promise.reject(new Error('LiveSync: stopped'));
+    this._handoffHeld = true;
+    if (this._rafHandle != null) {
+      this._cancelFrame(this._rafHandle);
+      this._rafHandle = null;
+    }
+    return import('./saved-handoff.js')
+      .then(({ engineHandoff }) => engineHandoff(this, options))
+      .then((handoff) => (this._handoff = handoff));
+  }
+
   /**
    * Schedule the next-frame morph if one isn't already pending. Skipped when
    * a morph is in flight; the morph's post-completion check will reschedule
    * if a newer payload arrived during it.
    */
   _scheduleNextFrame() {
-    if (this.isDestroyed) return;
+    if (this.isDestroyed || this._handoffHeld) return;
     if (this._rafHandle != null) return;
     if (this._morphInFlight) return;
     this._rafHandle = this._requestFrame(() => this._runPending());
@@ -1464,6 +1650,20 @@ class LiveSync {
     this._rafHandle = null;
     if (this.isDestroyed) return;
 
+    if (!loadedEngine()) {
+      this._morphInFlight = true;
+      try {
+        await mergeEngine();
+      } catch (error) {
+        this._log('Merge engine failed to load', error);
+        this._engineRetry = setTimeout(() => this._scheduleNextFrame(), 2000);
+        return;
+      } finally {
+        this._morphInFlight = false;
+      }
+      if (this.isDestroyed) return;
+    }
+
     const ext = this._pendingExternal;
     const opts = ext?.fetchOptions || null;
     // A startup check and a stamped repair are both version checks: each one
@@ -1656,11 +1856,17 @@ class LiveSync {
    * @param {object} [lane.extra] - extra mergeDocument options (the disk lane's beforeApply)
    */
   async _mergeIncoming(html, identityMap, { base, baseIdentityMap = null, captureLocal, synthetic, source = 'peer', seq = null, etag = null, extra = {} }) {
+    if (!loadedEngine()) await mergeEngine();
+    // The first merge is what a reader downloads the ledger for: this frame is the
+    // one that may produce a conflict, and nothing before it could have. A ledger
+    // already in hand is read synchronously, so a tab that has merged once begins
+    // its next apply in the caller's own tick, as it always did.
+    const { beginApply, completeApply, failApply, beginLineageCapture } = conflictLedger() || await loadConflicts();
     let lineageCapture;
     const mergeDocument = (options) => {
       lineageCapture = beginLineageCapture(conflicts.list());
       try {
-        const pending = HyperMorph.mergeDocument({ ...options, lineage: lineageCapture.lineage });
+        const pending = loadedEngine().HyperMorph.mergeDocument({ ...options, lineage: lineageCapture.lineage });
         lineageCapture.returned();
         return pending;
       } catch (error) {
@@ -1692,7 +1898,8 @@ class LiveSync {
     const syntheticByAuthored = new Map();
     if (isIdMap(identityMap)) {
       remote = new DOMParser().parseFromString(html, 'text/html');
-      const imported = HyperMorph.importMap(remote.documentElement, identityMap);
+      canonicalizeReceived(remote);
+      const imported = loadedEngine().HyperMorph.importMap(remote.documentElement, identityMap);
       for (const el of remote.querySelectorAll('[data-id], [id]')) {
         const id = authored(el);
         const synthetic = id && imported.get(el);
@@ -1708,9 +1915,10 @@ class LiveSync {
       opaque: (el) => el.matches(FREEZE_SELECTOR) || (derivedActive() && ownsDerivedText(el)),
       remoteWins: (el) => el.matches(REMOTE_WINS_SELECTOR),
       ignoreAttribute: (el, name, merged) => isRootLocalAttr(el, name, merged) || (derivedActive() && isDerivedAttr(merged || el, name)),
+      attributeMerge,
       protectFocusedValue: true,
       keepLiveOnly: source === 'peer',
-      scripts: { mergeTags: mergeTagRecognizers },
+      scripts: { mergeTags: loadedEngine().mergeTagRecognizers },
       hooks: { beforeAttributeUpdated },
       ...extra,
     };
@@ -1835,7 +2043,8 @@ class LiveSync {
   _saveAfterMerge(diverged, typedDuringWait) {
     if (!(diverged || typedDuringWait)) return;
     if (!autosaveActive()) return;
-    savePageThrottled();
+    if (edit) edit.savePageThrottled();
+    else notInEditModeResult();
   }
 
   /**
@@ -1849,6 +2058,15 @@ class LiveSync {
    * @returns {Promise<void>}
    */
   async _doApplyUpdate(html, seq, identityMap, etag, by = null) {
+    // Another version of the document is not a change to this one, whichever lane
+    // or slot it arrived on: a peer snapshot merges no more than a saved frame does,
+    // and nothing applies after the first refusal. The guard holds the saves and
+    // asks the notice to offer a reload.
+    if (upgradeReplaces(html)) {
+      await stopForUpgrade();
+      return;
+    }
+    if (this.lane === 'live' && !edit) await loadEdit();
     this._log('applyUpdate - pausing mutations and morphing');
     this.isPaused = true;
 
@@ -1986,7 +2204,7 @@ class LiveSync {
           emitForSync: false,
           flushUndo: false,
         });
-        setLastSavedBaselines(forComparison, forDirty);
+        edit.setLastSavedBaselines(forComparison, forDirty);
         this._setDiskBase(forSave, this._ticket());
       }
 
@@ -2006,8 +2224,15 @@ class LiveSync {
       // event rather than on the frame's arrival for one reason: a frame that held
       // returns above without reaching here, so nothing can name an author for a
       // change this tab never took. Null on every frame the host did not stamp.
+      //
+      // A frame on the SAVED lane is a file, not a preview: only the live lane
+      // carries keystrokes nobody saved. Tagging both as `peer` made a view-mode
+      // reader, which drops previews, ignore every save on a page that also names
+      // `sync`. `lane` names the lane the frame came from either way.
+      if (this.lane === 'saved') this._represented = Object.freeze({ bytes: html, etag: etag || null, seq: seq ?? null });
+
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'peer', by: by || null, html, report, unresolved: this.unresolvedConflicts, conflictIds }
+        detail: { seq, source: this.lane === 'saved' ? 'disk' : 'peer', lane: this.lane, by: by || null, html, report, unresolved: this.unresolvedConflicts, conflictIds }
       }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
@@ -2026,7 +2251,7 @@ class LiveSync {
     // 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.
-    if (stamped) conflictResolvedBySync(etag);
+    if (stamped) edit?.conflictResolvedBySync(etag);
     this._saveAfterMerge(diverged, typedDuringWait);
   }
 
@@ -2046,6 +2271,14 @@ class LiveSync {
    * local edits.
    */
   async _doApplyExternal(html, seq, etag = null, by = null, fetchOptions = null) {
+    // Another version of the document is not a change to this one: it does not
+    // merge, and after it no later frame is applied either. The guard holds the
+    // saves and asks the notice to offer a reload.
+    if (upgradeReplaces(html)) {
+      await stopForUpgrade();
+      return;
+    }
+    if (this.lane === 'live' && !edit) await loadEdit();
     const priorDisk = this._diskBase;
     this._log(`applyExternal - external disk change (seq=${seq})`);
     this.isPaused = true;
@@ -2119,7 +2352,7 @@ class LiveSync {
         source: 'disk',
         seq,
         etag,
-        extra: { beforeApply: (doc) => activateIncomingDoc(doc.documentElement) },
+        extra: { beforeApply: (doc) => activateIncomingDoc(doc.documentElement, this.lane) },
       });
       diverged = report.localDiverged;
       typedDuringWait = typed;
@@ -2160,8 +2393,8 @@ class LiveSync {
         // 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.
-        setLastSavedBaselines(...pairedBaseline());
-        setUnsavedChanges(false);
+        edit.setLastSavedBaselines(...pairedBaseline());
+        edit.setUnsavedChanges(false);
 
         // Cross-lane baseline: the PEER diff base (lastHtml) would otherwise
         // still describe pre-frame state, and a later dirty peer apply would
@@ -2173,6 +2406,8 @@ class LiveSync {
         this._applyGen++;
       }
 
+      if (this.lane === 'saved') this._represented = Object.freeze({ bytes: html, etag: etag || null, seq: seq ?? null });
+
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
         detail: {
           seq,
@@ -2199,14 +2434,14 @@ 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.
-    if (stamped) conflictResolvedBySync(etag);
+    if (stamped) edit?.conflictResolvedBySync(etag);
     this._saveAfterMerge(diverged, typedDuringWait);
     // A disk frame from a writer that does not paint (an agent, the data API)
     // changes records and leaves the painted values as they were. If the page's
     // repainted values differ from them once the timer fires, one tab saves so
     // the bytes on disk heal. A writer that paints is left alone.
     if (priorDisk != null && paintSignatureOfHtml(priorDisk) === paintSignatureOfHtml(html)) {
-      schedulePaintHeal(() => (this._diskBase == null ? null : paintSignatureOfHtml(this._diskBase)));
+      if (edit) edit.schedulePaintHeal(() => (this._diskBase == null ? null : paintSignatureOfHtml(this._diskBase)));
     }
   }
 
@@ -2253,13 +2488,22 @@ class LiveSync {
     this.isDestroyed = true;
     console.log('[LiveSync] Stopped');
   }
+
+  /**
+   * The lifecycle participant for this module: the lease a live switch prepares,
+   * enables at the commit and disposes at the exit. Its body is in the edit-only
+   * chunk, so a reader never loads it.
+   */
+  editParticipant() {
+    return loadEdit().then((mod) => mod.syncParticipant(this));
+  }
 }
 
 // Singleton instance
 const liveSync = new LiveSync();
 
 // Auto-initialize when DOM is ready
-if (typeof window !== 'undefined') {
+if (typeof window !== 'undefined' && !entering) {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => liveSync.start());
   } else {
@@ -2270,5 +2514,6 @@ if (typeof window !== 'undefined') {
 // Export for the clayjs module system. The class itself is exported so
 // tests can create fresh instances without driving the singleton's
 // EventSource/snapshot wiring.
+const morph = (oldEl, newEl, options) => mergeEngine().then(({ morph }) => morph(oldEl, newEl, options));
 export { liveSync, LiveSync, morph, WIRE_PROFILES, conflicts, SYNC_IGNORE_SELECTOR, REMOTE_WINS_SELECTOR };
 export default liveSync;