@inkandswitch/patchwork-bootloader 0.0.3 → 0.0.5

package/dist/site.js

@@ -0,0 +1,365 @@
+/**
+ * High-level browser-app boot sequence for a Patchwork site.
+ *
+ * Layers on top of {@link setupServiceWorker} (the package default export) to
+ * construct the Repo, wire up the service-worker port, load plugins via the
+ * ModuleWatcher, resolve the user's account document, and hand control to the
+ * configured root tool.
+ *
+ * This entry point pulls in DOM- and plugin-layer dependencies (patchwork
+ * elements, plugins, filesystem) and is intended for use only from a browser
+ * site's `main.ts`. Non-UI consumers should import the package default (which
+ * only does SW registration and port handoff).
+ */
+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";
+// 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 { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
+import { openDocument, registerPatchworkViewElement, } from "@inkandswitch/patchwork-elements";
+import { getRegistry, registerPlugins, resolveAccountHandle, } from "@inkandswitch/patchwork-plugins";
+import * as plugins from "@inkandswitch/patchwork-plugins";
+import setupServiceWorker from "./setup.js";
+import { SwLogReader } from "./sw-logger.js";
+const DEFAULT_REMOTE_STORAGE_ID = "3760df37-a4c6-4f66-9ecd-732039a9385d";
+// 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>\?=[^&?]+)?/;
+/**
+ * Boot a Patchwork browser site.
+ *
+ * Performs the full application-shell setup: service worker + port, Repo,
+ * plugin/module loading, account resolution, URL-hash routing, and dev-console
+ * globals (`window.repo`, `window.patchwork`, `window.uncache`). Returns the
+ * constructed Repo, ModuleWatcher and account handle for sites that want to
+ * do additional wiring after boot.
+ */
+export async function bootPatchworkSite(config) {
+    const defaultModulesUrl = resolveDefaultModulesUrl(config.defaultModulesUrl);
+    // Fetch both Wasm binaries in parallel, then compile
+    const [automergeWasm, subductionWasm] = await Promise.all([
+        fetch("/automerge.wasm").then((r) => r.bytes()),
+        fetch("/subduction.wasm").then((r) => r.bytes()),
+    ]);
+    await initializeWasm(automergeWasm);
+    initSubductionSync(subductionWasm);
+    const repo = new Repo({
+        storage: new IndexedDBStorageAdapter(),
+        async sharePolicy(peerId) {
+            return peerId.includes("service-worker");
+        },
+        enableRemoteHeadsGossiping: true,
+    });
+    repo.subscribeToRemotes(config.remoteStorageIds ?? [DEFAULT_REMOTE_STORAGE_ID]);
+    const sw = await setupServiceWorker();
+    if (!sw)
+        throw new Error("Failed to set up service worker");
+    const net = new MessageChannelNetworkAdapter(sw.port);
+    repo.networkSubsystem.addNetworkAdapter(net);
+    await net.whenReady();
+    installDevConsoleGlobals(repo);
+    registerPatchworkViewElement({ 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, [defaultModulesUrl], onModuleLoaded);
+    const accountDocHandle = await resolveAccountHandle(repo, {
+        storageKey: config.accountStorageKey,
+    });
+    window.accountDocHandle = accountDocHandle;
+    wireModuleSettingsWhenReady(accountDocHandle, moduleWatcher);
+    const rootElement = document.getElementById(config.rootElementId ?? "root");
+    if (!rootElement) {
+        throw new Error(`bootPatchworkSite: no element with id="${config.rootElementId ?? "root"}"`);
+    }
+    primeRootElement(rootElement, accountDocHandle);
+    logToolRegistryWhenLoaded(moduleWatcher);
+    window.patchwork = {
+        repo,
+        modules: moduleWatcher,
+        plugins,
+        accountDocHandle,
+        sw: buildSwLogApi(),
+    };
+    window.uncache = uncache;
+    installHashRouting({
+        rootElement,
+        repo,
+        accountDocHandle,
+        moduleWatcher,
+        titleSuffix: config.titleSuffix,
+    });
+    return { repo, moduleWatcher, accountDocHandle };
+}
+// ─── Internals ──────────────────────────────────────────────────────────
+function resolveDefaultModulesUrl(builtin) {
+    const override = globalThis.localStorage?.getItem("defaultToolsUrl");
+    if (!override)
+        return builtin;
+    if (isValidAutomergeUrl(override)) {
+        if (override !== builtin) {
+            console.info(`using defaultToolsUrl override from localStorage: ${override}`);
+        }
+        return override;
+    }
+    console.warn(`ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`);
+    return builtin;
+}
+function installDevConsoleGlobals(repo) {
+    window.repo = repo;
+    window.Automerge = Automerge;
+    window.AutomergeRepo = AutomergeRepo;
+    window.getRepoChannel = () => {
+        const { port1, port2 } = new MessageChannel();
+        navigator.serviceWorker.controller.postMessage({ type: "port" }, [port2]);
+        return port1;
+    };
+}
+function onModuleLoaded(name, mod) {
+    if (Array.isArray(mod.plugins)) {
+        console.log(`[site] registering ${mod.plugins.length} plugin(s) from ${name.slice(0, 30)}...`, mod.plugins.map((p) => `${p.type}:${p.id}`));
+        registerPlugins(mod.plugins, name);
+    }
+    else {
+        console.warn(`[site] module ${name.slice(0, 30)}... has no plugins array`, Object.keys(mod));
+    }
+}
+/**
+ * The frame lazy-creates `moduleSettingsUrl` on first mount. Watch for it to
+ * appear on the account doc and feed it into the ModuleWatcher so the user's
+ * own tool bundle loads alongside the site default. Idempotent.
+ */
+function wireModuleSettingsWhenReady(accountDocHandle, moduleWatcher) {
+    const wire = () => {
+        const url = accountDocHandle.doc()?.moduleSettingsUrl;
+        if (!url)
+            return;
+        void moduleWatcher.addUrl(url);
+        accountDocHandle.off("change", wire);
+    };
+    wire();
+    if (!accountDocHandle.doc()?.moduleSettingsUrl) {
+        accountDocHandle.on("change", wire);
+    }
+}
+/**
+ * Set initial `tool-id` / `doc-url` attributes on the root `<patchwork-view>`
+ * based on the URL hash (if it specifies a frame override) or the account
+ * doc's configured frame tool + the account doc itself.
+ */
+function primeRootElement(rootElement, accountDocHandle) {
+    rootElement.style.visibility = "hidden";
+    showLoadingAnimation();
+    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 docUrl = docId
+            ? stringifyAutomergeUrl({ documentId: docId })
+            : accountDocHandle.url;
+        rootElement.setAttribute("doc-url", docUrl);
+    }
+    else {
+        rootElement.setAttribute("tool-id", accountDocHandle.doc().frameToolId);
+        rootElement.setAttribute("doc-url", accountDocHandle.url);
+    }
+}
+function logToolRegistryWhenLoaded(moduleWatcher) {
+    moduleWatcher.doneLoading
+        .then(() => {
+        const toolReg = getRegistry("patchwork:tool");
+        const tools = toolReg.all();
+        console.log(`[site] doneLoading: ${tools.length} tools registered:`, tools.map((t) => t.id));
+    })
+        .catch((err) => {
+        console.error("[site] doneLoading rejected:", err);
+    });
+}
+function buildSwLogApi() {
+    return {
+        printLogs: async (n = 200) => {
+            const entries = await SwLogReader.tail(n);
+            for (const e of entries) {
+                const prefix = `[${e.ts}] [${e.level}]`;
+                if (e.data !== undefined)
+                    console.log(prefix, e.msg, e.data);
+                else
+                    console.log(prefix, e.msg);
+            }
+            console.log(`--- ${entries.length} entries ---`);
+        },
+        tailLogs: (n = 200) => SwLogReader.tail(n),
+        exportLogs: () => SwLogReader.exportAll(),
+        clearLogs: () => SwLogReader.clear(),
+    };
+}
+const LOADING_STYLE_ID = "pw-bootloader-loading-styles";
+const LOADING_ELEMENT_ID = "pw-bootloader-loading";
+function showLoadingAnimation() {
+    if (!document.getElementById(LOADING_STYLE_ID)) {
+        const style = document.createElement("style");
+        style.id = LOADING_STYLE_ID;
+        style.textContent = `
+      @keyframes pw-bootloader-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-bootloader-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-bootloader-fading {
+        opacity: 0;
+        animation: none;
+      }
+    `;
+        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);
+}
+function hideLoadingAnimation() {
+    const el = document.getElementById(LOADING_ELEMENT_ID);
+    if (!el)
+        return;
+    el.classList.add("pw-bootloader-fading");
+    setTimeout(() => el.remove(), 700);
+}
+async function uncache(match) {
+    for (const name of await caches.keys()) {
+        const cache = await caches.open(name);
+        for (const request of await cache.keys()) {
+            if (request.url.includes(match)) {
+                cache.delete(request);
+            }
+        }
+    }
+}
+function installHashRouting(params) {
+    const { rootElement, repo, accountDocHandle, moduleWatcher, titleSuffix } = params;
+    rootElement.addEventListener("patchwork:no-tool", (event) => {
+        moduleWatcher.loadSuggestedImportUrl(event.detail.url);
+    });
+    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");
+        if (toolId)
+            params.set("tool", toolId);
+        else
+            params.delete("tool");
+        if (title)
+            params.set("title", title);
+        else
+            params.delete("title");
+        if (type)
+            params.set("type", type);
+        else
+            params.delete("type");
+        window.location.hash = params.toString();
+        try {
+            const docHandle = await repo.find(stringifyAutomergeUrl({ documentId, heads }));
+            const doc = docHandle.doc();
+            const docType = type || doc?.["@patchwork"]?.type;
+            if (!docType)
+                return;
+            const registry = getRegistry("patchwork:datatype");
+            const datatype = await registry.load(docType);
+            if (!datatype)
+                return;
+            const docTitle = datatype.module.getTitle(doc);
+            if (docTitle) {
+                document.title = `${docTitle} | ${titleSuffix}`;
+            }
+        }
+        catch (e) {
+            console.error("Failed to update document title", e);
+        }
+    });
+    let firstMount = true;
+    const reveal = () => {
+        if (!firstMount)
+            return;
+        firstMount = false;
+        rootElement.style.visibility = "visible";
+        hideLoadingAnimation();
+    };
+    rootElement.addEventListener("patchwork:mounted", (event) => {
+        handleHashChange();
+        if (event.target !== rootElement)
+            return;
+        console.info("root element mounted");
+        reveal();
+        // Re-resolve routing after a beat so deep-links from freshly-loaded tools
+        // get a second chance to render.
+        setTimeout(handleHashChange, 1000);
+    });
+    // Failsafe: if nothing ever mounts, reveal the element anyway after 12s so
+    // the user sees *something* rather than a blank page.
+    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 }));
+            }
+            return;
+        }
+        const params = new URLSearchParams(hash);
+        const documentId = params.get("doc");
+        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;
+            if (rootElement.getAttribute("tool-id") !== frame ||
+                rootElement.getAttribute("doc-url") !== docUrl) {
+                rootElement.setAttribute("tool-id", frame);
+                rootElement.setAttribute("doc-url", docUrl);
+            }
+        }
+        if (isValidDocumentId(documentId)) {
+            rootElement.dispatchEvent(new CustomEvent("patchwork:open-document", {
+                detail: {
+                    url: stringifyAutomergeUrl({ documentId, heads }),
+                    toolId,
+                    title,
+                    type,
+                },
+            }));
+        }
+    };
+    window.addEventListener("hashchange", handleHashChange);
+}

