@warlock.js/web 5.0.0

package/esm/vite/index.mjs

@@ -0,0 +1,146 @@
+import { HYDRATION_CLIENT_ENTRY_NAME, createHydrationClientEntry } from "./hydration-entries.mjs";
+import { buildHydrationClient } from "./build-client.mjs";
+import { gateAResolve } from "./gate-a-resolve.mjs";
+import { createPublicEnvTracker, gateBSecrets } from "./gate-b-secrets.mjs";
+import { ProjectionAmbiguityError, projection } from "./projection.mjs";
+import { buildPublicEnvManifest, findLeakedServerExports, findLeakedServerImportEdges, gateCVerify } from "./gate-c-verify.mjs";
+import { CLIENT_PAGE_REGISTRY_ID, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry } from "./page-registry-plugin.mjs";
+
+//#region ../web/src/vite/index.ts
+function clientEnvironmentOnly(plugin) {
+	return {
+		...plugin,
+		applyToEnvironment(environment) {
+			return environment.config.consumer === "client";
+		}
+	};
+}
+/**
+* The composed client-build pipeline: projection
+* strips the 5 server exports first, THEN Gate B's `transform` checks
+* whatever source remains for inline secret reads, THEN Gate A's
+* `resolveId` judges whatever imports remain. Array order here is
+* `[projection(), gateBSecrets(), gateAResolve()]` to match Vite's own
+* pipeline shape (`transform` before `resolveId`), but array order alone
+* does not guarantee this — see the hook-ordering fact below, which is what
+* actually makes the composition correct.
+*
+* Empirically observed fact (via an instrumented real `vite.build()`, not
+* assumed from plugin array order): for a given module M, Vite/Rollup calls
+* `transform(M)` BEFORE it calls `resolveId` for any of M's own import
+* specifiers — because Rollup must parse M's post-transform source to even
+* discover which specifiers to resolve next. Concretely: `transform` ran on
+* `entry.page.tsx` first, and only after that did `resolveId("./dep", ...)`
+* fire for the import statement still present in the transformed code. A
+* consequence follows directly: if projection's `transform` removes an
+* import statement from a page module entirely (e.g. `loader`'s
+* `@warlock.js/core` import, stripped because `loader` itself is removed),
+* `resolveId` is never invoked for that specifier at all — Gate A doesn't
+* "let it pass", it never sees it. Gate A's `resolveId` only fires for
+* imports that survive projection's `transform`, which is exactly why a
+* component-level `@warlock.js/core` import (never touched by projection)
+* still reaches and is refused by Gate A.
+*
+* This is OBSERVED Rollup behavior, not a documented contract — a future
+* Vite/Rollup upgrade could invert it. Pinned by a
+* regression test (`index.spec.ts`, "D.3 hook ordering pin") that fails
+* loudly if the ordering ever inverts, and by the `vite` peer floor in
+* `web/package.json` (`>=7.3.5`, the version this was verified against). If
+* that test ever fails after a Vite bump: the failure mode of the ordering
+* assumption breaking is SAFE — projection would stop removing an import
+* statement Gate A still sees, so Gate A would refuse an import it used to
+* silently let a stripped server export take with it. That is a loud build
+* failure ("Gate A refused an import"), never a silent client-bundle leak.
+* Do NOT "fix" an apparent Gate A false-positive after a Vite upgrade by
+* weakening Gate A (e.g. widening what it lets through) — investigate
+* whether this ordering assumption broke instead; loosening Gate A to work
+* around it would turn a loud failure into the exact silent leak this
+* pipeline exists to prevent.
+*
+* Gate B is placed between the two for the same reason, but for a `transform`
+* hook rather than `resolveId`: within a plugin array, Rollup runs each
+* module's registered `transform` hooks in array order, each one receiving
+* the PREVIOUS plugin's output. Running Gate B after projection means it
+* inspects the POST-projection source — a `process.env.SECRET` read inside
+* `loader` (a server export, legitimately reading a real secret server-side)
+* is invisible to Gate B once projection has already removed `loader`
+* entirely, exactly as it should be: Gate B's job is to fence client-bound
+* code, and projection is what decides what counts as client-bound. A
+* component-level secret read is untouched by projection and still reaches
+* Gate B, which refuses it. Gate B does not depend on Gate A's `resolveId`
+* output at all (orthogonal concern, raw source vs. import paths), so its
+* position relative to Gate A is not load-bearing — it is placed before Gate
+* A only to keep both `transform` hooks adjacent in the array.
+*
+* Gate C (`gate-c-verify.ts`) runs last and only at `generateBundle` — after
+* the entire `transform`/`resolveId` build phase has completed for every
+* plugin, regardless of array position (a Rollup lifecycle fact, not
+* something this array order enforces). It verifies the EMITTED output the
+* other three produced: no server export survived as a top-level binding, no
+* import edge into a server-only package survived into the module graph, and
+* it emits the reviewable `PUBLIC_*` inlined-value manifest. `gateBSecrets` and `gateCVerify` share
+* one `PublicEnvTracker` instance so the manifest and Gate B's own unread-key
+* exclusion check agree by construction, not by coincidence.
+*
+* `clientPageRegistry()` is FIRST, ahead of projection. It contributes no
+* `transform` at all — only a `resolveId`/`load` pair for one synthetic id —
+* so it cannot displace or pre-empt any gate's inspection of any real file.
+* Two reasons for the position, one of which is not load-bearing and is
+* labelled as such:
+*
+* 1. Load-bearing: it must own `virtual:warlock/pages` before Gate A's
+*    `resolveId` (also `enforce: "pre"`) reaches its `this.resolve(...)` call
+*    for that specifier. Gate A's nested resolve would find it anyway, but
+*    routing the id through Gate A's importer-chain bookkeeping only to have
+*    it come back means a synthetic id can surface in a user-facing "Import
+*    chain:" message. Resolving it first keeps ownership of the id in one
+*    place.
+* 2. NOT load-bearing: the position relative to `projection()`. Projection is
+*    `enforce: "pre"` and selects by file BASENAME (`projection.ts:242-248`),
+*    so it transforms every `*.page.tsx` / `layout.tsx` / `root.tsx` that
+*    enters the graph regardless of who imported it or where this plugin sits.
+*    The registry emits absolute POSIX specifiers that Rollup resolves and
+*    loads as ORDINARY file modules — they are not inlined into the virtual
+*    module — so each one is transformed exactly as a page imported from a
+*    real file would be. Projection declines the virtual module itself
+*    (`\0virtual:warlock/pages` has no matching basename), which is correct:
+*    generated code has no server exports to strip.
+*
+* Point 2 is asserted, not assumed, by a real `vite.build()` in
+* `page-registry-plugin.spec.ts`: a fixture page whose `loader` — and only its
+* `loader` — imports a marker module that Gate A independently PERMITS, built
+* through this exact array, with the marker proven absent from every emitted
+* chunk while the page's own component text is proven present. Inspecting this
+* array's order would prove nothing about what reaches the browser.
+*/
+function warlockClientBoundary(options = {}) {
+	const tracker = createPublicEnvTracker();
+	return [
+		clientPageRegistry({ appRoot: options.appRoot }),
+		projection(),
+		gateBSecrets({ tracker }),
+		gateAResolve(options),
+		gateCVerify({
+			...options,
+			tracker
+		})
+	].map(clientEnvironmentOnly);
+}
+/**
+* Callable production seam: callers own their exact source aliases and the
+* app-root classification boundary, while this module owns the one canonical
+* projection/Gate B/Gate A/Gate C composition.
+*/
+async function buildWarlockHydrationClient(options) {
+	return buildHydrationClient({
+		webRoot: options.webRoot,
+		outDir: options.outDir,
+		resolveAliases: options.resolveAliases,
+		external: options.external,
+		plugins: warlockClientBoundary({ appRoot: options.appRoot })
+	});
+}
+
+//#endregion
+export { CLIENT_PAGE_REGISTRY_ID, HYDRATION_CLIENT_ENTRY_NAME, ProjectionAmbiguityError, RESOLVED_CLIENT_PAGE_REGISTRY_ID, buildHydrationClient, buildPublicEnvManifest, buildWarlockHydrationClient, clientPageRegistry, createHydrationClientEntry, createPublicEnvTracker, findLeakedServerExports, findLeakedServerImportEdges, gateAResolve, gateBSecrets, gateCVerify, projection, warlockClientBoundary };
+//# sourceMappingURL=index.mjs.map

