@inkandswitch/patchwork 0.0.1

package/build-head.js

@@ -0,0 +1,10 @@
+import { build } from "esbuild";
+
+await build({
+  entryPoints: ["src/head.ts"],
+  bundle: true,
+  format: "iife",
+  outfile: "dist/head.js",
+  platform: "browser",
+  target: "esnext",
+});

package/dist/client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Ambient types for a Patchwork site — reference from vite-env.d.ts:
+ *
+ *   /// <reference types="@inkandswitch/patchwork/client" />
+ *
+ * Pulls in patchwork-elements'/-providers' HTMLElementTagNameMap and JSX
+ * augmentations, declares the vite `define`s every site gets from the
+ * `patchwork()` plugin, and extends ImportMetaEnv with the default-modules
+ * env var.
+ */
+import "@inkandswitch/patchwork-elements";
+import "@inkandswitch/patchwork-providers";
+
+declare global {
+  const __SITE_NAME__: string;
+  const __KEYHIVE__: boolean;
+  const __KEYHIVE_SYNC_SERVER__: boolean;
+
+  interface ImportMetaEnv {
+    /**
+     * Comma-separated list of default tool-manifest sources the shell boots
+     * with. Each entry is an `automerge:` URL or a static `modules.json`
+     * URL. Overridable at runtime via `localStorage.systemPackageListURL`.
+     */
+    readonly PATCHWORK_SYSTEM_PACKAGE_LIST_URL?: string;
+    /**
+     * @deprecated Use {@link ImportMetaEnv.PATCHWORK_SYSTEM_PACKAGE_LIST_URL}.
+     * Retained for backwards compatibility with existing build configs.
+     */
+    readonly VITE_DEFAULT_MODULES?: string;
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+}
+
+export {};

package/dist/global.css

@@ -0,0 +1 @@
+@import "@inkandswitch/patchwork-bootloader/global.css";

package/dist/head.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/head.js

@@ -0,0 +1,52 @@
+"use strict";
+(() => {
+  // ../bootloader/dist/externals-list.js
+  var externals = [
+    "@automerge/automerge",
+    "@automerge/automerge/slim",
+    "@automerge/automerge-repo",
+    "@automerge/automerge-repo/slim",
+    // Port-donation plumbing for WorkerWebSocketEndpoint: tabs spawn the shared
+    // proxy entry and donate its port to the automerge worker (Chrome can't
+    // spawn workers from inside a SharedWorker). See setup.ts/automerge-worker.ts.
+    "@automerge/automerge-repo/worker-port",
+    "@automerge/automerge-repo/subduction-websocket-worker-shared",
+    "@automerge/automerge-repo-network-messagechannel",
+    "@automerge/automerge-repo-network-websocket",
+    "@automerge/automerge-repo-storage-indexeddb",
+    "@automerge/automerge-repo-keyhive",
+    "@automerge/automerge-subduction",
+    "@automerge/automerge-subduction/slim",
+    "@keyhive/keyhive",
+    "@keyhive/keyhive/slim",
+    "@inkandswitch/patchwork-bootloader",
+    "@inkandswitch/patchwork-elements",
+    "@inkandswitch/patchwork-filesystem",
+    "@inkandswitch/patchwork-plugins",
+    "@inkandswitch/patchwork-providers",
+    "@inkandswitch/patchwork",
+    // sad
+    "@codemirror/state",
+    "@codemirror/view",
+    "@codemirror/language",
+    "@codemirror/commands",
+    // rip
+    "solid-js",
+    "solid-js/html",
+    "solid-js/web",
+    "solid-js/h",
+    "solid-js/store",
+    "solid-js/jsx-runtime"
+  ];
+  var externals_list_default = externals;
+
+  // src/head.ts
+  var importmap = { imports: {} };
+  for (const name of externals_list_default) {
+    importmap.imports[name] = `/packages/${name}.js`;
+  }
+  var script = document.createElement("script");
+  script.type = "importmap";
+  script.textContent = JSON.stringify(importmap);
+  document.currentScript ? document.currentScript.after(script) : document.head.appendChild(script);
+})();

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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,
+ * 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`.
+ *
+ * Setup owns page-wide state — the `window.repo`/`window.Automerge`/
+ * `window.AutomergeRepo`/`window.hive` globals, custom-element registration,
+ * document listeners — so it may run only once per page; a second call
+ * throws.
+ *
+ * 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.
+ */
+import { Repo } from "@automerge/vanillajs/slim";
+import type { AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
+import type { Patchwork, PatchworkOptions } from "./types.js";
+declare global {
+    interface Window {
+        patchwork: Patchwork;
+        repo: Repo;
+        Automerge: typeof import("@automerge/automerge");
+        AutomergeRepo: typeof import("@automerge/automerge-repo");
+        hive?: AutomergeRepoKeyhive;
+    }
+}
+export declare function setup(options?: PatchworkOptions): Promise<Patchwork>;
+export default setup;
+export { createRepo, initWasm } from "./repo.js";
+export { createRouter } from "./router.js";
+export { showLoadingAnimation, hideLoadingAnimation, showErrorScreen, } from "./loading.js";
+export type { OpenOptions, Patchwork, PatchworkOptions, ServiceWorkerApi, SignerIdentity, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,294 @@
+/**
+ * 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,
+ * 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`.
+ *
+ * Setup owns page-wide state — the `window.repo`/`window.Automerge`/
+ * `window.AutomergeRepo`/`window.hive` globals, custom-element registration,
+ * document listeners — so it may run only once per page; a second call
+ * throws.
+ *
+ * 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.
+ */
+import { MessageChannelNetworkAdapter, isValidAutomergeUrl, } from "@automerge/vanillajs/slim";
+import * as Automerge from "@automerge/automerge/slim";
+import * as AutomergeRepo from "@automerge/automerge-repo/slim";
+import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
+import { importAutomergePackageViaWorker } from "@inkandswitch/patchwork-bootloader/module-loader";
+import { registerPatchworkViewElement } from "@inkandswitch/patchwork-elements";
+import { registerRepoProviderElement } from "@inkandswitch/patchwork-providers";
+import { createDocOfDatatype2, getRegistry, registerPlugins, resolveAccountHandle, unregisterPlugins, } from "@inkandswitch/patchwork-plugins";
+import * as plugins from "@inkandswitch/patchwork-plugins";
+import setupServiceWorker, { lifecycleLog, } from "@inkandswitch/patchwork-bootloader";
+import debug from "debug";
+import { createRepo, firstRepoPort, initWasm, removeAdapterFor, } from "./repo.js";
+import { createRouter } from "./router.js";
+const log = debug("patchwork:setup");
+// ── Setup ────────────────────────────────────────────────────────────────
+let setupCalled = false;
+export function setup(options = {}) {
+    if (setupCalled) {
+        throw new Error("patchwork.setup: already called — setup owns page-wide state and may run only once");
+    }
+    setupCalled = true;
+    const done = doSetup(options);
+    void done.then(() => log("patchwork setup complete"));
+    const timeout = options.timeout ?? 30_000;
+    if (timeout === false)
+        return done;
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`patchwork.setup: boot did not finish within ${timeout}ms`)), timeout);
+    });
+    done.then(() => clearTimeout(timer), () => clearTimeout(timer));
+    return Promise.race([done, deadline]);
+}
+export default setup;
+async function doSetup(options) {
+    const siteName = options.name ??
+        (typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "patchwork");
+    const moduleSources = resolveDefaultModules(options);
+    const routing = options.routing ?? "hash";
+    log("booting", options);
+    installLifecycleLogging();
+    if (!options.repo)
+        await initWasm();
+    const sw = await setupServiceWorker();
+    if (!sw)
+        throw new Error("Failed to set up service worker");
+    log("workers ready");
+    let hive;
+    let repo;
+    let signerIdentity;
+    // Called with a fresh port when the automerge worker dies and is recreated.
+    // Assigned once the repo exists.
+    let onWorkerPortRenewed;
+    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(options, siteName, 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, false, false, 2000)
+                : fresh;
+            repo.networkSubsystem.addNetworkAdapter(registered);
+            removeAdapterFor(repo, workerAdapter, registered);
+            workerAdapter = fresh;
+            lifecycleLog("repo re-wired to the recreated automerge worker");
+        };
+    }
+    // Dev-console / tool-runtime globals (e2e and loaded tools read these). The
+    // `window.patchwork` handle is deliberately not set here — the caller does
+    // `window.patchwork = await setup(...)`.
+    window.repo = repo;
+    window.Automerge = Automerge;
+    window.AutomergeRepo =
+        AutomergeRepo;
+    if (hive)
+        window.hive = hive;
+    await repo.networkSubsystem.whenReady();
+    log("networkSubsystem ready");
+    hive?.networkAdapter?.syncKeyhive?.();
+    registerRepoProviderElement(repo);
+    const rootElementId = options.rootElementId ?? "root";
+    const rootElement = document.getElementById(rootElementId);
+    if (!rootElement) {
+        throw new Error(`patchwork.setup: no element with id="${rootElementId}"`);
+    }
+    // `<repo-provider>` sits above the root and answers `repo:handle-descriptor`
+    // for any view outside a remapper, resolving to the requested url unchanged.
+    // Generated site html already declares it around the root; wrap only
+    // hand-written markup that lacks one.
+    if (!rootElement.closest("repo-provider")) {
+        const repoProvider = document.createElement("repo-provider");
+        rootElement.parentElement.insertBefore(repoProvider, rootElement);
+        repoProvider.appendChild(rootElement);
+    }
+    registerPatchworkViewElement({ hive, repo });
+    // Started with the site bundle alone so resolveAccountHandle has something to
+    // await on — the `account` datatype lives there. The user's own
+    // module-settings URL is added lazily once it appears on the account doc.
+    const moduleWatcher = new ModuleWatcher(repo, nameSources(moduleSources), onModuleLoaded, unregisterPlugins, 
+    // Discover an Automerge package's plugin descriptors off the main thread;
+    // each plugin's load() re-imports the package (at heads) on this thread.
+    importAutomergePackageViaWorker);
+    const accountDocHandle = (await resolveAccountHandle(repo, {
+        storageKey: options.accountKey ?? "patchworkAccountURL",
+        hive,
+    }));
+    wireModuleSettings(accountDocHandle, moduleWatcher);
+    let router;
+    if (routing !== false) {
+        rootElement.style.visibility = "hidden";
+        router = createRouter({
+            rootElement,
+            repo,
+            accountDocHandle,
+            siteName,
+        });
+    }
+    const toolsLoaded = moduleWatcher.doneLoading.then(() => log("doneLoading, tools registered:", getRegistry("patchwork:tool")
+        .all()
+        .map((t) => t.id)), (err) => console.error("doneLoading rejected:", err));
+    installReveal(rootElement, router, toolsLoaded);
+    return {
+        repo,
+        hive,
+        account: accountDocHandle,
+        signer: signerIdentity,
+        packages: moduleWatcher,
+        plugins,
+        sw: {
+            connectClassicSync: sw.connectClassicSync,
+            subscribeToRepoChannel: sw.subscribeToRepoChannel,
+            subscribeSyncState: sw.subscribeSyncState,
+        },
+        async create(type, init) {
+            const datatype = await getRegistry("patchwork:datatype").load(type);
+            if (!datatype) {
+                throw new Error(`patchwork.create: no datatype registered for "${type}"`);
+            }
+            return createDocOfDatatype2(datatype, repo, init, hive);
+        },
+        open(url, openOptions = {}) {
+            rootElement.dispatchEvent(new CustomEvent("patchwork:open-document", {
+                detail: {
+                    url,
+                    toolId: openOptions.tool,
+                    type: openOptions.type,
+                    title: openOptions.title,
+                },
+            }));
+        },
+        find(url) {
+            return repo.find(url);
+        },
+    };
+}
+// ── Reveal / mount ───────────────────────────────────────────────────────
+function installReveal(rootElement, router, toolsLoaded) {
+    let revealed = false;
+    const reveal = () => {
+        if (revealed)
+            return;
+        revealed = true;
+        rootElement.style.visibility = "visible";
+    };
+    rootElement.addEventListener("patchwork:mounted", (event) => {
+        if (event.target !== rootElement)
+            return;
+        log("root element mounted");
+        if (router) {
+            void router.route();
+            // Deep-links into tools that were still loading get routed again once
+            // every module has registered.
+            void toolsLoaded.then(() => router.route());
+        }
+        reveal();
+    });
+    // If nothing ever mounts, reveal anyway so the user sees something rather
+    // than a blank page.
+    setTimeout(reveal, 12_000);
+}
+// ── Module sources ───────────────────────────────────────────────────────
+function isValidModuleSource(source) {
+    return isValidAutomergeUrl(source) || /^(https?:\/\/|\.?\/)/.test(source);
+}
+/**
+ * The site's default module-list sources, honouring the
+ * `localStorage.systemPackageListURL` dev override, which replaces the entire
+ * built-in bundle.
+ */
+function resolveDefaultModules(options) {
+    const configured = options.packageListURL ?? [];
+    const builtin = (Array.isArray(configured) ? configured : [configured]).filter(Boolean);
+    const override = globalThis.localStorage?.getItem("systemPackageListURL");
+    if (override && isValidModuleSource(override)) {
+        console.info(`using systemPackageListURL from localStorage: ${override}`);
+        return [override];
+    }
+    if (override) {
+        console.warn(`ignoring invalid systemPackageListURL in localStorage: ${override}`);
+    }
+    if (builtin.length === 0) {
+        throw new Error("patchwork.setup: no default module sources configured (set `packageListURL`)");
+    }
+    return builtin;
+}
+/**
+ * Name the sources for the ModuleWatcher. The first keeps the canonical
+ * `system` name; the rest get suffixed. None may be `user`, which is reserved
+ * for the per-account settings doc and has branch-override precedence.
+ */
+function nameSources(sources) {
+    return Object.fromEntries(sources.map((source, i) => [i === 0 ? "system" : `system-${i}`, source]));
+}
+function onModuleLoaded(name, mod) {
+    if (!Array.isArray(mod.plugins)) {
+        console.warn(`module ${name} has no plugins array`, Object.keys(mod));
+        return;
+    }
+    log(`registering ${mod.plugins.length} plugin(s) from ${name}`, mod.plugins.map((p) => `${p.type}:${p.id}`));
+    registerPlugins(mod.plugins, name);
+}
+/**
+ * The frame lazy-creates `moduleSettingsUrl` on first mount, so watch for it to
+ * appear and feed it to the ModuleWatcher.
+ */
+function wireModuleSettings(accountDocHandle, moduleWatcher) {
+    const wire = () => {
+        const url = accountDocHandle.doc()?.moduleSettingsUrl;
+        if (!url)
+            return;
+        void moduleWatcher.addUrl("user", url);
+        accountDocHandle.off("change", wire);
+    };
+    wire();
+    if (!accountDocHandle.doc()?.moduleSettingsUrl) {
+        accountDocHandle.on("change", wire);
+    }
+}
+/** Page Lifecycle and connectivity transitions, to line up against the
+ * SharedWorker's sync-socket reaps. */
+function installLifecycleLogging() {
+    if (typeof document === "undefined")
+        return;
+    const opts = { capture: true };
+    const persisted = (e) => e.persisted;
+    document.addEventListener("visibilitychange", () => lifecycleLog("visibilitychange → %s", document.visibilityState), opts);
+    document.addEventListener("freeze", () => lifecycleLog("freeze (tab suspended)"), opts);
+    document.addEventListener("resume", () => lifecycleLog("resume (tab unsuspended)"), opts);
+    window.addEventListener("pageshow", (e) => lifecycleLog("pageshow persisted=%s", persisted(e)), opts);
+    window.addEventListener("pagehide", (e) => lifecycleLog("pagehide persisted=%s", persisted(e)), opts);
+    window.addEventListener("online", () => lifecycleLog("online"), opts);
+    window.addEventListener("offline", () => lifecycleLog("offline"), opts);
+    lifecycleLog("logging installed (visibilityState=%s, hasFocus=%s)", document.visibilityState, document.hasFocus());
+}
+// ── Named exports ────────────────────────────────────────────────────────
+export { createRepo, initWasm } from "./repo.js";
+export { createRouter } from "./router.js";
+export { showLoadingAnimation, hideLoadingAnimation, showErrorScreen, } from "./loading.js";

