@inkandswitch/patchwork 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @inkandswitch/patchwork
 
+## 0.7.0
+
+### Minor Changes
+
+- 5be751b: Add `static` and `buildInfo` options to the vite plugin.
+
+  `static` mounts file trees into the site — a package of Patchwork modules, a
+  sibling repo's build output, a hand-written `modules.json`. Each source is
+  served by the dev server and copied into the site at build:
+
+  ```js
+  patchwork({
+    static: [
+      { from: "modules.json" },
+      "@inkandswitch/patchwork-pkg-base",
+      {
+        from: "../notebook/dist",
+        to: "/packages/notebook",
+        watch: ".watch-ready",
+      },
+    ],
+  });
+  ```
+
+  A source is either a package specifier or a path relative to the site root, and
+  either a file or a directory. `to` mounts it somewhere other than the site root.
+  `watch` names a file inside the source that another build touches when it
+  finishes; writing to it full-reloads the dev page, which is how a sibling repo
+  in watch mode drives the site's dev server.
+
+  Sources never overwrite the site's own files — not the build's output, not
+  `public/`, not an earlier source in the list — so precedence is list order. A
+  site that wants its own `modules.json` lists it before the package it takes the
+  rest of its modules from. Every file a source didn't get to write is logged at
+  the end of the build, so a collision you didn't mean to have is visible.
+
+  A package can say which of its directories is the static tree with a
+  `"patchwork": {"static": "static-dist"}` field in its package.json. Without one,
+  the package root is mounted (minus its manifest, `node_modules` and `.git`).
+
+  `buildInfo` writes `build-info.json`: the site's git revision, the version and
+  revision of the patchwork that built it, and every `static` source. Pass an
+  object to merge extra fields into it.
+
+  Both options are off unless set, so existing sites are unaffected.
+
 ## 0.6.1
 
 ### Patch Changes

package/dist/vite/build-info-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/**
+ * Writes build-info.json: what this site was built from. The site's own
+ * revision, the version of patchwork that built it, and every `static` source,
+ * plus whatever extra fields the site passes as the option value.
+ */
+export declare function buildInfoPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/build-info-plugin.js

@@ -0,0 +1,63 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveStatic } from "./static-plugin.js";
+function revision(directory) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: directory,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What a package directory is: its name and version, plus the revision it was
+ * built from when it isn't an installed copy. A workspace link or a checkout
+ * resolves outside node_modules, and its version alone doesn't say which build
+ * of it this was.
+ */
+function describe(directory) {
+    const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        revision: directory.split(sep).includes("node_modules")
+            ? undefined
+            : revision(directory),
+    };
+}
+/**
+ * Writes build-info.json: what this site was built from. The site's own
+ * revision, the version of patchwork that built it, and every `static` source,
+ * plus whatever extra fields the site passes as the option value.
+ */
+export function buildInfoPlugin(options = {}) {
+    if (!options.buildInfo)
+        return null;
+    let root;
+    let outDir;
+    return {
+        name: "@patchwork/build-info",
+        configResolved(config) {
+            root = config.root;
+            outDir = join(config.root, config.build.outDir);
+        },
+        async closeBundle() {
+            const sources = resolveStatic(options, root).map((source) => source.packageDirectory
+                ? { from: source.from, ...describe(source.packageDirectory) }
+                : { from: source.from, revision: revision(source.path) });
+            await writeFile(join(outDir, "build-info.json"), `${JSON.stringify({
+                site: { revision: revision(root) },
+                patchwork: describe(join(dirname(fileURLToPath(import.meta.url)), "..", "..")),
+                static: sources.length ? sources : undefined,
+                ...(options.buildInfo === true ? {} : options.buildInfo),
+            }, null, 2)}\n`);
+        },
+    };
+}

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

@@ -1,4 +1,5 @@
 import type { Plugin, ServerOptions, PreviewOptions, BuildOptions } from "vite";