package/esm/vite/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../web/src/vite/index.ts"],"sourcesContent":["/**\n * `@warlock.js/web/vite` — build-tooling subpath, kept separate from the\n * runtime barrel (`@warlock.js/web`) so importing it never pulls `vite` into\n * a project that doesn't build with Vite.\n */\nimport type { Plugin } from \"vite\";\nimport {\n  buildHydrationClient,\n  type BuildHydrationClientOptions,\n  type BuildHydrationClientResult,\n} from \"./build-client\";\nimport { gateAResolve } from \"./gate-a-resolve\";\nimport { createPublicEnvTracker, gateBSecrets } from \"./gate-b-secrets\";\nimport { gateCVerify } from \"./gate-c-verify\";\nimport { clientPageRegistry } from \"./page-registry-plugin\";\nimport { projection } from \"./projection\";\n\nexport { buildHydrationClient } from \"./build-client\";\nexport type {\n  BuildHydrationClientOptions,\n  BuildHydrationClientResult,\n  HydrationClientBuildOutput,\n} from \"./build-client\";\nexport { gateAResolve } from \"./gate-a-resolve\";\nexport type { EnvironmentClassifier, EnvironmentClassifierOptions, WarlockEnvironment } from \"./gate-a-resolve\";\nexport { createPublicEnvTracker, gateBSecrets } from \"./gate-b-secrets\";\nexport type { PublicEnvTracker } from \"./gate-b-secrets\";\nexport {\n  buildPublicEnvManifest,\n  findLeakedServerExports,\n  findLeakedServerImportEdges,\n  gateCVerify,\n} from \"./gate-c-verify\";\nexport type {\n  GateCOptions,\n  PublicEnvManifestEntry,\n  ServerExportLeak,\n  ServerImportEdgeLeak,\n} from \"./gate-c-verify\";\nexport { HYDRATION_CLIENT_ENTRY_NAME, createHydrationClientEntry } from \"./hydration-entries\";\nexport type { HydrationClientEntry } from \"./hydration-entries\";\nexport {\n  CLIENT_PAGE_REGISTRY_ID,\n  clientPageRegistry,\n  RESOLVED_CLIENT_PAGE_REGISTRY_ID,\n} from \"./page-registry-plugin\";\nexport type { ClientPageRegistryPluginOptions } from \"./page-registry-plugin\";\nexport { projection, ProjectionAmbiguityError } from \"./projection\";\nexport type { ProjectionResult } from \"./projection\";\n\nexport type WarlockClientBoundaryOptions = Parameters<typeof gateAResolve>[0];\n\nexport type BuildWarlockHydrationClientOptions = Readonly<{\n  appRoot: string;\n  webRoot: string;\n  /** Absolute client output dir — threaded to `buildHydrationClient` (`<outdir>/client`). */\n  outDir: string;\n  resolveAliases: BuildHydrationClientOptions[\"resolveAliases\"];\n  external?: BuildHydrationClientOptions[\"external\"];\n}>;\n\nfunction clientEnvironmentOnly(plugin: Plugin): Plugin {\n  return {\n    ...plugin,\n    applyToEnvironment(environment) {\n      return environment.config.consumer === \"client\";\n    },\n  };\n}\n\n/**\n * The composed client-build pipeline: projection\n * strips the 5 server exports first, THEN Gate B's `transform` checks\n * whatever source remains for inline secret reads, THEN Gate A's\n * `resolveId` judges whatever imports remain. Array order here is\n * `[projection(), gateBSecrets(), gateAResolve()]` to match Vite's own\n * pipeline shape (`transform` before `resolveId`), but array order alone\n * does not guarantee this — see the hook-ordering fact below, which is what\n * actually makes the composition correct.\n *\n * Empirically observed fact (via an instrumented real `vite.build()`, not\n * assumed from plugin array order): for a given module M, Vite/Rollup calls\n * `transform(M)` BEFORE it calls `resolveId` for any of M's own import\n * specifiers — because Rollup must parse M's post-transform source to even\n * discover which specifiers to resolve next. Concretely: `transform` ran on\n * `entry.page.tsx` first, and only after that did `resolveId(\"./dep\", ...)`\n * fire for the import statement still present in the transformed code. A\n * consequence follows directly: if projection's `transform` removes an\n * import statement from a page module entirely (e.g. `loader`'s\n * `@warlock.js/core` import, stripped because `loader` itself is removed),\n * `resolveId` is never invoked for that specifier at all — Gate A doesn't\n * \"let it pass\", it never sees it. Gate A's `resolveId` only fires for\n * imports that survive projection's `transform`, which is exactly why a\n * component-level `@warlock.js/core` import (never touched by projection)\n * still reaches and is refused by Gate A.\n *\n * This is OBSERVED Rollup behavior, not a documented contract — a future\n * Vite/Rollup upgrade could invert it. Pinned by a\n * regression test (`index.spec.ts`, \"D.3 hook ordering pin\") that fails\n * loudly if the ordering ever inverts, and by the `vite` peer floor in\n * `web/package.json` (`>=7.3.5`, the version this was verified against). If\n * that test ever fails after a Vite bump: the failure mode of the ordering\n * assumption breaking is SAFE — projection would stop removing an import\n * statement Gate A still sees, so Gate A would refuse an import it used to\n * silently let a stripped server export take with it. That is a loud build\n * failure (\"Gate A refused an import\"), never a silent client-bundle leak.\n * Do NOT \"fix\" an apparent Gate A false-positive after a Vite upgrade by\n * weakening Gate A (e.g. widening what it lets through) — investigate\n * whether this ordering assumption broke instead; loosening Gate A to work\n * around it would turn a loud failure into the exact silent leak this\n * pipeline exists to prevent.\n *\n * Gate B is placed between the two for the same reason, but for a `transform`\n * hook rather than `resolveId`: within a plugin array, Rollup runs each\n * module's registered `transform` hooks in array order, each one receiving\n * the PREVIOUS plugin's output. Running Gate B after projection means it\n * inspects the POST-projection source — a `process.env.SECRET` read inside\n * `loader` (a server export, legitimately reading a real secret server-side)\n * is invisible to Gate B once projection has already removed `loader`\n * entirely, exactly as it should be: Gate B's job is to fence client-bound\n * code, and projection is what decides what counts as client-bound. A\n * component-level secret read is untouched by projection and still reaches\n * Gate B, which refuses it. Gate B does not depend on Gate A's `resolveId`\n * output at all (orthogonal concern, raw source vs. import paths), so its\n * position relative to Gate A is not load-bearing — it is placed before Gate\n * A only to keep both `transform` hooks adjacent in the array.\n *\n * Gate C (`gate-c-verify.ts`) runs last and only at `generateBundle` — after\n * the entire `transform`/`resolveId` build phase has completed for every\n * plugin, regardless of array position (a Rollup lifecycle fact, not\n * something this array order enforces). It verifies the EMITTED output the\n * other three produced: no server export survived as a top-level binding, no\n * import edge into a server-only package survived into the module graph, and\n * it emits the reviewable `PUBLIC_*` inlined-value manifest. `gateBSecrets` and `gateCVerify` share\n * one `PublicEnvTracker` instance so the manifest and Gate B's own unread-key\n * exclusion check agree by construction, not by coincidence.\n *\n * `clientPageRegistry()` is FIRST, ahead of projection. It contributes no\n * `transform` at all — only a `resolveId`/`load` pair for one synthetic id —\n * so it cannot displace or pre-empt any gate's inspection of any real file.\n * Two reasons for the position, one of which is not load-bearing and is\n * labelled as such:\n *\n * 1. Load-bearing: it must own `virtual:warlock/pages` before Gate A's\n *    `resolveId` (also `enforce: \"pre\"`) reaches its `this.resolve(...)` call\n *    for that specifier. Gate A's nested resolve would find it anyway, but\n *    routing the id through Gate A's importer-chain bookkeeping only to have\n *    it come back means a synthetic id can surface in a user-facing \"Import\n *    chain:\" message. Resolving it first keeps ownership of the id in one\n *    place.\n * 2. NOT load-bearing: the position relative to `projection()`. Projection is\n *    `enforce: \"pre\"` and selects by file BASENAME (`projection.ts:242-248`),\n *    so it transforms every `*.page.tsx` / `layout.tsx` / `root.tsx` that\n *    enters the graph regardless of who imported it or where this plugin sits.\n *    The registry emits absolute POSIX specifiers that Rollup resolves and\n *    loads as ORDINARY file modules — they are not inlined into the virtual\n *    module — so each one is transformed exactly as a page imported from a\n *    real file would be. Projection declines the virtual module itself\n *    (`\\0virtual:warlock/pages` has no matching basename), which is correct:\n *    generated code has no server exports to strip.\n *\n * Point 2 is asserted, not assumed, by a real `vite.build()` in\n * `page-registry-plugin.spec.ts`: a fixture page whose `loader` — and only its\n * `loader` — imports a marker module that Gate A independently PERMITS, built\n * through this exact array, with the marker proven absent from every emitted\n * chunk while the page's own component text is proven present. Inspecting this\n * array's order would prove nothing about what reaches the browser.\n */\nexport function warlockClientBoundary(options: Parameters<typeof gateAResolve>[0] = {}): Plugin[] {\n  const tracker = createPublicEnvTracker();\n  return [\n    clientPageRegistry({ appRoot: options.appRoot }),\n    projection(),\n    gateBSecrets({ tracker }),\n    gateAResolve(options),\n    gateCVerify({ ...options, tracker }),\n  ].map(clientEnvironmentOnly);\n}\n\n/**\n * Callable production seam: callers own their exact source aliases and the\n * app-root classification boundary, while this module owns the one canonical\n * projection/Gate B/Gate A/Gate C composition.\n */\nexport async function buildWarlockHydrationClient(\n  options: BuildWarlockHydrationClientOptions,\n): Promise<BuildHydrationClientResult> {\n  return buildHydrationClient({\n    webRoot: options.webRoot,\n    outDir: options.outDir,\n    resolveAliases: options.resolveAliases,\n    external: options.external,\n    plugins: warlockClientBoundary({ appRoot: options.appRoot }),\n  });\n}\n"],"mappings":";;;;;;;;;AA6DA,SAAS,sBAAsB,QAAwB;CACrD,OAAO;EACL,GAAG;EACH,mBAAmB,aAAa;GAC9B,OAAO,YAAY,OAAO,aAAa;EACzC;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoGA,SAAgB,sBAAsB,UAA8C,CAAC,GAAa;CAChG,MAAM,UAAU,uBAAuB;CACvC,OAAO;EACL,mBAAmB,EAAE,SAAS,QAAQ,QAAQ,CAAC;EAC/C,WAAW;EACX,aAAa,EAAE,QAAQ,CAAC;EACxB,aAAa,OAAO;EACpB,YAAY;GAAE,GAAG;GAAS;EAAQ,CAAC;CACrC,CAAC,CAAC,IAAI,qBAAqB;AAC7B;;;;;;AAOA,eAAsB,4BACpB,SACqC;CACrC,OAAO,qBAAqB;EAC1B,SAAS,QAAQ;EACjB,QAAQ,QAAQ;EAChB,gBAAgB,QAAQ;EACxB,UAAU,QAAQ;EAClB,SAAS,sBAAsB,EAAE,SAAS,QAAQ,QAAQ,CAAC;CAC7D,CAAC;AACH"}

