@panphora/clayjs 1.15.1 → 1.16.0

package/src/sync/presence-target.js

@@ -0,0 +1,243 @@
+/**
+ * presence-target.js — the one target union behind `clay.presence`.
+ *
+ * Kanban's record targets and a Document's page targets travel on the same wire
+ * field (`editing`) and through the same facade. This module is the contract
+ * alone: what a target is, what bounds it, how a roster session is read, and the
+ * exact request body a target turns into. It imports no Yjs, no ProseMirror, no
+ * page code and no visual code, so a reader can validate a frame without any of
+ * them, and the host can validate the same value without decoding Yjs.
+ *
+ * Three shapes are accepted for `editing`:
+ *
+ *   null                      nobody is anywhere
+ *   "1.2"                     the legacy dotted block path, unchanged
+ *   {kind:"record", id, field?}  a Kanban/Journal record (fieldless journals too)
+ *   {kind:"page", v:1, epoch, generation, selection}  a Document's page target
+ *
+ * Anything else is refused rather than repaired: a frame this module cannot read
+ * draws nothing, and a target it cannot read is never published.
+ */
+
+import { EDITING_PATH } from './editing-path.js';
+
+// The extended envelope's version. A body without `v` is the legacy shape.
+export const PRESENCE_VERSION = 1;
+
+// Bounds, shared by this client and the server contract it speaks to.
+export const MAX_TARGET_BYTES = 8 * 1024;
+export const MAX_PAGE_ID_BYTES = 256;
+export const MAX_REL_BYTES = 1024;
+export const MAX_RECORD_ID = 128;
+export const MAX_SELECTION_IDS = 128;
+
+// Kanban's documented field enum. A record target without a field is valid.
+export const RECORD_FIELDS = Object.freeze([
+  'title', 'description', 'labels', 'members', 'dates', 'checklist', 'comment', 'attachments',
+]);
+
+// Coalesce selection moves to one every 250 ms, renew a standing target every 5 s,
+// and let it expire 15 s after the server received it. The server accepts at most
+// 10 updates per second, with a burst of 20, per admitted session and document.
+export const COALESCE_MS = 250;
+export const RENEW_MS = 5000;
+export const EXPIRE_MS = 15000;
+export const RATE_PER_SECOND = 10;
+export const RATE_BURST = 20;
+
+const RECORD_KEYS = new Set(['kind', 'id', 'field']);
+const PAGE_KEYS = new Set(['kind', 'v', 'epoch', 'generation', 'selection']);
+const TEXT_KEYS = new Set(['kind', 'anchor', 'head']);
+const BLOCKS_KEYS = new Set(['kind', 'ids']);
+const CELL_KEYS = new Set(['kind', 'block', 'row', 'col']);
+const POSITION_KEYS = new Set(['block', 'rel']);
+
+// Kanban's ids are ASCII and at most 128 characters. Nothing else is an id.
+const RECORD_ID = /^[\x20-\x7e]+$/;
+// A base64 relative position: valid alphabet, valid padding, decodable length.
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+const refuse = (reason) => ({ ok: false, reason });
+const accept = (target) => ({ ok: true, target });
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const onlyKeys = (value, allowed) => {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) return false;
+  return true;
+};
+
+// UTF-8 length by hand: the host bounds bytes, and neither a test environment nor an
+// old browser is guaranteed a TextEncoder.
+function utf8Length(text) {
+  let length = 0;
+  for (const character of text) {
+    const code = character.codePointAt(0);
+    length += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+  }
+  return length;
+}
+
+function pageId(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && !CONTROL.test(value)
+    && utf8Length(value) <= MAX_PAGE_ID_BYTES;
+}
+
+function relativePosition(value) {
+  if (typeof value !== 'string' || !value.length || value.length % 4 !== 0 || !BASE64.test(value)) return false;
+  const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;
+  return (value.length / 4) * 3 - padding <= MAX_REL_BYTES;
+}
+
+function positionOf(value) {
+  if (!isObject(value) || !onlyKeys(value, POSITION_KEYS)) return null;
+  if (!pageId(value.block) || !relativePosition(value.rel)) return null;
+  return { block: value.block, rel: value.rel };
+}
+
+function selectionOf(value) {
+  if (!isObject(value)) return null;
+
+  if (value.kind === 'text') {
+    if (!onlyKeys(value, TEXT_KEYS)) return null;
+    const anchor = positionOf(value.anchor);
+    const head = positionOf(value.head);
+    return anchor && head ? { kind: 'text', anchor, head } : null;
+  }
+
+  if (value.kind === 'blocks') {
+    if (!onlyKeys(value, BLOCKS_KEYS) || !Array.isArray(value.ids)) return null;
+    if (!value.ids.length || value.ids.length > MAX_SELECTION_IDS) return null;
+    for (const id of value.ids) if (!pageId(id)) return null;
+    return { kind: 'blocks', ids: [...value.ids] };
+  }
+
+  if (value.kind === 'cell') {
+    if (!onlyKeys(value, CELL_KEYS)) return null;
+    if (!pageId(value.block) || !pageId(value.row) || !pageId(value.col)) return null;
+    return { kind: 'cell', block: value.block, row: value.row, col: value.col };
+  }
+
+  return null;
+}
+
+function withinSize(target) {
+  return utf8Length(JSON.stringify(target)) <= MAX_TARGET_BYTES;
+}
+
+function recordTarget(value) {
+  if (!onlyKeys(value, RECORD_KEYS)) return refuse('key');
+  const id = value.id;
+  if (typeof id !== 'string' || !id.length || id.length > MAX_RECORD_ID || !RECORD_ID.test(id)) return refuse('id');
+  if (value.field === undefined) {
+    const target = { kind: 'record', id };
+    return withinSize(target) ? accept(target) : refuse('size');
+  }
+  if (typeof value.field !== 'string' || !RECORD_FIELDS.includes(value.field)) return refuse('field');
+  const target = { kind: 'record', id, field: value.field };
+  return withinSize(target) ? accept(target) : refuse('size');
+}
+
+function pageTarget(value) {
+  if (!onlyKeys(value, PAGE_KEYS)) return refuse('key');
+  if (value.v !== PRESENCE_VERSION) return refuse('version');
+  if (!pageId(value.epoch)) return refuse('epoch');
+  if (!Number.isSafeInteger(value.generation) || value.generation < 0) return refuse('generation');
+  const selection = selectionOf(value.selection);
+  if (!selection) return refuse('selection');
+  const target = { kind: 'page', v: PRESENCE_VERSION, epoch: value.epoch, generation: value.generation, selection };
+  return withinSize(target) ? accept(target) : refuse('size');
+}
+
+/**
+ * Read one `editing` value.
+ *
+ * @param {*} value
+ * @returns {{ok: true, target: null|string|Object}|{ok: false, reason: string}}
+ */
+export function validateTarget(value) {
+  if (value === null) return accept(null);
+  if (typeof value === 'string') return EDITING_PATH.test(value) ? accept(value) : refuse('path');
+  if (!isObject(value)) return refuse('shape');
+  if (value.kind === 'record') return recordTarget(value);
+  if (value.kind === 'page') return pageTarget(value);
+  return refuse('kind');
+}
+
+/**
+ * The person-level `editing` value: the legacy string or a record target. Page
+ * coordinates live only in `sessions`, never on a person.
+ */
+export function normalizeEditing(value) {
+  const result = validateTarget(value === undefined ? null : value);
+  if (!result.ok) return null;
+  if (result.target !== null && typeof result.target === 'object' && result.target.kind !== 'record') return null;
+  return result.target;
+}
+
+/**
+ * A stable key for a validated target, so the sender can tell whether the target
+ * it holds is the one it sent. Expects `validateTarget`'s output.
+ */
+export function targetKey(target) {
+  if (target === null || target === undefined) return '';
+  if (typeof target === 'string') return `path:${target}`;
+  return `target:${JSON.stringify(target)}`;
+}
+
+/**
+ * Read one public session. `n` is monotonic within a session: a value below the
+ * one already seen for that session id cannot overwrite the newer one.
+ *
+ * @param {Array} value
+ * @param {Map<string, Object>} [previous]
+ */
+export function normalizeSessions(value, previous = null) {
+  const list = Array.isArray(value) ? value : [];
+  const sessions = [];
+  for (const item of list) {
+    if (!isObject(item)) continue;
+    const id = pageId(item.id) ? item.id : null;
+    if (!id) continue;
+    const n = Number.isSafeInteger(item.n) && item.n >= 0 ? item.n : 0;
+    const seen = previous && previous.get(id);
+    if (seen && n < seen.n) {
+      sessions.push(seen);
+      continue;
+    }
+    const editing = validateTarget(item.editing === undefined ? null : item.editing);
+    sessions.push({ id, you: item.you === true, n, editing: editing.ok ? editing.target : null });
+  }
+  return sessions;
+}
+
+/** The private recipient-specific transport block. Never published in a snapshot. */
+export function normalizeSelfSession(value) {
+  if (!isObject(value)) return null;
+  const id = pageId(value.id) ? value.id : null;
+  const token = typeof value.token === 'string' && value.token.length ? value.token : null;
+  return id && token ? { id, token } : null;
+}
+
+/**
+ * The exact body a target is sent as.
+ *
+ * The legacy dotted path and a clear keep the single-field shape every host
+ * already accepts, character for character. A record or page target uses the
+ * extended envelope once the connection has issued a session token; before that a
+ * record may still travel in the single-field shape, and a page target — whose
+ * coordinates need the envelope — has no body at all.
+ *
+ * @param {{target: *, session?: ?{token: string}, n?: number}} request
+ * @returns {?Object}
+ */
+export function requestBody({ target = null, session = null, n = 0 }) {
+  if (target === null || target === undefined || typeof target === 'string') return { editing: target ?? null };
+  const token = session && typeof session.token === 'string' && session.token.length ? session.token : null;
+  if (!token) return target.kind === 'record' ? { editing: target } : null;
+  if (!Number.isSafeInteger(n) || n < 0) return null;
+  return { v: PRESENCE_VERSION, session: token, n, editing: target };
+}