+import { type PatchworkStaticSource } from "./static-plugin.js";
 import type { PatchworkSiteOptions } from "../site-kit/options.js";
 /**
  * The patchwork vite plugin. A site's vite.config.ts can shrink down to
@@ -31,9 +32,23 @@ export type ImportMap = {
         [scope: string]: Imports;
     };
 };
+export type { PatchworkStaticSource } from "./static-plugin.js";
 export type { PatchworkSiteOptions, PatchworkIconsOptions, PatchworkHtmlOptions, PatchworkNetlifyOptions, PatchworkKeyhiveSyncServer, PatchworkSyncServersOptions, } from "../site-kit/options.js";
 export interface PatchworkVitePluginOptions extends PatchworkSiteOptions {
     importmap?: ImportMap;
+    /**
+     * File trees to mount into the site, in order of precedence — a package of
+     * Patchwork modules, a sibling repo's build output, a hand-written
+     * modules.json. Served in dev, copied into the site at build, and never
+     * overwriting the site's own files. A bare string is `{from: string}`.
+     */
+    static?: (string | PatchworkStaticSource)[];
+    /**
+     * Write build-info.json: this site's revision, the patchwork version that
+     * built it, and every `static` source. An object is merged into it, for
+     * whatever else the site wants recorded.
+     */
+    buildInfo?: boolean | Record<string, unknown>;
     server?: false | ServerOptions;
     preview?: false | PreviewOptions;
     worker?: false | {

package/dist/vite/patchwork-plugin.js

@@ -6,6 +6,8 @@ import { iconsPlugin } from "./icons.js";
 import { htmlPlugin } from "./html-plugin.js";
 import { manifestPlugin } from "./manifest-plugin.js";
 import { netlifyPlugin } from "./netlify-plugin.js";
+import { staticPlugin } from "./static-plugin.js";
+import { buildInfoPlugin } from "./build-info-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
@@ -38,5 +40,7 @@ export default function patchwork(options) {
         importmap(options),
         serviceworker(),
         devPlugin(options),
+        staticPlugin(options),
+        buildInfoPlugin(options),
     ].filter((plugin) => plugin != null);
 }

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

@@ -0,0 +1,46 @@
+import type { Plugin } from "vite";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+/**
+ * A tree of files to mount into the site — a package of Patchwork modules, a
+ * sibling repo's build output, a single hand-written file.
+ *
+ * `from` is either a package specifier or a path relative to the site root. A
+ * package says where its static tree lives with a `"patchwork": {"static":
+ * "static-dist"}` field in its own package.json; without one, the whole
+ * package directory is mounted.
+ */
+export interface PatchworkStaticSource {
+    from: string;
+    /**
+     * URL path to mount `from` at. Defaults to `/`. For a file source a trailing
+     * slash means "this directory, under the file's own name", so `{from:
+     * "build/modules.json"}` lands at `/modules.json`.
+     */
+    to?: string;
+    /**
+     * Path, within `from`, of a file another build touches when it finishes.
+     * Writing to it full-reloads the dev page, and it is never copied into the
+     * site. This is how a sibling repo in watch mode drives the site's dev
+     * server.
+     */
+    watch?: string;
+}
+export interface ResolvedStaticSource extends PatchworkStaticSource {
+    /** absolute path of the file or directory `from` resolved to */
+    path: string;
+    /** normalised mount point: "" for the site root, else "/packages/x" */
+    mount: string;
+    file: boolean;
+    /** set when `from` was a package specifier rather than a path */
+    packageDirectory?: string;
+}
+export declare function resolveStatic(options: PatchworkVitePluginOptions, root: string): ResolvedStaticSource[];
+/**
+ * Mounts `static` sources: served in dev, copied into the site at build.
+ *
+ * Sources never overwrite the site's own output — neither the build's, nor
+ * `public/`, nor an earlier source in the list. So precedence is just list
+ * order, and a site keeps its own `modules.json` by listing it before the
+ * package it borrows the rest of the packages from.
+ */
+export declare function staticPlugin(options?: PatchworkVitePluginOptions): Plugin | null;

package/dist/vite/static-plugin.js

