@pithy-sh/vite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pithy-sh/vite",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/vite"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "generate": "bun scripts/generateClientEnv.ts",
+    "build": "bun run generate && tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "peerDependencies": {
+    "vite": "^6.1.0 || ^7.0.0 || ^8.0.0"
+  },
+  "dependencies": {
+    "@pithy-sh/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/i18n": "workspace:*",
+    "@pithy-sh/payments": "workspace:*",
+    "@pithy-sh/support": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@pithy-sh/turnstile": "workspace:*",
+    "@pithy-sh/ui-react": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/clientEnvDeclaration.ts

@@ -0,0 +1,314 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+/**
+ * **`client-env.d.ts` is generated from the four declared client projections (#398).**
+ *
+ * `@pithy-sh/ui-react`'s `templates/client-env.d.ts` is the ambient declaration for the four
+ * `virtual:pithy/*` modules, copied into an adopter's Worker by `pithy ui add react`. It used to be
+ * hand-written, three packages away from the `client:` projections that produce the values it
+ * describes, and #392 held the two together with a spawned compiler because there was no faithful
+ * source to generate from: `Capability.client` is typed `(context) => ClientProjection`, so each
+ * capability's real shape existed only as an inferred literal inside a closure.
+ *
+ * #395 removed that. The four capabilities now declare their projection types, and the declaration is
+ * the source of truth rather than a restatement of the literal. So there is exactly one statement of
+ * each shape, and this module copies it — **a gate that watches two things agree is strictly worse
+ * than one thing.**
+ *
+ * ## Why the declared type is copied as text rather than re-printed from a type
+ *
+ * Because the doc comments are half of what the file is worth. A declaration emitted from a resolved
+ * type carries the shape and loses every sentence attached to it, and those sentences are what tell a
+ * screen that `action` must be rendered and never retyped, or that a Paddle client token is
+ * publishable by design. Copying the type node's own source text keeps the unions, the `| null` arms
+ * and the prose exactly as the capability wrote them.
+ *
+ * The one thing that is *not* copied is what is not a shape at all — see {@link PREAMBLE} and
+ * {@link ENABLED_EXPORT}, both of which are policy and are written as fixed text.
+ *
+ * ## Nothing an adopter runs
+ *
+ * The kit generates at its own build time and commits the artifact. `pithy ui add react` still copies
+ * a plain static `.d.ts` into a Worker, and a scaffolded project typechecks with no new step.
+ */
+
+/** One `virtual:pithy/*` module, and the declared type that is its whole shape. */
+export interface DeclaredModule {
+  /** The capability name — the segment after `virtual:pithy/`. */
+  readonly module: string;
+  /** The specifier the projection is read from. Resolved through the package's own exports map. */
+  readonly specifier: string;
+  /** The exported type alias that declares what a browser receives. */
+  readonly type: string;
+}
+
+/**
+ * The modules the declaration covers, in the order they are emitted.
+ *
+ * This list is the whole reach of the generated file: a further capability projecting to a browser is
+ * a further entry here, and until it is one, nothing declares it. The specifiers resolve because each
+ * capability is a devDependency of `@pithy-sh/vite` — a build-time dependency, like the compiler. An
+ * adopter installs none of them to use the plugin, and never runs this module.
+ */
+export const DECLARED_MODULES: readonly DeclaredModule[] = [
+  { module: "auth", specifier: "@pithy-sh/auth/src/client/projection", type: "AuthClientProjection" },
+  { module: "i18n", specifier: "@pithy-sh/i18n/src/client/projection", type: "I18nClientProjection" },
+  { module: "payments", specifier: "@pithy-sh/payments/src/client/projection", type: "PaymentsClientProjection" },
+  { module: "support", specifier: "@pithy-sh/support/src/client/projection", type: "SupportClientProjection" },
+  { module: "turnstile", specifier: "@pithy-sh/turnstile/src/client/projection", type: "TurnstileClientProjection" },
+];
+
+/**
+ * **Fixed text, item one: the preamble.**
+ *
+ * The `vite/client` reference and the paragraph explaining why the default export is a union are
+ * policy about how the modules are consumed, not a projection of anything, so there is nothing to
+ * derive them from. They are written here.
+ */
+const PREAMBLE = `/// <reference types="vite/client" />
+
+// The client-safe projection of this worker's composed capabilities, served by @pithy-sh/vite.
+//
+// Each module is a DEFAULT export whose type is a union discriminated on \`enabled\`. That shape is
+// deliberate. A capability that is not composed projects \`{ enabled: false }\` and nothing else, so a
+// NAMED import of any other key would be a missing export and the build would fail — on exactly the
+// case this mechanism exists to make survivable. Importing the default and narrowing cannot fail:
+//
+//   import turnstile from "virtual:pithy/turnstile";
+//   if (!turnstile.enabled) return null;   // narrowed: sitekey, mode and token exist below this line
+//
+// The \`virtual:pithy/*\` modules are never written to disk. These declarations describe modules the
+// Vite plugin serves, built from the Worker's own pithy.config.ts.
+//
+// **Generated, and copied here as it was emitted (#398).** Each declaration below is a capability's
+// declared client projection — \`src/client/projection.ts\` in @pithy-sh/auth, @pithy-sh/payments,
+// @pithy-sh/support and @pithy-sh/turnstile — written out by @pithy-sh/vite's
+// \`src/clientEnvDeclaration.ts\` at kit build time. In the kit that is one statement of each shape and
+// nothing to keep in step: a field a projection stops emitting is a compile error where it is
+// projected, and this file moves in the same commit.
+//
+// In your repository it is yours, like every other seeded file. Editing it changes what your compiler
+// believes and nothing about what the plugin serves.
+`;
+
+/**
+ * **Fixed text, item two: the one named export.**
+ *
+ * `enabled` is declared alone on purpose, and the refusal is the feature. A capability nobody composed
+ * serves `{ enabled: false }` and nothing else, so `import { sitekey } from "virtual:pithy/turnstile"`
+ * has to fail the build — on exactly the case the union exists to make survivable. Deriving the named
+ * exports from the projection's keys would declare every one of them and take that refusal away.
+ */
+const ENABLED_EXPORT = `  /**
+   * Whether this capability is composed and serving on this worker. Also the union's discriminant.
+   *
+   * The only named export, deliberately. Every other key is reached through the default export and a
+   * narrowing — see the note at the top of this file.
+   */
+  export const enabled: boolean;
+`;
+
+/**
+ * Which characters of a TypeScript source are code — everything outside a comment or a string.
+ *
+ * Both passes below need it, and for the same reason: a brace in `` `POST {basePath}/feedback` `` and
+ * a type name in an `{@link …}` tag are text, and counting or rewriting them would be a silent wrong
+ * answer rather than an error. Template literals with `${}` substitutions are not handled, because a
+ * type position cannot hold one — `parseTypeAliases` refuses anything it cannot finish instead.
+ */
+function codeMask(source: string): boolean[] {
+  const mask: boolean[] = new Array<boolean>(source.length).fill(true);
+  let index = 0;
+  while (index < source.length) {
+    if (source.startsWith("//", index)) {
+      while (index < source.length && source[index] !== "\n") mask[index++] = false;
+      continue;
+    }
+    if (source.startsWith("/*", index)) {
+      const close = source.indexOf("*/", index + 2);
+      const stop = close === -1 ? source.length : close + 2;
+      while (index < stop) mask[index++] = false;
+      continue;
+    }
+    const quote = source[index];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      mask[index++] = false;
+      while (index < source.length) {
+        const char = source[index];
+        mask[index++] = false;
+        if (char === "\\") {
+          if (index < source.length) mask[index++] = false;
+          continue;
+        }
+        if (char === quote) break;
+      }
+      continue;
+    }
+    index += 1;
+  }
+  return mask;
+}
+
+/**
+ * An identifier, wherever one may start, and the head of a top-level exported type alias.
+ *
+ * Both are built per call rather than shared. A `g` flag carries `lastIndex` between uses, and
+ * {@link inlineAliases} recurses — one shared instance would have an inner call move the outer's
+ * cursor, which reads as a reference the generator simply skipped.
+ */
+const identifierPattern = (): RegExp => /[A-Za-z_$][A-Za-z0-9_$]*/g;
+const typeAliasPattern = (): RegExp => /^export type ([A-Za-z_$][A-Za-z0-9_$]*)\s*=/gm;
+
+/**
+ * The source text of every top-level `export type X = …;` in a module, keyed by name.
+ *
+ * The value is the type node's own text, verbatim: every doc comment, every union arm, every `| null`
+ * exactly as written. It is found by scanning for the `;` that closes the alias at bracket depth zero,
+ * over code characters only.
+ */
+export function parseTypeAliases(source: string): Map<string, string> {
+  const mask = codeMask(source);
+  const aliases = new Map<string, string>();
+  const pattern = typeAliasPattern();
+  for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+    const [head, name] = match;
+    const start = match.index;
+    if (!mask[start] || !name) continue;
+    const from = start + head.length;
+    let depth = 0;
+    let end = -1;
+    for (let index = from; index < source.length; index += 1) {
+      if (!mask[index]) continue;
+      const char = source[index];
+      if (char === "{" || char === "(" || char === "[") depth += 1;
+      else if (char === "}" || char === ")" || char === "]") depth -= 1;
+      else if (char === ";" && depth === 0) {
+        end = index;
+        break;
+      }
+    }
+    if (end === -1) throw new Error(`\`export type ${name}\` is never closed by a \`;\` at depth zero.`);
+    aliases.set(name, source.slice(from, end));
+  }
+  return aliases;
+}
+
+/** The leading spaces of the line `index` falls on. What an inlined alias has to be pushed out by. */
+function indentAt(text: string, index: number): string {
+  const lineStart = text.lastIndexOf("\n", index - 1) + 1;
+  return /^[ ]*/.exec(text.slice(lineStart, index))?.[0] ?? "";
+}
+
+/**
+ * Replace every reference to a sibling type alias with that alias's own text, re-indented to sit where
+ * the reference did.
+ *
+ * `PaymentsClientProduct` is the only one today, and it is named rather than inlined at the source for
+ * a reason #395 recorded — the annotation goes on the `.map` callback, where a fresh literal is still
+ * checked in both directions. The declaration an adopter reads has no such seam to hang a name on, so
+ * the shape is written where it is used.
+ */
+export function inlineAliases(
+  text: string,
+  aliases: ReadonlyMap<string, string>,
+  seen: readonly string[] = [],
+): string {
+  const mask = codeMask(text);
+  const parts: string[] = [];
+  let cursor = 0;
+  const pattern = identifierPattern();
+  for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+    const name = match[0];
+    const body = aliases.get(name);
+    if (body === undefined || !mask[match.index]) continue;
+    if (seen.includes(name)) throw new Error(`\`${name}\` refers to itself through ${seen.join(" → ")}.`);
+    const indent = indentAt(text, match.index);
+    const inlined = inlineAliases(body, aliases, [...seen, name]);
+    parts.push(text.slice(cursor, match.index), reindent(inlined.trim(), indent));
+    cursor = match.index + name.length;
+  }
+  parts.push(text.slice(cursor));
+  return parts.join("");
+}
+
+/** Push every line but the first out by `indent`. The first is already sitting where it was written. */
+function reindent(text: string, indent: string): string {
+  return text
+    .split("\n")
+    .map((line, position) => (position === 0 || line === "" ? line : `${indent}${line}`))
+    .join("\n");
+}
+
+/**
+ * Move a block from the column it was written at to the one it is emitted at.
+ *
+ * The alias text arrives at whatever depth its source file put it — a union's arms at two spaces, its
+ * members at six. Inside a `declare module` block those want four and eight. So the block is dedented
+ * by its own first line's indent and then pushed out uniformly, which keeps every relative depth,
+ * including the ` *` continuation of a doc comment.
+ */
+function shift(text: string, indent: string): string {
+  const lines = text.split("\n");
+  while (lines.length > 0 && (lines[0] ?? "").trim() === "") lines.shift();
+  while (lines.length > 0 && (lines.at(-1) ?? "").trim() === "") lines.pop();
+  const base = /^[ ]*/.exec(lines[0] ?? "")?.[0] ?? "";
+  return lines
+    .map((line) => (line.startsWith(base) ? `${indent}${line.slice(base.length)}` : `${indent}${line.trimStart()}`))
+    .join("\n");
+}
+
+/** One `declare module "virtual:pithy/<module>"` block, fixed text and declared shape together. */
+export function renderModule(module: string, declaredType: string): string {
+  return [
+    `declare module "virtual:pithy/${module}" {`,
+    ENABLED_EXPORT,
+    "  const config:",
+    `${shift(declaredType, "    ")};`,
+    "  export default config;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The whole file, from each module's projection source.
+ *
+ * Pure, and the module list is an argument, so the test can hand it a projection this repository does
+ * not contain and read what came out. A generator asserted only against the real four would pass just
+ * as well if it ignored them and printed a constant.
+ */
+export function renderClientEnv(
+  sources: ReadonlyMap<string, string>,
+  modules: readonly DeclaredModule[] = DECLARED_MODULES,
+): string {
+  const blocks: string[] = [];
+  for (const declared of modules) {
+    const source = sources.get(declared.module);
+    if (source === undefined) throw new Error(`No projection source for virtual:pithy/${declared.module}.`);
+    const aliases = parseTypeAliases(source);
+    const body = aliases.get(declared.type);
+    if (body === undefined) throw new Error(`${declared.specifier} exports no type \`${declared.type}\`.`);
+    aliases.delete(declared.type);
+    blocks.push(renderModule(declared.module, inlineAliases(body, aliases)));
+  }
+  return `${PREAMBLE}\n${blocks.join("\n")}`;
+}
+
+/** Read the four projection sources through their own packages' exports maps. */
+export async function readProjectionSources(): Promise<Map<string, string>> {
+  const sources = new Map<string, string>();
+  for (const declared of DECLARED_MODULES) {
+    const path = fileURLToPath(import.meta.resolve(declared.specifier));
+    sources.set(declared.module, await readFile(path, "utf8"));
+  }
+  return sources;
+}
+
+/** The declaration as it should be on disk. What `bun run generate` writes and the gate compares. */
+export async function generateClientEnv(): Promise<string> {
+  return renderClientEnv(await readProjectionSources());
+}

package/src/devOrigin.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
+import { ENVIRONMENT_VAR, WORKER_ORIGIN_VAR } from "@pithy-sh/core/src/worker/identity";
+
+/**
+ * The slice of `@cloudflare/vite-plugin`'s worker config this touches.
+ *
+ * Structural rather than imported. `@pithy-sh/vite` does not depend on that plugin — an adopter picks
+ * its own version — and naming one field is enough to be checked against it at the call site, where the
+ * real type applies.
+ */
+export interface WorkerVars {
+  /** The Worker's plain environment variables, as `wrangler.jsonc` declared them. */
+  vars?: Record<string, WorkerVarValue>;
+}
+
+/**
+ * What a wrangler `vars` entry may hold — wrangler's own `Json`, restated.
+ *
+ * Restated rather than imported for the reason {@link WorkerVars} is structural, and it has to be this
+ * exact shape rather than `unknown`: the customizer's return type is checked against
+ * `Partial<WorkerConfig>` at the call site, and `Record<string, unknown>` is not assignable to
+ * `Record<string, Json>` — an index signature is invariant. A looser type here compiles in this package
+ * and fails in every adopter's, which is the worst place to find out.
+ */
+export type WorkerVarValue = string | number | boolean | null | WorkerVarValue[] | { [key: string]: WorkerVarValue };
+
+/**
+ * Give the Worker the origin `pithy dev` allocated this checkout, as `BASE_URL`.
+ *
+ * Spread into `@cloudflare/vite-plugin`'s `config` customizer:
+ *
+ * ```ts
+ * cloudflare({ config: devWorkerConfig() })
+ * ```
+ *
+ * **Why an adopter writes a line at all.** A Worker launched through `wrangler dev` is handed its own
+ * origin on the argv, by `pithy dev`, with nothing to configure. A Worker launched through a custom
+ * `dev.command` is a Vite dev server, and there is no argv to append a `--var` to: `@cloudflare/vite-plugin`
+ * takes the Worker's `vars` from `wrangler.jsonc`, and the only documented way in is this customizer,
+ * which lives in the adopter's `vite.config.ts`. `pithy init` scaffolds it; an existing project adds
+ * the line once and `pithy doctor` says so until it does.
+ *
+ * **Why it has to be given rather than written down.** A dev port is *allocated* — every checkout
+ * reserves its own block — so a `vars.BASE_URL` in `wrangler.jsonc` is right in the first checkout on a
+ * machine and wrong in every other one. That is not cosmetic: `BASE_URL` is the `iss` on every
+ * control-plane token a Worker signs and the origin its callback links are built against, so a second
+ * checkout signed tokens as the first one and its own seam denied every call, 401, with every stored
+ * value agreeing (#462, `pithy-sh/dashboard#95`).
+ *
+ * **Outside `pithy dev` it does nothing at all.** A plain `vite dev`, a build, or CI has no
+ * {@link WORKER_ORIGIN_VAR} in its environment, and the Worker keeps whatever `wrangler.jsonc` says —
+ * which for a deployed environment is the value `applyDomains` generated from `domains`, and is
+ * correct. This never invents an origin; it only passes on one that was allocated.
+ */
+export function devWorkerConfig(env: NodeJS.ProcessEnv = process.env): (config: WorkerVars) => WorkerVars {
+  return (config) => {
+    const origin = env[WORKER_ORIGIN_VAR];
+    // Absent, blank, or whitespace is "nobody allocated one", never "use the empty string". An empty
+    // `BASE_URL` is worse than a wrong one: it fails a URL parse somewhere far from here rather than
+    // being denied at the seam with the origin named.
+    if (origin === undefined || origin.trim() === "") return {};
+    // And never over a config that says, itself, that it is not dev.
+    //
+    // The customizer is applied on `build` as well as on `serve`, and it beats the `vars` the file
+    // declared — so the whole of what keeps a localhost origin out of a deploy is that only
+    // `pithy dev` ever sets `WORKER_ORIGIN_VAR`, on the children it spawns. That is true, and it is
+    // one exported variable away from not being true, and the failure would be silent and severe: a
+    // deployed Worker signing every control-plane token with a `localhost` issuer, and mailing magic
+    // links to an address nobody can reach.
+    //
+    // **Only ever removes the override, and only on a positive answer.** A stanza that does not stamp
+    // `ENVIRONMENT` cannot say which environment it is, and refusing there would silently withhold
+    // the fix from the dev run it exists for — the failure this whole issue was.
+    const environment = config.vars?.[ENVIRONMENT_VAR];
+    if (typeof environment === "string" && environment !== LOCAL_ENVIRONMENT) return {};
+    return { vars: { ...config.vars, BASE_URL: origin } };
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,214 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { resolve } from "node:path";
+import { resolveClientProjection } from "@pithy-sh/core/src/capability/client";
+import { type EnvironmentModuleNode, normalizePath, type Plugin, type ViteDevServer } from "vite";
+import {
+  capabilityNameFromResolvedId,
+  isResolvedVirtualId,
+  renderVirtualModule,
+  resolveVirtualId,
+} from "./virtualModule";
+import { type LoadedWorkerConfig, loadWorkerConfig } from "./workerConfig";
+
+/**
+ * What {@link pithy} hands back: a Vite plugin, described without naming a Vite type.
+ *
+ * **The return type used to be Vite's own `Plugin`, and that made the peer range a lie — Jim,
+ * 2026-08-21 (#414).** `package.json` declares `vite: ^6.1.0 || ^7.0.0 || ^8.0.0`, but a `Plugin` in
+ * the signature is a `Plugin` out of *this package's* `node_modules`. An adopter who resolved any
+ * other copy — which is every adopter developing against a symlinked kit, and every adopter whose
+ * install did not deduplicate — had to prove the kit's copy assignable to theirs, field by field,
+ * before `plugins: [pithy()]` would compile. Across majors that comparison fails outright: `hotUpdate`
+ * does not carry the same `this` in 6 as in 8, so this plugin was not a Vite 6 plugin however identical
+ * the hook body is. Within a major it does not even finish — `Plugin` is deep and recursive enough to
+ * exhaust tsc's depth budget, which is the `TS2321: Excessive stack depth` that stopped
+ * `pithy-sh/dashboard` typechecking the `vite.config.ts` `pithy init` had just written for it. A peer
+ * dependency that only compiles when the install deduplicates is not a peer dependency.
+ *
+ * So the signature promises the two things every Vite in that range agrees on and an adopter's
+ * checker can settle in two comparisons: the plugin has a name, and it runs early. No recursion, no
+ * hook signatures, nothing that can differ between two copies of the same library.
+ *
+ * **What is still checked.** The object below is written `satisfies Plugin` against the Vite this
+ * package develops against, so every hook keeps its parameter types, its `this`, and its return type.
+ * A hook that reads the wrong field off `config`, returns the wrong shape, or is spelled with a name
+ * Vite does not call is still a red build — here, where the kit is compiled, and in
+ * `tooling/vite-adopter`, which compiles this file too.
+ *
+ * **What is not.** The adopter's checker no longer re-derives any of that against their copy. It sees
+ * two properties and takes the hooks on trust. Four things pay for that trust and none of them is a
+ * type an adopter has to compare: `tooling/vite-adopter` compiles the return against every major in
+ * the peer range and runs a real `vite build` through the plugin at each of them, {@link
+ * PITHY_PLUGIN_HOOKS} holds every hook name to something all three call, `plugin.test.ts` drives each
+ * hook by hand, and it runs a real `vite build` and reads the bundle.
+ *
+ * **One gap, named rather than papered over — Jim, 2026-08-21.** The hook *signatures* are checked
+ * against one Vite, and there is no arrangement in which they could be checked against three. Vite 8
+ * is rolldown-based and Vite 6 and 7 are rollup-based, so `hotUpdate`'s `this` is
+ * `MinimalPluginContext & { environment: DevEnvironment }` out of two different bundlers — `meta`
+ * carries `rolldownVersion` in one and not the other. A single object cannot be written `satisfies
+ * Plugin` against both; restoring `pithy(): Plugin` reports exactly that at 6.1.6 and 7.0.0, and it is
+ * a fact about the two Vites rather than about this plugin. What is checked across the range is the
+ * hook *set* and the hook *behavior*: a name Vite 6 never calls is a red build, and a build that does
+ * not inline the projection at 6.1.6 is a red test. What is taken on trust across the range is that a
+ * hook Vite 6 calls with an argument of its own shape reaches the same field.
+ *
+ * **Why the floor is `^6.1.0` is not recorded here, because the reason first written down was wrong —
+ * Jim, 2026-08-21.** It said `hotUpdate` arrived in 6.1 and that below it this plugin would be silently
+ * inert. It did not: `npm pack vite@6.0.0` carries `hotUpdate?: ObjectHook<…>` in `index.d.ts`, and its
+ * `HotUpdatePluginContext` is byte-identical to 6.1.6's. The floor may still be right for a reason
+ * nobody has written down, and `6.0.0` is not pinned in `tooling/vite-adopter`, so nothing here has ever
+ * compiled against it.
+ *
+ * Two honest next steps, neither taken in this change: pin `6.0.0` in the fixture and find out, or drop
+ * the floor to `^6.0.0` and let the fixture say whether that holds. **An invented reason is worse than
+ * an absent one**, because the next person reads it instead of measuring.
+ */
+export interface PithyPlugin {
+  /** `"pithy"`. The plugin's identity in Vite's plugin list, and in any error raised from a hook. */
+  name: string;
+  /**
+   * `"pre"`, always. `virtual:pithy/*` is claimed before any other plugin can, so the order of an
+   * adopter's `plugins` array never decides whether the front end can read its own backend.
+   */
+  enforce: "pre";
+}
+
+/**
+ * Every hook {@link pithy} defines, by name.
+ *
+ * **The one thing about the hooks an adopter's checker can be given for free.** {@link PithyPlugin}
+ * deliberately names no Vite type, so nothing in the return says which hooks exist — and a hook Vite
+ * never calls is dead code that looks like a feature. A name is not a Vite type: `tooling/vite-adopter`
+ * asserts each of these is a `keyof Plugin` in 6, 7 and 8, which costs an adopter nothing and catches
+ * the regression that matters here. Adding a `buildApp` hook, which Vite 7 introduced and Vite 6 has no
+ * name for, reddens the fixture rather than shipping under a range that claims 6.
+ *
+ * `plugin.test.ts` holds this list to the object itself, both directions, at runtime — a hook added
+ * without listing it is a failure there, and a name listed that no longer exists is one too. A list
+ * that can drift from what it lists is a worse gate than none.
+ */
+export const PITHY_PLUGIN_HOOKS = ["configResolved", "configureServer", "resolveId", "load", "hotUpdate"] as const;
+
+/** One of the names {@link PITHY_PLUGIN_HOOKS} lists. */
+export type PithyPluginHook = (typeof PITHY_PLUGIN_HOOKS)[number];
+
+/** Options for {@link pithy}. Every one has a working default; `pithy()` is the usual call. */
+export interface PithyPluginOptions {
+  /**
+   * The Worker's `pithy.config.ts`. Relative paths resolve against the Vite root, which for a Pithy
+   * Worker is `apps/<name>/` — so the default, `pithy.config.ts`, is already the right file.
+   */
+  configFile?: string;
+  /**
+   * The environment this bundle is built for. Defaults to `ENVIRONMENT` in the process env, then
+   * `dev`. `pithy deploy --env <name>` is what threads a real value in, so a production bundle sees
+   * production's projection and a dev bundle sees dev's.
+   */
+  environment?: string;
+}
+
+/**
+ * Serve one `virtual:pithy/<capability>` module per capability, projected from the Worker's own
+ * `pithy.config.ts`.
+ *
+ * A screen imports what it needs — `import auth from "virtual:pithy/auth"` — and gets that
+ * capability's client-safe projection inlined at build time. A capability the Worker does not compose
+ * resolves to `{ enabled: false }` rather than failing the import, including a name nobody has ever
+ * heard of: a screen branches on `enabled`, it does not guard on whether the module exists.
+ */
+export function pithy(options: PithyPluginOptions = {}): PithyPlugin {
+  const environment = options.environment ?? process.env.ENVIRONMENT ?? "dev";
+  let configFile = "";
+  // Memoize the promise, not the value: `load` runs concurrently for every virtual module a bundle
+  // imports, and each `runnerImport` builds a fresh environment. One promise means one config load.
+  let loading: Promise<LoadedWorkerConfig> | null = null;
+  let server: ViteDevServer | undefined;
+  const watched = new Set<string>();
+
+  function watch(files: Iterable<string>): void {
+    for (const file of files) {
+      const path = normalizePath(file);
+      if (watched.has(path)) continue;
+      watched.add(path);
+      server?.watcher.add(path);
+    }
+  }
+
+  function loadOnce(): Promise<LoadedWorkerConfig> {
+    loading ??= loadWorkerConfig(configFile)
+      .then((loaded) => {
+        // The config's transitive imports are watched too, so editing a file the config imports
+        // reloads the front end just like editing the config itself.
+        watch(loaded.dependencies);
+        return loaded;
+      })
+      .catch((cause: unknown) => {
+        // Never memoize a failure. A first load can fail for reasons the developer is about to fix —
+        // most often `pithy dev` run before `bun install`, so the config's `@pithy-sh/*` imports do
+        // not resolve. Caching the rejection would wedge the dev server on that error until restart,
+        // and `hotUpdate` could not rescue it: the watch set only learns the config's transitive
+        // imports from a load that SUCCEEDED, so a file the developer then edits may not be watched.
+        loading = null;
+        throw cause;
+      });
+    return loading;
+  }
+
+  // `satisfies` rather than an annotation, and the difference is the whole fix. It contextually types
+  // every hook below against Vite's `Plugin` — same checking as the old `: Plugin` return type gave —
+  // while leaving the literal's own type intact, so the narrow `PithyPlugin` the signature promises is
+  // still derived from what is actually returned rather than asserted over it. A `const` because a
+  // fresh object literal returned straight out would be excess-property-checked against `PithyPlugin`,
+  // which names none of the hooks.
+  const plugin = {
+    name: "pithy",
+    // Claim `virtual:pithy/*` before any other plugin can, so the plugin array's order in an
+    // adopter's vite.config.ts never decides whether the front end can read its own backend.
+    enforce: "pre",
+
+    configResolved(config) {
+      // `resolve` leaves an absolute option alone and anchors a relative one to the Vite root.
+      configFile = normalizePath(resolve(config.root, options.configFile ?? "pithy.config.ts"));
+      watch([configFile]);
+    },
+
+    configureServer(devServer) {
+      server = devServer;
+      // Watch before the first load: a config that fails to import is still watched, so fixing it
+      // recovers the dev server instead of requiring a restart.
+      for (const path of watched) devServer.watcher.add(path);
+    },
+
+    resolveId(id) {
+      return resolveVirtualId(id);
+    },
+
+    async load(id) {
+      const name = capabilityNameFromResolvedId(id);
+      if (name === null) return null;
+      const { capabilities } = await loadOnce();
+      return renderVirtualModule(resolveClientProjection(capabilities.get(name), { environment }));
+    },
+
+    hotUpdate({ file }) {
+      if (!watched.has(normalizePath(file))) return;
+      // Drop the memo so the next `load` re-reads the config, then invalidate what it produced.
+      loading = null;
+      const invalidated: EnvironmentModuleNode[] = [];
+      for (const [id, module] of this.environment.moduleGraph.idToModuleMap) {
+        if (!isResolvedVirtualId(id)) continue;
+        this.environment.moduleGraph.invalidateModule(module);
+        invalidated.push(module);
+      }
+      // Config is read at module scope by screens all over the app; a full reload is the honest
+      // update, and returning the invalidated modules keeps Vite from also guessing at one.
+      this.environment.hot.send({ type: "full-reload" });
+      return invalidated;
+    },
+  } satisfies Plugin;
+
+  return plugin;
+}

package/src/testPlugin.ts

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { fileURLToPath } from "node:url";
+import { runnerImport } from "vite";
+import type { PithyPlugin, PithyPluginOptions } from "./plugin";
+
+/**
+ * `./plugin.ts`, as an absolute path.
+ *
+ * From `import.meta.url` rather than from a bare specifier: this file's own realpath is the one place
+ * the build plugin is certainly beside, whatever an adopter's `node_modules` looks like — a symlinked
+ * checkout, a hoisted install, a worktree.
+ */
+const BUILD_PLUGIN = fileURLToPath(new URL("./plugin.ts", import.meta.url));
+
+/**
+ * The Pithy plugin, for a test runner's config.
+ *
+ * **It is not a second plugin.** It resolves to the object {@link pithy} returns, built from
+ * `./plugin.ts` itself, so a test imports the module a build inlines — same config, same
+ * `resolveClientProjection`, same `renderVirtualModule`, same bytes. There is no fixture here, and
+ * therefore nothing that can drift from the projection. `testPlugin.test.ts` holds that: it renders a
+ * module through the build plugin's own `load` hook and makes a real child `vitest` run compare what it
+ * imports against it.
+ *
+ * ## Why the indirection exists at all
+ *
+ * Vitest loads its config by bundling it and leaving every **bare** specifier to node. So
+ * `import { pithy } from "@pithy-sh/vite/src/plugin"` in a `vitest.config.ts` is handed to node, which
+ * loads `plugin.ts` — and stops at its `@pithy-sh/core/src/capability/client` import, whose own
+ * `../error/pithyError` has no extension for node to resolve. The config never loads and no test runs.
+ * `vitest.shared.ts` in this repository documents the same wall from the other side, for the same reason.
+ *
+ * This module's whole static graph is `vite` and `node:url` — both things node loads — and the kit
+ * source is reached through {@link runnerImport}, which is vite's own loader and resolves extensionless
+ * TypeScript the way every other Pithy import site does. That constraint is load-bearing: **any
+ * `@pithy-sh/*` import added to this file breaks every adopter's test run at config load.** The child
+ * run in `testPlugin.test.ts` is what says so out loud.
+ *
+ * ## What an adopter writes
+ *
+ * One line, in the test project that mounts client modules — never per consumer:
+ *
+ * ```ts
+ * import { pithyTest } from "@pithy-sh/vite/src/testPlugin";
+ *
+ * export default defineConfig({
+ *   plugins: [pithyTest({ configFile: "apps/board/pithy.config.ts" })],
+ *   test: { environment: "happy-dom" },
+ * });
+ * ```
+ *
+ * `configFile` resolves against the Vite root, which for a test run is usually the repository root
+ * rather than the Worker's directory — so a monorepo names the Worker, and a single-Worker project takes
+ * the default.
+ *
+ * A promise, because vite awaits a plugin. That is a documented `PluginOption`, and it is what lets the
+ * real plugin be built by vite's loader instead of restated for node's.
+ *
+ * `Promise<PithyPlugin>` rather than `Promise<Plugin>` for the reason {@link PithyPlugin} gives (#414):
+ * a Vite type in this signature is *this package's* Vite type, and an adopter's `vitest.config.ts`
+ * cannot be typechecked against it unless their install happened to deduplicate onto the same copy.
+ * The test config is the same surface as the build config and takes the same rule.
+ */
+export function pithyTest(options: PithyPluginOptions = {}): Promise<PithyPlugin> {
+  return runnerImport<typeof import("./plugin")>(BUILD_PLUGIN).then(({ module }) => module.pithy(options));
+}

package/src/virtualModule.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ClientProjection } from "@pithy-sh/core/src/capability/client";
+
+/**
+ * The import specifier a screen writes: `import auth from "virtual:pithy/auth"`. One module per
+ * capability, resolved from the Worker's own `pithy.config.ts` — so a front end reads the backend it
+ * is served by, and never a hand-copied duplicate of its config.
+ */
+export const VIRTUAL_PREFIX = "virtual:pithy/";
+
+/**
+ * The resolved id. The leading NUL is Rollup's convention for "this module has no file" — it stops
+ * other plugins and the filesystem resolver from touching it.
+ */
+export const RESOLVED_PREFIX = "\0virtual:pithy/";
+
+/**
+ * A capability name as it may appear after the prefix: one segment, the same lowercase-hyphenated
+ * shape as `pithy add <capability>`. Anything else (a path, an empty name, a traversal) is not ours,
+ * so `resolveVirtualId` declines it and Vite reports its usual unresolved-import error.
+ */
+const CAPABILITY_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+
+/** A key that can legally be re-exported as `export const <key>`. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Keys that are valid object keys but not valid binding names. A projection carrying one still
+ * reaches the default export; only its named export is skipped, so nothing is silently lost.
+ */
+const RESERVED = new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+]);
+
+/** Map an import specifier to its resolved id, or `null` when the specifier is not a Pithy virtual module. */
+export function resolveVirtualId(id: string): string | null {
+  if (!id.startsWith(VIRTUAL_PREFIX)) return null;
+  const name = id.slice(VIRTUAL_PREFIX.length);
+  if (!CAPABILITY_NAME.test(name)) return null;
+  return `${RESOLVED_PREFIX}${name}`;
+}
+
+/** The capability name carried by a resolved id, or `null` when the id is not one of ours. */
+export function capabilityNameFromResolvedId(id: string): string | null {
+  if (!id.startsWith(RESOLVED_PREFIX)) return null;
+  const name = id.slice(RESOLVED_PREFIX.length);
+  return CAPABILITY_NAME.test(name) ? name : null;
+}
+
+/** Whether a module id is a resolved Pithy virtual module — used to sweep the dev module graph. */
+export function isResolvedVirtualId(id: string): boolean {
+  return capabilityNameFromResolvedId(id) !== null;
+}
+
+/**
+ * Render a projection as module source. Both shapes are emitted on purpose: the default export for
+ * `import auth from "virtual:pithy/auth"`, and one named export per key so a bundler can tree-shake
+ * `import { enabled } from "virtual:pithy/auth"` down to a single inlined literal.
+ *
+ * Every value is emitted through `JSON.stringify`, which is the second half of the security boundary
+ * — the projection was already validated as JSON, and nothing but JSON can be written here.
+ */
+export function renderVirtualModule(projection: ClientProjection): string {
+  const lines = [`export default ${JSON.stringify(projection)};`];
+  for (const [key, value] of Object.entries(projection)) {
+    if (value === undefined) continue;
+    if (!IDENTIFIER.test(key) || RESERVED.has(key)) continue;
+    lines.push(`export const ${key} = ${JSON.stringify(value)};`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/workerConfig.ts

@@ -0,0 +1,215 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { access } from "node:fs/promises";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import {
+  causeMessage,
+  failurePosition,
+  isBuildFailureWrapper,
+  prop,
+  rootCause,
+  safeReason,
+  unresolvedSpecifier,
+} from "@pithy-sh/core/src/error/cause";
+import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { runnerImport } from "vite";
+
+/** The default export of a Worker's `pithy.config.ts`, before it is trusted. */
+interface WorkerConfigModule {
+  default?: { capabilities?: unknown; app?: unknown };
+}
+
+/** One Worker's composed capabilities, indexed by name, plus the files the config was built from. */
+export interface LoadedWorkerConfig {
+  /** Capability name → the capability, library capabilities first and the app capability last. */
+  capabilities: Map<string, Capability>;
+  /** Every file the config transitively imported — what the dev server watches so an edit reloads. */
+  dependencies: readonly string[];
+}
+
+/**
+ * Why a `pithy.config.ts` would not load — and therefore what may be said about it (#217).
+ *
+ * This loader built the same refusal the CLI's did, with the same defect. #207 fixed the CLI's
+ * (`packages/cli/src/project/config.ts`, `classifyConfigLoadFailure`); this file could not import that
+ * fix, because `@pithy-sh/vite` depends on `@pithy-sh/core` and must not depend on the CLI. So it is
+ * restated here, with the same rule behind it: **a `catch` reachable by more than one underlying failure
+ * may not name a single specific remedy.** Classify, or hedge. The convention is in `docs/CONVENTIONS.md`.
+ *
+ * What the copies *cannot* be allowed to disagree about is anything that is not a sentence. Two kinds of
+ * that were found, one issue apart, and both live in `@pithy-sh/core` — the one package this plugin
+ * already depends on. What a runtime does to an error on its way out is the first: `rootCause`, `prop`
+ * and `isBuildFailureWrapper`, facts no copy can derive and every copy got wrong (#223). Whether one of
+ * its strings is safe to show is the second: `safeReason`, `failurePosition`, `unresolvedSpecifier` and
+ * `causeMessage`, because a path or a stack frame is a property of the string and not of the surface
+ * quoting it — three near-verbatim copies of that filter meant the hole #223 found in it had to be closed
+ * three times (#228).
+ *
+ * What stays restated here is the policy: which causes this loader recognizes, and what it says about
+ * each. Those are genuinely per-surface, and this plugin still cannot import the CLI's.
+ */
+export type WorkerConfigFailureKind =
+  /** An import in the config does not resolve. `bun install`, or a corrected specifier. */
+  | "unresolved-import"
+  /** The file does not parse. Installing will not help, and the adopter has read the opposite for years. */
+  | "parse-error"
+  /** The config loaded far enough to throw its own error. Neither of the above. */
+  | "threw-on-load"
+  /** None of the above. No remedy: a wrong action is worse than no action, because it is followed. */
+  | "unknown";
+
+/** What may be said about a config that would not load. */
+export interface WorkerConfigFailure {
+  /** Which failure this was, decided from the cause and never asserted over it. */
+  kind: WorkerConfigFailureKind;
+  /** The remedy, chosen from the kind. Carries no absolute path, no source line, no stack. */
+  action: string;
+}
+
+/**
+ * The message, de-colored, for this classifier's own pattern tests — never for output.
+ *
+ * What may be *said* is core's {@link safeReason}, and only core's. This plugin cannot import the CLI's
+ * refusals and never could, which is why the sentences below are restated here — but the *filter* those
+ * sentences pass a string through is not a sentence. Whether a string carries an absolute path or half a
+ * parser's ANSI box is a property of the string, so it is decided in `@pithy-sh/core`, the one package
+ * this plugin depends on, and the suppression #223 had to write three times is written once (#228).
+ */
+function rawMessage(cause: unknown): string {
+  return causeMessage(cause) ?? "";
+}
+
+function isUnresolvedImport(cause: unknown): boolean {
+  const code = prop(cause, "code");
+  if (
+    code === "ERR_MODULE_NOT_FOUND" ||
+    code === "MODULE_NOT_FOUND" ||
+    code === "ERR_PACKAGE_PATH_NOT_EXPORTED" ||
+    code === "ERR_UNSUPPORTED_DIR_IMPORT"
+  ) {
+    return true;
+  }
+  if (prop(cause, "name") === "ResolveMessage") return true;
+  return /Cannot find (?:package|module) |Failed to resolve (?:import|module)|Failed to load url /.test(
+    rawMessage(cause),
+  );
+}
+
+function isParseError(cause: unknown): boolean {
+  const name = prop(cause, "name");
+  if (name === "SyntaxError" || name === "BuildMessage") return true;
+  if (prop(cause, "code") === "PARSE_ERROR") return true;
+  // Bun's build wrapper with its diagnostics already dropped — the shape every caller after the first
+  // sees, since a failed module is cached and re-thrown emptied out. It proves a build produced
+  // diagnostics, so it is a parse error with no reason to quote. See core's `cause.ts` (#223).
+  if (isBuildFailureWrapper(cause)) return true;
+  return /Transform failed|\[PARSE_ERROR]|Parse (?:error|failure)|Unexpected (?:token|end of input)/.test(
+    rawMessage(cause),
+  );
+}
+
+/** Choose the refusal's `action` **from** the failure rather than asserting one over it (#217). */
+export function classifyWorkerConfigFailure(wrapped: unknown): WorkerConfigFailure {
+  // Bun hands `import()` failures over inside an `AggregateError`. Classify what is inside it.
+  const cause = rootCause(wrapped);
+  if (isUnresolvedImport(cause)) {
+    const specifier = unresolvedSpecifier(cause);
+    return {
+      kind: "unresolved-import",
+      action: specifier
+        ? `Nothing resolves "${specifier}". Install the project's dependencies (bun install), or correct that import.`
+        : "An import in the config does not resolve. Install the project's dependencies (bun install), then check its imports.",
+    };
+  }
+
+  if (isParseError(cause)) {
+    // Both of these can answer "nothing", and Bun's build wrapper — a count and a path, and never a
+    // reason or a position — is one of the reasons they do. That suppression is core's, once (#223, #228).
+    const reason = safeReason(cause);
+    const at = failurePosition(cause);
+    const where = at ? ` Line ${at.line}, column ${at.column}.` : "";
+    return {
+      kind: "parse-error",
+      action: `The config does not parse${reason ? `: ${reason}` : ""}.${where} Fix the file — installing dependencies will not help.`,
+    };
+  }
+
+  // Anything that carries a message, whether or not it extends `Error` — the config's own throw.
+  if (causeMessage(cause) !== undefined) {
+    const reason = safeReason(cause);
+    return {
+      kind: "threw-on-load",
+      action: reason
+        ? `The config threw while loading: ${reason}. Fix that in the config.`
+        : "The config threw while loading. Run the file directly to see what it throws.",
+    };
+  }
+
+  return { kind: "unknown", action: "Check pithy.config.ts. Run the file directly to see how it fails." };
+}
+
+function isCapability(value: unknown): value is Capability {
+  return typeof value === "object" && value !== null && typeof (value as Capability).name === "string";
+}
+
+/**
+ * Load a Worker's `pithy.config.ts` and index the capabilities it composes.
+ *
+ * `runnerImport` is Vite's own loader: it builds a throwaway runnable environment with
+ * `configFile: false`, so the config's TypeScript, its extensionless relative imports, and its
+ * `@pithy-sh/*` source imports all resolve — none of which a bare dynamic `import()` handles — and it
+ * behaves identically under `vite dev` and `vite build`. It also reports the transitive files it
+ * touched, which is what makes HMR on a config edit possible.
+ */
+export async function loadWorkerConfig(configFile: string): Promise<LoadedWorkerConfig> {
+  try {
+    await access(configFile);
+  } catch {
+    throw new NotFoundError({
+      message: `No pithy.config.ts at ${configFile}.`,
+      action: "Run pithy ui add from the project root, or point the plugin at it with pithy({ configFile }).",
+    });
+  }
+
+  let module: WorkerConfigModule;
+  let dependencies: readonly string[];
+  try {
+    const imported = await runnerImport<WorkerConfigModule>(configFile);
+    module = imported.module;
+    dependencies = imported.dependencies.filter((file) => typeof file === "string" && file.length > 0);
+  } catch (cause) {
+    // The config is there and would not load. Which of the four ways it failed decides what to tell the
+    // adopter — see {@link classifyWorkerConfigFailure}. The raw cause still goes to `detail` and stops
+    // there: the CLI renderer prints `message` and `action` only, and the HTTP codec strips `detail`.
+    const { kind, action } = classifyWorkerConfigFailure(cause);
+    throw new InternalError({
+      message: `Could not load ${configFile}.`,
+      action,
+      detail: `${kind}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    });
+  }
+
+  const config = module.default;
+  if (!config || !Array.isArray(config.capabilities)) {
+    throw new InternalError({
+      message: `${configFile} doesn't default-export a worker config.`,
+      action: "Export default { capabilities, app }.",
+    });
+  }
+
+  const capabilities = new Map<string, Capability>();
+  for (const entry of config.capabilities) {
+    if (!isCapability(entry)) {
+      throw new InternalError({
+        message: `${configFile} lists something that isn't a capability.`,
+        action: "Every entry in capabilities is a capability object with a name. Remove the odd one out.",
+      });
+    }
+    capabilities.set(entry.name, entry);
+  }
+  // The app capability composes last, so a Worker's own projection wins over a library's.
+  if (isCapability(config.app)) capabilities.set(config.app.name, config.app);
+
+  return { capabilities, dependencies };
+}