@inkandswitch/patchwork 0.7.4 → 0.8.1

package/dist/vite/patches-plugin.js

@@ -0,0 +1,149 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Source patches to @automerge/automerge-repo, applied as it passes through
+ * the bundler.
+ *
+ * The same edits live in this repo's `patches/` as a pnpm patch, which is what
+ * makes our own typecheck see the widened `role` type. A pnpm patch only
+ * exists in this repo's node_modules, though: a site that installs
+ * @inkandswitch/patchwork resolves automerge-repo out of its own tree and
+ * would bundle it unpatched. These run there too.
+ *
+ * Both edits are upstream-shaped and meant to be deleted once subduction takes
+ * them. Until then they are pinned to one automerge-repo version and every
+ * anchor has to match, so a dependency bump fails the build instead of quietly
+ * un-patching it.
+ */
+const AUTOMERGE_REPO = "@automerge/automerge-repo";
+const VERSION = "2.6.0-subduction.48";
+const PATCHES = {
+    "dist/subduction/AdapterConnections.js": [
+        {
+            find: `            if (role === "accept") {
+                await subduction.acceptTransport(transport, serviceName);
+            }
+            else {
+                await subduction.connectTransport(transport, serviceName);
+            }`,
+            replace: `            const initiate = role === "mesh" ? this.#localPeerId < peerId : role !== "accept";
+            if (initiate) {
+                await subduction.connectTransport(transport, serviceName);
+            }
+            else {
+                await subduction.acceptTransport(transport, serviceName);
+            }`,
+        },
+    ],
+    "dist/subduction/SubductionConnections.js": [
+        {
+            find: `            if (state === "connecting")
+                return true;`,
+            replace: `            // "awaiting-reconnect" counts: the loop is between attempts, not
+            // given up, so a query should wait rather than report unavailable.
+            if (state === "connecting" || state === "awaiting-reconnect")
+                return true;`,
+        },
+    ],
+};
+function match(id) {
+    const path = id.replace(/\\/g, "/").split("?")[0];
+    for (const file of Object.keys(PATCHES)) {
+        const suffix = `/${AUTOMERGE_REPO}/${file}`;
+        if (path.endsWith(suffix)) {
+            return {
+                file,
+                root: path.slice(0, -suffix.length) + `/${AUTOMERGE_REPO}`,
+            };
+        }
+    }
+}
+const versions = new Map();
+async function assertVersion(root, file) {
+    let version = versions.get(root);
+    if (!version) {
+        version = readFile(join(root, "package.json"), "utf8").then((json) => JSON.parse(json).version, (error) => {
+            throw new Error(`@inkandswitch/patchwork: couldn't read ${root}/package.json to ` +
+                `check the version the source patches are written against. ` +
+                `Has the package's layout changed? (${error})`);
+        });
+        versions.set(root, version);
+    }
+    if ((await version) !== VERSION) {
+        throw new Error(`@inkandswitch/patchwork: ${AUTOMERGE_REPO} is ${await version}, and the ` +
+            `source patches in patches-plugin.ts are written against ${VERSION}. ` +
+            `Re-check them against the new version (${file} is one of the files ` +
+            `they edit), then bump VERSION.`);
+    }
+}
+function apply(code, file) {
+    return PATCHES[file].reduce((code, { find, replace }) => {
+        if (code.includes(replace))
+            return code;
+        const matches = code.split(find).length - 1;
+        if (matches !== 1) {
+            throw new Error(`@inkandswitch/patchwork: the source patch for ${AUTOMERGE_REPO}'s ` +
+                `${file} matched ${matches} times, expected 1. The file is the ` +
+                `version it says it is, so the patch needs rewriting against it.`);
+        }
+        return code.replace(find, replace);
+    }, code);
+}
+async function patchFile(id) {
+    const found = match(id);
+    if (!found)
+        return;
+    await assertVersion(found.root, found.file);
+    return apply(await readFile(id, "utf8"), found.file);
+}
+export function patches() {
+    const seen = new Set();
+    let serve = false;
+    return {
+        name: "@patchwork/patches",
+        enforce: "pre",
+        // Dep pre-bundling runs esbuild directly, outside the plugin pipeline that
+        // applies `transform`. Without this the dev server would serve an
+        // unpatched automerge-repo while the build patched it.
+        config() {
+            return {
+                optimizeDeps: {
+                    esbuildOptions: {
+                        plugins: [
+                            {
+                                name: "patchwork-automerge-repo-patches",
+                                setup(build) {
+                                    build.onLoad({ filter: /automerge-repo[\\/]dist[\\/]subduction[\\/]/ }, async ({ path }) => {
+                                        const contents = await patchFile(path);
+                                        return contents ? { contents, loader: "js" } : undefined;
+                                    });
+                                },
+                            },
+                        ],
+                    },
+                },
+            };
+        },
+        configResolved(config) {
+            serve = config.command === "serve";
+        },
+        async transform(code, id) {
+            const found = match(id);
+            if (!found)
+                return;
+            await assertVersion(found.root, found.file);
+            seen.add(found.file);
+            return apply(code, found.file);
+        },
+        buildEnd() {
+            if (serve)
+                return;
+            const missing = Object.keys(PATCHES).filter((file) => !seen.has(file));
+            if (missing.length) {
+                throw new Error(`@inkandswitch/patchwork: ${AUTOMERGE_REPO}'s ${missing.join(", ")} ` +
+                    `never reached the bundler, so the source patches for them didn't ` +
+                    `apply. Has the package's layout changed?`);
+            }
+        },
+    };
+}

