@inkandswitch/patchwork 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+import type { AutomergeUrl, DocHandle, Repo } from "@automerge/vanillajs/slim";
+import type { AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
+import type { ModuleWatcher, HasPatchworkMetadata } from "@inkandswitch/patchwork-filesystem";
+import type { AccountDoc } from "@inkandswitch/patchwork-plugins";
+import type { ServiceWorkerRepoChannelListener, SyncStateDocMessage } from "@inkandswitch/patchwork-bootloader/types";
+import type * as pluginsNS from "@inkandswitch/patchwork-plugins";
+export type PluginsApi = typeof pluginsNS;
+export type SignerIdentity = {
+    peerId: string;
+    verifyingKey: string;
+};
+export interface ServiceWorkerApi {
+    connectClassicSync: (server?: string) => Promise<void>;
+    subscribeToRepoChannel: (listener: ServiceWorkerRepoChannelListener) => Promise<() => void>;
+    subscribeSyncState: (documentId: string, listener: (update: SyncStateDocMessage) => void) => () => void;
+}
+export interface OpenOptions {
+    tool?: string;
+    type?: string;
+    title?: string;
+}
+export interface PatchworkOptions {
+    /**
+     * 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.
+     *
+     * Overridable at runtime with `localStorage.systemPackageListURL`.
+     */
+    packageListURL?: string | string[];
+    /**
+     * `localStorage` key under which this site remembers which account document
+     * belongs to the current user. Defaults to `"patchworkAccountURL"`. Sites
+     * sharing an origin MUST use distinct keys so they do not clobber each
+     * other's accounts.
+     */
+    accountKey?: string;
+    /**
+     * Brand word for this site: appended to the document title as
+     * `"<doc> | <name>"` when a document is open (the separator is provided
+     * for you), and used to namespace this site's storage and peer ids.
+     *
+     * Defaults to the build-time `__SITE_NAME__` define, then `"patchwork"`.
+     */
+    name?: string;
+    /** DOM id of the `<patchwork-view>` hosting the root tool. Defaults to "root". */
+    rootElementId?: string;
+    /**
+     * Initialize keyhive for access control. The Repo then uses keyhive's network
+     * adapter, peerId and idFactory instead of a sharePolicy.
+     */
+    keyhive?: boolean;
+    /**
+     * Bring your own Repo. When provided, setup skips wasm initialization and
+     * repo creation entirely — you are responsible for having initialized
+     * automerge/subduction and wired the automerge-worker port yourself.
+     */
+    repo?: Repo;
+    /** The keyhive instance accompanying a provided {@link PatchworkOptions.repo}. */
+    hive?: AutomergeRepoKeyhive;
+    /**
+     * How document navigation maps onto the URL. `"hash"` (the default) drives
+     * the root view from `location.hash`. `false` installs no router — call
+     * `patchwork.open()` directly.
+     */
+    routing?: "hash" | false;
+    /**
+     * Milliseconds before the promise `setup()` returned rejects because boot
+     * hasn't finished — so a hang (service worker stuck, sync unreachable)
+     * surfaces as an error a site can show instead of blank space. The boot
+     * itself is not cancelled and may still complete in the background.
+     * Defaults to 30 seconds; `false` disables the deadline.
+     */
+    timeout?: number | false;
+}
+/**
+ * The site runtime `setup()` resolves with — what a site assigns to
+ * `window.patchwork`. Plain fields: it exists only once setup has finished,
+ * so every member is always usable.
+ */
+export interface Patchwork {
+    readonly repo: Repo;
+    readonly hive?: AutomergeRepoKeyhive;
+    readonly account: DocHandle<AccountDoc>;
+    readonly signer?: SignerIdentity;
+    create<D>(type: string, init?: (doc: D) => void): Promise<DocHandle<D & HasPatchworkMetadata>>;
+    open(url: AutomergeUrl, options?: OpenOptions): void;
+    find<D>(url: AutomergeUrl): Promise<DocHandle<D>>;
+    readonly packages: ModuleWatcher;
+    readonly plugins: PluginsApi;
+    readonly sw: ServiceWorkerApi;
+}

package/dist/types.js

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

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

@@ -0,0 +1,12 @@
+import type { Plugin } from "vite";
+import wasm from "vite-plugin-wasm";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/**
+ * Owns envPrefix, define (__SITE_NAME__/__KEYHIVE__/__KEYHIVE_SYNC_SERVER__),
+ * server/preview CORS defaults, worker format + the wasm plugin, and build
+ * defaults (firefox150 target, unminified, sourcemapped) — everything a site
+ * used to hand-write in its own vite.config.ts. Each is switched off
+ * individually via the matching `false` option.
+ */
+export declare function configPlugin(options?: PatchworkVitePluginOptions): Plugin;
+export { wasm };

package/dist/vite/config-plugin.js

@@ -0,0 +1,70 @@
+import wasm from "vite-plugin-wasm";
+const CORS_HEADERS = { "Access-Control-Allow-Origin": "*" };
+/**
+ * Owns envPrefix, define (__SITE_NAME__/__KEYHIVE__/__KEYHIVE_SYNC_SERVER__),
+ * server/preview CORS defaults, worker format + the wasm plugin, and build
+ * defaults (firefox150 target, unminified, sourcemapped) — everything a site
+ * used to hand-write in its own vite.config.ts. Each is switched off
+ * individually via the matching `false` option.
+ */
+export function configPlugin(options = {}) {
+    return {
+        name: "@patchwork/config",
+        config() {
+            const define = {
+                __KEYHIVE__: JSON.stringify(options.keyhive ?? false),
+                __KEYHIVE_SYNC_SERVER__: JSON.stringify(options.keyhiveSyncServer ?? false),
+            };
+            if (options.siteName) {
+                define.__SITE_NAME__ = JSON.stringify(options.siteName);
+            }
+            return {
+                envPrefix: ["VITE_", "PATCHWORK_"],
+                define,
+                server: options.server === false
+                    ? undefined
+                    : {
+                        headers: CORS_HEADERS,
+                        ...options.server,
+                    },
+                preview: options.preview === false
+                    ? undefined
+                    : {
+                        port: process.env.PORT ? +process.env.PORT : 5173,
+                        headers: CORS_HEADERS,
+                        ...options.preview,
+                    },
+                worker: options.worker === false
+                    ? undefined
+                    : {
+                        format: options.worker?.format ?? "es",
+                        plugins: () => [wasm()],
+                    },
+                build: {
+                    target: "firefox150",
+                    minify: false,
+                    sourcemap: true,
+                    ...options.build,
+                },
+            };
+        },
+        // The shared automerge-worker's chunk imports bypass the page's service
+        // worker, so offline boot needs the browser's HTTP cache to serve them
+        // without revalidating. Content hashes make that safe; a new build gets
+        // new URLs. Production gets this from the generated _headers file — vite
+        // preview doesn't read that, so mirror it here.
+        configurePreviewServer(server) {
+            if (options.netlify === false ||
+                options.netlify?.immutableAssets === false) {
+                return;
+            }
+            server.middlewares.use((req, res, next) => {
+                if (req.url?.startsWith("/assets/")) {
+                    res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+                }
+                next();
+            });
+        },
+    };
+}
+export { wasm };

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

@@ -0,0 +1,11 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/**
+ * Vite's html build step (`vite:build-html`) is a normal `transform` hook
+ * filtered on `id: /\.html$/` — it doesn't require a real file, just an id
+ * that *looks like* one under root (that's all `path.relative(root, id)`,
+ * which decides the output filename, cares about). So this is a plain
+ * virtual module: `resolveId` claims the one id we care about, `load`
+ * returns the generated string — nothing ever touches disk.
+ */
+export declare function htmlPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/html-plugin.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { buildHtml } from "../site-kit/html.js";
+const GENERATED_PATH = "index.html";
+/**
+ * Vite's html build step (`vite:build-html`) is a normal `transform` hook
+ * filtered on `id: /\.html$/` — it doesn't require a real file, just an id
+ * that *looks like* one under root (that's all `path.relative(root, id)`,
+ * which decides the output filename, cares about). So this is a plain
+ * virtual module: `resolveId` claims the one id we care about, `load`
+ * returns the generated string — nothing ever touches disk.
+ */
+export function htmlPlugin(options = {}) {
+    if (options.html === false)
+        return null;
+    const html = buildHtml(options);
+    let entryId;
+    return {
+        name: "@patchwork/html",
+        enforce: "pre",
+        config(config) {
+            const root = resolve(config.root ?? process.cwd());
+            entryId = resolve(root, GENERATED_PATH);
+            return {
+                build: { rollupOptions: { input: entryId } },
+            };
+        },
+        resolveId(source) {
+            if (source === entryId)
+                return entryId;
+        },
+        load(id) {
+            if (id === entryId)
+                return html;
+        },
+        configureServer: {
+            order: "pre",
+            handler(server) {
+                server.middlewares.use(async (req, res, next) => {
+                    if (req.url !== "/" && req.url !== "/index.html") {
+                        next();
+                        return;
+                    }
+                    const transformed = await server.transformIndexHtml(req.url, html, req.originalUrl);
+                    res.statusCode = 200;
+                    res.setHeader("Content-Type", "text/html");
+                    res.end(transformed);
+                });
+            },
+        },
+    };
+}

package/dist/vite/icons.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/** Emits the rendered icon PNGs for build, and serves the same buffers for dev. */
+export declare function iconsPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/icons.js

@@ -0,0 +1,42 @@
+import { resolve } from "node:path";
+import { getIcons } from "../site-kit/icons.js";
+/** Emits the rendered icon PNGs for build, and serves the same buffers for dev. */
+export function iconsPlugin(options = {}) {
+    if (!options.icons)
+        return null;
+    const { source } = options.icons;
+    let sourcePath;
+    let isBuild = false;
+    return {
+        name: "@patchwork/icons",
+        configResolved(config) {
+            isBuild = config.command === "build";
+            sourcePath = resolve(config.root, source);
+        },
+        async buildStart() {
+            if (!isBuild)
+                return;
+            const icons = await getIcons(sourcePath);
+            for (const [fileName, buffer] of icons) {
+                this.emitFile({ type: "asset", fileName, source: buffer });
+            }
+        },
+        configureServer(server) {
+            server.middlewares.use(async (req, res, next) => {
+                const fileName = req.url?.replace(/^\//, "");
+                if (!fileName) {
+                    next();
+                    return;
+                }
+                const icons = await getIcons(sourcePath);
+                const buffer = icons.get(fileName);
+                if (!buffer) {
+                    next();
+                    return;
+                }
+                res.setHeader("Content-Type", "image/png");
+                res.end(buffer);
+            });
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+export declare const builtins: Record<string, string>;
+export declare function importmap(options?: PatchworkVitePluginOptions): Plugin;

package/dist/vite/importmap-plugin.js

@@ -0,0 +1,83 @@
+import { fileURLToPath } from "node:url";
+/**
+ * bootloader owns resolving/emitting its own dependencies (it's the one that
+ * actually has automerge/keyhive/codemirror/solid/the other patchwork-*
+ * packages as real dependencies) — reused here rather than duplicated.
+ */
+import externals, { resolveExternal, emitWasmAssets, } from "@inkandswitch/patchwork-bootloader/externals";
+export const builtins = externals.reduce((builtins, name) => ((builtins[name] = `/packages/${name}.js`), builtins), {});
+// This package importmaps itself too, so tool code loaded at runtime can
+// bare-import it just like the other @inkandswitch/patchwork-* packages.
+builtins["@inkandswitch/patchwork"] = "/packages/@inkandswitch/patchwork.js";
+/**
+ * Node resolves a package's own name from within its own source when its
+ * package.json has "exports" (self-reference) — the same mechanism
+ * @inkandswitch/patchwork-bootloader already relies on to list itself among
+ * its own externals. Anchoring at *this* file (which lives inside
+ * @inkandswitch/patchwork's own installed directory) makes that
+ * self-reference resolve to this package instead of bootloader's.
+ */
+const self = fileURLToPath(import.meta.url);
+async function resolveSelf(name) {
+    const resolved = await this.resolve(name, self, { skipSelf: true });
+    if (!resolved) {
+        throw new Error(`@inkandswitch/patchwork: couldn't resolve "${name}" from its own package.`);
+    }
+    return resolved.id;
+}
+function resolveBuiltin(context, id) {
+    return id === "@inkandswitch/patchwork"
+        ? resolveSelf.call(context, id)
+        : resolveExternal.call(context, id);
+}
+function createImportMap(options) {
+    const importmap = structuredClone(options?.importmap ?? { imports: {}, scopes: {} });
+    importmap.imports ??= {};
+    importmap.scopes ??= {};
+    Object.assign(importmap.imports, builtins);
+    return { importmap, builtins };
+}
+export function importmap(options) {
+    const { importmap, builtins } = createImportMap(options);
+    return {
+        name: "@patchwork/vite",
+        async buildStart() {
+            for (const [id, fileName] of Object.entries(builtins)) {
+                this.emitFile({
+                    type: "chunk",
+                    fileName: fileName.slice(1),
+                    id: await resolveBuiltin(this, id),
+                    preserveSignature: "strict",
+                });
+            }
+            // Emitted so the service worker can fetch them
+            emitWasmAssets.call(this);
+        },
+        async resolveId(id) {
+            if (id in builtins) {
+                // point the site's own imports at the same copy we emit as a chunk,
+                // otherwise rollup bundles a second one out of the site's node_modules
+                // and you end up with two automerges racing to init the same wasm
+                return resolveBuiltin(this, id);
+            }
+            if (id in importmap.imports) {
+                return { id: importmap.imports[id], external: true };
+            }
+        },
+        transformIndexHtml: {
+            order: "pre",
+            handler(html) {
+                return {
+                    html,
+                    tags: [
+                        {
+                            tag: "script",
+                            attrs: { type: "importmap" },
+                            children: JSON.stringify(importmap, null, 2),
+                        },
+                    ],
+                };
+            },
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/** Emits manifest.webmanifest for build and serves it for dev, from the same generated object. */
+export declare function manifestPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/manifest-plugin.js

@@ -0,0 +1,34 @@
+import { buildManifest } from "../site-kit/manifest.js";
+/** Emits manifest.webmanifest for build and serves it for dev, from the same generated object. */
+export function manifestPlugin(options = {}) {
+    if (options.manifest === false)
+        return null;
+    const manifest = buildManifest(options);
+    const source = JSON.stringify(manifest, null, 2);
+    let isBuild = false;
+    return {
+        name: "@patchwork/manifest",
+        configResolved(config) {
+            isBuild = config.command === "build";
+        },
+        buildStart() {
+            if (!isBuild)
+                return;
+            this.emitFile({
+                type: "asset",
+                fileName: "manifest.webmanifest",
+                source,
+            });
+        },
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url !== "/manifest.webmanifest") {
+                    next();
+                    return;
+                }
+                res.setHeader("Content-Type", "application/manifest+json");
+                res.end(source);
+            });
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/**
+ * Netlify's _headers/_redirects are only meaningful on an actual Netlify
+ * deploy, so this only runs for the production build — no dev middleware.
+ * The Link header shares its sync-server/wasm-asset lists with html-plugin
+ * so the two never drift out of sync with each other.
+ */
+export declare function netlifyPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/netlify-plugin.js

@@ -0,0 +1,29 @@
+import { buildHeaders, REDIRECTS } from "../site-kit/netlify.js";
+/**
+ * Netlify's _headers/_redirects are only meaningful on an actual Netlify
+ * deploy, so this only runs for the production build — no dev middleware.
+ * The Link header shares its sync-server/wasm-asset lists with html-plugin
+ * so the two never drift out of sync with each other.
+ */
+export function netlifyPlugin(options = {}) {
+    if (options.netlify === false)
+        return null;
+    const headers = buildHeaders(options);
+    let isBuild = false;
+    return {
+        name: "@patchwork/netlify",
+        configResolved(config) {
+            isBuild = config.command === "build";
+        },
+        buildStart() {
+            if (!isBuild)
+                return;
+            this.emitFile({ type: "asset", fileName: "_headers", source: headers });
+            this.emitFile({
+                type: "asset",
+                fileName: "_redirects",
+                source: REDIRECTS,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+import type { Plugin, ServerOptions, PreviewOptions, BuildOptions } from "vite";
+import type { PatchworkSiteOptions } from "../site-kit/options.js";
+/**
+ * The patchwork vite plugin. A site's vite.config.ts can shrink down to
+ * `plugins: [patchwork({...})]` plus a single source icon file — this plugin
+ * owns the wasm plugin, the importmap/service-worker emission, the generated
+ * index.html/manifest.webmanifest/Netlify _headers+_redirects, the site's
+ * icon set, and vite's server/preview/worker/build/define config.
+ *
+ * Each generated piece is switched off individually by passing `false` for
+ * its option (`html: false`, `manifest: false`, `netlify: false`,
+ * `icons: false`, `server: false`, `preview: false`, `worker: false`).
+ *
+ * `server`/`preview`/`worker`/`build`/`define` are owned by this plugin's
+ * `config()` hook and driven entirely by these options — don't also set them
+ * in the site's own `defineConfig({...})` alongside `patchwork()`, since
+ * Vite's plugin-config merge order doesn't guarantee which one wins.
+ *
+ * Most of what this plugin does — icon rendering, and building the
+ * index.html/manifest.webmanifest/Netlify _headers content — has no vite
+ * dependency at all; see `../site-kit/index.ts` for those pieces reused by
+ * a different bundler adapter.
+ */
+export default function patchwork(options?: PatchworkVitePluginOptions): Plugin<any>[];
+type Imports = {
+    [name: string]: string;
+};
+export type ImportMap = {
+    imports: Imports;
+    scopes?: {
+        [scope: string]: Imports;
+    };
+};
+export type { PatchworkSiteOptions, PatchworkIconsOptions, PatchworkHtmlOptions, PatchworkNetlifyOptions, PatchworkSyncServersOptions, } from "../site-kit/options.js";
+export interface PatchworkVitePluginOptions extends PatchworkSiteOptions {
+    importmap?: ImportMap;
+    server?: false | ServerOptions;
+    preview?: false | PreviewOptions;
+    worker?: false | {
+        format?: "es" | "iife";
+    };
+    build?: BuildOptions;
+}

package/dist/vite/patchwork-plugin.js

@@ -0,0 +1,40 @@
+import { importmap } from "./importmap-plugin.js";
+import { serviceworker } from "./service-worker-plugin.js";
+import { configPlugin, wasm } from "./config-plugin.js";
+import { iconsPlugin } from "./icons.js";
+import { htmlPlugin } from "./html-plugin.js";
+import { manifestPlugin } from "./manifest-plugin.js";
+import { netlifyPlugin } from "./netlify-plugin.js";
+/**
+ * The patchwork vite plugin. A site's vite.config.ts can shrink down to
+ * `plugins: [patchwork({...})]` plus a single source icon file — this plugin
+ * owns the wasm plugin, the importmap/service-worker emission, the generated
+ * index.html/manifest.webmanifest/Netlify _headers+_redirects, the site's
+ * icon set, and vite's server/preview/worker/build/define config.
+ *
+ * Each generated piece is switched off individually by passing `false` for
+ * its option (`html: false`, `manifest: false`, `netlify: false`,
+ * `icons: false`, `server: false`, `preview: false`, `worker: false`).
+ *
+ * `server`/`preview`/`worker`/`build`/`define` are owned by this plugin's
+ * `config()` hook and driven entirely by these options — don't also set them
+ * in the site's own `defineConfig({...})` alongside `patchwork()`, since
+ * Vite's plugin-config merge order doesn't guarantee which one wins.
+ *
+ * Most of what this plugin does — icon rendering, and building the
+ * index.html/manifest.webmanifest/Netlify _headers content — has no vite
+ * dependency at all; see `../site-kit/index.ts` for those pieces reused by
+ * a different bundler adapter.
+ */
+export default function patchwork(options) {
+    return [
+        wasm(),
+        configPlugin(options),
+        iconsPlugin(options),
+        htmlPlugin(options),
+        manifestPlugin(options),
+        netlifyPlugin(options),
+        importmap(options),
+        serviceworker(),
+    ].filter((plugin) => plugin != null);
+}

package/dist/vite/service-worker-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function serviceworker(): Plugin;

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

@@ -0,0 +1,49 @@
+import { fileURLToPath } from "node:url";
+import { builtins } from "./importmap-plugin.js";
+// Anchor resolution at this file (inside @inkandswitch/patchwork's own
+// installed directory) rather than the site root — these worker specifiers
+// are @inkandswitch/patchwork-bootloader's own exports, a transitive
+// dependency of the site under strict pnpm, not resolvable from the site's
+// own node_modules by bare specifier.
+const self = fileURLToPath(import.meta.url);
+// The service worker and the automerge shared worker are emitted as their
+// own chunks. Their heavy imports are marked external and resolved to
+// /packages/... URLs (both workers are created with type:"module", so the
+// browser fetches those as regular network requests).
+const workers = [
+    {
+        specifier: "@inkandswitch/patchwork-bootloader/service-worker",
+        fileName: "service-worker.js",
+    },
+    {
+        specifier: "@inkandswitch/patchwork-bootloader/automerge-worker",
+        fileName: "automerge-worker.js",
+    },
+    {
+        specifier: "@inkandswitch/patchwork-bootloader/module-loader-worker",
+        fileName: "module-loader-worker.js",
+    },
+];
+export function serviceworker() {
+    const entryIds = new Set();
+    return {
+        name: "@patchwork/service-worker",
+        enforce: "pre",
+        async buildStart() {
+            for (const { specifier, fileName } of workers) {
+                const resolved = await this.resolve(specifier, self);
+                entryIds.add(resolved.id);
+                this.emitFile({
+                    type: "chunk",
+                    id: resolved.id,
+                    fileName,
+                });
+            }
+        },
+        resolveId(source, importer) {
+            if (importer && entryIds.has(importer) && source in builtins) {
+                return { id: builtins[source], external: true };
+            }
+        },
+    };
+}