@pyreon/zero 0.15.0 → 0.18.0

package/lib/types/server.d.ts

@@ -4,6 +4,7 @@ import * as _$_pyreon_router0 from "@pyreon/router";
 import { RouteRecord } from "@pyreon/router";
 import { Middleware, MiddlewareContext } from "@pyreon/server";
 import { Plugin } from "vite";
+
 //#region src/app.d.ts
 interface CreateAppOptions {
   /** Route definitions (from file-based routing or manual). */
@@ -16,6 +17,18 @@ interface CreateAppOptions {
   layout?: ComponentFn;
   /** Global error component. */
   errorComponent?: ComponentFn;
+  /**
+   * Base URL prefix for the deployed app (e.g. `/blog/`). Forwarded to
+   * `createRouter({ base })` so RouterLinks render correctly prefixed
+   * hrefs (`<a href="/blog/about">` instead of `<a href="/about">`) and
+   * the router strips the prefix from incoming URLs before matching.
+   *
+   * Default: `'/'`. Pre-fix this was disconnected from `zero({ base })`
+   * — RouterLinks rendered un-prefixed hrefs even when Vite's asset URL
+   * rewriting was correctly using the prefix, causing client-side
+   * navigation to break against subpath deploys.
+   */
+  base?: string;
 }
 /**
  * Create a full Zero app — assembles router, head provider, and root layout.
@@ -61,6 +74,66 @@ interface ApiRouteEntry {
   module: ApiRouteModule;
 }
 //#endregion
+//#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';
+}
+interface LocaleContext {
+  /** Current locale code. e.g. "en", "de" */
+  locale: string;
+  /** All supported locales. */
+  locales: string[];
+  /** Default locale. */
+  defaultLocale: string;
+  /** Build a localized path. e.g. localePath("/about", "de") → "/de/about" */
+  localePath: (path: string, locale?: string) => string;
+  /** Get hreflang alternates for the current path. */
+  alternates: () => Array<{
+    locale: string;
+    url: string;
+  }>;
+}
+/**
+ * Detect preferred locale from Accept-Language header.
+ */
+declare function detectLocaleFromHeader(acceptLanguage: string | null | undefined, locales: string[], defaultLocale: string): string;
+/**
+ * Create a LocaleContext for use in components and loaders.
+ */
+declare function createLocaleContext(locale: string, path: string, config: I18nRoutingConfig): LocaleContext;
+/**
+ * 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",
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function i18nRouting(config: I18nRoutingConfig): Plugin;
+//#endregion
 //#region src/types.d.ts
 type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr';
 interface ISRConfig {
@@ -73,6 +146,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" */
@@ -86,13 +195,199 @@ 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 */
@@ -135,6 +430,25 @@ interface RouteFileExports {
    * 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
@@ -154,6 +468,22 @@ interface RouteFileExports {
    * 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 {
@@ -196,16 +526,71 @@ 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>;
 }
-interface AdapterBuildOptions {
-  /** Path to the built server entry. */
-  serverEntry: string;
-  /** Path to the client build output. */
-  clientOutDir: string;
-  /** Final output directory. */
+/**
+ * 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/entry-server.d.ts
 interface CreateServerOptions {
@@ -257,6 +642,33 @@ declare function defineConfig(config: ZeroConfig): ZeroConfig;
 declare function resolveConfig(userConfig?: ZeroConfig): Required<Pick<ZeroConfig, 'mode' | 'base' | 'port' | 'adapter'>> & ZeroConfig;
 //#endregion
 //#region src/fs-router.d.ts
+/**
+ * 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`.
+ */
+type GetStaticPaths<TParams extends Record<string, string> = Record<string, string>> = () => Array<{
+  params: TParams;
+}> | Promise<Array<{
+  params: TParams;
+}>>;
 /**
  * Parse a set of file paths (relative to routes dir) into FileRoute objects.
  *
@@ -328,9 +740,97 @@ declare function scanRouteFiles(routesDir: string): Promise<string[]>;
  */
 declare function createISRHandler(handler: (req: Request) => Promise<Response>, config: ISRConfig): (req: Request) => Promise<Response>;
 //#endregion
+//#region src/vercel-revalidate-handler.d.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)
+ *   },
+ * })
+ */
+interface VercelRevalidateHandlerOptions {
+  /**
+   * Absolute or cwd-relative path to the `_pyreon-revalidate.json` manifest.
+   * Defaults to `./dist/_pyreon-revalidate.json` (the standard SSG output).
+   *
+   * The handler refuses to revalidate paths NOT in this manifest — protects
+   * against arbitrary-path revalidation attacks even when the secret leaks.
+   */
+  manifestPath?: string;
+  /**
+   * Custom revalidation impl. Defaults to calling Vercel's `res.revalidate()`
+   * API via the dynamic `@vercel/node`-bridged response object on globalThis
+   * (Vercel injects it for serverless functions).
+   *
+   * Supply this when running OUTSIDE Vercel (self-hosted SSR with a custom
+   * in-process ISR cache, edge runtimes that have their own purge API, etc.).
+   * Receives the validated path; throw to signal failure (handler returns 500).
+   */
+  onRevalidate?: (path: string) => void | Promise<void>;
+  /**
+   * Override the env-var name the handler reads the secret from. Default
+   * `VERCEL_REVALIDATE_TOKEN` matches the adapter's `revalidate()` write.
+   * Useful when adopting the helper outside Vercel and the production
+   * webhook uses a different secret name.
+   */
+  secretEnvVar?: string;
+}
+/**
+ * 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).
+ */
+declare function vercelRevalidateHandler(options?: VercelRevalidateHandlerOptions): (req: Request) => Promise<Response>;
+/**
+ * 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
+ */
+declare function _resetVercelRevalidateHandlerCache(handler: (req: Request) => Promise<Response>): void;
+//#endregion
 //#region src/adapters/bun.d.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.
  */
 declare function bunAdapter(): Adapter;
 //#endregion
