@inkandswitch/patchwork-bootloader 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @inkandswitch/patchwork-bootloader
 
+## 0.3.1
+
+### Patch Changes
+
+- 099e931: Discover a package's plugin descriptors in a dedicated module worker off the
+  main thread, then re-import the package (pinned to the same heads) on the main
+  thread to run each plugin's real loader. Adds
+  `importPluginFromFolderDocUrl(folderDocUrl, pluginType, pluginId)`, which selects
+  the plugin by both its `type` and `id` — a plugin `id` is only unique within a
+  plugin type, so a package may export e.g. a `patchwork:datatype` and a
+  `patchwork:tool` that share the same id.
+- Updated dependencies [099e931]
+  - @inkandswitch/patchwork-filesystem@0.1.1
+
 ## 0.2.8
 
 ### Patch Changes

package/dist/automerge-worker.js

@@ -20,12 +20,99 @@ import { WebCryptoSigner } from "@automerge/automerge-subduction/slim";
 import { Repo, isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "@automerge/automerge-repo/slim";
 import { resolvePath } from "@inkandswitch/patchwork-filesystem";
 // Small adapters — bundled directly into the worker
-import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
+import { IndexedDBWorkerStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb/IndexedDBWorkerStorageAdapter";
 import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel";
-import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
+import { WebSocketWorkerClientAdapter } from "@automerge/automerge-repo-network-websocket";
 import { initializeAutomergeRepoKeyhiveRustWithRepo, initKeyhiveWasm, } from "@automerge/automerge-repo-keyhive";
 import { HANDOFF_CHANNEL, } from "./types.js";
 let debugging = false;
+// Per-boot identity so a tab can detect a worker *restart*: a fresh instance
+// means a new repo peerId + cold in-memory state, so the tab's docs must be
+// re-subscribed. Sent in `hello` (on connect) and every `pong`.
+const WORKER_INSTANCE_ID = Math.random().toString(36).slice(2);
+const WORKER_BOOT_TIME = Date.now();
+// ── Forward console output + uncaught errors to the main thread ─────────
+// The SharedWorker has its own console that's a pain to find (chrome://inspect
+// → shared workers). Patch console.* and the global error handlers to also
+// post back over every connected tab's control port, tagged [automerge-worker].
+const controlPorts = new Set();
+// Logs emitted before any tab has connected (e.g. during wasm boot) would
+// otherwise be lost — buffer a bounded number and flush on first connect.
+const preConnectBuffer = [];
+const MAX_BUFFER = 200;
+function serializeArg(arg) {
+    if (typeof arg === "string")
+        return arg;
+    if (arg instanceof Error)
+        return arg.stack || `${arg.name}: ${arg.message}`;
+    try {
+        return JSON.stringify(arg);
+    }
+    catch {
+        return String(arg);
+    }
+}
+function forwardToMainThread(level, rawArgs) {
+    const args = rawArgs.map(serializeArg);
+    if (!controlPorts.size) {
+        if (preConnectBuffer.length < MAX_BUFFER) {
+            preConnectBuffer.push({ level, args });
+        }
+        return;
+    }
+    for (const port of controlPorts) {
+        try {
+            port.postMessage({ type: "console", level, args });
+        }
+        catch {
+            // Port may be closing — ignore.
+        }
+    }
+}
+for (const level of ["log", "info", "warn", "error", "debug"]) {
+    const original = console[level].bind(console);
+    console[level] = (...args) => {
+        original(...args);
+        forwardToMainThread(level, args);
+    };
+}
+self.addEventListener("error", (event) => {
+    const e = event;
+    forwardToMainThread("error", [
+        `uncaught error: ${e.message}`,
+        e.error instanceof Error ? e.error.stack : undefined,
+    ]);
+});
+self.addEventListener("unhandledrejection", (event) => {
+    const reason = event.reason;
+    forwardToMainThread("error", [
+        "unhandled rejection:",
+        reason instanceof Error ? reason.stack || reason.message : reason,
+    ]);
+});
+// Boot marker, buffered until the first tab connects. A new instance id means
+// the worker restarted (fresh peerId + cold state).
+console.warn(`[lifecycle] ${new Date(WORKER_BOOT_TIME).toISOString()} automerge ` +
+    `SharedWorker started (instance ${WORKER_INSTANCE_ID})`);
+// ── Suspension watchdog ─────────────────────────────────────────────────
+// A SharedWorker gets no lifecycle events, so infer freeze/suspend from timer
+// drift. A large gap means keepalive pongs stalled and the server may have
+// reaped us.
+const WATCHDOG_TICK_MS = 5_000;
+const WATCHDOG_GAP_FACTOR = 2;
+let watchdogLast = Date.now();
+setInterval(() => {
+    const now = Date.now();
+    const gap = now - watchdogLast;
+    watchdogLast = now;
+    if (gap > WATCHDOG_TICK_MS * WATCHDOG_GAP_FACTOR) {
+        console.warn(`[lifecycle] worker resumed after ~${Math.round(gap / 1000)}s gap ` +
+            `(timer expected every ${WATCHDOG_TICK_MS / 1000}s) — likely ` +
+            `suspended/frozen/throttled; WebSocket keepalive pongs were not sent ` +
+            `during this window, so the sync server may have reaped us. at ` +
+            `${new Date(now).toISOString()}`);
+    }
+}, WATCHDOG_TICK_MS);
 // Sync server selection. Sub is the default. Build with KEYHIVE_SYNC_SERVER=true
 // to target keyhive.sync.automerge.org.
 const useKeyhiveSyncServer = typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
@@ -61,7 +148,7 @@ async function connectClassicSyncNetwork(server) {
     classicSyncConnectPromise = (async () => {
         const { repo } = await getRepoHive();
         if (!classicSyncAdapter) {
-            classicSyncAdapter = new WebSocketClientAdapter(url);
+            classicSyncAdapter = new WebSocketWorkerClientAdapter(url);
             repo.networkSubsystem.addNetworkAdapter(classicSyncAdapter);
         }
         await classicSyncAdapter.whenReady();
@@ -99,7 +186,7 @@ function getRepoHive() {
             if (!useKeyhive) {
                 const signer = await WebCryptoSigner.setup();
                 const repo = new Repo({
-                    storage: new IndexedDBStorageAdapter(),
+                    storage: new IndexedDBWorkerStorageAdapter(),
                     signer,
                     peerId: ("automerge-worker-" +
                         Math.random()
@@ -122,7 +209,7 @@ function getRepoHive() {
             // ARK variant for talking to the keyhive-enabled subduction sync server.
             const { hive, repo } = await initializeAutomergeRepoKeyhiveRustWithRepo({
                 createRepo: (config) => new Repo(config),
-                storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
+                storage: new IndexedDBWorkerStorageAdapter(`${siteName}-keyhive`),
                 peerIdSuffix: `${siteName}-worker` + Math.random().toString(36).slice(2),
                 automaticArchiveIngestion: true,
                 cachingMode: "periodic",
@@ -131,7 +218,7 @@ function getRepoHive() {
                 // defaults to "subduction".
                 ...(useKeyhiveSyncServer ? { syncServer: "keyhive" } : {}),
                 repo: {
-                    storage: new IndexedDBStorageAdapter(),
+                    storage: new IndexedDBWorkerStorageAdapter(),
                     subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
                     enableRemoteHeadsGossiping: true,
                 },
@@ -266,6 +353,14 @@ function handleControlMessage(event, controlPort, connection) {
             replyPort?.close();
         });
     }
+    else if (data?.type === "ping") {
+        // Heartbeat: reply so the tab can detect our death or restart.
+        controlPort.postMessage({
+            type: "pong",
+            id: data.id,
+            instanceId: WORKER_INSTANCE_ID,
+        });
+    }
 }
 self.addEventListener("connect", (event) => {
     const controlPort = event.ports[0];
@@ -276,9 +371,30 @@ self.addEventListener("connect", (event) => {
     // Fires when the owning page is destroyed. Browsers without the close
     // event fall back to the adapters' lazy useWeakRef cleanup.
     controlPort.addEventListener("close", () => {
+        controlPorts.delete(controlPort);
         void dropConnection(connection);
     });
     controlPort.start();
+    // Greet the tab with our per-boot instance id so it can detect a restart
+    // (a different id than last seen) even if no port "close" fired.
+    controlPort.postMessage({
+        type: "hello",
+        instanceId: WORKER_INSTANCE_ID,
+        bootTime: WORKER_BOOT_TIME,
+    });
+    // Start forwarding console output to this tab, and flush anything buffered
+    // while no tab was connected (e.g. boot-time logs) to the first arrival.
+    controlPorts.add(controlPort);
+    if (preConnectBuffer.length) {
+        for (const { level, args } of preConnectBuffer.splice(0)) {
+            try {
+                controlPort.postMessage({ type: "console", level, args });
+            }
+            catch {
+                // Port may already be gone — ignore.
+            }
+        }
+    }
 });
 // ── Automerge URL resolution ───────────────────────────────────────────
 /**
@@ -422,7 +538,7 @@ async function handleHandoffRequest(message) {
             id,
             type: "response",
             response: {
-                status: 500,
+                status: 557,
                 body,
                 headers: { "content-type": "text/plain" },
             },
@@ -469,7 +585,7 @@ async function handleHandoffRequest(message) {
             id,
             type: "response",
             response: {
-                status: 500,
+                status: 558,
                 body: String(error),
                 headers: { "content-type": "text/plain" },
             },

package/dist/externals.js

@@ -7,10 +7,9 @@ const externals = [
     "@automerge/automerge-repo",
     "@automerge/automerge-repo/slim",
     "@automerge/automerge-repo-network-messagechannel",
+    "@automerge/automerge-repo-network-websocket",
     "@automerge/automerge-repo-storage-indexeddb",
     "@automerge/automerge-repo-keyhive",
-    "@automerge/automerge-repo-network-messagechannel",
-    "@automerge/automerge-repo-storage-indexeddb",
     "@automerge/automerge-subduction",
     "@automerge/automerge-subduction/slim",
     "@keyhive/keyhive",

package/dist/module-loader-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/module-loader-worker.js

@@ -0,0 +1,55 @@
+// Dedicated module worker for plugin-descriptor discovery.
+//
+// A module-settings doc lists Automerge folder-doc packages. To register the
+// plugins a package provides we only need their *descriptions* (id, type,
+// name, icon…), not their implementations. This worker imports a package's
+// entry point off the main thread purely to read its exported `plugins` array,
+// strips the non-cloneable `load()` / `import` machinery, and posts the plain
+// descriptors back. The main thread re-imports the package (at the same heads)
+// only when a plugin is actually loaded — see `importPluginFromFolderDocUrl`.
+//
+// Created with type:"module"; its dynamic `import()` of `/<automergeUrl>/…`
+// entry points is served by the service worker that controls this worker.
+import { importModuleFromFolderDocUrl } from "@inkandswitch/patchwork-filesystem";
+// Keep only the structured-cloneable description fields. `load` is a closure
+// and `module` is the (possibly already-loaded) implementation — neither can
+// cross the worker boundary. `import` is droppable too: the main thread
+// rebuilds loading by re-importing the package and calling the live plugin.
+function toDescriptor(plugin) {
+    if (!plugin || typeof plugin !== "object")
+        return {};
+    const { load, import: _import, module, ...description } = plugin;
+    return description;
+}
+function isDiscoverRequest(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        data.type === "discover" &&
+        typeof data.id === "number" &&
+        typeof data.url === "string");
+}
+self.addEventListener("message", (event) => {
+    const data = event.data;
+    if (!isDiscoverRequest(data))
+        return;
+    const { id, url } = data;
+    importModuleFromFolderDocUrl(url)
+        .then((mod) => {
+        const plugins = Array.isArray(mod?.plugins) ? mod.plugins : [];
+        const descriptors = plugins.map(toDescriptor);
+        self.postMessage({
+            type: "descriptors",
+            id,
+            descriptors,
+        });
+    })
+        .catch((error) => {
+        self.postMessage({
+            type: "error",
+            id,
+            error: error instanceof Error
+                ? (error.stack ?? error.message)
+                : String(error),
+        });
+    });
+});

package/dist/module-loader.d.ts

@@ -0,0 +1,13 @@
+type Descriptor = Record<string, unknown> & {
+    id?: string;
+    type?: string;
+};
+/**
+ * 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 declare function importAutomergeModuleViaWorker(urlAtHeads: string): Promise<{
+    plugins: Descriptor[];
+}>;
+export {};

package/dist/module-loader.js

@@ -0,0 +1,72 @@
+// 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";
+const WORKER_PATH = "/module-loader-worker.js";
+let worker;
+let nextRequestId = 1;
+const pending = new Map();
+function getWorker() {
+    if (worker)
+        return worker;
+    worker = new Worker(WORKER_PATH, {
+        type: "module",
+        name: "patchwork-module-loader",
+    });
+    worker.addEventListener("message", (event) => {
+        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) {
+    const id = nextRequestId++;
+    return new Promise((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) {
+    const url = urlAtHeads;
+    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/dist/service-worker.js

@@ -17,7 +17,36 @@ function log(...args) {
         return;
     console.log.call(console, `%cpatchwork:serviceworker%c\n`, `color: #00ffcc; font-weight: bold`, "color: inherit", ...args);
 }
+// ── 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) {
+    const clients = await self.clients.matchAll({
+        type: "window",
+        includeUncontrolled: true,
+    });
+    for (const client of clients)
+        client.postMessage(message);
+}
+function lifecycle(level, text) {
+    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;
+    lifecycle("warn", `uncaught error: ${e.message}` +
+        (e.filename ? ` @ ${e.filename}:${e.lineno}:${e.colno}` : ""));
+});
+self.addEventListener("unhandledrejection", (event) => {
+    const reason = event.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.
@@ -34,12 +63,28 @@ async function clearOldCaches() {
     await Promise.all(deletePromises);
 }
 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.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
+            }
+        }));
     })());
 });
 self.addEventListener("message", async (event) => {
@@ -72,7 +117,12 @@ 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);
         }
@@ -98,6 +148,8 @@ function handoff(request, handoffURL) {
     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`));
     }, HANDOFF_TIMEOUT_MS);
     return resolvers.promise.finally(() => {
@@ -153,7 +205,7 @@ self.addEventListener("fetch", (fetchEvent) => {
                 // response in our cache
                 const cached = await cache.match(request);
                 if (!cached) {
-                    return new Response(`the automerge worker reported ${handoffURL} cached, but it has no match in ${cachename}`, { status: 500 });
+                    return new Response(`the automerge worker reported ${handoffURL} cached, but it has no match in ${cachename}`, { status: 555 });
                 }
                 log(`serving ${handoffURL} from cache ${cachename} after handoff`);
                 return withSpecialHeaders(cached);
@@ -185,7 +237,7 @@ self.addEventListener("fetch", (fetchEvent) => {
             if (match)
                 return match;
             return new Response(message, {
-                status: 500,
+                status: 556,
                 headers: { "content-type": "text/plain" },
             });
         }

package/dist/setup.d.ts

@@ -1,4 +1,6 @@
 import type { SetupServiceWorkerOptions, SetupServiceWorkerResult } from "./types.js";
+export declare function lifecycleLoggingEnabled(): boolean;
 export declare function bumpServiceWorkerCache(sw?: ServiceWorker | null): void;
+export declare function getAutomergeWorker(): SharedWorker;
 export declare function connectClassicSync(server?: string): Promise<void>;
 export default function setupServiceWorker(options?: SetupServiceWorkerOptions): Promise<SetupServiceWorkerResult>;

package/dist/setup.js

@@ -2,6 +2,37 @@ import { readClassicSyncServer, DEFAULT_CLASSIC_SYNC_SERVER, } from "./sync-conf
 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() {
+    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() {
+    if (swLifecycleListenerInstalled)
+        return;
+    if (typeof navigator === "undefined" || !navigator.serviceWorker)
+        return;
+    swLifecycleListenerInstalled = true;
+    navigator.serviceWorker.addEventListener("message", (event) => {
+        const data = event.data;
+        if (data?.type !== "sw-lifecycle")
+            return;
+        if (!lifecycleLoggingEnabled())
+            return;
+        const fn = console[data.level] ?? console.log;
+        fn(`[service-worker] ${data.msg}`);
+    });
+}
 const key = "patchworkServiceWorkerCacheVersion";
 let nextRepoChannelId = 0;
 function bumpServiceWorkerCacheVersion() {
@@ -48,7 +79,7 @@ function configureServiceWorker(sw) {
 // port; it talks to the service worker over a BroadcastChannel.
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker;
-function getAutomergeWorker() {
+export function getAutomergeWorker() {
     if (!automergeWorker) {
         automergeWorker = new SharedWorker(automergeWorkerPath, {
             name: "patchwork-automerge",
@@ -57,10 +88,99 @@ function getAutomergeWorker() {
         // 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 !== "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 });
+        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) {
+    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 lastPongAt = Date.now();
+    let warnedUnresponsive = false;
+    worker.port.addEventListener("message", (event) => {
+        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.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 = readClassicSyncServer()) {
     const url = server.trim() || DEFAULT_CLASSIC_SYNC_SERVER;
     if (!/^wss?:\/\//.test(url)) {
@@ -155,11 +275,15 @@ function getRepoChannel() {
     return port1;
 }
 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.
+    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
     // worker — i.e. this is a first-time install (or a hard reload). Wait for
@@ -183,7 +307,15 @@ export default async function setupServiceWorker(options) {
         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,
         async subscribeToRepoChannel(listener) {