@inkandswitch/patchwork-bootloader 0.3.0 → 0.3.1

package/src/module-loader.ts

@@ -0,0 +1,85 @@
+// Main-thread client for the module-loader worker (see module-loader-worker.ts).
+//
+// `importAutomergeModuleViaWorker` is wired into the ModuleWatcher in place of
+// its default (direct, main-thread) package import. It asks the worker to
+// import the package entry point and report which plugins it exports, then
+// returns the same `{ plugins }` shape the watcher already feeds to
+// `registerPlugins` — except each plugin's `load()` re-imports the package
+// (pinned to the same heads) on this thread and runs the real plugin loader.
+
+import { importPluginFromFolderDocUrl } from "@inkandswitch/patchwork-filesystem";
+import type { AutomergeUrl } from "@automerge/automerge-repo/slim";
+
+type Descriptor = Record<string, unknown> & { id?: string; type?: string };
+
+type WorkerReply =
+  | { type: "descriptors"; id: number; descriptors: Descriptor[] }
+  | { type: "error"; id: number; error: string };
+
+const WORKER_PATH = "/module-loader-worker.js";
+
+let worker: Worker | undefined;
+let nextRequestId = 1;
+const pending = new Map<
+  number,
+  { resolve: (d: Descriptor[]) => void; reject: (e: Error) => void }
+>();
+
+function getWorker(): Worker {
+  if (worker) return worker;
+  worker = new Worker(WORKER_PATH, {
+    type: "module",
+    name: "patchwork-module-loader",
+  });
+  worker.addEventListener("message", (event: MessageEvent<WorkerReply>) => {
+    const data = event.data;
+    if (!data || (data.type !== "descriptors" && data.type !== "error")) return;
+    const entry = pending.get(data.id);
+    if (!entry) return;
+    pending.delete(data.id);
+    if (data.type === "descriptors") entry.resolve(data.descriptors);
+    else entry.reject(new Error(data.error));
+  });
+  worker.addEventListener("error", (event) => {
+    // An uncaught worker error can't be tied to a single request — fail every
+    // outstanding one so callers don't hang.
+    const error = new Error(
+      `module-loader worker error: ${event.message ?? "unknown"}`
+    );
+    for (const [, entry] of pending) entry.reject(error);
+    pending.clear();
+  });
+  return worker;
+}
+
+/** Ask the worker which plugins the package at `urlAtHeads` exports. */
+function discoverDescriptors(urlAtHeads: AutomergeUrl): Promise<Descriptor[]> {
+  const id = nextRequestId++;
+  return new Promise<Descriptor[]>((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    getWorker().postMessage({ type: "discover", id, url: urlAtHeads });
+  });
+}
+
+/**
+ * ModuleWatcher `importAutomergeModule` hook: discover descriptors in the
+ * worker, then return the `{ plugins }` shape with a main-thread `load()` per
+ * plugin that imports the package at heads and calls its real loader.
+ */
+export async function importAutomergeModuleViaWorker(
+  urlAtHeads: string
+): Promise<{ plugins: Descriptor[] }> {
+  const url = urlAtHeads as AutomergeUrl;
+  const descriptors = await discoverDescriptors(url);
+  const plugins = descriptors.map((descriptor) => {
+    const { id, type } = descriptor;
+    // A plugin id is only unique within a plugin type, so both are needed to
+    // re-select the right plugin when its load() re-imports the package.
+    if (typeof id !== "string" || typeof type !== "string") return descriptor;
+    return {
+      ...descriptor,
+      load: () => importPluginFromFolderDocUrl(url, type, id),
+    };
+  });
+  return { plugins };
+}

package/src/service-worker.ts

@@ -33,7 +33,49 @@ function log(...args: any[]) {
   );
 }
 
