@inkandswitch/patchwork-bootloader 0.4.1 → 0.4.3

package/dist/setup.js

@@ -70,12 +70,82 @@ function configureServiceWorker(sw) {
 }
 // ── The automerge worker ───────────────────────────────────────────────
 // The automerge repo lives in a SharedWorker (not the service worker). One
-// instance is shared by every tab and lives exactly as long as any tab
-// does, so there's no keepalive ping and no restart detection: if we're
-// alive, it's alive. Repo sync ports are passed to it over its connect
-// port; it talks to the service worker over a BroadcastChannel.
+// instance is shared by every tab and normally lives as long as any tab
+// does — but browsers do reap SharedWorkers under memory pressure, so we
+// heartbeat it and rebuild everything if it dies (see
+// recoverAutomergeWorker). Repo sync ports are passed to it over its
+// connect port; it talks to the service worker over a BroadcastChannel.
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker;
+// Bumped whenever a new SharedWorker is constructed. A repo port opened
+// against instance N is stale once instance N+1 exists (its channel ends in
+// a dead worker), so deliveries are guarded on the generation they started in.
+let workerGeneration = 0;
+// Tears down the current worker's heartbeat when it's replaced.
+let disposeWorkerDeathDetection;
+// Every subscribeToRepoChannel listener, kept so a recovered worker can hand
+// each subscriber a fresh repo port.
+const repoChannelListeners = new Set();
+let recoveringWorker = false;
+let lastWorkerRecoveryAt = 0;
+// Below this spacing, skip: if the fresh worker is dead too, its own
+// heartbeat re-triggers recovery later rather than spinning in a tight loop.
+const RECOVERY_MIN_INTERVAL_MS = 15_000;
+/**
+ * The automerge SharedWorker died (browser reaped it, or it crashed): build a
+ * replacement and re-wire everything a live tab holds against it — console
+ * forwarding and the io-proxy port donation (both re-done by
+ * getAutomergeWorker), the per-doc sync-state subscriptions, and every
+ * subscriber's repo sync port. The new instance boots with cold state; its
+ * repo is reconstructed on the first port we send.
+ */
+async function recoverAutomergeWorker(reason, deadWorker) {
+    if (deadWorker !== automergeWorker)
+        return; // already replaced
+    if (recoveringWorker)
+        return;
+    const now = Date.now();
+    if (now - lastWorkerRecoveryAt < RECOVERY_MIN_INTERVAL_MS)
+        return;
+    recoveringWorker = true;
+    lastWorkerRecoveryAt = now;
+    console.warn(`[lifecycle] ${new Date().toISOString()} recreating the automerge ` +
+        `SharedWorker (${reason})`);
+    try {
+        disposeWorkerDeathDetection?.();
+        disposeWorkerDeathDetection = undefined;
+        automergeWorker = undefined;
+        try {
+            deadWorker.port.close();
+        }
+        catch {
+            // Port already dead.
+        }
+        const fresh = getAutomergeWorker();
+        // The fresh instance knows nothing — replay every doc subscription.
+        for (const documentId of syncStateListeners.keys()) {
+            fresh.port.postMessage({ type: "sync-sub", documentId });
+        }
+        // Hand every repo-channel subscriber a fresh port so their repos sync
+        // again (the old adapters sit on dead MessagePorts).
+        for (const listener of repoChannelListeners) {
+            try {
+                const generation = workerGeneration;
+                const port = await openRepoChannel();
+                // Replaced again while we waited — the newer recovery re-delivers.
+                if (generation !== workerGeneration)
+                    break;
+                await listener(port);
+            }
+            catch (err) {
+                console.error("failed to re-wire a repo channel after worker recovery", err);
+            }
+        }
+    }
+    finally {
+        recoveringWorker = false;
+    }
+}
 // SharedWorker proxy entry that owns the subduction WebSocket. Chrome can't
 // spawn workers from inside a SharedWorker, so each tab offers this proxy's
 // port to the automerge worker (which requests one via its port provider).