@@ -0,0 +1,207 @@
+import { constants, existsSync, readFileSync, statSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { createRequire } from "node:module";
+const CONTENT_TYPES = {
+    ".css": "text/css",
+    ".html": "text/html",
+    ".js": "text/javascript",
+    ".json": "application/json",
+    ".map": "application/json",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".wasm": "application/wasm",
+};
+/** Never site content, whatever a source directory happens to contain. */
+const SKIP = new Set(["node_modules", ".git"]);
+/**
+ * Resolved from the site, not from here: the site is what depends on these
+ * packages, and under pnpm this plugin lives somewhere that can't see them.
+ */
+function packageDirectory(name, root) {
+    const require = createRequire(join(root, "package.json"));
+    try {
+        return dirname(require.resolve(`${name}/package.json`));
+    }
+    catch {
+        // an "exports" map can hide both the manifest and the package's own main,
+        // so fall back to looking for it where node would have found it
+        for (const directory of require.resolve.paths(name) ?? []) {
+            if (existsSync(join(directory, name, "package.json"))) {
+                return join(directory, name);
+            }
+        }
+        throw new Error(`[patchwork] can't find the package "${name}" — a static source has to be a dependency of the site`);
+    }
+}
+export function resolveStatic(options, root) {
+    return (options.static ?? []).map((source) => {
+        const entry = typeof source === "string" ? { from: source } : source;
+        const isPath = entry.from.startsWith(".") || isAbsolute(entry.from);
+        const directory = isPath ? undefined : packageDirectory(entry.from, root);
+        const path = directory
+            ? join(directory, JSON.parse(readFileSync(join(directory, "package.json"), "utf8"))
+                .patchwork?.static ?? ".")
+            : resolve(root, entry.from);
+        if (!existsSync(path)) {
+            throw new Error(`[patchwork] static source not found: ${entry.from}`);
+        }
+        const file = statSync(path).isFile();
+        const to = entry.to ?? "/";
+        return {
+            ...entry,
+            path,
+            file,
+            packageDirectory: directory,
+            mount: (file && to.endsWith("/") ? join(to, basename(path)) : to).replace(/\/+$/, ""),
+        };
+    });
+}
+function locate(source, pathname) {
+    if (source.file)
+        return pathname === source.mount ? source.path : undefined;
+    if (pathname !== source.mount && !pathname.startsWith(`${source.mount}/`)) {
+        return undefined;
+    }
+    const path = resolve(source.path, `.${pathname.slice(source.mount.length)}`);
+    const within = relative(source.path, path);
+    if (within.startsWith(".."))
+        return undefined;
+    if (within.split(sep).some((part) => SKIP.has(part)))
+        return undefined;
+    if (within === source.watch)
+        return undefined;
+    if (within === "package.json" && source.packageDirectory)
+        return undefined;
+    return path;
+}
+/** How a source is named in messages: a specifier, or the shorter of the paths. */
+function label(source, root) {
+    if (source.packageDirectory)
+        return source.from;
+    const path = relative(root, source.path);
+    return path.split(sep).filter((part) => part === "..").length > 1
+        ? source.path
+        : path;
+}
+async function files(source, directory = source) {
+    const paths = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (SKIP.has(entry.name))
+            continue;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            paths.push(...(await files(source, path)));
+        if (entry.isFile())
+            paths.push(relative(source, path));
+    }
+    return paths;
+}
+/**
+ * Mounts `static` sources: served in dev, copied into the site at build.
+ *
+ * Sources never overwrite the site's own output — neither the build's, nor
+ * `public/`, nor an earlier source in the list. So precedence is just list
+ * order, and a site keeps its own `modules.json` by listing it before the
+ * package it borrows the rest of the packages from.
+ */
+export function staticPlugin(options = {}) {
+    if (!options.static?.length)
+        return null;
+    let sources = [];
+    let root;
+    let outDir;
+    let base = "/";
+    let logger;
+    return {
+        name: "@patchwork/static",
+        configResolved(config) {
+            sources = resolveStatic(options, config.root);
+            root = config.root;
+            outDir = resolve(config.root, config.build.outDir);
+            base = config.base;
+            logger = config.logger;
+        },
+        async closeBundle() {
+            for (const source of sources) {
+                const paths = source.file ? [""] : await files(source.path);
+                const kept = [];
+                for (const path of paths) {
+                    if (path === source.watch)
+                        continue;
+                    // a package that doesn't declare a static directory mounts its whole
+                    // root, and its manifest isn't part of the site
+                    if (path === "package.json" && source.packageDirectory)
+                        continue;
+                    const to = join(outDir, `.${source.mount}`, path);
+                    await mkdir(dirname(to), { recursive: true });
+                    try {
+                        // EXCL rather than a check, so the build's own output and public/
+                        // win a collision no matter what order the copies happen in.
+                        await copyFile(join(source.path, path), to, constants.COPYFILE_EXCL);
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            throw error;
+                        kept.push(join(source.mount, "/", path));
+                    }
+                }
+                if (kept.length) {
+                    logger.info(`[patchwork] ${label(source, root)}: ${kept.length} ${kept.length === 1 ? "file was" : "files were"} already in the site and not copied over — ${kept
+                        .slice(0, 5)
+                        .join(", ")}${kept.length > 5 ? `, and ${kept.length - 5} more` : ""}`, { timestamp: true });
+                }
+            }
+        },
+        configureServer(server) {
+            const watched = new Map(sources
+                .filter((source) => source.watch)
+                .map((source) => [join(source.path, source.watch), source]));
+            for (const path of watched.keys())
+                server.watcher.add(path);
+            server.watcher.on("change", (path) => {
+                if (watched.has(path))
+                    server.ws.send({ type: "full-reload" });
+            });
+            // Returned, so this runs after vite's own public/static middlewares and
+            // dev matches the build: sources fill in what the site doesn't have.
+            // By then the SPA fallback has rewritten req.url to /index.html, so the
+            // path being asked for is the one connect saved on the way in.
+            return () => {
+                server.middlewares.use(async (request, response, next) => {
+                    const url = request
+                        .originalUrl ??
+                        request.url ??
+                        "/";
+                    let pathname;
+                    try {
+                        pathname = decodeURIComponent(new URL(url, "http://localhost").pathname);
+                    }
+                    catch {
+                        return next();
+                    }
+                    if (base !== "/" && pathname.startsWith(base)) {
+                        pathname = pathname.slice(base.length - 1);
+                    }
+                    for (const source of sources) {
+                        const path = locate(source, pathname);
+                        if (!path)
+                            continue;
+                        try {
+                            if (!statSync(path).isFile())
+                                continue;
+                            response.setHeader("Cache-Control", "no-cache");
+                            response.setHeader("Content-Type", CONTENT_TYPES[extname(path)] ?? "application/octet-stream");
+                            response.end(await readFile(path));
+                            return;
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    next();
+                });
+            };
+        },
+    };
+}

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+https://github.com/inkandswitch/patchwork-system.git",
     "directory": "core/patchwork"
   },
-  "version": "0.6.1",
+  "version": "0.7.0",
   "author": "Ink & Switch",
   "type": "module",
   "license": "MIT",
@@ -44,10 +44,10 @@
     "sharp": "^0.35.3",
     "vite-plugin-wasm": "^3.6.0",
     "@inkandswitch/patchwork-bootloader": "^0.6.2",
-    "@inkandswitch/patchwork-plugins": "^1.2.0",
     "@inkandswitch/patchwork-filesystem": "^0.2.5",
-    "@inkandswitch/patchwork-elements": "^6.0.0",
-    "@inkandswitch/patchwork-providers": "^0.5.0"
+    "@inkandswitch/patchwork-plugins": "^1.2.0",
+    "@inkandswitch/patchwork-providers": "^0.5.0",
+    "@inkandswitch/patchwork-elements": "^6.0.0"
   },
   "devDependencies": {
     "rollup": "^4.61.1",

package/src/vite/build-info-plugin.ts

@@ -0,0 +1,81 @@
+import type { Plugin } from "vite";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+import { resolveStatic } from "./static-plugin.js";
+
+function revision(directory: string) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: directory,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What a package directory is: its name and version, plus the revision it was
+ * built from when it isn't an installed copy. A workspace link or a checkout
+ * resolves outside node_modules, and its version alone doesn't say which build
+ * of it this was.
+ */
+function describe(directory: string) {
+  const manifest = JSON.parse(
+    readFileSync(join(directory, "package.json"), "utf8")
+  );
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    revision: directory.split(sep).includes("node_modules")
+      ? undefined
+      : revision(directory),
+  };
+}
+
+/**
+ * Writes build-info.json: what this site was built from. The site's own
+ * revision, the version of patchwork that built it, and every `static` source,
+ * plus whatever extra fields the site passes as the option value.
+ */
+export function buildInfoPlugin(
+  options: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  if (!options.buildInfo) return null;
+  let root: string;
+  let outDir: string;
+  return {
+    name: "@patchwork/build-info",
+    configResolved(config) {
+      root = config.root;
+      outDir = join(config.root, config.build.outDir);
+    },
+    async closeBundle() {
+      const sources = resolveStatic(options, root).map((source) =>
+        source.packageDirectory
+          ? { from: source.from, ...describe(source.packageDirectory) }
+          : { from: source.from, revision: revision(source.path) }
+      );
+      await writeFile(
+        join(outDir, "build-info.json"),
+        `${JSON.stringify(
+          {
+            site: { revision: revision(root) },
+            patchwork: describe(
+              join(dirname(fileURLToPath(import.meta.url)), "..", "..")
+            ),
+            static: sources.length ? sources : undefined,
+            ...(options.buildInfo === true ? {} : options.buildInfo),
+          },
+          null,
+          2
+        )}\n`
+      );
+    },
+  };
+}