@@ -384,6 +884,11 @@ declare function netlifyAdapter(): Adapter;
 //#region src/adapters/node.d.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.
  */
 declare function nodeAdapter(): Adapter;
 //#endregion
@@ -391,6 +896,15 @@ declare function nodeAdapter(): Adapter;
 /**
  * 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".
  */
 declare function staticAdapter(): Adapter;
 //#endregion
@@ -419,6 +933,16 @@ declare function vercelAdapter(): Adapter;
 /**
  * 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.
  */
 declare function resolveAdapter(config: ZeroConfig): Adapter;
 //#endregion
@@ -465,6 +989,12 @@ declare function compose(...middlewares: Middleware[]): Middleware;
 declare function getContext(ctx: MiddlewareContext): Record<string, unknown>;
 //#endregion
 //#region src/vite-plugin.d.ts
+/**
+ * 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.
+ */
+declare function getZeroPluginConfig(plugin: Plugin): ZeroConfig | undefined;
 /**
  * Zero Vite plugin — adds file-based routing and zero-config conventions
  * on top of @pyreon/vite-plugin.
@@ -588,6 +1118,62 @@ interface SitemapConfig {
   priority?: number;
   /** Additional URLs to include (for dynamic routes). */
   additionalPaths?: SitemapEntry[];