package/src/sync/presence.js

@@ -6,6 +6,12 @@
  * recipient, from that recipient's own access; nothing here asks for a name and
  * nothing here can widen what arrived.
  *
+ * The roster itself is not here: it lives in `presence-store.js`, which is what
+ * `clay.presence` hands to a page and what a caret adapter reads. This module is
+ * the chrome a reader sees — the squares, the count and the tip — and the visual
+ * library behind it stays a first-use download, so a reader who draws nothing
+ * still has a roster and still fetches none of it.
+ *
  * THE RULE THIS FILE EXISTS TO GET RIGHT.
  *
  * captureForSaveAndComparison() clones the document, hands that clone to peers
@@ -39,15 +45,39 @@
 import { hostSupports } from '../core/host-meta.js';
 import { make, set } from '../lib/hostile-css.js';
 import { initialsOf, personColor } from '../lib/person-face.js';
-import { pageScheme, RUNTIME_ONLY } from '../ui/bevel-controls.js';
-import { TOKENS, FONT_MONO, SHADOW } from '../ui/bevel.js';
+import { presence as store } from './presence-store.js';
 
 // Two initials at 11px need about 15px of the square, so the overlap has to
 // leave that much clear or the neighbouring square eats the second letter.
 const SIZE = 30;
 const OVERLAP = 6;