package/src/vite/patchwork-plugin.ts

@@ -8,6 +8,8 @@ import { iconsPlugin } from "./icons.js";
 import { htmlPlugin } from "./html-plugin.js";
 import { manifestPlugin } from "./manifest-plugin.js";
 import { netlifyPlugin } from "./netlify-plugin.js";
+import { staticPlugin, type PatchworkStaticSource } from "./static-plugin.js";
+import { buildInfoPlugin } from "./build-info-plugin.js";
 import type { PatchworkSiteOptions } from "../site-kit/options.js";
 
 /**
@@ -42,6 +44,8 @@ export default function patchwork(options?: PatchworkVitePluginOptions) {
     importmap(options),
     serviceworker(),
     devPlugin(options),
+    staticPlugin(options),
+    buildInfoPlugin(options),
   ].filter((plugin): plugin is Plugin => plugin != null);
 }
 
@@ -51,6 +55,8 @@ export type ImportMap = {
   scopes?: { [scope: string]: Imports };
 };
 
+export type { PatchworkStaticSource } from "./static-plugin.js";
+
 export type {
   PatchworkSiteOptions,
   PatchworkIconsOptions,
@@ -63,6 +69,20 @@ export type {
 export interface PatchworkVitePluginOptions extends PatchworkSiteOptions {
   importmap?: ImportMap;
 
+  /**
+   * File trees to mount into the site, in order of precedence — a package of
+   * Patchwork modules, a sibling repo's build output, a hand-written
+   * modules.json. Served in dev, copied into the site at build, and never
+   * overwriting the site's own files. A bare string is `{from: string}`.
+   */
+  static?: (string | PatchworkStaticSource)[];
+  /**
+   * Write build-info.json: this site's revision, the patchwork version that
+   * built it, and every `static` source. An object is merged into it, for
+   * whatever else the site wants recorded.
+   */
+  buildInfo?: boolean | Record<string, unknown>;
+
   server?: false | ServerOptions;
   preview?: false | PreviewOptions;
   worker?: false | { format?: "es" | "iife" };

