@inkandswitch/patchwork-bootloader 0.4.3 → 0.5.0

package/dist/setup.js

@@ -3,105 +3,150 @@ import debug from "debug";
 import { donatePort, isWorkerErrorMessage, } from "@automerge/automerge-repo/worker-port";
 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() {
-    try {
-        const v = globalThis.localStorage?.getItem(LIFECYCLE_LOG_KEY);
-        return v !== "off" && v !== "false" && v !== "0" && v !== "no";
-    }
-    catch {
-        return true;
-    }
+export const lifecycleLog = debug("patchwork:lifecycle");
+function describeErrorEvent(event) {
+    const error = event;
+    const where = error.filename
+        ? ` (${error.filename}:${error.lineno}:${error.colno})`
+        : "";
+    return `${error.message || String(event)}${where}`;
+}
+// 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 currentCacheName() {
+    return localStorage.getItem(CACHE_VERSION_KEY) ?? DEFAULT_CACHE_NAME;
+}
+function configureServiceWorker(sw) {
+    if (!sw)
+        return;
+    sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
+    sw.postMessage({ type: "cachename", cachename: currentCacheName() });
 }
-// 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;
+export function bumpServiceWorkerCache(sw = navigator.serviceWorker.controller) {
+    if (!sw)
+        throw new Error("no service worker!");
+    localStorage.setItem(CACHE_VERSION_KEY, Date.now().toString(36));
+    sw.postMessage({ type: "cachename", cachename: currentCacheName() });
+}
+// 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() {
-    if (swLifecycleListenerInstalled)
+    if (logForwardingInstalled)
         return;
     if (typeof navigator === "undefined" || !navigator.serviceWorker)
         return;
-    swLifecycleListenerInstalled = true;
+    logForwardingInstalled = true;
     navigator.serviceWorker.addEventListener("message", (event) => {
-        const data = event.data;
-        if (data?.type !== "sw-lifecycle")
-            return;
-        if (!lifecycleLoggingEnabled())
+        if (event.data?.type !== "sw-lifecycle")
             return;
-        const fn = console[data.level] ?? console.log;
-        fn(`[service-worker] ${data.msg}`);
+        lifecycleLog("[service-worker] %s", event.data.msg);
     });
 }
