@warlock.js/web 5.0.2 → 5.2.0

package/esm/vite/index.mjs

@@ -1,18 +1,123 @@
 import { HYDRATION_CLIENT_ENTRY_NAME, createHydrationClientEntry } from "./hydration-entries.mjs";
 import { buildHydrationClient } from "./build-client.mjs";
-import { gateAResolve } from "./gate-a-resolve.mjs";
+import { gateAResolve, isAppSourcePath, isRecognizedUniversalSurface, isServerFile, isWithinModuleWebFolder } from "./gate-a-resolve.mjs";
 import { createPublicEnvTracker, gateBSecrets } from "./gate-b-secrets.mjs";
-import { ProjectionAmbiguityError, projection } from "./projection.mjs";
+import { ProjectionAmbiguityError, isProjectableFile, projectModule, 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";
+import { CLIENT_PAGE_REGISTRY_ID, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry, invalidateClientPageRegistry } from "./page-registry-plugin.mjs";
+import path from "node:path";
+import { parse } from "@babel/parser";
 
-//#region ../web/src/vite/index.ts
-function clientEnvironmentOnly(plugin) {
+//#region web/src/vite/index.ts
+/**
+* `@warlock.js/web/vite` — build-tooling subpath, kept separate from the
+* runtime barrel (`@warlock.js/web`) so importing it never pulls `vite` into
+* a project that doesn't build with Vite.
+*/
+function moduleKey(id) {
+	return id.split("?")[0].replace(/\\/g, "/");
+}
+const CODE_MODULE_EXTENSION = /\.([cm]?[jt]sx?)$/;
+function isStatelessClientSurface(id, appRoot) {
+	const bare = moduleKey(id);
+	if (!isAppSourcePath(bare, appRoot)) return false;
+	if (isServerFile(bare, appRoot)) return false;
+	return isProjectableFile(bare) || isRecognizedUniversalSurface(bare) || isWithinModuleWebFolder(bare, appRoot);
+}
+function collectImportSpecifiers(code) {
+	const ast = parse(code, {
+		sourceType: "module",
+		plugins: ["typescript", "jsx"]
+	});
+	const imports = /* @__PURE__ */ new Set();
+	function walk(node) {
+		if (!node || typeof node !== "object") return;
+		if (Array.isArray(node)) {
+			for (const child of node) walk(child);
+			return;
+		}
+		const record = node;
+		if ((record.type === "ImportDeclaration" || record.type === "ExportNamedDeclaration" || record.type === "ExportAllDeclaration") && record.source?.type === "StringLiteral") imports.add(record.source.value);
+		if (record.type === "CallExpression" && record.callee?.type === "Import" && record.arguments?.[0]?.type === "StringLiteral") imports.add(record.arguments[0].value);
+		if (record.type === "ImportExpression" && record.source?.type === "StringLiteral") imports.add(record.source.value);
+		for (const [key, child] of Object.entries(record)) {
+			if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range" || key.endsWith("Comments") || key === "extra") continue;
+			walk(child);
+		}
+	}
+	walk(ast.program);
+	return imports;
+}
+function clientViewOf(state, code, id) {
+	const key = moduleKey(id);
+	if (!state.clientBoundModules.has(key) && !isStatelessClientSurface(key, state.appRoot)) return;
+	state.clientBoundModules.add(key);
+	if (!CODE_MODULE_EXTENSION.test(key)) {
+		state.clientImportsByModule.set(key, /* @__PURE__ */ new Set());
+		return code;
+	}
+	const clientCode = isProjectableFile(key) ? projectModule(code, key).code : code;
+	state.clientImportsByModule.set(key, collectImportSpecifiers(clientCode));
+	return clientCode;
+}
+function markResolvedClientModule(state, resolved) {
+	if (!resolved) return;
+	const id = typeof resolved === "string" ? resolved : resolved.id;
+	if (!id.includes("\0")) state.clientBoundModules.add(moduleKey(id));
+}
+function isServerEnvironment(context) {
+	return context.environment?.config.consumer === "server";
+}
+/**
+* Keeps the production/client pipeline byte-identical, while giving Gate A
+* and Gate B a validation-only view in Vite's development SSR environment.
+* SSR still evaluates the original source: only the gates receive the
+* projected client view, so loader/server exports retain their legitimate
+* server access while component-visible code is refused before evaluation.
+*/
+function clientEnvironmentOnly(plugin, ssrState) {
+	const validatesDevSsr = plugin.name === "warlock:gate-a-resolve" || plugin.name === "warlock:gate-b-secrets";
+	const originalTransform = typeof plugin.transform === "function" ? plugin.transform : plugin.transform?.handler;
+	const originalResolveId = typeof plugin.resolveId === "function" ? plugin.resolveId : plugin.resolveId?.handler;
+	const originalBuildStart = typeof plugin.buildStart === "function" ? plugin.buildStart : plugin.buildStart?.handler;
 	return {
 		...plugin,
 		applyToEnvironment(environment) {
-			return environment.config.consumer === "client";
-		}
+			return environment.config.consumer === "client" || validatesDevSsr && environment.config.consumer === "server";
+		},
+		buildStart: originalBuildStart ? function(...args) {
+			if (isServerEnvironment(this)) return;
+			return originalBuildStart.apply(this, args);
+		} : void 0,
+		transform: originalTransform ? async function(code, id, options) {
+			if (!isServerEnvironment(this)) return originalTransform.call(this, code, id, options);
+			const clientCode = clientViewOf(ssrState, code, id);
+			if (clientCode === void 0) return null;
+			const transformed = await originalTransform.call(this, clientCode, id, {
+				...options,
+				ssr: false
+			});
+			if (plugin.name === "warlock:gate-a-resolve" && originalResolveId) for (const source of ssrState.clientImportsByModule.get(moduleKey(id)) ?? []) markResolvedClientModule(ssrState, await originalResolveId.call(this, source, id, {
+				attributes: {},
+				isEntry: false,
+				ssr: false
+			}));
+			return transformed;
+		} : void 0,
+		resolveId: originalResolveId ? async function(source, importer, options) {
+			if (!isServerEnvironment(this)) return originalResolveId.call(this, source, importer, options);
+			if (!importer) return null;
+			const importerKey = moduleKey(importer);
+			if (!(ssrState.clientBoundModules.has(importerKey) || isStatelessClientSurface(importerKey, ssrState.appRoot))) return null;
+			const survivingImports = ssrState.clientImportsByModule.get(importerKey);
+			if (survivingImports && !survivingImports.has(source)) return null;
+			const resolved = await originalResolveId.call(this, source, importer, {
+				...options,
+				ssr: false
+			});
+			markResolvedClientModule(ssrState, resolved);
+			return resolved;
+		} : void 0
 	};
 }
 /**
@@ -115,8 +220,16 @@ function clientEnvironmentOnly(plugin) {
 */
 function warlockClientBoundary(options = {}) {
 	const tracker = createPublicEnvTracker();
+	const ssrState = {
+		appRoot: path.resolve(options.appRoot ?? process.cwd()),
+		clientBoundModules: /* @__PURE__ */ new Set(),
+		clientImportsByModule: /* @__PURE__ */ new Map()
+	};
 	return [
-		clientPageRegistry({ appRoot: options.appRoot }),
+		clientPageRegistry({
+			appRoot: options.appRoot,
+			beforePageHotUpdate: options.beforePageHotUpdate
+		}),
 		projection(),
 		gateBSecrets({ tracker }),
 		gateAResolve(options),
@@ -124,7 +237,7 @@ function warlockClientBoundary(options = {}) {
 			...options,
 			tracker
 		})
-	].map(clientEnvironmentOnly);
+	].map((plugin) => clientEnvironmentOnly(plugin, ssrState));
 }
 /**
 * Callable production seam: callers own their exact source aliases and the
@@ -137,10 +250,10 @@ async function buildWarlockHydrationClient(options) {
 		outDir: options.outDir,
 		resolveAliases: options.resolveAliases,
 		external: options.external,
-		plugins: warlockClientBoundary({ appRoot: options.appRoot })
+		plugins: [...warlockClientBoundary({ appRoot: options.appRoot }), ...options.plugins ?? []]
 	});
 }
 
 //#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 };
+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, invalidateClientPageRegistry, projection, warlockClientBoundary };
 //# sourceMappingURL=index.mjs.map

package/esm/vite/index.mjs.map

@@ -1 +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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["C:/Work/Warlock.js/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 { parse } from \"@babel/parser\";\nimport path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport {\n  buildHydrationClient,\n  type BuildHydrationClientOptions,\n  type BuildHydrationClientResult,\n} from \"./build-client\";\nimport {\n  gateAResolve,\n  isAppSourcePath,\n  isRecognizedUniversalSurface,\n  isServerFile,\n  isWithinModuleWebFolder,\n} from \"./gate-a-resolve\";\nimport { createPublicEnvTracker, gateBSecrets } from \"./gate-b-secrets\";\nimport { gateCVerify } from \"./gate-c-verify\";\nimport {\n  clientPageRegistry,\n  type ClientPageRegistryPluginOptions,\n} from \"./page-registry-plugin\";\nimport { isProjectableFile, projectModule, 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 {\n  EnvironmentClassifier,\n  EnvironmentClassifierOptions,\n  WarlockEnvironment,\n} 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 {\n  HYDRATION_CLIENT_ENTRY_NAME,\n  createHydrationClientEntry,\n} from \"./hydration-entries\";\nexport type { HydrationClientEntry } from \"./hydration-entries\";\nexport {\n  CLIENT_PAGE_REGISTRY_ID,\n  clientPageRegistry,\n  invalidateClientPageRegistry,\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<\n  typeof gateAResolve\n>[0] & {\n  beforePageHotUpdate?: ClientPageRegistryPluginOptions[\"beforePageHotUpdate\"];\n};\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  /** App-configured plugins, appended after Warlock's client-boundary pipeline. */\n  plugins?: BuildHydrationClientOptions[\"plugins\"];\n}>;\n\ntype SsrBoundaryState = {\n  readonly appRoot: string;\n  readonly clientBoundModules: Set<string>;\n  readonly clientImportsByModule: Map<string, Set<string>>;\n};\n\nfunction moduleKey(id: string): string {\n  return id.split(\"?\")[0].replace(/\\\\/g, \"/\");\n}\n\nconst CODE_MODULE_EXTENSION = /\\.([cm]?[jt]sx?)$/;\n\nfunction isStatelessClientSurface(id: string, appRoot: string): boolean {\n  const bare = moduleKey(id);\n  if (!isAppSourcePath(bare, appRoot)) return false;\n  if (isServerFile(bare, appRoot)) return false;\n\n  return (\n    isProjectableFile(bare) ||\n    isRecognizedUniversalSurface(bare) ||\n    isWithinModuleWebFolder(bare, appRoot)\n  );\n}\n\nfunction collectImportSpecifiers(code: string): Set<string> {\n  const ast = parse(code, {\n    sourceType: \"module\",\n    plugins: [\"typescript\", \"jsx\"],\n  });\n  const imports = new Set<string>();\n\n  function walk(node: unknown): void {\n    if (!node || typeof node !== \"object\") return;\n    if (Array.isArray(node)) {\n      for (const child of node) walk(child);\n      return;\n    }\n\n    const record = node as Record<string, any>;\n    if (\n      (record.type === \"ImportDeclaration\" ||\n        record.type === \"ExportNamedDeclaration\" ||\n        record.type === \"ExportAllDeclaration\") &&\n      record.source?.type === \"StringLiteral\"\n    ) {\n      imports.add(record.source.value);\n    }\n    if (\n      record.type === \"CallExpression\" &&\n      record.callee?.type === \"Import\" &&\n      record.arguments?.[0]?.type === \"StringLiteral\"\n    ) {\n      imports.add(record.arguments[0].value);\n    }\n    if (\n      record.type === \"ImportExpression\" &&\n      record.source?.type === \"StringLiteral\"\n    ) {\n      imports.add(record.source.value);\n    }\n\n    for (const [key, child] of Object.entries(record)) {\n      if (\n        key === \"type\" ||\n        key === \"start\" ||\n        key === \"end\" ||\n        key === \"loc\" ||\n        key === \"range\" ||\n        key.endsWith(\"Comments\") ||\n        key === \"extra\"\n      ) {\n        continue;\n      }\n      walk(child);\n    }\n  }\n\n  walk(ast.program);\n  return imports;\n}\n\nfunction clientViewOf(\n  state: SsrBoundaryState,\n  code: string,\n  id: string,\n): string | undefined {\n  const key = moduleKey(id);\n  if (\n    !state.clientBoundModules.has(key) &&\n    !isStatelessClientSurface(key, state.appRoot)\n  ) {\n    return undefined;\n  }\n\n  state.clientBoundModules.add(key);\n  if (!CODE_MODULE_EXTENSION.test(key)) {\n    state.clientImportsByModule.set(key, new Set());\n    return code;\n  }\n\n  const clientCode = isProjectableFile(key)\n    ? projectModule(code, key).code\n    : code;\n  state.clientImportsByModule.set(key, collectImportSpecifiers(clientCode));\n  return clientCode;\n}\n\nfunction markResolvedClientModule(\n  state: SsrBoundaryState,\n  resolved: { id: string } | string | null | false | void,\n): void {\n  if (!resolved) return;\n  const id = typeof resolved === \"string\" ? resolved : resolved.id;\n  if (!id.includes(\"\\0\")) state.clientBoundModules.add(moduleKey(id));\n}\n\nfunction isServerEnvironment(context: {\n  environment?: { config: { consumer?: string } };\n}): boolean {\n  return context.environment?.config.consumer === \"server\";\n}\n\n/**\n * Keeps the production/client pipeline byte-identical, while giving Gate A\n * and Gate B a validation-only view in Vite's development SSR environment.\n * SSR still evaluates the original source: only the gates receive the\n * projected client view, so loader/server exports retain their legitimate\n * server access while component-visible code is refused before evaluation.\n */\nfunction clientEnvironmentOnly(\n  plugin: Plugin,\n  ssrState: SsrBoundaryState,\n): Plugin {\n  const validatesDevSsr =\n    plugin.name === \"warlock:gate-a-resolve\" ||\n    plugin.name === \"warlock:gate-b-secrets\";\n  const originalTransform =\n    typeof plugin.transform === \"function\"\n      ? plugin.transform\n      : plugin.transform?.handler;\n  const originalResolveId =\n    typeof plugin.resolveId === \"function\"\n      ? plugin.resolveId\n      : plugin.resolveId?.handler;\n  const originalBuildStart =\n    typeof plugin.buildStart === \"function\"\n      ? plugin.buildStart\n      : plugin.buildStart?.handler;\n\n  return {\n    ...plugin,\n    applyToEnvironment(environment) {\n      return (\n        environment.config.consumer === \"client\" ||\n        (validatesDevSsr && environment.config.consumer === \"server\")\n      );\n    },\n    buildStart: originalBuildStart\n      ? function (...args) {\n          if (isServerEnvironment(this)) return;\n          return originalBuildStart.apply(this, args);\n        }\n      : undefined,\n    transform: originalTransform\n      ? async function (code, id, options) {\n          if (!isServerEnvironment(this)) {\n            return originalTransform.call(this, code, id, options);\n          }\n\n          const clientCode = clientViewOf(ssrState, code, id);\n          if (clientCode === undefined) return null;\n\n          const transformed = await originalTransform.call(\n            this,\n            clientCode,\n            id,\n            {\n              ...options,\n              ssr: false,\n            },\n          );\n\n          // Vite can externalize a package in the SSR environment before its\n          // normal resolver walk offers that edge to a plugin. Gate A cannot\n          // wait for that walk: validate every import that survived projection\n          // now, while the original TypeScript source and importer are known.\n          if (plugin.name === \"warlock:gate-a-resolve\" && originalResolveId) {\n            for (const source of ssrState.clientImportsByModule.get(\n              moduleKey(id),\n            ) ?? []) {\n              const resolved = await originalResolveId.call(this, source, id, {\n                attributes: {},\n                isEntry: false,\n                ssr: false,\n              });\n              markResolvedClientModule(ssrState, resolved);\n            }\n          }\n\n          return transformed;\n        }\n      : undefined,\n    resolveId: originalResolveId\n      ? async function (source, importer, options) {\n          if (!isServerEnvironment(this)) {\n            return originalResolveId.call(this, source, importer, options);\n          }\n\n          if (!importer) return null;\n          const importerKey = moduleKey(importer);\n          const isClientBound =\n            ssrState.clientBoundModules.has(importerKey) ||\n            isStatelessClientSurface(importerKey, ssrState.appRoot);\n          if (!isClientBound) return null;\n\n          const survivingImports =\n            ssrState.clientImportsByModule.get(importerKey);\n          if (survivingImports && !survivingImports.has(source)) return null;\n\n          const resolved = await originalResolveId.call(\n            this,\n            source,\n            importer,\n            {\n              ...options,\n              ssr: false,\n            },\n          );\n          markResolvedClientModule(ssrState, resolved);\n          return resolved;\n        }\n      : undefined,\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(\n  options: WarlockClientBoundaryOptions = {},\n): Plugin[] {\n  const tracker = createPublicEnvTracker();\n  const ssrState: SsrBoundaryState = {\n    appRoot: path.resolve(options.appRoot ?? process.cwd()),\n    clientBoundModules: new Set(),\n    clientImportsByModule: new Map(),\n  };\n  return [\n    clientPageRegistry({\n      appRoot: options.appRoot,\n      beforePageHotUpdate: options.beforePageHotUpdate,\n    }),\n    projection(),\n    gateBSecrets({ tracker }),\n    gateAResolve(options),\n    gateCVerify({ ...options, tracker }),\n  ].map((plugin) => clientEnvironmentOnly(plugin, ssrState));\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: [\n      ...warlockClientBoundary({ appRoot: options.appRoot }),\n      ...(options.plugins ?? []),\n    ],\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA4FA,SAAS,UAAU,IAAoB;CACrC,OAAO,GAAG,MAAM,GAAG,EAAE,GAAG,QAAQ,OAAO,GAAG;AAC5C;AAEA,MAAM,wBAAwB;AAE9B,SAAS,yBAAyB,IAAY,SAA0B;CACtE,MAAM,OAAO,UAAU,EAAE;CACzB,IAAI,CAAC,gBAAgB,MAAM,OAAO,GAAG,OAAO;CAC5C,IAAI,aAAa,MAAM,OAAO,GAAG,OAAO;CAExC,OACE,kBAAkB,IAAI,KACtB,6BAA6B,IAAI,KACjC,wBAAwB,MAAM,OAAO;AAEzC;AAEA,SAAS,wBAAwB,MAA2B;CAC1D,MAAM,MAAM,MAAM,MAAM;EACtB,YAAY;EACZ,SAAS,CAAC,cAAc,KAAK;CAC/B,CAAC;CACD,MAAM,0BAAU,IAAI,IAAY;CAEhC,SAAS,KAAK,MAAqB;EACjC,IAAI,CAAC,QAAQ,OAAO,SAAS,UAAU;EACvC,IAAI,MAAM,QAAQ,IAAI,GAAG;GACvB,KAAK,MAAM,SAAS,MAAM,KAAK,KAAK;GACpC;EACF;EAEA,MAAM,SAAS;EACf,KACG,OAAO,SAAS,uBACf,OAAO,SAAS,4BAChB,OAAO,SAAS,2BAClB,OAAO,QAAQ,SAAS,iBAExB,QAAQ,IAAI,OAAO,OAAO,KAAK;EAEjC,IACE,OAAO,SAAS,oBAChB,OAAO,QAAQ,SAAS,YACxB,OAAO,YAAY,IAAI,SAAS,iBAEhC,QAAQ,IAAI,OAAO,UAAU,GAAG,KAAK;EAEvC,IACE,OAAO,SAAS,sBAChB,OAAO,QAAQ,SAAS,iBAExB,QAAQ,IAAI,OAAO,OAAO,KAAK;EAGjC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;GACjD,IACE,QAAQ,UACR,QAAQ,WACR,QAAQ,SACR,QAAQ,SACR,QAAQ,WACR,IAAI,SAAS,UAAU,KACvB,QAAQ,SAER;GAEF,KAAK,KAAK;EACZ;CACF;CAEA,KAAK,IAAI,OAAO;CAChB,OAAO;AACT;AAEA,SAAS,aACP,OACA,MACA,IACoB;CACpB,MAAM,MAAM,UAAU,EAAE;CACxB,IACE,CAAC,MAAM,mBAAmB,IAAI,GAAG,KACjC,CAAC,yBAAyB,KAAK,MAAM,OAAO,GAE5C;CAGF,MAAM,mBAAmB,IAAI,GAAG;CAChC,IAAI,CAAC,sBAAsB,KAAK,GAAG,GAAG;EACpC,MAAM,sBAAsB,IAAI,qBAAK,IAAI,IAAI,CAAC;EAC9C,OAAO;CACT;CAEA,MAAM,aAAa,kBAAkB,GAAG,IACpC,cAAc,MAAM,GAAG,EAAE,OACzB;CACJ,MAAM,sBAAsB,IAAI,KAAK,wBAAwB,UAAU,CAAC;CACxE,OAAO;AACT;AAEA,SAAS,yBACP,OACA,UACM;CACN,IAAI,CAAC,UAAU;CACf,MAAM,KAAK,OAAO,aAAa,WAAW,WAAW,SAAS;CAC9D,IAAI,CAAC,GAAG,SAAS,IAAI,GAAG,MAAM,mBAAmB,IAAI,UAAU,EAAE,CAAC;AACpE;AAEA,SAAS,oBAAoB,SAEjB;CACV,OAAO,QAAQ,aAAa,OAAO,aAAa;AAClD;;;;;;;;AASA,SAAS,sBACP,QACA,UACQ;CACR,MAAM,kBACJ,OAAO,SAAS,4BAChB,OAAO,SAAS;CAClB,MAAM,oBACJ,OAAO,OAAO,cAAc,aACxB,OAAO,YACP,OAAO,WAAW;CACxB,MAAM,oBACJ,OAAO,OAAO,cAAc,aACxB,OAAO,YACP,OAAO,WAAW;CACxB,MAAM,qBACJ,OAAO,OAAO,eAAe,aACzB,OAAO,aACP,OAAO,YAAY;CAEzB,OAAO;EACL,GAAG;EACH,mBAAmB,aAAa;GAC9B,OACE,YAAY,OAAO,aAAa,YAC/B,mBAAmB,YAAY,OAAO,aAAa;EAExD;EACA,YAAY,qBACR,SAAU,GAAG,MAAM;GACjB,IAAI,oBAAoB,IAAI,GAAG;GAC/B,OAAO,mBAAmB,MAAM,MAAM,IAAI;EAC5C,IACA;EACJ,WAAW,oBACP,eAAgB,MAAM,IAAI,SAAS;GACjC,IAAI,CAAC,oBAAoB,IAAI,GAC3B,OAAO,kBAAkB,KAAK,MAAM,MAAM,IAAI,OAAO;GAGvD,MAAM,aAAa,aAAa,UAAU,MAAM,EAAE;GAClD,IAAI,eAAe,QAAW,OAAO;GAErC,MAAM,cAAc,MAAM,kBAAkB,KAC1C,MACA,YACA,IACA;IACE,GAAG;IACH,KAAK;GACP,CACF;GAMA,IAAI,OAAO,SAAS,4BAA4B,mBAC9C,KAAK,MAAM,UAAU,SAAS,sBAAsB,IAClD,UAAU,EAAE,CACd,KAAK,CAAC,GAMJ,yBAAyB,UAAU,MALZ,kBAAkB,KAAK,MAAM,QAAQ,IAAI;IAC9D,YAAY,CAAC;IACb,SAAS;IACT,KAAK;GACP,CAAC,CAC0C;GAI/C,OAAO;EACT,IACA;EACJ,WAAW,oBACP,eAAgB,QAAQ,UAAU,SAAS;GACzC,IAAI,CAAC,oBAAoB,IAAI,GAC3B,OAAO,kBAAkB,KAAK,MAAM,QAAQ,UAAU,OAAO;GAG/D,IAAI,CAAC,UAAU,OAAO;GACtB,MAAM,cAAc,UAAU,QAAQ;GAItC,IAAI,EAFF,SAAS,mBAAmB,IAAI,WAAW,KAC3C,yBAAyB,aAAa,SAAS,OAAO,IACpC,OAAO;GAE3B,MAAM,mBACJ,SAAS,sBAAsB,IAAI,WAAW;GAChD,IAAI,oBAAoB,CAAC,iBAAiB,IAAI,MAAM,GAAG,OAAO;GAE9D,MAAM,WAAW,MAAM,kBAAkB,KACvC,MACA,QACA,UACA;IACE,GAAG;IACH,KAAK;GACP,CACF;GACA,yBAAyB,UAAU,QAAQ;GAC3C,OAAO;EACT,IACA;CACN;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoGA,SAAgB,sBACd,UAAwC,CAAC,GAC/B;CACV,MAAM,UAAU,uBAAuB;CACvC,MAAM,WAA6B;EACjC,SAAS,KAAK,QAAQ,QAAQ,WAAW,QAAQ,IAAI,CAAC;EACtD,oCAAoB,IAAI,IAAI;EAC5B,uCAAuB,IAAI,IAAI;CACjC;CACA,OAAO;EACL,mBAAmB;GACjB,SAAS,QAAQ;GACjB,qBAAqB,QAAQ;EAC/B,CAAC;EACD,WAAW;EACX,aAAa,EAAE,QAAQ,CAAC;EACxB,aAAa,OAAO;EACpB,YAAY;GAAE,GAAG;GAAS;EAAQ,CAAC;CACrC,EAAE,KAAK,WAAW,sBAAsB,QAAQ,QAAQ,CAAC;AAC3D;;;;;;AAOA,eAAsB,4BACpB,SACqC;CACrC,OAAO,qBAAqB;EAC1B,SAAS,QAAQ;EACjB,QAAQ,QAAQ;EAChB,gBAAgB,QAAQ;EACxB,UAAU,QAAQ;EAClB,SAAS,CACP,GAAG,sBAAsB,EAAE,SAAS,QAAQ,QAAQ,CAAC,GACrD,GAAI,QAAQ,WAAW,CAAC,CAC1B;CACF,CAAC;AACH"}

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