package/src/vite/static-plugin.ts

@@ -0,0 +1,275 @@
+import type { Logger, Plugin } from "vite";
+import type { IncomingMessage } from "node:http";
+import { constants, existsSync, readFileSync, statSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir } from "node:fs/promises";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import { createRequire } from "node:module";
+import type { PatchworkVitePluginOptions } from "./patchwork-plugin.js";
+
+/**
+ * A tree of files to mount into the site — a package of Patchwork modules, a
+ * sibling repo's build output, a single hand-written file.
+ *
+ * `from` is either a package specifier or a path relative to the site root. A
+ * package says where its static tree lives with a `"patchwork": {"static":
+ * "static-dist"}` field in its own package.json; without one, the whole
+ * package directory is mounted.
+ */
+export interface PatchworkStaticSource {
+  from: string;
+  /**
+   * URL path to mount `from` at. Defaults to `/`. For a file source a trailing
+   * slash means "this directory, under the file's own name", so `{from:
+   * "build/modules.json"}` lands at `/modules.json`.
+   */
+  to?: string;
+  /**
+   * Path, within `from`, of a file another build touches when it finishes.
+   * Writing to it full-reloads the dev page, and it is never copied into the
+   * site. This is how a sibling repo in watch mode drives the site's dev
+   * server.
+   */
+  watch?: string;
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".css": "text/css",
+  ".html": "text/html",
+  ".js": "text/javascript",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".wasm": "application/wasm",
+};
+
+/** Never site content, whatever a source directory happens to contain. */
+const SKIP = new Set(["node_modules", ".git"]);
+
+export interface ResolvedStaticSource extends PatchworkStaticSource {
+  /** absolute path of the file or directory `from` resolved to */
+  path: string;
+  /** normalised mount point: "" for the site root, else "/packages/x" */
+  mount: string;
+  file: boolean;
+  /** set when `from` was a package specifier rather than a path */
+  packageDirectory?: string;
+}
+
+/**
+ * Resolved from the site, not from here: the site is what depends on these
+ * packages, and under pnpm this plugin lives somewhere that can't see them.
+ */
+function packageDirectory(name: string, root: string) {
+  const require = createRequire(join(root, "package.json"));
+  try {
+    return dirname(require.resolve(`${name}/package.json`));
+  } catch {
+    // an "exports" map can hide both the manifest and the package's own main,
+    // so fall back to looking for it where node would have found it
+    for (const directory of require.resolve.paths(name) ?? []) {
+      if (existsSync(join(directory, name, "package.json"))) {
+        return join(directory, name);
+      }
+    }
+    throw new Error(
+      `[patchwork] can't find the package "${name}" — a static source has to be a dependency of the site`
+    );
+  }
+}
+
+export function resolveStatic(
+  options: PatchworkVitePluginOptions,
+  root: string
+): ResolvedStaticSource[] {
+  return (options.static ?? []).map((source) => {
+    const entry = typeof source === "string" ? { from: source } : source;
+    const isPath = entry.from.startsWith(".") || isAbsolute(entry.from);
+    const directory = isPath ? undefined : packageDirectory(entry.from, root);
+    const path = directory
+      ? join(
+          directory,
+          JSON.parse(readFileSync(join(directory, "package.json"), "utf8"))
+            .patchwork?.static ?? "."
+        )
+      : resolve(root, entry.from);
+    if (!existsSync(path)) {
+      throw new Error(`[patchwork] static source not found: ${entry.from}`);
+    }
+    const file = statSync(path).isFile();
+    const to = entry.to ?? "/";
+    return {
+      ...entry,
+      path,
+      file,
+      packageDirectory: directory,
+      mount: (file && to.endsWith("/") ? join(to, basename(path)) : to).replace(
+        /\/+$/,
+        ""
+      ),
+    };
+  });
+}
+
+function locate(source: ResolvedStaticSource, pathname: string) {
+  if (source.file) return pathname === source.mount ? source.path : undefined;
+  if (pathname !== source.mount && !pathname.startsWith(`${source.mount}/`)) {
+    return undefined;
+  }
+  const path = resolve(source.path, `.${pathname.slice(source.mount.length)}`);
+  const within = relative(source.path, path);
+  if (within.startsWith("..")) return undefined;
+  if (within.split(sep).some((part) => SKIP.has(part))) return undefined;
+  if (within === source.watch) return undefined;
+  if (within === "package.json" && source.packageDirectory) return undefined;
+  return path;
+}
+
+/** How a source is named in messages: a specifier, or the shorter of the paths. */
+function label(source: ResolvedStaticSource, root: string) {
+  if (source.packageDirectory) return source.from;
+  const path = relative(root, source.path);
+  return path.split(sep).filter((part) => part === "..").length > 1
+    ? source.path
+    : path;
+}
+
+async function files(source: string, directory = source): Promise<string[]> {
+  const paths: string[] = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) paths.push(...(await files(source, path)));
+    if (entry.isFile()) paths.push(relative(source, path));
+  }
+  return paths;
+}
+
+/**
+ * Mounts `static` sources: served in dev, copied into the site at build.
+ *
+ * Sources never overwrite the site's own output — neither the build's, nor
+ * `public/`, nor an earlier source in the list. So precedence is just list
+ * order, and a site keeps its own `modules.json` by listing it before the
+ * package it borrows the rest of the packages from.
+ */
+export function staticPlugin(
+  options: PatchworkVitePluginOptions = {}
+): Plugin | null {
+  if (!options.static?.length) return null;
+  let sources: ResolvedStaticSource[] = [];
+  let root: string;
+  let outDir: string;
+  let base = "/";
+  let logger: Logger;
+  return {
+    name: "@patchwork/static",
+    configResolved(config) {
+      sources = resolveStatic(options, config.root);
+      root = config.root;
+      outDir = resolve(config.root, config.build.outDir);
+      base = config.base;
+      logger = config.logger;
+    },
+    async closeBundle() {
+      for (const source of sources) {
+        const paths = source.file ? [""] : await files(source.path);
+        const kept: string[] = [];
+        for (const path of paths) {
+          if (path === source.watch) continue;
+          // a package that doesn't declare a static directory mounts its whole
+          // root, and its manifest isn't part of the site
+          if (path === "package.json" && source.packageDirectory) continue;
+          const to = join(outDir, `.${source.mount}`, path);
+          await mkdir(dirname(to), { recursive: true });
+          try {
+            // EXCL rather than a check, so the build's own output and public/
+            // win a collision no matter what order the copies happen in.
+            await copyFile(
+              join(source.path, path),
+              to,
+              constants.COPYFILE_EXCL
+            );
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+            kept.push(join(source.mount, "/", path));
+          }
+        }
+        if (kept.length) {
+          logger.info(
+            `[patchwork] ${label(source, root)}: ${kept.length} ${
+              kept.length === 1 ? "file was" : "files were"
+            } already in the site and not copied over — ${kept
+              .slice(0, 5)
+              .join(
+                ", "
+              )}${kept.length > 5 ? `, and ${kept.length - 5} more` : ""}`,
+            { timestamp: true }
+          );
+        }
+      }
+    },
+    configureServer(server) {
+      const watched = new Map(
+        sources
+          .filter((source) => source.watch)
+          .map((source) => [join(source.path, source.watch!), source])
+      );
+      for (const path of watched.keys()) server.watcher.add(path);
+      server.watcher.on("change", (path) => {
+        if (watched.has(path)) server.ws.send({ type: "full-reload" });
+      });
+
+      // Returned, so this runs after vite's own public/static middlewares and
+      // dev matches the build: sources fill in what the site doesn't have.
+      // By then the SPA fallback has rewritten req.url to /index.html, so the
+      // path being asked for is the one connect saved on the way in.
+      return () => {
+        server.middlewares.use(async (request, response, next) => {
+          const url =
+            (request as IncomingMessage & { originalUrl?: string })
+              .originalUrl ??
+            request.url ??
+            "/";
+          let pathname: string;
+          try {
+            pathname = decodeURIComponent(
+              new URL(url, "http://localhost").pathname
+            );
+          } catch {
+            return next();
+          }
+          if (base !== "/" && pathname.startsWith(base)) {
+            pathname = pathname.slice(base.length - 1);
+          }
+          for (const source of sources) {
+            const path = locate(source, pathname);
+            if (!path) continue;
+            try {
+              if (!statSync(path).isFile()) continue;
+              response.setHeader("Cache-Control", "no-cache");
+              response.setHeader(
+                "Content-Type",
+                CONTENT_TYPES[extname(path)] ?? "application/octet-stream"
+              );
+              response.end(await readFile(path));
+              return;
+            } catch {
+              continue;
+            }
+          }
+          next();
+        });
+      };
+    },
+  };
+}