-const FONT = `600 11px/1 ${FONT_MONO}`;
-const LABEL_FONT = `500 11px/1.4 ${FONT_MONO}`;
+
+// The palette, the marking token and the two faces are the Bevel subset, which is a
+// first-use download: a reader alone on a document never draws a square, so it never
+// fetches them. Everything here is read after loadUI() resolves.
+let ui = null;
+let uiLoad = null;
+
+function loadUI() {
+  uiLoad ??= Promise.all([import('../ui/bevel-controls.js'), import('../ui/bevel.js')])
+    .then(([controls, bevel]) => (ui = {
+      pageScheme: controls.pageScheme,
+      RUNTIME_ONLY: controls.RUNTIME_ONLY,
+      TOKENS: bevel.TOKENS,
+      SHADOW: bevel.SHADOW,
+      FONT: `600 11px/1 ${bevel.FONT_MONO}`,
+      LABEL_FONT: `500 11px/1.4 ${bevel.FONT_MONO}`,
+    }))
+    .catch((error) => {
+      uiLoad = null;
+      throw error;
+    });
+  return uiLoad;
+}
+
+// A roster frame never rejects its way back to the stream: a chunk that failed to
+// arrive leaves the corner empty and the next frame asks again.
+const uiReady = () => loadUI().then(() => true, () => false);
 
 // all:initial first on every element, so a page rule has nothing left to reach; it
 // resets color-scheme and direction too, which are put back straight after.
