npm - @pyreon/zero - Versions diffs - 0.19.0 → 0.21.0 - Mend

@pyreon/zero 0.19.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +1 -1
package/lib/{api-routes-CQiOi3q5.js → api-routes-CMsLztoj.js} +1 -1
package/lib/favicon.js +120 -6
package/lib/{fs-router-BVY4lTH_.js → fs-router-Bacdhsq-.js} +2 -2
package/lib/image-plugin.js +14 -7
package/lib/image-types.js +0 -0
package/lib/server.js +2741 -144
package/lib/types/favicon.d.ts +34 -4
package/lib/types/i18n-routing.d.ts +2 -4
package/lib/types/image-types.d.ts +55 -0
package/lib/types/index.d.ts +3 -5
package/lib/types/link.d.ts +2 -4
package/lib/types/server.d.ts +19 -7
package/lib/types/theme.d.ts +1 -2
package/package.json +15 -10
package/src/favicon.ts +189 -12
package/src/image-plugin.ts +59 -14
package/src/image-types.ts +60 -0
package/lib/vite-plugin-8TXXFqdP.js +0 -2491
package/src/image-types.d.ts +0 -51

package/lib/server.js CHANGED Viewed

@@ -1,9 +1,218 @@
-import { _ as render404Page, a as detectLocaleFromHeader, c as vercelAdapter, d as netlifyAdapter, f as cloudflareAdapter, g as createServer, h as resolveConfig, i as createLocaleContext, l as staticAdapter, m as defineConfig, o as i18nRouting, p as bunAdapter, r as zeroPlugin, s as resolveAdapter, t as getZeroPluginConfig, u as nodeAdapter, v as createApp } from "./vite-plugin-8TXXFqdP.js";
-import { i as generateRouteModule, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles, t as filePathToUrlPath } from "./fs-router-BVY4lTH_.js";
-import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import { readFile, rm, writeFile } from "node:fs/promises";
+import { t as __exportAll } from "./rolldown-runtime-CjeV3_4I.js";
+import { i as matchApiRoute, n as createApiMiddleware, r as generateApiRouteModule } from "./api-routes-CMsLztoj.js";
+import { a as generateRouteModuleFromRoutes, c as scanRouteFilesWithExports, i as generateRouteModule, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles, t as filePathToUrlPath } from "./fs-router-Bacdhsq-.js";
+import { Fragment, createContext, h } from "@pyreon/core";
+import { HeadProvider } from "@pyreon/head";
+import { RouterProvider, RouterView, createRouter, getRedirectInfo } from "@pyreon/router";
+import { createHandler } from "@pyreon/server";
+import { renderToString } from "@pyreon/runtime-server";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { signal } from "@pyreon/reactivity";
+import { pathToFileURL } from "node:url";
+//#region src/app.ts
+/**
+* Create a full Zero app — assembles router, head provider, and root layout.
+*
+* Used internally by entry-server and entry-client.
+*/
+function createApp(options) {
+	const router = createRouter({
+		routes: options.routes,
+		mode: options.routerMode ?? "history",
+		...options.url ? { url: options.url } : {},
+		...options.base && options.base !== "/" ? { base: options.base } : {},
+		scrollBehavior: "top"
+	});
+	const hasLayoutInRoutes = options.layout !== void 0 && options.routes.some((r) => r.component === options.layout);
+	if (hasLayoutInRoutes && process.env.NODE_ENV !== "production") console.warn("[Pyreon] `createApp({ layout })` was passed a component that is ALSO a parent route in the matched chain (likely an fs-router `_layout.tsx`). The explicit `layout` option is being ignored to prevent double-mount. Remove the `layout` argument from `createApp`/`startClient` — the fs-router-emitted route handles it.");
+	const Layout = hasLayoutInRoutes ? DefaultLayout : options.layout ?? DefaultLayout;
+	function App() {
+		return h(HeadProvider, null, h(RouterProvider, { router }, h(Layout, null, h(RouterView, null))));
+	}
+	return {
+		App,
+		router
+	};
+}
+function DefaultLayout(props) {
+	return h(Fragment, null, ...Array.isArray(props.children) ? props.children : [props.children]);
+}
+//#endregion
+//#region src/not-found.ts
+const DEFAULT_404_BODY = "<h1>404 — Not Found</h1><p>The page you requested does not exist.</p>";
+/**
+* Render a 404 component to a full HTML string.
+* If no component is provided, returns a default 404 page.
+*/
+async function render404Page(component, template) {
+	let body;
+	if (component) body = await renderToString(h(component, null));
+	else body = DEFAULT_404_BODY;
+	if (template?.includes("<!--pyreon-app-->")) return template.replace("<!--pyreon-app-->", body);
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>404 — Not Found</title>
+</head>
+<body>
+  ${body}
+</body>
+</html>`;
+}
+//#endregion
+//#region src/entry-server.ts
+/**
+* Create a middleware that dispatches per-route middleware based on URL pattern matching.
+*/
+function createRouteMiddlewareDispatcher(entries) {
+	return async (ctx) => {
+		for (const entry of entries) if (matchPattern(entry.pattern, ctx.path)) {
+			const mw = Array.isArray(entry.middleware) ? entry.middleware : [entry.middleware];
+			for (const fn of mw) {
+				const result = await fn(ctx);
+				if (result) return result;
+			}
+		}
+	};
+}
+/**
+* URL pattern matcher supporting :param and :param* segments.
+*
+* Rules:
+* - Static segments must match exactly
+* - `:param` matches a single path segment
+* - `:param*` matches all remaining segments (must be last, and path must
+*   have matched all preceding segments)
+* - Path length must match pattern length (unless catch-all)
+*/
+function matchPattern(pattern, path) {
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = path.split("/").filter(Boolean);
+	for (let i = 0; i < patternParts.length; i++) {
+		const pp = patternParts[i];
+		if (pp.endsWith("*")) return i <= pathParts.length;
+		if (i >= pathParts.length) return false;
+		if (pp.startsWith(":")) continue;
+		if (pp !== pathParts[i]) return false;
+	}
+	return patternParts.length === pathParts.length;
+}
+/**
+* Create the SSR request handler for production.
+*
+* @example
+* import { routes } from "virtual:zero/routes"
+* import { routeMiddleware } from "virtual:zero/route-middleware"
+* import { createServer } from "@pyreon/zero"
+*
+* export default createServer({ routes, routeMiddleware, apiRoutes })
+*/
+function createServer(options) {
+	const config = options.config ?? {};
+	const allMiddleware = [];
+	if (options.apiRoutes?.length) allMiddleware.push(createApiMiddleware(options.apiRoutes));
+	if (options.routeMiddleware?.length) allMiddleware.push(createRouteMiddlewareDispatcher(options.routeMiddleware));
+	allMiddleware.push(...config.middleware ?? []);
+	allMiddleware.push(...options.middleware ?? []);
+	const { App } = createApp({
+		routes: options.routes,
+		routerMode: "history",
+		...config.base && config.base !== "/" ? { base: config.base } : {}
+	});
+	const handler = createHandler({
+		App,
+		routes: options.routes,
+		middleware: allMiddleware,
+		mode: config.ssr?.mode ?? "string",
+		...options.template ? { template: options.template } : {},
+		...options.clientEntry ? { clientEntry: options.clientEntry } : {}
+	});
+	if (!options.notFoundComponent) return handler;
+	const NotFound = options.notFoundComponent;
+	const hasRouteTreeNotFound = routeTreeHasNotFound(options.routes);
+	return async (req) => {
+		if (hasRouteTreeNotFound) return handler(req);
+		const pathname = new URL(req.url).pathname;
+		if (!routePatternsCache(options.routes).some((p) => matchPattern(p, pathname))) {
+			const fullHtml = await render404Page(NotFound, options.template);
+			return new Response(fullHtml, {
+				status: 404,
+				headers: { "Content-Type": "text/html; charset=utf-8" }
+			});
+		}
+		return handler(req);
+	};
+}
+/** Walk the route tree looking for any record with a `notFoundComponent`. */
+function routeTreeHasNotFound(routes) {
+	for (const r of routes) {
+		if (typeof r.notFoundComponent === "function") return true;
+		if (r.children && routeTreeHasNotFound(r.children)) return true;
+	}
+	return false;
+}
+/** Lazy cache of flattened patterns — only computed if legacy fallback fires. */
+const _routePatternsCache = /* @__PURE__ */ new WeakMap();
+function routePatternsCache(routes) {
+	const cached = _routePatternsCache.get(routes);
+	if (cached) return cached;
+	const out = flattenRoutePatterns$1(routes);
+	_routePatternsCache.set(routes, out);
+	return out;
+}
+/** Extract all URL patterns from a nested route tree. */
+function flattenRoutePatterns$1(routes, prefix = "") {
+	const patterns = [];
+	for (const route of routes) {
+		const fullPath = route.path === "/" && prefix ? prefix : `${prefix}${route.path}`;
+		patterns.push(fullPath);
+		if (route.children) patterns.push(...flattenRoutePatterns$1(route.children, fullPath));
+	}
+	return patterns;
+}
+//#endregion
+//#region src/config.ts
+/**
+* Define a Zero configuration.
+* Used in `zero.config.ts` at the project root.
+*
+* @example
+* import { defineConfig } from "@pyreon/zero/config"
+*
+* export default defineConfig({
+*   mode: "ssr",
+*   ssr: { mode: "stream" },
+*   port: 3000,
+* })
+*/
+function defineConfig(config) {
+	return config;
+}
+/** Merge user config with defaults. */
+function resolveConfig(userConfig = {}) {
+	return {
+		mode: "ssr",
+		base: "/",
+		port: 3e3,
+		adapter: "node",
+		...userConfig,
+		ssr: {
+			mode: "string",
+			...userConfig.ssr
+		}
+	};
+}
+//#endregion
 //#region src/isr.ts
 /**
 * In-memory ISR cache with stale-while-revalidate semantics.
@@ -102,169 +311,2477 @@ function createISRHandler(handler, config) {
 				...headers,
 				"x-isr-cache": "BYPASS"
 			}
-		});
-		set(key, {
-			html,
-			headers,
-			timestamp: Date.now()
-		});
-		return new Response(html, {
-			status: 200,
-			headers: {
-				...headers,
-				"content-type": "text/html; charset=utf-8",
-				"x-isr-cache": "MISS"
+		});
+		set(key, {
+			html,
+			headers,
+			timestamp: Date.now()
+		});
+		return new Response(html, {
+			status: 200,
+			headers: {
+				...headers,
+				"content-type": "text/html; charset=utf-8",
+				"x-isr-cache": "MISS"
+			}
+		});
+	};
+}
+//#endregion
+//#region src/vercel-revalidate-handler.ts
+/**
+* M3.1 — Drop-in Vercel revalidate webhook handler.
+*
+* Pre-M3.1 the `vercelAdapter.revalidate(path)` (PR I) POSTed to
+* `/api/_pyreon-revalidate?path=...&secret=...` — a CONVENTION that users
+* had to implement themselves. This helper scaffolds the convention:
+*
+*     // src/routes/api/_pyreon-revalidate.ts (or `pages/api/...` in
+*     // Next-style apps deployed to Vercel)
+*     export { vercelRevalidateHandler as default } from '@pyreon/zero/server'
+*
+* The handler validates the secret query param against
+* `VERCEL_REVALIDATE_TOKEN`, validates the path is in the build-time
+* revalidate manifest, and calls Vercel's `res.revalidate(path)` API.
+*
+* Returns a standard `(req: Request) => Response` Web API handler — works
+* with Vercel Edge functions, Node serverless functions (via Vercel's
+* `@vercel/node` adapter that bridges Node `req`/`res` to Web standard
+* fetch shapes), and the in-process `mode: 'ssr'` runtime.
+*
+* @example
+* // src/routes/api/_pyreon-revalidate.ts
+* import { vercelRevalidateHandler } from '@pyreon/zero/server'
+*
+* export const POST = vercelRevalidateHandler({
+*   // Optional — defaults to reading `_pyreon-revalidate.json` from cwd.
+*   manifestPath: './dist/_pyreon-revalidate.json',
+* })
+*
+* @example
+* // Custom revalidate impl (e.g. for a self-hosted Pyreon SSR runtime
+* // that wants build-time revalidate behavior without Vercel's
+* // `res.revalidate()` API):
+* export const POST = vercelRevalidateHandler({
+*   onRevalidate: async (path) => {
+*     // Clear your in-process ISR cache, emit a metrics event, etc.
+*     await myCache.invalidate(path)
+*   },
+* })
+*/
+/**
+* Create the Web-standard request handler. Reads the manifest once on first
+* invocation (cached in-process) so repeated revalidations don't re-read the
+* file. Manifest read failures cache the failure too — until next process
+* restart, all requests get the same 500 response (signals deploy-time misconfig).
+*/
+function vercelRevalidateHandler(options = {}) {
+	const manifestPath = options.manifestPath ?? "./dist/_pyreon-revalidate.json";
+	const secretEnvVar = options.secretEnvVar ?? "VERCEL_REVALIDATE_TOKEN";
+	let cache = null;
+	return async function handler(req) {
+		if (req.method !== "POST") return new Response(`Method ${req.method} not allowed`, { status: 405 });
+		const url = new URL(req.url);
+		const path = url.searchParams.get("path");
+		const secret = url.searchParams.get("secret");
+		if (!path || !secret) return new Response("Bad Request: missing path or secret", { status: 400 });
+		const expected = process.env[secretEnvVar];
+		if (!expected) return new Response(`Server misconfigured: ${secretEnvVar} env var not set`, { status: 500 });
+		if (secret !== expected) return new Response("Forbidden: invalid secret", { status: 403 });
+		if (cache === null) try {
+			const fileContent = await readFile(resolve(process.cwd(), manifestPath), "utf-8");
+			const parsed = JSON.parse(fileContent);
+			if (typeof parsed?.revalidate !== "object" || parsed.revalidate === null) throw new Error(`Malformed revalidate manifest at ${manifestPath}: missing or non-object \`revalidate\` field`);
+			cache = { manifest: parsed };
+		} catch (err) {
+			cache = { error: err };
+		}
+		if ("error" in cache) return new Response(`Server misconfigured: revalidate manifest at ${manifestPath} unreadable or malformed`, { status: 500 });
+		if (!Object.prototype.hasOwnProperty.call(cache.manifest.revalidate, path)) return new Response(`Path "${path}" not in revalidate manifest`, { status: 404 });
+		if (options.onRevalidate) try {
+			await options.onRevalidate(path);
+		} catch (err) {
+			return new Response(`Revalidation failed for "${path}": ${err instanceof Error ? err.message : String(err)}`, { status: 500 });
+		}
+		return new Response(JSON.stringify({
+			revalidated: true,
+			path
+		}), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	};
+}
+/**
+* Reset the in-process manifest cache. Test-only — production code never
+* reaches this. Used by unit tests to exercise the "manifest changed
+* between requests" path without spinning up a new handler.
+* @internal
+*/
+function _resetVercelRevalidateHandlerCache(handler) {}
+//#endregion
+//#region src/adapters/validate.ts
+/**
+* Validate that SSR-mode adapter build inputs exist before copying.
+* Throws with a clear error message if directories are missing.
+*
+* SSG-mode passes through unchanged — the SSG branch doesn't need a
+* server entry (every page is prerendered) and `outDir` IS the dist
+* directory the SSG plugin already populated. Validating it here would
+* be redundant.
+*
+* @internal
+*/
+async function validateBuildInputs(options) {
+	if (options.kind !== "ssr") return;
+	const { existsSync } = await import("node:fs");
+	if (!existsSync(options.clientOutDir)) throw new Error(`[Pyreon] Client build output not found: ${options.clientOutDir}. Run "vite build" first.`);
+	if (!existsSync(options.serverEntry)) throw new Error(`[Pyreon] Server entry not found: ${options.serverEntry}. Run "vite build --ssr" first.`);
+}
+//#endregion
+//#region src/adapters/bun.ts
+/**
+* Bun adapter — generates a standalone Bun.serve() entry.
+*
+* **SSG mode (PR J)**: no-op. Bun adapter exists for serving the SSR
+* runtime; SSG output is already complete static HTML — serve it with
+* any static-file server (`bun preview` / `bunx serve` / nginx / Caddy).
+* Use `staticAdapter()` if you want explicit SSG semantics.
+*/
+function bunAdapter() {
+	return {
+		name: "bun",
+		async build(options) {
+			if (options.kind === "ssg") return;
+			await validateBuildInputs(options);
+			const { writeFile, cp, mkdir } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			const outDir = options.outDir;
+			await mkdir(outDir, { recursive: true });
+			await cp(options.clientOutDir, join(outDir, "client"), { recursive: true });
+			await cp(join(options.serverEntry, ".."), join(outDir, "server"), { recursive: true });
+			const port = options.config.port ?? 3e3;
+			const serverEntry = `
+const handler = (await import("./server/entry-server.js")).default
+const clientDir = new URL("./client/", import.meta.url).pathname
+Bun.serve({
+  port: ${port},
+  async fetch(req) {
+    const url = new URL(req.url)
+    // Try static files first
+    if (req.method === "GET") {
+      const filePath = clientDir + (url.pathname === "/" ? "index.html" : url.pathname)
+      // Prevent path traversal — ensure resolved path stays within clientDir
+      const resolved = Bun.resolveSync(filePath, ".")
+      if (!resolved.startsWith(Bun.resolveSync(clientDir, "."))) {
+        return new Response("Forbidden", { status: 403 })
+      }
+      const file = Bun.file(filePath)
+      if (await file.exists()) {
+        return new Response(file, {
+          headers: {
+            "cache-control": filePath.endsWith(".js") || filePath.endsWith(".css")
+              ? "public, max-age=31536000, immutable"
+              : "public, max-age=3600",
+          },
+        })
+      }
+    }
+    // Fall through to SSR handler
+    return handler(req)
+  },
+})
+console.log("\\n  ⚡ Zero production server running on http://localhost:${port}\\n")
+`.trimStart();
+			await writeFile(join(outDir, "index.ts"), serverEntry);
+		},
+		async revalidate(_path) {
+			if (process.env.NODE_ENV !== "production") console.warn("[Pyreon] bunAdapter.revalidate() is a no-op — self-hosted Bun has no platform-driven ISR. Use mode: \"isr\" for runtime LRU caching, or vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven build-time ISR.");
+			return { regenerated: false };
+		}
+	};
+}
+//#endregion
+//#region src/adapters/warn-missing-env.ts
+/**
+* M2.4 — Loud first-call warning for missing adapter env vars.
+*
+* Pre-M2.4 the adapter `revalidate()` methods returned `{ regenerated: false }`
+* silently in production when required env vars were missing. The dev-mode
+* warning was gated on `process.env.NODE_ENV !== 'production'` — exactly the
+* env condition that DEPLOYED apps run under, where users would most need
+* the signal. Symptom: CMS triggers `adapter.revalidate(path)`, nothing
+* happens, no console output, no failure mode reported back to the
+* triggering webhook handler. The bug only surfaces when someone notices
+* stale content.
+*
+* Fix: warn ALWAYS (regardless of NODE_ENV) on the FIRST invocation per
+* `(adapterName + varSet)` combination. Dedupe via a module-level Set so
+* a busy revalidation handler doesn't spam logs — one warn per process
+* per missing-env-set is enough to expose the misconfiguration.
+*
+* Returns the canonical `{ regenerated: false }` so adapters can write
+* `return warnMissingEnv(...)` as a one-liner.
+*
+* @internal Exposed for unit tests via `_internal.warnMissingEnv` (not yet wired) + `_warnedKeys` reset.
+*/
+const _warnedKeys = /* @__PURE__ */ new Set();
+function warnMissingEnv(adapterName, missingVars, hint) {
+	const key = `${adapterName}:${missingVars.join(",")}`;
+	if (!_warnedKeys.has(key)) {
+		_warnedKeys.add(key);
+		console.warn(`[Pyreon] ${adapterName}Adapter.revalidate() needs ${missingVars.join(" + ")} env var(s). ${hint}`);
+	}
+	return { regenerated: false };
+}
+//#endregion
+//#region src/adapters/cloudflare.ts
+/**
+* Cloudflare Pages adapter — generates output for Cloudflare Pages with Functions.
+*
+* Produces:
+* - Client assets in the output directory root (served as static)
+* - `_worker.js` — Cloudflare Pages Function for SSR
+*
+* Note: Cloudflare Pages Functions have a ~1MB module size limit.
+* For large apps, configure Vite's SSR build to bundle server code:
+* `ssr: { noExternal: true }` in vite.config.ts.
+*
+* Deploy with: `npx wrangler pages deploy ./dist`
+*
+* @example
+* ```ts
+* // zero.config.ts
+* import { defineConfig } from "@pyreon/zero"
+*
+* export default defineConfig({
+*   adapter: "cloudflare",
+* })
+* ```
+*/
+function cloudflareAdapter() {
+	return {
+		name: "cloudflare",
+		async build(options) {
+			if (options.kind === "ssg") {
+				const { writeFile } = await import("node:fs/promises");
+				const { join } = await import("node:path");
+				await writeFile(join(options.outDir, "_routes.json"), JSON.stringify({
+					version: 1,
+					include: [],
+					exclude: ["/*"]
+				}, null, 2));
+				return;
+			}
+			await validateBuildInputs(options);
+			const { writeFile, cp, mkdir } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			const outDir = options.outDir;
+			await mkdir(outDir, { recursive: true });
+			await cp(options.clientOutDir, outDir, { recursive: true });
+			await cp(join(options.serverEntry, ".."), join(outDir, "_server"), { recursive: true });
+			const workerEntry = `
+import handler from "./_server/entry-server.js"
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url)
+    // Let Cloudflare serve static assets (files with extensions)
+    // This check is a fallback — Pages routes static files automatically
+    const ext = url.pathname.split(".").pop()
+    if (ext && ext !== url.pathname && !url.pathname.endsWith("/")) {
+      // Cloudflare Pages handles static assets automatically via its asset binding
+      // Only reach here if the file doesn't exist — fall through to SSR
+    }
+    // SSR handler
+    try {
+      return await handler(request)
+    } catch (err) {
+      return new Response("Internal Server Error", { status: 500 })
+    }
+  },
+}
+`.trimStart();
+			await writeFile(join(outDir, "_worker.js"), workerEntry);
+			await writeFile(join(outDir, "_routes.json"), JSON.stringify({
+				version: 1,
+				include: ["/*"],
+				exclude: [
+					"/assets/*",
+					"/favicon.*",
+					"/site.webmanifest",
+					"/robots.txt",
+					"/sitemap.xml"
+				]
+			}, null, 2));
+		},
+		async revalidate(path) {
+			const zoneId = process.env.CLOUDFLARE_ZONE_ID;
+			const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+			const siteUrl = process.env.CLOUDFLARE_SITE_URL;
+			if (!zoneId || !apiToken || !siteUrl) {
+				const missing = [];
+				if (!zoneId) missing.push("CLOUDFLARE_ZONE_ID");
+				if (!apiToken) missing.push("CLOUDFLARE_API_TOKEN");
+				if (!siteUrl) missing.push("CLOUDFLARE_SITE_URL");
+				return warnMissingEnv("cloudflare", missing, "Set them in Cloudflare Pages dashboard → Settings → Environment Variables. Note: Cloudflare imposes a 1000-purge-per-24h rate limit per zone — high-frequency revalidation will hit it.");
+			}
+			const fullUrl = `${siteUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+			try {
+				return { regenerated: (await fetch(`https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`, {
+					method: "POST",
+					headers: {
+						"Authorization": `Bearer ${apiToken}`,
+						"Content-Type": "application/json"
+					},
+					body: JSON.stringify({ files: [fullUrl] })
+				})).ok };
+			} catch (err) {
+				if (process.env.NODE_ENV !== "production") console.warn(`[Pyreon] cloudflareAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`);
+				return { regenerated: false };
+			}
+		}
+	};
+}
+//#endregion
+//#region src/adapters/netlify.ts
+/**
+* Netlify adapter — generates output for Netlify Functions (v2).
+*
+* Produces:
+* - Client assets in `publish/` directory
+* - `netlify/functions/ssr.mjs` — Netlify Function for SSR
+* - `netlify.toml` — routing configuration
+*
+* @example
+* ```ts
+* // zero.config.ts
+* import { defineConfig } from "@pyreon/zero"
+*
+* export default defineConfig({
+*   adapter: "netlify",
+* })
+* ```
+*/
+function netlifyAdapter() {
+	return {
+		name: "netlify",
+		async build(options) {
+			if (options.kind === "ssg") {
+				const { writeFile } = await import("node:fs/promises");
+				const { join } = await import("node:path");
+				await writeFile(join(options.outDir, "netlify.toml"), `[build]
+  publish = "."
+[[headers]]
+  for = "/assets/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+`);
+				return;
+			}
+			await validateBuildInputs(options);
+			const { writeFile, cp, mkdir } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			const outDir = options.outDir;
+			const publishDir = join(outDir, "publish");
+			const functionsDir = join(outDir, "netlify", "functions");
+			await mkdir(publishDir, { recursive: true });
+			await mkdir(functionsDir, { recursive: true });
+			await cp(options.clientOutDir, publishDir, { recursive: true });
+			await cp(join(options.serverEntry, ".."), join(functionsDir, "_server"), { recursive: true });
+			const funcEntry = `
+import handler from "./_server/entry-server.js"
+export default async function(req, context) {
+  try {
+    return await handler(req)
+  } catch (err) {
+    return new Response("Internal Server Error", { status: 500 })
+  }
+}
+export const config = {
+  path: "/*",
+  preferStatic: true,
+}
+`.trimStart();
+			await writeFile(join(functionsDir, "ssr.mjs"), funcEntry);
+			const toml = `
+[build]
+  publish = "publish"
+  functions = "netlify/functions"
+[[headers]]
+  for = "/assets/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+[[redirects]]
+  from = "/*"
+  to = "/.netlify/functions/ssr"
+  status = 200
+  conditions = {Role = ["admin", "user", ""]}
+`.trimStart();
+			await writeFile(join(outDir, "netlify.toml"), toml);
+		},
+		async revalidate(path) {
+			const hookUrl = process.env.NETLIFY_BUILD_HOOK_URL;
+			if (!hookUrl) return warnMissingEnv("netlify", ["NETLIFY_BUILD_HOOK_URL"], "Create a build hook in Site settings → Build & deploy → Build hooks → Add build hook. Note: Netlify Build Hooks trigger a FULL site rebuild — the path arg is recorded as `trigger_title` for audit traceability but Netlify doesn't support per-page ISR natively.");
+			try {
+				const triggerTitle = `revalidate:${path}`;
+				return { regenerated: (await fetch(`${hookUrl}?trigger_title=${encodeURIComponent(triggerTitle)}`, { method: "POST" })).ok };
+			} catch (err) {
+				if (process.env.NODE_ENV !== "production") console.warn(`[Pyreon] netlifyAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`);
+				return { regenerated: false };
+			}
+		}
+	};
+}
+//#endregion
+//#region src/adapters/node.ts
+/**
+* Node.js adapter — generates a standalone server entry using node:http.
+*
+* **SSG mode (PR J)**: no-op. Node adapter exists for serving the SSR
+* runtime; SSG output is already complete static HTML — serve it with
+* any static-file server (`bun preview` / nginx / Caddy / `npx serve`).
+* Use `staticAdapter()` if you want explicit SSG semantics.
+*/
+function nodeAdapter() {
+	return {
+		name: "node",
+		async build(options) {
+			if (options.kind === "ssg") return;
+			await validateBuildInputs(options);
+			const { writeFile, cp, mkdir } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			const outDir = options.outDir;
+			await mkdir(outDir, { recursive: true });
+			await cp(options.clientOutDir, join(outDir, "client"), { recursive: true });
+			await cp(join(options.serverEntry, ".."), join(outDir, "server"), { recursive: true });
+			const port = options.config.port ?? 3e3;
+			const serverEntry = `
+import { createServer } from "node:http"
+import { readFile } from "node:fs/promises"
+import { join, extname } from "node:path"
+import { fileURLToPath } from "node:url"
+const __dirname = fileURLToPath(new URL(".", import.meta.url))
+const handler = (await import("./server/entry-server.js")).default
+const clientDir = join(__dirname, "client")
+const MIME_TYPES = {
+  ".html": "text/html",
+  ".js": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ico": "image/x-icon",
+}
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url ?? "/", "http://localhost")
+  // Try to serve static files first
+  if (req.method === "GET") {
+    try {
+      const filePath = join(clientDir, url.pathname === "/" ? "index.html" : url.pathname)
+      // Prevent path traversal — ensure resolved path stays within clientDir
+      const { resolve } = await import("node:path")
+      const resolved = resolve(filePath)
+      if (!resolved.startsWith(resolve(clientDir))) {
+        res.writeHead(403)
+        res.end("Forbidden")
+        return
+      }
+      const ext = extname(filePath)
+      if (ext && ext !== ".html") {
+        const data = await readFile(filePath)
+        const mime = MIME_TYPES[ext] || "application/octet-stream"
+        res.writeHead(200, {
+          "content-type": mime,
+          "cache-control": ext === ".js" || ext === ".css"
+            ? "public, max-age=31536000, immutable"
+            : "public, max-age=3600",
+        })
+        res.end(data)
+        return
+      }
+    } catch {}
+  }
+  // Fall through to SSR handler
+  const headers = {}
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value) headers[key] = Array.isArray(value) ? value.join(", ") : value
+  }
+  const request = new Request(url.href, {
+    method: req.method,
+    headers,
+  })
+  const response = await handler(request)
+  const body = await response.text()
+  const responseHeaders = {}
+  response.headers.forEach((v, k) => { responseHeaders[k] = v })
+  res.writeHead(response.status, responseHeaders)
+  res.end(body)
+})
+server.listen(${port}, () => {
+  console.log("\\n  ⚡ Zero production server running on http://localhost:${port}\\n")
+})
+`.trimStart();
+			await writeFile(join(outDir, "index.js"), serverEntry);
+			await writeFile(join(outDir, "package.json"), JSON.stringify({ type: "module" }, null, 2));
+		},
+		async revalidate(_path) {
+			if (process.env.NODE_ENV !== "production") console.warn("[Pyreon] nodeAdapter.revalidate() is a no-op — self-hosted Node has no platform-driven ISR. Use mode: \"isr\" for runtime LRU caching, or vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven build-time ISR.");
+			return { regenerated: false };
+		}
+	};
+}
+//#endregion
+//#region src/adapters/static.ts
+/**
+* Static adapter — just copies the client build output.
+* Used with SSG mode where all pages are pre-rendered at build time.
+*
+* **SSG mode (PR J)**: no-op — `outDir` already IS the dist directory
+* the SSG plugin produced. Copying it onto itself would only fail. The
+* static adapter is the canonical zero-overhead deploy target for
+* pure-static sites.
+*
+* **SSR mode**: copies clientOutDir → outDir. Calling `static` with SSR
+* mode is unusual — the static adapter doesn't support server-side
+* execution — but preserved as a "client-only output packager".
+*/
+function staticAdapter() {
+	return {
+		name: "static",
+		async build(options) {
+			if (options.kind === "ssg") return;
+			const { cp, mkdir } = await import("node:fs/promises");
+			await mkdir(options.outDir, { recursive: true });
+			await cp(options.clientOutDir, options.outDir, { recursive: true });
+		},
+		async revalidate(_path) {
+			if (process.env.NODE_ENV !== "production") console.warn("[Pyreon] staticAdapter.revalidate() is a no-op — static hosts require a full rebuild + redeploy to refresh prerendered pages. Use vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven ISR.");
+			return { regenerated: false };
+		}
+	};
+}
+//#endregion
+//#region src/adapters/vercel.ts
+/**
+* Vercel adapter — generates output for Vercel's Build Output API v3.
+*
+* Produces a `.vercel/output` directory with:
+* - `static/` — client-side assets (JS, CSS, images)
+* - `functions/ssr.func/` — serverless function for SSR
+* - `config.json` — routing configuration
+*
+* @example
+* ```ts
+* // zero.config.ts
+* import { defineConfig } from "@pyreon/zero"
+*
+* export default defineConfig({
+*   adapter: "vercel",
+* })
+* ```
+*/
+function vercelAdapter() {
+	return {
+		name: "vercel",
+		async build(options) {
+			if (options.kind === "ssg") {
+				const { writeFile, mkdir } = await import("node:fs/promises");
+				const { join } = await import("node:path");
+				const vercelDir = join(options.outDir, ".vercel", "output");
+				await mkdir(vercelDir, { recursive: true });
+				await writeFile(join(vercelDir, "config.json"), JSON.stringify({
+					version: 3,
+					routes: [{
+						src: "/assets/(.*)",
+						headers: { "Cache-Control": "public, max-age=31536000, immutable" }
+					}]
+				}, null, 2));
+				return;
+			}
+			await validateBuildInputs(options);
+			const { writeFile, cp, mkdir } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			const vercelDir = join(options.outDir, ".vercel", "output");
+			const staticDir = join(vercelDir, "static");
+			const funcDir = join(vercelDir, "functions", "ssr.func");
+			await mkdir(staticDir, { recursive: true });
+			await mkdir(funcDir, { recursive: true });
+			await cp(options.clientOutDir, staticDir, { recursive: true });
+			await cp(join(options.serverEntry, ".."), funcDir, { recursive: true });
+			const funcEntry = `
+export default async function handler(req) {
+  const handler = (await import("./entry-server.js")).default
+  return handler(req)
+}
+`.trimStart();
+			await writeFile(join(funcDir, "index.js"), funcEntry);
+			await writeFile(join(funcDir, ".vc-config.json"), JSON.stringify({
+				runtime: "nodejs20.x",
+				handler: "index.js",
+				launcherType: "Nodejs"
+			}, null, 2));
+			await writeFile(join(vercelDir, "config.json"), JSON.stringify({
+				version: 3,
+				routes: [
+					{
+						src: "/assets/(.*)",
+						headers: { "Cache-Control": "public, max-age=31536000, immutable" }
+					},
+					{
+						src: "/(favicon\\..*|site\\.webmanifest|robots\\.txt|sitemap\\.xml)",
+						dest: "/$1"
+					},
+					{
+						src: "/(.*)",
+						dest: "/ssr"
+					}
+				]
+			}, null, 2));
+		},
+		async revalidate(path) {
+			const deploymentUrl = process.env.VERCEL_DEPLOYMENT_URL ?? process.env.VERCEL_URL;
+			const token = process.env.VERCEL_REVALIDATE_TOKEN;
+			if (!deploymentUrl || !token) {
+				const missing = [];
+				if (!deploymentUrl) missing.push("VERCEL_DEPLOYMENT_URL (or VERCEL_URL)");
+				if (!token) missing.push("VERCEL_REVALIDATE_TOKEN");
+				return warnMissingEnv("vercel", missing, "Set the token in Vercel project settings → Environment Variables. VERCEL_DEPLOYMENT_URL / VERCEL_URL is auto-injected by the Vercel runtime.");
+			}
+			const url = `${deploymentUrl.startsWith("http") ? "" : "https://"}${deploymentUrl}/api/_pyreon-revalidate?path=${encodeURIComponent(path)}&secret=${encodeURIComponent(token)}`;
+			try {
+				return { regenerated: (await fetch(url, { method: "POST" })).ok };
+			} catch (err) {
+				if (process.env.NODE_ENV !== "production") console.warn(`[Pyreon] vercelAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`);
+				return { regenerated: false };
+			}
+		}
+	};
+}
+//#endregion
+//#region src/adapters/index.ts
+/**
+* Resolve the adapter from config.
+* Returns a built-in adapter or throws if unknown.
+*
+* Accepts BOTH forms — the `ZeroConfig.adapter` type advertises string
+* names (`'vercel'` / `'cloudflare'` / …) but the scaffolded templates
+* historically emit `adapter: vercelAdapter()` (an Adapter instance via
+* the named factory). Both work: a string goes through the switch lookup;
+* an Adapter object (duck-typed via `name` + `build` fields) passes
+* through. Pre-PR-J `resolveAdapter` was never called from production
+* code so the string-vs-object mismatch was invisible; PR J wires the
+* call into `ssgPlugin.closeBundle`, surfacing the contract divergence.
+* The passthrough preserves both shapes without a breaking type change.
+*/
+function resolveAdapter(config) {
+	const value = config.adapter ?? "node";
+	if (typeof value === "object" && value !== null && typeof value.name === "string" && typeof value.build === "function") return value;
+	switch (value) {
+		case "node": return nodeAdapter();
+		case "bun": return bunAdapter();
+		case "static": return staticAdapter();
+		case "vercel": return vercelAdapter();
+		case "cloudflare": return cloudflareAdapter();
+		case "netlify": return netlifyAdapter();
+		default: throw new Error(`[Pyreon] Unknown adapter: "${String(value)}". Use "node", "bun", "static", "vercel", "cloudflare", or "netlify".`);
+	}
+}
+//#endregion
+//#region src/middleware.ts
+/**
+* Compose multiple middleware into a single middleware function.
+* Middleware runs sequentially — if any returns a Response, the chain stops.
+*
+* @example
+* import { compose } from "@pyreon/zero/middleware"
+* import { corsMiddleware } from "@pyreon/zero/cors"
+* import { rateLimitMiddleware } from "@pyreon/zero/rate-limit"
+*
+* const combined = compose(
+*   corsMiddleware({ origin: "*" }),
+*   rateLimitMiddleware({ max: 100 }),
+*   cacheMiddleware(),
+* )
+*/
+function compose(...middlewares) {
+	return async (ctx) => {
+		for (const mw of middlewares) {
+			const result = await mw(ctx);
+			if (result instanceof Response) return result;
+		}
+	};
+}
+const ZERO_CTX_KEY = "__zeroCtx";
+/**
+* Get the shared Zero context from a middleware context.
+* Creates one if it doesn't exist. Middleware can use this to
+* pass data to downstream middleware without polluting `ctx.locals`.
+*
+* @example
+* const authMiddleware: Middleware = (ctx) => {
+*   const zctx = getContext(ctx)
+*   zctx.userId = "user_123"
+* }
+*
+* const loggingMiddleware: Middleware = (ctx) => {
+*   const zctx = getContext(ctx)
+*   console.log("User:", zctx.userId)
+* }
+*/
+function getContext(ctx) {
+	let zctx = ctx.locals[ZERO_CTX_KEY];
+	if (!zctx) {
+		zctx = {};
+		ctx.locals[ZERO_CTX_KEY] = zctx;
+	}
+	return zctx;
+}
+//#endregion
+//#region src/error-overlay.ts
+/**
+* Dev-only error overlay for SSR/loader errors.
+* Renders a styled HTML page with the error stack trace.
+*/
+function renderErrorOverlay(error) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>SSR Error — Pyreon Zero</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+      background: #1a1a2e;
+      color: #e0e0e0;
+      min-height: 100vh;
+      padding: 2rem;
+    }
+    .overlay {
+      max-width: 900px;
+      margin: 0 auto;
+    }
+    .header {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      margin-bottom: 1.5rem;
+    }
+    .badge {
+      background: #e74c3c;
+      color: white;
+      padding: 0.25rem 0.75rem;
+      border-radius: 4px;
+      font-size: 0.75rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+    .label {
+      color: #888;
+      font-size: 0.85rem;
+    }
+    .message {
+      font-size: 1.25rem;
+      color: #ff6b6b;
+      margin-bottom: 1.5rem;
+      line-height: 1.5;
+      word-break: break-word;
+    }
+    .stack {
+      background: #16213e;
+      border: 1px solid #2a2a4a;
+      border-radius: 8px;
+      padding: 1.25rem;
+      overflow-x: auto;
+      font-size: 0.8rem;
+      line-height: 1.7;
+      white-space: pre-wrap;
+      word-break: break-all;
+    }
+    .stack .at { color: #888; }
+    .stack .file { color: #4ecdc4; }
+    .hint {
+      margin-top: 1.5rem;
+      padding: 1rem;
+      background: #1e2a45;
+      border-radius: 6px;
+      border-left: 3px solid #3498db;
+      font-size: 0.8rem;
+      color: #aaa;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="overlay">
+    <div class="header">
+      <span class="badge">SSR Error</span>
+      <span class="label">Pyreon Zero — Dev Mode</span>
+    </div>
+    <div class="message">${escapeHtml(error.message || "Unknown error")}</div>
+    <pre class="stack">${formatStack(escapeHtml(error.stack || ""))}</pre>
+    <div class="hint">
+      This error occurred during server-side rendering. Check the terminal for
+      the full stack trace. This overlay is only shown in development.
+    </div>
+  </div>
+</body>
+</html>`;
+}
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function formatStack(stack) {
+	return stack.split("\n").map((line) => {
+		if (line.includes("at ")) {
+			const fileMatch = line.match(/\(([^)]+)\)/);
+			if (fileMatch) return line.replace(fileMatch[0], `(<span class="file">${fileMatch[1]}</span>)`);
+		}
+		return line;
+	}).join("\n");
+}
+//#endregion
+//#region src/i18n-routing.ts
+/**
+* Detect preferred locale from Accept-Language header.
+*/
+function detectLocaleFromHeader(acceptLanguage, locales, defaultLocale) {
+	if (!acceptLanguage) return defaultLocale;
+	const preferred = acceptLanguage.split(",").map((part) => {
+		const [lang, q] = part.trim().split(";q=");
+		return {
+			lang: lang?.split("-")[0]?.toLowerCase() ?? "",
+			quality: q ? Number.parseFloat(q) : 1
+		};
+	}).sort((a, b) => b.quality - a.quality);
+	for (const { lang } of preferred) if (locales.includes(lang)) return lang;
+	return defaultLocale;
+}
+/**
+* Extract locale from a URL path.
+* Returns { locale, pathWithoutLocale }.
+*/
+function extractLocaleFromPath(path, locales, defaultLocale) {
+	const segments = path.split("/").filter(Boolean);
+	const firstSegment = segments[0]?.toLowerCase();
+	if (firstSegment && locales.includes(firstSegment)) return {
+		locale: firstSegment,
+		pathWithoutLocale: "/" + segments.slice(1).join("/") || "/"
+	};
+	return {
+		locale: defaultLocale,
+		pathWithoutLocale: path
+	};
+}
+/**
+* Build a localized path.
+*/
+function buildLocalePath(path, locale, defaultLocale, strategy) {
+	const clean = path === "/" ? "" : path;
+	if (strategy === "prefix-except-default" && locale === defaultLocale) return path;
+	return `/${locale}${clean}`;
+}
+/**
+* Fan a `FileRoute[]` into per-locale duplicates so the file-system router
+* knows about every localized URL pattern at build time. PR H — was the
+* missing half of the i18n story before this PR (the `i18nRouting()` Vite
+* plugin only handled request-time locale detection; routes themselves
+* were never duplicated, so static-host SSG outputs and SSR matching had
+* no `/de/about` / `/cs/about` records to render against).
+*
+* Strategy semantics:
+*
+* - **`prefix-except-default`** (default): the default locale's routes
+*   keep their original `urlPath` unchanged (`/about` stays `/about`); all
+*   non-default locales get a prefix (`/de/about`, `/cs/about`). Best for
+*   SEO-on-default-locale apps — search engines see canonical URLs at
+*   `/about` while non-default speakers get explicit prefixes.
+*
+* - **`prefix`**: every locale gets its own prefix, including the default
+*   (`/en/about`, `/de/about`, `/cs/about`). Root `/` becomes `/en` /
+*   `/de` / `/cs`. Better when no locale is "primary" — every URL
+*   self-identifies its locale.
+*
+* Layouts, error boundaries, loading components, and 404 pages duplicate
+* along with their pages — same source file (same `filePath`), new
+* locale-prefixed `urlPath` / `dirPath` / `depth`. The route tree built
+* from the expanded array therefore has one fully-formed subtree per
+* locale, so layout matching, dynamic params (`[id]` → `:id`), and
+* catch-all routes (`[...slug]` → `:slug*`) all compose naturally with
+* the locale prefix — no special cases.
+*
+* `getStaticPaths` composition (for SSG): each duplicate route inherits
+* the same `exports.getStaticPaths`. The SSG plugin's `expandUrlPattern`
+* step then expands `/blog/[slug]` × `[en, de]` × `getStaticPaths()
+* → ['a', 'b']` into `/blog/a`, `/blog/b`, `/de/blog/a`, `/de/blog/b`
+* (or all six prefixed forms under `'prefix'` strategy). Cardinality
+* compounds, which is by design — `ssg.concurrency` (PR D) limits
+* in-flight renders independent of route count.
+*
+* No-op when `config.locales` is empty or contains only the default
+* locale (prefix-except-default strategy with no other locales) — returns
+* the input array unchanged. Always return a fresh array on duplication
+* so callers don't accidentally mutate cached input.
+*
+* Reference: the helper is called from `vite-plugin.ts`'s virtual route
+* module load AND `ssg-plugin.ts`'s pre-render path expansion. Tested in
+* isolation — duplication is a pure transform on FileRoute[] with no
+* filesystem or network side effects.
+*/
+function expandRoutesForLocales(routes, config) {
+	const strategy = config.strategy ?? "prefix-except-default";
+	const { locales, defaultLocale } = config;
+	if (locales.length === 0) return routes;
+	for (const locale of locales) validateLocale(locale);
+	validateLocale(defaultLocale);
+	if (strategy === "prefix-except-default" && locales.length === 1 && locales[0] === defaultLocale) return routes;
+	const expanded = [];
+	for (const route of routes) for (const locale of locales) {
+		if (strategy === "prefix-except-default" && locale === defaultLocale) {
+			expanded.push(route);
+			continue;
+		}
+		if (strategy === "prefix-except-default" && route.isLayout && route.urlPath === "/") continue;
+		const newUrlPath = prefixUrlPath(route.urlPath, locale);
+		const newDirPath = route.dirPath === "" ? locale : `${locale}/${route.dirPath}`;
+		const newDepth = newUrlPath === "/" ? 0 : newUrlPath.split("/").filter(Boolean).length;
+		expanded.push({
+			...route,
+			urlPath: newUrlPath,
+			dirPath: newDirPath,
+			depth: newDepth
+		});
+	}
+	return expanded;
+}
+/**
+* Prepend `/locale` to a URL pattern. Handles three shapes:
+*   `/`         → `/de`
+*   `/about`    → `/de/about`
+*   `/users/:id` / `/blog/:slug*` → `/de/users/:id` / `/de/blog/:slug*`
+*
+* Internal helper to `expandRoutesForLocales`; not exported because the
+* public surface for path-building is `buildLocalePath` (which strips
+* existing locale prefixes — different semantics).
+*/
+function prefixUrlPath(urlPath, locale) {
+	if (urlPath === "/") return `/${locale}`;
+	return `/${locale}${urlPath}`;
+}
+/**
+* Validate a locale string (PR L2).
+*
+* The locale drives both URL pattern emission AND filesystem writes
+* (see `expandRoutesForLocales` for full rationale). Reject input that
+* would either:
+*   - break path-traversal boundaries (`..`, `/`, `\`)
+*   - produce invalid URL segments (whitespace, NUL)
+*   - create hidden-file artifacts (`.` leading)
+*   - silently kill the app (empty string)
+*
+* Throws with an actionable `[Pyreon]` error message. Called per-locale
+* by `expandRoutesForLocales` after the empty-locales no-op guard.
+*
+* @internal — exported for unit testing.
+*/
+function validateLocale(locale) {
+	if (typeof locale !== "string" || locale === "") throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Locales must be non-empty strings (e.g. "en", "de", "en-US").`);
+	if (locale.trim() !== locale) throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Leading or trailing whitespace not allowed.`);
+	if (locale.includes("/") || locale.includes("\\")) throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Path separators ("/", "\\\\") not allowed — they would break URL emission and could write outside the dist directory.`);
+	if (locale === ".." || locale === ".") throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Path-traversal segments not allowed.`);
+	if (locale.startsWith(".")) throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Leading dot not allowed — it would create a hidden-file directory (\`dist/.${locale.slice(1)}/\`) invisible to most file listings.`);
+	if (locale.includes("\0")) throw new Error(`[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. NUL characters not allowed.`);
+}
+/**
+* Create a LocaleContext for use in components and loaders.
+*/
+function createLocaleContext(locale, path, config) {
+	const strategy = config.strategy ?? "prefix-except-default";
+	return {
+		locale,
+		locales: config.locales,
+		defaultLocale: config.defaultLocale,
+		localePath(targetPath, targetLocale) {
+			return buildLocalePath(targetPath, targetLocale ?? locale, config.defaultLocale, strategy);
+		},
+		alternates() {
+			const { pathWithoutLocale } = extractLocaleFromPath(path, config.locales, config.defaultLocale);
+			return config.locales.map((loc) => ({
+				locale: loc,
+				url: buildLocalePath(pathWithoutLocale, loc, config.defaultLocale, strategy)
+			}));
+		}
+	};
+}
+/**
+* I18n routing middleware for Zero's server.
+*
+* - Detects locale from URL prefix or Accept-Language header
+* - Redirects root to preferred locale (when detectLocale is true)
+* - Sets locale context for loaders and components
+*
+* @example
+* ```ts
+* // zero.config.ts
+* import { i18nRouting } from "@pyreon/zero"
+*
+* export default defineConfig({
+*   plugins: [
+*     i18nRouting({
+*       locales: ["en", "de", "cs"],
+*       defaultLocale: "en",
+*     }),
+*   ],
+* })
+* ```
+*/
+function i18nRouting(config) {
+	const strategy = config.strategy ?? "prefix-except-default";
+	const detectEnabled = config.detectLocale !== false;
+	const cookieName = config.cookieName ?? "locale";
+	return {
+		name: "pyreon-zero-i18n-routing",
+		configResolved() {},
+		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				const url = req.url ?? "/";
+				if (url.startsWith("/@") || url.startsWith("/__") || url.includes(".")) return next();
+				const { locale } = extractLocaleFromPath(url, config.locales, config.defaultLocale);
+				if (detectEnabled && url === "/") {
+					const preferredFromCookie = parseCookies(req.headers.cookie)[cookieName];
+					const preferredFromHeader = detectLocaleFromHeader(req.headers["accept-language"], config.locales, config.defaultLocale);
+					const preferred = preferredFromCookie && config.locales.includes(preferredFromCookie) ? preferredFromCookie : preferredFromHeader;
+					if (strategy === "prefix" || preferred !== config.defaultLocale) {
+						res.writeHead(302, { Location: `/${preferred}/` });
+						res.end();
+						return;
+					}
+				}
+				req.__locale = locale;
+				req.__localeContext = createLocaleContext(locale, url, config);
+				localeSignal.set(locale);
+				next();
+			});
+		}
+	};
+}
+function parseCookies(header) {
+	if (!header) return {};
+	const result = {};
+	for (const pair of header.split(";")) {
+		const [key, value] = pair.trim().split("=");
+		if (key && value) result[key] = decodeURIComponent(value);
+	}
+	return result;
+}
+/** @internal Context for the current locale. */
+const LocaleCtx = createContext("en");
+/** Current locale signal — set by the server middleware or client-side detection. */
+const localeSignal = signal("en");
+//#endregion
+//#region src/ssg-plugin.ts
+/**
+* SSG (Static Site Generation) build hook for `@pyreon/zero`.
+*
+* Activates when `mode: "ssg"` is set in zero's config. After Vite's client
+* build finishes, this plugin:
+*
+*   1. Triggers a programmatic SSR build via Vite's `build()` API, producing
+*      a server bundle in `dist/.zero-ssg-server/` from a synthetic entry
+*      that imports `virtual:zero/routes` and `createServer`.
+*   2. Loads the built handler with dynamic `import()`.
+*   3. Resolves the path list from `config.ssg.paths` (string[], async fn,
+*      or auto-detected from the static-only routes in the route tree).
+*   4. Calls `prerender()` from `@pyreon/server` to render each path.
+*   5. Cleans up the temporary SSR build directory.
+*
+* Before this PR, `mode: "ssg"` and `ssg.paths` were typed in
+* `types.ts` but had no runtime implementation — the plugin file had zero
+* Rollup build hooks. Apps configured for SSG silently shipped a bare SPA
+* shell with no per-route HTML files, which broke direct-URL deploys to
+* static hosts (no `dist/<path>/index.html`, every URL falls back to the
+* SPA index).
+*/
+const __DEV__ = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+const _countSink = globalThis;
+const SSG_BUILD_FLAG = "PYREON_ZERO_SSG_INNER_BUILD";
+const renderSsrEntrySource = (locales = []) => {
+	return `
+import { routes } from "virtual:zero/routes"
+import { h } from "@pyreon/core"
+import { renderWithHead } from "@pyreon/head/ssr"
+import { getRedirectInfo, serializeLoaderData, stringifyLoaderData } from "@pyreon/router"
+import { runWithRequestContext } from "@pyreon/runtime-server"
+import { createApp } from "@pyreon/zero/server"
+// Lazy-imported styler integration. Projects that don't depend on
+// @pyreon/styler skip this entirely (the import fails silently, the
+// helper stays a no-op). Hot path: an awaited dynamic import resolved
+// once at entry-module evaluation, then sync calls per request.
+//
+// **No reset between paths.** @pyreon/styler's styled() inserts CSS
+// rules into sheet.ssrBuffer at MODULE-EVAL TIME (top-level of styled.ts:95),
+// not per-render. After that initial insert, each render of a styled
+// component just attaches the cached class name to props — no new buffer
+// push. Calling sheet.reset() between SSG paths would WIPE all rules and
+// leave subsequent pages style-less. For SSG this is acceptable: the
+// generated CSS is identical across all pages (same module-eval cache),
+// and shipping the full rule set in every page's <style> tag matches
+// how static SSG sites handle CSS — every page is self-contained,
+// cacheable by the browser, no per-route CSS code splitting needed.
+let __pyreonGetStylerTag = () => ""
+try {
+  const stylerMod = await import("@pyreon/styler")
+  if (stylerMod && stylerMod.sheet && typeof stylerMod.sheet.getStyleTag === "function") {
+    __pyreonGetStylerTag = () => stylerMod.sheet.getStyleTag()
+  }
+} catch {
+  // No @pyreon/styler in the project — leave the no-op stub in place.
+}
+// PR E — \`__ZERO_BASE__\` is the Vite-defined build-time constant
+// carrying the value of \`zero({ base })\`. Read it once at module
+// eval and forward to createRouter via createApp so SSG-rendered
+// pages have correctly-prefixed RouterLink hrefs that match the
+// asset URLs Vite already prefixed in the built HTML template.
+const __ssgBase = typeof __ZERO_BASE__ !== "undefined" && __ZERO_BASE__ !== "/"
+  ? __ZERO_BASE__
+  : undefined
+export default async function renderPath(path, options) {
+  const { App, router } = createApp({
+    routes,
+    routerMode: "history",
+    url: path,
+    ...(__ssgBase ? { base: __ssgBase } : {}),
+  })
+  // PR B — redirect handling. \`router.preload\` runs every loader in the
+  // matched chain and surfaces \`redirect()\` throws as the rejection
+  // reason. We catch BEFORE the render: rendering past a redirect would
+  // produce HTML for the wrong page AND leak the auth-gated layout
+  // structure for unauthenticated users. The runtime SSR handler
+  // (createHandler in @pyreon/server) already does this same catch and
+  // returns a 302/307 Location response; SSG mirrors that — return
+  // \`{ kind: 'redirect', from, to, status }\` instead of HTML, and the
+  // outer plugin emits a redirect manifest entry instead of an
+  // \`index.html\`. Any non-redirect error rethrows and lands in the
+  // existing \`errors[]\` collection.
+  //
+  // PR C — \`isNotFound\` skips parent-layout loaders during the 404 build.
+  // Layout loaders that hit auth resources (cookies, session tokens,
+  // private APIs) shouldn't fire when generating a static 404 page —
+  // the build has no real request context. Lazy components still
+  // resolve so the synthetic chain renders cleanly; only the
+  // \`r.loader()\` invocations are skipped. \`__renderNotFound\` below
+  // forwards \`{ isNotFound: true }\` for this path.
+  try {
+    await router.preload(path, undefined, {
+      skipLoaders: options?.isNotFound === true,
+    })
+  } catch (err) {
+    const info = getRedirectInfo(err)
+    if (info) {
+      return { kind: "redirect", from: path, to: info.url, status: info.status }
+    }
+    throw err
+  }
+  return runWithRequestContext(async () => {
+    const app = h(App, null)
+    const { html: appHtml, head } = await renderWithHead(app)
+    // Inject styler's <style data-pyreon-styler="..."> tag into the head
+    // BEFORE @pyreon/head's tags so the CSS cascade orders correctly with
+    // any meta/link tags the user added. Empty buffer emits a benign
+    // empty <style></style> — detected via the literal closing pair to
+    // avoid polluting the head when no styler is in use.
+    const styleTag = __pyreonGetStylerTag()
+    const isEmpty = !styleTag || styleTag.indexOf("></style>") !== -1
+    const finalHead = isEmpty ? head : styleTag + "\\n" + head
+    const loaderData = serializeLoaderData(router)
+    const hasData = loaderData && Object.keys(loaderData).length > 0
+    // M2.2 — safe serializer drops function/symbol values, throws a clear
+    // Pyreon-prefixed error on circular refs, escapes <\/script> uniformly.
+    const loaderScript = hasData
+      ? \`<script>window.__PYREON_LOADER_DATA__=\${stringifyLoaderData(loaderData)}<\/script>\`
+      : ""
+    return { kind: "html", appHtml, head: finalHead, loaderScript }
+  })
+}
+// ─── getStaticPaths enumeration (PR A) ──────────────────────────────────────
+//
+// Walks the generated routes tree and collects every dynamic route's
+// \`getStaticPaths\` function alongside its URL pattern. The SSG plugin
+// calls this once before rendering and uses the returned map to expand
+// dynamic routes (\`/posts/:id\` × \`[{id:'a'},{id:'b'}]\` → \`/posts/a\`,
+// \`/posts/b\`). Routes without \`getStaticPaths\` are absent from the map.
+//
+// Why we collect ALL routes here instead of resolving on-demand: the
+// SSG plugin's \`resolvePaths\` runs in the OUTER Vite plugin context (no
+// access to the bundled routes module). The SSR sub-build is the only
+// place where the user's compiled route exports are reachable, so we
+// expose a sync collector that lets the plugin call user functions
+// indirectly via the entry's exports.
+function collectStaticPathsRegistry(rs, out) {
+  for (const r of rs) {
+    if (typeof r.getStaticPaths === "function" && typeof r.path === "string") {
+      out.set(r.path, r.getStaticPaths)
+    }
+    if (Array.isArray(r.children)) collectStaticPathsRegistry(r.children, out)
+  }
+  return out
+}
+/** Map of \`urlPath → getStaticPaths function\` for every dynamic route. */
+export const __getStaticPathsRegistry = collectStaticPathsRegistry(routes, new Map())
+// ─── 404 emission (PR C) ────────────────────────────────────────────────────
+//
+// Locales the build was configured for (PR H: \`zero({ i18n: { locales } })\`).
+// Injected as a JSON-literal by the outer plugin so the walker can detect
+// which RouteRecord serves which locale by matching its \`path\` against
+// the \`/\${locale}\` / \`/\${locale}/*\` prefix. Empty array = no i18n,
+// single-default-locale shape, walker collects exactly one entry keyed
+// by \`null\` and the closeBundle writes a single \`dist/404.html\`.
+const __i18nLocales = ${JSON.stringify(locales)}
+// Walk the route tree and return ALL \`notFoundComponent\` references,
+// keyed by which locale subtree they were found in (or \`null\` for the
+// default / no-i18n case). fs-router attaches \`_404.tsx\` to its parent
+// layout's RouteRecord (or to each page record when no wrapping layout
+// exists — which is the per-locale subtree shape under PR H's root-
+// layout-skip). The walker collects the FIRST match per locale via
+// depth-first traversal: the per-locale subtree's \`notFoundComponent\`
+// wins over the root's for that locale.
+//
+// Locale detection: a RouteRecord serves locale \`X\` if its \`path\`
+// matches \`/X\` or starts with \`/X/\`. The default-locale entry
+// (under \`prefix-except-default\` strategy) is keyed by \`null\` since
+// its path doesn't carry a locale prefix.
+function findNotFoundComponentsByLocale(rs, currentLocale) {
+  const result = new Map()
+  function walk(records, ambient) {
+    for (const r of records) {
+      const path = typeof r.path === "string" ? r.path : ""
+      let locale = ambient
+      for (const l of __i18nLocales) {
+        if (path === \`/\${l}\` || path.startsWith(\`/\${l}/\`)) {
+          locale = l
+          break
+        }
+      }
+      if (typeof r.notFoundComponent === "function") {
+        if (!result.has(locale)) result.set(locale, r.notFoundComponent)
+      }
+      if (Array.isArray(r.children)) walk(r.children, locale)
+    }
+  }
+  walk(rs, currentLocale)
+  return result
+}
+export const __notFoundComponentsByLocale = findNotFoundComponentsByLocale(routes, null)
+// Back-compat: legacy single-export, picks up whatever the walker
+// classified as \`null\`-locale (default-locale or non-i18n root 404).
+// External callers (none currently in main, but downstream consumers
+// that imported this export pre-PR) keep working.
+export const __notFoundComponent = __notFoundComponentsByLocale.get(null) ?? null
+// Render the not-found component THROUGH the router (PR L5). We navigate
+// to a synthetic non-matching probe URL per locale — \`resolveRoute\`
+// (post-L5) walks the route tree finding the deepest parent
+// \`notFoundComponent\` and builds a matched chain
+// \`[...ancestorLayouts, syntheticLeaf]\`. The leaf carries the
+// not-found component; rendering through the normal pipeline produces
+// HTML WITH layout chrome — same headers, footers, navigation as
+// regular pages. The locale prefix in the probe URL ensures the right
+// per-locale layout subtree matches (under PR H's prefix strategy).
+//
+// Pre-L5 behavior (\`h(component, null)\` standalone) is preserved as a
+// fallback when the route tree has \`notFoundComponent\` at the root
+// but no \`isNotFound\` chain forms (older route shapes). The outer
+// plugin checks \`__notFoundComponentsByLocale\` first to gate emission
+// — if no notFoundComponent exists anywhere, \`__renderNotFound\` is
+// never called.
+export async function __renderNotFound(locale) {
+  // Probe URL chosen to be highly improbable as a real route. The
+  // suffix is deliberately literal (no \`Math.random\`) so build
+  // outputs are deterministic across runs.
+  const probePath = locale == null
+    ? "/__pyreon_not_found_probe__"
+    : \`/\${locale}/__pyreon_not_found_probe__\`
+  // Try the router-driven path first. If the route tree has a parent
+  // \`notFoundComponent\` reachable from the probe URL, resolveRoute's
+  // fallback builds the chain through the layout and the normal render
+  // pipeline produces 404 HTML wrapped in layout chrome.
+  //
+  // PR C — pass \`isNotFound: true\` so renderPath skips parent-layout
+  // loaders. Layout loaders that hit auth resources / external APIs
+  // shouldn't fire when generating a static 404 page (the build has
+  // no real request context). Lazy components still resolve; only
+  // \`r.loader()\` invocations are skipped.
+  const result = await renderPath(probePath, { isNotFound: true })
+  if (result && result.kind === "html") {
+    return {
+      appHtml: result.appHtml,
+      head: result.head,
+      loaderScript: result.loaderScript,
+    }
+  }
+  // Fallback for tree shapes where the resolver returns empty matched
+  // (no notFoundComponent walkable from this probe path). Render the
+  // component standalone — same shape pre-L5.
+  const component = locale == null
+    ? (__notFoundComponentsByLocale.get(null) ?? __notFoundComponent)
+    : __notFoundComponentsByLocale.get(locale)
+  if (typeof component !== "function") return null
+  return runWithRequestContext(async () => {
+    const vnode = h(component, null)
+    const { html: appHtml, head } = await renderWithHead(vnode)
+    const styleTag = __pyreonGetStylerTag()
+    const isEmpty = !styleTag || styleTag.indexOf("></style>") !== -1
+    const finalHead = isEmpty ? head : styleTag + "\\n" + head
+    return { appHtml, head: finalHead, loaderScript: "" }
+  })
+}
+`.trimStart();
+};
+const SSR_ENTRY_FILENAME = "__pyreon-zero-ssg-entry.js";
+/**
+* Substitute concrete values for `:param` / `:param*` segments in a URL
+* pattern. Mirrors the inverse of `filePathToUrlPath`.
+*
+*   /posts/:id            × { id: 'a' }            → /posts/a
+*   /posts/:id/:slug      × { id: 'a', slug: 'b' } → /posts/a/b
+*   /blog/:rest*          × { rest: 'a/b' }         → /blog/a/b   (catch-all preserves slashes)
+*
+* Missing params or empty values throw — the SSG plugin treats this as a
+* `getStaticPaths` error and records it in the per-path errors array.
+*/
+function expandUrlPattern(pattern, params) {
+	return pattern.split("/").map((seg) => {
+		if (!seg.startsWith(":")) return seg;
+		const isCatchAll = seg.endsWith("*");
+		const name = isCatchAll ? seg.slice(1, -1) : seg.slice(1);
+		const value = params[name];
+		if (value === void 0 || value === "") throw new Error(`[zero:ssg] getStaticPaths for "${pattern}" returned params without "${name}"`);
+		const segs = isCatchAll ? value.split("/") : [value];
+		if (!isCatchAll && value.includes("/") || segs.some((s) => s === "." || s === "..")) throw new Error(`[zero:ssg] getStaticPaths for "${pattern}" produced an unsafe "${name}" value (${JSON.stringify(value)}): a ${isCatchAll ? "catch-all" : "dynamic"} segment must not contain path-traversal ("." / "..")${isCatchAll ? "" : " or \"/\""}.`);
+		return value;
+	}).join("/");
+}
+/**
+* Auto-detect static paths from the route tree AND expand dynamic routes
+* via each route's `getStaticPaths` export (when present). A "static" path
+* is one with NO dynamic segments (`[id]`, `[...rest]`); a "dynamic" path
+* with `getStaticPaths` is expanded via the registry; remaining dynamic
+* routes are silently skipped (the user must hand-list them in
+* `ssg.paths`).
+*/
+async function autoDetectStaticPaths(routesDir, registry, errors = [], i18n) {
+	if (!existsSync(routesDir)) return ["/"];
+	const baseRoutes = parseFileRoutes(await scanRouteFiles(routesDir));
+	const fileRoutes = i18n ? expandRoutesForLocales(baseRoutes, i18n) : baseRoutes;
+	const out = [];
+	for (const r of fileRoutes) {
+		if (r.isLayout || r.isError || r.isLoading || r.isNotFound) continue;
+		const path = r.urlPath;
+		if (!path) continue;
+		if (!/[:*]/.test(path)) {
+			out.push(path);
+			continue;
+		}
+		const enumerator = registry?.get(path);
+		if (!enumerator) continue;
+		try {
+			const result = await enumerator();
+			if (!Array.isArray(result)) throw new Error(`getStaticPaths for "${path}" must return an array, got ${typeof result}`);
+			for (const entry of result) {
+				if (!entry || typeof entry !== "object" || !entry.params) throw new Error(`getStaticPaths for "${path}" returned an entry without "params"`);
+				out.push(expandUrlPattern(path, entry.params));
+			}
+		} catch (error) {
+			errors.push({
+				path,
+				error
+			});
+		}
+	}
+	const deduped = [...new Set(out)];
+	return deduped.length > 0 ? deduped : ["/"];
+}
+async function resolvePaths(config, routesDir, registry, errors = []) {
+	const explicit = config.ssg?.paths;
+	if (typeof explicit === "function") {
+		const result = await explicit();
+		return Array.isArray(result) ? result : [];
+	}
+	if (Array.isArray(explicit)) return explicit;
+	return autoDetectStaticPaths(routesDir, registry, errors, config.i18n);
+}
+/**
+* Write `content` to `target` atomically: write to a sibling temp file first,
+* then `rename` into place. Rename is an atomic syscall on POSIX (and Windows
+* for same-volume renames) — readers either see the OLD content or the FULL
+* new content, never a half-written file.
+*
+* M2.1 — Use this for manifests that adapters consume (`_redirects`,
+* `_pyreon-ssg-paths.json`, `_pyreon-revalidate.json`, etc.). A SIGINT during
+* a sequential plain-`writeFile` chain in `closeBundle` would leave partial
+* state: half the manifests pointing at the new render, half the old. Atomic
+* writes mean each manifest is independently consistent — readers see either
+* the old build's manifest or the new build's, never a mix.
+*
+* Per-page HTML writes (`dist/<path>/index.html`) intentionally do NOT use
+* this — they're individually-readable files (no cross-file invariants), and
+* the rename-per-page cost on 10k-path sites would be significant.
+*
+* Temp filename embeds `pid + perf-counter` so concurrent runs (e.g. CI
+* pipelines that fight over the same dist) don't collide. The tmp file is
+* cleaned up in a finally block — even if the rename fails, no orphaned
+* `.tmp.*` files leak.
+*
+* @internal Exposed via `_internal.writeFileAtomic` for unit tests.
+*/
+let _atomicSeq = 0;
+async function writeFileAtomic(target, content) {
+	const tmp = `${target}.tmp.${process.pid}.${++_atomicSeq}`;
+	try {
+		await writeFile(tmp, content);
+		await rename(tmp, target);
+	} catch (err) {
+		try {
+			await unlink(tmp);
+		} catch {}
+		throw err;
+	}
+}
+/**
+* Build the per-locale breakdown summary string for the closeBundle log.
+*
+* M2.5 — Computes per-locale path counts from `writtenPaths` by checking
+* each path's leading segment against the configured locale list. Paths
+* with no locale prefix go to the default locale (under
+* `prefix-except-default`) or are skipped (under `prefix`, where every
+* locale carries an explicit prefix — unprefixed paths are unexpected).
+*
+* Returns `` ` [en: 100, de: 100, cs: 100]` `` (with leading space) for
+* pretty concatenation into the summary line, or empty string when i18n
+* is unconfigured / writtenPaths is empty.
+*
+* @internal Exposed via `_internal.buildLocaleSummary` for unit tests.
+*/
+function buildLocaleSummary(writtenPaths, i18n) {
+	if (writtenPaths.length === 0 || i18n.locales.length === 0) return "";
+	const counts = /* @__PURE__ */ new Map();
+	for (const locale of i18n.locales) counts.set(locale, 0);
+	const defaultLocale = i18n.defaultLocale ?? i18n.locales[0] ?? "";
+	const strategy = i18n.strategy ?? "prefix-except-default";
+	for (const p of writtenPaths) {
+		const firstSeg = p.split("/")[1];
+		if (firstSeg && counts.has(firstSeg)) counts.set(firstSeg, (counts.get(firstSeg) ?? 0) + 1);
+		else if (strategy === "prefix-except-default" && defaultLocale) counts.set(defaultLocale, (counts.get(defaultLocale) ?? 0) + 1);
+	}
+	const parts = [];
+	for (const locale of i18n.locales) parts.push(`${locale}: ${counts.get(locale) ?? 0}`);
+	return ` [${parts.join(", ")}]`;
+}
+/**
+* Detect duplicate URLs in the resolved-paths list. Returns the duplicates
+* (sorted, unique). Empty array = no collisions.
+*
+* The render loop's `writtenPaths.push(p)` would silently last-wins on
+* duplicates — two routes producing the same URL would have one's HTML
+* overwrite the other's with no error. Catching the collision before
+* render makes the conflict visible at the source-of-truth (the routes
+* tree), not at the symptom (mysterious HTML drift between rebuilds).
+*
+* @internal Exposed via `_internal.detectPathCollisions` for unit tests.
+*/
+function detectPathCollisions(paths) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const p of paths) {
+		if (seen.has(p)) duplicates.add(p);
+		seen.add(p);
+	}
+	return [...duplicates].sort();
+}
+/** Format a path-collision error message with actionable guidance. */
+/**
+* Wiring helper: run the collision detector + throw with the formatted error
+* when any collisions are found. The closeBundle handler calls this between
+* `resolvePaths` and the render loop. Factored out so unit tests can exercise
+* the full "detect → throw" path without spinning up a Vite SSR sub-build.
+*
+* @internal Exposed via `_internal.assertNoPathCollisions` for unit tests.
+*/
+function assertNoPathCollisions(paths) {
+	const collisions = detectPathCollisions(paths);
+	if (collisions.length > 0) throw new Error(formatPathCollisionError(collisions));
+}
+function formatPathCollisionError(duplicates) {
+	const list = duplicates.map((p) => `  - ${p}`).join("\n");
+	return `[Pyreon] SSG path collision — ${duplicates.length} URL(s) resolved by multiple routes:\n${list}\nThis happens when a static route + getStaticPaths return overlap, or two getStaticPaths enumerators produce the same URL. Inspect your routes tree and ensure each URL is produced by exactly one route.`;
+}
+function resolveOutputPath(distDir, path) {
+	if (path === "/") return join(distDir, "index.html");
+	if (path.endsWith(".html")) return join(distDir, path);
+	return join(distDir, path, "index.html");
+}
+/**
+* Path-containment check that is SEPARATOR-TERMINATED. A bare
+* `resolve(filePath).startsWith(resolve(distDir))` is a string-prefix
+* test, not a path test: with distDir `/app/dist`, a traversed filePath
+* resolving to the SIBLING `/app/dist-evil/x` passes
+* `'/app/dist-evil/x'.startsWith('/app/dist')` → true and the build
+* writes outside the intended output root. `path` derives from caller
+* route params (CMS slugs via `getStaticPaths`), so this is reachable.
+*/
+function isInsideDist(distDir, filePath) {
+	const root = resolve(distDir);
+	const target = resolve(filePath);
+	return target === root || target.startsWith(root + sep);
+}
+/**
+* Render Netlify / Cloudflare Pages `_redirects` file content. One line
+* per redirect, format: `<from> <to> <status>`. Both platforms parse this
+* format identically; Vercel ignores it (use the JSON below). Lines with
+* leading `#` are comments — included so the file is self-documenting in
+* a deploy log.
+*/
+function renderNetlifyRedirects(entries) {
+	if (entries.length === 0) return "";
+	const lines = ["# Auto-generated by @pyreon/zero SSG. Do not edit."];
+	for (const e of entries) lines.push(`${e.from} ${e.to} ${e.status}`);
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Render Vercel `_redirects.json` content. Vercel reads this from the
+* `vercel.json` `redirects` array shape — but the bare `_redirects.json`
+* file ships alongside as documentation / fallback for adapters that
+* read either format. The 308/301/302/307 status maps to Vercel's
+* `permanent: true|false` boolean (308/301 → permanent; 302/307 →
+* temporary).
+*/
+function renderVercelRedirectsJson(entries) {
+	return `${JSON.stringify({ redirects: entries.map((e) => ({
+		source: e.from,
+		destination: e.to,
+		permanent: e.status === 301 || e.status === 308,
+		statusCode: e.status
+	})) }, null, 2)}\n`;
+}
+/**
+* Render a meta-refresh HTML stub for static hosts that don't read
+* `_redirects` (plain S3, GitHub Pages, simple file servers). The
+* `<meta http-equiv="refresh" content="0; url=…">` triggers a
+* client-side refresh; the canonical link is for SEO so search
+* engines de-dupe the source path against the target. Status code
+* has no HTML equivalent — a meta-refresh is always "client-side."
+*/
+function renderMetaRefreshHtml(target) {
+	const escaped = target.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+	return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="refresh" content="0; url=${escaped}">
+  <link rel="canonical" href="${escaped}">
+  <title>Redirecting to ${escaped}</title>
+</head>
+<body>
+  <p>Redirecting to <a href="${escaped}">${escaped}</a>...</p>
+</body>
+</html>
+`;
+}
+/**
+* Serialize the captured render-loop errors as a stable JSON artifact.
+* Each entry has `{ path, message, name, stack }`. Errors that aren't
+* `Error` instances (e.g. a loader that threw a string) are coerced via
+* `String()` for `message`; `name` falls back to `'Error'`; `stack` is
+* `undefined` (omitted from JSON output).
+*
+* Wrapped in `{ errors: [...] }` rather than emitted as a bare array so
+* future fields (timing, build metadata) can be added without breaking
+* existing CI consumers. Pretty-printed with 2-space indent — the file
+* is meant to be read both by tooling AND humans diagnosing a failed
+* build, so byte-density is not the priority.
+*/
+/**
+* Drain `items` through `concurrency` parallel workers, calling
+* `processItem(item)` on each and `onSettled(item, idx)` once each
+* settles (regardless of resolve/reject). The work-stealing pattern
+* (each worker pulls from a shared `nextIdx++` cursor) keeps load
+* balanced even when individual `processItem` calls vary widely in
+* duration — a fast item doesn't make its worker idle until the slowest
+* peer finishes.
+*
+* Settle ordering: `onSettled` fires in the order items finish, NOT in
+* input order. `idx` is the index into `items` (same identity across
+* `processItem` and `onSettled`), useful for "completed N of M"
+* progress reporting.
+*
+* Concurrency clamping: ≤ 0 inputs ARE clamped to 1 — the worker pool
+* is meaningless without at least one worker, but a value of `0` from
+* a misconfiguration shouldn't silently hang. The actual worker count
+* is `min(concurrency, items.length)` so a 2-item list with concurrency
+* 10 only spawns 2 workers (no idle workers spawned).
+*
+* Errors from `processItem` are NOT caught here — callers must handle
+* exceptions inside `processItem` (the SSG path does so via try/catch
+* in `renderOne`). Errors from `onSettled` likewise propagate; in the
+* SSG path the caller wraps it to record into `errors[]`. We don't
+* silently swallow because that would hide real bugs.
+*
+* Atomic operations under Node's single-threaded JS: `nextIdx++` is
+* atomic — workers never observe a partial increment, so two workers
+* never claim the same index. The pool relies on this invariant; do
+* NOT port to a multi-threaded runtime without revisiting.
+*/
+async function runWithConcurrency(items, concurrency, processItem, onSettled) {
+	const workerCount = Math.min(Math.max(1, concurrency), items.length);
+	if (workerCount === 0) return;
+	let nextIdx = 0;
+	const worker = async () => {
+		while (true) {
+			const idx = nextIdx++;
+			if (idx >= items.length) return;
+			const item = items[idx];
+			await processItem(item, idx);
+			if (onSettled) await onSettled(item, idx);
+		}
+	};
+	await Promise.all(Array.from({ length: workerCount }, () => worker()));
+}
+/**
+* PR I — build the revalidate manifest from scanned FileRoutes + the
+* list of paths that successfully rendered.
+*
+* For each FileRoute with a `revalidateLiteral` (captured at scan time
+* via `detectRouteExports`), parse the literal as JSON (numbers and
+* `false` are valid JSON tokens), build a regex from the route's
+* urlPath pattern, and match against `writtenPaths`. Each matching
+* concrete path goes into the manifest under the route's revalidate
+* value.
+*
+* Returns `{}` when no routes have a revalidate literal — the caller
+* checks `Object.keys(...).length > 0` before writing the manifest.
+*
+* Static routes match exactly (urlPath === concretePath). Dynamic
+* routes (`/posts/:id`) compile to `^\/posts\/[^/]+$`. Catch-alls
+* (`/blog/:slug*`) compile to `^\/blog\/.*$`. Layout / error / loading
+* / not-found routes are skipped — they don't appear in writtenPaths
+* anyway, but the explicit guard keeps the helper stand-alone-testable.
+*
+* Exposed via `_internal.buildRevalidateManifest` so it can be unit-
+* tested without a full SSG round-trip.
+*/
+function buildRevalidateManifest(fileRoutes, writtenPaths) {
+	const manifest = {};
+	for (const route of fileRoutes) {
+		if (route.isLayout || route.isError || route.isLoading || route.isNotFound) continue;
+		const literal = route.exports?.revalidateLiteral;
+		if (literal === void 0) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(literal);
+		} catch {
+			continue;
+		}
+		if (typeof parsed !== "number" && parsed !== false) continue;
+		const value = parsed;
+		const matcher = compileUrlPatternMatcher(route.urlPath);
+		for (const concretePath of writtenPaths) if (matcher(concretePath)) manifest[concretePath] = value;
+	}
+	return manifest;
+}
+/**
+* Compile a route's urlPath pattern (`/posts/:id`, `/blog/:slug*`,
+* `/about`) into a predicate that returns `true` for any concrete
+* path that matches. Static patterns return a `===` comparator.
+* Dynamic / catch-all patterns return a regex predicate.
+*
+* Internal helper to `buildRevalidateManifest`. Mirrors the routing
+* matcher's behaviour for `:param` (single segment) and `:param*`
+* (catch-all, zero-or-more segments). Doesn't need to handle every
+* router edge case — the writtenPaths it matches against are already
+* concrete (no params, no wildcards).
+*/
+function compileUrlPatternMatcher(urlPath) {
+	if (!urlPath.includes(":") && !urlPath.includes("*")) return (concrete) => concrete === urlPath;
+	const regex = urlPath.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:([A-Za-z_$][\w$]*)\*/g, ".*").replace(/:([A-Za-z_$][\w$]*)/g, "[^/]+");
+	const re = new RegExp(`^${regex}$`);
+	return (concrete) => re.test(concrete);
+}
+function renderErrorArtifact(entries) {
+	const errors = entries.map(({ path, error }) => ({
+		path,
+		message: error instanceof Error ? error.message : String(error),
+		name: error instanceof Error ? error.name : "Error",
+		stack: error instanceof Error ? error.stack : void 0
+	}));
+	return `${JSON.stringify({ errors }, null, 2)}\n`;
+}
+/**
+* Inject a rendered SSR result into the index.html template. Prefers
+* Pyreon's `<!--pyreon-head-->` / `<!--pyreon-app-->` /
+* `<!--pyreon-scripts-->` placeholders; falls back to inserting before
+* `</head>` / inside `<div id="app">` / before `</body>` so a bare
+* Vite-style `index.html` (no Pyreon comments) still receives content.
+*
+* Factored out of the per-path render loop so the 404 emission path can
+* reuse the exact same injection rules — keeps the rendered _404.tsx
+* subject to the same head/body/scripts pipeline as regular pages
+* (styler tag, @pyreon/head meta, hashed asset preload links).
+*/
+function injectIntoTemplate(template, result) {
+	let html = template;
+	if (html.includes("<!--pyreon-head-->")) html = html.replace("<!--pyreon-head-->", result.head);
+	else if (result.head) html = html.replace("</head>", `${result.head}</head>`);
+	if (html.includes("<!--pyreon-app-->")) html = html.replace("<!--pyreon-app-->", result.appHtml);
+	else if (result.appHtml) {
+		const appDivMatch = html.match(/<div\s+id=["']app["']\s*>([\s\S]*?)<\/div>/);
+		if (appDivMatch) html = html.replace(appDivMatch[0], `<div id="app">${result.appHtml}</div>`);
+		else html = html.replace("</body>", `<div id="app">${result.appHtml}</div></body>`);
+	}
+	if (html.includes("<!--pyreon-scripts-->")) html = html.replace("<!--pyreon-scripts-->", result.loaderScript);
+	else if (result.loaderScript) html = html.replace("</body>", `${result.loaderScript}</body>`);
+	return html;
+}
+/**
+* Plugin that performs SSG when `mode: "ssg"` is configured. Wires into
+* Vite's `closeBundle` hook so it runs once after the main client build
+* completes. The recursive SSR sub-build is gated by an env flag.
+*/
+function ssgPlugin(userConfig = {}) {
+	const config = resolveConfig(userConfig);
+	let root = "";
+	let distDir = "";
+	const isInnerBuild = process.env[SSG_BUILD_FLAG] === "1";
+	return {
+		name: "pyreon-zero-ssg",
+		apply: "build",
+		enforce: "post",
+		configResolved(resolved) {
+			root = resolved.root;
+			distDir = resolve(root, resolved.build.outDir);
+		},
+		async closeBundle() {
+			if (config.mode !== "ssg") return;
+			if (isInnerBuild) return;
+			const ssrOutDir = join(distDir, ".zero-ssg-server");
+			const indexHtmlPath = join(distDir, "index.html");
+			if (!existsSync(indexHtmlPath)) {
+				console.warn(`[zero:ssg] Skipping SSG — ${indexHtmlPath} not found. Did the client build complete?`);
+				return;
+			}
+			const entryPath = join(root, SSR_ENTRY_FILENAME);
+			await writeFile(entryPath, renderSsrEntrySource(config.i18n?.locales ?? []), "utf-8");
+			const { build } = await import("vite");
+			process.env[SSG_BUILD_FLAG] = "1";
+			try {
+				const [{ zeroPlugin }, pyreonModule] = await Promise.all([Promise.resolve().then(() => vite_plugin_exports), import("@pyreon/vite-plugin")]);
+				const pyreon = pyreonModule.default;
+				await build({
+					root,
+					mode: "production",
+					logLevel: "error",
+					configFile: false,
+					publicDir: false,
+					plugins: [pyreon(), zeroPlugin(userConfig)],
+					resolve: { conditions: ["bun"] },
+					build: {
+						ssr: entryPath,
+						outDir: ssrOutDir,
+						emptyOutDir: true,
+						target: "esnext",
+						rollupOptions: {
+							input: entryPath,
+							output: {
+								format: "es",
+								entryFileNames: "entry-server.mjs"
+							},
+							external: [/^node:/]
+						}
+					}
+				});
+			} finally {
+				delete process.env[SSG_BUILD_FLAG];
+				try {
+					await rm(entryPath, { force: true });
+				} catch {}
+			}
+			const handlerPath = join(ssrOutDir, "entry-server.mjs");
+			if (!existsSync(handlerPath)) {
+				console.warn(`[zero:ssg] SSR build did not produce ${handlerPath} — skipping prerender`);
+				return;
+			}
+			const handlerMod = await import(
+				/* @vite-ignore */
+				pathToFileURL(handlerPath).href
+);
+			const renderPath = handlerMod.default;
+			const registry = handlerMod.__getStaticPathsRegistry;
+			const template = await readFile(indexHtmlPath, "utf-8");
+			const errors = [];
+			const routesDir = join(root, "src", "routes");
+			const paths = await resolvePaths(config, routesDir, registry, errors);
+			if (paths.length === 0) {
+				console.warn("[zero:ssg] No static paths to prerender — set ssg.paths in zero config");
+				await rm(ssrOutDir, {
+					recursive: true,
+					force: true
+				});
+				return;
+			}
+			assertNoPathCollisions(paths);
+			let pages = 0;
+			const redirects = [];
+			const writtenPaths = [];
+			const start = Date.now();
+			const renderOne = async (p) => {
+				if (__DEV__) _countSink.__pyreon_count__?.("ssg.pathRender");
+				try {
+					const result = await Promise.race([renderPath(p), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`Prerender timeout for "${p}" (30s)`)), 3e4))]);
+					if (result.kind === "redirect") {
+						if (__DEV__) _countSink.__pyreon_count__?.("ssg.pathRedirect");
+						redirects.push({
+							from: result.from,
+							to: result.to,
+							status: result.status
+						});
+						if (config.ssg?.redirectsAsHtml === "meta-refresh") {
+							const filePath = resolveOutputPath(distDir, p);
+							if (!isInsideDist(distDir, filePath)) {
+								errors.push({
+									path: p,
+									error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
+								});
+								return;
+							}
+							await mkdir(dirname(filePath), { recursive: true });
+							await writeFile(filePath, renderMetaRefreshHtml(result.to), "utf-8");
+						}
+						return;
+					}
+					const html = injectIntoTemplate(template, result);
+					const filePath = resolveOutputPath(distDir, p);
+					if (!isInsideDist(distDir, filePath)) {
+						errors.push({
+							path: p,
+							error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
+						});
+						return;
+					}
+					await mkdir(dirname(filePath), { recursive: true });
+					await writeFile(filePath, html, "utf-8");
+					pages++;
+					writtenPaths.push(p);
+					if (__DEV__) _countSink.__pyreon_count__?.("ssg.pathWrite");
+				} catch (error) {
+					if (__DEV__) _countSink.__pyreon_count__?.("ssg.pathError");
+					errors.push({
+						path: p,
+						error
+					});
+					if (config.ssg?.onPathError) try {
+						const fallbackHtml = await config.ssg.onPathError(p, error);
+						if (typeof fallbackHtml === "string") {
+							const filePath = resolveOutputPath(distDir, p);
+							if (!isInsideDist(distDir, filePath)) {
+								errors.push({
+									path: p,
+									error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
+								});
+								return;
+							}
+							await mkdir(dirname(filePath), { recursive: true });
+							await writeFile(filePath, fallbackHtml, "utf-8");
+							pages++;
+						}
+					} catch (callbackError) {
+						errors.push({
+							path: `${p} (onPathError)`,
+							error: callbackError
+						});
+					}
+				}
+			};
+			const concurrency = Math.max(1, config.ssg?.concurrency ?? 4);
+			let completed = 0;
+			await runWithConcurrency(paths, concurrency, renderOne, async (p) => {
+				completed++;
+				if (config.ssg?.onProgress) try {
+					await config.ssg.onProgress({
+						completed,
+						total: paths.length,
+						currentPath: p,
+						elapsed: Date.now() - start
+					});
+				} catch (callbackError) {
+					errors.push({
+						path: `${p} (onProgress)`,
+						error: callbackError
+					});
+				}
+			});
+			if (writtenPaths.length > 0) await writeFileAtomic(join(distDir, "_pyreon-ssg-paths.json"), `${JSON.stringify({
+				paths: writtenPaths,
+				...config.i18n ? { i18n: config.i18n } : {}
+			}, null, 2)}\n`);
+			let revalidateCount = 0;
+			if (existsSync(routesDir)) try {
+				const revalidateManifest = buildRevalidateManifest(await scanRouteFilesWithExports(routesDir, config.mode), writtenPaths);
+				revalidateCount = Object.keys(revalidateManifest).length;
+				if (revalidateCount > 0) await writeFileAtomic(join(distDir, "_pyreon-revalidate.json"), `${JSON.stringify({ revalidate: revalidateManifest }, null, 2)}\n`);
+			} catch (err) {
+				errors.push({
+					path: "(revalidate-manifest)",
+					error: err
+				});
+			}
+			let emitted404Count = 0;
+			if (config.ssg?.emit404 !== false && handlerMod.__renderNotFound) {
+				const localeEntries = handlerMod.__notFoundComponentsByLocale instanceof Map ? [...handlerMod.__notFoundComponentsByLocale.keys()] : handlerMod.__notFoundComponent ? [null] : [];
+				for (const locale of localeEntries) try {
+					const result = await Promise.race([handlerMod.__renderNotFound(locale), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`Prerender timeout for ${locale == null ? "404" : `${locale}/404`} (30s)`)), 3e4))]);
+					if (result) {
+						const html = injectIntoTemplate(template, result);
+						const filePath = locale == null ? join(distDir, "404.html") : join(distDir, locale, "404.html");
+						if (locale != null) await mkdir(join(distDir, locale), { recursive: true });
+						await writeFile(filePath, html, "utf-8");
+						emitted404Count++;
+						if (__DEV__) _countSink.__pyreon_count__?.("ssg.404Emit");
+					}
+				} catch (error) {
+					errors.push({
+						path: locale == null ? "404.html" : `${locale}/404.html`,
+						error
+					});
+				}
+			}
+			if (redirects.length > 0 && config.ssg?.emitRedirects !== false) {
+				await writeFileAtomic(join(distDir, "_redirects"), renderNetlifyRedirects(redirects));
+				await writeFileAtomic(join(distDir, "_redirects.json"), renderVercelRedirectsJson(redirects));
+			}
+			if (errors.length > 0 && config.ssg?.errorArtifact !== "none") await writeFileAtomic(join(distDir, "_pyreon-ssg-errors.json"), renderErrorArtifact(errors));
+			const adapter = resolveAdapter(config);
+			try {
+				await adapter.build({
+					kind: "ssg",
+					outDir: distDir,
+					config
+				});
+			} catch (adapterError) {
+				errors.push({
+					path: `(adapter:${adapter.name})`,
+					error: adapterError
+				});
 			}
-		});
+			await rm(ssrOutDir, {
+				recursive: true,
+				force: true
+			});
+			const elapsed = Date.now() - start;
+			const redirectsSummary = redirects.length > 0 ? ` + ${redirects.length} redirect(s)` : "";
+			const concurrencySummary = concurrency > 1 ? ` (concurrency: ${concurrency})` : "";
+			const adapterSummary = adapter.name !== "node" ? ` [adapter: ${adapter.name}]` : "";
+			const revalidateSummary = revalidateCount > 0 ? ` + ${revalidateCount} revalidate path(s)` : "";
+			const localeSummary = config.i18n ? buildLocaleSummary(writtenPaths, config.i18n) : "";
+			console.log(`[zero:ssg] Prerendered ${pages} page(s)${emitted404Count > 0 ? emitted404Count === 1 ? " + 404.html" : ` + ${emitted404Count} 404 pages` : ""}${redirectsSummary}${revalidateSummary} in ${elapsed}ms${concurrencySummary}${adapterSummary}${localeSummary}` + (errors.length > 0 ? ` (${errors.length} error(s))` : ""));
+			for (const { path: errPath, error } of errors) console.error(`[zero:ssg] Failed to prerender "${errPath}":`, error);
+		}
 	};
 }
 //#endregion
-//#region src/vercel-revalidate-handler.ts
+//#region src/vite-plugin.ts
+var vite_plugin_exports = /* @__PURE__ */ __exportAll({
+	argvHasPortFlag: () => argvHasPortFlag,
+	getZeroPluginConfig: () => getZeroPluginConfig,
+	zeroPlugin: () => zeroPlugin
+});
 /**
-* M3.1 — Drop-in Vercel revalidate webhook handler.
-*
-* Pre-M3.1 the `vercelAdapter.revalidate(path)` (PR I) POSTed to
-* `/api/_pyreon-revalidate?path=...&secret=...` — a CONVENTION that users
-* had to implement themselves. This helper scaffolds the convention:
-*
-*     // src/routes/api/_pyreon-revalidate.ts (or `pages/api/...` in
-*     // Next-style apps deployed to Vercel)
-*     export { vercelRevalidateHandler as default } from '@pyreon/zero/server'
-*
-* The handler validates the secret query param against
-* `VERCEL_REVALIDATE_TOKEN`, validates the path is in the build-time
-* revalidate manifest, and calls Vercel's `res.revalidate(path)` API.
-*
-* Returns a standard `(req: Request) => Response` Web API handler — works
-* with Vercel Edge functions, Node serverless functions (via Vercel's
-* `@vercel/node` adapter that bridges Node `req`/`res` to Web standard
-* fetch shapes), and the in-process `mode: 'ssr'` runtime.
-*
-* @example
-* // src/routes/api/_pyreon-revalidate.ts
-* import { vercelRevalidateHandler } from '@pyreon/zero/server'
-*
-* export const POST = vercelRevalidateHandler({
-*   // Optional — defaults to reading `_pyreon-revalidate.json` from cwd.
-*   manifestPath: './dist/_pyreon-revalidate.json',
-* })
+* Scan node_modules/@pyreon/ to discover all installed Pyreon packages.
+* Returns package names to exclude from Vite's dep optimizer.
+*/
+function scanPyreonPackages(root) {
+	const pyreonDir = join(root, "node_modules", "@pyreon");
+	if (!existsSync(pyreonDir)) return [];
+	try {
+		return readdirSync(pyreonDir).filter((name) => !name.startsWith(".")).map((name) => `@pyreon/${name}`);
+	} catch {
+		return [];
+	}
+}
+/**
+* Resolve a package that isn't at the app's top-level `node_modules` but is
+* nested under another `@pyreon/*` package. Used to alias `@pyreon/runtime-server`
+* to the copy under `node_modules/@pyreon/zero/node_modules/@pyreon/runtime-server`
+* so `ssrLoadModule` works without requiring the app to declare it as a
+* direct dep.
+*/
+function resolveNestedPackage(root, name) {
+	const direct = join(root, "node_modules", name);
+	if (existsSync(direct)) return direct;
+	const nested = join(root, "node_modules", "@pyreon", "zero", "node_modules", name);
+	if (existsSync(nested)) return nested;
+}
+const VIRTUAL_ROUTES_ID = "virtual:zero/routes";
+const RESOLVED_VIRTUAL_ROUTES_ID = `\0${VIRTUAL_ROUTES_ID}`;
+const VIRTUAL_MIDDLEWARE_ID = "virtual:zero/route-middleware";
+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.
 *
-* @example
-* // Custom revalidate impl (e.g. for a self-hosted Pyreon SSR runtime
-* // that wants build-time revalidate behavior without Vercel's
-* // `res.revalidate()` API):
-* export const POST = vercelRevalidateHandler({
-*   onRevalidate: async (path) => {
-*     // Clear your in-process ISR cache, emit a metrics event, etc.
-*     await myCache.invalidate(path)
-*   },
-* })
+* 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 = /* @__PURE__ */ new WeakMap();
 /**
-* Create the Web-standard request handler. Reads the manifest once on first
-* invocation (cached in-process) so repeated revalidations don't re-read the
-* file. Manifest read failures cache the failure too — until next process
-* restart, all requests get the same 500 response (signals deploy-time misconfig).
+* 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.
 */
-function vercelRevalidateHandler(options = {}) {
-	const manifestPath = options.manifestPath ?? "./dist/_pyreon-revalidate.json";
-	const secretEnvVar = options.secretEnvVar ?? "VERCEL_REVALIDATE_TOKEN";
-	let cache = null;
-	return async function handler(req) {
-		if (req.method !== "POST") return new Response(`Method ${req.method} not allowed`, { status: 405 });
-		const url = new URL(req.url);
-		const path = url.searchParams.get("path");
-		const secret = url.searchParams.get("secret");
-		if (!path || !secret) return new Response("Bad Request: missing path or secret", { status: 400 });
-		const expected = process.env[secretEnvVar];
-		if (!expected) return new Response(`Server misconfigured: ${secretEnvVar} env var not set`, { status: 500 });
-		if (secret !== expected) return new Response("Forbidden: invalid secret", { status: 403 });
-		if (cache === null) try {
-			const fileContent = await readFile(resolve(process.cwd(), manifestPath), "utf-8");
-			const parsed = JSON.parse(fileContent);
-			if (typeof parsed?.revalidate !== "object" || parsed.revalidate === null) throw new Error(`Malformed revalidate manifest at ${manifestPath}: missing or non-object \`revalidate\` field`);
-			cache = { manifest: parsed };
-		} catch (err) {
-			cache = { error: err };
-		}
-		if ("error" in cache) return new Response(`Server misconfigured: revalidate manifest at ${manifestPath} unreadable or malformed`, { status: 500 });
-		if (!Object.prototype.hasOwnProperty.call(cache.manifest.revalidate, path)) return new Response(`Path "${path}" not in revalidate manifest`, { status: 404 });
-		if (options.onRevalidate) try {
-			await options.onRevalidate(path);
-		} catch (err) {
-			return new Response(`Revalidation failed for "${path}": ${err instanceof Error ? err.message : String(err)}`, { status: 500 });
-		}
-		return new Response(JSON.stringify({
-			revalidated: true,
-			path
-		}), {
-			status: 200,
-			headers: { "Content-Type": "application/json" }
-		});
-	};
+function getZeroPluginConfig(plugin) {
+	return zeroPluginConfigMap.get(plugin);
 }
 /**
-* Reset the in-process manifest cache. Test-only — production code never
-* reaches this. Used by unit tests to exercise the "manifest changed
-* between requests" path without spinning up a new handler.
+* 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
 */
-function _resetVercelRevalidateHandlerCache(handler) {}
-//#endregion
-//#region src/middleware.ts
+function argvHasPortFlag(argv = process.argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--port" || a === "-p") return true;
+		if (a !== void 0 && (a.startsWith("--port=") || a.startsWith("-p="))) return true;
+	}
+	return false;
+}
 /**
-* Compose multiple middleware into a single middleware function.
-* Middleware runs sequentially — if any returns a Response, the chain stops.
+* Zero Vite plugin — adds file-based routing and zero-config conventions
+* on top of @pyreon/vite-plugin.
 *
 * @example
-* import { compose } from "@pyreon/zero/middleware"
-* import { corsMiddleware } from "@pyreon/zero/cors"
-* import { rateLimitMiddleware } from "@pyreon/zero/rate-limit"
+* // vite.config.ts
+* import pyreon from "@pyreon/vite-plugin"
+* import zero from "@pyreon/zero"
 *
-* const combined = compose(
-*   corsMiddleware({ origin: "*" }),
-*   rateLimitMiddleware({ max: 100 }),
-*   cacheMiddleware(),
-* )
+* export default {
+*   plugins: [pyreon(), zero()],
+* }
 */
-function compose(...middlewares) {
-	return async (ctx) => {
-		for (const mw of middlewares) {
-			const result = await mw(ctx);
-			if (result instanceof Response) return result;
+function zeroPlugin(userConfig = {}) {
+	const config = resolveConfig(userConfig);
+	let routesDir;
+	let root;
+	const mainPlugin = {
+		name: "pyreon-zero",
+		enforce: "pre",
+		configResolved(resolvedConfig) {
+			root = resolvedConfig.root;
+			routesDir = `${root}/src/routes`;
+		},
+		resolveId(id) {
+			if (id === VIRTUAL_ROUTES_ID) return RESOLVED_VIRTUAL_ROUTES_ID;
+			if (id === VIRTUAL_MIDDLEWARE_ID) return RESOLVED_VIRTUAL_MIDDLEWARE_ID;
+			if (id === VIRTUAL_API_ROUTES_ID) return RESOLVED_VIRTUAL_API_ROUTES_ID;
+		},
+		async load(id) {
+			if (id === RESOLVED_VIRTUAL_ROUTES_ID) try {
+				const baseRoutes = await scanRouteFilesWithExports(routesDir, config.mode);
+				const routes = config.i18n ? expandRoutesForLocales(baseRoutes, config.i18n) : baseRoutes;
+				const ssgSplitDisabled = config.mode === "ssg" && config.ssg?.splitChunks === false;
+				return generateRouteModuleFromRoutes(routes, routesDir, { staticImports: ssgSplitDisabled });
+			} catch (_err) {
+				return `export const routes = []`;
+			}
+			if (id === RESOLVED_VIRTUAL_MIDDLEWARE_ID) try {
+				return generateMiddlewareModule(await scanRouteFiles(routesDir), routesDir);
+			} catch (_err) {
+				return `export const routeMiddleware = []`;
+			}
+			if (id === RESOLVED_VIRTUAL_API_ROUTES_ID) try {
+				return generateApiRouteModule(await scanRouteFiles(routesDir), routesDir);
+			} catch (_err) {
+				return `export const apiRoutes = []`;
+			}
+		},
+		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				const pathname = req.url?.split("?")[0] ?? "/";
+				if (pathname.startsWith("/@") || pathname.startsWith("/__")) return next();
+				if (/\.\w+$/.test(pathname)) return next();
+				dispatchApiRoute(server, req, res).then((handled) => {
+					if (!handled) next();
+				}, (err) => {
+					console.error("[Pyreon] Error in dev API dispatcher:", err);
+					next();
+				});
+			});
+			if (config.mode === "ssr") server.middlewares.use((req, res, next) => {
+				const accept = req.headers.accept ?? "";
+				if (!accept.includes("text/html") && !accept.includes("*/*")) return next();
+				const pathname = req.url?.split("?")[0] ?? "/";
+				if (pathname.startsWith("/@") || pathname.startsWith("/__")) return next();
+				if (/\.\w+$/.test(pathname)) return next();
+				const reqHost = req.headers.host ?? "localhost";
+				const reqUrl = new URL(req.url ?? "/", `http://${reqHost}`);
+				const reqHeaders = new Headers();
+				for (const [key, value] of Object.entries(req.headers)) if (value !== void 0) reqHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+				const webReq = new Request(reqUrl.href, {
+					method: req.method ?? "GET",
+					headers: reqHeaders
+				});
+				renderSsr(server, root, req.originalUrl ?? pathname, pathname, webReq).then((result) => {
+					if (result === null) return next();
+					res.statusCode = result.status;
+					res.setHeader("Content-Type", "text/html; charset=utf-8");
+					res.setHeader("Content-Length", Buffer.byteLength(result.html));
+					res.end(result.html);
+				}, (err) => {
+					const info = getRedirectInfo(err);
+					if (info) {
+						res.statusCode = info.status;
+						res.setHeader("Location", info.url);
+						res.end();
+						return;
+					}
+					const error = err instanceof Error ? err : new Error(String(err));
+					server.ssrFixStacktrace(error);
+					const html = renderErrorOverlay(error);
+					res.statusCode = 500;
+					res.setHeader("Content-Type", "text/html; charset=utf-8");
+					res.setHeader("Content-Length", Buffer.byteLength(html));
+					res.end(html);
+				});
+			});
+			server.middlewares.use((req, res, next) => {
+				const accept = req.headers.accept ?? "";
+				if (!accept.includes("text/html") && !accept.includes("*/*")) return next();
+				const pathname = req.url?.split("?")[0] ?? "/";
+				if (pathname.startsWith("/@") || pathname.startsWith("/__")) return next();
+				if (/\.\w+$/.test(pathname)) return next();
+				handle404(server, routesDir, pathname, res).then((handled) => {
+					if (!handled) next();
+				}, (err) => {
+					console.error("[Pyreon] Error in 404 handler:", err);
+					next();
+				});
+			});
+			server.middlewares.use((req, res, next) => {
+				if (!(req.headers.accept ?? "").includes("text/html")) return next();
+				const originalEnd = res.end.bind(res);
+				let errored = false;
+				const handleError = (err) => {
+					if (errored) return;
+					errored = true;
+					const error = err instanceof Error ? err : new Error(String(err));
+					server.ssrFixStacktrace(error);
+					const html = renderErrorOverlay(error);
+					res.statusCode = 500;
+					res.setHeader("Content-Type", "text/html; charset=utf-8");
+					res.setHeader("Content-Length", Buffer.byteLength(html));
+					originalEnd(html);
+				};
+				res.on("error", handleError);
+				try {
+					const result = next();
+					if (result && typeof result.catch === "function") result.catch(handleError);
+				} catch (err) {
+					handleError(err);
+				}
+			});
+			server.watcher.add(`${routesDir}/**/*.{tsx,jsx,ts,js}`);
+			server.watcher.on("all", (event, path) => {
+				if (path.startsWith(routesDir) && (event === "add" || event === "unlink")) {
+					for (const resolvedId of [
+						RESOLVED_VIRTUAL_ROUTES_ID,
+						RESOLVED_VIRTUAL_MIDDLEWARE_ID,
+						RESOLVED_VIRTUAL_API_ROUTES_ID
+					]) {
+						const mod = server.moduleGraph.getModuleById(resolvedId);
+						if (mod) server.moduleGraph.invalidateModule(mod);
+					}
+					server.ws.send({ type: "full-reload" });
+				}
+			});
+		},
+		config(viteUserConfig) {
+			const cwd = viteUserConfig.root ?? process.cwd();
+			const pyreonExclude = scanPyreonPackages(cwd);
+			const runtimeServerAlias = resolveNestedPackage(cwd, "@pyreon/runtime-server");
+			return {
+				resolve: {
+					conditions: ["bun"],
+					...runtimeServerAlias ? { alias: { "@pyreon/runtime-server": runtimeServerAlias } } : {}
+				},
+				ssr: { resolve: {
+					conditions: ["bun"],
+					...runtimeServerAlias ? { alias: { "@pyreon/runtime-server": runtimeServerAlias } } : {}
+				} },
+				optimizeDeps: { exclude: pyreonExclude },
+				...userConfig.port === void 0 && argvHasPortFlag() ? {} : { server: { port: config.port } },
+				base: config.base,
+				define: {
+					__ZERO_MODE__: JSON.stringify(config.mode),
+					__ZERO_BASE__: JSON.stringify(config.base)
+				}
+			};
 		}
 	};
+	zeroPluginConfigMap.set(mainPlugin, userConfig);
+	return config.mode === "ssg" ? [mainPlugin, ssgPlugin(userConfig)] : [mainPlugin];
 }
-const ZERO_CTX_KEY = "__zeroCtx";
 /**
-* Get the shared Zero context from a middleware context.
-* Creates one if it doesn't exist. Middleware can use this to
-* pass data to downstream middleware without polluting `ctx.locals`.
+* Dev-mode API-route dispatcher. Loads the `virtual:zero/api-routes` virtual
+* module, builds a Web `Request` from the Node `IncomingMessage`, and invokes
+* the matching route's HTTP-method handler.
 *
-* @example
-* const authMiddleware: Middleware = (ctx) => {
-*   const zctx = getContext(ctx)
-*   zctx.userId = "user_123"
-* }
+* Returns `true` if the API middleware handled the request (response written).
+* Returns `false` if no route matched (caller falls through to next middleware).
 *
-* const loggingMiddleware: Middleware = (ctx) => {
-*   const zctx = getContext(ctx)
-*   console.log("User:", zctx.userId)
-* }
+* Mirrors what `createServer` wires up in production via `createApiMiddleware`,
+* but adapted for Vite's connect-style middleware stack — needs a Node→Web
+* request adapter.
 */
-function getContext(ctx) {
-	let zctx = ctx.locals[ZERO_CTX_KEY];
-	if (!zctx) {
-		zctx = {};
-		ctx.locals[ZERO_CTX_KEY] = zctx;
+async function dispatchApiRoute(server, req, res) {
+	let apiRoutes;
+	try {
+		apiRoutes = (await server.ssrLoadModule(VIRTUAL_API_ROUTES_ID)).apiRoutes ?? [];
+	} catch {
+		return false;
 	}
-	return zctx;
+	if (apiRoutes.length === 0) return false;
+	const host = req.headers.host ?? "localhost";
+	const url = new URL(req.url ?? "/", `http://${host}`);
+	const pathname = url.pathname;
+	if (!apiRoutes.some((r) => matchApiRoute(r.pattern, pathname) !== null)) return false;
+	const method = (req.method ?? "GET").toUpperCase();
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) if (value !== void 0) headers.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+	const requestInit = {
+		method,
+		headers
+	};
+	if (method !== "GET" && method !== "HEAD") {
+		requestInit.body = Readable.toWeb(req);
+		requestInit.duplex = "half";
+	}
+	const webReq = new Request(url.href, requestInit);
+	const response = await createApiMiddleware(apiRoutes)({
+		req: webReq,
+		url,
+		path: pathname + url.search,
+		headers: new Headers(),
+		locals: {}
+	});
+	if (!response) return false;
+	res.statusCode = response.status;
+	response.headers.forEach((v, k) => {
+		res.setHeader(k, v);
+	});
+	if (response.body) Readable.fromWeb(response.body).pipe(res);
+	else res.end();
+	return true;
+}
+/**
+* Static-page 404 fallback for apps WITHOUT `_404.tsx` in the routes tree.
+*
+* 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, _routesDir, pathname, res) {
+	const routes = (await server.ssrLoadModule(VIRTUAL_ROUTES_ID)).routes;
+	if (flattenRoutePatterns(routes).some((pattern) => matchPattern(pattern, pathname))) return false;
+	const html = await render404Page(void 0);
+	res.statusCode = 404;
+	res.setHeader("Content-Type", "text/html; charset=utf-8");
+	res.setHeader("Content-Length", Buffer.byteLength(html));
+	res.end(html);
+	return true;
+}
+/**
+* Dev-mode SSR render pipeline. Returns the composed HTML string, or `null`
+* if the URL doesn't match any known route (caller falls through to the 404
+* middleware). Mirrors the production `createServer` flow:
+*   1. Load virtual:zero/routes + app.ts via Vite's ssrLoadModule
+*   2. Create a per-request router bound to the request URL
+*   3. Pre-run loaders for the matched route(s)
+*   4. Render app tree with head tag collection
+*   5. Serialize loader data into `window.__PYREON_LOADER_DATA__`
+*   6. Inject everything into the user's transformed index.html (so Vite
+*      still gets a chance to inject its HMR client + JSX runtime prelude)
+*/
+async function renderSsr(server, root, originalUrl, pathname, req) {
+	const routes = (await server.ssrLoadModule(VIRTUAL_ROUTES_ID)).routes;
+	let template = await readFile(join(root, "index.html"), "utf-8");
+	template = await server.transformIndexHtml(originalUrl, template);
+	const [core, _headPkg, headSsr, routerPkg, runtimeServer] = await Promise.all([
+		server.ssrLoadModule("@pyreon/core"),
+		server.ssrLoadModule("@pyreon/head"),
+		server.ssrLoadModule("@pyreon/head/ssr"),
+		server.ssrLoadModule("@pyreon/router"),
+		server.ssrLoadModule("@pyreon/runtime-server")
+	]);
+	const { App, router: routerInst } = (await server.ssrLoadModule("@pyreon/zero/server")).createApp({
+		routes,
+		routerMode: "history",
+		url: pathname
+	});
+	await routerInst.preload(pathname, req);
+	const resolved = routerInst.currentRoute();
+	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, null);
+		const { html: appHtml, head } = await headSsr.renderWithHead(app);
+		const loaderData = routerPkg.serializeLoaderData(routerInst);
+		const loaderScript = loaderData && Object.keys(loaderData).length > 0 ? `<script>window.__PYREON_LOADER_DATA__=${routerPkg.stringifyLoaderData(loaderData)}<\/script>` : "";
+		return {
+			html: template.replace("<!--pyreon-head-->", head).replace("<!--pyreon-app-->", appHtml).replace("<!--pyreon-scripts-->", loaderScript),
+			status
+		};
+	});
+}
+/**
+* Extract all URL patterns from a nested route tree.
+*
+* The fs-router emits ABSOLUTE paths for every route, including grandchildren —
+* `{ path: "/app/dashboard" }` not `{ path: "dashboard" }`. The matcher reads
+* each route's `path` as-is; no prefix accumulation. Pre-fix, this function
+* concatenated `${prefix}${route.path}` which produced patterns like
+* `///app/app/dashboard` (prefix `'/app'` + path `'/app/dashboard'`). After
+* `path.split('/').filter(Boolean)` those became `['app', 'app', 'dashboard']`
+* — which can't match a real `/app/dashboard` request — so dev-server returned
+* 404 for every nested-layout route. Re-enables PR #411 specs that rely on
+* `/app/*` routing.
+*/
+function flattenRoutePatterns(routes) {
+	const patterns = [];
+	for (const route of routes) {
+		if (!route.path) continue;
+		patterns.push(route.path);
+		if (route.children) patterns.push(...flattenRoutePatterns(route.children));
+	}
+	return patterns;
 }
 //#endregion
 //#region src/favicon.ts
