@warlock.js/web 5.5.0 → 5.7.0

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

@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 * WHY THIS MODULE EXISTS AT ALL, rather than the barrel exporting
 * `WebConnector` directly: `./web-connector.ts` imports `../vite`
 * (`web-connector.ts:52` → `@babel/parser` + `magic-string`),
-* `../../../core/src/router/router` (`:51`) and `./dev-server` (`:53`, which
+* `../../../core/src/router/router` (`:51`) and `./dev-error-transport` (`:53`, which
 * itself pulls core's http stack and `../vite`) at VALUE level. Re-exporting
 * that class from `web/src/connector/index.ts` would drag every one of those
 * into the static graph of every consuming app's config file — the exact

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 {\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,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;EAaA,gBAAgB,iBACd,UAAU,cAAc,YAAY,KAAK;CAC7C;AACF"}
+{"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-error-transport` (`: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.\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  // 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 } = 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[]) => instance?.shouldRestart(changedFiles) ?? false,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,MAAa,yBAAyB;;;;;;;;;;;;;;;AAwBtC,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;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,sBAAsB,MAAM,OAAO;GAEzD,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,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;EAaA,gBAAgB,iBAA2B,UAAU,cAAc,YAAY,KAAK;CACtF;AACF"}

package/esm/server/web-connector.mjs

@@ -5,17 +5,17 @@ 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 { devErrorTransportPlugin, sendCapturedDevError } from "./dev-server.mjs";
+import "../vite/index.mjs";
+import { createWebConnectorViteConfig } from "../vite/dev-server-config.mjs";
+import { devErrorTransportPlugin, sendCapturedDevError } from "./dev-error-transport.mjs";
 import { installProductionPageRoutes } from "./install-production-page-routes.mjs";
 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 fs from "node:fs";
 import { fileURLToPath } from "node:url";
 
 //#region ../web/src/server/web-connector.ts
@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 * It runs BESIDE `HttpConnector`, never instead of it: `warlock dev` alone now boots the API *and* serves React
 * pages on one port, and `web` no longer owns a private copy of the HTTP
 * lifecycle. Everything this file does used to live in `startDevServer()`
-* (`web/src/server/dev-server.ts`), which created its own Fastify instance,
+* (`web/src/server/dev-error-transport.ts`), which created its own Fastify instance,
 * scanned the router and called `listen()` itself — three responsibilities core
 * already owns at `core/src/connectors/http-connector.ts:72`, `:133` and `:147`.
 *
@@ -50,7 +50,7 @@ import { fileURLToPath } from "node:url";
 * the ordinary `router.get(…)` API — there is no second server matcher.
 *
 * DELIBERATE EXCEPTION to A.3 §2 ("web has no core dependency"), the same one
-* `./dev-server.ts` and `./install-page-routes.ts` record in their own headers:
+* `./dev-error-transport.ts` and `./install-page-routes.ts` record in their own headers:
 * this module is not re-exported from any package barrel (`web/src/index.ts`,
 * `web/src/server/index.ts`, `web/src/connector/index.ts`) and is not part of
 * `web/package.json`'s dependency graph. It is dev/CLI bootstrap code, only
@@ -59,7 +59,7 @@ import { fileURLToPath } from "node:url";
 * `@warlock.js/web/connector` reaches this class ONLY through
 * `./web-connector-factory.ts`'s `await import("./web-connector")` — a
 * deliberate seam, because a static edge from that barrel to this file would
-* put `../vite`, core's router and `./dev-server` into the import graph of
+* put `../vite`, core's router and `./dev-error-transport` into the import graph of
 * every consuming app's `warlock.config.ts`.
 */
 /**
@@ -133,58 +133,6 @@ var WebClientDirMissingError = class extends Error {
 	}
 };
 /**
-* Third-party packages core reaches through `await import(...)` and that must
-* therefore never enter Vite's SSR transform graph.
-*
-* Left un-externalized, Vite's SSR module runner tries to resolve them anyway
-* and jams: the failure is NOT a missing-module error but a `transport invoke
-* timed out` on whatever unrelated module happened to be in flight. Derived in
-* one pass from `peerDependenciesMeta.optional` across every workspace package
-* reachable from `core/src/index.ts`, and carried over verbatim from
-* `dev-server.ts`'s own list. Only THIRD-PARTY peers belong here — every
-* `@warlock.js/*` sibling must stay in Vite's graph.
-*
-* This list is core's peer list, not web's; publishing it from core instead
-* of duplicating it here is still outstanding.
-*/
-const CORE_OPTIONAL_PEERS = [
-	"nodemailer",
-	"@aws-sdk/client-sesv2",
-	"@react-email/render",
-	"redis",
-	"pg",
-	"mongodb",
-	"@sentry/node",
-	"sharp",
-	"socket.io",
-	"@aws-sdk/client-s3",
-	"@aws-sdk/lib-storage",
-	"@aws-sdk/s3-request-presigner",
-	"amqplib",
-	"langfuse",
-	"openai",
-	"pdf-parse"
-];
-/**
-* `web`'s OWN optional peers, kept separate from {@link CORE_OPTIONAL_PEERS}
-* because that list is core's and is documented as such.
-*
-* Same rule, same reason: anything this package reaches through
-* `await import(...)` must be external to every bundler and SSR pipeline, or
-* some pipeline will try to resolve it in an install that legitimately does not
-* have it. `vite` itself is the precedent — `createViteServer` has always
-* loaded it this way — and `@vitejs/plugin-react` is loaded from the same
-* function, for the same dev-only reason, so it belongs in the same set.
-*/
-const WEB_OPTIONAL_PEERS = ["vite", "@vitejs/plugin-react"];
-/**
-* Public specifier for the React Fast Refresh preamble module this connector
-* injects. See {@link WebConnector.resolveReactFastRefreshPlugins}.
-*/
-const REACT_REFRESH_PREAMBLE_ID = "virtual:warlock/react-refresh-preamble";
-/** The `\0`-prefixed form Rollup uses to mark a module as not-a-file. */
-const RESOLVED_REACT_REFRESH_PREAMBLE_ID = `\0${REACT_REFRESH_PREAMBLE_ID}`;
-/**
 * `@fastify/static`'s `maxAge` is milliseconds (the `send` package's option,
 * not seconds like `Cache-Control`'s own `max-age`) — one year, matching the
 * header this produces: `public, max-age=31536000, immutable`. Safe forever
@@ -207,28 +155,6 @@ function productionAssetsDirectoryOptions(clientDir) {
 	};
 }
 /**
-* A directory, plus the path the filesystem really stores it at when the two
-* differ. Both forms belong in `server.fs.allow` — see the `fs` block in
-* {@link WebConnector.createViteServer} for why one of them is never enough.
-*
-* A missing directory is not this function's problem to report: the roots it is
-* handed are already proven (`resolveWebPackageRoot`) or are the app's own cwd,
-* and an allow-list entry that points nowhere simply matches nothing.
-*/
-function withRealPath(directory) {
-	try {
-		const realPath = fs.realpathSync(directory);
-		return realPath === directory ? [directory] : [directory, realPath];
-	} catch {
-		return [directory];
-	}
-}
-/** POSIX-normalised, case-folded — Vite ids are `/`-separated on Windows too. */
-function normalizeModuleId(id) {
-	const [filepath] = id.split("?");
-	return filepath.replace(/\\/g, "/").toLowerCase();
-}
-/**
 * Web Connector
 * Manages the Vite dev server and the SSR page routes, mounted on the HTTP
 * connector's Fastify instance.
@@ -291,7 +217,7 @@ 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 ?? []);
+			if (this.pageManifest.clientDir !== void 0) registerProductionPublicFiles(router, this.resolveClientDir(), this.pageManifest.publicFiles ?? []);
 			this.installedPages = await installProductionPageRoutes({
 				router,
 				manifest: this.pageManifest,
@@ -334,8 +260,9 @@ var WebConnector = class extends BaseConnector {
 			vite: this.vite,
 			appSrcRoot: paths.appSrcRoot,
 			appFile: paths.appFile,
+			appRoot: paths.appRoot,
 			hydrationClientModuleUrl: this.resolveHydrationClientModuleUrl(paths.webRoot),
-			stylesheetUrls: webServerSsr.devStylesheetUrls(paths.appRoot, paths.appFile)
+			httpServer: fastify
 		});
 		this.installedPages = await this.installDevPageRoutes();
 	}
@@ -523,248 +450,24 @@ var WebConnector = class extends BaseConnector {
 			webServerBarrel: path.join(path.dirname(selfPath), `index${path.extname(selfPath)}`)
 		};
 	}
-	/**
-	* Vite in middleware mode, `appType: "custom"` — Warlock owns the response
-	* shape and Vite never fronts the server.
-	*
-	* `server.hmr.server` is handed the RAW node server (`fastify.server`), so the
-	* HMR websocket shares the one port the app already listens on. No `hmr.port`
-	* and no `clientPort`: Vite's HMR path stays the default `"/"`, socket.io
-	* stays on `"/socket.io"` (`core/src/connectors/socket-connector.ts:90`), and
-	* the two `upgrade` listeners coexist because each is a selective filter that
-	* leaves a non-matching socket alone — verified empirically in both attachment
-	* orders.
-	*/
-	/**
-	* React Fast Refresh, or nothing at all — never half of it.
-	*
-	* TWO plugins, and the second one is not optional. `@vitejs/plugin-react`
-	* emits, into every client component module, a wrapper that reads
-	* `window.$RefreshReg$` and THROWS "can't detect preamble" if it is missing.
-	* The preamble that defines it normally arrives through Vite's
-	* `transformIndexHtml`, and this pipeline has no HTML for Vite to transform:
-	* the document is React's SSR output and the only script appended to it is
-	* the hydration entry (`./create-page-route-handler.ts:95`). So the preamble
-	* is delivered as a virtual module that the hydration entry imports FIRST.
-	*
-	* "First" is load-bearing, twice over. ESM evaluates a module's imports in
-	* source order before the importer's own body, so an import placed at
-	* position 0 runs before `virtual:warlock/pages` pulls in a single component
-	* — which is what `$RefreshReg$` has to exist for — and before `react-dom`
-	* initialises, which is what `injectIntoGlobalHook` has to precede.
-	*
-	* The preamble TEXT is read from the plugin's own `preambleCode` export
-	* rather than copied here, so a version bump cannot leave this file holding
-	* a stale runtime contract. If that export ever stops being a string, Fast
-	* Refresh is DECLINED entirely (empty array) instead of registered without
-	* its preamble — a loud "no HMR" beats a component graph that throws on
-	* first paint.
-	*
-	* Dev-only by construction, like everything else this method is called from:
-	* `apply: "serve"` on our own plugin, `apply: "serve"` on the plugin's
-	* refresh half, and `skipFastRefresh` on `config.isProduction` inside it. The
-	* PRODUCTION client bundle cannot reach any of this — it is built by
-	* `buildWarlockHydrationClient` (`../vite/index.ts:185`), which composes
-	* `warlockClientBoundary()` and nothing else, and never calls this method.
-	*
-	* @param paths resolved by {@link WebConnector.resolvePaths}
-	*/
-	async resolveReactFastRefreshPlugins(paths) {
-		let viteReact;
-		try {
-			({default: viteReact} = await import("@vitejs/plugin-react"));
-		} catch {
-			console.warn("[warlock:web] React Fast Refresh is OFF: `@vitejs/plugin-react` is not installed. Edits to a component will reload the page instead of hot-swapping it. Install it with `npm i -D @vitejs/plugin-react` to enable it.");
-			return [];
-		}
-		const preambleCode = viteReact.preambleCode;
-		if (typeof preambleCode !== "string") {
-			console.warn("[warlock:web] React Fast Refresh is OFF: this `@vitejs/plugin-react` no longer exports `preambleCode`, so the refresh preamble cannot be injected into the hydration entry. Registering the plugin without it would make every component module throw \"can't detect preamble\" in the browser.");
-			return [];
-		}
-		const preambleSource = preambleCode.replace("__BASE__", "/");
-		const hydrationEntryId = normalizeModuleId(createHydrationClientEntry(paths.webRoot).sourcePath);
-		return [{
-			name: "warlock:react-refresh-preamble",
-			enforce: "pre",
-			apply: "serve",
-			applyToEnvironment: (environment) => environment.config.consumer === "client",
-			resolveId(source) {
-				if (source === REACT_REFRESH_PREAMBLE_ID) return RESOLVED_REACT_REFRESH_PREAMBLE_ID;
-				return null;
-			},
-			load(id) {
-				if (id === RESOLVED_REACT_REFRESH_PREAMBLE_ID) return preambleSource;
-				return null;
-			},
-			transform(code, id) {
-				if (normalizeModuleId(id) !== hydrationEntryId) return null;
-				return {
-					code: `import ${JSON.stringify(REACT_REFRESH_PREAMBLE_ID)};\n${code}`,
-					map: null
-				};
-			}
-		}, ...viteReact()];
-	}
 	async createViteServer(fastify, paths) {
 		const { createServer, buildErrorMessage, searchForWorkspaceRoot } = await import("vite");
 		const workspaceRoot = searchForWorkspaceRoot(paths.appRoot);
-		return createServer({
-			root: paths.appRoot,
-			appType: "custom",
-			plugins: [
-				devErrorTransportPlugin({
-					isProductionRuntime,
-					buildErrorMessage
-				}),
-				...warlockClientBoundary({
-					appRoot: paths.appRoot,
-					beforePageHotUpdate: ({ file }) => this.handlePageHotUpdate(file)
-				}),
-				...await this.resolveReactFastRefreshPlugins(paths),
-				...this.options.plugins ?? []
-			],
-			server: {
-				middlewareMode: true,
-				hmr: { server: fastify.server },
-				fs: { allow: [...new Set([
-					...withRealPath(workspaceRoot),
-					...withRealPath(paths.appRoot),
-					...withRealPath(paths.webRoot)
-				])] }
-			},
-			esbuild: {
-				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,
-					...WEB_OPTIONAL_PEERS,
-					...this.options.ssrExternal ?? []
-				],
-				/**
-				* ONE `@warlock.js/web`, for the same reason `resolve.dedupe` below
-				* insists on one React — and it is invisible from inside this repo.
-				*
-				* Vite externalises `node_modules` in SSR by default, so an installed
-				* app gets TWO instances: the app's own `root.tsx` imports
-				* `@warlock.js/web` and Vite hands that off to Node, while the pipeline
-				* is loaded deliberately through `vite.ssrLoadModule(...)` and stays
-				* inside Vite's graph. `renderPage` then sets the document context on
-				* Vite's copy of `components/document-context`, and the app's `<Head/>`
-				* reads Node's copy, which has nothing in it:
-				*
-				*     <Head/> was rendered outside the page pipeline's document context
-				*
-				* Measured on a published 5.0.1 install: `GET /` 500 without this line,
-				* 200 with it (404 control still 404). In THIS checkout the package
-				* resolves to source under Vite's root, never through `node_modules`,
-				* so both paths land on one instance and the bug cannot reproduce.
-				* Canon `6b7ab838`.
-				*/
-				noExternal: ["@warlock.js/web"]
-			},
-			resolve: {
-				dedupe: ["react", "react-dom"],
-				alias: [...this.options.resolveAlias ?? [], ...appConventionAliases(paths.appSrcRoot)]
-			}
-		});
+		return createServer(await createWebConnectorViteConfig({
+			appRoot: paths.appRoot,
+			appSrcRoot: paths.appSrcRoot,
+			webRoot: paths.webRoot,
+			workspaceRoot,
+			hmrServer: fastify.server,
+			handlePageHotUpdate: (file) => this.handlePageHotUpdate(file),
+			leadingPlugins: [devErrorTransportPlugin({
+				isProductionRuntime,
+				buildErrorMessage
+			})],
+			resolveAlias: this.options.resolveAlias,
+			ssrExternal: this.options.ssrExternal,
+			plugins: this.options.plugins
+		}));
 	}
 };