@@ -107,13 +177,23 @@ function workerBenchParams() {
     const qs = params.toString();
     return qs ? `?${qs}` : "";
 }
+function automergeWorkerUrl() {
+    return `${automergeWorkerPath}${workerBenchParams()}`;
+}
 export function getAutomergeWorker() {
     if (!automergeWorker) {
-        const workerUrl = `${automergeWorkerPath}${workerBenchParams()}`;
-        automergeWorker = new SharedWorker(workerUrl, {
+        workerGeneration++;
+        automergeWorker = new SharedWorker(automergeWorkerUrl(), {
             name: "patchwork-automerge",
             type: "module",
         });
+        // Fired when a message arrives that can't be structured-deserialized —
+        // e.g. a transfer list that named something unclonable. Silent otherwise:
+        // the message is simply dropped, which looks identical to a worker that
+        // never replied. Always loud, not gated on the lifecycle toggle.
+        automergeWorker.port.addEventListener("messageerror", (event) => {
+            console.error("[automerge-worker] undeserializable message from worker:", event);
+        });
         // Control replies (port-ready &c) come back on this port, so it needs
         // start() — we listen with addEventListener, not onmessage.
         automergeWorker.port.start();
@@ -169,16 +249,37 @@ export function getAutomergeWorker() {
                 type: "module",
                 name: "subduction-websocket",
             });
+            // This worker carries the websocket to the sync server, so if it fails
+            // to load, sync silently stops with no other symptom.
+            io.addEventListener("error", (event) => {
+                const error = event;
+                console.error(`[subduction-io] failed to load/run ${SUBDUCTION_IO_WORKER_URL}:`, error.message || event, error.filename ? `(${error.filename}:${error.lineno})` : "");
+            });
+            io.port.addEventListener("messageerror", (event) => {
+                console.error("[subduction-io] undeserializable message:", event);
+            });
             return io.port;
         });
-        installWorkerDeathDetection(automergeWorker);
+        disposeWorkerDeathDetection = 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.
+ * Detect when the automerge SharedWorker dies or its control port goes deaf.
+ *
+ * Silence alone is NOT proof of death: the worker may still be evaluating its
+ * (large) module graph on a cold boot, or its single thread may be busy with
+ * wasm/sync work — in both cases every queued message (including the repo
+ * ports the network adapters ride on) is delivered fine once it catches up,
+ * and tearing the port down would *lose* them. So silence only starts a
+ * non-destructive PROBE: a second SharedWorker connection to the same
+ * instance. Only when the probe gets a `hello` while this port stays silent do
+ * we know the instance is alive-and-responsive but our port is stranded (a
+ * failure mode observed in the wild) — or was replaced — and recovery is
+ * warranted. A `close` event (where supported) is a definitive death signal
+ * and recovers immediately. [lifecycle]-tagged. Returns a dispose that stops
+ * the heartbeat and any outstanding probe (called when this worker is
+ * replaced).
  */
 function installWorkerDeathDetection(worker) {
     const stamp = () => new Date().toISOString();
@@ -191,53 +292,135 @@ function installWorkerDeathDetection(worker) {
             console.info(`[lifecycle] ${stamp()} ${msg}`);
     };
     let instanceId;
-    let lastPongAt = Date.now();
+    let lastHeardAt = Date.now();
     let warnedUnresponsive = false;
+    let disposed = false;
+    let probe;
+    const closeProbe = () => {
+        if (!probe)
+            return;
+        try {
+            probe.port.close();
+        }
+        catch {
+            // Already closed.
+        }
+        probe = undefined;
+    };
+    let warnedSendFailed = false;
+    let pingsSent = 0;
     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;
-        }
+        lastHeardAt = Date.now();
+        warnedUnresponsive = false;
+        // The port spoke — any outstanding probe is moot.
+        closeProbe();
         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`);
+            warn(`automerge SharedWorker instance changed (instance ${data.instanceId}, ` +
+                `was ${instanceId})`);
             instanceId = data.instanceId;
         }
     });
     // Fires when the SharedWorker is destroyed (where supported).
     worker.port.addEventListener("close", () => {
-        warn("automerge SharedWorker control port CLOSED — worker terminated");
+        if (disposed)
+            return;
+        warn("automerge SharedWorker control port closed");
+        void recoverAutomergeWorker("control port closed", worker);
     });
+    // Not gated on the lifecycle toggle: a worker that fails to load never
+    // replies to anything, and this is the only signal that says so.
     worker.addEventListener("error", event => {
-        warn(`automerge SharedWorker error: ${event.message || event}`);
+        const error = event;
+        console.error(`[lifecycle] ${stamp()} automerge SharedWorker error:`, error.message || event, error.filename ? `(${error.filename}:${error.lineno})` : "");
     });
-    // 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;
+    // On probe hello, give the suspect port this long to also speak before
+    // concluding it's stranded: after a slow worker boot both connections hello
+    // at roughly the same moment and cross-port delivery order isn't guaranteed.
+    const PROBE_GRACE_MS = 500;
+    const startProbe = (reason) => {
+        if (probe || disposed)
+            return;
+        warn(`automerge SharedWorker ${reason}; probing with a second connection`);
+        const startedAt = Date.now();
+        const p = new SharedWorker(automergeWorkerUrl(), {
+            name: "patchwork-automerge",
+            type: "module",
+        });
+        probe = p;
+        p.port.start();
+        p.port.addEventListener("message", (event) => {
+            if (event.data?.type !== "hello")
+                return;
+            setTimeout(() => {
+                if (disposed || probe !== p)
+                    return; // superseded or torn down
+                closeProbe();
+                // The suspect spoke while (or just after) the probe ran: it was
+                // merely slow/busy, and everything queued on it has been delivered.
+                if (lastHeardAt >= startedAt)
+                    return;
+                void recoverAutomergeWorker(`port unresponsive on a live worker (${reason}; probe confirmed)`, worker);
+            }, PROBE_GRACE_MS);
+        });
+        // No hello on the probe means the instance is loading or busy (the probe
+        // waits indefinitely — its hello triggers the check above whenever it
+        // lands) — never tear anything down on a timer.
+    };
+    // A silent-too-long port while the tab is visible starts a probe (a miss
+    // while hidden is more likely suspension). Before first contact the budget
+    // is tighter: an idle worker hellos within milliseconds of connecting, so
+    // probing early costs nothing and rescues genuinely stranded boots fast.
+    const HEARTBEAT_MS = 5_000;
     const HEARTBEAT_TIMEOUT_MS = 25_000;
+    const FIRST_CONTACT_TIMEOUT_MS = 4_000;
     let seq = 0;
-    setInterval(() => {
+    const heartbeat = setInterval(() => {
         try {
             worker.port.postMessage({ type: "ping", id: ++seq });
+            pingsSent++;
         }
-        catch {
-            // Port already torn down — the "close" handler covers that case.
+        catch (error) {
+            // Swallowing this makes a failed send indistinguishable from a dead
+            // worker in the "no pong" warning below. Once, not every heartbeat.
+            if (!warnedSendFailed) {
+                warnedSendFailed = true;
+                console.error(`[lifecycle] ${stamp()} automerge SharedWorker ping send threw ` +
+                    `after ${pingsSent} sent:`, error);
+            }
         }
-        const silentMs = Date.now() - lastPongAt;
+        const neverHeard = instanceId === undefined;
+        const silentMs = Date.now() - lastHeardAt;
+        const timeoutMs = neverHeard
+            ? FIRST_CONTACT_TIMEOUT_MS
+            : HEARTBEAT_TIMEOUT_MS;
         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`);
