@inkandswitch/patchwork-bootloader 0.3.0 → 0.3.2

package/src/module-loader-worker.ts

@@ -0,0 +1,68 @@
+// 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";
+import type { AutomergeUrl } from "@automerge/automerge-repo/slim";
+
+type DiscoverRequest = {
+  type: "discover";
+  id: number;
+  url: AutomergeUrl;
+};
+
+// 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: any): Record<string, unknown> {
+  if (!plugin || typeof plugin !== "object") return {};
+  const { load, import: _import, module, ...description } = plugin;
+  return description;
+}
+
+function isDiscoverRequest(data: unknown): data is DiscoverRequest {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as any).type === "discover" &&
+    typeof (data as any).id === "number" &&
+    typeof (data as any).url === "string"
+  );
+}
+
+self.addEventListener("message", (event: MessageEvent) => {
+  const data = event.data;
+  if (!isDiscoverRequest(data)) return;
+  const { id, url } = data;
+
+  importModuleFromFolderDocUrl(url)
+    .then((mod) => {
+      const plugins: any[] = Array.isArray(mod?.plugins) ? mod.plugins : [];
+      const descriptors = plugins.map(toDescriptor);
+      (self as unknown as Worker).postMessage({
+        type: "descriptors",
+        id,
+        descriptors,
+      });
+    })
+    .catch((error) => {
+      (self as unknown as Worker).postMessage({
+        type: "error",
+        id,
+        error:
+          error instanceof Error
+            ? (error.stack ?? error.message)
+            : String(error),
+      });
+    });
+});

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

@@ -2,6 +2,7 @@ import type {
   ServiceWorkerRepoChannelListener,
   SetupServiceWorkerOptions,
   SetupServiceWorkerResult,
+  SyncStateDocMessage,
 } from "./types.js";
 import {
   readClassicSyncServer,
@@ -12,6 +13,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 +96,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 +105,158 @@ 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 === "sync-state") {
+        dispatchSyncState(event.data as SyncStateDocMessage);
+        return;
+      }
+      if (event.data?.type !== "console") return;
+      const { level, args } = event.data;
+      // Gate forwarded [lifecycle] logs on the toggle too.
+      if (
+        !lifecycleLoggingEnabled() &&
+        typeof args?.[0] === "string" &&
+        args[0].includes("[lifecycle]")
+      ) {
+        return;
+      }
+      const fn = (console as any)[level] ?? console.log;
+      // The worker's logs (debug library, the worker's own log()) carry %c
+      // format directives in args[0] with CSS in the following args. Prefix
+      // the tag into the format string rather than as a separate positional,
+      // or the %c would no longer be in arg 0 and the CSS would print raw.
+      if (typeof args[0] === "string") {
+        fn(`[automerge-worker] ${args[0]}`, ...args.slice(1));
+      } else {
+        fn("[automerge-worker]", ...args);
+      }
+    });
     automergeWorker.port.postMessage({ type: "debug", debug: workerDebugging });
+
+    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);
+}
+
+// ── Sync-state subscriptions ────────────────────────────────────────────
+// The automerge worker pushes per-document heads only to the tabs that ask for
+// them (see SyncStateDocMessage). We ref-count locally so several callers in
+// this tab can watch the same doc with a single worker subscription, and tear
+// the worker subscription down when the last local watcher drops.
+type SyncStateListener = (update: SyncStateDocMessage) => void;
+const syncStateListeners = new Map<string, Set<SyncStateListener>>();
+
+function dispatchSyncState(update: SyncStateDocMessage): void {
+  const listeners = syncStateListeners.get(update.documentId);
+  if (!listeners) return;
+  for (const listener of listeners) {
+    try {
+      listener(update);
+    } catch (err) {
+      console.error("sync-state listener threw", err);
+    }
+  }
+}
+
+export function subscribeSyncState(
+  documentId: string,
+  listener: SyncStateListener
+): () => void {
+  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: string = readClassicSyncServer()
 ): Promise<void> {
@@ -104,11 +280,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 +360,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,9 +407,19 @@ export default async function setupServiceWorker(
     "background: #fcf2f0; color: #333; border: 2px solid; border-radius: 4px"
   );
 
+  // todon't
+  (window as any).killsw = () => {
+    if (automergeWorker) {
+      automergeWorker.port.close();
+      automergeWorker = undefined;
+    }
+  };
+
   return {
+    shared,
     connectClassicSync,
     getRepoChannel,
+    subscribeSyncState,
     async subscribeToRepoChannel(listener: ServiceWorkerRepoChannelListener) {
       // The automerge worker outlives the page, so unlike the old in-service-
       // worker repo there's nothing to reconnect: one port, handed over once.