@pyreon/zero 0.15.0 → 0.18.0

package/src/vite-plugin.ts

@@ -14,6 +14,7 @@ import { resolveConfig } from './config'
 // Used in the dev-mode SSR catch handler to convert loader-thrown
 // `redirect()` errors into real HTTP redirects (302/307/308).
 import { getRedirectInfo } from '@pyreon/router'
+import { matchPattern } from './entry-server'
 
 /**
  * Scan node_modules/@pyreon/ to discover all installed Pyreon packages.
@@ -46,7 +47,6 @@ function resolveNestedPackage(root: string, name: string): string | undefined {
   if (existsSync(nested)) return nested
   return undefined
 }
-import { matchPattern } from "./entry-server";
 import { renderErrorOverlay } from "./error-overlay";
 import {
 	generateMiddlewareModule,
@@ -54,6 +54,7 @@ import {
 	scanRouteFiles,
 	scanRouteFilesWithExports,
 } from "./fs-router";
+import { expandRoutesForLocales } from "./i18n-routing";
 import { render404Page } from "./not-found";
 import { ssgPlugin } from "./ssg-plugin";
 import type { ZeroConfig } from "./types";
@@ -67,6 +68,49 @@ const RESOLVED_VIRTUAL_MIDDLEWARE_ID = `\0${VIRTUAL_MIDDLEWARE_ID}`;
 const VIRTUAL_API_ROUTES_ID = "virtual:zero/api-routes";
 const RESOLVED_VIRTUAL_API_ROUTES_ID = `\0${VIRTUAL_API_ROUTES_ID}`;
 
+/**
+ * Per-plugin-instance storage for the user-supplied ZeroConfig. Lets
+ * downstream consumers (e.g. `@pyreon/zero-cli`'s `build` command, which
+ * loads the user's `vite.config.ts` and inspects its plugin list)
+ * recover the original config without us attaching internal state to
+ * the public Plugin object via an underscore-prefixed property.
+ *
+ * Exported via `getZeroPluginConfig(plugin)` so the WeakMap itself
+ * stays an implementation detail — callers can't enumerate or mutate
+ * the table, only read by Plugin identity.
+ */
+const zeroPluginConfigMap = new WeakMap<Plugin, ZeroConfig>();
+
+/**
+ * Retrieve the `ZeroConfig` that was passed to `zeroPlugin(userConfig)`
+ * when the plugin was created. Returns `undefined` if the argument
+ * isn't a recognized pyreon-zero main plugin instance.
+ */
+export function getZeroPluginConfig(plugin: Plugin): ZeroConfig | undefined {
+	return zeroPluginConfigMap.get(plugin);
+}
+
+/**
+ * Detects `--port` / `--port=N` / `-p N` / `-p=N` in `process.argv`.
+ * Used by the plugin's `config()` hook to decide whether to apply the
+ * default port — when the CLI was invoked with `--port`, the plugin
+ * must skip its default so the CLI flag wins (see the comment at the
+ * port-handling block in `zeroPlugin()` for the full precedence model).
+ *
+ * Exported for testing only (the plugin uses it internally).
+ *
+ * @internal
+ */
+export function argvHasPortFlag(argv: readonly string[] = process.argv): boolean {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--port" || a === "-p") return true;
+		if (a !== undefined && (a.startsWith("--port=") || a.startsWith("-p=")))
+			return true;
+	}
+	return false;
+}
+
 /**
  * Zero Vite plugin — adds file-based routing and zero-config conventions
  * on top of @pyreon/vite-plugin.
@@ -85,10 +129,9 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 	let routesDir: string;
 	let root: string;
 
-	const mainPlugin: Plugin & { _zeroConfig: ZeroConfig } = {
+	const mainPlugin: Plugin = {
 		name: "pyreon-zero",
 		enforce: "pre",
-		_zeroConfig: userConfig,
 
 		configResolved(resolvedConfig) {
 			root = resolvedConfig.root;
@@ -109,9 +152,30 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 					//   • lazy() for routes that only export `default` (best code splitting)
 					//   • Direct mod.loader/.guard/.meta access for routes with metadata
 					//   • No spurious IMPORT_IS_UNDEFINED warnings from Rolldown
-					const routes = await scanRouteFilesWithExports(routesDir, config.mode);
+					const baseRoutes = await scanRouteFilesWithExports(routesDir, config.mode);
+					// PR H — fan routes into per-locale variants when `i18n` is
+					// configured. No-op when unset; identity-returns the input
+					// otherwise so existing apps see byte-identical output.
+					const routes = config.i18n
+						? expandRoutesForLocales(baseRoutes, config.i18n)
+						: baseRoutes;
+					// SSG mode: lazy() route splitting by default (parity with
+					// SSR/SPA). Opt-out via `ssg.splitChunks: false` for tiny
+					// sites that prefer single-chunk + instant navigation.
+					//
+					// Pre-2026-Q3: SSG was hardcoded to `staticImports: true`
+					// (bundle everything). Trade-off was instant post-hydration
+					// nav, but the initial bundle grew linearly with route
+					// count — a 50-route docs site shipped all 50 route
+					// components on first paint. Lazy splitting (now the
+					// default for SSG) fixes that: only the landing route +
+					// deps load up front, the rest fetch on navigation. See
+					// `ssg.splitChunks` JSDoc in types.ts for the crossover-
+					// point rationale.
+					const ssgSplitDisabled =
+						config.mode === "ssg" && config.ssg?.splitChunks === false;
 					return generateRouteModuleFromRoutes(routes, routesDir, {
-						staticImports: config.mode === 'ssg',
+						staticImports: ssgSplitDisabled,
 					});
 				} catch (_err) {
 					return `export const routes = []`;
@@ -203,10 +267,10 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 					renderSsr(server, root, req.originalUrl ?? pathname, pathname, webReq).then(
 						(result) => {
 							if (result === null) return next();
-							res.statusCode = 200;
+							res.statusCode = result.status;
 							res.setHeader("Content-Type", "text/html; charset=utf-8");
-							res.setHeader("Content-Length", Buffer.byteLength(result));
-							res.end(result);
+							res.setHeader("Content-Length", Buffer.byteLength(result.html));
+							res.end(result.html);
 						},
 						(err: unknown) => {
 							// Loader-thrown `redirect()` — convert to a real HTTP redirect
@@ -327,15 +391,15 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 			// Discover all @pyreon/* packages installed in node_modules.
 			// The "bun" export condition points to TS source — esbuild's
 			// dep optimizer would compile them with the wrong JSX runtime.
-			const root = viteUserConfig.root ?? process.cwd()
-			const pyreonExclude = scanPyreonPackages(root)
+			const cwd = viteUserConfig.root ?? process.cwd()
+			const pyreonExclude = scanPyreonPackages(cwd)
 
 			// `@pyreon/runtime-server` is only imported by zero's dev SSR
 			// middleware and the production server entry — apps rarely list it
 			// as a direct dep. Resolve it to the copy nested under zero so
 			// `ssrLoadModule("@pyreon/runtime-server")` works uniformly.
 			const runtimeServerAlias = resolveNestedPackage(
-				root,
+				cwd,
 				"@pyreon/runtime-server",
 			)
 
@@ -361,16 +425,51 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 				optimizeDeps: {
 					exclude: pyreonExclude,
 				},
-				// Only set the port when the user explicitly provided one in
-				// `zero({ port: N })`. Without this guard, the plugin always
-				// returned `server: { port: 3000 }` which overrode Vite's CLI
-				// `--port` flag and made multi-example dev impossible — every
-				// example tried to bind 3000 even when launched with
-				// `vite --port 5173`. Surfaced when wiring up the playwright
-				// e2e suite.
-				...(userConfig.port !== undefined
-					? { server: { port: config.port } }
-					: {}),
+				// Port handling — the zero-canonical default is 3000 (matches
+				// `zero dev` / `zero preview` / the runtime adapter, and
+				// matches Next.js / Remix / Astro convention).
+				//
+				// Apply the default UNLESS Vite's CLI was invoked with
+				// `--port`/`-p` (in which case the CLI flag must win — see
+				// memory: vite cli port doesnt override plugin). PR #579
+				// proved this empirically: returning `server: { port: 3000 }`
+				// unconditionally clobbered `vite --port 517N --strictPort`
+				// in the e2e playwright config and every webServer timed
+				// out. argv detection here lets the CLI win at the source.
+				//
+				// Precedence (CLI > user vite.config > zero({port}) > 3000):
+				//   1. `vite --port N` → argvHasPortFlag() === true → plugin
+				//      omits `server.port` entirely → CLI value wins
+				//   2. User `vite.config.ts server: { port: N }` → user
+				//      config beats plugin in Vite's merge order
+				//   3. `zero({ port: N })` → resolved into `config.port`
+				//   4. Default 3000 — when no other source set a port
+				//
+				// `process.argv` is populated by the time Vite invokes the
+				// plugin's config() hook (Vite calls plugins synchronously
+				// during CLI bootstrap before applying inline overrides).
+				...(userConfig.port === undefined && argvHasPortFlag()
+					? {}
+					: { server: { port: config.port } }),
+				// Propagate `zero({ base })` to Vite's `base` config — that's
+				// what controls asset URL rewriting in the built HTML/JS
+				// (`<script src="/blog/assets/…">`). Pre-fix this was a
+				// typed-but-unimplemented field: `__ZERO_BASE__` was defined
+				// as a Vite global but no consumer existed, AND Vite's own
+				// `base` had to be set manually in vite.config.ts. Setting
+				// it here makes `zero({ base: '/blog/' })` the canonical
+				// single-source-of-truth surface; the value flows through
+				// to (a) Vite's HTML/asset URL rewriter, (b) `createRouter`
+				// via `__ZERO_BASE__` in `startClient` / `createApp`, (c)
+				// the SSG entry's `createApp({ base })` call.
+				//
+				// Vite's config-merge semantics: plugin-returned config is
+				// the BASE; user's `vite.config.ts` top-level overrides.
+				// So a user who sets BOTH `zero({ base: '/blog/' })` AND
+				// `vite.config.base: '/foo/'` gets the latter — the user's
+				// explicit override wins. The default `/` is a no-op
+				// (matches Vite's default), so always-setting is safe.
+				base: config.base,
 				define: {
 					__ZERO_MODE__: JSON.stringify(config.mode),
 					__ZERO_BASE__: JSON.stringify(config.base),
@@ -379,6 +478,12 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 		},
 	};
 
+	// Stash the original user config keyed by plugin identity so the CLI
+	// (which loads vite.config.ts and inspects the plugin list) can
+	// recover it via `getZeroPluginConfig(plugin)` without us hanging a
+	// `_`-prefixed property off the public Plugin object.
+	zeroPluginConfigMap.set(mainPlugin, userConfig);
+
 	// SSG mode auto-wires the static-site generation hook. Other modes get
 	// just the main plugin. The SSG plugin internally no-ops when
 	// `mode !== 'ssg'`, but skipping it entirely keeps the plugin chain
@@ -488,13 +593,24 @@ async function dispatchApiRoute(
 }
 
 /**
- * Check if the requested path matches any route. If not, render a 404 page.
- * Returns true if the 404 was handled (response sent), false otherwise.
+ * Static-page 404 fallback for apps WITHOUT `_404.tsx` in the routes tree.
  *
- * In dev mode, the _404.tsx component cannot be SSR-rendered because
- * the compiler emits _tpl() calls that require `document`. Instead,
- * we return a static 404 page. The actual component rendering happens
- * on the client side when the SPA loads.
+ * For `mode: 'ssr'` apps with `_404.tsx`, the SSR middleware's `renderSsr`
+ * routes unmatched URLs through the router-driven path (PR L5 + M1.2) — that
+ * produces a layout-wrapped 404 with HTTP status 404, never reaching here.
+ * This function is the LEGACY fallback that fires only when:
+ *   - The app is in `mode: 'spa'` / `mode: 'ssg'` (no dev SSR middleware), OR
+ *   - The app has no reachable `notFoundComponent` in its routes tree (so the
+ *     SSR middleware's `resolveRoute` returns matched: [] and falls through).
+ *
+ * Returns true if the 404 was handled (response sent), false if the path
+ * actually matches a route (caller continues to next middleware).
+ *
+ * Pre-M1.2 a stale comment claimed `_404.tsx` "cannot be SSR-rendered because
+ * the compiler emits _tpl() calls that require document". That was wrong — the
+ * SSR runtime renders compiler-emitted components fine via `renderToString`
+ * (no document needed). The static fallback exists for backward compat with
+ * apps that don't ship `_404.tsx`, not because SSR-rendering it is impossible.
  */
 async function handle404(
 	server: import("vite").ViteDevServer,
@@ -510,10 +626,11 @@ async function handle404(
 		return false; // Route matches — not a 404
 	}
 
-	// No route matched — return a 404.
-	// In dev, we return a static page since the compiler emits _tpl() calls
-	// that require document (unavailable in SSR). The _404.tsx component
-	// renders on the client side after hydration.
+	// No route matched + no `_404.tsx` reachable — emit a minimal static page
+	// so the user gets SOMETHING. Apps that want branded 404s should add
+	// `_404.tsx` to their routes tree (canonical pattern); the SSR middleware
+	// then routes through the router-driven path with layout chrome instead
+	// of landing here.
 	const html = await render404Page(undefined);
 
 	res.statusCode = 404;
@@ -541,18 +658,12 @@ async function renderSsr(
 	originalUrl: string,
 	pathname: string,
 	req?: Request,
-): Promise<string | null> {
-	// Pattern check FIRST — otherwise SSR would try (and likely crash) on
-	// asset paths that happened to accept text/html (e.g. curl-style).
+): Promise<{ html: string; status: number } | null> {
 	const routesMod = await server.ssrLoadModule(VIRTUAL_ROUTES_ID);
 	const routes = routesMod.routes as Array<{
 		path?: string;
 		children?: unknown[];
 	}>;
-	const patterns = flattenRoutePatterns(routes);
-	if (!patterns.some((pattern) => matchPattern(pattern, pathname))) {
-		return null;
-	}
 
 	// Read + transform index.html (Vite injects the HMR client / JSX prelude).
 	let template = await readFile(join(root, "index.html"), "utf-8");
@@ -565,7 +676,7 @@ async function renderSsr(
 	// `@pyreon/runtime-server` isn't a direct dep of most apps, so zero's
 	// `config()` hook registers an alias that points it at the copy under
 	// zero's own `node_modules` — same path → same Vite module → same instance.
-	const [core, headPkg, headSsr, routerPkg, runtimeServer] = await Promise.all(
+	const [core, _headPkg, headSsr, routerPkg, runtimeServer] = await Promise.all(
 		[
 			server.ssrLoadModule("@pyreon/core") as Promise<
 				typeof import("@pyreon/core")
@@ -620,8 +731,25 @@ async function renderSsr(
 	// `preload` loads lazy route components AND runs loaders for `pathname` so
 	// the synchronous render pass produces final HTML — no loading fallbacks,
 	// no `useLoaderData() === undefined`.
+	//
+	// M1.2 — Unmatched URLs no longer bail to a static 404 page. The router's
+	// `resolveRoute` (PR L5) walks the route tree and, if a parent layout has
+	// `notFoundComponent` AND the URL is under that layout's prefix, builds a
+	// synthetic chain `[...ancestorLayouts, syntheticLeaf]` with
+	// `isNotFound: true`. The render then produces 404 HTML INSIDE the
+	// layout's chrome. If the routes tree has no reachable `notFoundComponent`,
+	// `matched` stays empty — fall through to `handle404` for the static
+	// fallback (preserves backward compat for apps without `_404.tsx`).
 	await routerInst.preload(pathname, req);
 
+	const resolved = routerInst.currentRoute() as
+		| { matched?: unknown[]; isNotFound?: boolean }
+		| undefined;
+	if (!resolved?.matched || resolved.matched.length === 0) {
+		return null;
+	}
+	const status = resolved.isNotFound === true ? 404 : 200;
+
 	return runtimeServer.runWithRequestContext(async () => {
 		const app = core.h(App as Parameters<typeof core.h>[0], null);
 
@@ -630,14 +758,16 @@ async function renderSsr(
 			routerInst as Parameters<typeof routerPkg.serializeLoaderData>[0],
 		);
 		const hasData = loaderData && Object.keys(loaderData).length > 0;
+		// M2.2 — safe serializer (parity with production handler / SSG entry).
 		const loaderScript = hasData
-			? `<script>window.__PYREON_LOADER_DATA__=${JSON.stringify(loaderData).replace(/<\//g, "<\\/")}</script>`
+			? `<script>window.__PYREON_LOADER_DATA__=${routerPkg.stringifyLoaderData(loaderData)}</script>`
 			: "";
 
-		return template
+		const html = template
 			.replace("<!--pyreon-head-->", head)
 			.replace("<!--pyreon-app-->", appHtml)
 			.replace("<!--pyreon-scripts-->", loaderScript);
+		return { html, status };
 	});
 }