+        // First contact probes regardless of visibility: SharedWorkers don't
+        // suspend with tab visibility, boots in background tabs must still get
+        // rescued, and the probe destroys nothing. Post-contact silence defers to
+        // visibility, since a hidden page's own throttling can fake it.
+        if (silentMs > timeoutMs && (neverHeard || visible)) {
+            const reason = neverHeard
+                ? `no hello ~${Math.round(silentMs / 1000)}s after connecting`
+                : `no pong for ~${Math.round(silentMs / 1000)}s`;
+            if (!warnedUnresponsive) {
+                warnedUnresponsive = true;
+                warn(`automerge SharedWorker ${reason} (tab visible)`);
+            }
+            startProbe(reason);
         }
     }, HEARTBEAT_MS);
+    return () => {
+        disposed = true;
+        clearInterval(heartbeat);
+        closeProbe();
+    };
 }
 const syncStateListeners = new Map();
 function dispatchSyncState(update) {
@@ -273,7 +456,10 @@ export function subscribeSyncState(documentId, listener) {
         set.delete(listener);
         if (set.size === 0) {
             syncStateListeners.delete(documentId);
-            worker.port.postMessage({ type: "sync-unsub", documentId });
+            // The worker may have been replaced since we subscribed (recovery
+            // replays subscriptions onto the new instance) — unsubscribe from
+            // whichever instance is current, not the one captured above.
+            automergeWorker?.port.postMessage({ type: "sync-unsub", documentId });
         }
     };
 }
