@pyreon/zero 0.15.0 → 0.16.0

package/lib/types/index.d.ts

@@ -1,5 +1,5 @@
 import * as _$_pyreon_core0 from "@pyreon/core";
-import { ComponentFn, VNodeChild } from "@pyreon/core";
+import { ComponentFn, Ref, VNodeChild } from "@pyreon/core";
 import * as _$_pyreon_reactivity0 from "@pyreon/reactivity";
 import { LoaderContext, NavigationGuard } from "@pyreon/router";
 import { Middleware } from "@pyreon/server";
@@ -47,6 +47,9 @@ interface ImageProps {
    * Raw mode — renders a plain `<img>` without the container div,
    * aspect-ratio, max-width, or lazy loading wrapper.
    * Use when the Image is inside a custom layout (absolute positioning, etc.).
+   *
+   * Note: `raw` skips the three-layer API entirely. `useImage` / `createImage`
+   * do not apply when `raw: true` — the component returns a bare `<img>`.
    */
   raw?: boolean;
 }
@@ -54,9 +57,106 @@ interface ImageSource {
   src: string;
   width: number;
 }
+/** Return type of {@link useImage}. */
+interface UseImageReturn {
+  /** Ref — attach to the container element for IntersectionObserver. */
+  containerRef: Ref<HTMLElement>;
+  /** Whether the image has entered the viewport (and started loading). */
+  inView: () => boolean;
+  /** Whether the `<img>` onLoad has fired. */
+  loaded: () => boolean;
+  /** Resolved `src` accessor — empty string until inView, then `props.src`. */
+  src: () => string;
+  /** Resolved srcSet accessor — empty until inView; empty when `formats` is set (srcset moves to `<source>` elements). */
+  srcSet: () => string;
+  /** `sizes` attribute or undefined when no srcset. */
+  sizes: string | undefined;
+  /** `aspect-ratio` CSS value (`"${width} / ${height}"`). */
+  aspectRatio: string;
+  /** Resolved CSS for the container — position + overflow + aspect-ratio + max-width + caller's `style`. */
+  containerStyle: string;
+  /** Resolved CSS accessor for the `<img>` — fit + transition + opacity (placeholder fade). */
+  imageStyle: () => string;
+  /** Resolved CSS accessor for the placeholder `<img>` (only meaningful when `placeholder` is set). */
+  placeholderStyle: () => string;
+  /** `loading` attribute — eager when priority/eager, else lazy. */
+  loading: 'lazy' | 'eager';
+  /** `fetchPriority` — 'high' when priority, else undefined. */
+  fetchPriority: 'high' | undefined;
+  /** onLoad handler — sets the loaded signal. Wire into the rendered `<img>`. */
+  handleLoad: () => void;
+  /** Resolved per-format <source> descriptors (or undefined when no formats). */
+  formats: FormatSource[] | undefined;
+  /** Whether `formats` is non-empty (i.e. consumer should render a `<picture>` wrapper). */
+  hasFormats: boolean;
+}
+/** Props passed to a custom component via {@link createImage}. */
+interface ImageRenderProps {
+  /** Container ref. */
+  containerRef: Ref<HTMLElement>;
+  /** CSS class for the container. */
+  class: string | undefined;
+  /** Resolved container `style` string. */
+  containerStyle: string;
+  /** Pre-rendered placeholder `<img>` (or `null` when `placeholder` is unset). */
+  placeholder: VNodeChild;
+  /** Pre-rendered image — either a bare `<img>` or a `<picture>` tree when `formats` is set. */
+  image: VNodeChild;
+}
 /**
- * Optimized image component with lazy loading, responsive images,
- * multi-format <picture> support, and blur-up placeholders.
+ * Composable that provides all image optimization behavior — lazy loading,
+ * srcset/sizes resolution, format selection, blur-placeholder state,
+ * load tracking.
+ *
+ * Use this for full control when `createImage` is too opinionated about
+ * the surrounding markup (e.g. custom container layouts, non-`<div>`
+ * wrappers, additional overlay elements).
+ *
+ * @example
+ * function MyImage(props: ImageProps) {
+ *   const img = useImage(props)
+ *   return (
+ *     <figure ref={img.containerRef} style={img.containerStyle}>
+ *       <img
+ *         src={img.src}
+ *         srcSet={img.srcSet}
+ *         sizes={img.sizes}
+ *         alt={props.alt}
+ *         loading={img.loading}
+ *         onLoad={img.handleLoad}
+ *         style={img.imageStyle}
+ *       />
+ *       <figcaption>{props.alt}</figcaption>
+ *     </figure>
+ *   )
+ * }
+ */
+declare function useImage(props: ImageProps): UseImageReturn;
+/**
+ * Higher-order component that wraps any component with image optimization.
+ *
+ * The wrapped component receives {@link ImageRenderProps} with the pre-rendered
+ * `image` JSX (bare `<img>` OR `<picture>` tree depending on formats), the
+ * pre-rendered `placeholder` JSX, and the container ref + styles. Consumers
+ * compose those pieces with whatever wrapper element / layout they want.
+ *
+ * @example
+ * // Custom figure-based image with caption
+ * const FigureImage = createImage((props) => (
+ *   <figure ref={props.containerRef} class={props.class} style={props.containerStyle}>
+ *     {props.placeholder}
+ *     {props.image}
+ *     <figcaption>Caption goes here</figcaption>
+ *   </figure>
+ * ))
+ *
+ * // Usage — identical to default <Image>
+ * <FigureImage src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ */
+declare function createImage(Component: (p: ImageRenderProps) => any): (props: ImageProps) => any;
+/**
+ * Default optimized image component with lazy loading, responsive srcset,
+ * `<picture>` multi-format support, and blur-up placeholders.
  *
  * @example
  * // With imagePlugin — spread the import directly
@@ -67,7 +167,7 @@ interface ImageSource {
  * // Manual usage
  * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
  */
