@warlock.js/web 5.0.2 → 5.2.0

package/esm/server/unregistered-pages.mjs

@@ -0,0 +1,42 @@
+import { matchPath } from "./match-page-route.mjs";
+import { isNotFoundPageFile } from "./not-found-page.mjs";
+import { discoverPages, isDiscoveredRoutablePage, toPosix } from "../build/discover-pages.mjs";
+import path from "node:path";
+
+//#region web/src/server/unregistered-pages.ts
+function fileKey(file) {
+	const posix = toPosix(file);
+	return process.platform === "win32" ? posix.toLowerCase() : posix;
+}
+function findUnregisteredPages(options) {
+	const { appRoot, appSrcRoot, registeredPageFiles, discover = discoverPages } = options;
+	const registered = new Set(registeredPageFiles().map(fileKey));
+	const webRoot = path.resolve(appSrcRoot, "web");
+	return discover({
+		appRoot,
+		srcDir: path.relative(appRoot, appSrcRoot)
+	}).filter(isDiscoveredRoutablePage).filter((page) => path.resolve(page.webRoot) === webRoot && !isNotFoundPageFile(page.pageFile) && !registered.has(fileKey(page.pageFile)));
+}
+function describeUnregisteredPages(pageFiles, appRoot, request) {
+	const named = pageFiles.map((pageFile) => `  - ${toPosix(path.relative(appRoot, pageFile))}`).join("\n");
+	return `[warlock:web] ${request.method} ${request.url} answered 404. These src/web page files exist on disk but are absent from the active route table:
+` + named;
+}
+function createUnregisteredPageReporter(options) {
+	const { appRoot, warn = console.warn } = options;
+	const reported = /* @__PURE__ */ new Set();
+	return (request) => {
+		try {
+			const unregistered = findUnregisteredPages(options).find((page) => !reported.has(fileKey(page.pageFile)) && matchPath(page.routePath, request.pathname) !== void 0);
+			if (unregistered === void 0) return;
+			reported.add(fileKey(unregistered.pageFile));
+			warn(describeUnregisteredPages([unregistered.pageFile], appRoot, request));
+		} catch {
+			return;
+		}
+	};
+}
+
+//#endregion
+export { createUnregisteredPageReporter };
+//# sourceMappingURL=unregistered-pages.mjs.map

package/esm/server/unregistered-pages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"unregistered-pages.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/server/unregistered-pages.ts"],"sourcesContent":["import path from \"node:path\";\nimport {\n  discoverPages,\n  isDiscoveredRoutablePage,\n  toPosix,\n  type DiscoverPagesOptions,\n  type DiscoveredPage,\n} from \"../build/discover-pages\";\nimport { matchPath } from \"./match-page-route\";\nimport { isNotFoundPageFile } from \"./not-found-page\";\n\ntype DiscoveredGlobalPage = Extract<DiscoveredPage, { type: \"page\" }>;\ntype DiscoverPages = (options: DiscoverPagesOptions) => readonly DiscoveredPage[];\n\nexport type UnregisteredPagesOptions = {\n  appRoot: string;\n  appSrcRoot: string;\n  registeredPageFiles: () => readonly string[];\n  discover?: DiscoverPages;\n  warn?: (message: string) => void;\n};\n\nfunction fileKey(file: string): string {\n  const posix = toPosix(file);\n\n  return process.platform === \"win32\" ? posix.toLowerCase() : posix;\n}\n\nfunction findUnregisteredPages(options: UnregisteredPagesOptions): DiscoveredGlobalPage[] {\n  const { appRoot, appSrcRoot, registeredPageFiles, discover = discoverPages } = options;\n  const registered = new Set(registeredPageFiles().map(fileKey));\n  const webRoot = path.resolve(appSrcRoot, \"web\");\n\n  return discover({ appRoot, srcDir: path.relative(appRoot, appSrcRoot) })\n    .filter(isDiscoveredRoutablePage)\n    .filter(\n      (page) =>\n      path.resolve(page.webRoot) === webRoot &&\n      !isNotFoundPageFile(page.pageFile) &&\n      !registered.has(fileKey(page.pageFile)),\n    );\n}\n\nexport function findUnregisteredPageFiles(options: UnregisteredPagesOptions): string[] {\n  return findUnregisteredPages(options).map((page) => page.pageFile);\n}\n\nexport function describeUnregisteredPages(\n  pageFiles: readonly string[],\n  appRoot: string,\n  request: { method: string; url: string },\n): string {\n  const named = pageFiles\n    .map((pageFile) => `  - ${toPosix(path.relative(appRoot, pageFile))}`)\n    .join(\"\\n\");\n\n  return (\n    `[warlock:web] ${request.method} ${request.url} answered 404. ` +\n    \"These src/web page files exist on disk but are absent from the active route table:\\n\" +\n    named\n  );\n}\n\nexport function createUnregisteredPageReporter(\n  options: UnregisteredPagesOptions,\n): (request: { method: string; url: string; pathname: string }) => void {\n  const { appRoot, warn = console.warn } = options;\n  const reported = new Set<string>();\n\n  return (request) => {\n    // `discoverPages()` deliberately refuses malformed pages. Its install/build\n    // diagnostic is authoritative, so a response hook must leave this 404 alone.\n    try {\n      const unregistered = findUnregisteredPages(options).find(\n        (page) =>\n          !reported.has(fileKey(page.pageFile)) &&\n          matchPath(page.routePath, request.pathname) !== undefined,\n      );\n\n      if (unregistered === undefined) return;\n\n      reported.add(fileKey(unregistered.pageFile));\n      warn(describeUnregisteredPages([unregistered.pageFile], appRoot, request));\n    } catch {\n      return;\n    }\n  };\n}\n"],"mappings":";;;;;;AAsBA,SAAS,QAAQ,MAAsB;CACrC,MAAM,QAAQ,QAAQ,IAAI;CAE1B,OAAO,QAAQ,aAAa,UAAU,MAAM,YAAY,IAAI;AAC9D;AAEA,SAAS,sBAAsB,SAA2D;CACxF,MAAM,EAAE,SAAS,YAAY,qBAAqB,WAAW,kBAAkB;CAC/E,MAAM,aAAa,IAAI,IAAI,oBAAoB,EAAE,IAAI,OAAO,CAAC;CAC7D,MAAM,UAAU,KAAK,QAAQ,YAAY,KAAK;CAE9C,OAAO,SAAS;EAAE;EAAS,QAAQ,KAAK,SAAS,SAAS,UAAU;CAAE,CAAC,EACpE,OAAO,wBAAwB,EAC/B,QACE,SACD,KAAK,QAAQ,KAAK,OAAO,MAAM,WAC/B,CAAC,mBAAmB,KAAK,QAAQ,KACjC,CAAC,WAAW,IAAI,QAAQ,KAAK,QAAQ,CAAC,CACxC;AACJ;AAMA,SAAgB,0BACd,WACA,SACA,SACQ;CACR,MAAM,QAAQ,UACX,KAAK,aAAa,OAAO,QAAQ,KAAK,SAAS,SAAS,QAAQ,CAAC,GAAG,EACpE,KAAK,IAAI;CAEZ,OACE,iBAAiB,QAAQ,OAAO,GAAG,QAAQ,IAAI;IAE/C;AAEJ;AAEA,SAAgB,+BACd,SACsE;CACtE,MAAM,EAAE,SAAS,OAAO,QAAQ,SAAS;CACzC,MAAM,2BAAW,IAAI,IAAY;CAEjC,QAAQ,YAAY;EAGlB,IAAI;GACF,MAAM,eAAe,sBAAsB,OAAO,EAAE,MACjD,SACC,CAAC,SAAS,IAAI,QAAQ,KAAK,QAAQ,CAAC,KACpC,UAAU,KAAK,WAAW,QAAQ,QAAQ,MAAM,MACpD;GAEA,IAAI,iBAAiB,QAAW;GAEhC,SAAS,IAAI,QAAQ,aAAa,QAAQ,CAAC;GAC3C,KAAK,0BAA0B,CAAC,aAAa,QAAQ,GAAG,SAAS,OAAO,CAAC;EAC3E,QAAQ;GACN;EACF;CACF;AACF"}