package/dist/vite/patchwork-plugin.d.ts

@@ -24,6 +24,7 @@ import type { PatchworkSiteOptions } from "../site-kit/options.js";
  */
 export default function patchwork(options?: PatchworkVitePluginOptions): Plugin<any>[];
 export { importmap, builtins, devDependencyId } from "./importmap-plugin.js";
+export { patches } from "./patches-plugin.js";
 export { serviceworker, workers } from "./service-worker-plugin.js";
 export { config, buildDefines, wasm } from "./config-plugin.js";
 export { dev } from "./dev-plugin.js";
@@ -43,7 +44,7 @@ export type ImportMap = {
     };
 };
 export type { PatchworkStaticSource } from "./static-plugin.js";
-export type { PatchworkSiteOptions, PatchworkIconsOptions, PatchworkHtmlOptions, PatchworkNetlifyOptions, PatchworkKeyhiveSyncServer, PatchworkSyncServersOptions, } from "../site-kit/options.js";
+export type { PatchworkSiteOptions, PatchworkIconsOptions, PatchworkHtmlOptions, PatchworkNetlifyOptions, PatchworkKeyhiveSyncServer, PatchworkKeyhiveOptions, PatchworkSyncServersOptions, } from "../site-kit/options.js";
 export interface PatchworkVitePluginOptions extends PatchworkSiteOptions {
     importmap?: ImportMap;
     /**

package/dist/vite/patchwork-plugin.js

@@ -1,4 +1,5 @@
 import { importmap } from "./importmap-plugin.js";
+import { patches } from "./patches-plugin.js";
 import { serviceworker } from "./service-worker-plugin.js";
 import { config, wasm } from "./config-plugin.js";
 import { dev } from "./dev-plugin.js";
@@ -38,6 +39,7 @@ export default function patchwork(options) {
         manifest(options),
         netlify(options),
         importmap(options),
+        patches(),
         serviceworker(),
         dev(options),
         statics(options),
@@ -45,6 +47,7 @@ export default function patchwork(options) {
     ].filter((plugin) => plugin != null);
 }
 export { importmap, builtins, devDependencyId } from "./importmap-plugin.js";
+export { patches } from "./patches-plugin.js";
 export { serviceworker, workers } from "./service-worker-plugin.js";
 export { config, buildDefines, wasm } from "./config-plugin.js";
 export { dev } from "./dev-plugin.js";

package/dist/vite/service-worker-plugin.js

@@ -16,8 +16,8 @@ export const workers = [
         fileName: "service-worker.js",
     },
     {
-        specifier: "@inkandswitch/patchwork-bootloader/automerge-worker",
-        fileName: "automerge-worker.js",
+        specifier: "@inkandswitch/patchwork-bootloader/automerge-protocol-handler-worker",
+        fileName: "automerge-protocol-handler-worker.js",
     },
     {
         specifier: "@inkandswitch/patchwork-bootloader/module-loader-worker",

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+https://github.com/inkandswitch/patchwork-system.git",
     "directory": "core/patchwork"
   },
-  "version": "0.7.4",
+  "version": "0.8.1",
   "author": "Ink & Switch",
   "type": "module",
   "license": "MIT",
@@ -72,7 +72,7 @@
     "./global.css": "./dist/global.css"
   },
   "dependencies": {
-    "@automerge/automerge": "3.3.2",
+    "@automerge/automerge": "3.4.1",
     "@automerge/automerge-repo": "2.6.0-subduction.48",
     "@automerge/automerge-repo-keyhive": "0.5.0-alpha.7",
     "@automerge/automerge-repo-storage-indexeddb": "2.6.0-subduction.48",
@@ -83,10 +83,10 @@
     "esbuild": "^0.23.1",
     "sharp": "^0.35.3",
     "vite-plugin-wasm": "^3.6.0",
-    "@inkandswitch/patchwork-bootloader": "^0.6.3",
+    "@inkandswitch/patchwork-bootloader": "^0.7.1",
     "@inkandswitch/patchwork-elements": "^6.0.2",
-    "@inkandswitch/patchwork-filesystem": "^0.2.8",
-    "@inkandswitch/patchwork-plugins": "^1.2.3",
+    "@inkandswitch/patchwork-filesystem": "^0.2.9",
+    "@inkandswitch/patchwork-plugins": "^1.2.4",
     "@inkandswitch/patchwork-providers": "^0.5.2"
   },
   "devDependencies": {

package/src/index.ts

@@ -1,8 +1,9 @@
 /**
  * One import for a Patchwork site.
  *
- * `setup(options)` constructs the Repo, wires up the automerge-worker port,
- * loads plugins via the ModuleWatcher, resolves the user's account document,
+ * `setup(options)` constructs the Repo, wires up the
+ * automerge-protocol-handler-worker port, loads plugins via the
+ * ModuleWatcher, resolves the user's account document,
  * installs the router, and resolves with the site's runtime API — `repo`,
  * `create`, `open`, `find`, `packages`, `plugins`, `sw` — which is what a
  * site assigns to `window.patchwork`.
@@ -15,12 +16,13 @@
  * Pulls in DOM- and plugin-layer dependencies, so it is for a browser site's
  * `main.ts` only. Non-UI consumers should import
  * `@inkandswitch/patchwork-bootloader` directly, which does SW registration
- * and the automerge-worker handoff and nothing else.
+ * and the automerge-protocol-handler-worker handoff and nothing else.
  */
 import {
   type AutomergeUrl,
   type DocHandle,
-  MessageChannelNetworkAdapter,
+  type DocumentId,
+  type StorageId,
   Repo,
 } from "@automerge/vanillajs/slim";
 import * as Automerge from "@automerge/automerge/slim";
@@ -52,13 +54,9 @@ import type {
   Patchwork,
   PatchworkOptions,
   SignerIdentity,
+  SyncStateDocMessage,
 } from "./types.js";
-import {
-  createRepo,
-  firstRepoPort,
-  initWasm,
-  removeAdapterFor,
-} from "./repo.js";
+import { createRepo, initWasm } from "./repo.js";
 import { createRouter, type Router } from "./router.js";
 import { createDefaultAccount } from "./createAccount.js";
 
@@ -130,46 +128,13 @@ async function doSetup(options: PatchworkOptions): Promise<Patchwork> {
   let hive: AutomergeRepoKeyhive | undefined;
   let repo: Repo;
   let signerIdentity: SignerIdentity | undefined;
-  // Called with a fresh port when the automerge worker dies and is recreated.
-  // Assigned once the repo exists.
-  let onWorkerPortRenewed: ((port: MessagePort) => void) | undefined;
 
   if (options.repo) {
     log("using provided Repo");
     repo = options.repo;
     hive = options.hive;
   } else {
-    const workerPort = await firstRepoPort(sw, (port) => {
-      if (onWorkerPortRenewed) onWorkerPortRenewed(port);
-      else {
-        console.warn(
-          "automerge worker port renewed before the repo existed; dropping it"
-        );
-      }
-    });
-
-    let workerAdapter = new MessageChannelNetworkAdapter(workerPort);
-    ({ repo, hive, signerIdentity } = await createRepo(workerAdapter));
-
-    // The worker was recreated with cold state: wire the repo onto the fresh
-    // port and drop the adapter stranded on the dead one.
-    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.
-      const registered = bootHive
-        ? bootHive.createKeyhiveNetworkAdapter(fresh, {
-            onlyShareWithSyncServer: false,
-            periodicallyRequestSync: false,
-            syncRequestInterval: 2000,
-          })
-        : fresh;
-      repo.networkSubsystem.addNetworkAdapter(registered as any);
-      removeAdapterFor(repo, workerAdapter, registered);
-      workerAdapter = fresh;
-      lifecycleLog("repo re-wired to the recreated automerge worker");
-    };
+    ({ repo, hive, signerIdentity } = await createRepo());
   }
 
   // Dev-console / tool-runtime globals (e2e and loaded tools read these). The
@@ -181,8 +146,6 @@ async function doSetup(options: PatchworkOptions): Promise<Patchwork> {
     AutomergeRepo as typeof import("@automerge/automerge-repo");
   if (hive) window.hive = hive;
 
-  await repo.networkSubsystem.whenReady();
-  log("networkSubsystem ready");
   (hive?.networkAdapter as any)?.syncKeyhive?.();
 
   registerRepoProviderElement(repo as any);
@@ -261,8 +224,8 @@ async function doSetup(options: PatchworkOptions): Promise<Patchwork> {
     plugins,
     sw: {
       connectClassicSync: sw.connectClassicSync,
-      subscribeToRepoChannel: sw.subscribeToRepoChannel,
-      subscribeSyncState: sw.subscribeSyncState,
+      subscribeSyncState: (documentId, listener) =>
+        subscribeSyncState(repo, documentId, listener),
     },
 
     async create<D>(type: string, init?: (doc: D) => void) {
@@ -433,6 +396,50 @@ function installLifecycleLogging(): void {
   );
 }
 
+// The tab's own Repo hears the server's heads directly, so this is a filter
+// over its `subduction-remote-heads` event. The current value is replayed
+// from the handle's sync info, when the server has reported any.
+function subscribeSyncState(
+  repo: Repo,
+  documentId: string,
+  listener: (update: SyncStateDocMessage) => void
+): () => void {
+  const onHeads = (payload: {
+    documentId: string;
+    storageId: string;
+    heads: readonly string[];
+    timestamp: number;
+  }) => {
+    if (payload.documentId !== documentId) return;
+    listener({
+      type: "sync-state",
+      documentId,
+      storageId: payload.storageId,
+      heads: [...payload.heads],
+      timestamp: payload.timestamp,
+    });
+  };
+  repo.on("subduction-remote-heads", onHeads);
+
+  void (async () => {
+    const handle = repo.handles[documentId as DocumentId];
+    if (!handle) return;
+    for (const storageId of await repo.connectedSubductionPeerIds()) {
+      const info = handle.getSyncInfo(storageId as StorageId);
+      if (info) {
+        onHeads({
+          documentId,
+          storageId,
+          heads: info.lastHeads,
+          timestamp: info.lastSyncTimestamp,
+        });
+      }
+    }
+  })();
+
+  return () => repo.off("subduction-remote-heads", onHeads);
+}
+
 // ── Named exports ────────────────────────────────────────────────────────
 
 export { createRepo, initWasm } from "./repo.js";
@@ -448,4 +455,5 @@ export type {
   PatchworkOptions,
   ServiceWorkerApi,
   SignerIdentity,
+  SyncStateDocMessage,
 } from "./types.js";

package/src/repo.ts

@@ -1,22 +1,17 @@
-import {
-  initializeWasm,
-  MessageChannelNetworkAdapter,
-  Repo,
-  type AutomergeUrl,
-} from "@automerge/vanillajs/slim";
+import { initializeWasm, Repo } from "@automerge/vanillajs/slim";
 import { IndexedDBWorkerStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb/IndexedDBWorkerStorageAdapter";
+import { siblingAdapters } from "@inkandswitch/patchwork-bootloader/siblings";
+import { loadOrCreateSigner } from "@inkandswitch/patchwork-bootloader/signer";
 import * as AutomergeRepo from "@automerge/automerge-repo/slim";
 import {
   initKeyhiveWasm,
-  initializeLegacyAutomergeRepoKeyhive,
-  type AutomergeRepoKeyhiveBase,
+  initializeAutomergeRepoKeyhive,
+  type AutomergeRepoKeyhive,
   type SyncServerSelection,
 } 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";
-import { MemorySigner } from "@automerge/automerge-subduction/slim";
-import setupServiceWorker from "@inkandswitch/patchwork-bootloader";
 import {
   keyhiveStorageName,
   storagePrefix,
@@ -29,6 +24,7 @@ const log = debug("patchwork:setup:repo");
 declare const __SYNC_SERVER__: {
   url: string;
   keyhive?: SyncServerSelection;
+  useIdFactory?: boolean;
 };
 const syncServer =
   typeof __SYNC_SERVER__ !== "undefined"
@@ -53,28 +49,40 @@ export function initWasm(): Promise<void> {
   return wasmReady;
 }
 
-export async function createRepo(
-  workerAdapter: MessageChannelNetworkAdapter
-): Promise<{
+export type TabRepo = {
   repo: Repo;
-  hive?: AutomergeRepoKeyhiveBase;
+  hive?: AutomergeRepoKeyhive;
   signerIdentity?: SignerIdentity;
-}> {
+};
+
+/**
+ * The tab's own node: this origin's IndexedDB, a socket to the sync server,
+ * and the siblings channel to every other Repo on the origin. Nothing is
+ * shared with other tabs except the database underneath.
+ */
+export async function createRepo(): Promise<TabRepo> {
   if (syncServer.keyhive) {
     log("setting up keyhive");
     initKeyhiveWasm();
-    const { hive, repo } = await initializeLegacyAutomergeRepoKeyhive({
-      createRepo: (repoConfig) => new Repo(repoConfig),
+    const { hive, repo } = await initializeAutomergeRepoKeyhive({
+      // ARK injects an `idFactory` deriving document ids from keyhive. A site
+      // can opt out of it with `keyhive: { useIdFactory: false }`.
+      createRepo: ({ idFactory, ...repoConfig }) =>
+        new Repo(
+          syncServer.useIdFactory === false
+            ? repoConfig
+            : { ...repoConfig, idFactory }
+        ),
       storage: new IndexedDBWorkerStorageAdapter(keyhiveStorageName),
       peerIdSuffix: storagePrefix + Math.random().toString(36).slice(2),
-      networkAdapter: workerAdapter,
       automaticArchiveIngestion: true,
       cachingMode: "periodic",
-      onlyShareWithSyncServer: false,
       // ARK selects the relay via `syncServer`, defaulting to "subduction".
       syncServer: syncServer.keyhive,
       repo: {
         storage: new IndexedDBWorkerStorageAdapter(),
+        subductionWebsocketEndpoints: [syncServer.url],
+        subductionAdapters: siblingAdapters(),
         enableRemoteHeadsGossiping: true,
       },
     });
@@ -82,20 +90,19 @@ export async function createRepo(
     return { repo, hive };
   }
 
-  // An explicit signer, rather than the Repo's internal default, so the tab's
-  // identity can be exposed on window.patchwork. The tab never connects via
-  // Subduction, so this id never goes on the wire.
-  const signer = new MemorySigner();
+  // The signer is explicit rather than the Repo's internal default so that
+  // every tab on this origin signs as the same peer, and so the identity the
+  // tab presents to the server can be shown on window.patchwork.
+  const storage = new IndexedDBWorkerStorageAdapter();
+  const signer = await loadOrCreateSigner(storage);
   const repo = new Repo({
-    network: [workerAdapter],
-    storage: new IndexedDBWorkerStorageAdapter(),
     signer,
-    async sharePolicy(peerId) {
-      return peerId.includes("automerge-worker");
-    },
-    enableRemoteHeadsGossiping: true,
+    storage,
     peerId:
       `${storagePrefix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
+    subductionWebsocketEndpoints: [syncServer.url],
+    subductionAdapters: siblingAdapters(),
+    enableRemoteHeadsGossiping: true,
   });
   const signerIdentity = {
     peerId: signer.peerId().toString(),
@@ -108,46 +115,3 @@ export async function createRepo(
   log("repo created, tab subduction identity:", signerIdentity);
   return { repo, signerIdentity };
 }
-
-/**
- * Resolve with the first repo port the worker delivers, calling `onRenewed` for
- * every later one.
- *
- * subscribeToRepoChannel is deliberately not awaited: it resolves only after
- * the boot channel's port-ready handshake, which can take its full 30s timeout
- * against a stranded worker connection. Boot blocks on the first *delivered*
- * port instead — if the boot channel stalls, worker recovery hands the listener
- * a good port long before that timeout.
- */
-export function firstRepoPort(
-  sw: Awaited<ReturnType<typeof setupServiceWorker>>,
-  onRenewed: (port: MessagePort) => void
-): Promise<MessagePort> {
-  return new Promise<MessagePort>((resolve) => {
-    let seen = false;
-    void sw.subscribeToRepoChannel((port) => {
-      if (seen) return onRenewed(port);
-      seen = true;
-      resolve(port);
-    });
-  });
-}
-
-/** Drop the adapter sitting on the dead worker port, leaving `keep` in place. */
-export function removeAdapterFor(
-  repo: Repo,
-  stale: MessageChannelNetworkAdapter,
-  keep: unknown
-): void {
-  for (const adapter of [...repo.networkSubsystem.adapters]) {
-    if (adapter === keep) continue;
-    // The keyhive wrapper keeps the wrapped adapter on `.networkAdapter`.
-    const base = (adapter as any).networkAdapter ?? adapter;
-    if (base !== stale) continue;
-    try {
-      repo.networkSubsystem.removeNetworkAdapter(adapter as any);
-    } catch (err) {
-      console.error("failed to remove stale worker network adapter", err);
-    }
-  }
-}

package/src/site-kit/index.ts

@@ -13,6 +13,7 @@ export type {
   PatchworkHtmlOptions,
   PatchworkNetlifyOptions,
   PatchworkKeyhiveSyncServer,
+  PatchworkKeyhiveOptions,
   PatchworkSyncServersOptions,
 } from "./options.js";
 

package/src/site-kit/options.ts

@@ -36,19 +36,31 @@ export interface PatchworkNetlifyOptions {
   immutableAssets?: boolean;
 }
 
-type PatchworkPrimarySyncServerOptions =
-  | { subduction?: string; keyhive?: never }
-  | { subduction?: never; keyhive: PatchworkKeyhiveSyncServer };
-
 export type PatchworkKeyhiveSyncServer =
   | "keyhive"
   | "subduction"
   | ({ url: string } & SyncServerIdentity);
 
+export interface PatchworkKeyhiveOptions {
+  /**
+   * Which relay ARK registers and grants access to. Default `"subduction"`.
+   * A custom identity also carries the WebSocket URL to reach it on.
+   */
+  syncServer?: PatchworkKeyhiveSyncServer;
+  /**
+   * Use the `idFactory` ARK injects into the repo config, which derives
+   * document ids from keyhive. Default true. `false` drops it and lets the
+   * Repo generate ids its own way.
+   */
+  useIdFactory?: boolean;
+}
+
 export type PatchworkSyncServersOptions = {
   /** wss:// URL for the legacy automerge-repo sync-server channel (connected on demand via connectClassicSync). Default: wss://sync3.automerge.org. Pass false to skip its preconnect hint. */
   classic?: string | false;
-} & PatchworkPrimarySyncServerOptions;
+  /** wss:// URL for the subduction channel. Default: wss://subduction.sync.inkandswitch.com. Overrides the URL a named `keyhive.syncServer` would otherwise imply. */
+  subduction?: string;
+};
 
 export const DEFAULT_TITLE = "Patchwork";
 
@@ -81,12 +93,15 @@ export interface PatchworkSiteOptions {
   backgroundColor?: string;
 
   /**
-   * Sync-server configuration for this build. Providing `keyhive` enables
-   * keyhive and selects the relay identity ARK grants access to. Custom
-   * identities also require their WebSocket URL. `subduction` and `keyhive`
-   * are mutually exclusive. The live server and `classic` are also emitted as
-   * connection hints. Pass `false` to keep the default servers but skip those
-   * hints.
+   * Enables keyhive for this build. `true` takes every default; an object
+   * picks the relay and turns individual behaviour off. Omitted or `false`
+   * builds a plain subduction repo.
+   */
+  keyhive?: boolean | PatchworkKeyhiveOptions;
+
+  /**
+   * The sync-server URLs for this build. Also emitted as connection hints;
+   * pass `false` to keep the URLs but skip the hints.
    */
   syncServers?: false | PatchworkSyncServersOptions;