@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/sync.ts

@@ -0,0 +1,1257 @@
+// THE EDITOR'S LIVE SYNC CLIENT (collaboration lanes R4 and R5).
+//
+// When the server turns live sync on for a Project (`LoadedShot.sync`), the
+// editor stops PUTting whole documents and sends what changed instead, as
+// batches of sync ops over one socket to the document's session (store's
+// shotSession.ts). The session orders every batch and tells everybody.
+//
+//   C   the confirmed document: the server's, at `seq`
+//   S   batches of this document's OTHER open tabs on this device, shared over
+//       a BroadcastChannel: shown, never sent
+//   P   batches this tab sends: its own queue's, and those of any closed tab
+//       it adopted, oldest first
+//
+// What the author sees is C with S and P replayed on top. Three paths change it:
+//
+//   a local edit   diffed against what was last minted, into one batch.
+//                  A drag mints at most every 50 ms (20 Hz). Each batch is
+//                  written to IndexedDB first, then sent
+//   our own ack    folds into C and pops P. When the server applied it
+//                  differently (a rename, a repair, an op a concurrent delete
+//                  beat) the view is rebuilt from C
+//   another entry  folds into C. When it touches nothing pending it lands on
+//                  the view directly; otherwise the pending batches are
+//                  replayed on the new C, and one of ours that no longer
+//                  validates is dropped and said
+//
+// ── ONE BATCH IN FLIGHT ─────────────────────────────────────────────────────
+//
+// Stop and wait: the next send waits for the ack (or nack) of the last. What
+// piled up meanwhile goes as ONE wire batch under the last counter, so a drag
+// over a slow link is one message per round trip, not one per pointermove.
+// The server's dedupe (`n <= acked`) then covers every batch it folded. Only
+// batches of one queue are combined.
+//
+// ── BEFORE ANY SERVER MESSAGE, MINT ─────────────────────────────────────────
+//
+// The overlap test and the rebuild both reason about P, so the local edits
+// not yet in P (a drag between two 50 ms mints) are minted first. After that
+// the editor's document IS the view, and a remote change can be landed on it
+// as a diff (`host.adopt`), which an open drag survives (engine's
+// `history.adopt` rebases the gesture).
+//
+// ── QUEUES THAT OUTLIVE THEIR TAB (R5) ───────────────────────────────────────
+//
+// Each tab holds the Web Lock `dailies-sync-q:<q>` for its life. A queue in
+// IndexedDB whose lock is free belongs to a tab that is gone: this tab claims
+// the lock, adopts the batches and sends them as its own, then forgets the
+// queue. A queue whose lock is held is a sibling tab's: its batches (from
+// IndexedDB, then each new one over the channel) are shown here, and a
+// waiting lock request adopts them the moment that tab closes. The join names
+// every such queue, and the reply says how far each was acked: a batch the
+// server already applied is never replayed nor sent twice (a resent `new`
+// would make a second copy).
+//
+// ── HOLDS ───────────────────────────────────────────────────────────────────
+//
+// Three things stop editing until they clear, each said by the editor:
+//
+//   upgrade        the server runs a newer schema: the editor reloads
+//   older-server   this editor is newer than the server: it retries
+//   quota          IndexedDB is full: "Try again" stores what waits
+//
+// A queue written at an older schema (the tab that reloaded for an upgrade)
+// is migrated on the join reply: its base and its result both go through
+// `migrateShotDoc` and are diffed again, as one batch.
+import {
+  CURRENT_SHOT_SCHEMA_VERSION,
+  applyOps,
+  canonicalize,
+  diffDoc,
+  invertOps,
+  migrateShotDoc,
+  remapIds,
+  renameCollisions,
+  syncValidateScope,
+  validateShotDoc,
+} from "@dailies-studio/shot/doc";
+import type {
+  Doc3D,
+  SyncEntry,
+  SyncOp,
+  SyncPresence,
+  SyncPresenceMessage,
+  SyncQueueAcks,
+  SyncServerMessage,
+  SyncSnapshot,
+} from "@dailies-studio/shot/doc";
+import type { HistoryDelta } from "@dailies-studio/engine";
+import { isQuotaError } from "./syncCache.js";
+import type { SyncCache, SyncStoredBatch } from "./syncCache.js";
+
+/** The server closes a frame over 512 KB (1009). Margin for the envelope. */
+const SEND_BUDGET = 512 * 1024 - 8 * 1024;
+/** A drag mints at most this often. */
+const SCRUB_MS = 50;
+/** How long an edit makes its layer "ours" for measured writes (text fit). */
+const TOUCH_MS = 10_000;
+const RETRY_MS = 1_000;
+/** The most other queues one join names (the protocol's cap). */
+const MAX_JOIN_QUEUES = 64;
+
+export interface SyncSocket {
+  send(text: string): void;
+  close(): void;
+}
+
+/** Open the document's socket. `close` gets the close code. */
+export type SyncConnect = (
+  docId: string,
+  on: { open(): void; message(text: string): void; close(code: number): void },
+) => SyncSocket;
+
+/** What stops editing until it clears (see HOLDS above). */
+export type SyncHold = "upgrade" | "older-server" | "quota";
+
+export interface SyncStatus {
+  /** This tab's batches the server has not applied (its own and adopted). */
+  pending: number;
+  /** Every change on this device the server has not applied: `pending`
+   *  plus what this document's other tabs hold. */
+  waiting: number;
+  /** An edit exists that is only in memory: not minted yet, or a batch not
+   *  (yet) in IndexedDB. What the close guard warns about. */
+  unstored: boolean;
+  /** Joined to the session. */
+  connected: boolean;
+  /** When the next reconnect is due (ms since the epoch), while one waits. */
+  retryAt: number | null;
+  /** Open tabs of this document on this device, this one included. */
+  tabs: number;
+  hold: SyncHold | null;
+}
+
+export interface SyncHost {
+  /** Land a server change on the editor's document with no undo entry, and
+   *  answer the document now current. */
+  adopt(fn: (doc: Doc3D) => Doc3D): Doc3D;
+  status(s: SyncStatus): void;
+  /** A checkpoint stored the session's document as `rev`. `clean`: the
+   *  editor's document is that one (nothing of ours is pending). */
+  saved(rev: string, clean: boolean): void;
+  /** The session refused this tab's writes by role. */
+  forbidden(): void;
+  /** The document was deleted (close 4004). `info`: who trashed it, and the
+   *  Trash handle, when the session said (R10). `pending`: what this tab
+   *  holds that never reached the server, as ops on the confirmed document;
+   *  `revive()` sends it once the document is back. */
+  gone(info?: SyncGoneInfo | null, pending?: { base: Doc3D; ops: SyncOp[] } | null): void;
+  /** The Project was renamed to `to` (R10). The socket follows the id, so
+   *  nothing else changes. `by`: who did it, when the session knows. */
+  renamed?(to: string, by: string | null): void;
+  /** The server runs schema `sv`, newer than this editor: reload. */
+  upgrade(sv: number): void;
+  toast(message: string): void;
+  /** Who else is here (R7): a session's `peers`, `peer` or `peer-left`, or
+   *  null when the socket went and nobody is known to be here any more. */
+  presence?(msg: SyncPresenceMessage | null): void;
+}
+
+/** What the session said of a delete before it closed the socket. */
+export interface SyncGoneInfo {
+  by: string | null;
+  trashId?: string;
+}
+
+export interface SyncClient {
+  /** The editor's document changed by the author. `scrubbing`: a gesture is
+   *  open, so minting is throttled. */
+  localChange(doc: Doc3D, scrubbing: boolean): void;
+  /** Resolves once every edit so far is acked AND checkpointed. */
+  flush(): Promise<void>;
+  /** Resolves once a checkpoint as `rev` was announced (a server write this
+   *  tab asked for over HTTP, such as a library import, has arrived). */
+  reach(rev: string): Promise<void>;
+  /** Did this tab edit the layer lately? Measured writes (an auto text fit)
+   *  are made only by the tab that caused them, or every open tab would. */
+  touched(layerId: string): boolean;
+  /** Where this tab is now (R7). Sent while joined; the latest is sent again
+   *  after every join. Never stored. */
+  presence(p: SyncPresence): void;
+  /** Reconnect now instead of when the backoff says ("Try now", the
+   *  browser coming back online). */
+  retryNow(): void;
+  /** Store what is only in memory again, after a quota refusal; `prune`
+   *  first forgets other documents' confirmed copies. True once nothing
+   *  waits only in memory and the hold is gone. */
+  retryStorage(prune: boolean): Promise<boolean>;
+  /** Join again after `gone` (the Project was restored from the Trash): the
+   *  restored session is a new epoch, so its snapshot replays what waits. */
+  revive(): void;
+  /** Close, and forget every edit this tab holds for the document, stored
+   *  ones too: they were saved somewhere else ("Save as copy"), and a later
+   *  restore must not replay them. */
+  discard(): void;
+  close(): void;
+}
+
+/** The part of the Web Locks API this uses (`navigator.locks`). */
+export interface SyncLocks {
+  request(name: string, options: LockOptions, callback: (lock: Lock | null) => Promise<void> | void): Promise<unknown>;
+}
+
+/** The part of a BroadcastChannel this uses. */
+export interface SyncChannel {
+  postMessage(message: unknown): void;
+  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  close(): void;
+}
+
+export interface SyncClientOptions {
+  docId: string;
+  /** The Project's name, kept with the confirmed copy for an offline boot. */
+  name?: string;
+  /** The editor's document as loaded, and the rev it was read at. */
+  doc: Doc3D;
+  rev: string;
+  connect: SyncConnect;
+  cache: SyncCache | null;
+  host: SyncHost;
+  /** `GET /api/shots/:name?sync=1`, for a snapshot too large to send inline. */
+  fetchSnapshot(): Promise<SyncSnapshot>;
+  /** This tab's queue. Fresh per client. */
+  q?: string;
+  /** Web Locks, or null where there are none: then no queue of another tab
+   *  is adopted or shown. */
+  locks?: SyncLocks | null;
+  /** The channel this document's tabs share (`dailies-sync:<ws>:<docId>`). */
+  channel?: SyncChannel | null;
+  /** The editor booted from this device's copy with no network: the cached
+   *  confirmed document and every stored batch are the view at once. */
+  offline?: boolean;
+  now?(): number;
+}
+
+interface Pending {
+  q: string;
+  n: number;
+  base: number;
+  ops: SyncOp[];
+  bytes: number;
+  /** IndexedDB answered (or there is none): sendable. */
+  ready: boolean;
+  /** In IndexedDB. */
+  stored: boolean;
+}
+
+/** What tabs of one document tell each other. */
+type ChannelMessage =
+  | { t: "hello"; q: string }
+  | { t: "here"; q: string }
+  | { t: "batch"; q: string; n: number; base: number; ops: SyncOp[] }
+  | { t: "drop"; q: string; n: number };
+
+const encoder = new TextEncoder();
+const bytesOf = (x: unknown): number => encoder.encode(JSON.stringify(x)).length;
+const noop = (): void => undefined;
+export const syncLockName = (q: string): string => `dailies-sync-q:${q}`;
+
+/** Every path an op changes, with an ordered-list op standing for its list. */
+function touchedPaths(ops: readonly SyncOp[]): string[][] {
+  return ops.map((op) => (op.op === "ins" || op.op === "mv" || op.op === "rm" ? op.p.slice(0, -1) : [...op.p]));
+}
+
+const nested = (a: readonly string[], b: readonly string[]): boolean => {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) if (a[i] !== b[i]) return false;
+  return true;
+};
+
+/** Does any of `a` write a path at, above or below one `b` writes? */
+export function opsOverlap(a: readonly SyncOp[], b: readonly SyncOp[]): boolean {
+  const pa = touchedPaths(a);
+  return touchedPaths(b).some((q) => pa.some((p) => nested(p, q)));
+}
+
+/**
+ * Undo under live sync (R6, Paper page 21 "Undo is yours only"). An undo or
+ * redo is the inverse ops of this author's own change, and an op is skipped
+ * when `theirs` (what others changed since) wrote at, above or below its path,
+ * or when its target is gone. The result goes out through sync like any edit.
+ *
+ * ponytail: an undo that would leave the document less valid than it found it
+ * (half of a layer a peer still edits, a layer whose material a peer deleted)
+ * is dropped whole rather than repaired op by op.
+ */
+export const undoDelta: HistoryDelta<Doc3D, SyncOp> = {
+  diff: diffDoc,
+  invert: invertOps,
+  apply(doc, ops, theirs) {
+    const taken = theirs.map((t) => t.p);
+    const kept = ops.filter((op) => !taken.some((p) => nested(p, op.p)));
+    const { doc: next, skipped } = applyOps(doc, kept);
+    const applied = kept.filter((op) => !skipped.some((s) => s.op === op));
+    if (applied.length === 0) return { doc, applied };
+    const scope = syncValidateScope(applied) ?? undefined;
+    if (validateShotDoc(next, scope).length > validateShotDoc(doc, scope).length) return { doc, applied: [] };
+    return { doc: next, applied };
+  },
+};
+
+/** Replay one batch on `view` the way the server would apply it. */
+function replay(view: Doc3D, ops: readonly SyncOp[]): { next: Doc3D; ops: SyncOp[]; renamed: boolean; valid: boolean } {
+  const renamed = renameCollisions(view, ops);
+  const next = canonicalize(applyOps(view, renamed.ops).doc, renamed.ops);
+  const valid = validateShotDoc(next, syncValidateScope(renamed.ops) ?? undefined).length === 0;
+  return { next, ops: renamed.ops, renamed: renamed.renames.length > 0, valid };
+}
+
+export function createSyncClient(o: SyncClientOptions): SyncClient {
+  const { docId, connect, cache, host } = o;
+  const q = o.q ?? crypto.randomUUID();
+  const now = o.now ?? (() => Date.now());
+  const locks = o.locks ?? null;
+  // Sharing between tabs needs the locks: they are what says a tab is gone.
+  const channel = locks === null ? null : (o.channel ?? null);
+  const sv = CURRENT_SHOT_SCHEMA_VERSION;
+
+  let C: { doc: Doc3D; seq: number; epoch: string; rev: string } | null = null;
+  /** The cached confirmed copy when it is at an older schema: the base an
+   *  old queue's batches are migrated from. */
+  let oldBase: Doc3D | null = null;
+  const P: Pending[] = [];
+  const S = new Map<string, Pending[]>();
+  /** The highest counter of each sibling queue the server applied: a channel
+   *  batch at or under it is already in C. */
+  const siblingAcked = new Map<string, number>();
+  /** The queues this tab sends: its own and the adopted ones. */
+  const mine = new Set([q]);
+  /** Adopted queues the server has not yet said how far it acked: nothing of
+   *  them is sent before it does. */
+  const unconfirmed = new Set<string>();
+  /** Adopted batches written at an older schema, migrated on the join reply. */
+  const stale = new Map<string, SyncStoredBatch[]>();
+  /** Other tabs of this document that are open (their lock is held). */
+  const siblings = new Set<string>();
+  /** A waiting lock request per other queue: cancelled on close. */
+  const watching = new Map<string, AbortController>();
+  /** Releases the lock of each adopted queue, once it is drained. */
+  const holding = new Map<string, () => void>();
+  let releaseOwn: () => void = noop;
+  /** The queues the last join named. */
+  let named: string[] = [];
+  let counter = 0;
+  /** The wire batch awaiting its ack: its queue, the last counter it carried
+   *  and how many ops it sent. */
+  let inflight: { q: string; n: number; ops: number } | null = null;
+  /** Send one stored batch at a time up to this counter (a combined batch
+   *  was refused: find which one). */
+  let solo: { q: string; n: number } | null = null;
+  let local = o.doc;
+  let minted = o.doc;
+  let sock: SyncSocket | null = null;
+  let joined = false;
+  /** C is the server's (a join was answered), or this device's copy on an
+   *  offline boot: the view may be rebuilt from it. Before that a cached C
+   *  can be older than the editor's document and would flash. */
+  let trusted = false;
+  let hold: SyncHold | null = null;
+  let stopped = false;
+  /** `close()` ran: nothing revives this client. */
+  let closed = false;
+  let attempts = 0;
+  let retryAt: number | null = null;
+  let savedSeq = -1;
+  const revs: string[] = [o.rev];
+  /** Messages that arrived while a too-large snapshot is fetched. */
+  let held: SyncServerMessage[] | null = null;
+  let scrubTimer: ReturnType<typeof setTimeout> | null = null;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  const touchedAt = new Map<string, number>();
+  /** Where this tab last said it is, and whether the session has told us who
+   *  is here since the last join (then presence goes out). */
+  let where: SyncPresence | null = null;
+  let present = false;
+  /** The Project's name now: a rename under the session moves it. */
+  let name = o.name;
+  /** The session's `deleted` notice, for the 4004 that follows it. */
+  let goneInfo: SyncGoneInfo | null = null;
+  const waiters: Array<{ test: () => boolean; resolve: () => void; reject: (e: Error) => void }> = [];
+
+  // ── status and waiting ─────────────────────────────────────────────────────
+
+  function emit(): void {
+    let shown = 0;
+    for (const list of S.values()) shown += list.length;
+    for (const list of stale.values()) shown += list.length;
+    host.status({
+      pending: P.length,
+      waiting: P.length + shown,
+      unstored: local !== minted || P.some((b) => !b.stored),
+      connected: joined,
+      retryAt,
+      tabs: 1 + siblings.size,
+      hold,
+    });
+  }
+
+  function wait(test: () => boolean): Promise<void> {
+    if (test()) return Promise.resolve();
+    return new Promise((resolve, reject) => waiters.push({ test, resolve, reject }));
+  }
+
+  function settle(): void {
+    for (const w of [...waiters]) {
+      if (!w.test()) continue;
+      waiters.splice(waiters.indexOf(w), 1);
+      w.resolve();
+    }
+  }
+
+  function fail(why: string): void {
+    for (const w of waiters.splice(0)) w.reject(new Error(why));
+  }
+
+  function post(m: ChannelMessage): void {
+    try {
+      channel?.postMessage(m);
+    } catch {
+      // A closed channel: the siblings learn the rest from the server.
+    }
+  }
+
+  // ── storing ────────────────────────────────────────────────────────────────
+
+  const storedOf = (b: Pending): SyncStoredBatch => ({ q: b.q, n: b.n, docId, base: b.base, sv, ops: b.ops });
+
+  /** Write one batch to IndexedDB, then tell the other tabs. */
+  function store(b: Pending): Promise<void> {
+    return cache!.putBatch(storedOf(b)).then(
+      () => {
+        b.stored = true;
+        post({ t: "batch", q: b.q, n: b.n, base: b.base, ops: b.ops });
+      },
+      (e: unknown) => {
+        // Out of space: editing pauses so nothing more lives only in memory.
+        // Any other refusal: this batch stays in memory and the close guard
+        // keeps warning until it is acked.
+        if (isQuotaError(e) && hold === null) hold = "quota";
+      },
+    );
+  }
+
+  // ── local edits ────────────────────────────────────────────────────────────
+
+  function mint(): void {
+    if (scrubTimer !== null) clearTimeout(scrubTimer);
+    scrubTimer = null;
+    if (local === minted || stopped) return;
+    const ops = diffDoc(minted, local);
+    minted = local;
+    if (ops.length === 0) return;
+    const t = now();
+    for (const op of ops) {
+      const i = op.p.indexOf("layersById");
+      const id = i < 0 ? undefined : op.p[i + 1];
+      if (id !== undefined) touchedAt.set(id, t);
+    }
+    const b: Pending = { q, n: ++counter, base: C?.seq ?? 0, ops, bytes: bytesOf(ops), ready: cache === null, stored: false };
+    P.push(b);
+    if (cache !== null) {
+      void store(b).finally(() => {
+        b.ready = true;
+        pump();
+        emit();
+      });
+    }
+    pump();
+  }
+
+  /** Forget an adopted queue once nothing of it waits, and let its lock go. */
+  function release(qq: string): void {
+    if (qq === q || P.some((b) => b.q === qq) || stale.has(qq)) return;
+    const free = holding.get(qq);
+    if (free === undefined) return;
+    holding.delete(qq);
+    mine.delete(qq);
+    unconfirmed.delete(qq);
+    void cache?.dropQueue(qq).catch(noop).finally(free);
+  }
+
+  /** Remove batches from P and IndexedDB, and tell the other tabs. */
+  function drop(batches: readonly Pending[]): void {
+    for (const b of batches) {
+      const i = P.indexOf(b);
+      if (i >= 0) P.splice(i, 1);
+      void cache?.dropBatches(b.q, b.n, b.n).catch(noop);
+      post({ t: "drop", q: b.q, n: b.n });
+    }
+    for (const qq of new Set(batches.map((b) => b.q))) release(qq);
+  }
+
+  /** Forget every batch of queue `qq` the server has applied, up to `n`. */
+  function popQueue(qq: string, n: number): void {
+    if (n <= 0) return;
+    if (mine.has(qq)) {
+      for (let i = P.length - 1; i >= 0; i--) if (P[i]!.q === qq && P[i]!.n <= n) P.splice(i, 1);
+      if (inflight !== null && inflight.q === qq && inflight.n <= n) inflight = null;
+      void cache?.dropBatches(qq, 0, n).catch(noop);
+      release(qq);
+      return;
+    }
+    // A sibling's: it forgets its own copy in IndexedDB.
+    siblingAcked.set(qq, Math.max(n, siblingAcked.get(qq) ?? 0));
+    const list = S.get(qq);
+    if (list === undefined) return;
+    const rest = list.filter((b) => b.n > n);
+    if (rest.length > 0) S.set(qq, rest);
+    else S.delete(qq);
+  }
+
+  /** Does a batch some other tab of this device holds have `n`? */
+  const showsSibling = (qq: string, n: number): boolean => S.get(qq)?.some((b) => b.n <= n) === true;
+
+  // ── sending ────────────────────────────────────────────────────────────────
+
+  function pump(): void {
+    // A quota hold still sends: an ack is what frees memory.
+    if (!joined || inflight !== null || stopped || sock === null || retryTimer !== null) return;
+    const batch: Pending[] = [];
+    let bytes = 0;
+    for (const b of P) {
+      if (!b.ready || unconfirmed.has(b.q)) break;
+      const single = solo !== null && solo.q === b.q && b.n <= solo.n;
+      if (batch.length > 0 && (b.q !== batch[0]!.q || bytes + b.bytes > SEND_BUDGET || single)) break;
+      batch.push(b);
+      bytes += b.bytes;
+      if (single) break;
+    }
+    const head = batch[0];
+    if (head === undefined) return;
+    if (head.bytes > SEND_BUDGET) {
+      // ponytail: one edit over a socket frame (a huge paste) is dropped and
+      // said; a whole-document merge PUT is the upgrade path.
+      drop([head]);
+      host.toast("That change was too large to send, so it was not kept. Try it in smaller steps.");
+      rebuild();
+      pump();
+      return;
+    }
+    const ops = batch.flatMap((b) => b.ops);
+    const last = batch[batch.length - 1]!;
+    inflight = { q: head.q, n: last.n, ops: ops.length };
+    sock.send(JSON.stringify({ t: "batch", doc: docId, q: head.q, n: last.n, base: head.base, sv, ops }));
+  }
+
+  // ── landing the server's changes ───────────────────────────────────────────
+
+  const entryOps = (e: SyncEntry): SyncOp[] => (e.extra === undefined ? e.ops : [...e.ops, ...e.extra]);
+
+  /** Put the view on the editor. `local === minted` holds (minted first).
+   *  An open drag replays its last capture on the result, which may differ
+   *  from the view where the rebuild moved what it drags: the drag is the
+   *  newer edit, so that difference is minted and sent. */
+  function land(view: Doc3D): void {
+    const ops = diffDoc(minted, view);
+    minted = view;
+    if (ops.length > 0) local = host.adopt((d) => applyOps(d, ops).doc);
+    mint();
+  }
+
+  /** Land ops on the view as they are: nothing pending replays after them. */
+  function landDirect(ops: readonly SyncOp[]): void {
+    minted = applyOps(minted, ops).doc;
+    local = host.adopt((d) => applyOps(d, ops).doc);
+    mint();
+  }
+
+  const remember = (rev: string): void => {
+    revs.push(rev);
+    if (revs.length > 32) revs.shift();
+  };
+
+  /** The view again: C with every pending batch replayed the way the server
+   *  would apply it, the other tabs' first. One of ours that no longer
+   *  validates is dropped and said, unless it is already in flight (its nack
+   *  will say so); one of another tab's is only left out (that tab drops it). */
+  function rebuild(): void {
+    if (C === null || !trusted) return;
+    let view = C.doc;
+    for (const list of S.values()) {
+      for (const b of list) {
+        const r = replay(view, b.ops);
+        if (r.valid) view = r.next;
+      }
+    }
+    for (const b of [...P]) {
+      const flying = inflight !== null && b.q === inflight.q && b.n <= inflight.n;
+      const r = replay(view, b.ops);
+      if (!flying && !r.valid) {
+        drop([b]);
+        host.toast("A change of yours conflicted with someone else's and was undone.");
+        continue;
+      }
+      if (!flying && r.renamed) {
+        b.ops = r.ops;
+        b.base = C.seq;
+      }
+      view = r.next;
+    }
+    land(view);
+  }
+
+  function foldEntry(e: SyncEntry): void {
+    C = { ...C!, doc: applyOps(C!.doc, entryOps(e)).doc, seq: e.seq };
+  }
+
+  /** Does anything pending on this device write where `ops` do? */
+  const pendingOverlap = (ops: readonly SyncOp[]): boolean =>
+    P.some((b) => opsOverlap(b.ops, ops)) || [...S.values()].some((list) => list.some((b) => opsOverlap(b.ops, ops)));
+
+  /** Rejoin from where C stands: a gap in the log, a session that forgot us,
+   *  or a queue adopted since the last join. */
+  function resync(): void {
+    const s = sock;
+    sock = null;
+    joined = false;
+    absent();
+    inflight = null;
+    s?.close();
+    open();
+  }
+
+  /**
+   * Batches an older editor wrote (it reloaded for an upgrade), as ONE batch
+   * at this schema: the base they were written on and the result, both
+   * migrated, diffed again. What the server already applied (`acked`) is part
+   * of the base. The batch keeps the last counter, so a resend still dedupes.
+   *
+   * ponytail: the base is this device's last confirmed copy at that schema,
+   * which can be older than the one the old tab wrote on; an op that only
+   * made sense on a newer base lands as a plain write or fails validation
+   * (then the rebuild drops it and says so).
+   */
+  function migrateStale(qq: string, acked: number): void {
+    const list = stale.get(qq);
+    if (list === undefined) return;
+    stale.delete(qq);
+    const sorted = [...list].sort((a, b) => a.n - b.n);
+    const rest = sorted.filter((b) => b.n > acked);
+    const last = sorted[sorted.length - 1]!.n;
+    if (rest.length === 0) {
+      void cache?.dropBatches(qq, 0, last).catch(noop);
+      return;
+    }
+    let ops: SyncOp[] | null = null;
+    if (oldBase !== null) {
+      try {
+        let base = oldBase;
+        for (const b of sorted) if (b.n <= acked) base = applyOps(base, b.ops).doc;
+        let top = base;
+        for (const b of rest) top = applyOps(top, b.ops).doc;
+        ops = diffDoc(migrateShotDoc(base), migrateShotDoc(top));
+      } catch {
+        ops = null;
+      }
+    }
+    if (ops === null) {
+      void cache?.dropBatches(qq, 0, last).catch(noop);
+      host.toast("Changes made before the editor was updated could not be brought over, so they were not kept.");
+      return;
+    }
+    if (ops.length === 0) {
+      void cache?.dropBatches(qq, 0, last).catch(noop);
+      return;
+    }
+    const b: Pending = { q: qq, n: last, base: C?.seq ?? 0, ops, bytes: bytesOf(ops), ready: cache === null, stored: false };
+    adoptInto([b]);
+    if (cache !== null) {
+      // The new batch overwrites the old one under the same key, then the
+      // older ones go: the edits are in IndexedDB at every moment.
+      void store(b)
+        .then(() => (b.stored ? cache.dropBatches(qq, 0, last - 1) : undefined))
+        .catch(noop)
+        .finally(() => {
+          b.ready = true;
+          pump();
+          emit();
+        });
+    }
+  }
+
+  /** Put adopted batches into P after whatever is in flight, before this
+   *  tab's own: they are older. */
+  function adoptInto(batches: readonly Pending[]): void {
+    let at = 0;
+    while (at < P.length && P[at]!.q !== q && !batches.some((b) => b.q === P[at]!.q)) at++;
+    while (at < P.length && inflight !== null && P[at]!.q === inflight.q && P[at]!.n <= inflight.n) at++;
+    P.splice(at, 0, ...batches);
+  }
+
+  /** What a join reply says of the queues: drop what was applied, migrate
+   *  what an older editor wrote, and let the adopted ones send. */
+  function joinedQueues(acked: number, queues: SyncQueueAcks | undefined): void {
+    popQueue(q, acked);
+    for (const qq of named) {
+      const n = queues?.[qq] ?? 0;
+      migrateStale(qq, n);
+      popQueue(qq, n);
+      unconfirmed.delete(qq);
+    }
+    joined = true;
+    trusted = true;
+    attempts = 0;
+    retryAt = null;
+    if (hold === "older-server") hold = null;
+  }
+
+  function onSnapshot(s: SyncSnapshot, acked: number, queues: SyncQueueAcks | undefined): void {
+    if (C === null || s.epoch !== C.epoch) savedSeq = -1;
+    C = { doc: s.doc, seq: s.seq, epoch: s.epoch, rev: s.rev };
+    remember(s.rev);
+    saveConfirmed();
+    // A snapshot replaces the log position: anything in flight is resent.
+    inflight = null;
+    joinedQueues(acked, queues);
+    rebuild();
+  }
+
+  function sendPresence(): void {
+    if (present && where !== null) sock?.send(JSON.stringify({ t: "presence", doc: docId, ...where }));
+  }
+
+  function absent(): void {
+    if (!present) return;
+    present = false;
+    host.presence?.(null);
+  }
+
+  function saveConfirmed(): void {
+    if (C === null) return;
+    void cache?.saveConfirmed({ docId, sv, ...C, ...(name === undefined ? {} : { name }) }).catch(noop);
+  }
+
+  /** The server holds another schema version than this editor. */
+  function schemaMismatch(server: number): void {
+    inflight = null;
+    if (server > sv) {
+      // Newer: nothing more is sent or folded. The editor reloads, and the
+      // reloaded tab adopts this queue and migrates it.
+      hold = "upgrade";
+      stopped = true;
+      const s = sock;
+      sock = null;
+      joined = false;
+      absent();
+      s?.close();
+      fail("this Project was upgraded by a newer editor");
+      emit();
+      host.upgrade(server);
+      return;
+    }
+    // Older (a deploy still rolling out): read only, and ask again later.
+    hold = "older-server";
+    const s = sock;
+    sock = null;
+    joined = false;
+    absent();
+    s?.close();
+    fail("this editor is newer than the server");
+    later(1006);
+    emit();
+  }
+
+  function receive(msg: SyncServerMessage): void {
+    // Presence is not the document: no mint, never held behind a snapshot.
+    if (msg.t === "peers" || msg.t === "peer" || msg.t === "peer-left") {
+      if (msg.t === "peers") present = true;
+      host.presence?.(msg);
+      if (msg.t === "peers") sendPresence();
+      return;
+    }
+    // Neither is the document (R10). The socket is by id, so a rename keeps it.
+    if (msg.t === "doc") {
+      name = msg.renamedTo;
+      saveConfirmed();
+      host.renamed?.(msg.renamedTo, msg.by);
+      return;
+    }
+    if (msg.t === "deleted") {
+      goneInfo = { by: msg.by, ...(msg.trashId === undefined ? {} : { trashId: msg.trashId }) };
+      return;
+    }
+    if (held !== null) {
+      held.push(msg);
+      return;
+    }
+    mint();
+    switch (msg.t) {
+      case "welcome": {
+        if (msg.sv !== sv) return schemaMismatch(msg.sv);
+        if (C === null) return resync();
+        for (const e of msg.entries) {
+          if (e.seq <= C.seq) continue;
+          foldEntry(e);
+          popQueue(e.q, e.n);
+        }
+        joinedQueues(msg.acked, msg.queues);
+        rebuild();
+        break;
+      }
+      case "snapshot": {
+        if (msg.sv !== sv) return schemaMismatch(msg.sv);
+        const { t: _t, acked, queues, ...at } = msg;
+        if (at.doc !== undefined) {
+          onSnapshot({ ...at, doc: at.doc }, acked, queues);
+          break;
+        }
+        // Too large to send inline: read it over HTTP, and hold what arrives
+        // meanwhile (a later entry applies on top of it).
+        held = [];
+        o.fetchSnapshot().then(
+          (s) => {
+            const later = held ?? [];
+            held = null;
+            mint();
+            onSnapshot(s, acked, queues);
+            for (const m of later) receive(m);
+            pump();
+            settle();
+            emit();
+          },
+          () => {
+            held = null;
+            resync();
+          },
+        );
+        return;
+      }
+      case "ack":
+      case "entry": {
+        const { t, ...e } = msg;
+        if (C === null) return;
+        const own = mine.has(e.q);
+        if (e.seq <= C.seq) {
+          popQueue(e.q, e.n);
+          break;
+        }
+        if (e.seq !== C.seq + 1) return resync();
+        const sent = inflight;
+        foldEntry(e);
+        if (own) {
+          popQueue(e.q, e.n);
+          // The server applied it as sent: the view already has it.
+          const asSent =
+            t === "ack" &&
+            sent !== null &&
+            sent.q === e.q &&
+            sent.n === e.n &&
+            e.extra === undefined &&
+            e.remap === undefined &&
+            e.ops.length === sent.ops;
+          if (e.remap !== undefined) for (const b of P) if (b.q === e.q) b.ops = remapIds(b.ops, e.remap);
+          if (!asSent) rebuild();
+          break;
+        }
+        // A sibling tab's batch landed: it is in C now, not in S.
+        if (showsSibling(e.q, e.n)) {
+          popQueue(e.q, e.n);
+          rebuild();
+          break;
+        }
+        popQueue(e.q, e.n);
+        const ops = entryOps(e);
+        // Nothing pending touches it, so it lands the same on the view as on
+        // C, under an open drag too (that drag's edit is in P).
+        if (pendingOverlap(ops)) rebuild();
+        else landDirect(ops);
+        break;
+      }
+      case "nack": {
+        const sent = inflight;
+        if (sent === null || msg.q !== sent.q || msg.n !== sent.n) break;
+        inflight = null;
+        const covered = P.filter((b) => b.q === sent.q && b.n <= sent.n);
+        if (msg.code === "unavailable") {
+          retryTimer = setTimeout(() => {
+            retryTimer = null;
+            pump();
+          }, RETRY_MS);
+          break;
+        }
+        if (msg.code === "schema") return schemaMismatch(msg.sv);
+        if (msg.code === "forbidden") {
+          if (sent.q !== q && msg.problems.some((p) => p.at === "q")) {
+            // An adopted queue another user wrote (a shared device): it is
+            // not this user's to send.
+            drop(P.filter((b) => b.q === sent.q));
+            rebuild();
+            break;
+          }
+          drop([...P]);
+          host.forbidden();
+          rebuild();
+          break;
+        }
+        if (covered.length > 1) {
+          // Several batches went as one: send them singly to find the one.
+          solo = { q: sent.q, n: sent.n };
+          break;
+        }
+        drop(covered);
+        const why = msg.problems.map((p) => p.message).join("; ");
+        host.toast(`A change was refused${why === "" ? "" : `: ${why}`}`);
+        rebuild();
+        break;
+      }
+      case "saved": {
+        savedSeq = msg.seq;
+        remember(msg.rev);
+        if (C === null || C.seq !== msg.seq) break;
+        C = { ...C, rev: msg.rev };
+        saveConfirmed();
+        host.saved(msg.rev, P.length === 0 && local === minted);
+        break;
+      }
+      case "error": {
+        if (msg.code === "unavailable") fail(`the Project could not be saved: ${msg.message}`);
+        else if (msg.code === "not-joined" || msg.code === "closed") return resync();
+        else host.toast(`Live sync: ${msg.message}`);
+        break;
+      }
+    }
+    pump();
+    settle();
+    emit();
+  }
+
+  // ── the socket ─────────────────────────────────────────────────────────────
+
+  /** The other queues a join names: adopted, and the open siblings'. */
+  function joinQueues(): string[] {
+    return [...new Set([...mine, ...stale.keys(), ...siblings, ...S.keys()])].filter((qq) => qq !== q).slice(0, MAX_JOIN_QUEUES);
+  }
+
+  function open(): void {
+    if (stopped) return;
+    retryAt = null;
+    const s = connect(docId, {
+      open() {
+        if (sock !== s) return;
+        named = joinQueues();
+        s.send(
+          JSON.stringify({
+            t: "join",
+            doc: docId,
+            q,
+            sv,
+            ...(C === null ? {} : { epoch: C.epoch, seq: C.seq }),
+            ...(named.length > 0 ? { queues: named } : {}),
+          }),
+        );
+      },
+      message(text) {
+        if (sock !== s) return;
+        let msg: SyncServerMessage;
+        try {
+          msg = JSON.parse(text) as SyncServerMessage;
+        } catch {
+          return;
+        }
+        receive(msg);
+      },
+      close(code) {
+        if (sock !== s) return;
+        sock = null;
+        joined = false;
+        absent();
+        inflight = null;
+        fail("the live session disconnected");
+        if (code === 4004) {
+          // What is only in memory joins P first, so it is offered (and
+          // stored) with the rest.
+          mint();
+          stopped = true;
+          emit();
+          const info = goneInfo;
+          goneInfo = null;
+          const ops = P.flatMap((b) => b.ops);
+          host.gone(info, C === null || ops.length === 0 ? null : { base: C.doc, ops });
+          return;
+        }
+        later(code);
+        emit();
+      },
+    });
+    sock = s;
+  }
+
+  /** Reconnect after a backoff with jitter. 4001: access changed or the
+   *  session is stale, so at once, and the server says what this tab may do. */
+  function later(code: number): void {
+    if (stopped) return;
+    const delay = code === 4001 ? 0 : Math.min(30_000, 500 * 2 ** attempts) * (0.5 + Math.random() / 2);
+    attempts++;
+    retryAt = now() + delay;
+    if (reconnectTimer !== null) clearTimeout(reconnectTimer);
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      open();
+    }, delay);
+  }
+
+  // ── the other tabs of this document ────────────────────────────────────────
+
+  /** Show a sibling's batches (deduped by counter, skipping applied ones). */
+  function showSibling(qq: string, batches: readonly SyncStoredBatch[]): Pending[] {
+    const list = S.get(qq) ?? [];
+    const acked = siblingAcked.get(qq) ?? 0;
+    const added: Pending[] = [];
+    for (const b of batches) {
+      if (b.sv !== sv || b.n <= acked || list.some((x) => x.n === b.n)) continue;
+      const p: Pending = { q: qq, n: b.n, base: b.base, ops: b.ops, bytes: 0, ready: true, stored: true };
+      list.push(p);
+      added.push(p);
+    }
+    list.sort((a, b) => a.n - b.n);
+    if (list.length > 0) S.set(qq, list);
+    return added;
+  }
+
+  /**
+   * A queue's lock came free: the tab that held it is gone. Read what it left
+   * and send it as this tab's (adopted), holding the lock until it drains so
+   * no other tab sends it too. Resolves when the lock may go.
+   */
+  async function claim(qq: string): Promise<void> {
+    siblings.delete(qq);
+    S.delete(qq);
+    if (stopped || cache === null) return;
+    const all = await cache.batchesOf(docId).catch((): SyncStoredBatch[] => []);
+    if (stopped) return;
+    const left = all.filter((b) => b.q === qq);
+    const current = left.filter((b) => b.sv === sv).sort((a, b) => a.n - b.n);
+    const old = left.filter((b) => b.sv < sv);
+    if (current.length === 0 && old.length === 0) {
+      // ponytail: a queue a NEWER editor wrote is left where it is, for that
+      // editor; this one cannot read it.
+      if (left.length === 0) await cache.dropQueue(qq).catch(noop);
+      if (trusted) rebuild();
+      emit();
+      return;
+    }
+    mine.add(qq);
+    unconfirmed.add(qq);
+    if (old.length > 0) stale.set(qq, old);
+    if (current.length > 0) {
+      adoptInto(
+        current.map((b) => ({ q: qq, n: b.n, base: b.base, ops: b.ops, bytes: bytesOf(b.ops), ready: true, stored: true })),
+      );
+    }
+    const freed = new Promise<void>((resolve) => holding.set(qq, resolve));
+    // The join names it, so its reply says how far it was acked.
+    if (sock !== null) resync();
+    else if (trusted) rebuild();
+    emit();
+    return freed;
+  }
+
+  /** Follow another queue of this document: adopt it once its tab is gone. */
+  function watch(qq: string, live: boolean): Promise<void> {
+    if (qq === q || mine.has(qq) || watching.has(qq) || locks === null || stopped) return Promise.resolve();
+    const ac = new AbortController();
+    watching.set(qq, ac);
+    const done = (): void => void watching.delete(qq);
+    if (live) {
+      // A tab that just said hello: alive, whatever the lock says this instant.
+      siblings.add(qq);
+      void locks
+        .request(syncLockName(qq), { signal: ac.signal }, () => claim(qq))
+        .catch(noop)
+        .finally(done);
+      return Promise.resolve();
+    }
+    return new Promise<void>((decided) => {
+      locks
+        .request(syncLockName(qq), { ifAvailable: true }, (lock) => {
+          if (lock !== null) {
+            decided();
+            return claim(qq).finally(done);
+          }
+          siblings.add(qq);
+          decided();
+          void locks
+            .request(syncLockName(qq), { signal: ac.signal }, () => claim(qq))
+            .catch(noop)
+            .finally(done);
+        })
+        .catch(() => {
+          done();
+          decided();
+        });
+    });
+  }
+
+  function onChannel(event: MessageEvent): void {
+    const m = event.data as ChannelMessage | null;
+    if (stopped || typeof m !== "object" || m === null || typeof m.q !== "string" || m.q === q || mine.has(m.q)) return;
+    if (m.t === "hello") post({ t: "here", q });
+    if (!watching.has(m.q)) void watch(m.q, true);
+    if (m.t === "batch") {
+      const added = showSibling(m.q, [{ q: m.q, n: m.n, docId, base: m.base, sv, ops: m.ops }]);
+      if (added.length > 0 && trusted && C !== null) {
+        mint();
+        const r = renameCollisions(minted, m.ops);
+        // Nothing of ours replays after it: it lands as is.
+        if (r.renames.length === 0 && !P.some((b) => opsOverlap(b.ops, m.ops))) landDirect(m.ops);
+        else rebuild();
+      }
+    } else if (m.t === "drop") {
+      const list = S.get(m.q);
+      if (list !== undefined && list.some((b) => b.n === m.n)) {
+        const rest = list.filter((b) => b.n !== m.n);
+        if (rest.length > 0) S.set(m.q, rest);
+        else S.delete(m.q);
+        rebuild();
+      }
+    }
+    emit();
+  }
+
+  // ── boot ───────────────────────────────────────────────────────────────────
+
+  async function boot(): Promise<void> {
+    if (locks !== null) {
+      void locks.request(syncLockName(q), {}, () => new Promise<void>((resolve) => (releaseOwn = resolve))).catch(noop);
+    }
+    channel?.addEventListener("message", onChannel);
+    post({ t: "hello", q });
+    const none: [null, SyncStoredBatch[], string[]] = [null, [], []];
+    const [c, stored, queues] =
+      cache === null
+        ? none
+        : await Promise.all([cache.confirmed(docId), locks === null ? [] : cache.batchesOf(docId), locks === null ? [] : cache.queuesOf(docId)]).catch(
+            () => none,
+          );
+    if (stopped) return;
+    // The confirmed copy from an earlier visit lets the join ask only for what
+    // it missed; the editor's document is replaced by the view on the reply.
+    if (c !== null && c.sv === sv && C === null) C = { doc: c.doc, seq: c.seq, epoch: c.epoch, rev: c.rev };
+    else if (c !== null && c.sv < sv) oldBase = c.doc;
+    const byQueue = new Map<string, SyncStoredBatch[]>(queues.map((qq) => [qq, []]));
+    for (const b of stored) byQueue.set(b.q, [...(byQueue.get(b.q) ?? []), b]);
+    byQueue.delete(q);
+    await Promise.all([...byQueue.keys()].map((qq) => watch(qq, false)));
+    if (stopped) return;
+    // What the siblings hold right now. Each new batch arrives on the channel.
+    for (const qq of siblings) showSibling(qq, byQueue.get(qq) ?? []);
+    if (o.offline === true && C !== null) {
+      trusted = true;
+      rebuild();
+    }
+    emit();
+    open();
+  }
+  void boot();
+
+  const client: SyncClient = {
+    localChange(doc, scrubbing) {
+      local = doc;
+      if (!scrubbing) mint();
+      else scrubTimer ??= setTimeout(() => {
+        mint();
+        emit();
+      }, SCRUB_MS);
+      emit();
+    },
+    async flush() {
+      mint();
+      emit();
+      if (hold === "upgrade") throw new Error("this Project was upgraded by a newer editor: reload to keep editing");
+      if (hold === "older-server") throw new Error("this editor is newer than the server: editing waits until the server catches up");
+      if (retryAt !== null || stopped) throw new Error("the live session is not connected");
+      await wait(() => joined && P.length === 0);
+      const want = C!.seq;
+      if (savedSeq < want) sock?.send(JSON.stringify({ t: "flush" }));
+      await wait(() => savedSeq >= want);
+    },
+    reach(rev) {
+      return wait(() => revs.includes(rev));
+    },
+    touched(layerId) {
+      const t = touchedAt.get(layerId);
+      return t !== undefined && now() - t < TOUCH_MS;
+    },
+    presence(p) {
+      where = p;
+      sendPresence();
+    },
+    retryNow() {
+      if (stopped || reconnectTimer === null) return;
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+      open();
+      emit();
+    },
+    async retryStorage(prune) {
+      if (cache === null) return true;
+      if (prune) await cache.prune(docId).catch(noop);
+      const loose = P.filter((b) => !b.stored);
+      const full = (): boolean => hold === "quota";
+      if (full()) hold = null;
+      for (const b of loose) {
+        await store(b);
+        if (full()) break;
+      }
+      pump();
+      emit();
+      return !full();
+    },
+    revive() {
+      if (!stopped || closed || hold === "upgrade") return;
+      stopped = false;
+      attempts = 0;
+      open();
+      emit();
+    },
+    close() {
+      stopped = true;
+      closed = true;
+      for (const t of [scrubTimer, retryTimer, reconnectTimer]) if (t !== null) clearTimeout(t);
+      fail("the Project was closed");
+      for (const ac of watching.values()) ac.abort();
+      watching.clear();
+      // Undrained adopted queues go back to IndexedDB's care: the next tab
+      // of this document adopts them.
+      for (const free of holding.values()) free();
+      holding.clear();
+      releaseOwn();
+      try {
+        channel?.close();
+      } catch {
+        // already closed
+      }
+      const s = sock;
+      sock = null;
+      s?.close();
+    },
+    discard() {
+      const queues = new Set([q, ...P.map((b) => b.q)]);
+      P.length = 0;
+      client.close();
+      for (const qq of queues) void cache?.dropQueue(qq).catch(noop);
+    },
+  };
+  return client;
+}
+
+/** The browser's socket: same origin, `/api/sync`. */
+export const browserSyncConnect: SyncConnect = (docId, on) => {
+  const scheme = location.protocol === "https:" ? "wss" : "ws";
+  const ws = new WebSocket(`${scheme}://${location.host}/api/sync?doc=${encodeURIComponent(docId)}`);
+  ws.onopen = () => on.open();
+  ws.onmessage = (e) => on.message(typeof e.data === "string" ? e.data : "");
+  ws.onclose = (e) => on.close(e.code);
+  return { send: (text) => ws.send(text), close: () => ws.close() };
+};