package/esm/server/web-connector-factory.d.mts

@@ -2,12 +2,11 @@ import { WebBuildOptions } from "../build/contribution.mjs";
 import { WebConnectorOptions } from "./web-connector.mjs";
 import { Connector } from "@warlock.js/core";
 
-//#region ../web/src/server/web-connector-factory.d.ts
+//#region web/src/server/web-connector-factory.d.ts
 type WebConnectorFactoryOptions = WebConnectorOptions & {
   /**
    * What web contributes to `warlock build`. Passed straight to
-   * {@link createWebBuildContribution}; JSON-serializable values only — no
-   * plugin or pipeline instances, so a config load never pulls Vite in.
+   * {@link createWebBuildContribution}; JSON-serializable values only.
    */
   build?: WebBuildOptions;
 };

package/esm/server/web-connector-factory.mjs

@@ -1,9 +1,9 @@
 import { createWebBuildContribution } from "../build/contribution.mjs";
+import { ConnectorLifecyclePhase } from "@warlock.js/core";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { ConnectorLifecyclePhase } from "@warlock.js/core";
 
-//#region ../web/src/server/web-connector-factory.ts
+//#region web/src/server/web-connector-factory.ts
 /**
 * `webConnector()` — the ONE thing `warlock.config.ts` imports from
 * `@warlock.js/web/connector`, and the only value the `./connector` barrel
@@ -74,10 +74,11 @@ function deriveWebRoot() {
 function webConnector(options = {}) {
 	const { build: buildOptions, ...connectorOptions } = options;
 	const webRoot = connectorOptions.webRoot ?? deriveWebRoot();
+	const connectorPlugins = [...connectorOptions.plugins ?? []];
 	const build = createWebBuildContribution({
 		...buildOptions,
 		webRoot: buildOptions?.webRoot ?? webRoot
-	});
+	}, connectorPlugins);
 	let instance;
 	/**
 	* Load the heavy half on first lifecycle call. `boot()` is always the first
@@ -89,6 +90,7 @@ function webConnector(options = {}) {
 			const { WebConnector: WebConnectorClass } = await import("./web-connector.mjs");
 			instance = new WebConnectorClass({
 				...connectorOptions,
+				plugins: connectorPlugins,
 				webRoot
 			});
 		}
@@ -112,7 +114,7 @@ function webConnector(options = {}) {
 		shutdown: async () => {
 			await instance?.shutdown();
 		},
-		shouldRestart: () => false
+		shouldRestart: (changedFiles) => instance?.shouldRestart(changedFiles) ?? false
 	};
 }
 

package/esm/server/web-connector-factory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"web-connector-factory.mjs","names":[],"sources":["../../../../../../../web/src/server/web-connector-factory.ts"],"sourcesContent":["/**\n * `webConnector()` — the ONE thing `warlock.config.ts` imports from\n * `@warlock.js/web/connector`, and the only value the `./connector` barrel\n * adds beyond the build/runtime seams.\n *\n * WHY THIS MODULE EXISTS AT ALL, rather than the barrel exporting\n * `WebConnector` directly: `./web-connector.ts` imports `../vite`\n * (`web-connector.ts:52` → `@babel/parser` + `magic-string`),\n * `../../../core/src/router/router` (`:51`) and `./dev-server` (`:53`, which\n * itself pulls core's http stack and `../vite`) at VALUE level. Re-exporting\n * that class from `web/src/connector/index.ts` would drag every one of those\n * into the static graph of every consuming app's config file — the exact\n * config-load weight the `./connector` subpath was created to prevent.\n *\n * So the factory returns a LAZY DELEGATE: a `Connector` whose identity fields\n * (`name`, `priority`, `lifecyclePhase`, `build`) are plain data available\n * synchronously, and whose lifecycle methods `await import(\"./web-connector\")`\n * on first use. `warlock build` reads `build` off this object and never boots\n * anything, so a build never loads Vite or React through\n * here either. This is the third instance of a pattern the codebase already\n * uses twice — `core/src/connectors/access-connector.ts:39` and\n * `web/src/server/dev-cli.ts:61` — not a new one.\n *\n * KEEP THIS MODULE LIGHT. Its whole value-level static graph is `node:path`,\n * `node:url`, `../../../core/src/connectors/types` (whose own two imports are\n * both `import type` and therefore erased — `core/src/connectors/types.ts:1-2`)\n * and `../build/contribution` (`node:fs` + `node:path` + type-only core).\n * Everything else here is `import type`, which `verbatimModuleSyntax` erases.\n */\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  type Connector,\n  type ConnectorBuildContribution,\n  ConnectorLifecyclePhase,\n  type ConnectorName,\n} from \"@warlock.js/core\";\nimport { createWebBuildContribution, type WebBuildOptions } from \"../build/contribution\";\nimport type { WebConnector, WebConnectorOptions } from \"./web-connector\";\n\n/**\n * Boot/shutdown position relative to core's own connectors.\n *\n * `ConnectorPriority.HTTP` is `5` and `ConnectorPriority.STORAGE` is `6`\n * (`core/src/connectors/types.ts:187-188`), and the manager sorts on a plain\n * numeric compare (`core/src/connectors/connectors-manager.ts:46`) — so `5.5`\n * is \"immediately after http, before everything else\".\n *\n * Defined HERE and re-exported by `./web-connector` rather than the other way\n * round: the delegate must publish `priority` synchronously, and reading it\n * from the heavy module would defeat the whole point of the delegate.\n */\nexport const WEB_CONNECTOR_PRIORITY = 5.5;\n\nexport type WebConnectorFactoryOptions = WebConnectorOptions & {\n  /**\n   * What web contributes to `warlock build`. Passed straight to\n   * {@link createWebBuildContribution}; JSON-serializable values only — no\n   * plugin or pipeline instances, so a config load never pulls Vite in.\n   */\n  build?: WebBuildOptions;\n};\n\n/**\n * The `@warlock.js/web` package root, derived once from THIS module's location\n * and then passed EXPLICITLY to both halves.\n *\n * `web/src/server/web-connector-factory.ts` → `web/src/server` → `web/src` →\n * `web`; published as `web/esm/server/web-connector-factory.js`, two levels up\n * is the package root under both layouts — the same arithmetic\n * `contribution.ts:136-140` documents.\n *\n * Deriving it here and handing it down means the build contribution never falls\n * back to its own `import.meta.url` guess (`contribution.ts:129-141`): one\n * derivation, one place to be wrong, and `assertWebPackageRoot` verifies it\n * against `<root>/package.json`'s `name` either way.\n */\nfunction deriveWebRoot(): string {\n  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\");\n}\n\n/**\n * Construct web's connector for `warlock.config.ts > connectors`.\n *\n * @example\n * ```ts\n * export default defineConfig({ connectors: [webConnector()] });\n * ```\n */\nexport function webConnector(options: WebConnectorFactoryOptions = {}): Connector {\n  const { build: buildOptions, ...connectorOptions } = options;\n  const webRoot = connectorOptions.webRoot ?? deriveWebRoot();\n\n  const build: ConnectorBuildContribution = createWebBuildContribution({\n    ...buildOptions,\n    webRoot: buildOptions?.webRoot ?? webRoot,\n  });\n\n  let instance: WebConnector | undefined;\n\n  /**\n   * Load the heavy half on first lifecycle call. `boot()` is always the first\n   * of these to run (`core/src/connectors/connectors-manager.ts:87-93`), so the\n   * import lands in a process that has already committed to serving pages.\n   */\n  const load = async (): Promise<WebConnector> => {\n    if (!instance) {\n      const { WebConnector: WebConnectorClass } = await import(\"./web-connector\");\n\n      instance = new WebConnectorClass({ ...connectorOptions, webRoot });\n    }\n\n    return instance;\n  };\n\n  return {\n    name: \"web\" satisfies ConnectorName,\n    priority: WEB_CONNECTOR_PRIORITY,\n    lifecyclePhase: ConnectorLifecyclePhase.Late,\n    build,\n\n    // Never loads the heavy half: a connector that was never booted is not\n    // active, and answering that must not cost a Vite import.\n    isActive: () => instance?.isActive() ?? false,\n\n    boot: async () => {\n      await (await load()).boot();\n    },\n    start: async () => {\n      await (await load()).start();\n    },\n    restart: async () => {\n      await (await load()).restart();\n    },\n\n    // Both of these are asked of every registered connector, including ones\n    // that never booted — so neither may force the import.\n    shutdown: async () => {\n      await instance?.shutdown();\n    },\n    shouldRestart: () => false,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,MAAa,yBAAyB;;;;;;;;;;;;;;;AAyBtC,SAAS,gBAAwB;CAC/B,OAAO,KAAK,QAAQ,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC,GAAG,MAAM,IAAI;AAC9E;;;;;;;;;AAUA,SAAgB,aAAa,UAAsC,CAAC,GAAc;CAChF,MAAM,EAAE,OAAO,cAAc,GAAG,qBAAqB;CACrD,MAAM,UAAU,iBAAiB,WAAW,cAAc;CAE1D,MAAM,QAAoC,2BAA2B;EACnE,GAAG;EACH,SAAS,cAAc,WAAW;CACpC,CAAC;CAED,IAAI;;;;;;CAOJ,MAAM,OAAO,YAAmC;EAC9C,IAAI,CAAC,UAAU;GACb,MAAM,EAAE,cAAc,sBAAsB,MAAM,OAAO;GAEzD,WAAW,IAAI,kBAAkB;IAAE,GAAG;IAAkB;GAAQ,CAAC;EACnE;EAEA,OAAO;CACT;CAEA,OAAO;EACL,MAAM;EACN,UAAU;EACV,gBAAgB,wBAAwB;EACxC;EAIA,gBAAgB,UAAU,SAAS,KAAK;EAExC,MAAM,YAAY;GAChB,OAAO,MAAM,KAAK,EAAC,CAAE,KAAK;EAC5B;EACA,OAAO,YAAY;GACjB,OAAO,MAAM,KAAK,EAAC,CAAE,MAAM;EAC7B;EACA,SAAS,YAAY;GACnB,OAAO,MAAM,KAAK,EAAC,CAAE,QAAQ;EAC/B;EAIA,UAAU,YAAY;GACpB,MAAM,UAAU,SAAS;EAC3B;EACA,qBAAqB;CACvB;AACF"}
+{"version":3,"file":"web-connector-factory.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/server/web-connector-factory.ts"],"sourcesContent":["/**\n * `webConnector()` — the ONE thing `warlock.config.ts` imports from\n * `@warlock.js/web/connector`, and the only value the `./connector` barrel\n * adds beyond the build/runtime seams.\n *\n * WHY THIS MODULE EXISTS AT ALL, rather than the barrel exporting\n * `WebConnector` directly: `./web-connector.ts` imports `../vite`\n * (`web-connector.ts:52` → `@babel/parser` + `magic-string`),\n * `../../../core/src/router/router` (`:51`) and `./dev-server` (`:53`, which\n * itself pulls core's http stack and `../vite`) at VALUE level. Re-exporting\n * that class from `web/src/connector/index.ts` would drag every one of those\n * into the static graph of every consuming app's config file — the exact\n * config-load weight the `./connector` subpath was created to prevent.\n *\n * So the factory returns a LAZY DELEGATE: a `Connector` whose identity fields\n * (`name`, `priority`, `lifecyclePhase`, `build`) are plain data available\n * synchronously, and whose lifecycle methods `await import(\"./web-connector\")`\n * on first use. `warlock build` reads `build` off this object and never boots\n * anything, so a build never loads Vite or React through\n * here either. This is the third instance of a pattern the codebase already\n * uses twice — `core/src/connectors/access-connector.ts:39` and\n * `web/src/server/dev-cli.ts:61` — not a new one.\n *\n * KEEP THIS MODULE LIGHT. Its whole value-level static graph is `node:path`,\n * `node:url`, `../../../core/src/connectors/types` (whose own two imports are\n * both `import type` and therefore erased — `core/src/connectors/types.ts:1-2`)\n * and `../build/contribution` (`node:fs` + `node:path` + type-only core).\n * Everything else here is `import type`, which `verbatimModuleSyntax` erases.\n */\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  type Connector,\n  type ConnectorBuildContribution,\n  ConnectorLifecyclePhase,\n  type ConnectorName,\n} from \"@warlock.js/core\";\nimport {\n  createWebBuildContribution,\n  type WebBuildOptions,\n} from \"../build/contribution\";\nimport type { WebConnector, WebConnectorOptions } from \"./web-connector\";\n\n/**\n * Boot/shutdown position relative to core's own connectors.\n *\n * `ConnectorPriority.HTTP` is `5` and `ConnectorPriority.STORAGE` is `6`\n * (`core/src/connectors/types.ts:187-188`), and the manager sorts on a plain\n * numeric compare (`core/src/connectors/connectors-manager.ts:46`) — so `5.5`\n * is \"immediately after http, before everything else\".\n *\n * Defined HERE and re-exported by `./web-connector` rather than the other way\n * round: the delegate must publish `priority` synchronously, and reading it\n * from the heavy module would defeat the whole point of the delegate.\n */\nexport const WEB_CONNECTOR_PRIORITY = 5.5;\n\nexport type WebConnectorFactoryOptions = WebConnectorOptions & {\n  /**\n   * What web contributes to `warlock build`. Passed straight to\n   * {@link createWebBuildContribution}; JSON-serializable values only.\n   */\n  build?: WebBuildOptions;\n};\n\n/**\n * The `@warlock.js/web` package root, derived once from THIS module's location\n * and then passed EXPLICITLY to both halves.\n *\n * `web/src/server/web-connector-factory.ts` → `web/src/server` → `web/src` →\n * `web`; published as `web/esm/server/web-connector-factory.js`, two levels up\n * is the package root under both layouts — the same arithmetic\n * `contribution.ts:136-140` documents.\n *\n * Deriving it here and handing it down means the build contribution never falls\n * back to its own `import.meta.url` guess (`contribution.ts:129-141`): one\n * derivation, one place to be wrong, and `assertWebPackageRoot` verifies it\n * against `<root>/package.json`'s `name` either way.\n */\nfunction deriveWebRoot(): string {\n  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\");\n}\n\n/**\n * Construct web's connector for `warlock.config.ts > connectors`.\n *\n * @example\n * ```ts\n * export default defineConfig({ connectors: [webConnector()] });\n * ```\n */\nexport function webConnector(\n  options: WebConnectorFactoryOptions = {},\n): Connector {\n  const { build: buildOptions, ...connectorOptions } = options;\n  const webRoot = connectorOptions.webRoot ?? deriveWebRoot();\n  // One snapshot feeds both halves. Mutating the caller's array after config\n  // construction cannot make dev and `warlock build` observe different lists.\n  const connectorPlugins = [...(connectorOptions.plugins ?? [])];\n\n  const build: ConnectorBuildContribution = createWebBuildContribution(\n    {\n      ...buildOptions,\n      webRoot: buildOptions?.webRoot ?? webRoot,\n    },\n    connectorPlugins,\n  );\n\n  let instance: WebConnector | undefined;\n\n  /**\n   * Load the heavy half on first lifecycle call. `boot()` is always the first\n   * of these to run (`core/src/connectors/connectors-manager.ts:87-93`), so the\n   * import lands in a process that has already committed to serving pages.\n   */\n  const load = async (): Promise<WebConnector> => {\n    if (!instance) {\n      const { WebConnector: WebConnectorClass } =\n        await import(\"./web-connector\");\n\n      instance = new WebConnectorClass({\n        ...connectorOptions,\n        plugins: connectorPlugins,\n        webRoot,\n      });\n    }\n\n    return instance;\n  };\n\n  return {\n    name: \"web\" satisfies ConnectorName,\n    priority: WEB_CONNECTOR_PRIORITY,\n    lifecyclePhase: ConnectorLifecyclePhase.Late,\n    build,\n\n    // Never loads the heavy half: a connector that was never booted is not\n    // active, and answering that must not cost a Vite import.\n    isActive: () => instance?.isActive() ?? false,\n\n    boot: async () => {\n      await (await load()).boot();\n    },\n    start: async () => {\n      await (await load()).start();\n    },\n    restart: async () => {\n      await (await load()).restart();\n    },\n\n    // Both of these are asked of every registered connector, including ones\n    // that never booted — so neither may force the import.\n    shutdown: async () => {\n      await instance?.shutdown();\n    },\n\n    // Asked on EVERY watcher batch, so the `instance?.` is load-bearing twice:\n    // it keeps the answer free for a connector that never booted, and it is the\n    // only reason this delegate can forward the question at all — by the time a\n    // watcher batch exists, `boot()` has already loaded the heavy half, so\n    // reading the real answer off it costs nothing beyond the call.\n    //\n    // It used to be a hard `false`, which meant a `*.page.tsx` created while\n    // `warlock dev` was running was never noticed: page routes are installed\n    // once, in `WebConnector.boot()`, so the new page's URL 404'd in silence.\n    // The connector itself now decides: add/remove and route-identity edits are\n    // live route-table work; component-body-only edits remain Vite HMR work.\n    shouldRestart: (changedFiles: string[]) =>\n      instance?.shouldRestart(changedFiles) ?? false,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,MAAa,yBAAyB;;;;;;;;;;;;;;;AAwBtC,SAAS,gBAAwB;CAC/B,OAAO,KAAK,QAAQ,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC,GAAG,MAAM,IAAI;AAC9E;;;;;;;;;AAUA,SAAgB,aACd,UAAsC,CAAC,GAC5B;CACX,MAAM,EAAE,OAAO,cAAc,GAAG,qBAAqB;CACrD,MAAM,UAAU,iBAAiB,WAAW,cAAc;CAG1D,MAAM,mBAAmB,CAAC,GAAI,iBAAiB,WAAW,CAAC,CAAE;CAE7D,MAAM,QAAoC,2BACxC;EACE,GAAG;EACH,SAAS,cAAc,WAAW;CACpC,GACA,gBACF;CAEA,IAAI;;;;;;CAOJ,MAAM,OAAO,YAAmC;EAC9C,IAAI,CAAC,UAAU;GACb,MAAM,EAAE,cAAc,sBACpB,MAAM,OAAO;GAEf,WAAW,IAAI,kBAAkB;IAC/B,GAAG;IACH,SAAS;IACT;GACF,CAAC;EACH;EAEA,OAAO;CACT;CAEA,OAAO;EACL,MAAM;EACN,UAAU;EACV,gBAAgB,wBAAwB;EACxC;EAIA,gBAAgB,UAAU,SAAS,KAAK;EAExC,MAAM,YAAY;GAChB,OAAO,MAAM,KAAK,GAAG,KAAK;EAC5B;EACA,OAAO,YAAY;GACjB,OAAO,MAAM,KAAK,GAAG,MAAM;EAC7B;EACA,SAAS,YAAY;GACnB,OAAO,MAAM,KAAK,GAAG,QAAQ;EAC/B;EAIA,UAAU,YAAY;GACpB,MAAM,UAAU,SAAS;EAC3B;EAaA,gBAAgB,iBACd,UAAU,cAAc,YAAY,KAAK;CAC7C;AACF"}

