@pyreon/zero 0.15.0 → 0.18.0

package/lib/types/config.d.ts

@@ -1,5 +1,18 @@
 import { Middleware } from "@pyreon/server";
-
+//#region src/i18n-routing.d.ts
+interface I18nRoutingConfig {
+  /** Supported locales. e.g. ["en", "de", "cs"] */
+  locales: string[];
+  /** Default locale — served without prefix (/ instead of /en/). */
+  defaultLocale: string;
+  /** Redirect root to detected locale. Default: true */
+  detectLocale?: boolean;
+  /** Cookie name to persist locale preference. Default: "locale" */
+  cookieName?: string;
+  /** URL strategy. Default: "prefix-except-default" */
+  strategy?: 'prefix' | 'prefix-except-default';
+}
+//#endregion
 //#region src/types.d.ts
 type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr';
 interface ISRConfig {
@@ -12,6 +25,42 @@ interface ISRConfig {
    * space (e.g. `/user/:id` where `:id` is free-form).
    */
   maxEntries?: number;
+  /**
+   * Cache-key derivation function. The default keys cache entries by
+   * `url.pathname` ONLY — query strings, cookies, and headers are
+   * stripped.
+   *
+   * **⚠️ Auth-gated incompatibility.** The default behavior is
+   * unsafe for request-dependent loaders. A loader that reads
+   * `request.headers.get('cookie')` to gate auth will render ONCE
+   * with the first user's cookie, then serve that HTML to every
+   * subsequent user. To use ISR with personalized / auth-gated
+   * pages, supply a `cacheKey` that varies on the auth identifier
+   * (session cookie, user-id header, etc.), OR don't use ISR for
+   * such routes — use SSR instead.
+   *
+   * @example
+   * // Vary cache by session cookie:
+   * isr: {
+   *   revalidate: 60,
+   *   cacheKey: (req) => {
+   *     const url = new URL(req.url)
+   *     const session = req.headers.get('cookie')?.match(/session=([^;]+)/)?.[1] ?? 'anon'
+   *     return `${url.pathname}::${session}`
+   *   },
+   * }
+   *
+   * @example
+   * // Vary by a query parameter:
+   * isr: {
+   *   revalidate: 60,
+   *   cacheKey: (req) => {
+   *     const url = new URL(req.url)
+   *     return `${url.pathname}?sort=${url.searchParams.get('sort') ?? ''}`
+   *   },
+   * }
+   */
+  cacheKey?: (req: Request) => string;
 }
 interface ZeroConfig {
   /** Default rendering mode. Default: "ssr" */
@@ -25,18 +74,273 @@ interface ZeroConfig {
   /** SSG options — only used when mode is "ssg". */
   ssg?: {
     /** Paths to prerender (or function returning paths). */paths?: string[] | (() => string[] | Promise<string[]>);
+    /**
+     * Auto-emit `dist/404.html` from the route tree's `_404.tsx` /
+     * `_not-found.tsx` convention. fs-router already wires `_404.tsx` as
+     * `notFoundComponent` on its parent layout route; the SSG plugin walks
+     * the tree, picks up the first one, renders it through the same SSR
+     * pipeline as regular paths (so styler CSS / @pyreon/head metadata land
+     * correctly), and writes the result to `dist/404.html`. Static hosts
+     * (Netlify, Cloudflare Pages, GitHub Pages, S3+CloudFront) serve this
+     * file automatically for unmatched URLs. Default: `true`. Set to
+     * `false` to opt out — the route tree is left alone.
+     */
+    emit404?: boolean;
+    /**
+     * When a route loader throws `redirect('/target')` during SSG, write
+     * a `dist/_redirects` file (Netlify / Cloudflare Pages convention)
+     * AND a `dist/_redirects.json` (Vercel convention) listing every
+     * redirected source path → target. Static hosts pick whichever
+     * format their platform supports automatically. The redirected
+     * path's HTML file is NOT emitted — the redirect is the response.
+     *
+     * Without this option, redirect-throwing loaders land in
+     * `errors[]` and the path silently disappears from the build —
+     * the user sees no output for `/old` AND no warning that the
+     * loader ran a redirect. Default: `true`. Set to `false` to
+     * restore the pre-PR-B behaviour (redirects treated as errors).
+     */
+    emitRedirects?: boolean;
+    /**
+     * Additionally emit a static HTML file at the source path with a
+     * `<meta http-equiv="refresh">` redirect — for adapters / hosts
+     * that don't read `_redirects` (plain S3, GitHub Pages, simple
+     * file servers). The meta-refresh fallback works on any HTTP
+     * server that serves static files.
+     *
+     * - `'none'` (default): only `_redirects` / `_redirects.json` are
+     *   emitted; no per-redirect HTML file.
+     * - `'meta-refresh'`: emit `dist/<source>/index.html` containing
+     *   `<meta http-equiv="refresh" content="0; url=<target>">` plus
+     *   a canonical link tag for SEO. Status code information is
+     *   lost (meta-refresh has no status equivalent), so 301/302/307/
+     *   308 all collapse to "client-side refresh".
+     */
+    redirectsAsHtml?: 'none' | 'meta-refresh';
+    /**
+     * Callback invoked when a path's render throws (loader-throw that
+     * isn't a `redirect()`, render exception, anything that lands in the
+     * `errors[]` collection). Returns either:
+     * - `string` → written as the path's HTML in place of the failed
+     *   render. Use this to emit a per-path fallback page (e.g. a generic
+     *   "this content is temporarily unavailable" template) so static
+     *   hosts have something to serve at that URL instead of 404'ing.
+     * - `null` → skip; the path produces no HTML output. The error
+     *   stays in `errors[]` for the post-build summary.
+     *
+     * The callback runs ONCE per failed path. Async callbacks are
+     * awaited. If the callback itself throws, the throw is captured as
+     * a separate error entry and the path is skipped (no fallback HTML).
+     * Default: `undefined` — failed paths just land in `errors[]`.
+     *
+     * @example
+     * ssg: {
+     *   onPathError: async (path, error) => {
+     *     console.error(\`SSG render failed for \${path}:\`, error)
+     *     return \`<!DOCTYPE html><html><body><h1>Page unavailable</h1></body></html>\`
+     *   },
+     * }
+     */
+    onPathError?: (path: string, error: unknown) => string | null | Promise<string | null>;
+    /**
+     * When `'json'` (default), write `dist/_pyreon-ssg-errors.json` after
+     * the render loop summarising every error encountered (path traversal,
+     * timeout, render exception, getStaticPaths throw, fallback callback
+     * throw). Each entry has `{ path, message, name, stack }`. The file
+     * is ONLY written when `errors.length > 0` — successful builds don't
+     * leak an empty manifest. Reading it lets CI gate on render failures
+     * without parsing console output (e.g.
+     * `cat dist/_pyreon-ssg-errors.json | jq '.errors | length' | grep -q 0`).
+     *
+     * Set to `'none'` to opt out entirely — errors stay in console-only,
+     * matching pre-PR-G behaviour.
+     */
+    errorArtifact?: 'json' | 'none';
+    /**
+     * Maximum number of paths rendered in parallel during the SSG closeBundle
+     * loop. Default: `4` — a sensible balance between speedup and the risk
+     * of exhausting downstream resources (DB connection pools, fetch
+     * rate-limits) inside loaders. Set to `1` to render fully sequentially
+     * (the pre-PR-D behaviour). Set to a higher value for faster builds
+     * on CI / multi-core hosts; the practical ceiling is the number of
+     * loader-side concurrent connections your app's data layer tolerates.
+     *
+     * The render-error pipeline (`onPathError` callback, `errors[]`
+     * collection, `_pyreon-ssg-errors.json` artifact) is unchanged —
+     * concurrency only affects how many paths are in flight at once,
+     * not how their successes / failures are recorded.
+     *
+     * @example
+     * ssg: {
+     *   concurrency: 8, // Faster builds for static-content sites
+     * }
+     */
+    concurrency?: number;
+    /**
+     * Per-path progress callback. Invoked once per path AFTER its render
+     * settles (success, redirect, OR failure) — never during in-flight
+     * renders. Receives `{ completed, total, currentPath, elapsed }`
+     * where:
+     *   - `completed` is the count of paths whose render has settled (1-indexed)
+     *   - `total` is the full path count from `resolvePaths()`
+     *   - `currentPath` is the path that just settled
+     *   - `elapsed` is wall-clock ms since the loop started
+     *
+     * Use cases: build-tool progress bars (Vite picks up stdout), CI
+     * heartbeat lines on long builds (10k-path sites take minutes —
+     * silent stretches look hung), build-time perf instrumentation.
+     *
+     * Async callbacks are awaited before the next path's progress fires,
+     * so a slow callback can serialize progress reporting (it does NOT
+     * gate the worker pool — paths keep rendering in parallel; only
+     * the progress callbacks themselves are serialized). Throws are
+     * captured into `errors[]` with the path suffix `(onProgress)` so
+     * a buggy callback can't take down the build.
+     *
+     * @example
+     * ssg: {
+     *   onProgress: ({ completed, total, currentPath, elapsed }) => {
+     *     console.log(`[${completed}/${total}] ${currentPath} (${elapsed}ms)`)
+     *   },
+     * }
+     */
+    onProgress?: (info: {
+      completed: number;
+      total: number;
+      currentPath: string;
+      elapsed: number;
+    }) => void | Promise<void>;
+    /**
+     * Route-level code splitting in SSG mode. Default `true`.
+     *
+     * When `true` (default), each route file becomes its own dynamic-import
+     * chunk via `lazy(() => import("..."))` — only the route the user
+     * lands on plus its dependencies ship in the initial bundle, the
+     * rest fetch on navigation. Matches the SSR/SPA-mode behaviour zero
+     * has always had; brings parity to SSG.
+     *
+     * When `false`, every route is bundled statically into the main
+     * client chunk (the pre-2026-Q3 SSG behaviour). Useful for tiny
+     * sites (2-5 pages) where the single-chunk-then-instant-nav trade
+     * is preferable — the chunk-fetch cost on navigation is gone, and
+     * the marginal bytes are negligible.
+     *
+     * Crossover point: ~5-8 routes. Below that, single-chunk is fine.
+     * Above that, lazy() shrinks the initial bundle by a meaningful
+     * amount (a 50-route docs site might drop from 200 KB to 80 KB on
+     * first paint).
+     *
+     * Underlying mechanism is the same 3-tier generator zero already
+     * uses for SSR/SPA mode (`fs-router.ts:generateRouteEntry`): lazy
+     * component + inlined metadata when possible, lazy + lazy-thunked
+     * function exports when not, namespace-import fallback for cases
+     * the literal-extractor can't reach.
+     *
+     * @example
+     * ssg: {
+     *   splitChunks: false, // bundle-everything for a 3-page marketing site
+     * }
+     */
+    splitChunks?: boolean;
   };
   /** ISR config — only used when mode is "isr". */
   isr?: ISRConfig;
-  /** Deploy adapter. Default: "node" */
-  adapter?: 'node' | 'bun' | 'static' | 'vercel' | 'cloudflare' | 'netlify';
+  /**
+   * Deploy adapter. Default: `"node"`.
+   *
+   * Accepts either a built-in adapter name (string) OR a constructed
+   * `Adapter` instance (e.g. `vercelAdapter()`). The scaffolded templates
+   * emit the instance form (`adapter: vercelAdapter()`) by convention.
+   * `resolveAdapter` (see `adapters/index.ts`) accepts both shapes —
+   * strings go through a switch lookup, instances pass through
+   * unchanged.
+   */
+  adapter?: 'node' | 'bun' | 'static' | 'vercel' | 'cloudflare' | 'netlify' | Adapter;
   /** Base URL path. Default: "/" */
   base?: string;
+  /**
+   * i18n routing — locale-prefixed route variants generated at build time
+   * (PR H of the SSG roadmap). When set, every `FileRoute` is fanned into
+   * per-locale duplicates by `expandRoutesForLocales` from
+   * `@pyreon/zero`. Independent from the `i18nRouting()` Vite plugin
+   * (which only handles request-time locale detection); both can be used
+   * together. See `expandRoutesForLocales` JSDoc for strategy semantics.
+   */
+  i18n?: I18nRoutingConfig;
   /** App-level middleware applied to all routes. */
   middleware?: Middleware[];
   /** Server port for dev/preview. Default: 3000 */
   port?: number;
 }
+interface Adapter {
+  name: string;
+  /** Build the production server/output for this adapter. */
+  build(options: AdapterBuildOptions): Promise<void>;
+  /**
+   * Revalidate a prerendered path on the deploy platform's ISR layer
+   * (PR I — build-time ISR). Called by user code (webhook handlers,
+   * cron jobs, CMS triggers, etc.) to trigger a rebuild-on-stale for
+   * the named path. Optional — adapters without platform ISR support
+   * (static, node, bun) implement a no-op. Returns `{ regenerated:
+   * boolean }` so user code can branch on whether the platform actually
+   * accepted the revalidation request.
+   *
+   * Distinct from runtime ISR (`mode: 'isr'`, on-demand LRU caching in
+   * `@pyreon/zero/server`'s `createISRHandler`). Build-time ISR is
+   * static prerender + platform-driven rebuild-on-stale; runtime ISR is
+   * SSR-cached-with-TTL. They can coexist.
+   *
+   * Per-route `revalidate` metadata flows from `export const revalidate
+   * = 60` in route files into a `dist/_pyreon-revalidate.json` manifest
+   * the adapter reads at deploy time. Adapters use that manifest to
+   * configure platform ISR (Vercel `output/config.json`, Cloudflare
+   * Cache API rules, Netlify revalidation headers).
+   */
+  revalidate?(path: string): Promise<AdapterRevalidateResult>;
+}
+/**
+ * Result of `Adapter.revalidate(path)`. `regenerated: false` means the
+ * adapter does not support platform ISR (no-op fallback) OR the
+ * platform rejected the request. Adapters that throw on platform-API
+ * failure should let it propagate so user code can handle the rejection.
+ */
+interface AdapterRevalidateResult {
+  regenerated: boolean;
+}
+/**
+ * Inputs the build pipeline passes to an adapter's `build()` method.
+ *
+ * The `kind` field discriminates the two shapes. **SSR mode** (`'ssr'`)
+ * carries `serverEntry` + `clientOutDir` so adapters can wrap the user's
+ * server bundle as a serverless function. **SSG mode** (`'ssg'`) carries
+ * only `outDir` (which IS the rendered dist/) — no serverEntry exists
+ * because every page is already prerendered. SSG-mode adapters write
+ * platform-specific routing config so the host knows the deploy is
+ * fully-static (no function invocation per request).
+ *
+ * Pre-PR-J this was a single SSR-shaped struct; the SSG path had no way
+ * to invoke `adapter.build()` because it couldn't supply `serverEntry`.
+ * Adding `kind` (with TS-narrowing per branch) lets `ssgPlugin`
+ * `closeBundle` call `adapter.build({ kind: 'ssg', outDir, config })`
+ * cleanly, AND keeps the SSR-mode adapter implementations unchanged.
+ */
+type AdapterBuildOptions = {
+  kind: 'ssr'; /** Path to the built server entry. */
+  serverEntry: string; /** Path to the client build output. */
+  clientOutDir: string; /** Final output directory. */
+  outDir: string;
+  config: ZeroConfig;
+} | {
+  kind: 'ssg';
+  /**
+   * The rendered dist directory. For SSG, this directory IS the
+   * publishable output — adapters write platform-specific routing
+   * config alongside (e.g. `.vercel/output/config.json`,
+   * `_routes.json`, `netlify.toml`) but generally don't move files.
+   */
+  outDir: string;
+  config: ZeroConfig;
+};
 //#endregion
 //#region src/config.d.ts
 /**

package/lib/types/env.d.ts

@@ -81,7 +81,7 @@ type InferEnvSchema<T> = { [K in keyof T]: InferEntry<T[K]> };
  * })
  * ```
  */
-declare function validateEnv<T extends Record<string, SchemaEntry>>(schema: T, source?: Record<string, string | undefined>): InferEnvSchema<T>;
+declare function validateEnv<T extends Record<string, SchemaEntry>>(envSchema: T, source?: Record<string, string | undefined>): InferEnvSchema<T>;
 /**
  * Extract public environment variables (prefixed with `ZERO_PUBLIC_`).
  *
@@ -95,7 +95,7 @@ declare function validateEnv<T extends Record<string, SchemaEntry>>(schema: T, s
  * ```
  */
 declare function publicEnv(): Record<string, string>;
-declare function publicEnv<T extends Record<string, SchemaEntry>>(schema: T): InferEnvSchema<T>;
+declare function publicEnv<T extends Record<string, SchemaEntry>>(envSchema: T): InferEnvSchema<T>;
 /**
  * Create an env validator from a custom parse function.
  * Use this to integrate any schema library (Zod, Valibot, ArkType, etc.).

package/lib/types/i18n-routing.d.ts

@@ -1,7 +1,133 @@
 import * as _$_pyreon_core0 from "@pyreon/core";
 import * as _$_pyreon_reactivity0 from "@pyreon/reactivity";
 import { Plugin } from "vite";
-
+//#region src/types.d.ts
+type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr';
+/**
+ * Which optional metadata exports a route file declares.
+ * Detected at scan time by parsing the file source. The code generator
+ * uses this to skip emitting `import * as mod` for routes that only
+ * export `default`, eliminating the dual-import collision with `lazy()`
+ * and silencing `IMPORT_IS_UNDEFINED` warnings from Rolldown.
+ */
+interface RouteFileExports {
+  /** Has `export const loader` or `export function loader` */
+  hasLoader: boolean;
+  /** Has `export const guard` or `export function guard` */
+  hasGuard: boolean;
+  /** Has `export const meta` */
+  hasMeta: boolean;
+  /** Has `export const renderMode` */
+  hasRenderMode: boolean;
+  /** Has `export const error` (custom per-route error component) */
+  hasError: boolean;
+  /** Has `export const middleware` */
+  hasMiddleware: boolean;
+  /**
+   * Has `export const loaderKey` or `export function loaderKey`. When present,
+   * the route generator wires it as the `loaderKey` field on the route record,
+   * which controls cache identity for `_loaderCache`. Useful for auth-gate
+   * loaders that should invalidate when the session cookie changes — read
+   * `document.cookie` (CSR) or `ctx.request.headers.get('cookie')` (SSR) and
+   * derive a key from session identity. Default cache key is `path + params`,
+   * which doesn't see cookie changes.
+   */
+  hasLoaderKey: boolean;
+  /**
+   * Has `export const gcTime` (number, in ms). When present, the route generator
+   * inlines it on the route record. `gcTime: 0` disables caching entirely —
+   * the loader runs on every navigation. Useful for auth-gate loaders that
+   * must validate session on every navigation rather than serve stale data.
+   */
+  hasGcTime: boolean;
+  /**
+   * Has `export function getStaticPaths` or `export const getStaticPaths`.
+   * Used at SSG build time to enumerate concrete values for dynamic routes
+   * (`/posts/[id].tsx` → `[/posts/1, /posts/2, …]`). The function returns
+   * `Array<{ params: Record<string, string> }>`. Mirrors Astro's per-route
+   * convention. Without it, dynamic routes are silently skipped during SSG
+   * auto-detect — the user must hand-list every value in `ssg.paths`.
+   */
+  hasGetStaticPaths: boolean;
+  /**
+   * Has `export const revalidate` (number, in seconds, or `false` for
+   * never-revalidate). PR I — build-time ISR. The SSG plugin emits a
+   * `dist/_pyreon-revalidate.json` manifest mapping `{ path: revalidate }`
+   * which the deploy adapter (Vercel / Cloudflare / Netlify) consumes
+   * to wire platform-specific ISR rebuild-on-stale. The route generator
+   * does NOT inline `revalidate` onto the route record — it's a
+   * build-time-only concern that never reaches the runtime router.
+   */
+  hasRevalidate: boolean;
+  /**
+   * Raw text of the `export const meta = …` initializer, captured as a
+   * literal expression. When present, the route generator inlines this
+   * value directly into the generated routes module instead of importing
+   * it from the route file — which means the route file can be lazy()'d
+   * without forcing the entire dependency tree into the main bundle.
+   *
+   * Only set when the meta export is a top-level `export const meta = { … }`
+   * literal that can be extracted via balanced-brace scanning. Anything
+   * fancier (computed values, function calls, references to other
+   * declarations) leaves this undefined and falls back to a static module
+   * import.
+   */
+  metaLiteral?: string;
+  /**
+   * Raw text of the `export const renderMode = …` initializer, captured
+   * as a literal expression. Same inlining strategy as `metaLiteral`.
+   */
+  renderModeLiteral?: string;
+  /**
+   * Raw text of the `export const revalidate = …` initializer (e.g.
+   * `'60'`, `'false'`, `'3600'`). Captured at scan time so the SSG
+   * plugin can read the value to emit the build-time ISR manifest
+   * WITHOUT loading the route module — which is critical because the
+   * manifest is emitted from the synthetic SSR build's outer plugin
+   * context, where evaluating route modules would re-trigger the
+   * recursive sub-build env-flag guard.
+   *
+   * Only set when the revalidate export is a top-level
+   * `export const revalidate = <numeric|boolean literal>` that passes
+   * `isPureLiteral`. Anything else (function calls, references to
+   * other declarations) leaves this undefined and the manifest falls
+   * back to omitting the entry.
+   */
+  revalidateLiteral?: string;
+}
+/** Internal representation of a file-system route before conversion to RouteRecord. */
+interface FileRoute {
+  /** File path relative to routes dir (e.g. "users/[id].tsx") */
+  filePath: string;
+  /** Parsed URL path pattern (e.g. "/users/:id") */
+  urlPath: string;
+  /** Directory path for grouping (e.g. "users" or "" for root) */
+  dirPath: string;
+  /** Route segment depth for nesting. */
+  depth: number;
+  /** Whether this is a layout file. */
+  isLayout: boolean;
+  /** Whether this is an error boundary file. */
+  isError: boolean;
+  /** Whether this is a loading fallback file. */
+  isLoading: boolean;
+  /** Whether this is a not-found (404) file. */
+  isNotFound: boolean;
+  /** Whether this is a catch-all route. */
+  isCatchAll: boolean;
+  /** Resolved rendering mode. */
+  renderMode: RenderMode;
+  /**
+   * Detected optional exports from the file source.
+   * When undefined, the generator treats the file as having no metadata
+   * exports and emits the optimal `lazy()` shape (one dynamic import,
+   * no static metadata wiring). When provided, the generator emits a
+   * single namespace import for files with metadata or `lazy()` for
+   * files with only a default export.
+   */
+  exports?: RouteFileExports;
+}
+//#endregion
 //#region src/i18n-routing.d.ts
 interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */
@@ -46,6 +172,71 @@ declare function extractLocaleFromPath(path: string, locales: string[], defaultL
  * Build a localized path.
  */
 declare function buildLocalePath(path: string, locale: string, defaultLocale: string, strategy: 'prefix' | 'prefix-except-default'): string;
+/**
+ * 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.
+ */
+declare function expandRoutesForLocales(routes: FileRoute[], config: I18nRoutingConfig): FileRoute[];
+/**
+ * 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.
+ */
+declare function validateLocale(locale: string): void;
 /**
  * Create a LocaleContext for use in components and loaders.
  */
@@ -100,5 +291,5 @@ declare function useLocale(): string;
  */
 declare function setLocale(locale: string, config: I18nRoutingConfig): void;
 //#endregion
-export { I18nRoutingConfig, LocaleContext, LocaleCtx, buildLocalePath, createLocaleContext, detectLocaleFromHeader, extractLocaleFromPath, i18nRouting, localeSignal, setLocale, useLocale };
+export { I18nRoutingConfig, LocaleContext, LocaleCtx, buildLocalePath, createLocaleContext, detectLocaleFromHeader, expandRoutesForLocales, extractLocaleFromPath, i18nRouting, localeSignal, setLocale, useLocale, validateLocale };
 //# sourceMappingURL=i18n-routing2.d.ts.map