@inkandswitch/patchwork-bootloader 0.3.1 → 0.4.0

package/dist/service-worker.js

@@ -6,9 +6,11 @@
 // "cached" (or "response" for errors and other things that shouldn't be
 // cached).
 import { HANDOFF_CHANNEL, } 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.
 const HANDOFF_TIMEOUT_MS = 35_000;
@@ -52,20 +54,16 @@ self.addEventListener("install", (event) => {
     // every old tab closes.
     event.waitUntil(self.skipWaiting());
 });
-async function clearOldCaches() {
-    const cacheWhitelist = [cachename];
-    const cacheNames = await caches.keys();
-    const deletePromises = cacheNames.map((cacheName) => {
-        if (!cacheWhitelist.includes(cacheName)) {
+async function clearOtherCaches() {
+    await Promise.all((await caches.keys()).map((cacheName) => {
+        if (cacheName !== cachename)
             return caches.delete(cacheName);
-        }
-    });
-    await Promise.all(deletePromises);
+    }));
 }
 self.addEventListener("activate", (event) => {
     lifecycle("info", "activate (claiming clients)");
     event.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.
@@ -77,7 +75,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);
                     }
                 }
             }
@@ -93,9 +91,18 @@ 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;
@@ -157,15 +164,39 @@ function handoff(request, handoffURL) {
         pendingHandoffs.delete(id);
     });
 }
