@inkandswitch/patchwork-bootloader 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @inkandswitch/patchwork-bootloader
 
+## 0.2.8
+
+### Patch Changes
+
+- 48e4391: Pass the realm-local `repo` to `<patchwork-view>` registration so booted views
+  resolve their document handles through it — via the per-view `OverlayRepo` and
+  the root `<repo-provider>` fallback for `repo:handle-descriptor`.
+- Updated dependencies [48e4391]
+- Updated dependencies [48e4391]
+  - @inkandswitch/patchwork-elements@2.0.0
+  - @inkandswitch/patchwork-providers@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

package/dist/automerge-worker.js

@@ -23,7 +23,7 @@ import { resolvePath } from "@inkandswitch/patchwork-filesystem";
 import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
 import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel";
 import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
-import { initializeAutomergeRepoKeyhiveRust, initKeyhiveWasm, } from "@automerge/automerge-repo-keyhive";
+import { initializeAutomergeRepoKeyhiveRustWithRepo, initKeyhiveWasm, } from "@automerge/automerge-repo-keyhive";
 import { HANDOFF_CHANNEL, } from "./types.js";
 let debugging = false;
 // Sync server selection. Sub is the default. Build with KEYHIVE_SYNC_SERVER=true
@@ -37,9 +37,6 @@ if (useKeyhiveSyncServer) {
         KEYHIVE_SERVER_IDENTITY: "keyhive-sync",
     };
 }
-// keyhive.sync.automerge.org's keyhive identity (issuer d7f41e6f…).
-const KEYHIVE_SYNC_SERVER_PEER_ID = "1/Qebw9O69oH8T/ejYMhFup0tNBh69I3ytGqsmIl358=";
-const KEYHIVE_SYNC_SERVER_CONTACT_CARD_JSON = '{"Rotate":{"payload":{"old":[73,163,230,244,111,233,153,119,133,211,134,237,111,36,52,131,22,50,54,144,150,45,227,235,128,36,33,217,190,198,55,75],"new":[109,115,204,144,178,114,182,238,113,124,4,139,249,76,220,44,128,104,194,68,187,184,82,241,94,145,104,198,159,122,186,43]},"issuer":[215,244,30,111,15,78,235,218,7,241,63,222,141,131,33,22,234,116,180,208,97,235,210,55,202,209,170,178,98,37,223,159],"signature":[178,64,85,76,51,199,196,151,129,14,191,53,127,191,34,223,97,238,95,109,118,179,152,17,205,188,204,177,116,166,147,231,192,201,48,137,19,214,180,45,108,104,34,8,14,63,115,139,215,142,4,179,233,89,150,218,174,168,107,23,8,109,228,6]}}';
 const SUBDUCTION_ENDPOINTS = [
     useKeyhiveSyncServer
         ? "wss://keyhive.sync.automerge.org"
@@ -79,7 +76,7 @@ async function connectClassicSyncNetwork(server) {
     }
 }
 const siteName = typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
