@inkandswitch/patchwork-bootloader 0.3.0 → 0.3.2

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,9 @@
-import type { SetupServiceWorkerOptions, SetupServiceWorkerResult } from "./types.js";
+import type { SetupServiceWorkerOptions, SetupServiceWorkerResult, SyncStateDocMessage } from "./types.js";
+export declare function lifecycleLoggingEnabled(): boolean;
 export declare function bumpServiceWorkerCache(sw?: ServiceWorker | null): void;
+export declare function getAutomergeWorker(): SharedWorker;
+type SyncStateListener = (update: SyncStateDocMessage) => void;
+export declare function subscribeSyncState(documentId: string, listener: SyncStateListener): () => void;
 export declare function connectClassicSync(server?: string): Promise<void>;
 export default function setupServiceWorker(options?: SetupServiceWorkerOptions): Promise<SetupServiceWorkerResult>;
+export {};

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,141 @@ 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 === "sync-state") {
+                dispatchSyncState(event.data);
+                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 });
+        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);
+}
+const syncStateListeners = new Map();
+function dispatchSyncState(update) {
+    const listeners = syncStateListeners.get(update.documentId);
+    if (!listeners)
+        return;
+    for (const listener of listeners) {
+        try {
+            listener(update);
+        }
+        catch (err) {
+            console.error("sync-state listener threw", err);
+        }
+    }
+}
+export function subscribeSyncState(documentId, listener) {
+    const worker = getAutomergeWorker();
+    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
+        active = false;
+        const set = syncStateListeners.get(documentId);
+        if (!set)
+            return;
+        set.delete(listener);
+        if (set.size === 0) {
+            syncStateListeners.delete(documentId);
+            worker.port.postMessage({ type: "sync-unsub", documentId });
+        }
+    };
+}
 export function connectClassicSync(server = readClassicSyncServer()) {
     const url = server.trim() || DEFAULT_CLASSIC_SYNC_SERVER;
     if (!/^wss?:\/\//.test(url)) {
@@ -155,11 +317,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,9 +349,18 @@ 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,
+        subscribeSyncState,
         async subscribeToRepoChannel(listener) {
             // The automerge worker outlives the page, so unlike the old in-service-
             // worker repo there's nothing to reconnect: one port, handed over once.

package/dist/site.d.ts

@@ -11,12 +11,12 @@
  * site's `main.ts`. Non-UI consumers should import the package default (which
  * only does SW registration and the automerge-worker handoff).
  */
-import { type DocHandle, Repo, type AutomergeUrl, type StorageId } from "@automerge/vanillajs/slim";
+import { type DocHandle, Repo, type AutomergeUrl } from "@automerge/vanillajs/slim";
 import { type AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
 import { type AccountDoc } from "@inkandswitch/patchwork-plugins";
 import * as plugins from "@inkandswitch/patchwork-plugins";
-import type { ServiceWorkerRepoChannelListener } from "./types.js";
+import type { ServiceWorkerRepoChannelListener, SyncStateDocMessage } from "./types.js";
 declare global {
     interface Window {
         accountDocHandle: DocHandle<AccountDoc>;
@@ -30,9 +30,14 @@ declare global {
             packages: ModuleWatcher;
             plugins: typeof plugins;
             accountDocHandle: DocHandle<AccountDoc>;
+            signer?: {
+                peerId: string;
+                verifyingKey: string;
+            };
             sw: {
                 connectClassicSync: (server?: string) => Promise<void>;
                 subscribeToRepoChannel: (listener: ServiceWorkerRepoChannelListener) => Promise<() => void>;
+                subscribeSyncState: (documentId: string, listener: (update: SyncStateDocMessage) => void) => () => void;
             };
         };
         uncache: (match: string) => Promise<void>;
@@ -82,11 +87,6 @@ export interface SiteConfig {
      * Defaults to `"root"`.
      */
     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