-function withSpecialHeaders(response) {
-    const headers = new Headers(response.headers);
-    headers.set("cross-origin-embedder-policy", "credentialless");
-    headers.set("cross-origin-resource-policy", "cross-origin");
+function makeResponse(response) {
     return new Response(response.body ?? null, {
         status: response.status ?? 200,
-        headers,
+        headers: response.headers,
     });
 }
+function indexRequestFor(request) {
+    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) {
+    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, request, 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) => {
     log("fetch event", fetchEvent.request.url);
@@ -190,7 +221,7 @@ self.addEventListener("fetch", (fetchEvent) => {
             if (handoffURL) {
                 if (match) {
                     log(`serving ${handoffURL} from cache ${cachename}`);
-                    return withSpecialHeaders(match);
+                    return match;
                 }
                 log(`handing ${handoffURL} off to the automerge worker`);
                 const replyPromise = handoff(request, handoffURL);
@@ -199,7 +230,7 @@ self.addEventListener("fetch", (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
                 // response in our cache
@@ -208,25 +239,41 @@ self.addEventListener("fetch", (fetchEvent) => {
                     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);
+                return cached;
             }
             else {
-                const response = await fetch(request).catch(() => null);
-                if (response) {
-                    if (cacheableStatuses.includes(response.status) &&
-                        response.url.match(/^https?\:/)) {
-                        await cache.put(request, response.clone()).catch((error) => {
+                // 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) => 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 ((response.status === 0 ||
+                        cacheableStatuses.includes(response.status)) &&
+                        /^https?:/.test(request.url)) {
+                        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}`);
+                        log(`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) {

package/dist/setup.d.ts

@@ -1,6 +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

@@ -1,5 +1,6 @@
 import { readClassicSyncServer, DEFAULT_CLASSIC_SYNC_SERVER, } from "./sync-config.js";
 import debug from "debug";
+import { donatePort, isWorkerErrorMessage, } from "@automerge/automerge-repo/worker-port";
 const serviceWorkerDebugging = debug.enabled("patchwork:serviceworker");
 const workerDebugging = debug.enabled("patchwork:automergeworker");
 // Diagnostic [lifecycle] logging, on by default. Disable via
@@ -34,6 +35,7 @@ function installServiceWorkerLogForwarding() {
     });
 }
 const key = "patchworkServiceWorkerCacheVersion";
+const defaultServiceWorkerCacheName = "patchwork";
 let nextRepoChannelId = 0;
 function bumpServiceWorkerCacheVersion() {
     const version = new Date().valueOf().toString(36);
@@ -43,19 +45,13 @@ function bumpServiceWorkerCacheVersion() {
 function getServiceWorkerCacheVersion() {
     return localStorage.getItem(key);
 }
-function getOrCreateServiceWorkerCacheVersion() {
-    const existing = getServiceWorkerCacheVersion();
-    if (existing)
-        return existing;
-    return bumpServiceWorkerCacheVersion();
-}
 function setServiceWorkerCacheName(sw) {
     if (!sw) {
         throw new Error("no service worker!");
     }
     sw.postMessage({
         type: "cachename",
-        cachename: getOrCreateServiceWorkerCacheVersion(),
+        cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
     });
 }
 export function bumpServiceWorkerCache(sw = navigator.serviceWorker.controller) {
@@ -67,9 +63,10 @@ function configureServiceWorker(sw) {
     if (!sw)
         return;
     sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
-    const cachename = getServiceWorkerCacheVersion();
-    if (cachename)
-        sw.postMessage({ type: "cachename", cachename });
+    sw.postMessage({
+        type: "cachename",
+        cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
+    });
 }
 // ── The automerge worker ───────────────────────────────────────────────
 // The automerge repo lives in a SharedWorker (not the service worker). One
@@ -79,9 +76,41 @@ function configureServiceWorker(sw) {
 // port; it talks to the service worker over a BroadcastChannel.
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker;
+// 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).
+// Being a SharedWorker itself, the proxy — and the donated worker↔worker
+// port — outlives the donor tab. Emitted at /packages/... via externals.ts.
+const SUBDUCTION_IO_WORKER_URL = "/packages/@automerge/automerge-repo/subduction-websocket-worker-shared.js";
+// Bench toggles for the subduction socket (see getSubductionEndpoints in
+// automerge-worker.ts), passed as query params because SharedWorker scope
+// has no localStorage — which also gives each configuration its own worker
+// instance, so bench arms can't share state.
+//   localStorage["patchwork:ws-mode"] = "inline"  → socket on worker thread
+//   localStorage["patchwork:ws-window"] = "16"    → WorkerWebSocketEndpoint
+//                                                    windowFrames override
+function workerBenchParams() {
+    const params = new URLSearchParams();
+    try {
+        for (const [key, param] of [
+            ["patchwork:ws-mode", "ws-mode"],
+            ["patchwork:ws-window", "ws-window"],
+        ]) {
+            const value = globalThis.localStorage?.getItem(key);
+            if (value)
+                params.set(param, value);
+        }
+    }
+    catch {
+        // No localStorage (shouldn't happen in a tab) — use defaults.
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
 export function getAutomergeWorker() {
     if (!automergeWorker) {
-        automergeWorker = new SharedWorker(automergeWorkerPath, {
+        const workerUrl = `${automergeWorkerPath}${workerBenchParams()}`;
+        automergeWorker = new SharedWorker(workerUrl, {
             name: "patchwork-automerge",
             type: "module",
         });
@@ -91,6 +120,26 @@ export function getAutomergeWorker() {
         // 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 (isWorkerErrorMessage(event.data)) {
+                // Crash/skew reports relayed from the subduction io proxy (e.g.
+                // protocol-mismatch from a stale SW-cached worker chunk). Surface
+                // loudly — these otherwise only exist in chrome://inspect.
+                console.error("[subduction-io]", event.data);
+                return;
+            }
+            if (event.data?.type === "drift-samples") {
+                // Keepalive-drift samples from the worker's bench probe. Kept on a
+                // bounded window global for the Playwright bench to harvest.
+                const sink = (window.__driftSamples ??= []);
+                sink.push(...event.data.samples);
+                if (sink.length > 10_000)
+                    sink.splice(0, sink.length - 10_000);
+                return;
+            }
             if (event.data?.type !== "console")
                 return;
             const { level, args } = event.data;
@@ -113,6 +162,15 @@ export function getAutomergeWorker() {
             }
         });
         automergeWorker.port.postMessage({ type: "debug", debug: workerDebugging });
+        // Offer the subduction io proxy's port; the worker's port provider pulls
+        // it when (re)constructing its WorkerWebSocketEndpoint.
+        donatePort(automergeWorker.port, () => {
+            const io = new SharedWorker(SUBDUCTION_IO_WORKER_URL, {
+                type: "module",
+                name: "subduction-websocket",
+            });
+            return io.port;
+        });
         installWorkerDeathDetection(automergeWorker);
     }
     return automergeWorker;
@@ -181,6 +239,44 @@ function installWorkerDeathDetection(worker) {
         }
     }, 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)) {
@@ -278,6 +374,7 @@ 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();
+    localStorage.removeItem(key);
     if (options?.workerPath)
         automergeWorkerPath = options.workerPath;
     // Start the automerge worker right away so it boots (wasm, repo) while the
@@ -318,6 +415,7 @@ export default async function setupServiceWorker(options) {
         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

@@ -16,7 +16,7 @@ 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>;

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";
@@ -19,6 +19,7 @@ import { initKeyhiveWasm, initializeAutomergeRepoKeyhiveWithRepo, } from "@autom
 // eslint-disable-next-line
 // @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 useKeyhiveSyncServer = typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
@@ -30,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()),
@@ -59,6 +63,7 @@ export async function bootPatchworkSite(config) {
     log("workers ready");
     let hive;
     let repo;
+    let tabSignerIdentity;
     // 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.
@@ -102,15 +107,26 @@ export async function bootPatchworkSite(config) {
         }
         else {
             log("creating repo");
+            // Pass an explicit signer (instead of the Repo's internal default) so we
+            // can expose tab signer identity on window.patchwork for dev inspection.
+            // The tab never connects via Subduction (no endpoints/adapters), so this
+            // id never goes on the wire.
+            const tabSigner = new MemorySigner();
             repo = new Repo({
                 network: [new MessageChannelNetworkAdapter(workerPort)],
                 storage: new IndexedDBWorkerStorageAdapter(),
+                signer: tabSigner,
                 async sharePolicy(peerId) {
                     return peerId.includes("automerge-worker");
                 },
                 enableRemoteHeadsGossiping: true,
                 peerId: `${config.titleSuffix}-tab-${crypto.randomUUID()}`,
             });
+            tabSignerIdentity = {
+                peerId: tabSigner.peerId().toString(),
+                verifyingKey: tabSigner.verifyingKey().toHex(),
+            };
+            console.log("[patchwork] tab subduction identity:", tabSignerIdentity);
             log("repo created");
         }
     }
@@ -157,9 +173,11 @@ export async function bootPatchworkSite(config) {
         packages: moduleWatcher,
         plugins,
         accountDocHandle,
+        ...(tabSignerIdentity ? { signer: tabSignerIdentity } : {}),
         sw: {
             connectClassicSync: sw.connectClassicSync,
             subscribeToRepoChannel: sw.subscribeToRepoChannel,
+            subscribeSyncState: sw.subscribeSyncState,
         },
     };
     window.uncache = uncache;
@@ -167,7 +185,6 @@ export async function bootPatchworkSite(config) {
         rootElement,
         repo,
         accountDocHandle,
-        moduleWatcher,
         titleSuffix: config.titleSuffix,
     });
     return { repo, moduleWatcher, accountDocHandle };
@@ -296,10 +313,7 @@ function primeRootElement(rootElement, accountDocHandle) {
     const initialParams = new URLSearchParams(location.hash.slice(1));
     if (initialParams.has("frame")) {
         rootElement.setAttribute("tool-id", initialParams.get("frame"));
-        const docId = initialParams.get("doc")?.replace(/^automerge:/, "");
-        const docUrl = docId
-            ? stringifyAutomergeUrl({ documentId: docId })
-            : accountDocHandle.url;
+        const docUrl = docParamToUrl(initialParams.get("doc")) ?? accountDocHandle.url;
         rootElement.setAttribute("doc-url", docUrl);
     }
     else {
@@ -385,20 +399,56 @@ async function uncache(match) {
         }
     }
 }
+// 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 = [];
+    const emit = (key) => {
+        if (emitted.has(key))
+            return;
+        const value = params.get(key);
+        if (!value)
+            return;
+        emitted.add(key);
+        parts.push(`${key}=${RAW_HASH_KEYS.has(key) ? value : encodeURIComponent(value)}`);
+    };
+    for (const key of HASH_KEY_ORDER)
+        emit(key);
+    for (const key of params.keys())
+        emit(key);
+    return parts.join("&");
+}
+/**
+ * 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.
+ */
+function docParamToUrl(docParam) {
+    if (!docParam)
+        return undefined;
+    if (isValidAutomergeUrl(docParam)) {
+        return docParam;
+    }
+    const documentId = docParam.replace(/^automerge:/, "");
+    if (isValidDocumentId(documentId)) {
+        return stringifyAutomergeUrl({ documentId: documentId });
+    }
+    return undefined;
+}
 function installHashRouting(params) {
-    const { rootElement, repo, accountDocHandle, moduleWatcher, titleSuffix } = params;
-    rootElement.addEventListener("patchwork:no-tool", (event) => {
-        moduleWatcher.loadSuggestedImportUrl(event.detail.url);
-    });
+    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;
-        const { documentId, heads } = parseAutomergeUrl(url);
-        params.set("doc", documentId);
-        if (heads)
-            params.set("heads", heads.join("|"));
-        else
-            params.delete("heads");
+        // `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)
             params.set("tool", toolId);
         else
@@ -411,9 +461,9 @@ function installHashRouting(params) {
             params.set("type", type);
         else
             params.delete("type");
-        window.location.hash = params.toString();
+        window.location.hash = serializeHashParams(params);
         try {
-            const docHandle = await repo.find(stringifyAutomergeUrl({ documentId, heads }));
+            const docHandle = await repo.find(url);
             const doc = docHandle.doc();
             const docType = type || doc?.["@patchwork"]?.type;
             if (!docType)
@@ -454,44 +504,40 @@ 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>
         if (isValidAutomergeUrl(hash)) {
-            const { documentId, heads } = parseAutomergeUrl(hash);
+            const url = hash;
             window.location.hash = "";
-            openDocument(rootElement, stringifyAutomergeUrl({ documentId, heads }));
+            openDocument(rootElement, url);
             return;
         }
         const params = new URLSearchParams(hash);
-        const documentId = params.get("doc")?.replace(/^automerge:/, "");
-        const heads = params.get("heads")?.split("|");
+        const docUrl = docParamToUrl(params.get("doc"));
         const toolId = params.get("tool");
         const title = params.get("title");
         const type = params.get("type");
         const frame = params.get("frame");
         if (frame) {
-            const docUrl = params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
+            const frameDocUrl = docUrl ?? accountDocHandle.url;
             if (rootElement.getAttribute("tool-id") !== frame ||
-                rootElement.getAttribute("doc-url") !== docUrl) {
+                rootElement.getAttribute("doc-url") !== frameDocUrl) {
                 rootElement.setAttribute("tool-id", frame);
-                rootElement.setAttribute("doc-url", docUrl);
+                rootElement.setAttribute("doc-url", frameDocUrl);
             }
         }
-        if (isValidDocumentId(documentId)) {
+        if (docUrl) {
             rootElement.dispatchEvent(new CustomEvent("patchwork:open-document", {
-                detail: {
-                    url: stringifyAutomergeUrl({ documentId, heads }),
-                    toolId,
-                    title,
-                    type,
-                },
+                detail: { url: docUrl, toolId, title, type },
             }));
         }
     };