+  /**
+   * When `true` AND the build is running in SSG mode, the sitemap reads
+   * the resolved-paths manifest emitted by the SSG plugin
+   * (`dist/_pyreon-ssg-paths.json`) and includes EVERY prerendered URL —
+   * including dynamic routes enumerated via `getStaticPaths` (PR A) and
+   * per-locale variants (PR H, when shipped). Without this flag the
+   * sitemap walks the file-system route tree directly and silently
+   * skips dynamic routes (`[id]` / `[...slug]`) because their concrete
+   * values aren't knowable without running each route's enumerator.
+   *
+   * Sequencing: when `true`, sitemap.xml emission moves from Vite's
+   * `generateBundle` hook (where the SSG plugin's path enumeration
+   * hasn't run yet) to `closeBundle` with `enforce: 'post'` so it
+   * runs AFTER the SSG plugin. The user must ensure `seoPlugin()` is
+   * placed AFTER `zero()` in the Vite plugin array (the canonical
+   * ordering — `closeBundle` hooks fire in plugin-registration order).
+   *
+   * Falls back gracefully: when the manifest doesn't exist (mode is
+   * not `ssg`, or the SSG step was skipped), the sitemap still walks
+   * the file-system routes — same shape as without this flag.
+   *
+   * Default: `false` (preserves prior behaviour). Set `true` for SSG
+   * sites that ship dynamic-route enumerations.
+   */
+  useSsgPaths?: boolean;
+  /**
+   * Emit `<xhtml:link rel="alternate" hreflang="...">` cross-references
+   * inside each `<url>` entry, declaring the locale variants of every
+   * page (PR K — i18n follow-up).
+   *
+   * Accepts:
+   *   - `true` — read the i18n config from the SSG paths manifest
+   *     (which `zero({ i18n: ... })` automatically embeds when SSG runs).
+   *     Zero-config win — declare i18n once, sitemap picks it up.
+   *   - `I18nRoutingConfig` — pass the i18n config explicitly. Use when
+   *     the project doesn't run SSG (file-scan sitemap path) but still
+   *     wants hreflang in the emitted sitemap.
+   *   - `false` / omitted — no hreflang, plain `<url>` entries.
+   *
+   * The emitted shape per page-cluster is the Google-recommended form:
+   *
+   *   <url>
+   *     <loc>https://example.com/about</loc>
+   *     <xhtml:link rel="alternate" hreflang="en" href="https://example.com/about"/>
+   *     <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/about"/>
+   *     <xhtml:link rel="alternate" hreflang="cs" href="https://example.com/cs/about"/>
+   *     <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about"/>
+   *   </url>
+   *
+   * The `x-default` entry points at the default-locale URL so search
+   * engines have a fallback when the user's language doesn't match any
+   * of the configured locales. URLs are clustered by their un-prefixed
+   * (default-locale) form — `/about`, `/de/about`, `/cs/about` collapse
+   * into ONE `<url>` entry with three `xhtml:link` siblings.
+   */
+  hreflang?: boolean | I18nRoutingConfig;
 }
 interface SitemapEntry {
   path: string;
@@ -598,8 +1184,14 @@ interface SitemapEntry {
 type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
 /**
  * Generate a sitemap.xml string from route file paths.
+ *
+ * When `i18n` is set (PR K — passed by `seoPlugin` after reading the
+ * i18n config from `zero({ i18n: ... })`), URLs are clustered by their
+ * un-prefixed (default-locale) form and each `<url>` carries
+ * `<xhtml:link rel="alternate" hreflang="...">` siblings for every
+ * locale variant + an `x-default` entry pointing at the default locale.
  */
-declare function generateSitemap(routeFiles: string[], config: SitemapConfig): string;
+declare function generateSitemap(routeFiles: string[], config: SitemapConfig, i18n?: I18nRoutingConfig): string;
 interface RobotsConfig {
   /** Rules per user-agent. */
   rules?: RobotsRule[];
@@ -649,7 +1241,10 @@ interface SeoPluginConfig {
  *     pyreon(),
  *     zero(),
  *     seoPlugin({
- *       sitemap: { origin: "https://example.com" },
+ *       sitemap: {
+ *         origin: "https://example.com",
+ *         useSsgPaths: true, // include dynamic-route enumerations
+ *       },
  *       robots: { sitemap: "https://example.com/sitemap.xml" },
  *     }),
  *   ],
@@ -904,65 +1499,5 @@ declare function inferJsonLd(options: InferJsonLdOptions): Record<string, unknow
  */
 declare function aiPlugin(config: AiPluginConfig): Plugin;
 //#endregion
-//#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';
-}
-interface LocaleContext {
-  /** Current locale code. e.g. "en", "de" */
-  locale: string;
-  /** All supported locales. */
-  locales: string[];
-  /** Default locale. */
-  defaultLocale: string;
-  /** Build a localized path. e.g. localePath("/about", "de") → "/de/about" */
-  localePath: (path: string, locale?: string) => string;
-  /** Get hreflang alternates for the current path. */
-  alternates: () => Array<{
-    locale: string;
-    url: string;
-  }>;
-}
-/**
- * Detect preferred locale from Accept-Language header.
- */
-declare function detectLocaleFromHeader(acceptLanguage: string | null | undefined, locales: string[], defaultLocale: string): string;
-/**
- * Create a LocaleContext for use in components and loaders.
- */
-declare function createLocaleContext(locale: string, path: string, config: I18nRoutingConfig): LocaleContext;
-/**
- * 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",
- *     }),
- *   ],
- * })
- * ```
- */
-declare function i18nRouting(config: I18nRoutingConfig): Plugin;
-//#endregion
-export { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type InferJsonLdOptions, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, aiPlugin, bunAdapter, cloudflareAdapter, compose, createApp, createISRHandler, createLocaleContext, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateRobots, generateRouteModule, generateSitemap, getContext, i18nRouting, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter };
+export { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type GetStaticPaths, type InferJsonLdOptions, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, type VercelRevalidateHandlerOptions, _resetVercelRevalidateHandlerCache, aiPlugin, bunAdapter, cloudflareAdapter, compose, createApp, createISRHandler, createLocaleContext, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateRobots, generateRouteModule, generateSitemap, getContext, getZeroPluginConfig, i18nRouting, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter, vercelRevalidateHandler };
 //# sourceMappingURL=server2.d.ts.map