package/dist/sw-logger.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Persistent ring-buffer logger for service workers.
+ *
+ * Stores log entries in a dedicated IndexedDB database (`sw-logs`) that is
+ * completely separate from the `automerge` database used by the Repo, so
+ * writes here never contend with storage or hydration transactions.
+ *
+ * Entries are accumulated in memory and batch-flushed to IDB periodically
+ * (every {@link FLUSH_INTERVAL_MS}) or when the buffer reaches
+ * {@link FLUSH_THRESHOLD} entries — whichever comes first.
+ *
+ * The on-disk store is a ring buffer capped at {@link MAX_ENTRIES}. Oldest
+ * entries are pruned on each flush when the cap is exceeded.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { SwLogger } from "./sw-logger.js"
+ *
+ * const log = await SwLogger.open()
+ * log.info("repo initialized")
+ * log.warn("connection dropped", { url })
+ * log.error("sync threw", error)
+ *
+ * // From the SW inspector console:
+ * self.printLogs()         // prints last 200 entries
+ * self.printLogs(5000)     // prints last 5 000 entries
+ * self.tailLogs(100)       // returns last 100 entries as an array
+ * self.exportLogs()        // returns all entries as JSON string
+ * self.clearLogs()         // wipes the log database
+ * ```
+ */
+export interface LogEntry {
+    /** Auto-incremented IDB key (doubles as ordering index). */
+    id?: number;
+    /** ISO-8601 timestamp */
+    ts: string;
+    /** Monotonic high-res timestamp (ms since SW start) */
+    hrt: number;
+    /** Log level */
+    level: "debug" | "info" | "warn" | "error";
+    /** Log message */
+    msg: string;
+    /** Optional structured data (must be cloneable) */
+    data?: unknown;
+}
+export interface SwLoggerInterface {
+    debug(msg: string, data?: unknown): void;
+    info(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+    flush(): Promise<void>;
+    tail(n?: number): Promise<LogEntry[]>;
+    exportAll(): Promise<string>;
+    clear(): Promise<void>;
+    dispose(): void;
+}
+export declare class SwLogger implements SwLoggerInterface {
+    #private;
+    private constructor();
+    /**
+     * Open (or create) the log database and return a ready logger.
+     * If the database cannot be opened (quota, permissions, etc.),
+     * returns a {@link NoopLogger} that writes to the console only.
+     */
+    static open(): Promise<SwLoggerInterface>;
+    debug(msg: string, data?: unknown): void;
+    info(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+    /** Force an immediate flush of the in-memory buffer to IDB. */
+    flush(): Promise<void>;
+    /** Read the last `n` entries (default 200). */
+    tail(n?: number): Promise<LogEntry[]>;
+    /** Return all entries as a JSON string (for copy-paste from console). */
+    exportAll(): Promise<string>;
+    /** Delete all log entries. */
+    clear(): Promise<void>;
+    /** Stop the periodic flush timer. */
+    dispose(): void;
+}
+/**
+ * Read-only accessor for the SW log database.
+ *
+ * Unlike {@link SwLogger}, this class does not hold a persistent IDB
+ * connection — each method opens a fresh connection and closes it after
+ * use. This avoids interfering with the SW's write transactions.
+ *
+ * @example
+ * ```ts
+ * import { SwLogReader } from "@inkandswitch/patchwork-bootloader/sw-logger"
+ *
+ * const last100 = await SwLogReader.tail(100)
+ * const json    = await SwLogReader.exportAll()
+ * await SwLogReader.clear()
+ * ```
+ */
+export declare class SwLogReader {
+    /** Read the last `n` entries (default 200), oldest-first. */
+    static tail(n?: number): Promise<LogEntry[]>;
+    /** Return all entries as a JSON string. */
+    static exportAll(): Promise<string>;
+    /** Delete all log entries. */
+    static clear(): Promise<void>;
+}