@inkandswitch/patchwork-bootloader 0.3.2 → 0.4.1

package/dist/site.js

@@ -11,7 +11,7 @@
  * site's `main.ts`. Non-UI consumers should import the package default (which
  * only does SW registration and the automerge-worker handoff).
  */
-import { initializeWasm, isValidAutomergeUrl, isValidDocumentId, MessageChannelNetworkAdapter, parseAutomergeUrl, Repo, stringifyAutomergeUrl, } from "@automerge/vanillajs/slim";
+import { initializeWasm, isValidAutomergeUrl, isValidDocumentId, MessageChannelNetworkAdapter, Repo, stringifyAutomergeUrl, } 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";
@@ -31,8 +31,11 @@ import * as plugins from "@inkandswitch/patchwork-plugins";
 import setupServiceWorker, { lifecycleLoggingEnabled, } from "./setup.js";
 import debug from "debug";
 const log = debug("patchwork:bootloader:site");
-// 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>\?=[^&?]+)?/;
+// Legacy big-patchwork hash shape: `<slug>--<documentId>[?…]`. The slug can
+// contain characters we don't otherwise permit (e.g. `drawing-(branch-1)`), so
+// we anchor on the `--` before the base58 document id and allow any non-query
+// characters ahead of it rather than a strict slug charset.
+const BIG_PATCHWORK_HASH_REGEX = /^(?<title>[^=&?/#]*)--(?<docId>[1-9A-HJ-NP-Za-km-z]+)/;
 const [automergeWasm, subductionWasm] = await Promise.all([
     fetch("/automerge.wasm?main").then((r) => r.bytes()),
     fetch("/subduction.wasm").then((r) => r.bytes()),
@@ -182,7 +185,6 @@ export async function bootPatchworkSite(config) {
         rootElement,
         repo,
         accountDocHandle,
-        moduleWatcher,
         titleSuffix: config.titleSuffix,
     });
     return { repo, moduleWatcher, accountDocHandle };
@@ -397,12 +399,12 @@ async function uncache(match) {
         }
     }
 }
-// Keys whose values are automerge URLs — we keep the `:` (and any `#`/`|`
-// heads) literal rather than percent-encoding them so links stay readable.
-const RAW_HASH_KEYS = new Set(["doc", "package"]);
-// Emit hash params in a stable order so re-serializing the same logical
-// params yields a byte-identical string (avoids spurious `hashchange`).
-const HASH_KEY_ORDER = ["doc", "package", "tool", "type", "title", "frame"];
+// The `doc=` value is an automerge URL — we keep its `:` (and any `#`/`|`
+// heads) literal rather than percent-encoding it so links stay readable.
+const RAW_HASH_KEYS = new Set(["doc"]);
+// Emit hash params in a stable order so re-serializing the same logical params
+// yields a byte-identical string (avoids spurious `hashchange` round-trips).
+const HASH_KEY_ORDER = ["doc", "tool", "type", "title", "frame"];
 function serializeHashParams(params) {
     const emitted = new Set();
     const parts = [];
@@ -423,14 +425,15 @@ function serializeHashParams(params) {
 }
 /**
  * Coerce a `doc=` hash param to a full automerge URL. Accepts a full URL
- * (`automerge:<id>[#heads]`) or a bare document id for backwards
- * compatibility with older links.
+ * (`automerge:<id>[#heads]`) or a bare document id for backwards compatibility
+ * with older links.
  */
 function docParamToUrl(docParam) {
     if (!docParam)
         return undefined;
-    if (isValidAutomergeUrl(docParam))
+    if (isValidAutomergeUrl(docParam)) {
         return docParam;
+    }
     const documentId = docParam.replace(/^automerge:/, "");
     if (isValidDocumentId(documentId)) {
         return stringifyAutomergeUrl({ documentId: documentId });
@@ -438,12 +441,12 @@ function docParamToUrl(docParam) {
     return undefined;
 }
 function installHashRouting(params) {
-    const { rootElement, repo, accountDocHandle, moduleWatcher, titleSuffix } = params;
+    const { rootElement, repo, accountDocHandle, titleSuffix } = params;
     rootElement.addEventListener("patchwork:open-document", async (event) => {
         const params = new URLSearchParams(window.location.hash.slice(1));
         const { url, toolId, type, title } = event.detail;
-        // `doc` is now the full automerge URL (heads, if any, live in it). The
-        // in-use package is recorded separately in `package=` when a tool mounts.
+        // `doc` is now the full automerge URL — heads, if any, live inside it, so
+        // the separate `heads=` param is gone.
         params.delete("heads");
         params.set("doc", url);
         if (toolId)
@@ -478,29 +481,6 @@ function installHashRouting(params) {
             console.error("Failed to update document title", e);
         }
     });
-    // When a tool mounts we know the package actually rendering the top-level
-    // document, so record its (heads-pinned) importUrl in `package=`.
-    const recordInUsePackage = (event) => {
-        const detail = event.detail;
-        if (!detail || !("url" in detail) || !detail.importUrl)
-            return;
-        const params = new URLSearchParams(window.location.hash.slice(1));
-        const docUrl = docParamToUrl(params.get("doc"));
-        if (!docUrl)
-            return;
-        // Ignore nested branch / side-by-side views: only the top-level doc's
-        // package belongs in the hash.
-        if (parseAutomergeUrl(docUrl).documentId !==
-            parseAutomergeUrl(detail.url).documentId) {
-            return;
-        }
-        if (params.get("package") === detail.importUrl)
-            return;
-        params.set("package", detail.importUrl);
-        // Replace rather than push: recording the in-use package shouldn't add a
-        // back-button entry (and replaceState avoids a `hashchange` round-trip).
-        history.replaceState(null, "", `#${serializeHashParams(params)}`);
-    };
     let firstMount = true;
     const reveal = () => {
         if (!firstMount)
@@ -510,7 +490,6 @@ function installHashRouting(params) {
         hideLoadingAnimation();
     };
     rootElement.addEventListener("patchwork:mounted", (event) => {
-        recordInUsePackage(event);
         handleHashChange();
         if (event.target !== rootElement)
             return;
@@ -525,12 +504,14 @@ function installHashRouting(params) {
     setTimeout(reveal, 12_000);
     const handleHashChange = async () => {
         const hash = window.location.hash.slice(1);
-        const legacy = BIG_PATCHWORK_HASH_REGEX.exec(hash);
-        if (legacy) {
-            const documentId = legacy.groups?.docId;
-            if (isValidDocumentId(documentId)) {
-                openDocument(rootElement, stringifyAutomergeUrl({ documentId }));
-            }
+        // Legacy big-patchwork link (`<slug>--<docId>?…`): if the hash carries a
+        // `--` followed by a valid document id, normalize it to the canonical
+        // `#doc=automerge:<docId>` form and let routing re-run on the hashchange.
+        const legacyDocId = BIG_PATCHWORK_HASH_REGEX.exec(hash)?.groups?.docId;
+        if (legacyDocId && isValidDocumentId(legacyDocId)) {
+            window.location.hash = serializeHashParams(new URLSearchParams({
+                doc: stringifyAutomergeUrl({ documentId: legacyDocId }),
+            }));
             return;
         }
         // Bare automerge URL in hash: /#automerge:<documentId>
@@ -542,16 +523,10 @@ function installHashRouting(params) {
         }
         const params = new URLSearchParams(hash);
         const docUrl = docParamToUrl(params.get("doc"));
-        const packageUrl = params.get("package");
         const toolId = params.get("tool");
         const title = params.get("title");
         const type = params.get("type");
         const frame = params.get("frame");
-        // Load the package that produced this document so its tool is available
-        // even when it isn't in the user's module settings.
-        if (packageUrl) {
-            void moduleWatcher.loadModules([packageUrl]);
-        }
         if (frame) {
             const frameDocUrl = docUrl ?? accountDocHandle.url;
             if (rootElement.getAttribute("tool-id") !== frame ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkandswitch/patchwork-bootloader",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "author": "chee",
   "type": "module",
   "license": "MIT",
@@ -44,29 +44,29 @@
     }
   },
   "dependencies": {
-    "@automerge/automerge": "3.3.0-fragments.1",
-    "@automerge/automerge-repo": "2.6.0-subduction.39",
-    "@automerge/automerge-repo-network-messagechannel": "2.6.0-subduction.39",
-    "@automerge/automerge-repo-network-websocket": "2.6.0-subduction.39",
-    "@automerge/automerge-repo-storage-indexeddb": "2.6.0-subduction.39",
+    "@automerge/automerge": "3.3.2",
+    "@automerge/automerge-repo": "2.6.0-subduction.46",
+    "@automerge/automerge-repo-network-messagechannel": "2.6.0-subduction.45",
+    "@automerge/automerge-repo-network-websocket": "2.6.0-subduction.45",
+    "@automerge/automerge-repo-storage-indexeddb": "2.6.0-subduction.45",
     "@automerge/automerge-subduction": "0.16.0",
-    "@automerge/vanillajs": "2.6.0-subduction.39",
+    "@automerge/vanillajs": "2.6.0-subduction.45",
     "@keyhive/keyhive": "0.1.0-alpha.5",
     "@types/debug": "^4.1.13",
     "debug": "^4.4.3",
     "resolve.exports": "^2.0.3",
     "service-worker-types": "npm:@types/serviceworker@^0.0.153",
     "tinyargs": "^0.1.4",
-    "@inkandswitch/patchwork-elements": "^2.0.0",
-    "@inkandswitch/patchwork-filesystem": "^0.1.1",
-    "@inkandswitch/patchwork-plugins": "^0.0.11",
-    "@inkandswitch/patchwork-providers": "^0.3.0"
+    "@inkandswitch/patchwork-elements": "^3.0.0",
+    "@inkandswitch/patchwork-filesystem": "^0.1.3",
+    "@inkandswitch/patchwork-providers": "^0.4.0",
+    "@inkandswitch/patchwork-plugins": "^0.0.11"
   },
   "peerDependencies": {
-    "@automerge/automerge": "3.3.0-fragments.1",
-    "@automerge/automerge-repo": "2.6.0-subduction.39",
+    "@automerge/automerge": "3.3.2",
+    "@automerge/automerge-repo": "2.6.0-subduction.46",
     "@automerge/automerge-repo-keyhive": "0.3.0-alpha.sub.8b",
-    "@automerge/vanillajs": "2.6.0-subduction.39"
+    "@automerge/vanillajs": "2.6.0-subduction.45"
   },
   "scripts": {
     "build": "tsc",

package/src/automerge-worker.ts

@@ -18,9 +18,11 @@ import { initializeWasm, hasHeads } from "@automerge/automerge/slim";
 // @ts-ignore — initSync is a wasm-bindgen runtime helper not in the .d.ts
 import { initSync as initSubductionSync } from "@automerge/automerge-subduction/slim";
 import { WebCryptoSigner } from "@automerge/automerge-subduction/slim";
+import { makePortProvider } from "@automerge/automerge-repo/worker-port";
 
 import {
   Repo,
+  WorkerWebSocketEndpoint,
   isValidAutomergeUrl,
   parseAutomergeUrl,
   stringifyAutomergeUrl,
@@ -73,6 +75,35 @@ const WORKER_BOOT_TIME = Date.now();
 
 const controlPorts = new Set<MessagePort>();
 
+// ── Keepalive-drift probe (bench instrumentation) ───────────────────────
+// Measures how late a 1s timer fires on this thread — i.e. how late an
+// in-thread keepalive would be under sync/wasm load. Cheap (one Date.now()
+// per second); samples are batched to every connected tab as drift-samples
+// messages, which setup.ts accumulates on window.__driftSamples for the
+// Playwright bench (e2e/tests/bench-ws.spec.ts).
+const DRIFT_INTERVAL_MS = 1_000;
+const DRIFT_BATCH_SIZE = 5;
+{
+  let expected = Date.now() + DRIFT_INTERVAL_MS;
+  let batch: number[] = [];
+  setInterval(() => {
+    const now = Date.now();
+    batch.push(Math.max(0, now - expected));
+    expected = now + DRIFT_INTERVAL_MS;
+    if (batch.length >= DRIFT_BATCH_SIZE) {
+      const samples = batch;
+      batch = [];
+      for (const port of controlPorts) {
+        try {
+          port.postMessage({ type: "drift-samples", samples });
+        } catch {
+          // Port torn down mid-iteration — its close handler cleans up.
+        }
+      }
+    }
+  }, DRIFT_INTERVAL_MS);
+}
+
 // ── Per-tab sync-state subscriptions ────────────────────────────────────
 // Each tab's control port subscribes to the documents it cares about; we push
 // only those docs' heads back down that port (addressed — tab A never sees tab
@@ -211,11 +242,55 @@ if (useKeyhiveSyncServer) {
   };
 }
 
-const SUBDUCTION_ENDPOINTS = [
-  useKeyhiveSyncServer
-    ? "wss://keyhive.sync.automerge.org"
-    : "wss://subduction.sync.inkandswitch.com",
-];
+const SUBDUCTION_SYNC_URL = useKeyhiveSyncServer
+  ? "wss://keyhive.sync.automerge.org"
+  : "wss://subduction.sync.inkandswitch.com";
+
+// The subduction WebSocket lives in its own worker so socket I/O (and
+// keepalive pongs) keep flowing even when this SharedWorker's thread is busy
+// syncing. We can't spawn that worker ourselves — Chrome doesn't expose the
+// Worker constructor inside SharedWorkerGlobalScope — so tabs spawn the
+// shipped SharedWorker proxy entry and donate its port to us (donatePort in
+// setup.ts). The provider hands WorkerWebSocketEndpoint whichever port is
+// current, healing across late arrival and proxy-worker restarts.
+const subductionPortProvider = makePortProvider();
+
+// A/B bench toggle: the tab appends ?ws-mode=inline to our URL (SharedWorker
+// scope has no localStorage; see getAutomergeWorker in setup.ts). "inline"
+// passes the bare URL string so the socket lives on this thread — the
+// pre-worker behaviour — as the control arm for benchmarking the
+// worker-based endpoint. Default: "worker".
+const WS_MODE =
+  new URL(self.location.href).searchParams.get("ws-mode") === "inline"
+    ? "inline"
+    : "worker";
+
+// Optional windowFrames override (bench knob — max un-acked frames the io
+// proxy delivers before pausing; endpoint default is 128).
+const WS_WINDOW_FRAMES =
+  Number(new URL(self.location.href).searchParams.get("ws-window")) ||
+  undefined;
+
+// Memoized so a repo-construction retry (getRepoHive clears its promise on
+// failure) reuses the same endpoint instead of leaking one per attempt.
+let subductionEndpoints: (WorkerWebSocketEndpoint | string)[] | null = null;
+function getSubductionEndpoints(): (WorkerWebSocketEndpoint | string)[] {
+  if (!subductionEndpoints) {
+    log(`subduction websocket mode: ${WS_MODE}`);
+    subductionEndpoints =
+      WS_MODE === "inline"
+        ? [SUBDUCTION_SYNC_URL]
+        : [
+            new WorkerWebSocketEndpoint(SUBDUCTION_SYNC_URL, {
+              worker: subductionPortProvider.source,
+              ...(WS_WINDOW_FRAMES
+                ? { windowFrames: WS_WINDOW_FRAMES }
+                : {}),
+            }),
+          ];
+  }
+  return subductionEndpoints;
+}
 const RESOLVE_TIMEOUT_MS = 30_000;
 
 // Backoff re-sync of stuck/diverged docs. Only this worker is connected to the
@@ -310,8 +385,6 @@ function getRepoHive() {
             }
           ).toHex(),
         };
-        console.log("[patchwork] shared-worker subduction identity:", identity);
-
         const repo = new Repo({
           storage: new IndexedDBWorkerStorageAdapter(),
           signer,
@@ -323,9 +396,16 @@ function getRepoHive() {
             return peerId.includes("storage-server");
           },
           enableRemoteHeadsGossiping: true,
-          subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
+          subductionWebsocketEndpoints: getSubductionEndpoints(),
         });
 
+        console.log(
+          "[patchwork] shared-worker subduction identity:",
+          identity,
+          "networkSubsystem.adapters:",
+          repo.networkSubsystem.adapters.length
+        );
+
         (self as any).repo = repo;
         (self as any).syncIdentity = identity;
         setupSyncStateBroadcast(repo, identity);
@@ -354,7 +434,7 @@ function getRepoHive() {
         ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
         repo: {
           storage: new IndexedDBWorkerStorageAdapter(),
-          subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
+          subductionWebsocketEndpoints: getSubductionEndpoints(),
           enableRemoteHeadsGossiping: true,
         },
       });
@@ -717,10 +797,14 @@ function dropRepoChannel(repo: Repo, channel: RepoChannel) {
   // wrapper: make sure the underlying port is disconnected and closed too.
   try {
     channel.mcAdapter.disconnect();
-  } catch {}
+  } catch {
+    // Already disconnected by removeNetworkAdapter above.
+  }
   try {
     channel.port.close();
-  } catch {}
+  } catch {
+    // Port already closed by the departing tab.
+  }
 }
 
 async function dropConnection(connection: Connection) {
@@ -851,6 +935,11 @@ self.addEventListener("connect", (event) => {
     handleControlMessage(messageEvent as MessageEvent, controlPort, connection);
   });
 
+  // Let the subduction port provider negotiate over this tab's control port
+  // (the tab side runs donatePort; the messages are channel-tagged so they
+  // coexist with our control protocol above).
+  subductionPortProvider.attachClient(controlPort);
+
   // Fires when the owning page is destroyed. Browsers without the close
   // event fall back to the adapters' lazy useWeakRef cleanup.
   controlPort.addEventListener("close", () => {
@@ -975,11 +1064,10 @@ async function resolveAutomergeUrl(automergeURL: URL): Promise<Response> {
       ? (new Uint8Array(resolved.content) as BlobPart)
       : resolved.content;
 
-  const headers = new Headers({ "content-type": resolved.type });
-  headers.set("cross-origin-embedder-policy", "credentialless");
-  headers.set("cross-origin-resource-policy", "cross-origin");
-
-  return new Response(body, { status: 200, headers });
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": resolved.type },
+  });
 }
 
 // ── Handoff: resolve special URLs for the service worker ──────────────

package/src/externals.ts

@@ -6,6 +6,11 @@ const externals = [
   "@automerge/automerge/slim",
   "@automerge/automerge-repo",
   "@automerge/automerge-repo/slim",
+  // Port-donation plumbing for WorkerWebSocketEndpoint: tabs spawn the shared
+  // proxy entry and donate its port to the automerge worker (Chrome can't
+  // spawn workers from inside a SharedWorker). See setup.ts/automerge-worker.ts.
+  "@automerge/automerge-repo/worker-port",
+  "@automerge/automerge-repo/subduction-websocket-worker-shared",
   "@automerge/automerge-repo-network-messagechannel",
   "@automerge/automerge-repo-network-websocket",
   "@automerge/automerge-repo-storage-indexeddb",
@@ -24,6 +29,7 @@ const externals = [
   "@codemirror/state",
   "@codemirror/view",
   "@codemirror/language",
+  "@codemirror/commands",
 
   // rip
   "solid-js",

package/src/service-worker.ts

@@ -13,10 +13,13 @@ import {
   type HandoffRequestMessage,
 } from "./types.js";
 
-let cachename = "default";
+const DEFAULT_CACHE_NAME = "patchwork";
+
+let cachename = DEFAULT_CACHE_NAME;
 let debugging = false;
 
-const cacheableStatuses = [200, 203, 204];
+// 0 is an opaque response, that also needs cached
+const cacheableStatuses = [0, 200, 203, 204];
 
 // The automerge worker times its own resolution out after 30s and replies
 // with an error, so this only fires when nobody is listening at all.
@@ -82,22 +85,19 @@ self.addEventListener("install", (event) => {
   (event as ExtendableEvent).waitUntil(self.skipWaiting());
 });
 
-async function clearOldCaches() {
-  const cacheWhitelist = [cachename];
-  const cacheNames = await caches.keys();
-  const deletePromises = cacheNames.map((cacheName) => {
-    if (!cacheWhitelist.includes(cacheName)) {
-      return caches.delete(cacheName);
-    }
-  });
-  await Promise.all(deletePromises);
+async function clearOtherCaches() {
+  await Promise.all(
+    (await caches.keys()).map((cacheName) => {
+      if (cacheName !== cachename) return caches.delete(cacheName);
+    })
+  );
 }
 
 self.addEventListener("activate", (event) => {
   lifecycle("info", "activate (claiming clients)");
   (event as ExtendableEvent).waitUntil(
     (async () => {
-      await clearOldCaches();
+      await clearOtherCaches();
       await self.clients.claim();
       // Pre-cache pages of already-open clients so they survive going offline
       // before the next navigation.
@@ -110,7 +110,7 @@ self.addEventListener("activate", (event) => {
             if (!existing) {
               const response = await fetch(client.url);
               if (cacheableStatuses.includes(response.status)) {
-                await cache.put(client.url, response);
+                await cachePage(cache, client.url, response);
               }
             }
           } catch {
@@ -128,11 +128,19 @@ self.addEventListener("message", async (event) => {
     if (cachename == nextCachename) {
       return;
     }
-    console.info(
-      `deleting ${cachename} and setting cache name to ${nextCachename}`
-    );
-    caches.delete(cachename);
+    console.info(`moving from cache ${cachename} to ${nextCachename}`);
+    if (cachename === DEFAULT_CACHE_NAME) {
+      const defaultCache = await caches.open(cachename);
+      const nextCache = await caches.open(nextCachename);
+      await Promise.all(
+        (await defaultCache.keys()).map(async (request) => {
+          const response = await defaultCache.match(request);
+          if (response) await nextCache.put(request, response);
+        })
+      );
+    }
     cachename = nextCachename;
+    await clearOtherCaches();
   } else if (event.data.type == "debug") {
     debugging = event.data.debug;
     log("serviceworker debugging enabled");
@@ -216,20 +224,47 @@ function handoff(
   });
 }
 
-function withSpecialHeaders(response: {
+function makeResponse(response: {
   body?: BodyInit | ReadableStream<Uint8Array> | null;
   status?: number;
   headers?: HeadersInit;
 }): Response {
-  const headers = new Headers(response.headers);
-  headers.set("cross-origin-embedder-policy", "credentialless");
-  headers.set("cross-origin-resource-policy", "cross-origin");
   return new Response(response.body ?? null, {
     status: response.status ?? 200,
-    headers,
+    headers: response.headers,
   });
 }
 
+function indexRequestFor(request: Request | string): Request | undefined {
+  const url = new URL(typeof request === "string" ? request : request.url);
+  if (url.origin !== self.location.origin) return undefined;
+  url.pathname = "/index.html";
+  url.search = "";
+  url.hash = "";
+  return new Request(url.href);
+}
+
+function rootRequestFor(request: Request | string): Request | undefined {
+  const url = new URL(typeof request === "string" ? request : request.url);
+  if (url.origin !== self.location.origin) return undefined;
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return new Request(url.href);
+}
+
+async function cachePage(
+  cache: Cache,
+  request: Request | string,
+  response: Response
+) {
+  const indexRequest = indexRequestFor(request);
+  if (indexRequest) await cache.put(indexRequest, response.clone());
+  const rootRequest = rootRequestFor(request);
+  if (rootRequest) await cache.put(rootRequest, response.clone());
+  await cache.put(request, response);
+}
+
 // ── Fetch handler ──────────────────────────────────────────────────────
 
 self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
@@ -260,7 +295,7 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
         if (handoffURL) {
           if (match) {
             log(`serving ${handoffURL} from cache ${cachename}`);
-            return withSpecialHeaders(match);
+            return match;
           }
 
           log(`handing ${handoffURL} off to the automerge worker`);
@@ -271,7 +306,7 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
           if (reply.type === "response") {
             // errors, redirects and other things that shouldn't be cached
             log(`serving handed-off response for ${handoffURL}`, reply);
-            return withSpecialHeaders(reply.response);
+            return makeResponse(reply.response);
           }
 
           // reply.type === "cached": the automerge worker has put the
@@ -284,26 +319,51 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
             );
           }
           log(`serving ${handoffURL} from cache ${cachename} after handoff`);
-          return withSpecialHeaders(cached);
+          return cached;
         } else {
-          const response = await fetch(request).catch(() => null);
-          if (response) {
+          // fetch() rejects on network error / abort rather than resolving;
+          // keep the error so we can surface it in the 503 body below.
+          const result = await fetch(request).catch((error: unknown) =>
+            error instanceof Error ? error : new Error(String(error))
+          );
+          if (result instanceof Response) {
+            const response = result;
+            // Tool subresources (<link>/<script>) are requested from srcdoc
+            // frames whose origin is "null", so they come back as opaque
+            // cross-origin `no-cors` responses: status 0 and an empty url. They
+            // render fine while online but were being excluded from the cache,
+            // so e.g. a theme stylesheet vanished on an offline refresh. Opaque
+            // responses are cacheable and replay to the same no-cors consumer,
+            // so treat status 0 as cacheable and gate the scheme on request.url
+            // (an opaque response's own url is "").
             if (
-              cacheableStatuses.includes(response.status) &&
-              response.url.match(/^https?\:/)
+              (response.status === 0 ||
+                cacheableStatuses.includes(response.status)) &&
+              /^https?:/.test(request.url)
             ) {
-              await cache.put(request, response.clone()).catch((error) => {
+              const cachedResponse = response.clone();
+              await (
+                request.mode === "navigate" ||
+                request.destination === "document"
+                  ? cachePage(cache, request, cachedResponse)
+                  : cache.put(request, cachedResponse)
+              ).catch((error) => {
                 log(`error caching ${request.url} in ${cachename}`, error);
               });
             } else {
               log(
-                `skipping uncacheable response code from cache: ${response.status} for ${response.url}`
+                `skipping uncacheable response code from cache: ${response.status} for ${request.url}`
               );
             }
             return response;
           }
           if (match) return match;
-          return new Response("couldnt fetch and no stale", { status: 503 });
+          return new Response(
+            `couldnt fetch ${request.url} and no stale copy in ${cachename}\n\n${
+              result.stack ?? result.message
+            }`,
+            { status: 503, headers: { "content-type": "text/plain" } }
+          );
         }
       } catch (error) {
         const message =