-const key = "patchworkServiceWorkerCacheVersion";
-const defaultServiceWorkerCacheName = "patchwork";
-let nextRepoChannelId = 0;
-function bumpServiceWorkerCacheVersion() {
-    const version = new Date().valueOf().toString(36);
-    localStorage.setItem(key, version);
-    return getServiceWorkerCacheVersion();
-}
-function getServiceWorkerCacheVersion() {
-    return localStorage.getItem(key);
-}
-function setServiceWorkerCacheName(sw) {
-    if (!sw) {
-        throw new Error("no service worker!");
-    }
-    sw.postMessage({
-        type: "cachename",
-        cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
-    });
-}
-export function bumpServiceWorkerCache(sw = navigator.serviceWorker.controller) {
-    bumpServiceWorkerCacheVersion();
-    setServiceWorkerCacheName(sw);
-}
-window.bumpServiceWorkerCache = bumpServiceWorkerCache;
-function configureServiceWorker(sw) {
-    if (!sw)
-        return;
-    sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
-    sw.postMessage({
-        type: "cachename",
-        cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
-    });
-}
-// ── 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;
-// 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;
-// Every subscribeToRepoChannel listener, kept so a recovered worker can hand
-// each subscriber a fresh repo port.
 const repoChannelListeners = new Set();
 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() {
+    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) {
+    const data = event.data;
+    if (data?.type === "sync-state") {
+        dispatchSyncState(data);
+        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[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() {
+    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, deadWorker) {
     if (deadWorker !== automergeWorker)
-        return; // already replaced
+        return;
     if (recoveringWorker)
         return;
     const now = Date.now();
@@ -109,8 +154,7 @@ async function recoverAutomergeWorker(reason, deadWorker) {
         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;
@@ -118,16 +162,11 @@ async function recoverAutomergeWorker(reason, deadWorker) {
         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;
@@ -146,210 +185,72 @@ async function recoverAutomergeWorker(reason, deadWorker) {
         recoveringWorker = false;
     }
 }
-// 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() {
-    const params = new URLSearchParams();
-    try {
-        for (const [key, param] of [
-            ["patchwork:ws-mode", "ws-mode"],
-            ["patchwork:ws-window", "ws-window"],
-        ]) {
-            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() {
-    return `${automergeWorkerPath}${workerBenchParams()}`;
-}
-export function getAutomergeWorker() {
-    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) => {
-            if (event.data?.type === "sync-state") {
-                dispatchSyncState(event.data);
-                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.__driftSamples ??= []);
-                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[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;
-                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).
- */
+// 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;
 function installWorkerDeathDetection(worker) {
-    const stamp = () => new Date().toISOString();
-    const warn = (msg) => {
-        if (lifecycleLoggingEnabled())
-            console.warn(`[lifecycle] ${stamp()} ${msg}`);
-    };
-    const info = (msg) => {
-        if (lifecycleLoggingEnabled())
-            console.info(`[lifecycle] ${stamp()} ${msg}`);
-    };
     let instanceId;
     let lastHeardAt = Date.now();
     let warnedUnresponsive = false;
+    let warnedSendFailed = false;
     let disposed = false;
     let probe;
+    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) => {
         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;
-        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) => {
         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",
         });
@@ -360,39 +261,27 @@ function installWorkerDeathDetection(worker) {
                 return;
             setTimeout(() => {
                 if (disposed || probe !== p)
-                    return; // superseded or torn down
+                    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)`, worker);
             }, 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;
@@ -400,21 +289,24 @@ function installWorkerDeathDetection(worker) {
         const timeoutMs = neverHeard
             ? FIRST_CONTACT_TIMEOUT_MS
             : HEARTBEAT_TIMEOUT_MS;
-        const visible = typeof document === "undefined" || document.visibilityState === "visible";
+        if (silentMs <= timeoutMs)
+            return;
         // 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);
+        // 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";
+        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 () => {
         disposed = true;
@@ -424,10 +316,7 @@ function installWorkerDeathDetection(worker) {
 }
 const syncStateListeners = new Map();
 function dispatchSyncState(update) {
-    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);
         }
@@ -441,26 +330,24 @@ export function subscribeSyncState(documentId, listener) {
     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
+            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 });
     };
 }
 export function connectClassicSync(server = readClassicSyncServer()) {
@@ -478,146 +365,134 @@ export function connectClassicSync(server = readClassicSyncServer()) {
         port1.onmessage = (event) => {
             clearTimeout(timeout);
             port1.close();
-            if (event.data?.type === "connect-classic-sync-ready") {
+            if (event.data?.type === "connect-classic-sync-ready")
                 resolve();
-            }
-            else {
+            else
                 reject(new Error(event.data?.error ?? "connect-classic-sync failed"));
-            }
         };
         worker.port.postMessage({ type: "connect-classic-sync", server: url }, [
             port2,
         ]);
     });
 }
-/** Wait for a registration to have an active worker */
-function waitForActive(reg) {
-    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);
-        });
-    });
-}
-async function openRepoChannel() {
-    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;
+function sendRepoPort(id) {
     const { port1, port2 } = new MessageChannel();
-    const workerReady = new Promise((resolve, reject) => {
-        let timeout;
+    getAutomergeWorker().port.postMessage({ type: "port", id }, [port2]);
+    return port1;
+}
+/**
+ * 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, id) {
+    return new Promise((resolve, reject) => {
         const cleanup = () => {
             clearTimeout(timeout);
-            worker.port.removeEventListener("message", listener);
+            control.removeEventListener("message", listener);
         };
         const listener = (event) => {
             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() {
+    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() {
-    const worker = getAutomergeWorker();
-    const { port1, port2 } = new MessageChannel();
-    worker.port.postMessage({ type: "port", id: ++nextRepoChannelId }, [port2]);
-    return port1;
+    return sendRepoPort(++nextRepoChannelId);
+}
+function waitForActive(reg) {
+    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) {
-    // 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);
-    // 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.
+    localStorage.removeItem(CACHE_VERSION_KEY);
+    // 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((resolve) => {
             navigator.serviceWorker.addEventListener("controllerchange", () => resolve(), { once: true });
         });
     }
-    // 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);
     });
     console.log("service worker alive, loading %c patchwork system ", "background: #fcf2f0; color: #333; border: 2px solid; border-radius: 4px");
-    // todon't
-    window.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) {
-            // 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);
@@ -627,3 +502,4 @@ export default async function setupServiceWorker(options) {
         },
     };
 }
+window.bumpServiceWorkerCache = bumpServiceWorkerCache;