-declare function Image(props: ImageProps): VNodeChild;
+declare const Image: (props: ImageProps) => any;
 //#endregion
 //#region src/link.d.ts
 interface LinkProps {
@@ -209,14 +309,86 @@ interface ScriptProps {
   id?: string;
   /** Async attribute. Default: true */
   async?: boolean;
-  /** onLoad callback. */
+  /** onLoad callback — fires when the `<script>` finishes loading. */
   onLoad?: () => void;
-  /** onError callback. */
+  /** onError callback — fires when the `<script>` fails to load. */
   onError?: (error: Error) => void;
 }
 type ScriptStrategy = 'beforeHydration' | 'afterHydration' | 'onIdle' | 'onInteraction' | 'onViewport';
+/** Return type of {@link useScript}. */
+interface UseScriptReturn {
+  /** Ref — attach to the sentinel element for `onViewport` strategy. Undefined for other strategies. */
+  sentinelRef: Ref<HTMLElement> | undefined;
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean;
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean;
+  /** Whether the script is in the strategy state machine awaiting a trigger (idle/interaction/viewport). */
+  pending: () => boolean;
+  /** Whether the consumer needs to render a sentinel element (only true for `onViewport`). */
+  needsSentinel: boolean;
+  /** Imperatively trigger the script load. Already invoked automatically by the strategy. */
+  load: () => void;
+}
+/** Props passed to a custom component via {@link createScript}. */
+interface ScriptRenderProps {
+  /** Ref — attach to whatever sentinel element you render (only matters for `onViewport`). */
+  sentinelRef: Ref<HTMLElement> | undefined;
+  /** Whether the script is in viewport-wait mode (true → render a sentinel; false → render null). */
+  needsSentinel: boolean;
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean;
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean;
+  /** Whether the script is in the strategy state machine awaiting a trigger. */
+  pending: () => boolean;
+}
+/**
+ * Composable that provides all script loading behavior — strategy state
+ * machine (afterHydration / onIdle / onInteraction / onViewport),
+ * deduplication, load/error tracking.
+ *
+ * Returns reactive signals (`loaded`, `errored`, `pending`) so consumers
+ * can render loading indicators, retry buttons, or analytics-readiness
+ * gates without re-implementing the strategy machine.
+ *
+ * @example
+ * function MyScript(props: ScriptProps) {
+ *   const s = useScript(props)
+ *   return (
+ *     <>
+ *       {() => s.loaded() ? <Analytics /> : <Skeleton />}
+ *       {() => s.needsSentinel && <div ref={s.sentinelRef} style="width:0;height:0" />}
+ *     </>
+ *   )
+ * }
+ */
+declare function useScript(props: ScriptProps): UseScriptReturn;
 /**
- * Optimized script loading component.
+ * Higher-order component that wraps any component with script load behavior.
+ *
+ * The wrapped component receives {@link ScriptRenderProps} with the sentinel
+ * ref, load-state signals, and a `needsSentinel` flag. Use this when you want
+ * to render a loading indicator, retry button, or custom analytics-readiness
+ * gate around the script load.
+ *
+ * @example
+ * // Script with a loading indicator
+ * const TrackedScript = createScript((props) => (
+ *   <>
+ *     {() => props.pending() && <Spinner />}
+ *     {() => props.errored() && <button onClick={() => location.reload()}>Retry</button>}
+ *     {props.needsSentinel && <div ref={props.sentinelRef} style="width:0;height:0" />}
+ *   </>
+ * ))
+ *
+ * <TrackedScript src="/analytics.js" strategy="onIdle" />
+ */
+declare function createScript(Component: (p: ScriptRenderProps) => any): (props: ScriptProps) => any;
+/**
+ * Default optimized script component. Renders a 0×0 sentinel `<div>` for the
+ * `onViewport` strategy (so IntersectionObserver has an element to observe),
+ * `null` for every other strategy.
  *
  * @example
  * // Load analytics after page is interactive
@@ -230,7 +402,460 @@ type ScriptStrategy = 'beforeHydration' | 'afterHydration' | 'onIdle' | 'onInter
  *   {`console.log("App hydrated!")`}
  * </Script>
  */
-declare function Script(props: ScriptProps): VNodeChild;
+declare const Script: (props: ScriptProps) => VNodeChild;
+//#endregion
+//#region src/types.d.ts
+/** What a route file (e.g. `src/routes/index.tsx`) can export. */
+interface RouteModule {
+  /** Default export is the page component. */
+  default?: ComponentFn;
+  /** Layout wrapper — wraps this route and all children. */
+  layout?: ComponentFn;
+  /** Loading component shown while lazy-loading or during Suspense. */
+  loading?: ComponentFn;
+  /** Error component shown when the route errors. */
+  error?: ComponentFn;
+  /** Server-side data loader. */
+  loader?: (ctx: LoaderContext) => Promise<unknown>;
+  /** Per-route middleware. */
+  middleware?: Middleware | Middleware[];
+  /** Navigation guard — can redirect or block navigation. */
+  guard?: NavigationGuard;
+  /** Route metadata. */
+  meta?: RouteMeta;
+  /** Rendering mode override for this route. */
+  renderMode?: RenderMode;
+}
+/** Per-route metadata. */
+interface RouteMeta {
+  title?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr';
+interface ISRConfig {
+  /** Revalidation interval in seconds. */
+  revalidate: number;
+  /**
+   * Maximum number of distinct URL paths to keep in the in-memory cache.
+   * Oldest-first LRU eviction once the cap is reached. Default: `1000`.
+   * Set higher for SSG-heavy sites, lower for routes with unbounded URL
+   * 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" */
+  mode?: RenderMode;
+  /** Vite config overrides. */
+  vite?: Record<string, unknown>;
+  /** SSR options. */
+  ssr?: {
+    /** Streaming mode. Default: "string" */mode?: 'string' | 'stream';
+  };
+  /** 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>;
+  };
+  /** ISR config — only used when mode is "isr". */
+  isr?: ISRConfig;
+  /**
+   * 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;
+}
+/**
+ * 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;
+}
+/** Entry mapping a URL pattern to its route-level middleware. */
+interface RouteMiddlewareEntry {
+  pattern: string;
+  middleware: Middleware | Middleware[];
+}
+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/i18n-routing.d.ts
 interface I18nRoutingConfig {
@@ -494,179 +1119,6 @@ declare function ThemeToggle(props: {
  */
 declare const themeScript = "(function(){try{var t=localStorage.getItem(\"zero-theme\");var r=t===\"light\"?\"light\":t===\"dark\"?\"dark\":window.matchMedia(\"(prefers-color-scheme:dark)\").matches?\"dark\":\"light\";document.documentElement.dataset.theme=r;document.querySelectorAll(\"[data-favicon-theme]\").forEach(function(l){l.media=l.dataset.faviconTheme===r?\"\":\"not all\"})}catch(e){}})()";
 //#endregion
-//#region src/types.d.ts
-/** What a route file (e.g. `src/routes/index.tsx`) can export. */
-interface RouteModule {
-  /** Default export is the page component. */
-  default?: ComponentFn;
-  /** Layout wrapper — wraps this route and all children. */
-  layout?: ComponentFn;
-  /** Loading component shown while lazy-loading or during Suspense. */
-  loading?: ComponentFn;
-  /** Error component shown when the route errors. */
-  error?: ComponentFn;
-  /** Server-side data loader. */
-  loader?: (ctx: LoaderContext) => Promise<unknown>;
-  /** Per-route middleware. */
-  middleware?: Middleware | Middleware[];
-  /** Navigation guard — can redirect or block navigation. */
-  guard?: NavigationGuard;
-  /** Route metadata. */
-  meta?: RouteMeta;
-  /** Rendering mode override for this route. */
-  renderMode?: RenderMode;
-}
-/** Per-route metadata. */
-interface RouteMeta {
-  title?: string;
-  description?: string;
-  [key: string]: unknown;
-}
-type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr';
-interface ISRConfig {
-  /** Revalidation interval in seconds. */
-  revalidate: number;
-  /**
-   * Maximum number of distinct URL paths to keep in the in-memory cache.
-   * Oldest-first LRU eviction once the cap is reached. Default: `1000`.
-   * Set higher for SSG-heavy sites, lower for routes with unbounded URL
-   * space (e.g. `/user/:id` where `:id` is free-form).
-   */
-  maxEntries?: number;
-}
-interface ZeroConfig {
-  /** Default rendering mode. Default: "ssr" */
-  mode?: RenderMode;
-  /** Vite config overrides. */
-  vite?: Record<string, unknown>;
-  /** SSR options. */
-  ssr?: {
-    /** Streaming mode. Default: "string" */mode?: 'string' | 'stream';
-  };
-  /** SSG options — only used when mode is "ssg". */
-  ssg?: {
-    /** Paths to prerender (or function returning paths). */paths?: string[] | (() => string[] | Promise<string[]>);
-  };
-  /** ISR config — only used when mode is "isr". */
-  isr?: ISRConfig;
-  /** Deploy adapter. Default: "node" */
-  adapter?: 'node' | 'bun' | 'static' | 'vercel' | 'cloudflare' | 'netlify';
-  /** Base URL path. Default: "/" */
-  base?: string;
-  /** App-level middleware applied to all routes. */
-  middleware?: Middleware[];
-  /** Server port for dev/preview. Default: 3000 */
-  port?: number;
-}
-/**
- * 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;
-  /**
-   * 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;
-}
-/** 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;
-}
-/** Entry mapping a URL pattern to its route-level middleware. */
-interface RouteMiddlewareEntry {
-  pattern: string;
-  middleware: Middleware | Middleware[];
-}
-interface Adapter {
-  name: string;
-  /** Build the production server/output for this adapter. */
-  build(options: AdapterBuildOptions): Promise<void>;
-}
-interface AdapterBuildOptions {
-  /** Path to the built server entry. */
-  serverEntry: string;
-  /** Path to the client build output. */
-  clientOutDir: string;
-  /** Final output directory. */
-  outDir: string;
-  config: ZeroConfig;
-}
-//#endregion
 //#region src/index.d.ts
 /** @deprecated Import from `@pyreon/zero/favicon` instead */
 declare function faviconPlugin(..._: unknown[]): never;
@@ -683,5 +1135,5 @@ declare function ogImagePlugin(..._: unknown[]): never;
 /** @deprecated Import from `@pyreon/zero/ai` instead */
 declare function aiPlugin(..._: unknown[]): never;
 //#endregion
-export { type Adapter, type AdapterBuildOptions, type FileRoute, type I18nRoutingConfig, type ISRConfig, Image, type ImageProps, type ImageSource, Link, type LinkProps, type LinkRenderProps, type LoaderContext, type LocaleContext, Meta, type MetaProps, type RenderMode, type RouteMeta, type RouteMiddlewareEntry, type RouteModule, Script, type ScriptProps, type ScriptStrategy, type Theme, ThemeToggle, type UseLinkReturn, type ZeroConfig, aiPlugin, buildLocalePath, buildMetaTags, createLink, createServer, defineConfig, extractLocaleFromPath, faviconPlugin, initTheme, ogImagePlugin, prefetchRoute, resolvedTheme, seoPlugin, setLocale, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme, useLink, useLocale, validateEnv };
+export { type Adapter, type AdapterBuildOptions, type FileRoute, type I18nRoutingConfig, type ISRConfig, Image, type ImageProps, type ImageRenderProps, type ImageSource, Link, type LinkProps, type LinkRenderProps, type LoaderContext, type LocaleContext, Meta, type MetaProps, type RenderMode, type RouteMeta, type RouteMiddlewareEntry, type RouteModule, Script, type ScriptProps, type ScriptRenderProps, type ScriptStrategy, type Theme, ThemeToggle, type UseImageReturn, type UseLinkReturn, type UseScriptReturn, type ZeroConfig, aiPlugin, buildLocalePath, buildMetaTags, createImage, createLink, createScript, createServer, defineConfig, extractLocaleFromPath, faviconPlugin, initTheme, ogImagePlugin, prefetchRoute, resolvedTheme, seoPlugin, setLocale, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme, useImage, useLink, useLocale, useScript, validateEnv };
 //# sourceMappingURL=index2.d.ts.map