package/esm/vite/page-registry-plugin.d.mts

@@ -0,0 +1,43 @@
+import { Plugin } from "vite";
+
+//#region ../web/src/vite/page-registry-plugin.d.ts
+/**
+ * The specifier application code writes.
+ *
+ * Exported so the client runtime imports this constant instead of retyping the
+ * string: a constant two sides must agree on is a guard, and a guard duplicated
+ * at a second site fails open at the third — a typo'd re-spelling doesn't fail
+ * loudly, it resolves to "no such module" or, worse, to a stale real file.
+ */
+declare const CLIENT_PAGE_REGISTRY_ID = "virtual:warlock/pages";
+/**
+ * The resolved id, `\0`-prefixed per Vite/Rollup convention so no other plugin
+ * (and no filesystem watcher) mistakes it for a real path.
+ */
+declare const RESOLVED_CLIENT_PAGE_REGISTRY_ID = "\0virtual:warlock/pages";
+type ClientPageRegistryPluginOptions = {
+  /** Absolute path to the application root. Defaults to `process.cwd()`, matching Vite's own default `root` and Gate A's `appRoot` default. */appRoot?: string; /** Source directory name under `appRoot`; forwarded verbatim to `discoverPages`, which defaults it to `"src"`. */
+  srcDir?: string;
+};
+/**
+ * Serves the client page registry at {@link CLIENT_PAGE_REGISTRY_ID}.
+ *
+ * Discovery runs INSIDE `load`, once per `load` call, and its result is NOT
+ * cached across builds — the plugin holds no state at all. A registry cached
+ * past the moment a page file appears is a page that silently 404s until
+ * someone restarts the dev server, which is a far more expensive bug than
+ * re-walking a source tree. Rollup calls `load` once per module per build, and
+ * in dev Vite's module graph caches the transformed result until the module is
+ * invalidated, so the walk is not per-request either way. (Invalidating that
+ * dev-server cache when a page file is ADDED needs a `handleHotUpdate`/watcher
+ * hook that belongs with the dev provider slice — see the followup.)
+ *
+ * `enforce: "pre"` and placed FIRST in `warlockClientBoundary`'s array — see
+ * that function's comment in `index.ts` for why position is what it is, and
+ * `page-registry-plugin.spec.ts` for the real-build proof that the pages this
+ * module names still reach `projection()`.
+ */
+declare function clientPageRegistry(options?: ClientPageRegistryPluginOptions): Plugin;
+//#endregion
+export { CLIENT_PAGE_REGISTRY_ID, ClientPageRegistryPluginOptions, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry };
+//# sourceMappingURL=page-registry-plugin.d.mts.map