-const cacheableStatuses = [200, 203, 204, 206];
+const cacheableStatuses = [200, 203, 204];
 function log(...args) {
     if (!debugging)
         return;
@@ -122,40 +119,23 @@ function getRepoHive() {
                 return { repo };
             }
             initKeyhiveWasm();
-            const keyhiveStorage = new IndexedDBStorageAdapter(`${siteName}-keyhive`);
-            // Keyhive bootstrap needs to run before Repo creation but
-            // the adapter needs the subduction instance from the Repo.
-            // A deferred promise breaks the cycle.
-            let resolveRepoSubduction;
-            const repoSubductionPromise = new Promise((resolve) => {
-                resolveRepoSubduction = resolve;
-            });
-            // We use the Rust variant of Keyhive initialization to talk
-            // to the Rust keyhive-enabled subduction sync server.
-            const hive = await initializeAutomergeRepoKeyhiveRust({
-                storage: keyhiveStorage,
+            // ARK variant for talking to the keyhive-enabled subduction sync server.
+            const { hive, repo } = await initializeAutomergeRepoKeyhiveRustWithRepo({
+                createRepo: (config) => new Repo(config),
+                storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
                 peerIdSuffix: `${siteName}-worker` + Math.random().toString(36).slice(2),
-                subduction: repoSubductionPromise,
                 automaticArchiveIngestion: true,
                 cachingMode: "periodic",
-                ...(useKeyhiveSyncServer
-                    ? {
-                        serverPeerId: KEYHIVE_SYNC_SERVER_PEER_ID,
-                        serverContactCardJson: KEYHIVE_SYNC_SERVER_CONTACT_CARD_JSON,
-                    }
-                    : {}),
-            });
-            const signer = await hive.constructSubductionSigner();
-            const repo = new Repo({
-                storage: new IndexedDBStorageAdapter(),
-                signer,
-                subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
-                peerId: hive.peerId,
-                enableRemoteHeadsGossiping: true,
-                idFactory: hive.idFactory,
+                // ARK selects the relay via `syncServer` ("keyhive" | "subduction"),
+                // which pairs the contact card with the matching peer id. Omitting it
+                // defaults to "subduction".
+                ...(useKeyhiveSyncServer ? { syncServer: "keyhive" } : {}),
+                repo: {
+                    storage: new IndexedDBStorageAdapter(),
+                    subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
+                    enableRemoteHeadsGossiping: true,
+                },
             });
-            repo.subduction.then(resolveRepoSubduction);
-            hive.linkRepo(repo);
             self.repo = repo;
             self.hive = hive;
             log("repo constructed, waiting for network subsystem");
@@ -239,6 +219,7 @@ async function connectPort(port, connection) {
         }
     });
     keyhiveNetworkAdapter.on("ingest-remote", () => {
+        hive.notifySameAgentKeyhiveChange();
         hive.networkAdapter.syncKeyhive?.();
         repo.shareConfigChanged();
     });

package/dist/externals.js

@@ -19,6 +19,7 @@ const externals = [
     "@inkandswitch/patchwork-elements",
     "@inkandswitch/patchwork-filesystem",
     "@inkandswitch/patchwork-plugins",
+    "@inkandswitch/patchwork-providers",
     // sad
     "@codemirror/state",
     "@codemirror/view",

package/dist/service-worker.js

@@ -8,7 +8,7 @@
 import { HANDOFF_CHANNEL, } from "./types.js";
 let cachename = "default";
 let debugging = false;
-const cacheableStatuses = [200, 203, 204, 206];
+const cacheableStatuses = [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;
@@ -163,7 +163,9 @@ self.addEventListener("fetch", (fetchEvent) => {
                 if (response) {
                     if (cacheableStatuses.includes(response.status) &&
                         response.url.match(/^https?\:/)) {
-                        await cache.put(request, response.clone());
+                        await cache.put(request, response.clone()).catch((error) => {
+                            log(`error caching ${request.url} in ${cachename}`, error);
+                        });
                     }
                     else {
                         log(`skipping uncacheable response code from cache: ${response.status} for ${response.url}`);

package/dist/site.d.ts

@@ -40,16 +40,32 @@ declare global {
 }
 export interface SiteConfig {
     /**
-     * Automerge URL of the site's default module-settings document — the bundle
-     * of tools every user of this site gets out of the box. Must contribute at
-     * least a `patchwork:datatype` registration for `"account"` (typically the
-     * one supplied by `@inkandswitch/patchwork-frame`).
+     * The site's default tool bundle — the tools every user of this site gets
+     * out of the box. Must collectively contribute at least a
+     * `patchwork:datatype` registration for `"account"` (typically the one
+     * supplied by `@inkandswitch/patchwork-frame`).
+     *
+     * Each entry is a *module-list source* and may be either:
+     *  - an Automerge module-settings doc URL (`automerge:...`), which is
+     *    live-reloaded, or
+     *  - an HTTP(S) URL (absolute or site-relative, e.g. `/modules.json`) to a
+     *    static JSON manifest of the shape `{ modules: string[], branches? }`,
+     *    fetched once at boot.
+     *
+     * The module URLs *inside* either kind of source may themselves be Automerge
+     * folder docs or plain HTTP(S) bundles, so deployment targets can be freely
+     * mixed.
      *
      * Can be overridden at runtime by setting `localStorage.defaultToolsUrl` to
-     * another automerge: URL — useful for local development against an
-     * unpublished tool set.
+     * another `automerge:` URL or manifest URL — useful for local development
+     * against an unpublished tool set.
+     */
+    defaultModules?: string | string[];
+    /**
+     * @deprecated Use {@link SiteConfig.defaultModules}. Retained for backwards
+     * compatibility with existing sites.
      */
-    defaultModulesUrl: AutomergeUrl;
+    defaultModulesUrl?: AutomergeUrl;
     /**
      * `localStorage` key under which this site remembers which account document
      * belongs to the current user. Sites sharing an origin MUST use distinct

package/dist/site.js

@@ -14,11 +14,12 @@
 import { IndexedDBStorageAdapter, initializeWasm, isValidAutomergeUrl, isValidDocumentId, MessageChannelNetworkAdapter, parseAutomergeUrl, Repo, stringifyAutomergeUrl, } from "@automerge/vanillajs/slim";
 import * as Automerge from "@automerge/automerge/slim";
 import * as AutomergeRepo from "@automerge/automerge-repo/slim";
-import { initKeyhiveWasm, initializeAutomergeRepoKeyhive, } from "@automerge/automerge-repo-keyhive";
+import { initKeyhiveWasm, initializeAutomergeRepoKeyhiveWithRepo, } from "@automerge/automerge-repo-keyhive";
 // 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";
 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";
 import { openDocument, registerPatchworkViewElement, } from "@inkandswitch/patchwork-elements";
 import { registerRepoProviderElement } from "@inkandswitch/patchwork-providers";
@@ -44,7 +45,7 @@ const [automergeWasm, subductionWasm] = await Promise.all([
  * do additional wiring after boot.
  */
 export async function bootPatchworkSite(config) {
-    const defaultModulesUrl = resolveDefaultModulesUrl(config.defaultModulesUrl);
+    const defaultModuleSources = resolveDefaultModules(config);
     showLoadingAnimation();
     log(`booting`, config);
     await initializeWasm(automergeWasm);
@@ -61,26 +62,28 @@ export async function bootPatchworkSite(config) {
     });
     await sw.subscribeToRepoChannel(resolvePort);
     const workerPort = await portPromise;
+    let repo;
     if (config.keyhive) {
         initKeyhiveWasm();
-        hive = await initializeAutomergeRepoKeyhive({
+        ({ hive, repo } = await initializeAutomergeRepoKeyhiveWithRepo({
+            createRepo: (config) => new Repo(config),
             storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
             peerIdSuffix: siteName + Math.random().toString(36).slice(2),
             networkAdapter: new MessageChannelNetworkAdapter(workerPort),
             automaticArchiveIngestion: true,
             cachingMode: "periodic",
             onlyShareWithHardcodedServerPeerId: false,
-        });
+            // ARK selects the relay via `syncServer` ("keyhive" | "subduction").
+            // Defaults to "subduction".
+            ...(useKeyhiveSyncServer ? { syncServer: "keyhive" } : {}),
+            repo: {
+                storage: new IndexedDBStorageAdapter(),
+                enableRemoteHeadsGossiping: true,
+            },
+        }));
     }
-    const repo = hive
-        ? new Repo({
-            storage: new IndexedDBStorageAdapter(),
-            enableRemoteHeadsGossiping: true,
-            network: [hive.networkAdapter],
-            peerId: hive.peerId,
-            idFactory: hive.idFactory,
-        })
-        : new Repo({
+    else {
+        repo = new Repo({
             network: [new MessageChannelNetworkAdapter(workerPort)],
             storage: new IndexedDBStorageAdapter(),
             async sharePolicy(peerId) {
@@ -89,6 +92,7 @@ export async function bootPatchworkSite(config) {
             enableRemoteHeadsGossiping: true,
             peerId: `${config.titleSuffix}-tab-${crypto.randomUUID()}`,
         });
+    }
     repo.subscribeToRemotes(config.remoteStorageIds ?? [DEFAULT_REMOTE_STORAGE_ID]);
     await repo.networkSubsystem.whenReady();
     if (hive) {
@@ -100,15 +104,17 @@ export async function bootPatchworkSite(config) {
     if (!rootElement) {
         throw new Error(`bootPatchworkSite: no element with id="${config.rootElementId ?? "root"}"`);
     }
+    // `<repo-provider>` sits above the root and answers `repo:handle-descriptor`
+    // for any view outside a remapper (resolving to the requested url unchanged).
     const repoProvider = document.createElement("repo-provider");
     rootElement.parentElement.insertBefore(repoProvider, rootElement);
     repoProvider.appendChild(rootElement);
-    registerPatchworkViewElement(hive ? { hive } : {});
+    registerPatchworkViewElement({ hive, repo });
     // The watcher is started with the site's default-tools bundle alone so that
     // `resolveAccountHandle` below has something to await on (the `account`
     // datatype lives in that bundle today). The user's own module-settings URL
     // is added lazily once it appears on the account doc — see below.
-    const moduleWatcher = new ModuleWatcher(repo, { system: defaultModulesUrl }, onModuleLoaded, unregisterPlugins);
+    const moduleWatcher = new ModuleWatcher(repo, buildSystemSources(defaultModuleSources), onModuleLoaded, unregisterPlugins);
     const accountDocHandle = (await resolveAccountHandle(repo, {
         storageKey: config.accountStorageKey,
         hive,
@@ -140,18 +146,56 @@ export async function bootPatchworkSite(config) {
     return { repo, moduleWatcher, accountDocHandle };
 }
 // ─── Internals ──────────────────────────────────────────────────────────
-function resolveDefaultModulesUrl(builtin) {
+/**
+ * A module-list source is valid if it is an Automerge URL or looks like an
+ * HTTP(S)/site-relative manifest URL.
+ */
+function isValidModuleSource(source) {
+    if (isValidAutomergeUrl(source))
+        return true;
+    return (source.startsWith("/") ||
+        source.startsWith("http://") ||
+        source.startsWith("https://") ||
+        source.startsWith("./"));
+}
+/**
+ * Resolve the site's default module-list sources, honouring the
+ * `localStorage.defaultToolsUrl` 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");
-    if (!override)
-        return builtin;
-    if (isValidAutomergeUrl(override)) {
-        if (override !== builtin) {
-            console.info(`using defaultToolsUrl override from localStorage: ${override}`);
+    if (override) {
+        if (isValidModuleSource(override)) {
+            if (!builtinList.includes(override)) {
+                console.info(`using defaultToolsUrl override from localStorage: ${override}`);
+            }
+            return [override];
         }
-        return override;
+        console.warn(`ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`);
+    }
+    if (builtinList.length === 0) {
+        throw new Error("bootPatchworkSite: no default module sources configured (set `defaultModules`)");
     }
-    console.warn(`ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`);
-    return builtin;
+    return builtinList;
+}
+/**
+ * Turn an ordered list of module-list sources into the name-keyed map the
+ * ModuleWatcher expects. The first source keeps the canonical `system` name;
+ * additional sources get suffixed names. None may be `user` (reserved for the
+ * per-account settings doc, which has branch-override precedence).
+ */
+function buildSystemSources(sources) {
+    const map = {};
+    sources.forEach((source, index) => {
+        const name = index === 0 ? "system" : `system-${index}`;
+        map[name] = source;
+    });
+    return map;
 }
 function installDevConsoleGlobals(repo, hive, getRepoChannel) {
     window.repo = repo;
@@ -200,7 +244,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");
+        const docId = initialParams.get("doc")?.replace(/^automerge:/, "");
         const docUrl = docId
             ? stringifyAutomergeUrl({ documentId: docId })
             : accountDocHandle.url;
@@ -366,15 +410,22 @@ function installHashRouting(params) {
             }
             return;
         }
+        // Bare automerge URL in hash: /#automerge:<documentId>
+        if (isValidAutomergeUrl(hash)) {
+            const { documentId, heads } = parseAutomergeUrl(hash);
+            window.location.hash = "";
+            openDocument(rootElement, stringifyAutomergeUrl({ documentId, heads }));
+            return;
+        }
         const params = new URLSearchParams(hash);
-        const documentId = params.get("doc");
+        const documentId = params.get("doc")?.replace(/^automerge:/, "");
         const heads = params.get("heads")?.split("|");
         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") ?? accountDocHandle.url;
+            const docUrl = params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
             if (rootElement.getAttribute("tool-id") !== frame ||
                 rootElement.getAttribute("doc-url") !== docUrl) {
                 rootElement.setAttribute("tool-id", frame);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@inkandswitch/patchwork-bootloader",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "author": "chee",
   "type": "module",
   "license": "MIT",
   "devDependencies": {
-    "@automerge/automerge-repo-keyhive": "0.3.0-alpha.sub.1c",
+    "@automerge/automerge-repo-keyhive": "0.3.0-alpha.sub.6c",
     "esbuild": "^0.23.1",
     "rollup": "^4.61.1"
   },
@@ -41,28 +41,28 @@
   },
   "dependencies": {
     "@automerge/automerge": "3.3.0-fragments.1",
-    "@automerge/automerge-repo": "2.6.0-subduction.29",
-    "@automerge/automerge-repo-network-messagechannel": "2.6.0-subduction.29",
-    "@automerge/automerge-repo-network-websocket": "2.6.0-subduction.29",
-    "@automerge/automerge-repo-storage-indexeddb": "2.6.0-subduction.29",
-    "@automerge/automerge-subduction": "0.15.0",
-    "@automerge/vanillajs": "2.6.0-subduction.29",
-    "@keyhive/keyhive": "0.0.0-alpha.56",
+    "@automerge/automerge-repo": "2.6.0-subduction.34",
+    "@automerge/automerge-repo-network-messagechannel": "2.6.0-subduction.34",
+    "@automerge/automerge-repo-network-websocket": "2.6.0-subduction.34",
+    "@automerge/automerge-repo-storage-indexeddb": "2.6.0-subduction.34",
+    "@automerge/automerge-subduction": "0.16.0",
+    "@automerge/vanillajs": "2.6.0-subduction.34",
+    "@keyhive/keyhive": "0.1.0-alpha.3",
     "@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": "^1.0.0",
-    "@inkandswitch/patchwork-filesystem": "^0.0.8",
+    "@inkandswitch/patchwork-filesystem": "^0.1.0",
     "@inkandswitch/patchwork-plugins": "^0.0.11",
-    "@inkandswitch/patchwork-providers": "^0.2.2"
+    "@inkandswitch/patchwork-providers": "^0.3.0",
+    "@inkandswitch/patchwork-elements": "^2.0.0"
   },
   "peerDependencies": {
     "@automerge/automerge": "3.3.0-fragments.1",
-    "@automerge/automerge-repo": "2.6.0-subduction.29",
-    "@automerge/automerge-repo-keyhive": "0.3.0-alpha.sub.1c",
-    "@automerge/vanillajs": "2.6.0-subduction.29"
+    "@automerge/automerge-repo": "2.6.0-subduction.34",
+    "@automerge/automerge-repo-keyhive": "0.3.0-alpha.sub.6c",
+    "@automerge/vanillajs": "2.6.0-subduction.34"
   },
   "scripts": {
     "build": "tsc",

package/src/automerge-worker.ts

@@ -34,7 +34,7 @@ import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-index
 import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel";
 import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
 import {
-  initializeAutomergeRepoKeyhiveRust,
+  initializeAutomergeRepoKeyhiveRustWithRepo,
   initKeyhiveWasm,
   type AutomergeRepoKeyhiveRust,
 } from "@automerge/automerge-repo-keyhive";
@@ -68,12 +68,6 @@ if (useKeyhiveSyncServer) {
   };
 }
 
-// keyhive.sync.automerge.org's keyhive identity (issuer d7f41e6f…).
-const KEYHIVE_SYNC_SERVER_PEER_ID =
-  "1/Qebw9O69oH8T/ejYMhFup0tNBh69I3ytGqsmIl358=";
-const KEYHIVE_SYNC_SERVER_CONTACT_CARD_JSON =
-  '{"Rotate":{"payload":{"old":[73,163,230,244,111,233,153,119,133,211,134,237,111,36,52,131,22,50,54,144,150,45,227,235,128,36,33,217,190,198,55,75],"new":[109,115,204,144,178,114,182,238,113,124,4,139,249,76,220,44,128,104,194,68,187,184,82,241,94,145,104,198,159,122,186,43]},"issuer":[215,244,30,111,15,78,235,218,7,241,63,222,141,131,33,22,234,116,180,208,97,235,210,55,202,209,170,178,98,37,223,159],"signature":[178,64,85,76,51,199,196,151,129,14,191,53,127,191,34,223,97,238,95,109,118,179,152,17,205,188,204,177,116,166,147,231,192,201,48,137,19,214,180,45,108,104,34,8,14,63,115,139,215,142,4,179,233,89,150,218,174,168,107,23,8,109,228,6]}}';
-
 const SUBDUCTION_ENDPOINTS = [
   useKeyhiveSyncServer
     ? "wss://keyhive.sync.automerge.org"
@@ -121,7 +115,7 @@ async function connectClassicSyncNetwork(server: string): Promise<void> {
 const siteName =
   typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
 
-const cacheableStatuses = [200, 203, 204, 206];
+const cacheableStatuses = [200, 203, 204];
 
 function log(...args: any[]) {
   if (!debugging) return;
@@ -183,48 +177,26 @@ function getRepoHive() {
       }
 
       initKeyhiveWasm();
-      const keyhiveStorage = new IndexedDBStorageAdapter(`${siteName}-keyhive`);
-
-      // Keyhive bootstrap needs to run before Repo creation but
-      // the adapter needs the subduction instance from the Repo.
-      // A deferred promise breaks the cycle.
-      let resolveRepoSubduction!: (s: any) => void;
-      const repoSubductionPromise = new Promise((resolve) => {
-        resolveRepoSubduction = resolve;
-      });
 
-      // We use the Rust variant of Keyhive initialization to talk
-      // to the Rust keyhive-enabled subduction sync server.
-      const hive = await initializeAutomergeRepoKeyhiveRust({
-        storage: keyhiveStorage,
+      // ARK variant for talking to the keyhive-enabled subduction sync server.
+      const { hive, repo } = await initializeAutomergeRepoKeyhiveRustWithRepo({
+        createRepo: (config) => new Repo(config),
+        storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
         peerIdSuffix:
           `${siteName}-worker` + Math.random().toString(36).slice(2),
-        subduction: repoSubductionPromise as any,
         automaticArchiveIngestion: true,
         cachingMode: "periodic",
-        ...(useKeyhiveSyncServer
-          ? {
-              serverPeerId: KEYHIVE_SYNC_SERVER_PEER_ID as any,
-              serverContactCardJson: KEYHIVE_SYNC_SERVER_CONTACT_CARD_JSON,
-            }
-          : {}),
-      });
-
-      const signer = await hive.constructSubductionSigner();
-
-      const repo = new Repo({
-        storage: new IndexedDBStorageAdapter(),
-        signer,
-        subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
-        peerId: hive.peerId,
-        enableRemoteHeadsGossiping: true,
-        idFactory: hive.idFactory,
+        // ARK selects the relay via `syncServer` ("keyhive" | "subduction"),
+        // which pairs the contact card with the matching peer id. Omitting it
+        // defaults to "subduction".
+        ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
+        repo: {
+          storage: new IndexedDBStorageAdapter(),
+          subductionWebsocketEndpoints: SUBDUCTION_ENDPOINTS,
+          enableRemoteHeadsGossiping: true,
+        },
       });
 
-      repo.subduction.then(resolveRepoSubduction);
-
-      hive.linkRepo(repo);
-
       (self as any).repo = repo;
       (self as any).hive = hive;
       log("repo constructed, waiting for network subsystem");
@@ -336,6 +308,7 @@ async function connectPort(port: MessagePort, connection: Connection) {
   });
 
   (keyhiveNetworkAdapter as any).on("ingest-remote", () => {
+    hive.notifySameAgentKeyhiveChange();
     (hive.networkAdapter as any).syncKeyhive?.();
     repo.shareConfigChanged();
   });

package/src/externals.ts

@@ -19,6 +19,7 @@ const externals = [
   "@inkandswitch/patchwork-elements",
   "@inkandswitch/patchwork-filesystem",
   "@inkandswitch/patchwork-plugins",
+  "@inkandswitch/patchwork-providers",
 
   // sad
   "@codemirror/state",

package/src/service-worker.ts

@@ -16,7 +16,7 @@ import {
 let cachename = "default";
 let debugging = false;
 
-const cacheableStatuses = [200, 203, 204, 206];
+const cacheableStatuses = [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.
@@ -220,7 +220,9 @@ self.addEventListener("fetch", (fetchEvent: FetchEvent) => {
               cacheableStatuses.includes(response.status) &&
               response.url.match(/^https?\:/)
             ) {
-              await cache.put(request, response.clone());
+              await cache.put(request, response.clone()).catch((error) => {
+                log(`error caching ${request.url} in ${cachename}`, error);
+              });
             } else {
               log(
                 `skipping uncacheable response code from cache: ${response.status} for ${response.url}`

package/src/site.ts

@@ -30,7 +30,7 @@ import * as Automerge from "@automerge/automerge/slim";
 import * as AutomergeRepo from "@automerge/automerge-repo/slim";
 import {
   initKeyhiveWasm,
-  initializeAutomergeRepoKeyhive,
+  initializeAutomergeRepoKeyhiveWithRepo,
   type AutomergeRepoKeyhive,
 } from "@automerge/automerge-repo-keyhive";
 // eslint-disable-next-line
@@ -41,6 +41,14 @@ declare const __SITE_NAME__: string;
 const siteName =
   typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
 
+// Sync-server selection for keyhive. Defaults to "subduction". Build with
+// KEYHIVE_SYNC_SERVER=true to target keyhive.sync.automerge.org. This must match
+// the automerge-worker (SharedWorker) selection so the tab and the SW grant relay
+// access to the same server.
+declare const __KEYHIVE_SYNC_SERVER__: boolean;
+const useKeyhiveSyncServer =
+  typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
+
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
 import {
   openDocument,
@@ -89,16 +97,33 @@ declare global {
 
 export interface SiteConfig {
   /**
-   * Automerge URL of the site's default module-settings document — the bundle
-   * of tools every user of this site gets out of the box. Must contribute at
-   * least a `patchwork:datatype` registration for `"account"` (typically the
-   * one supplied by `@inkandswitch/patchwork-frame`).
+   * The site's default tool bundle — the tools every user of this site gets
+   * out of the box. Must collectively contribute at least a
+   * `patchwork:datatype` registration for `"account"` (typically the one
+   * supplied by `@inkandswitch/patchwork-frame`).
+   *
+   * Each entry is a *module-list source* and may be either:
+   *  - an Automerge module-settings doc URL (`automerge:...`), which is
+   *    live-reloaded, or
+   *  - an HTTP(S) URL (absolute or site-relative, e.g. `/modules.json`) to a
+   *    static JSON manifest of the shape `{ modules: string[], branches? }`,
+   *    fetched once at boot.
+   *
+   * The module URLs *inside* either kind of source may themselves be Automerge
+   * folder docs or plain HTTP(S) bundles, so deployment targets can be freely
+   * mixed.
    *
    * Can be overridden at runtime by setting `localStorage.defaultToolsUrl` to
-   * another automerge: URL — useful for local development against an
-   * unpublished tool set.
+   * another `automerge:` URL or manifest URL — useful for local development
+   * against an unpublished tool set.
+   */
+  defaultModules?: string | string[];
+
+  /**
+   * @deprecated Use {@link SiteConfig.defaultModules}. Retained for backwards
+   * compatibility with existing sites.
    */
-  defaultModulesUrl: AutomergeUrl;
+  defaultModulesUrl?: AutomergeUrl;
 
   /**
    * `localStorage` key under which this site remembers which account document
@@ -163,7 +188,7 @@ const [automergeWasm, subductionWasm] = await Promise.all([
 export async function bootPatchworkSite(
   config: SiteConfig
 ): Promise<BootResult> {
-  const defaultModulesUrl = resolveDefaultModulesUrl(config.defaultModulesUrl);
+  const defaultModuleSources = resolveDefaultModules(config);
   showLoadingAnimation();
   log(`booting`, config);
   await initializeWasm(automergeWasm);
@@ -173,53 +198,53 @@ export async function bootPatchworkSite(
   if (!sw) throw new Error("Failed to set up service worker");
 
   let hive: AutomergeRepoKeyhive | undefined;
-      // Get the initial automerge-worker port via subscribeToRepoChannel,
-    // then pass it to keyhive init which wraps it in its own network adapter.
-    let resolvePort!: (port: MessagePort) => void;
-    const portPromise = new Promise<MessagePort>((r) => {
-      resolvePort = r;
-    });
-    await sw.subscribeToRepoChannel(resolvePort);
-    const workerPort = await portPromise;
+  // Get the initial automerge-worker port via subscribeToRepoChannel,
+  // then pass it to keyhive init which wraps it in its own network adapter.
+  let resolvePort!: (port: MessagePort) => void;
+  const portPromise = new Promise<MessagePort>((r) => {
+    resolvePort = r;
+  });
+  await sw.subscribeToRepoChannel(resolvePort);
+  const workerPort = await portPromise;
 
+  let repo: Repo;
   if (config.keyhive) {
     initKeyhiveWasm();
 
-    hive = await initializeAutomergeRepoKeyhive({
+    ({ hive, repo } = await initializeAutomergeRepoKeyhiveWithRepo({
+      createRepo: (config) => new Repo(config),
       storage: new IndexedDBStorageAdapter(`${siteName}-keyhive`),
       peerIdSuffix: siteName + Math.random().toString(36).slice(2),
       networkAdapter: new MessageChannelNetworkAdapter(workerPort),
       automaticArchiveIngestion: true,
       cachingMode: "periodic",
       onlyShareWithHardcodedServerPeerId: false,
-    });
-  }
-
-  const repo = hive
-    ? new Repo({
+      // ARK selects the relay via `syncServer` ("keyhive" | "subduction").
+      // Defaults to "subduction".
+      ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
+      repo: {
         storage: new IndexedDBStorageAdapter(),
         enableRemoteHeadsGossiping: true,
-        network: [hive.networkAdapter],
-        peerId: hive.peerId,
-        idFactory: hive.idFactory,
-      })
-    : new Repo({
-        network: [new MessageChannelNetworkAdapter(workerPort)],
-        storage: new IndexedDBStorageAdapter(),
-        async sharePolicy(peerId) {
-          return peerId.includes("automerge-worker");
-        },
-        enableRemoteHeadsGossiping: true,
-        peerId:
-          `${config.titleSuffix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
-      });
+      },
+    }));
+  } else {
+    repo = new Repo({
+      network: [new MessageChannelNetworkAdapter(workerPort)],
+      storage: new IndexedDBStorageAdapter(),
+      async sharePolicy(peerId) {
+        return peerId.includes("automerge-worker");
+      },
+      enableRemoteHeadsGossiping: true,
+      peerId:
+        `${config.titleSuffix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
+    });
+  }
   repo.subscribeToRemotes(
     config.remoteStorageIds ?? [DEFAULT_REMOTE_STORAGE_ID]
   );
 
   await repo.networkSubsystem.whenReady();
   if (hive) {
-
     (hive.networkAdapter as any).syncKeyhive?.();
   }
 
@@ -233,11 +258,13 @@ export async function bootPatchworkSite(
       `bootPatchworkSite: no element with id="${config.rootElementId ?? "root"}"`
     );
   }
+  // `<repo-provider>` sits above the root and answers `repo:handle-descriptor`
+  // for any view outside a remapper (resolving to the requested url unchanged).
   const repoProvider = document.createElement("repo-provider");
   rootElement.parentElement!.insertBefore(repoProvider, rootElement);
   repoProvider.appendChild(rootElement);
 
-  registerPatchworkViewElement(hive ? { hive } : {});
+  registerPatchworkViewElement({ hive, repo });
 
   // The watcher is started with the site's default-tools bundle alone so that
   // `resolveAccountHandle` below has something to await on (the `account`
@@ -245,7 +272,7 @@ export async function bootPatchworkSite(
   // is added lazily once it appears on the account doc — see below.
   const moduleWatcher = new ModuleWatcher(
     repo,
-    { system: defaultModulesUrl },
+    buildSystemSources(defaultModuleSources),
     onModuleLoaded,
     unregisterPlugins
   );
@@ -289,21 +316,70 @@ export async function bootPatchworkSite(
 
 // ─── Internals ──────────────────────────────────────────────────────────
 
-function resolveDefaultModulesUrl(builtin: AutomergeUrl): AutomergeUrl {
+/**
+ * A module-list source is valid if it is an Automerge URL or looks like an
+ * HTTP(S)/site-relative manifest URL.
+ */
+function isValidModuleSource(source: string): boolean {
+  if (isValidAutomergeUrl(source)) return true;
+  return (
+    source.startsWith("/") ||
+    source.startsWith("http://") ||
+    source.startsWith("https://") ||
+    source.startsWith("./")
+  );
+}
+
+/**
+ * Resolve the site's default module-list sources, honouring the
+ * `localStorage.defaultToolsUrl` dev override (which replaces the entire
+ * built-in default bundle).
+ */
+function resolveDefaultModules(config: SiteConfig): string[] {
+  const builtin =
+    config.defaultModules ??
+    config.defaultModulesUrl ??
+    [];
+  const builtinList = (Array.isArray(builtin) ? builtin : [builtin]).filter(
+    Boolean
+  );
+
   const override = globalThis.localStorage?.getItem("defaultToolsUrl");
-  if (!override) return builtin;
-  if (isValidAutomergeUrl(override)) {
-    if (override !== builtin) {
-      console.info(
-        `using defaultToolsUrl override from localStorage: ${override}`
-      );
+  if (override) {
+    if (isValidModuleSource(override)) {
+      if (!builtinList.includes(override)) {
+        console.info(
+          `using defaultToolsUrl override from localStorage: ${override}`
+        );
+      }
+      return [override];
     }
-    return override;
+    console.warn(
+      `ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`
+    );
   }
-  console.warn(
-    `ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`
-  );
-  return builtin;
+
+  if (builtinList.length === 0) {
+    throw new Error(
+      "bootPatchworkSite: no default module sources configured (set `defaultModules`)"
+    );
+  }
+  return builtinList;
+}
+
+/**
+ * Turn an ordered list of module-list sources into the name-keyed map the
+ * ModuleWatcher expects. The first source keeps the canonical `system` name;
+ * additional sources get suffixed names. None may be `user` (reserved for the
+ * per-account settings doc, which has branch-override precedence).
+ */
+function buildSystemSources(sources: string[]): Record<string, string> {
+  const map: Record<string, string> = {};
+  sources.forEach((source, index) => {
+    const name = index === 0 ? "system" : `system-${index}`;
+    map[name] = source;
+  });
+  return map;
 }
 
 function installDevConsoleGlobals(
@@ -371,7 +447,7 @@ function primeRootElement(
   const initialParams = new URLSearchParams(location.hash.slice(1));
   if (initialParams.has("frame")) {
     rootElement.setAttribute("tool-id", initialParams.get("frame")!);
-    const docId = initialParams.get("doc");
+    const docId = initialParams.get("doc")?.replace(/^automerge:/, "");
     const docUrl = docId
       ? stringifyAutomergeUrl({ documentId: docId as DocumentId })
       : accountDocHandle.url;
@@ -557,15 +633,26 @@ function installHashRouting(params: HashRoutingParams): void {
       return;
     }
 
+    // Bare automerge URL in hash: /#automerge:<documentId>
+    if (isValidAutomergeUrl(hash as AutomergeUrl)) {
+      const { documentId, heads } = parseAutomergeUrl(hash as AutomergeUrl);
+      window.location.hash = "";
+      openDocument(
+        rootElement,
+        stringifyAutomergeUrl({ documentId, heads })
+      );
+      return;
+    }
+
     const params = new URLSearchParams(hash);
-    const documentId = params.get("doc");
+    const documentId = params.get("doc")?.replace(/^automerge:/, "");
     const heads = params.get("heads")?.split("|") as UrlHeads | undefined;
     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") ?? accountDocHandle.url;
+      const docUrl = params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
       if (
         rootElement.getAttribute("tool-id") !== frame ||
         rootElement.getAttribute("doc-url") !== docUrl