@@ -375,6 +561,11 @@ export default async function setupServiceWorker(options) {
     // install / activate markers from the controlling worker are rendered here.
     installServiceWorkerLogForwarding();
     localStorage.removeItem(key);
+    // Ask for persistent storage so cache growth can't trip origin-wide
+    // eviction, which would take the Automerge IndexedDB — the user's documents
+    // — with it. Chrome/Safari decide silently from site engagement; Firefox may
+    // show a one-time prompt. Best-effort: denial just means default eviction.
+    void navigator.storage?.persist?.().catch(() => { });
     if (options?.workerPath)
         automergeWorkerPath = options.workerPath;
     // Start the automerge worker right away so it boots (wasm, repo) while the
@@ -417,10 +608,22 @@ export default async function setupServiceWorker(options) {
         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.
-            await listener(await openRepoChannel());
-            return () => { };
+            // Called once with the boot port. If the automerge worker later dies
+            // and is recreated (recoverAutomergeWorker), the listener is called
+            // again with a fresh port — treat every call as "(re)wire your repo's
+            // sync onto this port".
+            repoChannelListeners.add(listener);
+            const generation = workerGeneration;
+            const port = await openRepoChannel();
+            // If the worker was replaced while this channel was opening (e.g. the
+            // port-ready wait timed out against a stranded connection and recovery
+            // already delivered a good port to this listener), drop the stale one
+            // rather than wiring the repo to a dead channel.
+            if (generation === workerGeneration)
+                await listener(port);
+            return () => {
+                repoChannelListeners.delete(listener);
+            };
         },
     };
 }

package/dist/site.d.ts

