@inkandswitch/patchwork 0.0.1

package/src/site-kit/netlify.ts

@@ -0,0 +1,35 @@
+import type { PatchworkSiteOptions } from "./options.js";
+import { resolveSyncServers, PRELOAD_WASM_ASSETS } from "./sync-servers.js";
+
+function buildLinkHeader(syncServers: string[]): string {
+  const parts = PRELOAD_WASM_ASSETS.map(
+    (asset) => `</${asset}>; rel=preload; as=fetch; crossorigin`
+  );
+  for (const server of syncServers) {
+    parts.push(`<${server}>; rel=preconnect`);
+  }
+  for (const server of syncServers) {
+    parts.push(`<${server}>; rel=dns-prefetch`);
+  }
+  return parts.join(", ");
+}
+
+/** Builds the generated Netlify _headers file content — no bundler involved. */
+export function buildHeaders(options: PatchworkSiteOptions): string {
+  const syncServers = resolveSyncServers(options);
+  const immutableAssets =
+    options.netlify === false || options.netlify?.immutableAssets === false
+      ? null
+      : "/assets/*\n  Cache-Control: public, max-age=31536000, immutable\n";
+
+  return [
+    "/*\n  Access-Control-Allow-Origin: *",
+    immutableAssets,
+    `/\n  Link: ${buildLinkHeader(syncServers)}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** The generated Netlify _redirects file content — always the same SPA fallback. */
+export const REDIRECTS = "/* /index.html 200\n";

package/src/site-kit/options.ts

@@ -0,0 +1,73 @@
+/**
+ * The bundler-agnostic option shape for a Patchwork site's generated
+ * static assets (icons, index.html, manifest.webmanifest, Netlify config).
+ * `../vite/patchwork-plugin.ts` extends this with vite-only config
+ * (importmap, server/preview/worker/build) — a different bundler adapter
+ * can reuse this same shape and the pure builders in this directory without
+ * pulling in anything vite-specific.
+ */
+
+export interface PatchworkIconsOptions {
+  /** Path (relative to the site root) to a source svg or raster image. Every icon size is rendered from it via sharp. */
+  source: string;
+  /** Path to a monochrome svg for Safari's pinned-tab mask icon. Omitted entirely if not set. */
+  maskIcon?: string;
+  maskIconColor?: string;
+}
+
+export interface PatchworkHtmlOptions {
+  lang?: string;
+  /** Raw HTML appended just before </html> — e.g. extra <link>/<meta> tags. */
+  extraHead?: string;
+}
+
+export interface PatchworkNetlifyOptions {
+  /** Cache-Control: immutable on /assets/*. Default true. */
+  immutableAssets?: boolean;
+}
+
+export interface 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;
+  /** wss:// URL for subduction sync — live when keyhiveSyncServer is false. Default: wss://subduction.sync.inkandswitch.com */
+  subduction?: string;
+  /** wss:// URL for keyhive sync — live when keyhiveSyncServer is true. Default: wss://keyhive.sync.automerge.org */
+  keyhive?: string;
+}
+
+export interface PatchworkSiteOptions {
+  /** -> __SITE_NAME__ define */
+  siteName?: string;
+  /** <title>, apple-mobile-web-app-title, manifest name */
+  title?: string;
+  /** manifest short_name (defaults to title) */
+  shortName?: string;
+  /** manifest description, <meta name=description> */
+  description?: string;
+  /** default "/src/main.ts" — must be root-absolute, since the generated index.html doesn't live at the project root */
+  entry?: string;
+
+  /** -> __KEYHIVE__ define */
+  keyhive?: boolean;
+  /** -> __KEYHIVE_SYNC_SERVER__ define */
+  keyhiveSyncServer?: boolean;
+
+  themeColor?: string | { light: string; dark: string };
+  /** manifest background_color */
+  backgroundColor?: string;
+
+  /**
+   * Which sync-server hosts to preconnect/dns-prefetch from the html and
+   * list in the Netlify Link header. Only the channel actually live for
+   * this build is included — subduction xor keyhive, picked by
+   * `keyhiveSyncServer`, matching automerge-worker.ts's own selection —
+   * plus `classic` (on-demand, but cheap to hint) unless set to `false`.
+   * Pass `false` to skip all sync-server hints.
+   */
+  syncServers?: false | PatchworkSyncServersOptions;
+
+  icons?: false | PatchworkIconsOptions;
+  html?: false | PatchworkHtmlOptions;
+  manifest?: false | Record<string, unknown>;
+  netlify?: false | PatchworkNetlifyOptions;
+}

package/src/site-kit/sync-servers.ts

@@ -0,0 +1,39 @@
+import type { PatchworkSiteOptions } from "./options.js";
+
+// Mirrors core/bootloader/src/sync-config.ts's DEFAULT_CLASSIC_SYNC_SERVER
+// and automerge-worker.ts's SUBDUCTION_SYNC_URL selection — kept here as
+// plain constants (rather than importing those runtime modules) since this
+// only needs the hostnames, not the browser-only logic that reads them.
+const DEFAULT_SYNC_SERVERS = {
+  classic: "wss://sync3.automerge.org",
+  subduction: "wss://subduction.sync.inkandswitch.com",
+  keyhive: "wss://keyhive.sync.automerge.org",
+};
+
+function wsToHttpOrigin(wsUrl: string): string {
+  return wsUrl.replace(/^ws/, "http");
+}
+
+/**
+ * Resolves which sync-server origins are actually live for this build: the
+ * channel that's live is subduction xor keyhive (picked by
+ * `keyhiveSyncServer`, matching automerge-worker.ts's own selection) plus
+ * classic (on-demand, but still worth a preconnect hint) unless disabled.
+ * A flat list would drift from `keyhiveSyncServer` — e.g. always hinting
+ * subduction even on a build that actually connects to keyhive.
+ */
+export function resolveSyncServers(options: PatchworkSiteOptions): string[] {
+  if (options.syncServers === false) return [];
+  const servers = { ...DEFAULT_SYNC_SERVERS, ...options.syncServers };
+  const origins: string[] = [];
+  const primary = options.keyhiveSyncServer
+    ? servers.keyhive
+    : servers.subduction;
+  origins.push(primary);
+  if (servers.classic) origins.push(servers.classic);
+  return origins.map(wsToHttpOrigin);
+}
+
+// Emitted by importmap-plugin.ts. keyhive_wasm.wasm is loaded lazily (only
+// when keyhive is actually enabled), so it isn't worth an eager preload.
+export const PRELOAD_WASM_ASSETS = ["automerge.wasm", "subduction.wasm"];

package/src/types.ts

@@ -0,0 +1,135 @@
+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/src/vite/config-plugin.ts

@@ -0,0 +1,88 @@
+import type { Plugin } from "vite";
+import wasm from "vite-plugin-wasm";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+
+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: PatchworkVitePluginOptions = {}
+): Plugin {
+  return {
+    name: "@patchwork/config",
+    config() {
+      const define: Record<string, string> = {
+        __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/src/vite/html-plugin.ts

@@ -0,0 +1,60 @@
+import type { Plugin } from "vite";
+import { resolve } from "node:path";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+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: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  if (options.html === false) return null;
+
+  const html = buildHtml(options);
+  let entryId: string;
+
+  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/src/vite/icons.ts

@@ -0,0 +1,47 @@
+import type { Plugin } from "vite";
+import { resolve } from "node:path";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+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: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  if (!options.icons) return null;
+  const { source } = options.icons;
+
+  let sourcePath: string;
+  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/src/vite/importmap-plugin.ts

@@ -0,0 +1,112 @@
+import type { Plugin } from "vite";
+import type {
+  ImportMap,
+  PatchworkVitePluginOptions,
+} from "./patchwork-plugin.js";
+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),
+  {} as Record<string, string>
+);
+
+// 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(
+  this: import("rollup").PluginContext,
+  name: string
+): Promise<string> {
+  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: import("rollup").PluginContext,
+  id: string
+): Promise<string> {
+  return id === "@inkandswitch/patchwork"
+    ? resolveSelf.call(context, id)
+    : resolveExternal.call(context, id);
+}
+
+function createImportMap(options?: PatchworkVitePluginOptions) {
+  const importmap: ImportMap = structuredClone(
+    options?.importmap ?? { imports: {}, scopes: {} }
+  );
+  importmap.imports ??= {};
+  importmap.scopes ??= {};
+  Object.assign(importmap.imports, builtins);
+  return { importmap, builtins };
+}
+
+export function importmap(options?: PatchworkVitePluginOptions): Plugin {
+  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/src/vite/manifest-plugin.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+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: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  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/src/vite/netlify-plugin.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+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: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  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,
+      });
+    },
+  };
+}