package/esm/vite/page-registry-plugin.mjs

@@ -0,0 +1,138 @@
+import { discoverPages, toPosix } from "../build/discover-pages.mjs";
+import { generateClientRegistry } from "../build/generate-client-registry.mjs";
+import path from "node:path";
+import { parse } from "@babel/parser";
+import MagicString from "magic-string";
+
+//#region ../web/src/vite/page-registry-plugin.ts
+/**
+* The wire between the two halves that already existed and never met:
+* `discoverPages` (the page graph, read off disk) and `generateClientRegistry`
+* (the module SOURCE that carries that graph into the browser). Neither one
+* touches Vite; this plugin is the only place they are joined, and it joins
+* them as a VIRTUAL module so nothing is ever written to the user's tree.
+*
+* Identical in dev and build — no `apply`/`command` gating, matching the rest
+* of `warlockClientBoundary`'s composition (`index.ts`), which is also
+* mode-agnostic. A registry that differed between `vite dev` and `vite build`
+* would make every dev-only or prod-only page bug unreproducible in the other
+* mode.
+*/
+/**
+* The specifier application code writes.
+*
+* Exported so the client runtime imports this constant instead of retyping the
+* string: a constant two sides must agree on is a guard, and a guard duplicated
+* at a second site fails open at the third — a typo'd re-spelling doesn't fail
+* loudly, it resolves to "no such module" or, worse, to a stale real file.
+*/
+const CLIENT_PAGE_REGISTRY_ID = "virtual:warlock/pages";
+/**
+* The resolved id, `\0`-prefixed per Vite/Rollup convention so no other plugin
+* (and no filesystem watcher) mistakes it for a real path.
+*/
+const RESOLVED_CLIENT_PAGE_REGISTRY_ID = `\0${CLIENT_PAGE_REGISTRY_ID}`;
+/**
+* The import specifiers the emitted registry names must be ABSOLUTE POSIX file
+* paths, never relative ones.
+*
+* A relative specifier resolves against its IMPORTER, and the importer here is
+* `\0virtual:warlock/pages` — a synthetic id whose `dirname` is not a real
+* directory. `./blog.page.tsx` from that importer resolves to nonsense that
+* fails at bundle time with a path no user authored and no user can act on.
+*
+* Separator normalization is `hydration-entries.ts`'s
+* (`hydration-entries.ts:12-14`) and `discover-pages.ts`'s single
+* `.replace(/\\/g, "/")` rule, reused via the already-exported `toPosix` rather
+* than spelled a third time — keeping the drive colon (`D:/...`) is exactly
+* what Vite's resolver wants on Windows.
+*/
+function toImportSpecifier(absoluteFilePath) {
+	return toPosix(path.resolve(absoluteFilePath));
+}
+/**
+* Erases the generated module's TypeScript down to plain JavaScript.
+*
+* NOT optional, and not a style choice. Vite's `vite:esbuild` transform is
+* gated behind `createFilter`, which refuses ANY id containing a NUL byte
+* (`node_modules/vite/dist/node/chunks/config.js:1512` — `if
+* (id.includes("\0")) return false`). So the one module in this build that is
+* `\0`-prefixed by convention is precisely the one module esbuild will never
+* transform, while `generateClientRegistry` always emits TypeScript (a
+* type-only `ClientPageEntry` import plus the array's type annotation). Handed
+* to Rollup verbatim, `import type { ClientPageEntry } from ...` is a
+* JavaScript syntax error.
+*
+* Done with the AST rather than a regex, using the same `@babel/parser` +
+* `MagicString` pair `projection.ts` already uses in this directory — a regex
+* over generated source is a second grammar that drifts from the generator's
+* silently. If the generator ever emits a TS construct outside these two
+* shapes, the result is a Rollup parse error naming the virtual module: loud,
+* not silent. `page-registry-plugin.spec.ts` pins that the erased output
+* re-parses as plain JavaScript with the TypeScript plugin switched OFF.
+*/
+function eraseTypes(source) {
+	const ast = parse(source, {
+		sourceType: "module",
+		plugins: ["typescript"]
+	});
+	const magic = new MagicString(source);
+	for (const statement of ast.program.body) {
+		if (statement.type === "ImportDeclaration" && statement.importKind === "type") {
+			let end = statement.end;
+			if (source[end] === "\r" && source[end + 1] === "\n") end += 2;
+			else if (source[end] === "\n") end += 1;
+			magic.remove(statement.start, end);
+			continue;
+		}
+		const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations) {
+			const annotation = declarator.id?.typeAnnotation;
+			if (annotation) magic.remove(annotation.start, annotation.end);
+		}
+	}
+	return magic.toString();
+}
+/**
+* Serves the client page registry at {@link CLIENT_PAGE_REGISTRY_ID}.
+*
+* Discovery runs INSIDE `load`, once per `load` call, and its result is NOT
+* cached across builds — the plugin holds no state at all. A registry cached
+* past the moment a page file appears is a page that silently 404s until
+* someone restarts the dev server, which is a far more expensive bug than
+* re-walking a source tree. Rollup calls `load` once per module per build, and
+* in dev Vite's module graph caches the transformed result until the module is
+* invalidated, so the walk is not per-request either way. (Invalidating that
+* dev-server cache when a page file is ADDED needs a `handleHotUpdate`/watcher
+* hook that belongs with the dev provider slice — see the followup.)
+*
+* `enforce: "pre"` and placed FIRST in `warlockClientBoundary`'s array — see
+* that function's comment in `index.ts` for why position is what it is, and
+* `page-registry-plugin.spec.ts` for the real-build proof that the pages this
+* module names still reach `projection()`.
+*/
+function clientPageRegistry(options = {}) {
+	const appRoot = path.resolve(options.appRoot ?? process.cwd());
+	return {
+		name: "warlock:client-page-registry",
+		enforce: "pre",
+		resolveId(source) {
+			if (source === "virtual:warlock/pages") return RESOLVED_CLIENT_PAGE_REGISTRY_ID;
+		},
+		load(id) {
+			if (id !== RESOLVED_CLIENT_PAGE_REGISTRY_ID) return void 0;
+			return eraseTypes(generateClientRegistry({
+				pages: discoverPages({
+					appRoot,
+					srcDir: options.srcDir
+				}),
+				toImportSpecifier
+			}));
+		}
+	};
+}
+
+//#endregion
+export { CLIENT_PAGE_REGISTRY_ID, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry };
+//# sourceMappingURL=page-registry-plugin.mjs.map

