@inkandswitch/patchwork 0.0.1

package/src/loading.ts

@@ -0,0 +1,137 @@
+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(): void {
+  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(): void {
+  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: unknown,
+  options: { contact?: string } = {}
+): void {
+  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/src/repo.ts

@@ -0,0 +1,146 @@
+import {
+  initializeWasm,
+  MessageChannelNetworkAdapter,
+  Repo,
+  type AutomergeUrl,
+} from "@automerge/vanillajs/slim";
+import { IndexedDBWorkerStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb/IndexedDBWorkerStorageAdapter";
+import * as AutomergeRepo from "@automerge/automerge-repo/slim";
+import {
+  initKeyhiveWasm,
+  initializeAutomergeRepoKeyhiveWithRepo,
+  type AutomergeRepoKeyhive,
+} from "@automerge/automerge-repo-keyhive";
+// eslint-disable-next-line
+// @ts-ignore — initSync is a wasm-bindgen runtime helper not in the .d.ts
+import { initSync as initSubductionSync } from "@automerge/automerge-subduction/slim";
+import { MemorySigner } from "@automerge/automerge-subduction/slim";
+import setupServiceWorker from "@inkandswitch/patchwork-bootloader";
+import type { SignerIdentity } from "./types.js";
+import debug from "debug";
+
+const log = debug("patchwork:setup:repo");
+
+// Must match the automerge-worker's selection, or the tab and the SW grant
+// relay access to different servers.
+declare const __KEYHIVE_SYNC_SERVER__: boolean;
+const useKeyhiveSyncServer =
+  typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
+
+// Fetch and initialize automerge + subduction wasm. Memoized: the fetches start
+// on the first call and every later caller awaits the same init. Skipped
+// entirely when the site brings its own Repo (it did this itself).
+let wasmReady: Promise<void> | undefined;
+export function initWasm(): Promise<void> {
+  if (!wasmReady) {
+    wasmReady = (async () => {
+      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);
+    })();
+  }
+  return wasmReady;
+}
+
+export async function createRepo(
+  config: { keyhive?: boolean },
+  siteName: string,
+  workerAdapter: MessageChannelNetworkAdapter
+): Promise<{
+  repo: Repo;
+  hive?: AutomergeRepoKeyhive;
+  signerIdentity?: SignerIdentity;
+}> {
+  if (config.keyhive) {
+    log("setting up keyhive");
+    initKeyhiveWasm();
+    const { hive, repo } = await initializeAutomergeRepoKeyhiveWithRepo({
+      createRepo: (repoConfig) => new Repo(repoConfig),
+      storage: new IndexedDBWorkerStorageAdapter(`${siteName}-keyhive`),
+      peerIdSuffix: siteName + Math.random().toString(36).slice(2),
+      networkAdapter: workerAdapter,
+      automaticArchiveIngestion: true,
+      cachingMode: "periodic",
+      onlyShareWithHardcodedServerPeerId: false,
+      // ARK selects the relay via `syncServer`, defaulting to "subduction".
+      ...(useKeyhiveSyncServer ? { syncServer: "keyhive" as const } : {}),
+      repo: {
+        storage: new IndexedDBWorkerStorageAdapter(),
+        enableRemoteHeadsGossiping: true,
+      },
+    });
+    log("keyhive setup complete");
+    return { repo, hive };
+  }
+
+  // An explicit signer, rather than the Repo's internal default, so the tab's
+  // identity can be exposed on window.patchwork. The tab never connects via
+  // Subduction, so this id never goes on the wire.
+  const signer = new MemorySigner();
+  const repo = new Repo({
+    network: [workerAdapter],
+    storage: new IndexedDBWorkerStorageAdapter(),
+    signer,
+    async sharePolicy(peerId) {
+      return peerId.includes("automerge-worker");
+    },
+    enableRemoteHeadsGossiping: true,
+    peerId: `${siteName}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
+  });
+  const signerIdentity = {
+    peerId: signer.peerId().toString(),
+    verifyingKey: (
+      signer.verifyingKey() as Uint8Array<ArrayBufferLike> & {
+        toHex(): string;
+      }
+    ).toHex(),
+  };
+  log("repo created, tab subduction identity:", signerIdentity);
+  return { repo, signerIdentity };
+}
+
+/**
+ * Resolve with the first repo port the worker delivers, calling `onRenewed` for
+ * every later one.
+ *
+ * subscribeToRepoChannel is deliberately not awaited: it resolves only after
+ * the boot channel's port-ready handshake, which can take its full 30s timeout
+ * against a stranded worker connection. Boot blocks on the first *delivered*
+ * port instead — if the boot channel stalls, worker recovery hands the listener
+ * a good port long before that timeout.
+ */
+export function firstRepoPort(
+  sw: Awaited<ReturnType<typeof setupServiceWorker>>,
+  onRenewed: (port: MessagePort) => void
+): Promise<MessagePort> {
+  return new Promise<MessagePort>((resolve) => {
+    let seen = false;
+    void sw.subscribeToRepoChannel((port) => {
+      if (seen) return onRenewed(port);
+      seen = true;
+      resolve(port);
+    });
+  });
+}
+
+/** Drop the adapter sitting on the dead worker port, leaving `keep` in place. */
+export function removeAdapterFor(
+  repo: Repo,
+  stale: MessageChannelNetworkAdapter,
+  keep: unknown
+): void {
+  for (const adapter of [...repo.networkSubsystem.adapters]) {
+    if (adapter === keep) continue;
+    // The keyhive wrapper keeps the wrapped adapter on `.networkAdapter`.
+    const base = (adapter as any).networkAdapter ?? adapter;
+    if (base !== stale) continue;
+    try {
+      repo.networkSubsystem.removeNetworkAdapter(adapter as any);
+    } catch (err) {
+      console.error("failed to remove stale worker network adapter", err);
+    }
+  }
+}

package/src/router.ts

@@ -0,0 +1,195 @@
+import {
+  isValidAutomergeUrl,
+  isValidDocumentId,
+  stringifyAutomergeUrl,
+  type AutomergeUrl,
+  type DocHandle,
+  type DocumentId,
+  type Repo,
+} from "@automerge/vanillajs/slim";
+import { openDocument } from "@inkandswitch/patchwork-elements";
+import {
+  type AccountDoc,
+  type DatatypeDescription,
+  type DatatypeImplementation,
+  getRegistry,
+} from "@inkandswitch/patchwork-plugins";
+
+// Legacy big-patchwork hash shape: `<slug>--<documentId>[?…]`. The slug can
+// contain characters we don't otherwise permit (e.g. `drawing-(branch-1)`), so
+// anchor on the `--` before the base58 document id rather than a strict slug
+// charset.
+const BIG_PATCHWORK_HASH_REGEX =
+  /^(?<title>[^=&?/#]*)--(?<docId>[1-9A-HJ-NP-Za-km-z]+)/;
+
+// The `doc=` value is an automerge URL, kept literal rather than
+// percent-encoded so links stay readable.
+const RAW_HASH_KEYS = new Set(["doc"]);
+// A stable order means re-serializing the same logical params is
+// byte-identical, avoiding spurious `hashchange` round-trips.
+const HASH_KEY_ORDER = ["doc", "tool", "type", "title", "frame"];
+
+function serializeHashParams(params: URLSearchParams): string {
+  const keys = [...HASH_KEY_ORDER, ...params.keys()];
+  const parts: string[] = [];
+  const emitted = new Set<string>();
+  for (const key of keys) {
+    if (emitted.has(key)) continue;
+    const value = params.get(key);
+    if (!value) continue;
+    emitted.add(key);
+    parts.push(
+      `${key}=${RAW_HASH_KEYS.has(key) ? value : encodeURIComponent(value)}`
+    );
+  }
+  return parts.join("&");
+}
+
+/**
+ * Coerce a `doc=` hash param to a full automerge URL. Accepts a full URL
+ * (`automerge:<id>[#heads]`) or a bare document id, for older links.
+ */
+export function docParamToUrl(docParam: string | null): AutomergeUrl | undefined {
+  if (!docParam) return undefined;
+  if (isValidAutomergeUrl(docParam as AutomergeUrl)) {
+    return docParam as AutomergeUrl;
+  }
+  const documentId = docParam.replace(/^automerge:/, "");
+  if (!isValidDocumentId(documentId)) return undefined;
+  return stringifyAutomergeUrl({ documentId: documentId as DocumentId });
+}
+
+export interface RouterParams {
+  rootElement: HTMLElement;
+  repo: Repo;
+  accountDocHandle: DocHandle<AccountDoc>;
+  siteName: string;
+}
+
+export interface Router {
+  /** Apply `location.hash` to the view. */
+  route(): Promise<void>;
+}
+
+export function createRouter({
+  rootElement,
+  repo,
+  accountDocHandle,
+  siteName,
+}: RouterParams): Router {
+  const route = async () => {
+    // The first call seeds the root view's tool/doc so it can mount; later
+    // calls reconcile the mounted view with the hash.
+    if (!rootElement.hasAttribute("tool-id")) {
+      const params = new URLSearchParams(location.hash.slice(1));
+      const frame = params.get("frame");
+      rootElement.setAttribute(
+        "tool-id",
+        frame ?? accountDocHandle.doc().frameToolId
+      );
+      rootElement.setAttribute(
+        "doc-url",
+        (frame && docParamToUrl(params.get("doc"))) || accountDocHandle.url
+      );
+      return;
+    }
+
+    const hash = window.location.hash.slice(1);
+
+    // Legacy big-patchwork link: normalize to `#doc=automerge:<docId>` and let
+    // routing re-run on the resulting hashchange.
+    const legacyDocId = BIG_PATCHWORK_HASH_REGEX.exec(hash)?.groups?.docId;
+    if (legacyDocId && isValidDocumentId(legacyDocId)) {
+      window.location.hash = serializeHashParams(
+        new URLSearchParams({
+          doc: stringifyAutomergeUrl({ documentId: legacyDocId as DocumentId }),
+        })
+      );
+      return;
+    }
+
+    // Bare automerge URL: /#automerge:<documentId>
+    if (isValidAutomergeUrl(hash as AutomergeUrl)) {
+      window.location.hash = "";
+      openDocument(rootElement, hash as AutomergeUrl);
+      return;
+    }
+
+    const params = new URLSearchParams(hash);
+    const docUrl = docParamToUrl(params.get("doc"));
+    const frame = params.get("frame");
+
+    if (frame) {
+      const frameDocUrl = docUrl ?? accountDocHandle.url;
+      if (
+        rootElement.getAttribute("tool-id") !== frame ||
+        rootElement.getAttribute("doc-url") !== frameDocUrl
+      ) {
+        rootElement.setAttribute("tool-id", frame);
+        rootElement.setAttribute("doc-url", frameDocUrl);
+      }
+    }
+
+    if (docUrl) {
+      rootElement.dispatchEvent(
+        new CustomEvent("patchwork:open-document", {
+          detail: {
+            url: docUrl,
+            toolId: params.get("tool"),
+            title: params.get("title"),
+            type: params.get("type"),
+          },
+        })
+      );
+    }
+  };
+
+  rootElement.addEventListener("patchwork:open-document", async (event) => {
+    const { url, toolId, type, title } = event.detail as {
+      url: AutomergeUrl;
+      toolId?: string;
+      type?: string;
+      title?: string;
+    };
+
+    const params = new URLSearchParams(window.location.hash.slice(1));
+    // `doc` is the full automerge URL, so heads live inside it and the separate
+    // `heads=` param is gone.
+    params.delete("heads");
+    params.set("doc", url);
+    for (const [key, value] of [
+      ["tool", toolId],
+      ["title", title],
+      ["type", type],
+    ] as const) {
+      if (value) params.set(key, value);
+      else params.delete(key);
+    }
+    window.location.hash = serializeHashParams(params);
+
+    try {
+      const docHandle = await repo.find<{ "@patchwork"?: { type?: string } }>(
+        url
+      );
+      const doc = docHandle.doc();
+      const docType = type || doc?.["@patchwork"]?.type;
+      if (!docType) return;
+      const datatype =
+        await getRegistry<DatatypeDescription>("patchwork:datatype").load(
+          docType
+        );
+      if (!datatype) return;
+      const docTitle = (datatype.module as DatatypeImplementation).getTitle(
+        doc
+      );
+      if (docTitle) document.title = `${docTitle} | ${siteName}`;
+    } catch (e) {
+      console.error("Failed to update document title", e);
+    }
+  });
+
+  window.addEventListener("hashchange", route);
+  void route();
+
+  return { route };
+}

package/src/site-kit/html.ts

@@ -0,0 +1,100 @@
+import type { PatchworkSiteOptions } from "./options.js";
+import { resolveSyncServers, PRELOAD_WASM_ASSETS } from "./sync-servers.js";
+import { ICON_SPECS } from "./icons.js";
+
+const HTML_ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+export function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]!);
+}
+
+/** Builds the generated index.html as a plain string — no bundler involved. */
+export function buildHtml(options: PatchworkSiteOptions): string {
+  const title = options.title ?? options.siteName ?? "Patchwork";
+  const lang = (options.html && options.html.lang) || "en";
+  const entry = options.entry ?? "/src/main.ts";
+  const syncServers = resolveSyncServers(options);
+
+  const head: string[] = [
+    `<meta charset="UTF-8" />`,
+    `<meta name="viewport" content="width=device-width, initial-scale=1.0" />`,
+    `<title>${escapeHtml(title)}</title>`,
+    `<link rel="stylesheet" href="@inkandswitch/patchwork/global.css" />`,
+  ];
+
+  if (options.description) {
+    head.push(
+      `<meta name="description" content="${escapeHtml(options.description)}" />`
+    );
+  }
+
+  if (options.icons) {
+    for (const spec of ICON_SPECS) {
+      if (spec.fileName === "apple-touch-icon.png") {
+        head.push(
+          `<link rel="apple-touch-icon" sizes="${spec.size}x${spec.size}" href="/${spec.fileName}" />`
+        );
+      } else if (spec.fileName.startsWith("favicon-")) {
+        head.push(
+          `<link rel="icon" type="image/png" sizes="${spec.size}x${spec.size}" href="/${spec.fileName}" />`
+        );
+      }
+    }
+    if (options.icons?.maskIcon) {
+      head.push(
+        `<link rel="mask-icon" href="${options.icons.maskIcon}" color="${
+          options.icons.maskIconColor ?? "#000000"
+        }" />`
+      );
+    }
+  }
+
+  if (typeof options.themeColor === "string") {
+    head.push(`<meta name="theme-color" content="${options.themeColor}" />`);
+  } else if (options.themeColor) {
+    head.push(
+      `<meta name="theme-color" content="${options.themeColor.light}" media="(prefers-color-scheme: light)" />`,
+      `<meta name="theme-color" content="${options.themeColor.dark}" media="(prefers-color-scheme: dark)" />`
+    );
+  }
+
+  head.push(
+    `<meta name="apple-mobile-web-app-capable" content="yes" />`,
+    `<meta name="apple-mobile-web-app-status-bar-style" content="default" />`,
+    `<meta name="apple-mobile-web-app-title" content="${escapeHtml(title)}" />`
+  );
+
+  if (options.manifest !== false) {
+    head.push(`<link rel="manifest" href="/manifest.webmanifest" />`);
+  }
+
+  for (const server of syncServers) {
+    head.push(`<link rel="preconnect" href="${server}" />`);
+  }
+  for (const server of syncServers) {
+    head.push(`<link rel="dns-prefetch" href="${server}" />`);
+  }
+  for (const asset of PRELOAD_WASM_ASSETS) {
+    head.push(
+      `<link rel="preload" href="/${asset}" as="fetch" crossorigin />`
+    );
+  }
+
+  if (options.html && options.html.extraHead) {
+    head.push(options.html.extraHead);
+  }
+
+  return `<!doctype html>
+<html lang="${lang}">
+${head.join("\n")}
+<repo-provider><patchwork-view id="root"></patchwork-view></repo-provider>
+<script type="module" src="${entry}"></script>
+</html>
+`;
+}

package/src/site-kit/icons.ts

@@ -0,0 +1,49 @@
+import sharp from "sharp";
+import { readFile } from "node:fs/promises";
+
+export interface IconSpec {
+  fileName: string;
+  size: number;
+  /** Included in the generated manifest.webmanifest icons array when set. */
+  manifestPurpose?: string;
+}
+
+// apple-touch-icon at 180 matches iOS's expected size; 192/512 are the
+// standard PWA manifest sizes; 16/32 cover browser tab favicons.
+export const ICON_SPECS: IconSpec[] = [
+  { fileName: "favicon-16x16.png", size: 16 },
+  { fileName: "favicon-32x32.png", size: 32 },
+  { fileName: "apple-touch-icon.png", size: 180 },
+  { fileName: "icon-192x192.png", size: 192, manifestPurpose: "any maskable" },
+  { fileName: "icon-512x512.png", size: 512, manifestPurpose: "any maskable" },
+];
+
+const cache = new Map<string, Promise<Map<string, Buffer>>>();
+
+async function renderIcons(source: string): Promise<Map<string, Buffer>> {
+  const input = await readFile(source);
+  const rendered = new Map<string, Buffer>();
+  await Promise.all(
+    ICON_SPECS.map(async (spec) => {
+      const buffer = await sharp(input)
+        .resize(spec.size, spec.size, { fit: "cover" })
+        .png()
+        .toBuffer();
+      rendered.set(spec.fileName, buffer);
+    })
+  );
+  return rendered;
+}
+
+/** Renders every icon size from a single source image (svg or raster), cached by source path. */
+export function getIcons(source: string): Promise<Map<string, Buffer>> {
+  let promise = cache.get(source);
+  if (!promise) {
+    promise = renderIcons(source).catch((error) => {
+      cache.delete(source);
+      throw error;
+    });
+    cache.set(source, promise);
+  }
+  return promise;
+}

package/src/site-kit/index.ts

@@ -0,0 +1,22 @@
+/**
+ * The bundler-agnostic parts of building a Patchwork site's static assets —
+ * icon rendering, and the index.html/manifest.webmanifest/Netlify _headers
+ * content builders. No `vite` import anywhere in this directory: a
+ * different bundler adapter (esbuild, webpack, or a plain pre-build script)
+ * can reuse these directly. `../vite/*` is the vite-specific adapter that
+ * wires these into vite's plugin hooks (dev middleware, emitFile, virtual
+ * modules, config()).
+ */
+export type {
+  PatchworkSiteOptions,
+  PatchworkIconsOptions,
+  PatchworkHtmlOptions,
+  PatchworkNetlifyOptions,
+  PatchworkSyncServersOptions,
+} from "./options.js";
+
+export { resolveSyncServers, PRELOAD_WASM_ASSETS } from "./sync-servers.js";
+export { getIcons, ICON_SPECS, type IconSpec } from "./icons.js";
+export { buildHtml, escapeHtml } from "./html.js";
+export { buildManifest } from "./manifest.js";
+export { buildHeaders, REDIRECTS } from "./netlify.js";

package/src/site-kit/manifest.ts

@@ -0,0 +1,39 @@
+import type { PatchworkSiteOptions } from "./options.js";
+import { ICON_SPECS } from "./icons.js";
+
+/** Builds the generated manifest.webmanifest object — no bundler involved. */
+export function buildManifest(
+  options: PatchworkSiteOptions
+): Record<string, unknown> {
+  const title = options.title ?? options.siteName ?? "Patchwork";
+  const icons = !options.icons
+    ? []
+    : ICON_SPECS.filter(
+        (spec) =>
+          spec.fileName === "apple-touch-icon.png" || spec.manifestPurpose
+      ).map((spec) => ({
+        src: `/${spec.fileName}`,
+        sizes: `${spec.size}x${spec.size}`,
+        type: "image/png",
+        ...(spec.manifestPurpose ? { purpose: spec.manifestPurpose } : {}),
+      }));
+
+  const manifest: Record<string, unknown> = {
+    name: title,
+    short_name: options.shortName ?? title,
+    description: options.description,
+    start_url: "/",
+    display: "standalone",
+    display_override: ["window-controls-overlay", "standalone"],
+    background_color: options.backgroundColor ?? "#ffffff",
+    theme_color:
+      (typeof options.themeColor === "string"
+        ? options.themeColor
+        : options.themeColor?.light) ??
+      options.backgroundColor ??
+      "#ffffff",
+    icons,
+  };
+
+  return { ...manifest, ...options.manifest };
+}