@@ -1,6 +1,6 @@
-import { Plugin } from "vite";
+import { Plugin, ViteDevServer } from "vite";
 
-//#region ../web/src/vite/page-registry-plugin.d.ts
+//#region web/src/vite/page-registry-plugin.d.ts
 /**
  * The specifier application code writes.
  *
@@ -15,9 +15,28 @@ declare const CLIENT_PAGE_REGISTRY_ID = "virtual:warlock/pages";
  * (and no filesystem watcher) mistakes it for a real path.
  */
 declare const RESOLVED_CLIENT_PAGE_REGISTRY_ID = "\0virtual:warlock/pages";
+/**
+ * Evicts the client registry so its next request re-runs page discovery, then
+ * reloads the document so hydration consumes that fresh registry.
+ *
+ * Vite 7 keeps separate module graphs per environment. Pages are imported by
+ * the browser, so only the resolved virtual module in the client graph is the
+ * cache entry this operation owns.
+ */
+declare function invalidateClientPageRegistry(vite: ViteDevServer): void;
 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;
+  /**
+   * Optional server-side barrier run before this plugin decides how the browser
+   * receives a page update. `true` means the callback already published the
+   * new route graph and sent the required reload, so this hook emits no second
+   * update for the same filesystem event.
+   */
+  beforePageHotUpdate?: (context: {
+    file: string;
+    type: "create" | "update" | "delete";
+  }) => boolean | Promise<boolean>;
 };
 /**
  * Serves the client page registry at {@link CLIENT_PAGE_REGISTRY_ID}.
@@ -39,5 +58,5 @@ type ClientPageRegistryPluginOptions = {
  */
 declare function clientPageRegistry(options?: ClientPageRegistryPluginOptions): Plugin;
 //#endregion