@@ -60,30 +90,18 @@ const FACE = '#FFFCF6';
 
 /** Every element this module creates, marked the same way. */
 function runtimeRoot(el) {
-  el.setAttribute('clay', RUNTIME_ONLY);
+  el.setAttribute('clay', ui.RUNTIME_ONLY);
   return el;
 }
 
 /**
- * Read the roster frame defensively. Everything here arrived over a wire, and a
- * frame this function cannot understand must draw nothing rather than draw a
- * guess: `[object Object]` in a square is worse than an empty corner.
+ * What this module draws from a snapshot. The store keeps the rest — the target
+ * each person holds and their sessions — because none of it is chrome: a frame that
+ * only moved somebody's caret must leave every square where it is.
  */
-function normalize(data) {
-  const list = data && Array.isArray(data.people) ? data.people : [];
-  const people = [];
-  for (const person of list) {
-    if (!person || typeof person.id !== 'string' || !person.id) continue;
-    const name = typeof person.name === 'string' && person.name.trim() ? person.name.trim() : 'Someone';
-    people.push({
-      id: person.id,
-      name,
-      you: person.you === true,
-    });
-  }
-  const count = data && data.anonymous;
-  const anonymous = typeof count === 'number' && Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
-  return { people, anonymous };
+function faces(snapshot) {
+  const people = snapshot.people.map((person) => ({ id: person.id, name: person.name, you: person.you }));
+  return { people, anonymous: snapshot.anonymous };
 }
 
 class Presence {
@@ -99,10 +117,21 @@ class Presence {
   /**
    * Does this host run presence at all? Asked once, of /_/meta, and never
    * inferred from a frame arriving: the answer decides whether the chrome is
-   * built, so a host that says nothing draws nothing forever.
+   * built, so a host that says nothing draws nothing forever. The two awareness
+   * capabilities travel with it, because the store publishes them in the same
+   * snapshot and a page reads them before it publishes a target.
    */
   supported() {
-    if (!this._gate) this._gate = hostSupports('presence').then((ok) => ok === true, () => false);
+    if (!this._gate) {
+      this._gate = Promise.all([
+        hostSupports('presence'),
+        hostSupports('record-awareness-v1'),
+        hostSupports('page-awareness-v1'),
+      ]).then(([supported, recordAwareness, pageAwareness]) => {
+        store.setCapabilities({ supported, recordAwareness, pageAwareness });
+        return supported === true;
+      }, () => false);
+    }
     return this._gate;
   }
 
@@ -115,19 +144,20 @@ class Presence {
    * @returns {Promise<void>}
    */
   async update(data) {
-    const next = normalize(data);
+    const next = faces(store.receive(data));
     const same = this.root && JSON.stringify(next) === JSON.stringify(this.roster);
     this.roster = next;
     if (!(await this.supported())) return;
     if (same) {
-      set(this.root, 'color-scheme', pageScheme());
+      set(this.root, 'color-scheme', ui.pageScheme());
       return;
     }
-    this.render();
+    await this.render();
   }
 
   /** The stream went away, so the roster is no longer true about anything. */
   clear() {
+    store.clear();
     this.roster = { people: [], anonymous: 0 };
     if (!this.root) return;
     this.root.remove();
@@ -137,7 +167,7 @@ class Presence {
     this.tip = null;
   }
 
-  render() {
+  async render() {
     const { people, anonymous } = this.roster;
 
     // A person alone on a document is told nothing at all. The count is the
@@ -148,10 +178,11 @@ class Presence {
       this.hide();
       return;
     }
+    if (!(await uiReady())) return;
     if (!this.build()) return;
 
     this.hideTip();
-    set(this.root, 'color-scheme', pageScheme());
+    set(this.root, 'color-scheme', ui.pageScheme());
     this.stack.textContent = '';
     for (const person of people) {
       this.stack.appendChild(this.avatar(person));
@@ -184,14 +215,14 @@ class Presence {
 
     this.root = runtimeRoot(make('div', [
       ...RESET,
-      `color-scheme:${pageScheme()}`,
+      `color-scheme:${ui.pageScheme()}`,
       'position:fixed',
       'top:calc(12px + env(safe-area-inset-top,0px))',
       'right:calc(12px + env(safe-area-inset-right,0px))',
       'z-index:2147483000',
       'display:flex', 'align-items:center', 'gap:8px',
       'max-width:calc(100vw - 24px)',
-      `font:${LABEL_FONT}`, `color:${TOKENS.ink}`,
+      `font:${ui.LABEL_FONT}`, `color:${ui.TOKENS.ink}`,
       // Only the squares take a pointer. A fixed corner that swallowed clicks
       // would take a bite out of whatever the page put underneath it.
       'pointer-events:none',
@@ -202,10 +233,10 @@ class Presence {
       ...RESET,
       'box-sizing:border-box', 'flex:none', 'white-space:nowrap',
       'padding:3px 8px', 'border-radius:0',
-      `background:${TOKENS.surface}`, `color:${TOKENS.muted}`,
-      `border:1px solid ${TOKENS['line-2']}`,
-      `font:${LABEL_FONT}`, 'letter-spacing:.02em',
-      `box-shadow:${SHADOW}`,
+      `background:${ui.TOKENS.surface}`, `color:${ui.TOKENS.muted}`,
+      `border:1px solid ${ui.TOKENS['line-2']}`,
+      `font:${ui.LABEL_FONT}`, 'letter-spacing:.02em',
+      `box-shadow:${ui.SHADOW}`,
       'display:none',
       'pointer-events:none',
     ]));
@@ -224,9 +255,9 @@ class Presence {
       'position:absolute', 'top:100%', 'right:0', 'margin-top:6px',
       'box-sizing:border-box', 'white-space:nowrap', 'pointer-events:none',
       'padding:5px 9px', 'border-radius:0',
-      `background:${TOKENS.ink}`, `color:${TOKENS.ground}`,
-      `font:${LABEL_FONT}`, 'letter-spacing:.02em',
-      `box-shadow:${SHADOW}`,
+      `background:${ui.TOKENS.ink}`, `color:${ui.TOKENS.ground}`,
+      `font:${ui.LABEL_FONT}`, 'letter-spacing:.02em',
+      `box-shadow:${ui.SHADOW}`,
       'display:none',
     ]));
     this.tip.setAttribute('data-clay-presence-tip', '');
@@ -245,10 +276,10 @@ class Presence {
       'box-sizing:border-box', 'flex:none',
       `width:${SIZE}px`, `height:${SIZE}px`, 'border-radius:0',
       'display:flex', 'align-items:center', 'justify-content:center',
-      `font:${FONT}`, 'letter-spacing:.02em',
+      `font:${ui.FONT}`, 'letter-spacing:.02em',
       `margin-left:-${OVERLAP}px`,
       'border-width:2px', 'border-style:solid', 'background-image:none',
-      `box-shadow:${SHADOW}`,
+      `box-shadow:${ui.SHADOW}`,
       'user-select:none', 'cursor:default', 'pointer-events:auto',
       ...skin,
     ], initialsOf(person.name)));

package/src/sync/saved-handoff.js

@@ -0,0 +1,200 @@
+// The reader's half of a live switch: what the saved lane hands to an entry without
+// stopping, and what it takes back when the entry is refused.
+//
+// A reader owns the saved lane — the transport it opened, or the frames generic sync
+// applies to the page — and a switch needs that one lane, never a second stream. So
+// preparation holds the queue instead of closing it: an apply already on the wire
+// finishes, a file that arrives meanwhile keeps its place, and a repair the host asked
+// for stays owed. `reconcile` applies what was held, `resume` gives the lane back
+// exactly as it was, and `commit` retires it only onto a receipt a successor can build
+// from. Nothing here clears a buffer, aborts a request or stops a stream before commit.
+//
+// This is a dynamic target: a reader that never enters edit never fetches it.
+
+const fail = (message, code) => Object.assign(new Error(`clayjs: ${message}`), { code });
+
+const newer = (staged, candidate) =>
+  !staged || candidate.seq === null || staged.seq === null || candidate.seq > staged.seq ? candidate : staged;
+
+/**
+ * A transport's handoff, built out of the transport's own takeover points: `adopt`
+ * moves the acknowledged sink here, so nothing is applied and the receipt still moves
+ * only onto bytes a sink took. `stop` is never called before commit.
+ *
+ * `yieldArticle` gives the article up to a switch that mounts over it and
+ * `reclaimArticle` takes it back when that switch is refused; both are the reader's
+ * own, so the queue and the receipt never move while the article is not its.
+ *
+ * @param {Object} lane
+ * @param {Object} lane.stream - the transport this reader opened
+ * @param {function(Object): boolean} lane.apply - apply one file to the article
+ * @param {function(): boolean} lane.retire - give up the article and its claim
+ * @param {function(): boolean} lane.yieldArticle - release the article, keep the queue
+ * @param {function(): boolean} lane.reclaimArticle - take the article back and repaint
+ */
+function streamHandoff({ stream, apply, retire, yieldArticle = () => false, reclaimArticle = () => false }) {
+  let staged = null;
+  let yielded = false;
+  stream.adopt({
+    onSnapshot: (candidate) => {
+      staged = newer(staged, candidate);
+      return true;
+    },
+  });
+  const take = () => {
+    const candidate = staged;
+    staged = null;
+    return candidate;
+  };
+  return {
+    get represented() {
+      return stream.represented;
+    },
+    // The newest file this reader holds: a snapshot the transport took while the
+    // switch prepared is a file the session was not built from.
+    get held() {
+      return staged ?? stream.represented;
+    },
+    yieldArticle() {
+      if (yielded || !yieldArticle()) return false;
+      yielded = true;
+      return true;
+    },
+    reclaimArticle() {
+      if (!yielded || !reclaimArticle()) return false;
+      yielded = false;
+      return true;
+    },
+    reconcile() {
+      const candidate = take();
+      if (candidate && !apply(candidate)) return Promise.reject(fail("the switch could not apply the saved file", "load-failed"));
+      return Promise.resolve();
+    },
+    resume() {
+      stream.adopt({ onSnapshot: apply });
+      const candidate = take();
+      if (candidate) apply(candidate);
+    },
+    commit() {
+      // Whatever the old owner was never shown goes on screen first: the receipt a
+      // successor is built from and the article it replaces must name one file. An
+      // article already yielded belongs to the switch: it reconciled the queue and
+      // refused anything newer before asking for this commit, so nothing staged is
+      // its to paint, and the read-only half only stops the stream and retires.
+      if (!yielded) {
+        const candidate = take();
+        if (candidate && !apply(candidate)) return false;
+      }
+      if (stream.represented.bytes === null) return false;
+      stream.stop();
+      return retire();
+    },
+  };
+}
+
+/**
+ * A reader's handoff: its own transport, or the engine that feeds the page.
+ *
+ * @param {Object} reader
+ * @param {?Object} reader.stream - the transport this reader owns, if any
+ * @param {Object} reader.options - `{ signal, deadline }` for the lane
+ * @param {function(Object): boolean} reader.apply - apply one file to the article
+ * @param {function(): boolean} reader.retire - give up the article and its claim
+ * @param {function(): boolean} reader.yieldArticle - release the article, keep the queue
+ * @param {function(): boolean} reader.reclaimArticle - take the article back and repaint
+ * @returns {Promise<Object>}
+ */
+export async function readerHandoff({ stream, options, apply, retire, yieldArticle = () => false, reclaimArticle = () => false }) {
+  if (stream) return streamHandoff({ stream, apply, retire, yieldArticle, reclaimArticle });
+  const lane = await import("./live-sync.js").then(({ liveSync }) => liveSync.prepareHandoff(options));
+  return {
+    get represented() {
+      return lane.represented;
+    },
+    get held() {
+      return lane.held;
+    },
+    yieldArticle,
+    reclaimArticle,
+    reconcile: () => lane.reconcile(),
+    resume: () => lane.resume(),
+    commit: () => lane.commit() && retire(),
+  };
+}
+
+/**
+ * A sync engine's handoff: hold the saved lane's frames and the repair it owes, and
+ * answer with the file it last applied.
+ *
+ * @param {Object} lane - the engine instance
+ * @param {Object} options - `{ signal, deadline }`
+ * @returns {Promise<Object>}
+ */
+export async function engineHandoff(lane, { signal, deadline = 15000 } = {}) {
+  const until = Date.now() + deadline;
+  // An apply already in flight is the one thing preparation waits for: its bytes are
+  // the file the switch will be built from.
+  while (lane._morphInFlight) {
+    if (signal?.aborted) {
+      lane._handoffHeld = false;
+      throw fail("the switch was cancelled", "aborted");
+    }
+    if (Date.now() >= until) {
+      lane._handoffHeld = false;
+      throw fail("the apply did not settle", "timeout");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+  const queued = () => lane._pendingHtml != null || lane._pendingExternal != null;
+  return {
+    get represented() {
+      return lane._represented;
+    },
+    // The newest file the lane holds, queued or applied: a frame the engine took
+    // while the switch prepared is newer than the one on the page, and a session
+    // built from the older one must refuse rather than stop the lane over it.
+    get held() {
+      let newest = lane._represented;
+      if (lane._pendingHtml != null) {
+        newest = newer(newest, {
+          bytes: lane._pendingHtml,
+          etag: lane._pendingEtag ?? null,
+          seq: lane._pendingSeq ?? null,
+        });
+      }
+      if (lane._pendingExternal) {
+        newest = newer(newest, {
+          bytes: lane._pendingExternal.html,
+          etag: lane._pendingExternal.etag ?? null,
+          seq: lane._pendingExternal.seq ?? null,
+        });
+      }
+      return newest;
+    },
+    async reconcile() {
+      if (!lane._handoff || lane.isDestroyed) return;
+      for (let pass = 0; pass < 8; pass++) {
+        if (lane._morphInFlight) {
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          continue;
+        }
+        if (!queued()) return;
+        await lane._runPending();
+      }
+      if (queued()) throw fail("the held frame could not be applied", "load-failed");
+    },
+    resume() {
+      if (!lane._handoff) return;
+      lane._handoff = null;
+      lane._handoffHeld = false;
+      lane._scheduleNextFrame();
+    },
+    commit() {
+      if (!lane._represented.bytes) return false;
+      lane._handoff = null;
+      lane._handoffHeld = false;
+      lane.stop();
+      return true;
+    },
+  };
+}