@warlock.js/web 5.4.0 → 5.6.0

package/esm/server/web-connector.mjs

@@ -5,9 +5,9 @@ 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";
@@ -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,
@@ -335,7 +261,8 @@ var WebConnector = class extends BaseConnector {
 			appSrcRoot: paths.appSrcRoot,
 			appFile: paths.appFile,
 			hydrationClientModuleUrl: this.resolveHydrationClientModuleUrl(paths.webRoot),
-			stylesheetUrls: webServerSsr.devStylesheetUrls(paths.appRoot, paths.appFile)
+			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
+		}));
 	}
 };