@inkandswitch/patchwork-bootloader 0.4.3 → 0.4.4

package/src/setup.ts

@@ -17,139 +17,193 @@ import {
 const serviceWorkerDebugging = debug.enabled("patchwork:serviceworker");
 const workerDebugging = debug.enabled("patchwork:automergeworker");
 
-// Diagnostic [lifecycle] logging, on by default. Disable via
-// localStorage["patchwork:lifecycle-logs"] = "off". Read live at log time.
-const LIFECYCLE_LOG_KEY = "patchwork:lifecycle-logs";
-export function lifecycleLoggingEnabled(): boolean {
-  try {
-    const v = globalThis.localStorage?.getItem(LIFECYCLE_LOG_KEY);
-    return v !== "off" && v !== "false" && v !== "0" && v !== "no";
-  } catch {
-    return true;
-  }
-}
-
-// The SW can't read localStorage, so it always emits [lifecycle] markers and
-// forwards them as `sw-lifecycle`; gate rendering here on the live toggle.
-let swLifecycleListenerInstalled = false;
-function installServiceWorkerLogForwarding(): void {
-  if (swLifecycleListenerInstalled) return;
-  if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
-  swLifecycleListenerInstalled = true;
-  navigator.serviceWorker.addEventListener("message", (event: MessageEvent) => {
-    const data = event.data;
-    if (data?.type !== "sw-lifecycle") return;
-    if (!lifecycleLoggingEnabled()) return;
-    const fn = (console as any)[data.level] ?? console.log;
-    fn(`[service-worker] ${data.msg}`);
-  });
+export const lifecycleLog = debug("patchwork:lifecycle");
+
+function describeErrorEvent(event: Event): string {
+  const error = event as ErrorEvent;
+  const where = error.filename
+    ? ` (${error.filename}:${error.lineno}:${error.colno})`
+    : "";
+  return `${error.message || String(event)}${where}`;
 }
 
-const key = "patchworkServiceWorkerCacheVersion";
-const defaultServiceWorkerCacheName = "patchwork";
-let nextRepoChannelId = 0;
-
-function bumpServiceWorkerCacheVersion() {
-  const version = new Date().valueOf().toString(36);
-  localStorage.setItem(key, version);
-  return getServiceWorkerCacheVersion();
-}
+// The version is cleared on every boot, so the steady state is
+// DEFAULT_CACHE_NAME. bumpServiceWorkerCache is a dev escape hatch: it moves
+// the worker to a throwaway cache now, and the next boot both reverts the name
+// and (via the worker's activate handler) deletes the throwaway.
+const CACHE_VERSION_KEY = "patchworkServiceWorkerCacheVersion";
+const DEFAULT_CACHE_NAME = "patchwork";
 
-function getServiceWorkerCacheVersion() {
-  return localStorage.getItem(key);
+function currentCacheName(): string {
+  return localStorage.getItem(CACHE_VERSION_KEY) ?? DEFAULT_CACHE_NAME;
 }
 
-function setServiceWorkerCacheName(sw: ServiceWorker | null) {
-  if (!sw) {
-    throw new Error("no service worker!");
-  }
-  sw.postMessage({
-    type: "cachename",
-    cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
-  });
+function configureServiceWorker(sw: ServiceWorker | null) {
+  if (!sw) return;
+  sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
+  sw.postMessage({ type: "cachename", cachename: currentCacheName() });
 }
 
 export function bumpServiceWorkerCache(
-  sw = navigator.serviceWorker.controller
+  sw: ServiceWorker | null = navigator.serviceWorker.controller
 ) {
-  bumpServiceWorkerCacheVersion();
-  setServiceWorkerCacheName(sw);
+  if (!sw) throw new Error("no service worker!");
+  localStorage.setItem(CACHE_VERSION_KEY, Date.now().toString(36));
+  sw.postMessage({ type: "cachename", cachename: currentCacheName() });
 }
 
-(window as any).bumpServiceWorkerCache = bumpServiceWorkerCache;
-
-function configureServiceWorker(sw: ServiceWorker | null) {
-  if (!sw) return;
-  sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
-  sw.postMessage({
-    type: "cachename",
-    cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
+// The service worker has no localStorage, so it can't read the debug config —
+// it always emits lifecycle markers and forwards them here to be filtered.
+let logForwardingInstalled = false;
+function installServiceWorkerLogForwarding(): void {
+  if (logForwardingInstalled) return;
+  if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
+  logForwardingInstalled = true;
+  navigator.serviceWorker.addEventListener("message", (event: MessageEvent) => {
+    if (event.data?.type !== "sw-lifecycle") return;
+    lifecycleLog("[service-worker] %s", event.data.msg);
   });
 }
 
-// ── The automerge worker ───────────────────────────────────────────────
-// The automerge repo lives in a SharedWorker (not the service worker). One
-// instance is shared by every tab and normally lives as long as any tab
-// does — but browsers do reap SharedWorkers under memory pressure, so we
-// heartbeat it and rebuild everything if it dies (see
-// recoverAutomergeWorker). Repo sync ports are passed to it over its
-// connect port; it talks to the service worker over a BroadcastChannel.
+// The automerge repo lives in a SharedWorker. one instance serves every
+// tab. Browsers might kill a SharedWorker under memory pressure, so we
+// heartbeat it and rebuild everything if it dies.
 
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker: SharedWorker | undefined;
-// Bumped whenever a new SharedWorker is constructed. A repo port opened
-// against instance N is stale once instance N+1 exists (its channel ends in
-// a dead worker), so deliveries are guarded on the generation they started in.
+// A repo port opened against instance N is stale once instance N+1 exists — its
+// channel ends in a dead worker — so deliveries are guarded on generation.
 let workerGeneration = 0;
-// Tears down the current worker's heartbeat when it's replaced.
 let disposeWorkerDeathDetection: (() => void) | undefined;
-// Every subscribeToRepoChannel listener, kept so a recovered worker can hand
-// each subscriber a fresh repo port.
 const repoChannelListeners = new Set<ServiceWorkerRepoChannelListener>();
 let recoveringWorker = false;
 let lastWorkerRecoveryAt = 0;
-// Below this spacing, skip: if the fresh worker is dead too, its own
-// heartbeat re-triggers recovery later rather than spinning in a tight loop.
+// Below this spacing, skip: if the fresh worker is dead too, its own heartbeat
+// re-triggers recovery later rather than spinning in a tight loop.
 const RECOVERY_MIN_INTERVAL_MS = 15_000;
+let nextRepoChannelId = 0;
+
+// Chrome can't spawn workers inside a SharedWorker, so each tab offers this
+// proxy's port to the automerge worker, which requests one via its port
+// provider. Being a SharedWorker itself, the proxy — and the donated
+// worker↔worker port — outlives the donor tab.
+const SUBDUCTION_IO_WORKER_URL =
+  "/packages/@automerge/automerge-repo/subduction-websocket-worker-shared.js";
+
+export function getAutomergeWorker(): SharedWorker {
+  if (automergeWorker) return automergeWorker;
+
+  workerGeneration++;
+  const worker = new SharedWorker(automergeWorkerPath, {
+    name: "patchwork-automerge",
+    type: "module",
+  });
+  automergeWorker = worker;
+
+  // Fires when a message can't be structured-deserialized. Silent otherwise:
+  // the message is dropped, which looks identical to a worker that never
+  // replied.
+  worker.port.addEventListener("messageerror", (event) => {
+    console.error(
+      "[automerge-worker] undeserializable message from worker:",
+      event
+    );
+  });
+  // Control replies come back on this port, and we listen with
+  // addEventListener rather than onmessage, so it needs start().
+  worker.port.start();
+  worker.port.addEventListener("message", handleWorkerMessage);
+  worker.port.postMessage({ type: "debug", debug: workerDebugging });
+
+  donatePort(worker.port, createSubductionIoPort);
+  disposeWorkerDeathDetection = installWorkerDeathDetection(worker);
+  return worker;
+}
+
+function handleWorkerMessage(event: MessageEvent): void {
+  const data = event.data;
+
+  if (data?.type === "sync-state") {
+    dispatchSyncState(data as SyncStateDocMessage);
+    return;
+  }
+
+  // Crash/skew reports relayed from the subduction io proxy (e.g. a protocol
+  // mismatch from a stale SW-cached worker chunk). These otherwise only exist
+  // in chrome://inspect.
+  if (isWorkerErrorMessage(data)) {
+    console.error("[subduction-io]", data);
+    return;
+  }
+
+  if (data?.type !== "console") return;
+  const { level, args } = data;
+  if (
+    !lifecycleLog.enabled &&
+    typeof args?.[0] === "string" &&
+    args[0].includes("[lifecycle]")
+  ) {
+    return;
+  }
+  const write = (console as any)[level] ?? console.log;
+  // The worker's logs carry %c directives in args[0] with CSS in the following
+  // args, so the tag has to go inside the format string or the CSS prints raw.
+  if (typeof args[0] === "string") {
+    write(`[automerge-worker] ${args[0]}`, ...args.slice(1));
+  } else {
+    write("[automerge-worker]", ...args);
+  }
+}
+
+function createSubductionIoPort(): MessagePort {
+  const io = new SharedWorker(SUBDUCTION_IO_WORKER_URL, {
+    type: "module",
+    name: "subduction-websocket",
+  });
+  // This worker carries the websocket to the sync server, so a load failure
+  // stops sync with no other symptom.
+  io.addEventListener("error", (event) => {
+    console.error(
+      `[subduction-io] failed to load/run ${SUBDUCTION_IO_WORKER_URL}:`,
+      describeErrorEvent(event)
+    );
+  });
+  io.port.addEventListener("messageerror", (event) => {
+    console.error("[subduction-io] undeserializable message:", event);
+  });
+  return io.port;
+}
 
 /**
- * The automerge SharedWorker died (browser reaped it, or it crashed): build a
- * replacement and re-wire everything a live tab holds against it — console
- * forwarding and the io-proxy port donation (both re-done by
+ * Build a replacement worker and re-wire everything a live tab holds against
+ * it: console forwarding and port donation (both re-done by
  * getAutomergeWorker), the per-doc sync-state subscriptions, and every
- * subscriber's repo sync port. The new instance boots with cold state; its
- * repo is reconstructed on the first port we send.
+ * subscriber's repo port. The new instance boots with cold state.
  */
 async function recoverAutomergeWorker(
   reason: string,
   deadWorker: SharedWorker
 ): Promise<void> {
-  if (deadWorker !== automergeWorker) return; // already replaced
+  if (deadWorker !== automergeWorker) return;
   if (recoveringWorker) return;
   const now = Date.now();
   if (now - lastWorkerRecoveryAt < RECOVERY_MIN_INTERVAL_MS) return;
   recoveringWorker = true;
   lastWorkerRecoveryAt = now;
-  console.warn(
-    `[lifecycle] ${new Date().toISOString()} recreating the automerge ` +
-      `SharedWorker (${reason})`
-  );
+  lifecycleLog("recreating the automerge SharedWorker (%s)", reason);
+
   try {
     disposeWorkerDeathDetection?.();
     disposeWorkerDeathDetection = undefined;
     automergeWorker = undefined;
     try {
       deadWorker.port.close();
-    } catch {
-      // Port already dead.
-    }
+    } catch {}
+
     const fresh = getAutomergeWorker();
-    // The fresh instance knows nothing — replay every doc subscription.
     for (const documentId of syncStateListeners.keys()) {
       fresh.port.postMessage({ type: "sync-sub", documentId });
     }
-    // Hand every repo-channel subscriber a fresh port so their repos sync
-    // again (the old adapters sit on dead MessagePorts).
     for (const listener of repoChannelListeners) {
       try {
         const generation = workerGeneration;
@@ -169,225 +223,83 @@ async function recoverAutomergeWorker(
   }
 }
 
-// SharedWorker proxy entry that owns the subduction WebSocket. Chrome can't
-// spawn workers from inside a SharedWorker, so each tab offers this proxy's
-// port to the automerge worker (which requests one via its port provider).
-// Being a SharedWorker itself, the proxy — and the donated worker↔worker
-// port — outlives the donor tab. Emitted at /packages/... via externals.ts.
-const SUBDUCTION_IO_WORKER_URL =
-  "/packages/@automerge/automerge-repo/subduction-websocket-worker-shared.js";
-
-// Bench toggles for the subduction socket (see getSubductionEndpoints in
-// automerge-worker.ts), passed as query params because SharedWorker scope
-// has no localStorage — which also gives each configuration its own worker
-// instance, so bench arms can't share state.
-//   localStorage["patchwork:ws-mode"] = "inline"  → socket on worker thread
-//   localStorage["patchwork:ws-window"] = "16"    → WorkerWebSocketEndpoint
-//                                                    windowFrames override
-function workerBenchParams(): string {
-  const params = new URLSearchParams();
-  try {
-    for (const [key, param] of [
-      ["patchwork:ws-mode", "ws-mode"],
-      ["patchwork:ws-window", "ws-window"],
-    ] as const) {
-      const value = globalThis.localStorage?.getItem(key);
-      if (value) params.set(param, value);
-    }
-  } catch {
-    // No localStorage (shouldn't happen in a tab) — use defaults.
-  }
-  const qs = params.toString();
-  return qs ? `?${qs}` : "";
-}
-
-function automergeWorkerUrl(): string {
-  return `${automergeWorkerPath}${workerBenchParams()}`;
-}
+// A silent port is not proof of death: the worker may still be evaluating its
+// module graph, or be busy with wasm/sync work. In both cases every queued
+// message — including the repo ports the network adapters ride on — is
+// delivered once it catches up, and tearing the port down would lose them. So
+// silence only starts a non-destructive probe: a second connection to the same
+// instance. Only if the probe gets a `hello` while this port stays silent do we
+// know the instance is alive but our port is stranded, and recover.
+const HEARTBEAT_MS = 5_000;
+const HEARTBEAT_TIMEOUT_MS = 25_000;
+// An idle worker hellos within milliseconds of connecting, so before first
+// contact the budget is tighter — probing early rescues stranded boots fast.
+const FIRST_CONTACT_TIMEOUT_MS = 4_000;
+// After a slow boot both connections hello at roughly the same moment and
+// cross-port delivery order isn't guaranteed, so give the suspect this long to
+// also speak before concluding it's stranded.
+const PROBE_GRACE_MS = 500;
 
-export function getAutomergeWorker(): SharedWorker {
-  if (!automergeWorker) {
-    workerGeneration++;
-    automergeWorker = new SharedWorker(automergeWorkerUrl(), {
-      name: "patchwork-automerge",
-      type: "module",
-    });
-    // Fired when a message arrives that can't be structured-deserialized —
-    // e.g. a transfer list that named something unclonable. Silent otherwise:
-    // the message is simply dropped, which looks identical to a worker that
-    // never replied. Always loud, not gated on the lifecycle toggle.
-    automergeWorker.port.addEventListener("messageerror", (event) => {
-      console.error(
-        "[automerge-worker] undeserializable message from worker:",
-        event
-      );
-    });
-    // Control replies (port-ready &c) come back on this port, so it needs
-    // start() — we listen with addEventListener, not onmessage.
-    automergeWorker.port.start();
-    // Surface the SharedWorker's console output and uncaught errors in this
-    // tab's console (it has its own console that's awkward to find otherwise).
-    automergeWorker.port.addEventListener("message", (event: MessageEvent) => {
-      if (event.data?.type === "sync-state") {
-        dispatchSyncState(event.data as SyncStateDocMessage);
-        return;
-      }
-      if (isWorkerErrorMessage(event.data)) {
-        // Crash/skew reports relayed from the subduction io proxy (e.g.
-        // protocol-mismatch from a stale SW-cached worker chunk). Surface
-        // loudly — these otherwise only exist in chrome://inspect.
-        console.error("[subduction-io]", event.data);
-        return;
-      }
-      if (event.data?.type === "drift-samples") {
-        // Keepalive-drift samples from the worker's bench probe. Kept on a
-        // bounded window global for the Playwright bench to harvest.
-        const sink = ((window as any).__driftSamples ??= []) as number[];
-        sink.push(...event.data.samples);
-        if (sink.length > 10_000) sink.splice(0, sink.length - 10_000);
-        return;
-      }
-      if (event.data?.type !== "console") return;
-      const { level, args } = event.data;
-      // Gate forwarded [lifecycle] logs on the toggle too.
-      if (
-        !lifecycleLoggingEnabled() &&
-        typeof args?.[0] === "string" &&
-        args[0].includes("[lifecycle]")
-      ) {
-        return;
-      }
-      const fn = (console as any)[level] ?? console.log;
-      // The worker's logs (debug library, the worker's own log()) carry %c
-      // format directives in args[0] with CSS in the following args. Prefix
-      // the tag into the format string rather than as a separate positional,
-      // or the %c would no longer be in arg 0 and the CSS would print raw.
-      if (typeof args[0] === "string") {
-        fn(`[automerge-worker] ${args[0]}`, ...args.slice(1));
-      } else {
-        fn("[automerge-worker]", ...args);
-      }
-    });
-    automergeWorker.port.postMessage({ type: "debug", debug: workerDebugging });
-
-    // Offer the subduction io proxy's port; the worker's port provider pulls
-    // it when (re)constructing its WorkerWebSocketEndpoint.
-    donatePort(automergeWorker.port, () => {
-      const io = new SharedWorker(SUBDUCTION_IO_WORKER_URL, {
-        type: "module",
-        name: "subduction-websocket",
-      });
-      // This worker carries the websocket to the sync server, so if it fails
-      // to load, sync silently stops with no other symptom.
-      io.addEventListener("error", (event) => {
-        const error = event as ErrorEvent;
-        console.error(
-          `[subduction-io] failed to load/run ${SUBDUCTION_IO_WORKER_URL}:`,
-          error.message || event,
-          error.filename ? `(${error.filename}:${error.lineno})` : ""
-        );
-      });
-      io.port.addEventListener("messageerror", (event) => {
-        console.error("[subduction-io] undeserializable message:", event);
-      });
-      return io.port;
-    });
-
-    disposeWorkerDeathDetection = installWorkerDeathDetection(automergeWorker);
-  }
-  return automergeWorker;
-}
-
-/**
- * Detect when the automerge SharedWorker dies or its control port goes deaf.
- *
- * Silence alone is NOT proof of death: the worker may still be evaluating its
- * (large) module graph on a cold boot, or its single thread may be busy with
- * wasm/sync work — in both cases every queued message (including the repo
- * ports the network adapters ride on) is delivered fine once it catches up,
- * and tearing the port down would *lose* them. So silence only starts a
- * non-destructive PROBE: a second SharedWorker connection to the same
- * instance. Only when the probe gets a `hello` while this port stays silent do
- * we know the instance is alive-and-responsive but our port is stranded (a
- * failure mode observed in the wild) — or was replaced — and recovery is
- * warranted. A `close` event (where supported) is a definitive death signal
- * and recovers immediately. [lifecycle]-tagged. Returns a dispose that stops
- * the heartbeat and any outstanding probe (called when this worker is
- * replaced).
- */
 function installWorkerDeathDetection(worker: SharedWorker): () => void {
-  const stamp = () => new Date().toISOString();
-  const warn = (msg: string) => {
-    if (lifecycleLoggingEnabled()) console.warn(`[lifecycle] ${stamp()} ${msg}`);
-  };
-  const info = (msg: string) => {
-    if (lifecycleLoggingEnabled()) console.info(`[lifecycle] ${stamp()} ${msg}`);
-  };
-
   let instanceId: string | undefined;
   let lastHeardAt = Date.now();
   let warnedUnresponsive = false;
+  let warnedSendFailed = false;
   let disposed = false;
   let probe: SharedWorker | undefined;
+  let seq = 0;
 
   const closeProbe = () => {
     if (!probe) return;
     try {
       probe.port.close();
-    } catch {
-      // Already closed.
-    }
+    } catch {}
     probe = undefined;
   };
-  let warnedSendFailed = false;
-  let pingsSent = 0;
 
   worker.port.addEventListener("message", (event: MessageEvent) => {
     const data = event.data;
     if (data?.type !== "hello" && data?.type !== "pong") return;
     lastHeardAt = Date.now();
     warnedUnresponsive = false;
-    // The port spoke — any outstanding probe is moot.
     closeProbe();
     if (instanceId === undefined) {
       instanceId = data.instanceId;
-      info(`automerge SharedWorker instance ${data.instanceId} (via ${data.type})`);
+      lifecycleLog(
+        "automerge SharedWorker instance %s (via %s)",
+        data.instanceId,
+        data.type
+      );
     } else if (data.instanceId && data.instanceId !== instanceId) {
-      warn(
-        `automerge SharedWorker instance changed (instance ${data.instanceId}, ` +
-          `was ${instanceId})`
+      lifecycleLog(
+        "automerge SharedWorker instance changed (instance %s, was %s)",
+        data.instanceId,
+        instanceId
       );
       instanceId = data.instanceId;
     }
   });
 
-  // Fires when the SharedWorker is destroyed (where supported).
   worker.port.addEventListener("close", () => {
     if (disposed) return;
-    warn("automerge SharedWorker control port closed");
+    lifecycleLog("automerge SharedWorker control port closed");
     void recoverAutomergeWorker("control port closed", worker);
   });
 
-  // Not gated on the lifecycle toggle: a worker that fails to load never
-  // replies to anything, and this is the only signal that says so.
-  worker.addEventListener("error", event => {
-    const error = event as ErrorEvent;
-    console.error(
-      `[lifecycle] ${stamp()} automerge SharedWorker error:`,
-      error.message || event,
-      error.filename ? `(${error.filename}:${error.lineno})` : ""
-    );
+  // Not gated on the debug namespace: a worker that fails to load never replies
+  // to anything, and this is the only signal that says so.
+  worker.addEventListener("error", (event) => {
+    console.error("automerge SharedWorker error:", describeErrorEvent(event));
   });
 
-  // On probe hello, give the suspect port this long to also speak before
-  // concluding it's stranded: after a slow worker boot both connections hello
-  // at roughly the same moment and cross-port delivery order isn't guaranteed.
-  const PROBE_GRACE_MS = 500;
   const startProbe = (reason: string) => {
     if (probe || disposed) return;
-    warn(`automerge SharedWorker ${reason}; probing with a second connection`);
+    lifecycleLog(
+      "automerge SharedWorker %s; probing with a second connection",
+      reason
+    );
     const startedAt = Date.now();
-    const p = new SharedWorker(automergeWorkerUrl(), {
+    const p = new SharedWorker(automergeWorkerPath, {
       name: "patchwork-automerge",
       type: "module",
     });
@@ -396,10 +308,10 @@ function installWorkerDeathDetection(worker: SharedWorker): () => void {
     p.port.addEventListener("message", (event: MessageEvent) => {
       if (event.data?.type !== "hello") return;
       setTimeout(() => {
-        if (disposed || probe !== p) return; // superseded or torn down
+        if (disposed || probe !== p) return;
         closeProbe();
-        // The suspect spoke while (or just after) the probe ran: it was
-        // merely slow/busy, and everything queued on it has been delivered.
+        // The suspect spoke while the probe ran: it was merely busy, and
+        // everything queued on it has been delivered.
         if (lastHeardAt >= startedAt) return;
         void recoverAutomergeWorker(
           `port unresponsive on a live worker (${reason}; probe confirmed)`,
@@ -407,56 +319,45 @@ function installWorkerDeathDetection(worker: SharedWorker): () => void {
         );
       }, PROBE_GRACE_MS);
     });
-    // No hello on the probe means the instance is loading or busy (the probe
-    // waits indefinitely — its hello triggers the check above whenever it
-    // lands) — never tear anything down on a timer.
+    // No hello on the probe means the instance is loading or busy. The probe
+    // waits indefinitely rather than tearing anything down on a timer.
   };
 
-  // A silent-too-long port while the tab is visible starts a probe (a miss
-  // while hidden is more likely suspension). Before first contact the budget
-  // is tighter: an idle worker hellos within milliseconds of connecting, so
-  // probing early costs nothing and rescues genuinely stranded boots fast.
-  const HEARTBEAT_MS = 5_000;
-  const HEARTBEAT_TIMEOUT_MS = 25_000;
-  const FIRST_CONTACT_TIMEOUT_MS = 4_000;
-  let seq = 0;
   const heartbeat = setInterval(() => {
     try {
       worker.port.postMessage({ type: "ping", id: ++seq });
-      pingsSent++;
     } catch (error) {
-      // Swallowing this makes a failed send indistinguishable from a dead
-      // worker in the "no pong" warning below. Once, not every heartbeat.
+      // Without this a failed send is indistinguishable from a dead worker.
       if (!warnedSendFailed) {
         warnedSendFailed = true;
-        console.error(
-          `[lifecycle] ${stamp()} automerge SharedWorker ping send threw ` +
-            `after ${pingsSent} sent:`,
-          error
-        );
+        console.error("automerge SharedWorker ping send threw", error);
       }
     }
+
     const neverHeard = instanceId === undefined;
     const silentMs = Date.now() - lastHeardAt;
     const timeoutMs = neverHeard
       ? FIRST_CONTACT_TIMEOUT_MS
       : HEARTBEAT_TIMEOUT_MS;
+    if (silentMs <= timeoutMs) return;
+
+    // First contact probes regardless of visibility: SharedWorkers don't
+    // suspend with the tab, and the probe destroys nothing. Post-contact
+    // silence defers to visibility, since a hidden page's throttling can fake
+    // it.
     const visible =
       typeof document === "undefined" || document.visibilityState === "visible";
-    // First contact probes regardless of visibility: SharedWorkers don't
-    // suspend with tab visibility, boots in background tabs must still get
-    // rescued, and the probe destroys nothing. Post-contact silence defers to
-    // visibility, since a hidden page's own throttling can fake it.
-    if (silentMs > timeoutMs && (neverHeard || visible)) {
-      const reason = neverHeard
-        ? `no hello ~${Math.round(silentMs / 1000)}s after connecting`
-        : `no pong for ~${Math.round(silentMs / 1000)}s`;
-      if (!warnedUnresponsive) {
-        warnedUnresponsive = true;
-        warn(`automerge SharedWorker ${reason} (tab visible)`);
-      }
-      startProbe(reason);
-     }
+    if (!neverHeard && !visible) return;
+
+    const seconds = Math.round(silentMs / 1000);
+    const reason = neverHeard
+      ? `no hello ~${seconds}s after connecting`
+      : `no pong for ~${seconds}s`;
+    if (!warnedUnresponsive) {
+      warnedUnresponsive = true;
+      lifecycleLog("automerge SharedWorker %s (tab visible)", reason);
+    }
+    startProbe(reason);
   }, HEARTBEAT_MS);
 
   return () => {
@@ -466,18 +367,13 @@ function installWorkerDeathDetection(worker: SharedWorker): () => void {
   };
 }
 
-// ── Sync-state subscriptions ────────────────────────────────────────────
-// The automerge worker pushes per-document heads only to the tabs that ask for
-// them (see SyncStateDocMessage). We ref-count locally so several callers in
-// this tab can watch the same doc with a single worker subscription, and tear
-// the worker subscription down when the last local watcher drops.
+// Ref-counted locally so several callers in this tab can watch the same doc
+// with a single worker subscription.
 type SyncStateListener = (update: SyncStateDocMessage) => void;
 const syncStateListeners = new Map<string, Set<SyncStateListener>>();
 
 function dispatchSyncState(update: SyncStateDocMessage): void {
-  const listeners = syncStateListeners.get(update.documentId);
-  if (!listeners) return;
-  for (const listener of listeners) {
+  for (const listener of syncStateListeners.get(update.documentId) ?? []) {
     try {
       listener(update);
     } catch (err) {
@@ -494,25 +390,22 @@ export function subscribeSyncState(
   let listeners = syncStateListeners.get(documentId);
   if (!listeners) {
     syncStateListeners.set(documentId, (listeners = new Set()));
-    // First local watcher for this doc — ask the worker to start pushing it.
     worker.port.postMessage({ type: "sync-sub", documentId });
   }
   listeners.add(listener);
 
   let active = true;
   return () => {
-    if (!active) return; // idempotent
+    if (!active) return;
     active = false;
     const set = syncStateListeners.get(documentId);
     if (!set) return;
     set.delete(listener);
-    if (set.size === 0) {
-      syncStateListeners.delete(documentId);
-      // The worker may have been replaced since we subscribed (recovery
-      // replays subscriptions onto the new instance) — unsubscribe from
-      // whichever instance is current, not the one captured above.
-      automergeWorker?.port.postMessage({ type: "sync-unsub", documentId });
-    }
+    if (set.size > 0) return;
+    syncStateListeners.delete(documentId);
+    // Unsubscribe from whichever instance is current: recovery replays
+    // subscriptions onto a new worker, so it may not be the one captured above.
+    automergeWorker?.port.postMessage({ type: "sync-unsub", documentId });
   };
 }
 
@@ -536,11 +429,9 @@ export function connectClassicSync(
     port1.onmessage = (event) => {
       clearTimeout(timeout);
       port1.close();
-      if (event.data?.type === "connect-classic-sync-ready") {
-        resolve();
-      } else {
+      if (event.data?.type === "connect-classic-sync-ready") resolve();
+      else
         reject(new Error(event.data?.error ?? "connect-classic-sync failed"));
-      }
     };
     worker.port.postMessage({ type: "connect-classic-sync", server: url }, [
       port2,
@@ -548,110 +439,113 @@ export function connectClassicSync(
   });
 }
 
-/** Wait for a registration to have an active worker */
-function waitForActive(reg: ServiceWorkerRegistration): Promise<ServiceWorker> {
-  if (reg.active) return Promise.resolve(reg.active);
-  const worker = reg.installing || reg.waiting;
-  if (!worker)
-    return Promise.reject(new Error("no service worker in registration"));
-  return new Promise((resolve) => {
-    worker.addEventListener("statechange", () => {
-      if (worker.state === "activated") resolve(worker);
-    });
-  });
+function sendRepoPort(id: number): MessagePort {
+  const { port1, port2 } = new MessageChannel();
+  getAutomergeWorker().port.postMessage({ type: "port", id }, [port2]);
+  return port1;
 }
 
-async function openRepoChannel(): Promise<MessagePort> {
-  const worker = getAutomergeWorker();
-
-  // Send a MessagePort so the worker's repo can sync with this tab, and wait
-  // for the worker to confirm its repo is constructed before returning. The
-  // MessageChannel adapter's whenReady() force-resolves after 100ms regardless
-  // of the other end's state, so it can't be used as a real readiness signal
-  // on first boot (when the worker still has to fetch wasm and build its repo).
-  const id = ++nextRepoChannelId;
-  const { port1, port2 } = new MessageChannel();
-  const workerReady = new Promise<void>((resolve, reject) => {
-    let timeout: ReturnType<typeof setTimeout>;
+/**
+ * Wait for the worker to confirm its repo is constructed. The MessageChannel
+ * adapter's whenReady() force-resolves after 100ms regardless of the other
+ * end's state, so it can't serve as a readiness signal on first boot, when the
+ * worker still has to fetch wasm and build its repo.
+ */
+function awaitPortReady(control: MessagePort, id: number): Promise<void> {
+  return new Promise((resolve, reject) => {
     const cleanup = () => {
       clearTimeout(timeout);
-      worker.port.removeEventListener("message", listener);
+      control.removeEventListener("message", listener);
     };
     const listener = (event: MessageEvent) => {
       if (event.data?.id !== id) return;
-      if (event.data?.type === "port-ready") {
+      if (event.data.type === "port-ready") {
         cleanup();
         resolve();
-      } else if (event.data?.type === "port-failed") {
+      } else if (event.data.type === "port-failed") {
         cleanup();
         reject(new Error(`automerge worker init failed: ${event.data.error}`));
       }
     };
-    worker.port.addEventListener("message", listener);
-    // Failsafe: don't block boot forever if the worker never replies. Surface
-    // the issue and let the rest of the site come up rather than hanging on a
-    // blank page.
-    timeout = setTimeout(() => {
+    control.addEventListener("message", listener);
+    const timeout = setTimeout(() => {
       cleanup();
       reject(new Error("automerge worker port-ready timeout"));
     }, 30_000);
   });
-  worker.port.postMessage({ type: "port", id }, [port2]);
+}
+
+async function openRepoChannel(): Promise<MessagePort> {
+  const id = ++nextRepoChannelId;
+  const ready = awaitPortReady(getAutomergeWorker().port, id);
+  const port = sendRepoPort(id);
   try {
-    await workerReady;
+    await ready;
   } catch (err) {
+    // Surface the problem and let the rest of the site come up rather than
+    // hanging on a blank page.
     console.warn(
       "proceeding without worker ready ack:",
       err instanceof Error ? err.message : err
     );
   }
-  return port1;
+  return port;
 }
 
 /** Open a fresh repo sync port to the automerge worker (dev console). */
 function getRepoChannel(): MessagePort {
-  const worker = getAutomergeWorker();
-  const { port1, port2 } = new MessageChannel();
-  worker.port.postMessage({ type: "port", id: ++nextRepoChannelId }, [port2]);
-  return port1;
+  return sendRepoPort(++nextRepoChannelId);
+}
+
+function waitForActive(reg: ServiceWorkerRegistration): Promise<ServiceWorker> {
+  if (reg.active) return Promise.resolve(reg.active);
+  const worker = reg.installing || reg.waiting;
+  if (!worker) {
+    return Promise.reject(new Error("no service worker in registration"));
+  }
+  return new Promise((resolve, reject) => {
+    worker.addEventListener("statechange", () => {
+      if (worker.state === "activated") resolve(worker);
+      // Without this the promise never settles when an install fails.
+      else if (worker.state === "redundant") {
+        reject(new Error("service worker became redundant before activating"));
+      }
+    });
+  });
 }
 
 export default async function setupServiceWorker(
   options?: SetupServiceWorkerOptions
 ): Promise<SetupServiceWorkerResult> {
-  // Attach the SW→tab [lifecycle] log bridge as early as possible so boot /
-  // install / activate markers from the controlling worker are rendered here.
+  // Attach the log bridge first so the controlling worker's boot/install/
+  // activate markers are rendered here.
   installServiceWorkerLogForwarding();
-  localStorage.removeItem(key);
+  localStorage.removeItem(CACHE_VERSION_KEY);
 
-  // Ask for persistent storage so cache growth can't trip origin-wide
-  // eviction, which would take the Automerge IndexedDB — the user's documents
-  // — with it. Chrome/Safari decide silently from site engagement; Firefox may
-  // show a one-time prompt. Best-effort: denial just means default eviction.
+  // Cache growth can otherwise trip origin-wide eviction, which would take the
+  // Automerge IndexedDB — the user's documents — with it. Chrome/Safari decide
+  // silently from site engagement; Firefox may prompt. Denial just means
+  // default eviction.
   void navigator.storage?.persist?.().catch(() => {});
 
   if (options?.workerPath) automergeWorkerPath = options.workerPath;
 
-  // Start the automerge worker right away so it boots (wasm, repo) while the
+  // Start the automerge worker now so it boots wasm and its repo while the
   // service worker installs.
   const shared = getAutomergeWorker();
-  // todo delete
-
-  const path = options?.path ?? "/service-worker.js";
-  // No controller at this point means the page loaded without a service
-  // worker — i.e. this is a first-time install (or a hard reload). Wait for
-  // activation so the app boots with the SW in control of generated fetches.
-  const reg = await navigator.serviceWorker.register(path, { type: "module" });
-
-  // If there's an update waiting or installing, wait for it to activate
-  let active = reg.active;
-  if (reg.installing || reg.waiting) {
-    active = await waitForActive(reg);
-  }
 
+  const reg = await navigator.serviceWorker.register(
+    options?.path ?? "/service-worker.js",
+    { type: "module" }
+  );
+
+  const active =
+    reg.installing || reg.waiting ? await waitForActive(reg) : reg.active;
   configureServiceWorker(active);
 
-  // Wait for the controller to be available
+  // No controller means the page loaded without a service worker — a first-time
+  // install or a hard reload. Wait for it so the app boots with the worker in
+  // control of generated fetches.
   if (!navigator.serviceWorker.controller) {
     await new Promise<void>((resolve) => {
       navigator.serviceWorker.addEventListener(
@@ -662,8 +556,8 @@ export default async function setupServiceWorker(
     });
   }
 
-  // A replacement service worker boots with the default cache name — re-send
-  // its configuration whenever a new one takes control.
+  // A replacement worker boots with the default cache name, so reconfigure
+  // whenever a new one takes control.
   navigator.serviceWorker.addEventListener("controllerchange", () => {
     configureServiceWorker(navigator.serviceWorker.controller);
   });
@@ -673,30 +567,20 @@ export default async function setupServiceWorker(
     "background: #fcf2f0; color: #333; border: 2px solid; border-radius: 4px"
   );
 
-  // todon't
-  (window as any).killsw = () => {
-    if (automergeWorker) {
-      automergeWorker.port.close();
-      automergeWorker = undefined;
-    }
-  };
-
   return {
     shared,
     connectClassicSync,
     getRepoChannel,
     subscribeSyncState,
+    // Called once with the boot port. If the automerge worker later dies and is
+    // recreated, the listener is called again with a fresh port — treat every
+    // call as "(re)wire your repo's sync onto this port".
     async subscribeToRepoChannel(listener: ServiceWorkerRepoChannelListener) {
-      // Called once with the boot port. If the automerge worker later dies
-      // and is recreated (recoverAutomergeWorker), the listener is called
-      // again with a fresh port — treat every call as "(re)wire your repo's
-      // sync onto this port".
       repoChannelListeners.add(listener);
       const generation = workerGeneration;
       const port = await openRepoChannel();
-      // If the worker was replaced while this channel was opening (e.g. the
-      // port-ready wait timed out against a stranded connection and recovery
-      // already delivered a good port to this listener), drop the stale one
+      // If the worker was replaced while this channel was opening, recovery has
+      // already delivered a good port to this listener — drop the stale one
       // rather than wiring the repo to a dead channel.
       if (generation === workerGeneration) await listener(port);
       return () => {
@@ -705,3 +589,5 @@ export default async function setupServiceWorker(
     },
   };
 }
+
+(window as any).bumpServiceWorkerCache = bumpServiceWorkerCache;