+/**
+* Stable content hash (FNV-1a, 32-bit) of the favicon source file(s),
+* rendered as a `?v=<hex>` cache-bust query for the injected `<head>`
+* links. Browsers cache favicons extremely aggressively (often per-
+* session / effectively forever), so with a stable URL a changed icon
+* is never re-fetched by returning visitors. Same source bytes →
+* identical query (no needless cache churn); changed bytes → new query
+* → browser re-downloads. Falls back to `''` (no query, prior
+* behaviour) if a source can't be read — never break the build over a
+* cache-bust nicety. NOTE: this versions everything referenced via
+* `<link>` (svg/png/apple-touch/manifest). The bare `/favicon.ico`
+* convention request (browsers fetch it with no link tag) and the
+* `site.webmanifest`'s internal icon entries keep stable URLs — those
+* rely on host cache headers / are re-resolved on PWA (re)install.
+*/
+function faviconVersionQuery(paths) {
+	let h = 2166136261;
+	let any = false;
+	for (const p of paths) {
+		let buf;
+		try {
+			buf = readFileSync(p);
+		} catch {
+			continue;
+		}
+		any = true;
+		for (let i = 0; i < buf.length; i++) {
+			h ^= buf[i];
+			h = Math.imul(h, 16777619);
+		}
+	}
+	if (!any) return "";
+	return `?v=${(h >>> 0).toString(16).padStart(8, "0")}`;
+}
 let sharpWarned$1 = false;
 function warnSharpMissing$1() {
 	if (sharpWarned$1) return;
@@ -315,6 +2832,15 @@ function faviconPlugin(config) {
 	const generateManifest = config.manifest !== false;
 	let root = "";
 	let isBuild = false;
+	let versionQuery = null;
+	function getVersionQuery() {
+		if (versionQuery === null) {
+			const paths = [join(root, config.source)];
+			if (config.darkSource) paths.push(join(root, config.darkSource));
+			versionQuery = faviconVersionQuery(paths);
+		}
+		return versionQuery;
+	}
 	return {
 		name: "pyreon-zero-favicon",
 		enforce: "pre",
@@ -335,11 +2861,25 @@ function faviconPlugin(config) {
 				return defaultSource;
 			}
 			server.middlewares.use(async (req, res, next) => {
-				const url = req.url ?? "";
+				const url = (req.url ?? "").split("?")[0];
 				const localeSource = resolveLocaleSource(url, config, root);
 				const svgUrl = localeSource ? localeSource.url : url;
 				const svgPath = localeSource ? localeSource.sourcePath : sourcePath;
 				const isSvgSource = localeSource ? localeSource.source.endsWith(".svg") : config.source.endsWith(".svg");
+				if (isSvgSource && (svgUrl.endsWith("/favicon-light.svg") || svgUrl.endsWith("/favicon-dark.svg"))) {
+					const isDarkVariant = svgUrl.endsWith("/favicon-dark.svg");
+					const variantPath = isDarkVariant ? darkPath ?? svgPath : svgPath;
+					try {
+						let content = await readFile(variantPath, "utf-8");
+						if (!isDarkVariant) {
+							if (autoDevBadge) content = addDevBadgeToSvg(content);
+							else if (devSourcePath && existsSync(devSourcePath)) content = await readFile(devSourcePath, "utf-8");
+						}
+						res.setHeader("Content-Type", "image/svg+xml");
+						res.end(content);
+						return;
+					} catch {}
+				}
 				if (svgUrl.endsWith("/favicon.svg") && isSvgSource) try {
 					let content = await readFile(svgPath, "utf-8");
 					if (autoDevBadge) content = addDevBadgeToSvg(content);
@@ -416,7 +2956,27 @@ function faviconPlugin(config) {
 			const isSvg = config.source.endsWith(".svg");
 			const hasDark = !!config.darkSource;
 			const tags = [];
-			if (isSvg) tags.push({
+			if (isSvg && hasDark) tags.push({
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-light.svg",
+					"data-favicon-theme": "light"
+				},
+				injectTo: "head"
+			}, {
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-dark.svg",
+					"data-favicon-theme": "dark",
+					media: "not all"
+				},
+				injectTo: "head"
+			});
+			else if (isSvg) tags.push({
 				tag: "link",
 				attrs: {
 					rel: "icon",
@@ -539,10 +3099,21 @@ function faviconPlugin(config) {
 				injectTo: "head",
 				children: `(function(){try{var t=localStorage.getItem("zero-theme");var r=t==="light"?"light":t==="dark"?"dark":window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light";document.querySelectorAll("[data-favicon-theme]").forEach(function(l){l.media=l.dataset.faviconTheme===r?"":"not all"})}catch(e){}})()`
 			});
+			const v = getVersionQuery();
+			if (v) {
+				for (const t of tags) if (t.tag === "link" && t.attrs.href) t.attrs.href += v;
+			}
 			return tags;
 		},
 		async generateBundle() {
 			if (!isBuild) return;
+			try {
+				await import("sharp");
+			} catch {
+				this.error(`[Pyreon] faviconPlugin: a favicon \`source\` is configured but \`sharp\` is not installed — NO favicons would be generated and the production build would silently ship none.
+  Fix:    bun add -D sharp   (or: npm i -D sharp)
+  Source: ${config.source}\nTo intentionally build without favicons, remove faviconPlugin() from your Vite plugins.`);
+			}
 			await generateFaviconSet.call(this, root, config.source, config.darkSource, "", config, themeColor, backgroundColor, generateManifest);
 			if (config.locales) for (const [locale, localeConfig] of Object.entries(config.locales)) await generateFaviconSet.call(this, root, localeConfig.source, localeConfig.darkSource, `${locale}/`, config, themeColor, backgroundColor, generateManifest);
 		}
@@ -597,7 +3168,20 @@ async function generateFaviconSet(rootDir, source, darkSource, prefix, config, t
 		let finalSvg = svgContent;
 		if (darkSource) {
 			const darkPath = join(rootDir, darkSource);
-			if (existsSync(darkPath)) finalSvg = wrapSvgWithDarkMode(svgContent, await readFile(darkPath, "utf-8"));
+			if (existsSync(darkPath)) {
+				const darkSvg = await readFile(darkPath, "utf-8");
+				finalSvg = wrapSvgWithDarkMode(svgContent, darkSvg);
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-light.svg`,
+					source: svgContent
+				});
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-dark.svg`,
+					source: darkSvg
+				});
+			}
 		}
 		this.emitFile({
 			type: "asset",
@@ -687,8 +3271,21 @@ function faviconLinks(locale, config) {
 	const hasLocaleOverride = locale && config.locales?.[locale];
 	const prefix = hasLocaleOverride ? `/${locale}` : "";
 	const isSvg = (hasLocaleOverride ? config.locales[locale].source : config.source).endsWith(".svg");
+	const hasDark = !!config.darkSource;
 	const links = [];
-	if (isSvg) links.push({
+	if (isSvg && hasDark) links.push({
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-light.svg`,
+		"data-favicon-theme": "light"
+	}, {
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-dark.svg`,
+		"data-favicon-theme": "dark",
+		media: "not all"
+	});
+	else if (isSvg) links.push({
 		rel: "icon",
 		type: "image/svg+xml",
 		href: `${prefix}/favicon.svg`
@@ -1253,7 +3850,7 @@ function seoPlugin(config = {}) {
 		},
 		async generateBundle(_, _bundle) {
 			if (config.sitemap && !useSsgPaths) {
-				const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
+				const { scanRouteFiles } = await import("./fs-router-Bacdhsq-.js").then((n) => n.n);
 				const routesDir = `${process.cwd()}/src/routes`;
 				try {
 					const files = await scanRouteFiles(routesDir);
@@ -1277,7 +3874,7 @@ function seoPlugin(config = {}) {
 		},
 		async closeBundle() {
 			if (!config.sitemap || !useSsgPaths) return;
-			const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
+			const { scanRouteFiles } = await import("./fs-router-Bacdhsq-.js").then((n) => n.n);
 			const routesDir = `${process.cwd()}/src/routes`;
 			const manifestPath = join(distDir, "_pyreon-ssg-paths.json");
 			try {
@@ -1315,7 +3912,7 @@ function seoMiddleware(config = {}) {
 	return async (ctx) => {
 		if (ctx.url.pathname === "/robots.txt" && config.robots) return new Response(generateRobots(config.robots), { headers: { "Content-Type": "text/plain" } });
 		if (ctx.url.pathname === "/sitemap.xml" && config.sitemap) try {
-			const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
+			const { scanRouteFiles } = await import("./fs-router-Bacdhsq-.js").then((n) => n.n);
 			const sitemap = generateSitemap(await scanRouteFiles(`${process.cwd()}/src/routes`), config.sitemap);
 			return new Response(sitemap, { headers: { "Content-Type": "application/xml" } });
 		} catch {}