@warlock.js/web 5.4.0 → 5.6.0

package/esm/vite/dev-server-config.mjs

@@ -0,0 +1,240 @@
+import { warlockClientBoundary } from "./index.mjs";
+import { appConventionAliases } from "./app-convention-aliases.mjs";
+import { resolveReactFastRefreshPlugins } from "./react-refresh-preamble.mjs";
+import fs from "node:fs";
+
+//#region ../web/src/vite/dev-server-config.ts
+/**
+* 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-error-transport.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"];
+/**
+* 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 createWebConnectorViteConfig} 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];
+	}
+}
+/**
+* `WebConnector`'s Vite dev-server config — 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.
+*/
+async function createWebConnectorViteConfig(options) {
+	return {
+		root: options.appRoot,
+		appType: "custom",
+		plugins: [
+			...options.leadingPlugins,
+			...warlockClientBoundary({
+				appRoot: options.appRoot,
+				beforePageHotUpdate: ({ file }) => options.handlePageHotUpdate(file)
+			}),
+			...await resolveReactFastRefreshPlugins({ webRoot: options.webRoot }),
+			...options.plugins ?? []
+		],
+		server: {
+			middlewareMode: true,
+			hmr: { server: options.hmrServer },
+			fs: { allow: [...new Set([
+				...withRealPath(options.workspaceRoot),
+				...withRealPath(options.appRoot),
+				...withRealPath(options.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/entry/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/entry/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,
+				...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: [...options.resolveAlias ?? [], ...appConventionAliases(options.appSrcRoot)]
+		}
+	};
+}
+
+//#endregion
+export { createWebConnectorViteConfig };
+//# sourceMappingURL=dev-server-config.mjs.map

package/esm/vite/dev-server-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server-config.mjs","names":[],"sources":["../../../../../../../web/src/vite/dev-server-config.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Alias, HttpServer, InlineConfig, PluginOption } from \"vite\";\nimport { appConventionAliases } from \"./app-convention-aliases\";\nimport { warlockClientBoundary } from \"./index\";\nimport { resolveReactFastRefreshPlugins } from \"./react-refresh-preamble\";\n\n/**\n * Third-party packages core reaches through `await import(...)` and that must\n * therefore never enter Vite's SSR transform graph.\n *\n * Left un-externalized, Vite's SSR module runner tries to resolve them anyway\n * and jams: the failure is NOT a missing-module error but a `transport invoke\n * timed out` on whatever unrelated module happened to be in flight. Derived in\n * one pass from `peerDependenciesMeta.optional` across every workspace package\n * reachable from `core/src/index.ts`, and carried over verbatim from\n * `dev-error-transport.ts`'s own list. Only THIRD-PARTY peers belong here — every\n * `@warlock.js/*` sibling must stay in Vite's graph.\n *\n * This list is core's peer list, not web's; publishing it from core instead\n * of duplicating it here is still outstanding.\n */\nconst CORE_OPTIONAL_PEERS = [\n  // mail\n  \"nodemailer\",\n  \"@aws-sdk/client-sesv2\",\n  \"@react-email/render\",\n  // cache\n  \"redis\",\n  \"pg\",\n  // cascade\n  \"mongodb\",\n  // logger\n  \"@sentry/node\",\n  // core\n  \"sharp\",\n  \"socket.io\",\n  \"@aws-sdk/client-s3\",\n  \"@aws-sdk/lib-storage\",\n  \"@aws-sdk/s3-request-presigner\",\n  // herald\n  \"amqplib\",\n  // ai\n  \"langfuse\",\n  \"openai\",\n  \"pdf-parse\",\n] as const;\n\n/**\n * `web`'s OWN optional peers, kept separate from {@link CORE_OPTIONAL_PEERS}\n * because that list is core's and is documented as such.\n *\n * Same rule, same reason: anything this package reaches through\n * `await import(...)` must be external to every bundler and SSR pipeline, or\n * some pipeline will try to resolve it in an install that legitimately does not\n * have it. `vite` itself is the precedent — `createViteServer` has always\n * loaded it this way — and `@vitejs/plugin-react` is loaded from the same\n * function, for the same dev-only reason, so it belongs in the same set.\n */\nconst WEB_OPTIONAL_PEERS = [\"vite\", \"@vitejs/plugin-react\"] as const;\n\n/**\n * A directory, plus the path the filesystem really stores it at when the two\n * differ. Both forms belong in `server.fs.allow` — see the `fs` block in\n * {@link createWebConnectorViteConfig} for why one of them is never enough.\n *\n * A missing directory is not this function's problem to report: the roots it is\n * handed are already proven (`resolveWebPackageRoot`) or are the app's own cwd,\n * and an allow-list entry that points nowhere simply matches nothing.\n */\nfunction withRealPath(directory: string): string[] {\n  try {\n    const realPath = fs.realpathSync(directory);\n\n    return realPath === directory ? [directory] : [directory, realPath];\n  } catch {\n    return [directory];\n  }\n}\n\nexport type WebConnectorViteConfigOptions = {\n  appRoot: string;\n  appSrcRoot: string;\n  webRoot: string;\n  workspaceRoot: string;\n  /** The raw node server Vite's HMR websocket shares with the rest of the app. */\n  hmrServer: HttpServer;\n  handlePageHotUpdate: (file: string) => Promise<boolean>;\n  /** Plugins that must run ahead of the client-boundary gates, e.g. `devErrorTransportPlugin`. */\n  leadingPlugins: PluginOption[];\n  resolveAlias?: Alias[];\n  ssrExternal?: string[];\n  plugins?: PluginOption[];\n};\n\n/**\n * `WebConnector`'s Vite dev-server config — Vite in middleware mode,\n * `appType: \"custom\"` — Warlock owns the response shape and Vite never fronts\n * the server.\n *\n * `server.hmr.server` is handed the RAW node server (`fastify.server`), so the\n * HMR websocket shares the one port the app already listens on. No `hmr.port`\n * and no `clientPort`: Vite's HMR path stays the default `\"/\"`, socket.io\n * stays on `\"/socket.io\"` (`core/src/connectors/socket-connector.ts:90`), and\n * the two `upgrade` listeners coexist because each is a selective filter that\n * leaves a non-matching socket alone — verified empirically in both attachment\n * orders.\n */\nexport async function createWebConnectorViteConfig(\n  options: WebConnectorViteConfigOptions,\n): Promise<InlineConfig> {\n  return {\n    root: options.appRoot,\n    appType: \"custom\",\n    plugins: [\n      // FIRST, and dev-only by construction: this method is reachable only\n      // from `boot()`'s Vite branch, past the `isProductionRuntime()` guard.\n      // The same predicate is handed in rather than re-derived, and the\n      // factory throws if it is ever true — see the plugin's own header for\n      // why the layer has to be registered from a plugin and not from\n      // `vite.middlewares.use(...)` after this call returns.\n      ...options.leadingPlugins,\n      ...warlockClientBoundary({\n        appRoot: options.appRoot,\n        beforePageHotUpdate: ({ file }) => options.handlePageHotUpdate(file),\n      }),\n      // AFTER the boundary, and the order matters among `enforce: \"pre\"`\n      // plugins (Vite keeps array order within an enforce bucket).\n      // `warlock:projection` strips a page's server exports — `loader` and\n      // friends — before React's babel pass sees the module, so Fast Refresh\n      // never registers a refresh boundary for an export that is not supposed\n      // to reach the browser at all.\n      //\n      // BEFORE `options.plugins` so an application can still override.\n      ...(await resolveReactFastRefreshPlugins({ webRoot: options.webRoot })),\n      ...(options.plugins ?? []),\n    ],\n    server: {\n      middlewareMode: true,\n      hmr: { server: options.hmrServer },\n      fs: {\n        // `<Scripts />` points the browser at the hydration client entry under\n        // `<webRoot>`: the published `esm/entry/index.mjs` when installed,\n        // or `src/entry/index.ts` in this checkout. A dependency normally\n        // lives under the app root's `node_modules`; when `@warlock.js/web` is\n        // LINKED — a monorepo checkout, `npm link`, or a `file:` dependency —\n        // its real path can sit outside every directory Vite allows by default\n        // and the request comes back `403 Restricted`.\n        //\n        // That failure is silent in the worst way: SSR has already produced\n        // the markup by the time the browser asks for the script, so the page\n        // renders perfectly, nothing is logged, and the only symptom is that\n        // no button ever works. Naming web's own root makes a linked install\n        // behave like an installed one.\n        //\n        // Every root is listed twice, as given and as `realpathSync` reports\n        // it, because Vite resolves a requested file to its REAL path before\n        // testing it against this list. Allowing the symlink alone therefore\n        // matches nothing — the 403 page prints the link that was allowed\n        // directly above the real path it rejected.\n        allow: [\n          ...new Set([\n            ...withRealPath(options.workspaceRoot),\n            ...withRealPath(options.appRoot),\n            ...withRealPath(options.webRoot),\n          ]),\n        ],\n      },\n    },\n    // Without an explicit target, esbuild assumes native (TC39) decorator\n    // support and leaves `@RegisterModel()`-style syntax untouched — but Vite's\n    // SSR module runner evaluates transformed code via `new AsyncFunction(...)`,\n    // which node has no native decorator support for. `es2022` downlevels them\n    // into helper calls. `jsx` is named explicitly rather than left to tsconfig\n    // discovery, because Vite matches a file against a tsconfig's `include` and\n    // `web/tsconfig.json`'s is narrow enough that most of `web/src` matched no\n    // config at all and fell back to the CLASSIC transform — emitting\n    // `React.createElement` into modules that import no `React` binding.\n    esbuild: { target: \"es2022\", jsx: \"automatic\" },\n    /**\n     * REACT MUST BE PRE-BUNDLED, and naming it here is the only thing that\n     * makes that happen for the framework's own client graph.\n     *\n     * `react-dom/client` is CommonJS. A browser cannot import a named export\n     * from it, so Vite's dep optimizer normally rewrites it into an ESM shim\n     * under `/node_modules/.vite/deps/`. Whether that rewrite happens is\n     * decided in `tryNodeResolve`, and one of the conditions that SKIPS it is\n     * `importer && isInNodeModules(importer)`\n     * (`vite/dist/node/chunks/config.js:32822`). Vite's reasoning is sound in\n     * general — a dependency's own internal imports are the optimizer's job,\n     * not the resolver's — but it is exactly wrong here:\n     *\n     *   `<Scripts />` points the browser at the hydration entry, and in an\n     *   INSTALLED app that entry is\n     *   `<app>/node_modules/@warlock.js/web/esm/entry/index.mjs`.\n     *   Every module it reaches is therefore inside `node_modules`, so every\n     *   bare import it makes takes the skip branch and is served as the raw\n     *   file with a `?v=<browserHash>` cache key bolted on.\n     *\n     * For `esm/**.mjs` that is harmless — they are already ESM. For\n     * `react-dom/client` it is fatal, and it is the whole defect: the browser\n     * receives `\"use strict\"; function checkDCE()…` and refuses the module\n     * with\n     *\n     *     SyntaxError: The requested module '/node_modules/react-dom/client.js?v=…'\n     *     does not provide an export named 'hydrateRoot'\n     *\n     * Nothing in the client runtime then runs at all: no hydration, so no\n     * `useState`, no Fast Refresh, and `<Link>` degrades to a full document\n     * load because the navigation listener was never attached. Measured on a\n     * published 5.0.2 install (fresh app, no symlinks): all four symptoms\n     * before this block, none after.\n     *\n     * `include` is the fix rather than `entries` because it does not depend\n     * on the scanner reaching the entry: an included id is pre-bundled at\n     * server start and `tryOptimizedResolve` matches it by NAME\n     * (`config.js:32633`) before `tryNodeResolve` — and that lookup has no\n     * importer condition, so a node_modules importer resolves to the shim\n     * like anyone else. Pointing `optimizeDeps.entries` at the hydration\n     * entry would not work: the scanner classifies a resolution inside\n     * `node_modules` as a dependency to externalize rather than a source to\n     * walk.\n     *\n     * All four names are listed even though `react` and `react/jsx-runtime`\n     * usually get discovered anyway — they are discovered only because the\n     * APP's own pages import them, which is a fact about the app and not\n     * something the framework may rely on. `react-dom/client` is imported by\n     * `client/hydrate-page.tsx` and by nothing a normal app writes, which is\n     * why it was the one that broke.\n     *\n     * This is INVISIBLE from the monorepo checkout: there the hydration entry\n     * resolves to `web/src/entry/index.ts`, a path with no `node_modules`\n     * segment, so the skip branch never fires and React optimizes normally.\n     * Canon: nothing measured inside the checkout is evidence about a\n     * published install.\n     */\n    optimizeDeps: {\n      include: [\"react\", \"react-dom\", \"react-dom/client\", \"react/jsx-runtime\"],\n      /**\n       * The SECOND instance problem, and the reason this is `exclude` and not\n       * another `include`.\n       *\n       * An app page's `import { Link } from \"@warlock.js/web\"` has an importer\n       * OUTSIDE `node_modules`, so it takes the opposite branch above and the\n       * whole package is pre-bundled into\n       * `/node_modules/.vite/deps/@warlock__js_web.js`. The hydration entry\n       * cannot reach that bundle — it is loaded by absolute path through\n       * `/@fs/` and its imports are relative, so they resolve to the raw\n       * `esm/*.mjs` files. The browser then holds TWO copies of every client\n       * module in this package: the app renders `<Link>` from the bundled one\n       * while the hydration entry publishes routes and mounts the document\n       * context on the raw one. Module-level state does not cross that line.\n       *\n       * `routing/route-table` survives it by accident — it keeps its table in\n       * a `Symbol.for` slot on `globalThis`, which is realm-wide — but\n       * `components/document-context` is a React context OBJECT, and two\n       * `createContext()` calls are two different contexts no provider can\n       * bridge.\n       *\n       * Excluding the package makes the app's import resolve to\n       * `esm/index.mjs` with the same `?v=` key the hydration entry's imports\n       * carry, so there is one instance again. It costs the pre-bundle (a\n       * handful of extra dev requests for files that are already valid ESM)\n       * and nothing else — the grep across every client-reachable module in\n       * this package finds exactly three bare imports, all of them React, all\n       * of them covered by `include` above.\n       */\n      exclude: [\"@warlock.js/web\"],\n    },\n    ssr: {\n      external: [...CORE_OPTIONAL_PEERS, ...WEB_OPTIONAL_PEERS, ...(options.ssrExternal ?? [])],\n      /**\n       * ONE `@warlock.js/web`, for the same reason `resolve.dedupe` below\n       * insists on one React — and it is invisible from inside this repo.\n       *\n       * Vite externalises `node_modules` in SSR by default, so an installed\n       * app gets TWO instances: the app's own `root.tsx` imports\n       * `@warlock.js/web` and Vite hands that off to Node, while the pipeline\n       * is loaded deliberately through `vite.ssrLoadModule(...)` and stays\n       * inside Vite's graph. `renderPage` then sets the document context on\n       * Vite's copy of `components/document-context`, and the app's `<Head/>`\n       * reads Node's copy, which has nothing in it:\n       *\n       *     <Head/> was rendered outside the page pipeline's document context\n       *\n       * Measured on a published 5.0.1 install: `GET /` 500 without this line,\n       * 200 with it (404 control still 404). In THIS checkout the package\n       * resolves to source under Vite's root, never through `node_modules`,\n       * so both paths land on one instance and the bug cannot reproduce.\n       * Canon `6b7ab838`.\n       */\n      noExternal: [\"@warlock.js/web\"],\n    },\n    resolve: {\n      // ONE React, resolved from the application. A linked `@warlock.js/web`\n      // resolves `react` out of its own tree while the app's pages resolve it\n      // out of theirs; two React instances share no hook dispatcher, and SSR\n      // dies on the first `useState` with \"Cannot read properties of null\".\n      // `dedupe` forces these package names to resolve from Vite's `root` —\n      // the app — whoever imported them, in the SSR environment as much as in\n      // the client one.\n      //\n      // Two names cover every entry point. Vite matches a deep import against\n      // the package it belongs to before consulting this list, so\n      // `react-dom/client`, `react/jsx-runtime` and `react/jsx-dev-runtime`\n      // are already deduped by `react-dom` and `react`; listing them\n      // separately would only add entries that can never match.\n      //\n      // Do NOT express this as a `resolve.alias` entry instead. Pointing a\n      // bare React specifier at a directory drags React's CommonJS entry into\n      // Vite's SSR module graph, and the dev server then dies at startup with\n      // \"module is not defined\" before it renders anything at all.\n      dedupe: [\"react\", \"react-dom\"],\n      alias: [\n        ...(options.resolveAlias ?? []),\n        // The app-tree convention `v5/app/tsconfig.json`'s own `paths` declare.\n        // Vite does not read tsconfig paths on its own and no\n        // `vite-tsconfig-paths` plugin is installed in this workspace.\n        //\n        // ONE definition, shared with the production build contribution\n        // (`web/src/build/contribution.ts`). These were two separate literals\n        // until 2026-08-24, and the production half simply did not have them —\n        // dev resolved `web/*` while the production client build died on the\n        // first page. Do not inline them back here.\n        ...appConventionAliases(options.appSrcRoot),\n      ],\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,MAAM,sBAAsB;CAE1B;CACA;CACA;CAEA;CACA;CAEA;CAEA;CAEA;CACA;CACA;CACA;CACA;CAEA;CAEA;CACA;CACA;AACF;;;;;;;;;;;;AAaA,MAAM,qBAAqB,CAAC,QAAQ,sBAAsB;;;;;;;;;;AAW1D,SAAS,aAAa,WAA6B;CACjD,IAAI;EACF,MAAM,WAAW,GAAG,aAAa,SAAS;EAE1C,OAAO,aAAa,YAAY,CAAC,SAAS,IAAI,CAAC,WAAW,QAAQ;CACpE,QAAQ;EACN,OAAO,CAAC,SAAS;CACnB;AACF;;;;;;;;;;;;;;AA8BA,eAAsB,6BACpB,SACuB;CACvB,OAAO;EACL,MAAM,QAAQ;EACd,SAAS;EACT,SAAS;GAOP,GAAG,QAAQ;GACX,GAAG,sBAAsB;IACvB,SAAS,QAAQ;IACjB,sBAAsB,EAAE,WAAW,QAAQ,oBAAoB,IAAI;GACrE,CAAC;GASD,GAAI,MAAM,+BAA+B,EAAE,SAAS,QAAQ,QAAQ,CAAC;GACrE,GAAI,QAAQ,WAAW,CAAC;EAC1B;EACA,QAAQ;GACN,gBAAgB;GAChB,KAAK,EAAE,QAAQ,QAAQ,UAAU;GACjC,IAAI,EAoBF,OAAO,CACL,GAAG,IAAI,IAAI;IACT,GAAG,aAAa,QAAQ,aAAa;IACrC,GAAG,aAAa,QAAQ,OAAO;IAC/B,GAAG,aAAa,QAAQ,OAAO;GACjC,CAAC,CACH,EACF;EACF;EAUA,SAAS;GAAE,QAAQ;GAAU,KAAK;EAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0D9C,cAAc;GACZ,SAAS;IAAC;IAAS;IAAa;IAAoB;GAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BvE,SAAS,CAAC,iBAAiB;EAC7B;EACA,KAAK;GACH,UAAU;IAAC,GAAG;IAAqB,GAAG;IAAoB,GAAI,QAAQ,eAAe,CAAC;GAAE;;;;;;;;;;;;;;;;;;;;;GAqBxF,YAAY,CAAC,iBAAiB;EAChC;EACA,SAAS;GAmBP,QAAQ,CAAC,SAAS,WAAW;GAC7B,OAAO,CACL,GAAI,QAAQ,gBAAgB,CAAC,GAU7B,GAAG,qBAAqB,QAAQ,UAAU,CAC5C;EACF;CACF;AACF"}

package/esm/vite/gate-a-resolve.d.mts

@@ -14,11 +14,12 @@ interface EnvironmentClassifierOptions {
   serverPackages?: Iterable<string>;
   /**
    * The app's project root. Defines what counts as APP SOURCE (see
-   * `isAppSourcePath`), which two rules depend on: rule 4 ("outside
-   * `$module/web/`") and rule 3's plain-`server/`-folder half. A dependency's
+   * `isAppSourcePath`), which rule 3's plain-`server/`-folder half depends on
+   * (rule 4, "outside `$module/web/`", drew on the same distinction before it
+   * was removed — see `ruleViolation`'s "RULE 4 IS GONE" note). A dependency's
    * own internal file layout — reached once resolution has left the app root,
-   * or through a `node_modules/` segment — is exempt from both, though rules
-   * 1, 2 and the `.server` half of rule 3 still apply to it. Defaults to
+   * or through a `node_modules/` segment — is exempt from it, though rules 1,
+   * 2 and the `.server` half of rule 3 still apply to it. Defaults to
    * `process.cwd()`, matching Vite's own default `root`.
    */
   appRoot?: string;

package/esm/vite/gate-a-resolve.mjs

@@ -1,3 +1,5 @@
+import { toPosix } from "../shared/to-posix.mjs";
+import { moduleKey } from "../shared/module-key.mjs";
 import { builtinModules } from "node:module";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
@@ -14,6 +16,10 @@ import { fileURLToPath } from "node:url";
 *      `externalizedBuiltins` for the one route that reaches a chunk
 *      without passing through `resolveId` at all. This rule is judged for
 *      EVERY importer, in or out of `GOVERNED_SCOPES` — see its note below.
+*   1b. The `server-only` npm package — a module importing it has declared
+*      itself server-side and cannot reach the browser. Judged by NAME, right
+*      after rule 1 and ahead of rule 2's scope check; see
+*      `BOUNDARY_DECLARATION_PACKAGES`.
 *   2. `@warlock.js/*` / `@mongez/*` packages whose `package.json` carries
 *      `"warlock": { "environment": "server" }`. An ABSENT marker is NOT a
 *      refusal — see the burden note on `createEnvironmentClassifier`. Judged
@@ -24,17 +30,16 @@ import { fileURLToPath } from "node:url";
 *   3. Server-only modules declared by FILE NAME: `*.server.ts` files,
 *      anything under a `.server/` directory, and — for the app's OWN source
 *      only — anything under a plain `server/` directory segment.
-*   4. Local modules outside a `$module/web/` (or `src/web/`) folder that are
-*      not a recognized universal surface (`*.page.tsx`, `layout.tsx`). The app
-*      root (`src/web/root.tsx`) is admitted by the `web/` FOLDER rule above,
-*      not by its name — see the note in `isRecognizedUniversalSurface`. A
-*      specifier that omits its file extension is judged on the file it will
-*      actually load, not on the extensionless string — see
-*      `completeLocalModulePath`.
-*   5. The `server-only` npm package — a module importing it has declared
-*      itself server-side and cannot reach the browser. Judged by NAME, right
-*      after rule 1 and ahead of rule 2's scope check; see
-*      `BOUNDARY_DECLARATION_PACKAGES`.
+*
+* A former rule 4 — refusing a local module outside a `$module/web/` folder
+* that was not a recognized universal surface — is GONE, deliberately. Owner
+* ruling 2026-08-24 (canon `10f6041c`, see `ruleViolation`'s "RULE 4 IS GONE"
+* note): it was a location PROXY for danger and refused genuinely universal
+* files for their address alone. The client boundary is now decided by the
+* import GRAPH — rules 1, 1b, 2 and 3 above — not by where a file sits. A
+* specifier that omits its file extension is judged on the file it will
+* actually load, not on the extensionless string — see
+* `completeLocalModulePath`.
 *
 * Gate B (inline secrets), Gate C (output verification) and the SSR mirror
 * rule for a future client-only rendering primitive is NOT this gate. Do not
@@ -202,9 +207,6 @@ function isNodeBuiltin(source) {
 	if (source.startsWith("node:")) return true;
 	return NODE_BUILTINS.has(source);
 }
-function normalize(filePath) {
-	return filePath.replace(/\\/g, "/");
-}
 /**
 * A plain `server/` path segment, tested against a path ALREADY made relative
 * to the app root — never against the absolute path. An app checked out at
@@ -213,55 +215,23 @@ function normalize(filePath) {
 const APP_SERVER_SEGMENT = /(^|\/)server(\/|$)/;
 function isServerFile(resolvedPath, appRoot) {
 	const bare = resolvedPath.split("?")[0];
-	const normalized = normalize(bare);
+	const normalized = toPosix(bare);
 	if (/\.server(\.[jt]sx?)?$/.test(normalized)) return true;
 	if (/(^|\/)\.server(\/|$)/.test(normalized)) return true;
 	if (isAppSourcePath(bare, appRoot)) {
-		if (APP_SERVER_SEGMENT.test(normalize(path.relative(appRoot, bare)))) return true;
+		if (APP_SERVER_SEGMENT.test(toPosix(path.relative(appRoot, bare)))) return true;
 	}
 	return false;
 }
 function isRecognizedUniversalSurface(resolvedPath) {
-	const normalized = normalize(resolvedPath);
+	const normalized = toPosix(resolvedPath);
 	const base = path.basename(normalized);
 	if (/\.page\.tsx?$/.test(base)) return true;
 	if (base === "layout.tsx" || base === "layout.ts") return true;
 	return false;
 }
 /**
-* A `web/` path segment, tested — like `APP_SERVER_SEGMENT` above and for the
-* same reason — against a path ALREADY made relative to the app root.
-*
-* Never against the absolute path, and this repo is its own proof: Gate A's
-* fixtures live at `@warlock.js/web/__tests__/vite/fixtures/gate-a/...`, so
-* EVERY absolute path under them contains a `/web/` segment belonging to the
-* package directory rather than to any app module. Matched absolutely, rule 4
-* would admit the whole fixture tree and cases 9 and 25-28 would all go green
-* for the wrong reason.
-*/
-const MODULE_WEB_SEGMENT = /(^|\/)web(\/|$)/;
-/**
-* Whether a judged path is anywhere INSIDE a module's `web/` folder — at any
-* depth, not merely directly inside one.
-*
-* The depth matters and used to be wrong: this asked for `/web/<one-segment>`,
-* so `src/web/middleware/base.middleware.ts` — two segments in — did not count
-* as being within `src/web/` at all. Nothing had noticed because the only way
-* to reach such a file is a relative import, and rule 4 was not judging those
-* (see `completeLocalModulePath`): a nested universal file escaped the rule
-* rather than being admitted by it, and the two are indistinguishable until the
-* escape is closed. Closing it without this would have turned the v5 app's own
-* `src/web/root.tsx` — which imports exactly that middleware — into a refusal.
-*
-* Rule 4's premise is a FOLDER ("outside a `$module/web/` folder"), and a
-* subfolder of `web/` is inside it. `web/components/`, `web/layouts/` and
-* `web/utils/` are ordinary app layout, not a way around the fence.
-*/
-function isWithinModuleWebFolder(resolvedPath, appRoot) {
-	return MODULE_WEB_SEGMENT.test(normalize(path.relative(appRoot, resolvedPath)));
-}
-/**
-* Rule 4's subject set: local files that CARRY CODE. Deliberately the same
+* Local files that CARRY CODE. Deliberately the same
 * shape as `PARSEABLE_MODULE_EXTENSIONS` below — one notion of "this is a
 * JS/TS module" for the whole file — which also picks up `.mts`/`.cts`, absent
 * from the earlier hand-spelled `/\.(tsx?|jsx?|mjs|cjs)$/`. `.mts` is a real
@@ -285,9 +255,9 @@ const LOCAL_MODULE_EXTENSIONS = /\.([cm]?[jt]sx?)$/;
 * escape hatch of exactly the shape this completion exists to close — the
 * judged path would gain a suffix and still be waved through. Pinned by case 32
 * in the spec. The order only decides which of two same-named files gets
-* judged, and every rule downstream (`isServerFile`, `isWithinModuleWebFolder`,
-* `isRecognizedUniversalSurface`) answers identically for `x.ts` and `x.js`, so
-* matching Vite is for least surprise rather than for correctness.
+* judged, and every rule downstream (`isServerFile`, `isRecognizedUniversalSurface`)
+* answers identically for `x.ts` and `x.js`, so matching Vite is for least
+* surprise rather than for correctness.
 */
 const IMPLICIT_MODULE_EXTENSIONS = [
 	".mjs",
@@ -372,10 +342,9 @@ function completeBareLocalModulePath(judgedPath) {
 }
 /**
 * Whether a judged path is the APP'S OWN SOURCE, as opposed to a dependency's
-* internals. This is Gate A's single definition of that boundary — rules 3
-* and 4 both call it, and `packageNameForFilePath` draws the same line for
-* Gate C. Two conditions, both already required by rule 4 before this was
-* extracted:
+* internals. This is Gate A's single definition of that boundary — rule 3
+* calls it, and `packageNameForFilePath` draws the same line for
+* Gate C. Two conditions:
 *
 *   - inside `appRoot` (a monorepo sibling or any other path resolution has
 *     left the app root for is that package's own business), and
@@ -391,7 +360,7 @@ function completeBareLocalModulePath(judgedPath) {
 function isAppSourcePath(resolvedPath, appRoot) {
 	if (!path.isAbsolute(resolvedPath)) return false;
 	if (!isInsideAppRoot(resolvedPath, appRoot)) return false;
-	return !normalize(resolvedPath).includes("/node_modules/");
+	return !toPosix(resolvedPath).includes("/node_modules/");
 }
 function isInsideAppRoot(resolvedPath, appRoot) {
 	const relative = path.relative(appRoot, resolvedPath);
@@ -408,14 +377,6 @@ const GOVERNED_SCOPE_MENTION = /@warlock\.js\/|@mongez\//;
 * `undefined` for any id containing `\0` — see its note).
 */
 const TYPE_ONLY_ERASED_ID = "\0warlock:type-only-erased";
-/**
-* Rollup module ids carry query suffixes (`?v=`, `?used`, ...) that differ
-* between the `transform` id and a later `importer`. Both sides key through
-* here so they agree.
-*/
-function moduleKey(id) {
-	return normalize(id.split("?")[0]);
-}
 function parserPluginsFor(id) {
 	return /\.[cm]?ts$/.test(moduleKey(id)) ? ["typescript"] : ["typescript", "jsx"];
 }
@@ -567,7 +528,7 @@ function ruleViolation(source, resolvedPath, importer, environmentOf, appRoot, i
 * than the one at the top of the tree.
 */
 function displayName(id) {
-	const normalized = normalize(id);
+	const normalized = toPosix(id);
 	const segments = normalized.split("node_modules/");
 	if (segments.length < 2) return path.basename(normalized);
 	return segments[segments.length - 1];
@@ -646,12 +607,12 @@ function createEnvironmentClassifier(options = {}) {
 	}
 	function packageNameForFilePath(absPath) {
 		if (absPath.includes("\0")) return void 0;
-		const normalized = normalize(path.resolve(absPath));
+		const normalized = toPosix(path.resolve(absPath));
 		const nodeModulesMatch = packageNameFromNodeModulesPath(normalized);
 		if (nodeModulesMatch) return nodeModulesMatch;
 		if (isInsideAppRoot(normalized, appRoot)) return void 0;
 		if (workspaceIndex) for (const [name, pkgJsonPath] of workspaceIndex.packageJsonByName) {
-			const root = `${normalize(path.dirname(pkgJsonPath))}/`;
+			const root = `${toPosix(path.dirname(pkgJsonPath))}/`;
 			if (normalized.startsWith(root)) return name;
 		}
 	}
@@ -884,5 +845,5 @@ function gateAResolve(options = {}) {
 }
 
 //#endregion
-export { createEnvironmentClassifier, gateAResolve, isAppSourcePath, isRecognizedUniversalSurface, isServerFile, isWithinModuleWebFolder };
+export { createEnvironmentClassifier, gateAResolve, isAppSourcePath, isRecognizedUniversalSurface, isServerFile };
 //# sourceMappingURL=gate-a-resolve.mjs.map