@pyreon/zero 0.15.0 → 0.18.0

package/src/entry-server.ts

@@ -123,6 +123,11 @@ export function createServer(options: CreateServerOptions) {
 	const { App } = createApp({
 		routes: options.routes,
 		routerMode: "history",
+		// Forward zero's `base` to createRouter so RouterLinks render
+		// correctly prefixed hrefs during SSR — must match the value
+		// the client-side `startClient` reads from `__ZERO_BASE__` so
+		// hydration doesn't mismatch.
+		...(config.base && config.base !== "/" ? { base: config.base } : {}),
 	});
 
 	const handler = createHandler({
@@ -134,18 +139,40 @@ export function createServer(options: CreateServerOptions) {
 		...(options.clientEntry ? { clientEntry: options.clientEntry } : {}),
 	});
 
-	// Wrap handler with 404 detection when a notFoundComponent is provided
+	// M1.2 — Runtime SSR 404 routes through the router (PR L5).
+	// When a URL doesn't match any leaf, @pyreon/router's resolveRoute
+	// walks up to the closest parent `notFoundComponent` and builds a
+	// synthetic chain `[...ancestorLayouts, syntheticLeaf]`. The handler
+	// renders that chain, producing 404 HTML INSIDE the layout's chrome,
+	// and reads `resolved.isNotFound` to set HTTP status 404. This
+	// replaces the pre-M1 URL-pattern wrapper that bypassed the router
+	// for unmatched URLs and rendered the not-found component standalone
+	// (no layout wrapping).
+	//
+	// `options.notFoundComponent` is a legacy fallback for apps that
+	// don't carry `_404.tsx` in their routes tree. When set AND the
+	// routes tree has no reachable `notFoundComponent`, we render the
+	// standalone shape as a final fallback. The canonical pattern is
+	// `_404.tsx` inside a `_layout.tsx` directory — that goes through
+	// PR L5's router-driven path and gets layout chrome for free.
 	if (!options.notFoundComponent) return handler;
 
 	const NotFound = options.notFoundComponent;
-	const routePatterns = flattenRoutePatterns(options.routes);
+	const hasRouteTreeNotFound = routeTreeHasNotFound(options.routes);
 
 	return async (req: Request) => {
+		// Route-tree notFoundComponent present → handler handles 404 via
+		// resolveRoute's `isNotFound` fallback (PR L5). Skip the legacy
+		// wrapper entirely — handler.ts sets status 404 + renders layout
+		// chrome correctly.
+		if (hasRouteTreeNotFound) return handler(req);
+
+		// Legacy fallback: routes tree has no notFoundComponent but the
+		// caller passed `options.notFoundComponent`. Run the URL-pattern
+		// check + standalone render for backward compat.
 		const url = new URL(req.url);
 		const pathname = url.pathname;
-
-		// Check if any defined route matches this path
-		if (!routePatterns.some((pattern) => matchPattern(pattern, pathname))) {
+		if (!routePatternsCache(options.routes).some((p) => matchPattern(p, pathname))) {
 			const fullHtml = await render404Page(NotFound, options.template);
 			return new Response(fullHtml, {
 				status: 404,
@@ -157,6 +184,29 @@ export function createServer(options: CreateServerOptions) {
 	};
 }
 
+/** Walk the route tree looking for any record with a `notFoundComponent`. */
+function routeTreeHasNotFound(routes: RouteRecord[]): boolean {
+	for (const r of routes) {
+		if (typeof (r as { notFoundComponent?: unknown }).notFoundComponent === "function") {
+			return true;
+		}
+		if (r.children && routeTreeHasNotFound(r.children as RouteRecord[])) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** Lazy cache of flattened patterns — only computed if legacy fallback fires. */
+const _routePatternsCache = new WeakMap<RouteRecord[], string[]>();
+function routePatternsCache(routes: RouteRecord[]): string[] {
+	const cached = _routePatternsCache.get(routes);
+	if (cached) return cached;
+	const out = flattenRoutePatterns(routes);
+	_routePatternsCache.set(routes, out);
+	return out;
+}
+
 /** Extract all URL patterns from a nested route tree. */
 function flattenRoutePatterns(routes: RouteRecord[], prefix = ""): string[] {
 	const patterns: string[] = [];

package/src/env.ts

@@ -244,14 +244,14 @@ type InferEnvSchema<T> = {
  * ```
  */
 export function validateEnv<T extends Record<string, SchemaEntry>>(
-  schema: T,
+  envSchema: T,
   source?: Record<string, string | undefined>,
 ): InferEnvSchema<T> {
   const env = source ?? (typeof process !== 'undefined' ? process.env : {})
   const result: Record<string, unknown> = {}
   const errors: string[] = []
 
-  for (const [key, entry] of Object.entries(schema)) {
+  for (const [key, entry] of Object.entries(envSchema)) {
     const validator = toValidator(entry)
     try {
       result[key] = validator.parse(env[key], key)
@@ -284,12 +284,12 @@ export function validateEnv<T extends Record<string, SchemaEntry>>(
  * ```
  */
 export function publicEnv(): Record<string, string>
-export function publicEnv<T extends Record<string, SchemaEntry>>(schema: T): InferEnvSchema<T>
-export function publicEnv(schema?: Record<string, SchemaEntry>): Record<string, unknown> {
+export function publicEnv<T extends Record<string, SchemaEntry>>(envSchema: T): InferEnvSchema<T>
+export function publicEnv(envSchema?: Record<string, SchemaEntry>): Record<string, unknown> {
   const prefix = 'ZERO_PUBLIC_'
   const env = typeof process !== 'undefined' ? process.env : {}
 
-  if (!schema) {
+  if (!envSchema) {
     const result: Record<string, string> = {}
     for (const [key, value] of Object.entries(env)) {
       if (key.startsWith(prefix) && value !== undefined) {
@@ -300,10 +300,10 @@ export function publicEnv(schema?: Record<string, SchemaEntry>): Record<string,
   }
 
   const prefixedSource: Record<string, string | undefined> = {}
-  for (const key of Object.keys(schema)) {
+  for (const key of Object.keys(envSchema)) {
     prefixedSource[key] = env[`${prefix}${key}`]
   }
-  return validateEnv(schema, prefixedSource)
+  return validateEnv(envSchema, prefixedSource)
 }
 
 // ─── Custom validator escape hatch ──────────────────────────────────────────

package/src/font.ts

@@ -159,11 +159,11 @@ export function parseGoogleFamily(input: string): ResolvedFont {
       for (const entry of entries) {
         if (entry.includes(',')) {
           // Tuple format: "0,300" or "1,500" — last value is the weight
-          const parts = entry.split(',')
-          const weight = Number(parts[parts.length - 1])
+          const tuple = entry.split(',')
+          const weight = Number(tuple[tuple.length - 1])
           if (weight > 0) weights.add(weight)
           // Detect italic from tuple: "1,xxx" means italic
-          if (parts[0] === '1') italic = true
+          if (tuple[0] === '1') italic = true
         } else if (entry.includes('..')) {
           // Variable range already handled above — skip
         } else {

package/src/fs-router.ts

@@ -2,6 +2,34 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { FileRoute, RenderMode, RouteFileExports } from './types'
 
+/**
+ * Return type of a route file's `getStaticPaths()` export. Each entry
+ * supplies one set of concrete values for the route's dynamic segments;
+ * the SSG plugin expands the route's URL pattern with these params and
+ * renders one HTML file per entry.
+ *
+ * @example
+ * ```tsx
+ * // src/routes/posts/[id].tsx
+ * import type { GetStaticPaths } from '@pyreon/zero/server'
+ *
+ * export const getStaticPaths: GetStaticPaths<{ id: string }> = async () => {
+ *   const posts = await fetch('https://api.example.com/posts').then(r => r.json())
+ *   return posts.map((p) => ({ params: { id: p.slug } }))
+ * }
+ *
+ * export default function Post() { ... }
+ * ```
+ *
+ * For catch-all routes (`/blog/[...slug].tsx`), pass the full path through
+ * the catch-all param: `{ params: { slug: 'a/b' } }` → `/blog/a/b`.
+ */
+export type GetStaticPaths<
+  TParams extends Record<string, string> = Record<string, string>,
+> = () =>
+  | Array<{ params: TParams }>
+  | Promise<Array<{ params: TParams }>>
+
 // ─── File-system route conventions ──────────────────────────────────────────
 //
 // src/routes/
@@ -42,6 +70,8 @@ const ROUTE_EXPORT_NAMES = [
   'middleware',
   'loaderKey',
   'gcTime',
+  'getStaticPaths',
+  'revalidate',
 ] as const
 
 type RouteExportName = (typeof ROUTE_EXPORT_NAMES)[number]
@@ -102,12 +132,27 @@ export function detectRouteExports(source: string): RouteFileExports {
   const rawRenderMode = found.has('renderMode')
     ? extractLiteralExport(source, 'renderMode')
     : undefined
+  // PR I — capture `revalidate` as a literal so the build-time ISR
+  // manifest (`dist/_pyreon-revalidate.json`) can be emitted from the
+  // SSG plugin without loading the route module. The route generator
+  // does NOT inline `revalidate` into the route record — it's a build-
+  // time-only concern that adapters consume via the manifest.
+  const rawRevalidate = found.has('revalidate')
+    ? extractLiteralExport(source, 'revalidate')
+    : undefined
   const cleanMeta = rawMeta !== undefined ? stripTypeAssertions(rawMeta) : undefined
   const cleanRenderMode =
     rawRenderMode !== undefined ? stripTypeAssertions(rawRenderMode) : undefined
+  const cleanRevalidate =
+    rawRevalidate !== undefined ? stripTypeAssertions(rawRevalidate) : undefined
   const metaLiteral = cleanMeta !== undefined && isPureLiteral(cleanMeta) ? cleanMeta : undefined
   const renderModeLiteral =
     cleanRenderMode !== undefined && isPureLiteral(cleanRenderMode) ? cleanRenderMode : undefined
+  // `revalidate` literals are number (`60`) or boolean (`false`) — never
+  // an object/array — so `isPureLiteral` is overkill. Keep the same
+  // safety check for defense-in-depth.
+  const revalidateLiteral =
+    cleanRevalidate !== undefined && isPureLiteral(cleanRevalidate) ? cleanRevalidate : undefined
 
   return {
     hasLoader: found.has('loader'),
@@ -118,8 +163,11 @@ export function detectRouteExports(source: string): RouteFileExports {
     hasMiddleware: found.has('middleware'),
     hasLoaderKey: found.has('loaderKey'),
     hasGcTime: found.has('gcTime'),
+    hasGetStaticPaths: found.has('getStaticPaths'),
+    hasRevalidate: found.has('revalidate'),
     ...(metaLiteral !== undefined ? { metaLiteral } : {}),
     ...(renderModeLiteral !== undefined ? { renderModeLiteral } : {}),
+    ...(revalidateLiteral !== undefined ? { revalidateLiteral } : {}),
   }
 }
 
@@ -751,6 +799,8 @@ const EMPTY_EXPORTS: RouteFileExports = {
   hasMiddleware: false,
   hasLoaderKey: false,
   hasGcTime: false,
+  hasGetStaticPaths: false,
+  hasRevalidate: false,
 }
 
 /**
@@ -767,7 +817,8 @@ export function hasAnyMetaExport(exports: RouteFileExports): boolean {
     exports.hasError ||
     exports.hasMiddleware ||
     exports.hasLoaderKey ||
-    exports.hasGcTime
+    exports.hasGcTime ||
+    exports.hasGetStaticPaths
   )
 }
 
@@ -1095,6 +1146,8 @@ export function generateRouteModuleFromRoutes(
         if (exp.hasGuard) props.push(`${indent}  beforeEnter: ${mod}.guard`)
         if (exp.hasLoaderKey) props.push(`${indent}  loaderKey: ${mod}.loaderKey`)
         if (exp.hasGcTime) props.push(`${indent}  gcTime: ${mod}.gcTime`)
+        if (exp.hasGetStaticPaths)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
         if (exp.hasMeta || exp.hasRenderMode) {
           const metaParts: string[] = []
           if (exp.hasMeta) metaParts.push(`...${mod}.meta`)
@@ -1132,7 +1185,13 @@ export function generateRouteModuleFromRoutes(
       const inlineableMeta =
         (!exp.hasMeta || exp.metaLiteral !== undefined) &&
         (!exp.hasRenderMode || exp.renderModeLiteral !== undefined)
-      const needsFunctionExports = exp.hasLoader || exp.hasGuard || exp.hasError
+      // getStaticPaths is a build-time export consumed by the SSG plugin's
+      // path-resolution phase. Like loader/guard/error, it can't be inlined
+      // as a literal — we need the actual function reference. Force the
+      // generator into the mixed branch (case 2) when present so a namespace
+      // import is emitted and `mod.getStaticPaths` lands on the route record.
+      const needsFunctionExports =
+        exp.hasLoader || exp.hasGuard || exp.hasError || exp.hasGetStaticPaths
 
       if (hasMeta && inlineableMeta && !needsFunctionExports) {
         // Optimal path — component lazy, metadata inlined.
@@ -1174,6 +1233,15 @@ export function generateRouteModuleFromRoutes(
           const mod = nextModuleImport(page.filePath)
           props.push(`${indent}  gcTime: ${mod}.gcTime`)
         }
+        if (exp.hasGetStaticPaths) {
+          // getStaticPaths runs at SSG build time (not request time), so
+          // routing it through a dynamic import is fine — but going through
+          // a namespace import keeps it consistent with loaderKey/gcTime
+          // and avoids per-call import overhead during the SSG enumeration
+          // phase.
+          const mod = nextModuleImport(page.filePath)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
+        }
         emitInlineMeta(exp, props, indent)
         if (errorName) {
           // For error components we can't easily await — pass the lazy
@@ -1195,6 +1263,8 @@ export function generateRouteModuleFromRoutes(
         if (exp.hasGuard) props.push(`${indent}  beforeEnter: ${mod}.guard`)
         if (exp.hasLoaderKey) props.push(`${indent}  loaderKey: ${mod}.loaderKey`)
         if (exp.hasGcTime) props.push(`${indent}  gcTime: ${mod}.gcTime`)
+        if (exp.hasGetStaticPaths)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
         if (exp.hasMeta || exp.hasRenderMode) {
           const metaParts: string[] = []
           if (exp.hasMeta) metaParts.push(`...${mod}.meta`)
@@ -1341,7 +1411,6 @@ export function generateRouteModuleFromRoutes(
  * skipping no-middleware files keeps both paths working.
  */
 export function generateMiddlewareModule(files: string[], routesDir: string): string {
-  const { readFileSync } = require('node:fs') as typeof import('node:fs')
   const routes = parseFileRoutes(files)
   const imports: string[] = []
   const entries: string[] = []

package/src/i18n-routing.ts

@@ -1,19 +1,39 @@
 import { createContext } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import type { Plugin } from 'vite'
+import type { FileRoute } from './types'
 
 // ─── Localized routing ─────────────────────────────────────────────────────
 //
-// Adds locale-prefixed routes to Zero's file-system router:
-// - /about → /en/about, /de/about, /cs/about
-// - / → /en, /de, /cs (or default locale without prefix)
-// - Automatic locale detection from Accept-Language header
-// - Redirect to preferred locale
-// - hreflang link generation
+// Adds locale-prefixed routes to Zero's file-system router (PR H of the SSG
+// roadmap). Two complementary halves:
+//
+// 1. **Build-time route duplication** — `expandRoutesForLocales(routes, config)`
+//    fans every `FileRoute` into per-locale variants according to the
+//    configured `strategy`. Called from `vite-plugin.ts`'s virtual-routes
+//    load AND `ssg-plugin.ts`'s pre-render path expansion. Wired via the
+//    `i18n?: I18nRoutingConfig` field on `ZeroConfig`.
+//
+// 2. **Request-time locale detection** — the `i18nRouting()` Vite plugin
+//    below attaches a middleware that reads `Accept-Language` / cookies,
+//    sets the `localeSignal` for `useLocale()`, and redirects root
+//    requests to the detected locale. Independent from (1) — `i18nRouting()`
+//    only handles middleware; route duplication happens via
+//    `expandRoutesForLocales` regardless of whether this plugin is mounted.
+//
+// Examples (with `locales: ["en","de","cs"]`, `defaultLocale: "en"`):
+// - `prefix-except-default` (default): `/about` (en, unprefixed) +
+//   `/de/about`, `/cs/about`. Best for SEO-on-default-locale apps.
+// - `prefix`: `/en/about`, `/de/about`, `/cs/about`. Every URL
+//   self-identifies its locale.
 //
 // Usage:
-//   import { i18nRouting } from "@pyreon/zero"
-//   export default { plugins: [Pyreon], defaultLocale: "en" })] }
+//   // zero.config.ts
+//   import { defineConfig, i18nRouting } from "@pyreon/zero"
+//   export default defineConfig({
+//     i18n: { locales: ["en","de","cs"], defaultLocale: "en" },
+//     plugins: [i18nRouting({ locales: ["en","de","cs"], defaultLocale: "en" })],
+//   })
 
 export interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */
@@ -108,6 +128,218 @@ export function buildLocalePath(
   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.
+ */
+export function expandRoutesForLocales(
+  routes: FileRoute[],
+  config: I18nRoutingConfig,
+): FileRoute[] {
+  const strategy = config.strategy ?? 'prefix-except-default'
+  const { locales, defaultLocale } = config
+
+  // Cheap no-op guards. Empty `locales` would otherwise produce an empty
+  // route array, killing the app silently.
+  if (locales.length === 0) return routes
+
+  // PR L2 — Validate every locale string before they reach the filesystem.
+  // The locales drive both URL pattern emission (`/${locale}/...`) AND
+  // filesystem writes (`mkdir(dist/${locale})` in ssg-plugin.ts's per-
+  // locale 404 emit). User-supplied input with `/`, `..`, `\`, NUL, or
+  // leading dots could write outside dist OR produce broken URLs.
+  // Validate at the single entry point so every downstream consumer
+  // (vite-plugin's virtual-routes load AND ssg-plugin's path expansion)
+  // benefits from one check.
+  //
+  // Reject:
+  //   - empty string (kills the app silently with no usable URLs)
+  //   - leading/trailing whitespace (URL-malformed)
+  //   - `/` or `\` (path traversal AND structurally invalid as a URL
+  //     segment — `/de/sub/about` would split into nested directories)
+  //   - `..` or `.` whole-string (path traversal)
+  //   - NUL char (system-call boundary breaks)
+  //   - leading `.` (hidden directory; macOS/Linux dotfile pattern that
+  //     would create `dist/.locale/` invisible to most ls outputs)
+  //
+  // Runs AFTER the empty-locales no-op guard so apps temporarily
+  // toggling to `i18n: { locales: [], ... }` (mid-migration shape)
+  // don't trip on an unused defaultLocale.
+  for (const locale of locales) validateLocale(locale)
+  validateLocale(defaultLocale)
+  if (
+    strategy === 'prefix-except-default'
+    && locales.length === 1
+    && locales[0] === defaultLocale
+  ) {
+    return routes
+  }
+
+  const expanded: FileRoute[] = []
+  for (const route of routes) {
+    for (const locale of locales) {
+      // For prefix-except-default, the default locale uses the ORIGINAL
+      // urlPath / dirPath / depth — no prefix applied.
+      if (strategy === 'prefix-except-default' && locale === defaultLocale) {
+        expanded.push(route)
+        continue
+      }
+
+      // PR H follow-up: skip duplication of ROOT-level layouts under
+      // `prefix-except-default`. The unprefixed default-locale root
+      // `_layout.tsx` (urlPath `/`) is the parent of the matched chain
+      // for EVERY path, including locale-prefixed ones — the route
+      // tree's hierarchical matching wraps `/de/about` under `/_layout`
+      // automatically. Producing a duplicate `/de/_layout` would cause
+      // the matcher to nest BOTH layouts (`/_layout` → `/de/_layout` →
+      // page), mounting the layout component twice and rendering two
+      // navbars / two PyreonUI providers.
+      //
+      // Non-root layouts (e.g. `/dashboard/_layout` at urlPath
+      // `/dashboard`) MUST still be duplicated — `/de/dashboard/users`
+      // is NOT a child of the unprefixed `/dashboard/_layout` (the
+      // path patterns don't match), so the de-prefixed dashboard needs
+      // its own `_layout`.
+      //
+      // Under `prefix` strategy this skip does NOT apply: there is no
+      // unprefixed default to inherit from, so every locale needs its
+      // own root layout (`/en/_layout`, `/de/_layout`, …).
+      if (
+        strategy === 'prefix-except-default'
+        && route.isLayout
+        && route.urlPath === '/'
+      ) {
+        continue
+      }
+
+      const newUrlPath = prefixUrlPath(route.urlPath, locale)
+      // dirPath needs the locale segment too so the route-tree builder
+      // groups localized siblings correctly. Original empty `dirPath`
+      // (root-level routes) becomes the bare locale.
+      const newDirPath = route.dirPath === '' ? locale : `${locale}/${route.dirPath}`
+      // Recompute depth from the new urlPath. Layouts at the root (depth
+      // 0) become depth 1 under their locale prefix; nested routes shift
+      // up by 1.
+      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: string, locale: string): string {
+  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.
+ */
+export function validateLocale(locale: string): void {
+  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.
  */
@@ -176,10 +408,12 @@ export function i18nRouting(config: I18nRoutingConfig): Plugin {
   return {
     name: 'pyreon-zero-i18n-routing',
 
-    // Route duplication is NOT handled here. The fs-router's `scanRouteFiles`
-    // consumes the i18n config to duplicate routes per locale at build time.
-    // This plugin only provides: (1) the server middleware for locale detection
-    // and (2) the runtime hooks (useLocale, setLocale) for client-side use.
+    // Route duplication is NOT handled here. It happens in
+    // `vite-plugin.ts` and `ssg-plugin.ts` via `expandRoutesForLocales`,
+    // gated by the `i18n` field on `ZeroConfig`. This plugin only
+    // provides: (1) the dev server middleware for locale detection
+    // (Accept-Language, cookies, root redirect) and (2) the runtime
+    // hooks (useLocale, setLocale) for client-side use.
     configResolved() {},
 
     configureServer(server) {