package/dist/loading.d.ts

@@ -0,0 +1,5 @@
+export declare function showLoadingAnimation(): void;
+export declare function hideLoadingAnimation(): void;
+export declare function showErrorScreen(error: unknown, options?: {
+    contact?: string;
+}): void;

package/dist/loading.js

@@ -0,0 +1,125 @@
+const LOADING_ELEMENT_ID = "pw-loading";
+const LOADING_STYLE_ID = "pw-loading-styles";
+const LOADING_CSS = `
+  @keyframes pw-loading-pulse {
+    0%, 100% { opacity: 0.25; }
+    50% { opacity: 0.95; }
+  }
+  #${LOADING_ELEMENT_ID} {
+    position: fixed;
+    inset: 0;
+    z-index: 0;
+    pointer-events: none;
+    background-color: #fff;
+    background-image:
+      radial-gradient(ellipse 55% 45% at 28% 35%, #fde4ec, transparent 70%),
+      radial-gradient(ellipse 50% 55% at 72% 65%, #e0f0fb, transparent 70%),
+      radial-gradient(ellipse 65% 55% at 50% 50%, #f1e6f6, transparent 80%);
+    animation: pw-loading-pulse 3.5s ease-in-out infinite;
+    transition: opacity 0.6s ease-out;
+  }
+  @media (prefers-color-scheme: dark) {
+    #${LOADING_ELEMENT_ID} {
+      background-color: #000;
+      background-image:
+        radial-gradient(ellipse 55% 45% at 28% 35%, #2a1d33, transparent 70%),
+        radial-gradient(ellipse 50% 55% at 72% 65%, #1a2738, transparent 70%),
+        radial-gradient(ellipse 65% 55% at 50% 50%, #221a2e, transparent 80%);
+    }
+  }
+  #${LOADING_ELEMENT_ID}.pw-loading-fading {
+    opacity: 0;
+    animation: none;
+  }
+`;
+export function showLoadingAnimation() {
+    if (!document.getElementById(LOADING_STYLE_ID)) {
+        const style = document.createElement("style");
+        style.id = LOADING_STYLE_ID;
+        style.textContent = LOADING_CSS;
+        document.head.appendChild(style);
+    }
+    if (document.getElementById(LOADING_ELEMENT_ID))
+        return;
+    const el = document.createElement("div");
+    el.id = LOADING_ELEMENT_ID;
+    document.body.appendChild(el);
+}
+export function hideLoadingAnimation() {
+    const el = document.getElementById(LOADING_ELEMENT_ID);
+    if (!el)
+        return;
+    el.classList.add("pw-loading-fading");
+    setTimeout(() => el.remove(), 700);
+}
+const ERROR_ELEMENT_ID = "pw-error";
+const ERROR_CSS = `
+  #${ERROR_ELEMENT_ID} {
+    position: fixed;
+    inset: 0;
+    z-index: 1;
+    overflow: auto;
+    padding: 3rem 1.5rem;
+    background: #fff;
+    color: #1a1a1a;
+    font: 1rem/1.5 system-ui, sans-serif;
+  }
+  #${ERROR_ELEMENT_ID} > div {
+    max-width: 38rem;
+    margin: 0 auto;
+  }
+  #${ERROR_ELEMENT_ID} h1 {
+    font-size: 1.25rem;
+    margin: 0 0 1rem;
+  }
+  #${ERROR_ELEMENT_ID} pre {
+    padding: 1rem;
+    border-radius: 0.5rem;
+    background: #f4f0f2;
+    overflow: auto;
+    white-space: pre-wrap;
+    font-size: 0.8125rem;
+  }
+  @media (prefers-color-scheme: dark) {
+    #${ERROR_ELEMENT_ID} {
+      background: #111;
+      color: #eee;
+    }
+    #${ERROR_ELEMENT_ID} pre {
+      background: #221a2e;
+    }
+    #${ERROR_ELEMENT_ID} a {
+      color: #9cc8f0;
+    }
+  }
+`;
+export function showErrorScreen(error, options = {}) {
+    hideLoadingAnimation();
+    if (document.getElementById(ERROR_ELEMENT_ID))
+        return;
+    const style = document.createElement("style");
+    style.textContent = ERROR_CSS;
+    document.head.appendChild(style);
+    const screen = document.createElement("div");
+    screen.id = ERROR_ELEMENT_ID;
+    const inner = document.createElement("div");
+    screen.appendChild(inner);
+    const heading = document.createElement("h1");
+    heading.textContent = "Something went wrong starting this site";
+    inner.appendChild(heading);
+    const detail = document.createElement("pre");
+    detail.textContent =
+        error instanceof Error ? (error.stack ?? error.message) : String(error);
+    inner.appendChild(detail);
+    const advice = document.createElement("p");
+    advice.append("Reloading the page may help. If it keeps happening");
+    if (options.contact) {
+        const link = document.createElement("a");
+        link.href = `mailto:${options.contact}`;
+        link.textContent = options.contact;
+        advice.append(", email ", link);
+    }
+    advice.append(".");
+    inner.appendChild(advice);
+    document.body.appendChild(screen);
+}

package/dist/repo.d.ts

@@ -0,0 +1,25 @@
+import { MessageChannelNetworkAdapter, Repo } from "@automerge/vanillajs/slim";
+import { type AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
+import setupServiceWorker from "@inkandswitch/patchwork-bootloader";
+import type { SignerIdentity } from "./types.js";
+export declare function initWasm(): Promise<void>;
+export declare function createRepo(config: {
+    keyhive?: boolean;
+}, siteName: string, workerAdapter: MessageChannelNetworkAdapter): Promise<{
+    repo: Repo;
+    hive?: AutomergeRepoKeyhive;
+    signerIdentity?: 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 declare function firstRepoPort(sw: Awaited<ReturnType<typeof setupServiceWorker>>, onRenewed: (port: MessagePort) => void): Promise<MessagePort>;
+/** Drop the adapter sitting on the dead worker port, leaving `keep` in place. */
+export declare function removeAdapterFor(repo: Repo, stale: MessageChannelNetworkAdapter, keep: unknown): void;