@@ -61,7 +61,7 @@ export interface SiteConfig {
      * folder docs or plain HTTP(S) bundles, so deployment targets can be freely
      * mixed.
      *
-     * Can be overridden at runtime by setting `localStorage.defaultToolsUrl` to
+     * Can be overridden at runtime by setting `localStorage.systemPackageListURL` to
      * another `automerge:` URL or manifest URL — useful for local development
      * against an unpublished tool set.
      */

package/dist/site.js

@@ -20,15 +20,15 @@ import { initKeyhiveWasm, initializeAutomergeRepoKeyhiveWithRepo, } from "@autom
 // @ts-ignore — initSync is a wasm-bindgen runtime helper not in the .d.ts
 import { initSync as initSubductionSync } from "@automerge/automerge-subduction/slim";
 import { MemorySigner } from "@automerge/automerge-subduction/slim";
-const siteName = typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
+const siteName = typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "patchwork.inkandswitch.com";
 const useKeyhiveSyncServer = typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
-import { importAutomergeModuleViaWorker } from "./module-loader.js";
+import { importAutomergePackageViaWorker } from "./module-loader.js";
 import { openDocument, registerPatchworkViewElement, } from "@inkandswitch/patchwork-elements";
 import { registerRepoProviderElement } from "@inkandswitch/patchwork-providers";
 import { getRegistry, registerPlugins, resolveAccountHandle, unregisterPlugins, } from "@inkandswitch/patchwork-plugins";
 import * as plugins from "@inkandswitch/patchwork-plugins";
-import setupServiceWorker, { lifecycleLoggingEnabled, } from "./setup.js";
+import setupServiceWorker, { lifecycleLoggingEnabled } from "./setup.js";
 import debug from "debug";
 const log = debug("patchwork:bootloader:site");
 // Legacy big-patchwork hash shape: `<slug>--<documentId>[?…]`. The slug can
@@ -37,7 +37,7 @@ const log = debug("patchwork:bootloader:site");
 // 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("/automerge.wasm").then((r) => r.bytes()),
     fetch("/subduction.wasm").then((r) => r.bytes()),
 ]);
 /**
@@ -64,6 +64,9 @@ export async function bootPatchworkSite(config) {
     let hive;
     let repo;
     let tabSignerIdentity;
+    // Called with a fresh port when the automerge worker dies and is recreated
+    // (see recoverAutomergeWorker in setup.ts); assigned once the repo exists.
+    let onWorkerPortRenewed;
     // If a Repo is already on `window` — an embedding context provided one before
     // this entry ran — reuse it and its keyhive instead of standing up a fresh
     // realm-local Repo, so we share the same documents and sync/keyhive context.
@@ -76,14 +79,34 @@ export async function bootPatchworkSite(config) {
     else {
         // Get the initial automerge-worker port via subscribeToRepoChannel,
         // then pass it to keyhive init which wraps it in its own network adapter.
-        let resolvePort;
-        const portPromise = new Promise((r) => {
-            resolvePort = r;
+        // The listener is called again with a fresh port if the worker is ever
+        // recreated after dying.
+        let resolveFirstPort;
+        const firstPortPromise = new Promise((r) => {
+            resolveFirstPort = r;
         });
+        let seenFirstPort = false;
         log("subscribing to repo channel");
-        await sw.subscribeToRepoChannel(resolvePort);
+        // Deliberately not awaited: subscribeToRepoChannel resolves only after
+        // the boot channel's port-ready handshake, which can take its full 30s
+        // timeout against a stranded worker connection. Boot should block on the
+        // first *delivered* port instead — if the boot channel stalls, worker
+        // recovery hands the listener a good port long before that timeout.
+        void sw.subscribeToRepoChannel((port) => {
+            if (!seenFirstPort) {
+                seenFirstPort = true;
+                resolveFirstPort(port);
+            }
+            else if (onWorkerPortRenewed) {
+                onWorkerPortRenewed(port);
+            }
+            else {
+                console.warn("automerge worker port renewed before the repo existed; dropping it");
+            }
+        });
+        const workerPort = await firstPortPromise;
         log("repo channel subscribed");
-        const workerPort = await portPromise;
+        let workerAdapter = new MessageChannelNetworkAdapter(workerPort);
         if (config.keyhive) {
             log("setting up keyhive");
             initKeyhiveWasm();
@@ -91,7 +114,7 @@ export async function bootPatchworkSite(config) {
                 createRepo: (config) => new Repo(config),
                 storage: new IndexedDBWorkerStorageAdapter(`${siteName}-keyhive`),
                 peerIdSuffix: siteName + Math.random().toString(36).slice(2),
-                networkAdapter: new MessageChannelNetworkAdapter(workerPort),
+                networkAdapter: workerAdapter,
                 automaticArchiveIngestion: true,
                 cachingMode: "periodic",
                 onlyShareWithHardcodedServerPeerId: false,
@@ -113,7 +136,7 @@ export async function bootPatchworkSite(config) {
             // id never goes on the wire.
             const tabSigner = new MemorySigner();
             repo = new Repo({
-                network: [new MessageChannelNetworkAdapter(workerPort)],
+                network: [workerAdapter],
                 storage: new IndexedDBWorkerStorageAdapter(),
                 signer: tabSigner,
                 async sharePolicy(peerId) {
@@ -129,6 +152,37 @@ export async function bootPatchworkSite(config) {
             console.log("[patchwork] tab subduction identity:", tabSignerIdentity);
             log("repo created");
         }
+        // The worker was recreated with cold state: wire the repo onto the fresh
+        // port and drop the adapter stranded on the dead one. `repo`/`hive` are
+        // settled by the time this can fire (recovery needs a missed heartbeat).
+        const bootHive = hive;
+        onWorkerPortRenewed = (port) => {
+            const fresh = new MessageChannelNetworkAdapter(port);
+            // Mirror the boot wiring: a keyhive repo talks to the worker through a
+            // keyhive adapter wrapped around the message channel (same parameters
+            // the worker uses for its side of the pair).
+            const registered = bootHive
+                ? bootHive.createKeyhiveNetworkAdapter(fresh, false, false, 2000)
+                : fresh;
+            repo.networkSubsystem.addNetworkAdapter(registered);
+            for (const adapter of [...repo.networkSubsystem.adapters]) {
+                if (adapter === registered)
+                    continue;
+                // The keyhive wrapper keeps the wrapped adapter on `.networkAdapter`.
+                const base = adapter.networkAdapter ?? adapter;
+                if (base !== workerAdapter)
+                    continue;
+                try {
+                    repo.networkSubsystem.removeNetworkAdapter(adapter);
+                }
+                catch (err) {
+                    console.error("failed to remove stale worker network adapter", err);
+                }
+            }
+            workerAdapter = fresh;
+            console.warn(`[lifecycle] ${new Date().toISOString()} repo re-wired to the ` +
+                `recreated automerge worker`);
+        };
     }
     log("popping repo on window");
     window.repo = repo;
@@ -157,7 +211,7 @@ export async function bootPatchworkSite(config) {
     const moduleWatcher = new ModuleWatcher(repo, buildSystemSources(defaultModuleSources), onModuleLoaded, unregisterPlugins, 
     // Discover an Automerge package's plugin descriptors off the main thread;
     // each plugin's load() re-imports the package (at heads) on this thread.
-    importAutomergeModuleViaWorker);
+    importAutomergePackageViaWorker);
     const accountDocHandle = (await resolveAccountHandle(repo, {
         storageKey: config.accountStorageKey,
         hive,
@@ -204,21 +258,24 @@ function isValidModuleSource(source) {
 }
 /**
  * Resolve the site's default module-list sources, honouring the
- * `localStorage.defaultToolsUrl` dev override (which replaces the entire
+ * `localStorage.systemPackageListURL` dev override (which replaces the entire
  * built-in default bundle).
  */
 function resolveDefaultModules(config) {
     const builtin = config.defaultModules ?? config.defaultModulesUrl ?? [];
     const builtinList = (Array.isArray(builtin) ? builtin : [builtin]).filter(Boolean);
-    const override = globalThis.localStorage?.getItem("defaultToolsUrl");
+    const storage = globalThis.localStorage;
+    // `defaultToolsUrl` is the pre-rename key, still honoured for existing browsers.
+    const override = storage?.getItem("systemPackageListURL") ??
+        storage?.getItem("defaultToolsUrl");
     if (override) {
         if (isValidModuleSource(override)) {
             if (!builtinList.includes(override)) {
-                console.info(`using defaultToolsUrl override from localStorage: ${override}`);
+                console.info(`using systemPackageListURL override from localStorage: ${override}`);
             }
             return [override];
         }
-        console.warn(`ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`);
+        console.warn(`ignoring invalid systemPackageListURL in localStorage: ${override}; using built-in default`);
     }
     if (builtinList.length === 0) {
         throw new Error("bootPatchworkSite: no default module sources configured (set `defaultModules`)");
@@ -269,8 +326,8 @@ function installLifecycleLogging() {
     document.addEventListener("visibilitychange", () => note(`visibilitychange → ${document.visibilityState}`), opts);
     document.addEventListener("freeze", () => note("freeze (tab suspended)"), opts);
     document.addEventListener("resume", () => note("resume (tab unsuspended)"), opts);
-    window.addEventListener("pageshow", e => note("pageshow", { persisted: e.persisted }), opts);
-    window.addEventListener("pagehide", e => note("pagehide", { persisted: e.persisted }), opts);
+    window.addEventListener("pageshow", (e) => note("pageshow", { persisted: e.persisted }), opts);
+    window.addEventListener("pagehide", (e) => note("pagehide", { persisted: e.persisted }), opts);
     window.addEventListener("online", () => note("online"), opts);
     window.addEventListener("offline", () => note("offline"), opts);
     note(`lifecycle logging installed (visibilityState=${document.visibilityState}, hasFocus=${document.hasFocus()})`);

package/dist/types.d.ts

@@ -133,7 +133,24 @@ export interface HandoffResponseMessage {
     type: "response";
     response: HandoffResponse;
 }
-export type HandoffReplyMessage = HandoffCachedMessage | HandoffResponseMessage;
+/**
+ * Automerge worker → service worker: fail the request as a network error
+ * rather than serving any response at all.
+ *
+ * "Heads haven't arrived yet" is not a 404 — the document may well exist, so
+ * a status implying it doesn't is a lie any HTTP cache is entitled to store.
+ * A network error is the honest answer and isn't storable as a response.
+ *
+ * This does *not* help with `import()`: the ES module map memoizes failed
+ * fetches, network errors included, so a retry needs a distinct URL either
+ * way (see `importModule` in patchwork-filesystem).
+ */
+export interface HandoffAbortMessage {
+    id: string;
+    type: "abort";
+    reason: string;
+}
+export type HandoffReplyMessage = HandoffCachedMessage | HandoffResponseMessage | HandoffAbortMessage;
 /**
  * Automerge worker → world: broadcast once on startup so the service worker
  * can re-send any handoff requests that raced the worker's boot.

package/dist/vite/importmap-plugin.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 /**
  * these dependencies will be built into the outdir,
@@ -7,6 +8,29 @@ const require = createRequire(import.meta.url);
  */
 import externals from "../externals.js";
 export const builtins = externals.reduce((builtins, name) => ((builtins[name] = `/packages/${name}.js`), builtins), {});
+/**
+ * pretend the import came from inside this package, so node_modules resolution
+ * walks up from *our* directory and finds our copy of each external. that's why
+ * a consuming site never has to install them or agree with us about versions.
+ */
+const self = fileURLToPath(import.meta.url);
+/**
+ * resolve an external from our node_modules rather than the site's.
+ *
+ * this goes through rollup's resolver rather than import.meta.resolve or
+ * require.resolve because those apply node's conditions: subduction (and
+ * others) would hand us `dist/esm/node.js`, which imports node:path and blows
+ * up at bundle time. rollup applies the browser conditions vite configured.
+ */
+async function resolveExternal(name) {
+    const resolved = await this.resolve(name, self, { skipSelf: true });
+    if (!resolved) {
+        throw new Error(`@patchwork/vite: couldn't resolve the external "${name}" from ` +
+            `@inkandswitch/patchwork-bootloader. it should be one of the ` +
+            `bootloader's own dependencies.`);
+    }
+    return resolved.id;
+}
 /**
  * merge the importmap option with our builtins
  */
@@ -26,7 +50,7 @@ export function importmap(options) {
                 this.emitFile({
                     type: "chunk",
                     fileName: fileName.slice(1),
-                    id,
+                    id: await resolveExternal.call(this, id),
                     preserveSignature: "strict",
                 });
             }
@@ -51,8 +75,14 @@ export function importmap(options) {
                 source: readFileSync(subdWasmPath),
             });
         },
-        resolveId(id) {
-            if (id in importmap.imports && !(id in builtins)) {
+        async resolveId(id) {
+            if (id in builtins) {
+                // point the site's own imports at the same copy we emit as a chunk,
+                // otherwise rollup bundles a second one out of the site's node_modules
+                // and you end up with two automerges racing to init the same wasm
+                return resolveExternal.call(this, id);
+            }
+            if (id in importmap.imports) {
                 return { id: importmap.imports[id], external: true };
             }
         },