package/esm/vite/page-registry-plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-registry-plugin.mjs","names":[],"sources":["../../../../../../../web/src/vite/page-registry-plugin.ts"],"sourcesContent":["/**\n * The wire between the two halves that already existed and never met:\n * `discoverPages` (the page graph, read off disk) and `generateClientRegistry`\n * (the module SOURCE that carries that graph into the browser). Neither one\n * touches Vite; this plugin is the only place they are joined, and it joins\n * them as a VIRTUAL module so nothing is ever written to the user's tree.\n *\n * Identical in dev and build — no `apply`/`command` gating, matching the rest\n * of `warlockClientBoundary`'s composition (`index.ts`), which is also\n * mode-agnostic. A registry that differed between `vite dev` and `vite build`\n * would make every dev-only or prod-only page bug unreproducible in the other\n * mode.\n */\nimport { parse } from \"@babel/parser\";\nimport MagicString from \"magic-string\";\nimport path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { discoverPages, toPosix } from \"../build/discover-pages\";\nimport { generateClientRegistry } from \"../build/generate-client-registry\";\n\n/**\n * The specifier application code writes.\n *\n * Exported so the client runtime imports this constant instead of retyping the\n * string: a constant two sides must agree on is a guard, and a guard duplicated\n * at a second site fails open at the third — a typo'd re-spelling doesn't fail\n * loudly, it resolves to \"no such module\" or, worse, to a stale real file.\n */\nexport const CLIENT_PAGE_REGISTRY_ID = \"virtual:warlock/pages\";\n\n/**\n * The resolved id, `\\0`-prefixed per Vite/Rollup convention so no other plugin\n * (and no filesystem watcher) mistakes it for a real path.\n */\nexport const RESOLVED_CLIENT_PAGE_REGISTRY_ID = `\\0${CLIENT_PAGE_REGISTRY_ID}`;\n\nexport type ClientPageRegistryPluginOptions = {\n  /** Absolute path to the application root. Defaults to `process.cwd()`, matching Vite's own default `root` and Gate A's `appRoot` default. */\n  appRoot?: string;\n  /** Source directory name under `appRoot`; forwarded verbatim to `discoverPages`, which defaults it to `\"src\"`. */\n  srcDir?: string;\n};\n\n/**\n * The import specifiers the emitted registry names must be ABSOLUTE POSIX file\n * paths, never relative ones.\n *\n * A relative specifier resolves against its IMPORTER, and the importer here is\n * `\\0virtual:warlock/pages` — a synthetic id whose `dirname` is not a real\n * directory. `./blog.page.tsx` from that importer resolves to nonsense that\n * fails at bundle time with a path no user authored and no user can act on.\n *\n * Separator normalization is `hydration-entries.ts`'s\n * (`hydration-entries.ts:12-14`) and `discover-pages.ts`'s single\n * `.replace(/\\\\/g, \"/\")` rule, reused via the already-exported `toPosix` rather\n * than spelled a third time — keeping the drive colon (`D:/...`) is exactly\n * what Vite's resolver wants on Windows.\n */\nfunction toImportSpecifier(absoluteFilePath: string): string {\n  return toPosix(path.resolve(absoluteFilePath));\n}\n\n/**\n * Erases the generated module's TypeScript down to plain JavaScript.\n *\n * NOT optional, and not a style choice. Vite's `vite:esbuild` transform is\n * gated behind `createFilter`, which refuses ANY id containing a NUL byte\n * (`node_modules/vite/dist/node/chunks/config.js:1512` — `if\n * (id.includes(\"\\0\")) return false`). So the one module in this build that is\n * `\\0`-prefixed by convention is precisely the one module esbuild will never\n * transform, while `generateClientRegistry` always emits TypeScript (a\n * type-only `ClientPageEntry` import plus the array's type annotation). Handed\n * to Rollup verbatim, `import type { ClientPageEntry } from ...` is a\n * JavaScript syntax error.\n *\n * Done with the AST rather than a regex, using the same `@babel/parser` +\n * `MagicString` pair `projection.ts` already uses in this directory — a regex\n * over generated source is a second grammar that drifts from the generator's\n * silently. If the generator ever emits a TS construct outside these two\n * shapes, the result is a Rollup parse error naming the virtual module: loud,\n * not silent. `page-registry-plugin.spec.ts` pins that the erased output\n * re-parses as plain JavaScript with the TypeScript plugin switched OFF.\n */\nfunction eraseTypes(source: string): string {\n  const ast = parse(source, { sourceType: \"module\", plugins: [\"typescript\"] });\n  const magic = new MagicString(source);\n\n  for (const statement of ast.program.body as any[]) {\n    if (statement.type === \"ImportDeclaration\" && statement.importKind === \"type\") {\n      let end = statement.end as number;\n      if (source[end] === \"\\r\" && source[end + 1] === \"\\n\") end += 2;\n      else if (source[end] === \"\\n\") end += 1;\n      magic.remove(statement.start as number, end);\n      continue;\n    }\n\n    const declaration =\n      statement.type === \"ExportNamedDeclaration\" ? statement.declaration : statement;\n\n    if (declaration?.type !== \"VariableDeclaration\") continue;\n\n    for (const declarator of declaration.declarations as any[]) {\n      const annotation = declarator.id?.typeAnnotation;\n      if (annotation) magic.remove(annotation.start as number, annotation.end as number);\n    }\n  }\n\n  return magic.toString();\n}\n\n/**\n * Serves the client page registry at {@link CLIENT_PAGE_REGISTRY_ID}.\n *\n * Discovery runs INSIDE `load`, once per `load` call, and its result is NOT\n * cached across builds — the plugin holds no state at all. A registry cached\n * past the moment a page file appears is a page that silently 404s until\n * someone restarts the dev server, which is a far more expensive bug than\n * re-walking a source tree. Rollup calls `load` once per module per build, and\n * in dev Vite's module graph caches the transformed result until the module is\n * invalidated, so the walk is not per-request either way. (Invalidating that\n * dev-server cache when a page file is ADDED needs a `handleHotUpdate`/watcher\n * hook that belongs with the dev provider slice — see the followup.)\n *\n * `enforce: \"pre\"` and placed FIRST in `warlockClientBoundary`'s array — see\n * that function's comment in `index.ts` for why position is what it is, and\n * `page-registry-plugin.spec.ts` for the real-build proof that the pages this\n * module names still reach `projection()`.\n */\nexport function clientPageRegistry(options: ClientPageRegistryPluginOptions = {}): Plugin {\n  const appRoot = path.resolve(options.appRoot ?? process.cwd());\n\n  return {\n    name: \"warlock:client-page-registry\",\n    enforce: \"pre\",\n    resolveId(source) {\n      if (source === CLIENT_PAGE_REGISTRY_ID) return RESOLVED_CLIENT_PAGE_REGISTRY_ID;\n      return undefined;\n    },\n    load(id) {\n      if (id !== RESOLVED_CLIENT_PAGE_REGISTRY_ID) return undefined;\n\n      const pages = discoverPages({ appRoot, srcDir: options.srcDir });\n\n      return eraseTypes(generateClientRegistry({ pages, toImportSpecifier }));\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,0BAA0B;;;;;AAMvC,MAAa,mCAAmC,KAAK;;;;;;;;;;;;;;;;AAwBrD,SAAS,kBAAkB,kBAAkC;CAC3D,OAAO,QAAQ,KAAK,QAAQ,gBAAgB,CAAC;AAC/C;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAS,WAAW,QAAwB;CAC1C,MAAM,MAAM,MAAM,QAAQ;EAAE,YAAY;EAAU,SAAS,CAAC,YAAY;CAAE,CAAC;CAC3E,MAAM,QAAQ,IAAI,YAAY,MAAM;CAEpC,KAAK,MAAM,aAAa,IAAI,QAAQ,MAAe;EACjD,IAAI,UAAU,SAAS,uBAAuB,UAAU,eAAe,QAAQ;GAC7E,IAAI,MAAM,UAAU;GACpB,IAAI,OAAO,SAAS,QAAQ,OAAO,MAAM,OAAO,MAAM,OAAO;QACxD,IAAI,OAAO,SAAS,MAAM,OAAO;GACtC,MAAM,OAAO,UAAU,OAAiB,GAAG;GAC3C;EACF;EAEA,MAAM,cACJ,UAAU,SAAS,2BAA2B,UAAU,cAAc;EAExE,IAAI,aAAa,SAAS,uBAAuB;EAEjD,KAAK,MAAM,cAAc,YAAY,cAAuB;GAC1D,MAAM,aAAa,WAAW,IAAI;GAClC,IAAI,YAAY,MAAM,OAAO,WAAW,OAAiB,WAAW,GAAa;EACnF;CACF;CAEA,OAAO,MAAM,SAAS;AACxB;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,mBAAmB,UAA2C,CAAC,GAAW;CACxF,MAAM,UAAU,KAAK,QAAQ,QAAQ,WAAW,QAAQ,IAAI,CAAC;CAE7D,OAAO;EACL,MAAM;EACN,SAAS;EACT,UAAU,QAAQ;GAChB,IAAI,oCAAoC,OAAO;EAEjD;EACA,KAAK,IAAI;GACP,IAAI,OAAO,kCAAkC,OAAO;GAIpD,OAAO,WAAW,uBAAuB;IAAE,OAF7B,cAAc;KAAE;KAAS,QAAQ,QAAQ;IAAO,CAEf;IAAG;GAAkB,CAAC,CAAC;EACxE;CACF;AACF"}