package/esm/server/web-connector.d.mts

@@ -1,7 +1,7 @@
 import { BaseConnector, ConnectorLifecyclePhase } from "@warlock.js/core";
 import { Alias, PluginOption, ViteDevServer } from "vite";
 
-//#region ../web/src/server/web-connector.d.ts
+//#region web/src/server/web-connector.d.ts
 type WebConnectorOptions = {
   /**
    * Vite's `root` — the application directory that owns `src/`, `package.json`

package/esm/server/web-connector.mjs

@@ -4,16 +4,21 @@ import { consumePageManifest } from "./page-manifest.mjs";
 import { createHydrationClientEntry } from "../vite/hydration-entries.mjs";
 import { resolveHydrationClientUrl } from "./hydration-client-url.mjs";
 import { WEB_CONNECTOR_PRIORITY } from "./web-connector-factory.mjs";
+import { invalidateClientPageRegistry } from "../vite/page-registry-plugin.mjs";
 import { warlockClientBoundary } from "../vite/index.mjs";
 import { appConventionAliases } from "../vite/app-convention-aliases.mjs";
-import { applyBufferedCookie, devErrorTransportPlugin, sendCapturedDevError } from "./dev-server.mjs";
+import { devErrorTransportPlugin, sendCapturedDevError } from "./dev-server.mjs";
 import { installProductionPageRoutes } from "./install-production-page-routes.mjs";
-import path from "node:path";
+import { classifyPageFileChanges, hasPageFileChanges } from "./page-file-change.mjs";
+import { pageRouteSourceFiles, pageRoutesNeedReplacement, registeredPageFiles } from "./page-route-reload.mjs";
+import { registerProductionPublicFiles } from "./register-production-public-files.mjs";
+import { createUnregisteredPageReporter } from "./unregistered-pages.mjs";
+import { Application, BaseConnector, ConnectorLifecyclePhase, container, requestContext, router } from "@warlock.js/core";
 import fs from "node:fs";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { Application, BaseConnector, ConnectorLifecyclePhase, container, requestContext, router } from "@warlock.js/core";
 
-//#region ../web/src/server/web-connector.ts
+//#region web/src/server/web-connector.ts
 /**
 * `WebConnector` — the SSR page surface as a first-class Warlock connector.
 *
@@ -89,6 +94,23 @@ import { Application, BaseConnector, ConnectorLifecyclePhase, container, request
 function isProductionRuntime() {
 	return Application.runtimeStrategy === "production";
 }
+function pageFileVersion(file) {
+	try {
+		return `present:${fs.readFileSync(file, "utf8")}`;
+	} catch {
+		return "absent";
+	}
+}
+function pageChangeVersions(changes) {
+	return new Map([
+		...changes.added,
+		...changes.removed,
+		...changes.inspectionNeeded
+	].map((file) => {
+		const absoluteFile = path.resolve(file);
+		return [absoluteFile, pageFileVersion(absoluteFile)];
+	}));
+}
 var WebPageManifestMissingError = class extends Error {
 	constructor() {
 		super("WebConnector booted in production without a page manifest. The generated `pages.ts` barrel never ran, so no page modules were handed to the connector and there is nothing to serve. Run `warlock build` with the web connector registered in `warlock.config.ts > connectors`, and start the artifact that build produced.");
@@ -96,7 +118,7 @@ var WebPageManifestMissingError = class extends Error {
 	}
 };
 /**
-* The manifest carried pages but no `clientDir`.
+* The manifest carried browser artifacts but no `clientDir`.
 *
 * The build bakes that field in beside the page table, so the only way to
 * observe this is a VERSION SPLIT: an artifact produced by a `@warlock.js/web`
@@ -106,7 +128,7 @@ var WebPageManifestMissingError = class extends Error {
 */
 var WebClientDirMissingError = class extends Error {
 	constructor() {
-		super("The page manifest carries pages but no `clientDir`, so the connector cannot locate the client bundle. This artifact was built by an older @warlock.js/web than the one now running it. Re-run `warlock build` to regenerate the `pages.ts` barrel against the current version.");
+		super("The page manifest carries pages or public files but no `clientDir`, so the connector cannot locate the browser artifacts. This artifact was built by an older @warlock.js/web than the one now running it. Re-run `warlock build` to regenerate the `pages.ts` barrel against the current version.");
 		this.name = "WebClientDirMissingError";
 	}
 };
@@ -194,8 +216,9 @@ var WebConnector = class extends BaseConnector {
 	priority = WEB_CONNECTOR_PRIORITY;
 	lifecyclePhase = ConnectorLifecyclePhase.Late;
 	/**
-	* Nothing. Page, layout and component edits are Vite's HMR to own — a
-	* connector restart would tear down the module graph Vite is keeping warm.
+	* Nothing. Core already supplies each watcher batch to `shouldRestart`; page
+	* membership and route identity are classified there, while component and
+	* layout body edits remain Vite's HMR domain.
 	*/
 	watchedFiles = [];
 	options;
@@ -209,6 +232,21 @@ var WebConnector = class extends BaseConnector {
 	* production reading is a hard error and why the branch is on MODE.
 	*/
 	pageManifest;
+	/**
+	* The paths the DEVELOPMENT boot resolved, kept so `shouldRestart` can decide
+	* whether a changed file is a page without re-deriving (and re-proving) the
+	* web package root on every watcher batch. `undefined` in production and
+	* before boot, which is exactly when `shouldRestart` must answer `false`.
+	*/
+	resolvedPaths;
+	/** Synchronous watcher classification handed to the async reload phase. */
+	pendingPageChanges;
+	/** Reuses Vite's pipeline-barrel module instance for every dev reinstall. */
+	installDevPageRoutes;
+	/** Serializes Vite and core watcher callbacks that can observe the same edit. */
+	pageRouteReloadQueue = Promise.resolve();
+	/** Committed file versions awaiting the overlapping watcher callback. */
+	pendingHotUpdateSuppressions = /* @__PURE__ */ new Map();
 	constructor(options = {}) {
 		super();
 		this.options = options;
@@ -231,12 +269,12 @@ var WebConnector = class extends BaseConnector {
 		this.pageManifest = consumePageManifest();
 		if (isProductionRuntime() && !this.pageManifest) throw new WebPageManifestMissingError();
 		if (isProductionRuntime() && this.pageManifest) {
+			if ((this.pageManifest.publicFiles?.length ?? 0) > 0) registerProductionPublicFiles(router, this.resolveClientDir(), this.pageManifest.publicFiles ?? []);
 			this.installedPages = await installProductionPageRoutes({
 				router,
 				manifest: this.pageManifest,
 				pageContext: requestContext,
 				sharedStore: () => requestContext.getStore(),
-				applyBufferedCookie,
 				resolveHydrationClientModuleUrl: () => this.resolveHydrationClientModuleUrl(),
 				clientDir: this.pageManifest.clientDir
 			});
@@ -248,6 +286,7 @@ var WebConnector = class extends BaseConnector {
 		}
 		const fastify = this.resolveFastify();
 		const paths = await this.resolvePaths();
+		this.resolvedPaths = paths;
 		this.vite = await this.createViteServer(fastify, paths);
 		const webServerSsr = await this.vite.ssrLoadModule(paths.webServerBarrel);
 		webServerSsr.connectSharedStore(() => requestContext.getStore());
@@ -258,15 +297,28 @@ var WebConnector = class extends BaseConnector {
 				done(error);
 			});
 		});
-		this.installedPages = await webServerSsr.installPageRoutes({
+		const reportUnregisteredPages = createUnregisteredPageReporter({
+			appRoot: paths.appRoot,
+			appSrcRoot: paths.appSrcRoot,
+			registeredPageFiles: () => registeredPageFiles(router.list(), paths.appSrcRoot)
+		});
+		fastify.addHook("onResponse", (request, reply, done) => {
+			if (reply.statusCode === 404) reportUnregisteredPages({
+				method: request.method,
+				url: request.url,
+				pathname: new URL(request.url, "http://warlock.local").pathname
+			});
+			done();
+		});
+		this.installDevPageRoutes = () => webServerSsr.installPageRoutes({
 			router,
 			vite: this.vite,
 			appSrcRoot: paths.appSrcRoot,
 			appFile: paths.appFile,
 			hydrationClientModuleUrl: this.resolveHydrationClientModuleUrl(paths.webRoot),
-			stylesheetUrls: webServerSsr.devStylesheetUrls(paths.appRoot, paths.appFile),
-			applyBufferedCookie
+			stylesheetUrls: webServerSsr.devStylesheetUrls(paths.appRoot, paths.appFile)
 		});
+		this.installedPages = await this.installDevPageRoutes();
 	}
 	/**
 	* Where the browser fetches the hydration entry from — the one line that
@@ -345,16 +397,81 @@ var WebConnector = class extends BaseConnector {
 		await this.vite?.close();
 		this.vite = void 0;
 		this.installedPages = [];
+		this.installDevPageRoutes = void 0;
+		this.pendingPageChanges = void 0;
+		this.pendingHotUpdateSuppressions.clear();
 		this.pageManifest = void 0;
 		this.active = false;
 	}
 	/**
-	* Never restart on a file change. Pages, layouts and components are Vite's
-	* HMR domain; rebooting this connector would drop Vite's module graph and
-	* re-register every page route on a Fastify instance that is already serving.
+	* Queue page add/remove/edit candidates for asynchronous live routing work.
+	* Classification stays synchronous because core's connector interface is;
+	* edited route exports are evaluated later through Vite's fresh SSR graph.
+	*/
+	shouldRestart(changedFiles = []) {
+		if (this.vite === void 0 || this.resolvedPaths === void 0) return false;
+		this.pendingPageChanges = this.classifyPageChanges(changedFiles);
+		return this.pendingPageChanges !== void 0;
+	}
+	classifyPageChanges(changedFiles) {
+		if (this.resolvedPaths === void 0) return void 0;
+		const changes = classifyPageFileChanges(changedFiles, {
+			appRoot: this.resolvedPaths.appRoot,
+			appSrcRoot: this.resolvedPaths.appSrcRoot,
+			installedPageFiles: registeredPageFiles(router.list(), this.resolvedPaths.appSrcRoot)
+		});
+		return hasPageFileChanges(changes) ? changes : void 0;
+	}
+	enqueuePageRouteReload(changes) {
+		const eventVersions = pageChangeVersions(changes);
+		const run = this.pageRouteReloadQueue.catch(() => void 0).then(async () => {
+			const vite = this.vite;
+			const install = this.installDevPageRoutes;
+			const paths = this.resolvedPaths;
+			if (vite === void 0 || install === void 0 || paths === void 0) return false;
+			const matchingCommittedFiles = /* @__PURE__ */ new Set();
+			for (const [file, eventVersion] of eventVersions) {
+				const committedVersion = this.pendingHotUpdateSuppressions.get(file);
+				if (committedVersion === void 0) continue;
+				this.pendingHotUpdateSuppressions.delete(file);
+				if (committedVersion === eventVersion) matchingCommittedFiles.add(file);
+			}
+			if (eventVersions.size > 0 && matchingCommittedFiles.size === eventVersions.size) return true;
+			if (!await pageRoutesNeedReplacement(changes, {
+				vite,
+				appSrcRoot: paths.appSrcRoot,
+				installedPages: this.installedPages
+			})) return false;
+			const nextInstalledPages = await router.replaceRoutesBySourceFiles(pageRouteSourceFiles(router.list()), install);
+			this.installedPages = nextInstalledPages;
+			invalidateClientPageRegistry(vite);
+			for (const [file, eventVersion] of eventVersions) if (!matchingCommittedFiles.has(file)) this.pendingHotUpdateSuppressions.set(file, eventVersion);
+			return true;
+		});
+		this.pageRouteReloadQueue = run;
+		return run;
+	}
+	/**
+	* Vite-side ordering barrier. It publishes a changed route graph before the
+	* page-registry plugin can reload the document; a matching change already
+	* handled by core is consumed once, preventing a duplicate full reload.
+	*/
+	async handlePageHotUpdate(file) {
+		const absoluteFile = path.resolve(file);
+		const changes = this.classifyPageChanges([absoluteFile]);
+		if (changes === void 0) return false;
+		return this.enqueuePageRouteReload(changes);
+	}
+	/**
+	* Live page routing update. Despite the connector API name, this never closes
+	* Vite: it atomically replaces page-owned routes only when membership or the
+	* canonical route identity changed, then refreshes the client registry.
 	*/
-	shouldRestart() {
-		return false;
+	async restart() {
+		const changes = this.pendingPageChanges;
+		this.pendingPageChanges = void 0;
+		if (changes === void 0 || this.resolvedPaths === void 0 || this.vite === void 0 || this.installDevPageRoutes === void 0) return;
+		await this.enqueuePageRouteReload(changes);
 	}
 	/** The pages this connector registered on the router, in registration order. */
 	getInstalledPages() {
@@ -481,7 +598,10 @@ var WebConnector = class extends BaseConnector {
 					isProductionRuntime,
 					buildErrorMessage
 				}),
-				...warlockClientBoundary({ appRoot: paths.appRoot }),
+				...warlockClientBoundary({
+					appRoot: paths.appRoot,
+					beforePageHotUpdate: ({ file }) => this.handlePageHotUpdate(file)
+				}),
 				...await this.resolveReactFastRefreshPlugins(paths),
 				...this.options.plugins ?? []
 			],
@@ -498,6 +618,101 @@ var WebConnector = class extends BaseConnector {
 				target: "es2022",
 				jsx: "automatic"
 			},
+			/**
+			* REACT MUST BE PRE-BUNDLED, and naming it here is the only thing that
+			* makes that happen for the framework's own client graph.
+			*
+			* `react-dom/client` is CommonJS. A browser cannot import a named export
+			* from it, so Vite's dep optimizer normally rewrites it into an ESM shim
+			* under `/node_modules/.vite/deps/`. Whether that rewrite happens is
+			* decided in `tryNodeResolve`, and one of the conditions that SKIPS it is
+			* `importer && isInNodeModules(importer)`
+			* (`vite/dist/node/chunks/config.js:32822`). Vite's reasoning is sound in
+			* general — a dependency's own internal imports are the optimizer's job,
+			* not the resolver's — but it is exactly wrong here:
+			*
+			*   `<Scripts />` points the browser at the hydration entry, and in an
+			*   INSTALLED app that entry is
+			*   `<app>/node_modules/@warlock.js/web/esm/hydration/index.mjs`.
+			*   Every module it reaches is therefore inside `node_modules`, so every
+			*   bare import it makes takes the skip branch and is served as the raw
+			*   file with a `?v=<browserHash>` cache key bolted on.
+			*
+			* For `esm/**.mjs` that is harmless — they are already ESM. For
+			* `react-dom/client` it is fatal, and it is the whole defect: the browser
+			* receives `"use strict"; function checkDCE()…` and refuses the module
+			* with
+			*
+			*     SyntaxError: The requested module '/node_modules/react-dom/client.js?v=…'
+			*     does not provide an export named 'hydrateRoot'
+			*
+			* Nothing in the client runtime then runs at all: no hydration, so no
+			* `useState`, no Fast Refresh, and `<Link>` degrades to a full document
+			* load because the navigation listener was never attached. Measured on a
+			* published 5.0.2 install (fresh app, no symlinks): all four symptoms
+			* before this block, none after.
+			*
+			* `include` is the fix rather than `entries` because it does not depend
+			* on the scanner reaching the entry: an included id is pre-bundled at
+			* server start and `tryOptimizedResolve` matches it by NAME
+			* (`config.js:32633`) before `tryNodeResolve` — and that lookup has no
+			* importer condition, so a node_modules importer resolves to the shim
+			* like anyone else. Pointing `optimizeDeps.entries` at the hydration
+			* entry would not work: the scanner classifies a resolution inside
+			* `node_modules` as a dependency to externalize rather than a source to
+			* walk.
+			*
+			* All four names are listed even though `react` and `react/jsx-runtime`
+			* usually get discovered anyway — they are discovered only because the
+			* APP's own pages import them, which is a fact about the app and not
+			* something the framework may rely on. `react-dom/client` is imported by
+			* `client/hydrate-page.tsx` and by nothing a normal app writes, which is
+			* why it was the one that broke.
+			*
+			* This is INVISIBLE from the monorepo checkout: there the hydration entry
+			* resolves to `web/src/hydration/index.ts`, a path with no `node_modules`
+			* segment, so the skip branch never fires and React optimizes normally.
+			* Canon: nothing measured inside the checkout is evidence about a
+			* published install.
+			*/
+			optimizeDeps: {
+				include: [
+					"react",
+					"react-dom",
+					"react-dom/client",
+					"react/jsx-runtime"
+				],
+				/**
+				* The SECOND instance problem, and the reason this is `exclude` and not
+				* another `include`.
+				*
+				* An app page's `import { Link } from "@warlock.js/web"` has an importer
+				* OUTSIDE `node_modules`, so it takes the opposite branch above and the
+				* whole package is pre-bundled into
+				* `/node_modules/.vite/deps/@warlock__js_web.js`. The hydration entry
+				* cannot reach that bundle — it is loaded by absolute path through
+				* `/@fs/` and its imports are relative, so they resolve to the raw
+				* `esm/*.mjs` files. The browser then holds TWO copies of every client
+				* module in this package: the app renders `<Link>` from the bundled one
+				* while the hydration entry publishes routes and mounts the document
+				* context on the raw one. Module-level state does not cross that line.
+				*
+				* `routing/route-table` survives it by accident — it keeps its table in
+				* a `Symbol.for` slot on `globalThis`, which is realm-wide — but
+				* `components/document-context` is a React context OBJECT, and two
+				* `createContext()` calls are two different contexts no provider can
+				* bridge.
+				*
+				* Excluding the package makes the app's import resolve to
+				* `esm/index.mjs` with the same `?v=` key the hydration entry's imports
+				* carry, so there is one instance again. It costs the pre-bundle (a
+				* handful of extra dev requests for files that are already valid ESM)
+				* and nothing else — the grep across every client-reachable module in
+				* this package finds exactly three bare imports, all of them React, all
+				* of them covered by `include` above.
+				*/
+				exclude: ["@warlock.js/web"]
+			},
 			ssr: {
 				external: [
 					...CORE_OPTIONAL_PEERS,