+// ── Lifecycle diagnostics ──────────────────────────────────────────────
+// [lifecycle] markers for SW (re)boots, install/activate, crashes, and stranded
+// handoffs. The SW can't read localStorage, so it always emits and forwards to
+// the tab, which gates rendering on the live toggle. The SW holds no sync
+// socket — observability only.
+
+async function postToClients(message: unknown) {
+  const clients = await self.clients.matchAll({
+    type: "window",
+    includeUncontrolled: true,
+  });
+  for (const client of clients) client.postMessage(message);
+}
+
+function lifecycle(level: "info" | "warn", text: string) {
+  const msg = `[lifecycle] ${new Date().toISOString()} ${text}`;
+  console[level](msg);
+  void postToClients({ type: "sw-lifecycle", level, msg });
+}
+
+lifecycle("info", `booted (scope ${self.registration?.scope ?? "?"})`);
+
+self.addEventListener("error", (event) => {
+  const e = event as ErrorEvent;
+  lifecycle(
+    "warn",
+    `uncaught error: ${e.message}` +
+      (e.filename ? ` @ ${e.filename}:${e.lineno}:${e.colno}` : "")
+  );
+});
+
+self.addEventListener("unhandledrejection", (event) => {
+  const reason = (event as PromiseRejectionEvent).reason;
+  lifecycle(
+    "warn",
+    `unhandled rejection: ${
+      reason instanceof Error ? reason.stack || reason.message : String(reason)
+    }`
+  );
+});
+
 self.addEventListener("install", (event) => {
+  lifecycle("info", "install (skipWaiting)");
   // waitUntil keeps the worker alive until skipWaiting resolves, so a freshly
   // installed SW reliably jumps the "waiting" queue instead of stalling until
   // every old tab closes.
@@ -52,13 +94,30 @@ async function clearOldCaches() {
 }
 
 self.addEventListener("activate", (event) => {
-  // Without waitUntil the activate event settles immediately and clients.claim()
-  // runs detached — the new worker can be killed before it takes control, so
-  // existing tabs keep talking to the old SW. Extend the event instead.
+  lifecycle("info", "activate (claiming clients)");
   (event as ExtendableEvent).waitUntil(
     (async () => {
       await clearOldCaches();
       await self.clients.claim();
+      // Pre-cache pages of already-open clients so they survive going offline
+      // before the next navigation.
+      const allClients = await self.clients.matchAll({ type: "window" });
+      const cache = await caches.open(cachename);
+      await Promise.all(
+        allClients.map(async (client) => {
+          try {
+            const existing = await cache.match(client.url);
+            if (!existing) {
+              const response = await fetch(client.url);
+              if (cacheableStatuses.includes(response.status)) {
+                await cache.put(client.url, response);
+              }
+            }
+          } catch {
+            // Network may be unavailable during activation
+          }
+        })
+      );
     })()
   );
 });
@@ -102,7 +161,15 @@ handoffChannel.addEventListener("message", (event) => {
   } else if (data?.type === "online") {
     // The automerge worker (re)started — re-broadcast anything still in
     // flight so requests that raced its boot aren't stranded.
-    for (const { message } of pendingHandoffs.values()) {
+    const stranded = [...pendingHandoffs.values()];
+    if (stranded.length > 0) {
+      lifecycle(
+        "info",
+        `automerge worker (re)started; re-broadcasting ${stranded.length} ` +
+          `in-flight asset handoff(s)`
+      );
+    }
+    for (const { message } of stranded) {
       log(`re-broadcasting handoff ${message.id} to the fresh worker`);
       handoffChannel.postMessage(message);
     }
@@ -132,6 +199,11 @@ function handoff(
   log(`broadcasting handoff request for cache ${cachename}`, message);
   handoffChannel.postMessage(message);
   const timeout = setTimeout(() => {
+    lifecycle(
+      "warn",
+      `asset handoff ${id} stranded: no reply from the automerge worker after ` +
+        `${HANDOFF_TIMEOUT_MS}ms (${handoffURL.href})`
+    );
     resolvers.reject(
       new Error(
         `no reply from the automerge worker after ${HANDOFF_TIMEOUT_MS}ms`
@@ -208,7 +280,7 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
           if (!cached) {
             return new Response(
               `the automerge worker reported ${handoffURL} cached, but it has no match in ${cachename}`,
-              { status: 500 }
+              { status: 555 }
             );
           }
           log(`serving ${handoffURL} from cache ${cachename} after handoff`);
@@ -245,7 +317,7 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
         if (match) return match;
 
         return new Response(message, {
-          status: 500,
+          status: 556,
           headers: { "content-type": "text/plain" },
         });
       }

package/src/setup.ts

@@ -12,6 +12,34 @@ import debug from "debug";
 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}`);
+  });
+}
+
 const key = "patchworkServiceWorkerCacheVersion";
 let nextRepoChannelId = 0;
 
@@ -67,7 +95,7 @@ function configureServiceWorker(sw: ServiceWorker | null) {
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker: SharedWorker | undefined;
 
-function getAutomergeWorker(): SharedWorker {
+export function getAutomergeWorker(): SharedWorker {
   if (!automergeWorker) {
     automergeWorker = new SharedWorker(automergeWorkerPath, {
       name: "patchwork-automerge",
@@ -76,11 +104,107 @@ function getAutomergeWorker(): SharedWorker {
     // 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 !== "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 });
+
+    installWorkerDeathDetection(automergeWorker);
   }
   return automergeWorker;
 }
 
+/**
+ * Detect when the automerge SharedWorker dies or restarts: control-port close,
+ * worker error, changed instance id, or an unanswered heartbeat while the tab
+ * is visible (a miss while hidden is more likely suspension). [lifecycle]-tagged.
+ */
+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 lastPongAt = Date.now();
+  let warnedUnresponsive = false;
+
+  worker.port.addEventListener("message", (event: MessageEvent) => {
+    const data = event.data;
+    if (data?.type !== "hello" && data?.type !== "pong") return;
+    if (data.type === "pong") {
+      lastPongAt = Date.now();
+      warnedUnresponsive = false;
+    }
+    if (instanceId === undefined) {
+      instanceId = data.instanceId;
+      info(`automerge SharedWorker instance ${data.instanceId} (via ${data.type})`);
+    } else if (data.instanceId && data.instanceId !== instanceId) {
+      warn(
+        `automerge SharedWorker RESTARTED (instance ${data.instanceId}, ` +
+          `was ${instanceId}) — fresh peerId + cold state; docs need re-subscribe`
+      );
+      instanceId = data.instanceId;
+    }
+  });
+
+  // Fires when the SharedWorker is destroyed (where supported).
+  worker.port.addEventListener("close", () => {
+    warn("automerge SharedWorker control port CLOSED — worker terminated");
+  });
+
+  worker.addEventListener("error", event => {
+    warn(`automerge SharedWorker error: ${(event as ErrorEvent).message || event}`);
+  });
+
+  // A missed pong while the tab is visible means the worker likely died (an
+  // active tab keeps it alive); a miss while hidden is more likely suspension.
+  const HEARTBEAT_MS = 10_000;
+  const HEARTBEAT_TIMEOUT_MS = 25_000;
+  let seq = 0;
+  setInterval(() => {
+    try {
+      worker.port.postMessage({ type: "ping", id: ++seq });
+    } catch {
+      // Port already torn down — the "close" handler covers that case.
+    }
+    const silentMs = Date.now() - lastPongAt;
+    const visible =
+      typeof document === "undefined" || document.visibilityState === "visible";
+    if (silentMs > HEARTBEAT_TIMEOUT_MS && visible && !warnedUnresponsive) {
+      warnedUnresponsive = true;
+      warn(
+        `automerge SharedWorker UNRESPONSIVE ~${Math.round(silentMs / 1000)}s ` +
+          `while tab visible — likely died/crashed`
+      );
+    }
+  }, HEARTBEAT_MS);
+}
+
 export function connectClassicSync(
   server: string = readClassicSyncServer()
 ): Promise<void> {
@@ -104,11 +228,7 @@ export function connectClassicSync(
       if (event.data?.type === "connect-classic-sync-ready") {
         resolve();
       } else {
-        reject(
-          new Error(
-            event.data?.error ?? "connect-classic-sync failed"
-          )
-        );
+        reject(new Error(event.data?.error ?? "connect-classic-sync failed"));
       }
     };
     worker.port.postMessage({ type: "connect-classic-sync", server: url }, [
@@ -188,11 +308,16 @@ function getRepoChannel(): MessagePort {
 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.
+  installServiceWorkerLogForwarding();
+
   if (options?.workerPath) automergeWorkerPath = options.workerPath;
 
   // Start the automerge worker right away so it boots (wasm, repo) while the
   // service worker installs.
-  getAutomergeWorker();
+  const shared = getAutomergeWorker();
+  // todo delete
 
   const path = options?.path ?? "/service-worker.js";
   // No controller at this point means the page loaded without a service
@@ -230,7 +355,16 @@ 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,
     async subscribeToRepoChannel(listener: ServiceWorkerRepoChannelListener) {

package/src/site.ts

@@ -13,7 +13,6 @@
  */
 import {
   type DocHandle,
-  IndexedDBStorageAdapter,
   initializeWasm,
   isValidAutomergeUrl,
   isValidDocumentId,
@@ -23,9 +22,9 @@ import {
   stringifyAutomergeUrl,
   type AutomergeUrl,
   type DocumentId,
-  type StorageId,
   type UrlHeads,
 } from "@automerge/vanillajs/slim";
+import { IndexedDBWorkerStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb/IndexedDBWorkerStorageAdapter";
 import * as Automerge from "@automerge/automerge/slim";
 import * as AutomergeRepo from "@automerge/automerge-repo/slim";
 import {
@@ -50,6 +49,7 @@ const useKeyhiveSyncServer =
   typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
 
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
+import { importAutomergeModuleViaWorker } from "./module-loader.js";
 import {
   openDocument,
   registerPatchworkViewElement,
@@ -66,7 +66,10 @@ import {
 } from "@inkandswitch/patchwork-plugins";
 import * as plugins from "@inkandswitch/patchwork-plugins";
 
-import setupServiceWorker from "./setup.js";
+import setupServiceWorker, {
+  getAutomergeWorker,
+  lifecycleLoggingEnabled,
+} from "./setup.js";
 import type { ServiceWorkerRepoChannelListener } from "./types.js";
 import debug from "debug";
 const log = debug("patchwork:bootloader:site");
@@ -144,12 +147,6 @@ export interface SiteConfig {
    */
   rootElementId?: string;
 
-  /**
-   * Storage IDs to subscribe to for remote-heads gossiping. Defaults to
-   * Ink & Switch's production Subduction storage.
-   */
-  remoteStorageIds?: StorageId[];
-
   /**
    * When true, initialize keyhive for access control.
    * The Repo will use keyhive's network adapter, peerId, and idFactory
@@ -164,9 +161,6 @@ export interface BootResult {
   accountDocHandle: DocHandle<AccountDoc>;
 }
 
-const DEFAULT_REMOTE_STORAGE_ID =
-  "3760df37-a4c6-4f66-9ecd-732039a9385d" as StorageId;
-
 // Legacy big-patchwork hash shape: `slug--<documentId>[?=type]`.
 const BIG_PATCHWORK_HASH_REGEX =
   /(?<title>[A-Za-z0-9-]+)--(?<docId>[1-9A-HJ-NP-Za-km-z]+)(?<type>\?=[^&?]+)?/;
@@ -191,59 +185,81 @@ export async function bootPatchworkSite(
   const defaultModuleSources = resolveDefaultModules(config);
   showLoadingAnimation();
   log(`booting`, config);
+  installLifecycleLogging();
   await initializeWasm(automergeWasm);
   initSubductionSync(subductionWasm);
 
+  log("enabling workers");
   const sw = await setupServiceWorker();
   if (!sw) throw new Error("Failed to set up service worker");
+  log("workers ready");
 
   let hive: AutomergeRepoKeyhive | undefined;
-  // Get the initial automerge-worker port via subscribeToRepoChannel,
-  // then pass it to keyhive init which wraps it in its own network adapter.
-  let resolvePort!: (port: MessagePort) => void;
-  const portPromise = new Promise<MessagePort>((r) => {
-    resolvePort = r;
-  });
-  await sw.subscribeToRepoChannel(resolvePort);
-  const workerPort = await portPromise;
-
   let repo: Repo;
-  if (config.keyhive) {
-    initKeyhiveWasm();
-
-    ({ hive, repo } = await initializeAutomergeRepoKeyhiveWithRepo({
-      createRepo: (config) => new Repo(config),
-      storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
-      peerIdSuffix: siteName + Math.random().toString(36).slice(2),
-      networkAdapter: new MessageChannelNetworkAdapter(workerPort),
-      automaticArchiveIngestion: true,
-      cachingMode: "periodic",
-      onlyShareWithHardcodedServerPeerId: false,
-      // ARK selects the relay via `syncServer` ("keyhive" | "subduction").
-      // Defaults to "subduction".
-      ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
-      repo: {
-        storage: new IndexedDBStorageAdapter(),
-        enableRemoteHeadsGossiping: true,
-      },
-    }));
+
+  // If a Repo is already on `window` — an embedding context provided one before
+  // this entry ran — reuse it and its keyhive instead of standing up a fresh
+  // realm-local Repo, so we share the same documents and sync/keyhive context.
+  // Otherwise create our own below.
+  if (window.repo) {
+    log("using existing Repo from window");
+    repo = window.repo;
+    hive = window.hive;
   } else {
-    repo = new Repo({
-      network: [new MessageChannelNetworkAdapter(workerPort)],
-      storage: new IndexedDBStorageAdapter(),
-      async sharePolicy(peerId) {
-        return peerId.includes("automerge-worker");
-      },
-      enableRemoteHeadsGossiping: true,
-      peerId:
-        `${config.titleSuffix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
+    // Get the initial automerge-worker port via subscribeToRepoChannel,
+    // then pass it to keyhive init which wraps it in its own network adapter.
+    let resolvePort!: (port: MessagePort) => void;
+    const portPromise = new Promise<MessagePort>((r) => {
+      resolvePort = r;
     });
+    log("subscribing to repo channel");
+    await sw.subscribeToRepoChannel(resolvePort);
+    log("repo channel subscribed");
+    const workerPort = await portPromise;
+
+    if (config.keyhive) {
+      log("setting up keyhive");
+      initKeyhiveWasm();
+
+      ({ hive, repo } = await initializeAutomergeRepoKeyhiveWithRepo({
+        createRepo: (config) => new Repo(config),
+        storage: new IndexedDBWorkerStorageAdapter(`${siteName}-keyhive`),
+        peerIdSuffix: siteName + Math.random().toString(36).slice(2),
+        networkAdapter: new MessageChannelNetworkAdapter(workerPort),
+        automaticArchiveIngestion: true,
+        cachingMode: "periodic",
+        onlyShareWithHardcodedServerPeerId: false,
+        // ARK selects the relay via `syncServer` ("keyhive" | "subduction").
+        // Defaults to "subduction".
+        ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
+        repo: {
+          storage: new IndexedDBWorkerStorageAdapter(),
+          enableRemoteHeadsGossiping: true,
+        },
+      }));
+      log("keyhive setup complete");
+    } else {
+      log("creating repo");
+      repo = new Repo({
+        network: [new MessageChannelNetworkAdapter(workerPort)],
+        storage: new IndexedDBWorkerStorageAdapter(),
+        async sharePolicy(peerId) {
+          return peerId.includes("automerge-worker");
+        },
+        enableRemoteHeadsGossiping: true,
+        peerId:
+          `${config.titleSuffix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
+      });
+      log("repo created");
+    }
   }
-  repo.subscribeToRemotes(
-    config.remoteStorageIds ?? [DEFAULT_REMOTE_STORAGE_ID]
-  );
+  log("popping repo on window");
+  window.repo = repo;
+  log("await repo.networkSubsystem.whenReady()");
 
   await repo.networkSubsystem.whenReady();
+  log("networkSubsystem ready");
+
   if (hive) {
     (hive.networkAdapter as any).syncKeyhive?.();
   }
@@ -274,7 +290,10 @@ export async function bootPatchworkSite(
     repo,
     buildSystemSources(defaultModuleSources),
     onModuleLoaded,
-    unregisterPlugins
+    unregisterPlugins,
+    // Discover an Automerge package's plugin descriptors off the main thread;
+    // each plugin's load() re-imports the package (at heads) on this thread.
+    importAutomergeModuleViaWorker
   );
 
   const accountDocHandle = (await resolveAccountHandle(repo, {
@@ -336,10 +355,7 @@ function isValidModuleSource(source: string): boolean {
  * built-in default bundle).
  */
 function resolveDefaultModules(config: SiteConfig): string[] {
-  const builtin =
-    config.defaultModules ??
-    config.defaultModulesUrl ??
-    [];
+  const builtin = config.defaultModules ?? config.defaultModulesUrl ?? [];
   const builtinList = (Array.isArray(builtin) ? builtin : [builtin]).filter(
     Boolean
   );
@@ -396,6 +412,46 @@ function installDevConsoleGlobals(
   window.getRepoChannel = getRepoChannel;
 }
 
+/**
+ * Log this tab's Page Lifecycle + connectivity transitions (visibility,
+ * freeze, bfcache, online/offline) so they line up against the SharedWorker's
+ * sync-socket reaps. [lifecycle]-tagged, on by default.
+ */
+function installLifecycleLogging(): void {
+  if (typeof document === "undefined") return;
+  const opts = { capture: true } as const;
+  const note = (label: string, extra?: unknown) => {
+    if (!lifecycleLoggingEnabled()) return;
+    const msg = `[lifecycle] ${new Date().toISOString()} ${label}`;
+    if (extra === undefined) console.info(msg);
+    else console.info(msg, extra);
+  };
+
+  document.addEventListener(
+    "visibilitychange",
+    () => note(`visibilitychange → ${document.visibilityState}`),
+    opts
+  );
+  document.addEventListener("freeze", () => note("freeze (tab suspended)"), opts);
+  document.addEventListener("resume", () => note("resume (tab unsuspended)"), opts);
+  window.addEventListener(
+    "pageshow",
+    e => note("pageshow", { persisted: (e as PageTransitionEvent).persisted }),
+    opts
+  );
+  window.addEventListener(
+    "pagehide",
+    e => note("pagehide", { persisted: (e as PageTransitionEvent).persisted }),
+    opts
+  );
+  window.addEventListener("online", () => note("online"), opts);
+  window.addEventListener("offline", () => note("offline"), opts);
+
+  note(
+    `lifecycle logging installed (visibilityState=${document.visibilityState}, hasFocus=${document.hasFocus()})`
+  );
+}
+
 function onModuleLoaded(name: string, mod: any): void {
   if (Array.isArray(mod.plugins)) {
     log(
@@ -637,10 +693,7 @@ function installHashRouting(params: HashRoutingParams): void {
     if (isValidAutomergeUrl(hash as AutomergeUrl)) {
       const { documentId, heads } = parseAutomergeUrl(hash as AutomergeUrl);
       window.location.hash = "";
-      openDocument(
-        rootElement,
-        stringifyAutomergeUrl({ documentId, heads })
-      );
+      openDocument(rootElement, stringifyAutomergeUrl({ documentId, heads }));
       return;
     }
 
@@ -652,7 +705,8 @@ function installHashRouting(params: HashRoutingParams): void {
     const type = params.get("type");
     const frame = params.get("frame");
     if (frame) {
-      const docUrl = params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
+      const docUrl =
+        params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
       if (
         rootElement.getAttribute("tool-id") !== frame ||
         rootElement.getAttribute("doc-url") !== docUrl