-export { CLIENT_PAGE_REGISTRY_ID, ClientPageRegistryPluginOptions, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry };
+export { CLIENT_PAGE_REGISTRY_ID, ClientPageRegistryPluginOptions, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry, invalidateClientPageRegistry };
 //# sourceMappingURL=page-registry-plugin.d.mts.map

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

@@ -1,10 +1,11 @@
 import { discoverPages, toPosix } from "../build/discover-pages.mjs";
+import { SERVER_EXPORT_NAMES } from "./projection.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
+//#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`
@@ -33,6 +34,23 @@ const CLIENT_PAGE_REGISTRY_ID = "virtual:warlock/pages";
 */
 const RESOLVED_CLIENT_PAGE_REGISTRY_ID = `\0${CLIENT_PAGE_REGISTRY_ID}`;
 /**
+* Evicts the client registry so its next request re-runs page discovery, then
+* reloads the document so hydration consumes that fresh registry.
+*
+* Vite 7 keeps separate module graphs per environment. Pages are imported by
+* the browser, so only the resolved virtual module in the client graph is the
+* cache entry this operation owns.
+*/
+function invalidateClientPageRegistry(vite) {
+	const moduleGraph = vite.environments.client.moduleGraph;
+	const registryModule = moduleGraph.getModuleById(RESOLVED_CLIENT_PAGE_REGISTRY_ID);
+	if (registryModule) moduleGraph.invalidateModule(registryModule);
+	vite.hot.send({
+		type: "full-reload",
+		path: "*"
+	});
+}
+/**
 * The import specifiers the emitted registry names must be ABSOLUTE POSIX file
 * paths, never relative ones.
 *
@@ -95,6 +113,184 @@ function eraseTypes(source) {
 	return magic.toString();
 }
 /**
+* The four file shapes that carry SERVER data (`metadata` chief among them)
+* and are therefore projected before the client graph forms — the exact set
+* `projection.ts`'s `isProjectableFile` matches, spelled here by BASENAME so
+* the two agree by construction on what "a server-side page module" is. A
+* change to one of these is the only kind of change whose SERVER half
+* (`metadata`, `loader`, …) can move without the client half moving at all.
+*/
+function isServerPageModule(file) {
+	const base = path.basename(file.split("?")[0]);
+	if (/\.page\.tsx?$/.test(base)) return true;
+	if (base === "layout.tsx" || base === "layout.ts") return true;
+	if (/\.layout\.tsx?$/.test(base)) return true;
+	if (base === "root.tsx") return true;
+	return false;
+}
+/**
+* What replaces a refresh-safe body in the skeleton. Its content is irrelevant —
+* only that it is CONSTANT, so two sources that differ solely inside a masked
+* body serialise identically.
+*/
+const MASKED_REFRESH_BODY = "/*warlock:refresh-body*/";
+/** React's own convention, and the one `react-refresh` itself uses: components are PascalCase. */
+function isComponentName(name) {
+	return typeof name === "string" && /^[A-Z]/.test(name);
+}
+/** The `body` node of a function-shaped expression/declaration, or `undefined` for anything else. */
+function functionBody(node) {
+	if (!node) return void 0;
+	if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") return node.body;
+}
+/**
+* Generic duck-typed identifier walk, the same shape `projection.ts`'s
+* `collectIdentifierNames` uses (it is not exported, and re-deriving one
+* OVER-collecting walk is safe here for the same reason it is safe there).
+*
+* Over-collecting — counting an object property key or a shadowing parameter
+* as a "read" — can only make the reachable set BIGGER, which can only UNMASK
+* more component bodies, which can only produce more reloads. The safe
+* direction.
+*/
+function collectIdentifierNames(node, names) {
+	if (!node || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const item of node) collectIdentifierNames(item, names);
+		return;
+	}
+	const record = node;
+	if (typeof record.type !== "string") return;
+	if (record.type === "Identifier" || record.type === "JSXIdentifier") names.add(record.name);
+	for (const key of Object.keys(record)) {
+		if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+		if (key === "leadingComments" || key === "trailingComments" || key === "innerComments" || key === "extra") continue;
+		collectIdentifierNames(record[key], names);
+	}
+}
+/** The module-scope names a top-level statement binds (the `export` wrapper looked through). */
+function topLevelBoundNames(stmt) {
+	const names = /* @__PURE__ */ new Set();
+	const declaration = stmt.type === "ExportNamedDeclaration" ? stmt.declaration : stmt;
+	if (!declaration) return names;
+	if (declaration.type === "VariableDeclaration") {
+		for (const declarator of declaration.declarations) if (declarator.id?.type === "Identifier") names.add(declarator.id.name);
+	} else if (declaration.id?.type === "Identifier") names.add(declaration.id.name);
+	return names;
+}
+/**
+* Every module-scope name reachable from one of the six server exports.
+*
+* Used ONLY to UNMASK: a PascalCase function that `metadata` or `loader` can
+* reach is not a component for this purpose, it is a server-side helper that
+* merely looks like one, and a change inside its body must reload. Seeded from
+* any top-level statement binding a `SERVER_EXPORT_NAMES` name — deliberately
+* looser than `projection.ts`'s own `isServerExportDeclaration` (no export
+* requirement, no single-declarator requirement), because seeding from MORE
+* statements can only unmask more, i.e. reload more.
+*
+* Fixpoint, not one pass, for the same reason projection's is: a server-only
+* helper can be reached only through another server-only helper.
+*/
+function serverReachableNames(body) {
+	const reached = /* @__PURE__ */ new Set();
+	const declarations = body.filter((stmt) => stmt.type !== "ImportDeclaration").map((stmt) => ({
+		stmt,
+		names: topLevelBoundNames(stmt)
+	}));
+	for (const { stmt, names } of declarations) {
+		let isServerExport = false;
+		for (const name of names) if (SERVER_EXPORT_NAMES.has(name)) isServerExport = true;
+		if (isServerExport) collectIdentifierNames(stmt, reached);
+	}
+	for (let changed = true; changed;) {
+		changed = false;
+		for (const { stmt, names } of declarations) {
+			let isReached = false;
+			for (const name of names) if (reached.has(name)) isReached = true;
+			if (!isReached) continue;
+			const before = reached.size;
+			collectIdentifierNames(stmt, reached);
+			if (reached.size !== before) changed = true;
+		}
+	}
+	return reached;
+}
+/**
+* The body node to mask for a top-level statement, or `undefined` if this
+* statement is neither a component declaration nor an exported `register`
+* declaration.
+*
+* Recognised shapes, and only these:
+*   - `export default function () {…}` / `export default () => …` — the page
+*     component, whatever it is called.
+*   - `function Name() {…}` / `const Name = () => …` (PascalCase, optionally
+*     `export`ed) — a component declared alongside it.
+*   - `export function register() {…}` / `export const register = () => …` —
+*     the lifecycle hook whose replacement namespace is invoked by projection.
+*
+* Everything else — `memo(...)`/`forwardRef(...)` wrappers, classes,
+* lowercase helpers, every server export — is left UNMASKED and therefore
+* compared byte-for-byte. That costs Fast Refresh on those shapes and buys the
+* guarantee; see this seam's header.
+*/
+function componentBodyToMask(stmt, serverReachable) {
+	if (stmt.type === "ExportDefaultDeclaration") return functionBody(stmt.declaration);
+	if (stmt.type === "ExportNamedDeclaration") {
+		const exported = stmt.declaration;
+		if (exported?.type === "FunctionDeclaration" && exported.id?.name === "register") return functionBody(exported);
+		if (exported?.type === "VariableDeclaration" && exported.declarations.length === 1) {
+			const declarator = exported.declarations[0];
+			if (declarator.id?.type === "Identifier" && declarator.id.name === "register") return functionBody(declarator.init);
+		}
+	}
+	const declaration = stmt.type === "ExportNamedDeclaration" ? stmt.declaration : stmt;
+	if (!declaration) return void 0;
+	const named = (name, node) => isComponentName(name) && !serverReachable.has(name) ? functionBody(node) : void 0;
+	if (declaration.type === "FunctionDeclaration") return named(declaration.id?.name, declaration);
+	if (declaration.type === "VariableDeclaration" && declaration.declarations.length === 1) {
+		const declarator = declaration.declarations[0];
+		if (declarator.id?.type !== "Identifier") return void 0;
+		return named(declarator.id.name, declarator.init);
+	}
+}
+/**
+* The module source with every component and exported `register` body replaced
+* by a constant — the ONE value the reload decision compares across an edit.
+*
+* Everything outside those bodies survives verbatim: imports, signatures,
+* module-level declarations, all six server exports, and the comments and
+* whitespace between them. So the skeleton is unchanged iff the save touched
+* nothing but refresh-safe bodies.
+*
+* Returns `undefined` when the source does not parse — a half-typed file whose
+* error Vite is already reporting from projection's real `transform`. The
+* caller leaves the cache holding the last GOOD skeleton, so the next
+* successful save is still compared against the right baseline.
+*/
+function captureSkeleton(code) {
+	let ast;
+	try {
+		ast = parse(code, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch {
+		return;
+	}
+	const body = ast.program.body;
+	const serverReachable = serverReachableNames(body);
+	const magic = new MagicString(code);
+	for (const stmt of body) {
+		const bodyNode = componentBodyToMask(stmt, serverReachable);
+		if (!bodyNode) continue;
+		const start = bodyNode.start;
+		const end = bodyNode.end;
+		if (end > start) magic.overwrite(start, end, MASKED_REFRESH_BODY);
+	}
+	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
@@ -114,6 +310,7 @@ function eraseTypes(source) {
 */
 function clientPageRegistry(options = {}) {
 	const appRoot = path.resolve(options.appRoot ?? process.cwd());
+	const skeletonCache = /* @__PURE__ */ new Map();
 	return {
 		name: "warlock:client-page-registry",
 		enforce: "pre",
@@ -129,10 +326,58 @@ function clientPageRegistry(options = {}) {
 				}),
 				toImportSpecifier
 			}));
+		},
+		/**
+		* Capture-only spy. Records the SKELETON of every server page module the
+		* CLIENT environment transforms, and returns nothing so projection's own
+		* `transform` still does the real work. SERVE-ONLY:
+		* `this.environment.mode !== "dev"` skips it during `vite build`, where
+		* there is no `hotUpdate` to feed and the extra parse would be pure cost.
+		*/
+		transform(code, id) {
+			if (this.environment?.mode !== "dev") return void 0;
+			if (!isServerPageModule(id)) return void 0;
+			const skeleton = captureSkeleton(code);
+			if (skeleton !== void 0) skeletonCache.set(id, skeleton);
+		},
+		/**
+		* Applies the ruling (canon `6b240682`): Fast Refresh ONLY when the only
+		* changes are inside component or exported `register` bodies.
+		*
+		*   - Skeleton moved (an import, a module-level declaration, ANY server
+		*     export — with or without a simultaneous JSX change) → full reload.
+		*   - Skeleton unchanged → defer to Fast Refresh, zero reloads.
+		*
+		* Note what is NOT here: no attempt to name which half a shared import or
+		* local belongs to. That question is what produced the two previous stale
+		* `<head>` bugs; this seam refuses to answer it and reloads instead.
+		* `hotUpdate` exists only on the dev server, so this is serve-only by
+		* construction.
+		*/
+		async hotUpdate(context) {
+			if (isServerPageModule(context.file)) {
+				if (await options.beforePageHotUpdate?.({
+					file: context.file,
+					type: context.type
+				})) return [];
+			}
+			if (context.type !== "update") return void 0;
+			if (!isServerPageModule(context.file)) return void 0;
+			const next = captureSkeleton(await context.read());
+			const prev = skeletonCache.get(context.file);
+			if (next !== void 0) skeletonCache.set(context.file, next);
+			if (next === void 0 || prev === void 0) return void 0;
+			if (prev !== next) {
+				this.environment.hot.send({
+					type: "full-reload",
+					path: "*"
+				});
+				return [];
+			}
 		}
 	};
 }
 
 //#endregion
-export { CLIENT_PAGE_REGISTRY_ID, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry };
+export { CLIENT_PAGE_REGISTRY_ID, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry, invalidateClientPageRegistry };
 //# sourceMappingURL=page-registry-plugin.mjs.map