package/esm/vite/projection.d.mts

@@ -0,0 +1,31 @@
+import MagicString from "magic-string";
+import { Plugin } from "vite";
+
+//#region ../web/src/vite/projection.d.ts
+/**
+ * Thrown when projection encounters an attribution-ambiguous top-level
+ * statement (`c604f0bc` §3: "the compiler must not guess"). Carries the
+ * file/statement/fix fields the plugin's `transform` hook formats into the
+ * build-failure message — never silently kept or silently dropped.
+ */
+declare class ProjectionAmbiguityError extends Error {
+  readonly file: string;
+  readonly statement: string;
+  readonly line: number;
+  readonly explanation: string;
+  readonly fix: string;
+  constructor(file: string, statement: string, line: number, explanation: string, fix: string);
+}
+interface ProjectionResult {
+  code: string;
+  map: ReturnType<MagicString["generateMap"]>;
+}
+/**
+ * The client-build Vite plugin. Scoped to `*.page.tsx`/`layout.tsx`/`root.tsx`
+ * and skipped entirely for the SSR build (`options.ssr`) — the server still
+ * needs `route`/`middleware`/`validation`/`loader`/`metadata` intact.
+ */
+declare function projection(): Plugin;
+//#endregion
+export { ProjectionAmbiguityError, ProjectionResult, projection };
+//# sourceMappingURL=projection.d.mts.map