@pyreon/zero 0.14.0 → 0.16.0

package/src/ssg-plugin.ts

@@ -0,0 +1,1523 @@
+/**
+ * SSG (Static Site Generation) build hook for `@pyreon/zero`.
+ *
+ * Activates when `mode: "ssg"` is set in zero's config. After Vite's client
+ * build finishes, this plugin:
+ *
+ *   1. Triggers a programmatic SSR build via Vite's `build()` API, producing
+ *      a server bundle in `dist/.zero-ssg-server/` from a synthetic entry
+ *      that imports `virtual:zero/routes` and `createServer`.
+ *   2. Loads the built handler with dynamic `import()`.
+ *   3. Resolves the path list from `config.ssg.paths` (string[], async fn,
+ *      or auto-detected from the static-only routes in the route tree).
+ *   4. Calls `prerender()` from `@pyreon/server` to render each path.
+ *   5. Cleans up the temporary SSR build directory.
+ *
+ * Before this PR, `mode: "ssg"` and `ssg.paths` were typed in
+ * `types.ts` but had no runtime implementation — the plugin file had zero
+ * Rollup build hooks. Apps configured for SSG silently shipped a bare SPA
+ * shell with no per-route HTML files, which broke direct-URL deploys to
+ * static hosts (no `dist/<path>/index.html`, every URL falls back to the
+ * SPA index).
+ */
+
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Plugin } from 'vite'
+import { resolveAdapter } from './adapters'
+import { resolveConfig } from './config'
+import { parseFileRoutes, scanRouteFiles, scanRouteFilesWithExports } from './fs-router'
+import { expandRoutesForLocales, type I18nRoutingConfig } from './i18n-routing'
+import type { ZeroConfig } from './types'
+
+// M2.3 — Server-side perf-harness counter sink (same shape as
+// runtime-server). `__DEV__` is gated at the call site so prod builds with
+// `NODE_ENV=production` skip the optional-chain entirely. Counter strings
+// remain in the bundle (few bytes) but the runtime cost is zero.
+//
+// Consumers run the build under a process that has installed a sink via
+// `@pyreon/perf-harness`'s `install()` / `enable()` API. Without a sink
+// installed, the optional chaining short-circuits and emission is free.
+// Useful for: CI plugins tracking SSG perf over time, dev profiling, or
+// the future `vite build --profile` flag.
+const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
+// Marker env var used to skip the SSG hook on the recursive SSR sub-build —
+// the SSR pass loads the same vite config + same plugin chain, so without
+// this guard the SSG hook would re-trigger an infinite build loop.
+const SSG_BUILD_FLAG = 'PYREON_ZERO_SSG_INNER_BUILD'
+
+// Synthetic SSR entry source. Imports the user's route tree via the virtual
+// module that zero's main plugin already registers, then exports a default
+// `(path: string) => Promise<string>` renderer that returns the full HTML
+// for a single path.
+//
+// The entry is materialized to disk (not registered as a virtual module)
+// because Rolldown's `rollupOptions.input` phase doesn't reliably resolve
+// `\0`-prefixed virtual ids when used as build entries — a virtual id
+// returned from `resolveId` works fine for downstream imports but fails
+// the entry-resolution stage with `Cannot resolve entry module`.
+//
+// We do NOT use zero's `createServer` because it wraps the user's App with
+// a router whose URL is baked in at App-creation time. SSG needs a fresh
+// router per path, so we mirror the dev SSR pipeline (`renderSsr` in
+// vite-plugin.ts): per request → new createApp({ url: path }) → preload
+// loaders → renderWithHead → serialize loader data → done.
+// SSG entry template — see notes above for the design rationale.
+//
+// **Styler CSS flush.** `@pyreon/styler` accumulates server-rendered CSS
+// rules into its singleton `sheet.ssrBuffer` as components render, then
+// emits them via `sheet.getStyleTag()`. Before this was wired into the SSG
+// path, prerendered HTML carried styler-generated class names (`pyr-1abc23`)
+// on every element but had ZERO `<style>` tags in the head — meaning every
+// SSG page rendered un-styled until the client JS ran and re-emitted the
+// CSS. The fix lazy-imports `@pyreon/styler` so projects that don't use it
+// pay nothing, calls `sheet.reset()` per request to start clean (singleton
+// state would leak across paths in the same SSG sub-build), and injects
+// the resulting `<style>` tag into the head ahead of @pyreon/head's tags.
+//
+// `@pyreon/server`'s `createHandler` exposes the same hook via a
+// `collectStyles` option (handler.ts:84-91); the SSG path used to bypass
+// that entirely because it builds its own renderer rather than going
+// through createHandler.
+// PR K (i18n follow-up): the SSG entry needs the configured locales list
+// baked in at build time so the per-locale 404 walker can detect which
+// RouteRecord serves which locale. Locale info isn't on the runtime
+// route records (they're path patterns, not metadata), so the walker
+// has to compare paths against the known locale list. Wrapping the
+// source template in a function lets the outer plugin pass
+// `config.i18n?.locales ?? []` per build.
+const renderSsrEntrySource = (locales: readonly string[] = []): string => {
+  const i18nLocalesLiteral = JSON.stringify(locales)
+  return `
+import { routes } from "virtual:zero/routes"
+import { h } from "@pyreon/core"
+import { renderWithHead } from "@pyreon/head/ssr"
+import { getRedirectInfo, serializeLoaderData, stringifyLoaderData } from "@pyreon/router"
+import { runWithRequestContext } from "@pyreon/runtime-server"
+import { createApp } from "@pyreon/zero/server"
+
+// Lazy-imported styler integration. Projects that don't depend on
+// @pyreon/styler skip this entirely (the import fails silently, the
+// helper stays a no-op). Hot path: an awaited dynamic import resolved
+// once at entry-module evaluation, then sync calls per request.
+//
+// **No reset between paths.** @pyreon/styler's styled() inserts CSS
+// rules into sheet.ssrBuffer at MODULE-EVAL TIME (top-level of styled.ts:95),
+// not per-render. After that initial insert, each render of a styled
+// component just attaches the cached class name to props — no new buffer
+// push. Calling sheet.reset() between SSG paths would WIPE all rules and
+// leave subsequent pages style-less. For SSG this is acceptable: the
+// generated CSS is identical across all pages (same module-eval cache),
+// and shipping the full rule set in every page's <style> tag matches
+// how static SSG sites handle CSS — every page is self-contained,
+// cacheable by the browser, no per-route CSS code splitting needed.
+let __pyreonGetStylerTag = () => ""
+try {
+  const stylerMod = await import("@pyreon/styler")
+  if (stylerMod && stylerMod.sheet && typeof stylerMod.sheet.getStyleTag === "function") {
+    __pyreonGetStylerTag = () => stylerMod.sheet.getStyleTag()
+  }
+} catch {
+  // No @pyreon/styler in the project — leave the no-op stub in place.
+}
+
+// PR E — \`__ZERO_BASE__\` is the Vite-defined build-time constant
+// carrying the value of \`zero({ base })\`. Read it once at module
+// eval and forward to createRouter via createApp so SSG-rendered
+// pages have correctly-prefixed RouterLink hrefs that match the
+// asset URLs Vite already prefixed in the built HTML template.
+const __ssgBase = typeof __ZERO_BASE__ !== "undefined" && __ZERO_BASE__ !== "/"
+  ? __ZERO_BASE__
+  : undefined
+
+export default async function renderPath(path, options) {
+  const { App, router } = createApp({
+    routes,
+    routerMode: "history",
+    url: path,
+    ...(__ssgBase ? { base: __ssgBase } : {}),
+  })
+
+  // PR B — redirect handling. \`router.preload\` runs every loader in the
+  // matched chain and surfaces \`redirect()\` throws as the rejection
+  // reason. We catch BEFORE the render: rendering past a redirect would
+  // produce HTML for the wrong page AND leak the auth-gated layout
+  // structure for unauthenticated users. The runtime SSR handler
+  // (createHandler in @pyreon/server) already does this same catch and
+  // returns a 302/307 Location response; SSG mirrors that — return
+  // \`{ kind: 'redirect', from, to, status }\` instead of HTML, and the
+  // outer plugin emits a redirect manifest entry instead of an
+  // \`index.html\`. Any non-redirect error rethrows and lands in the
+  // existing \`errors[]\` collection.
+  //
+  // PR C — \`isNotFound\` skips parent-layout loaders during the 404 build.
+  // Layout loaders that hit auth resources (cookies, session tokens,
+  // private APIs) shouldn't fire when generating a static 404 page —
+  // the build has no real request context. Lazy components still
+  // resolve so the synthetic chain renders cleanly; only the
+  // \`r.loader()\` invocations are skipped. \`__renderNotFound\` below
+  // forwards \`{ isNotFound: true }\` for this path.
+  try {
+    await router.preload(path, undefined, {
+      skipLoaders: options?.isNotFound === true,
+    })
+  } catch (err) {
+    const info = getRedirectInfo(err)
+    if (info) {
+      return { kind: "redirect", from: path, to: info.url, status: info.status }
+    }
+    throw err
+  }
+
+  return runWithRequestContext(async () => {
+    const app = h(App, null)
+    const { html: appHtml, head } = await renderWithHead(app)
+
+    // Inject styler's <style data-pyreon-styler="..."> tag into the head
+    // BEFORE @pyreon/head's tags so the CSS cascade orders correctly with
+    // any meta/link tags the user added. Empty buffer emits a benign
+    // empty <style></style> — detected via the literal closing pair to
+    // avoid polluting the head when no styler is in use.
+    const styleTag = __pyreonGetStylerTag()
+    const isEmpty = !styleTag || styleTag.indexOf("></style>") !== -1
+    const finalHead = isEmpty ? head : styleTag + "\\n" + head
+
+    const loaderData = serializeLoaderData(router)
+    const hasData = loaderData && Object.keys(loaderData).length > 0
+    // M2.2 — safe serializer drops function/symbol values, throws a clear
+    // Pyreon-prefixed error on circular refs, escapes </script> uniformly.
+    const loaderScript = hasData
+      ? \`<script>window.__PYREON_LOADER_DATA__=\${stringifyLoaderData(loaderData)}</script>\`
+      : ""
+    return { kind: "html", appHtml, head: finalHead, loaderScript }
+  })
+}
+
+// ─── getStaticPaths enumeration (PR A) ──────────────────────────────────────
+//
+// Walks the generated routes tree and collects every dynamic route's
+// \`getStaticPaths\` function alongside its URL pattern. The SSG plugin
+// calls this once before rendering and uses the returned map to expand
+// dynamic routes (\`/posts/:id\` × \`[{id:'a'},{id:'b'}]\` → \`/posts/a\`,
+// \`/posts/b\`). Routes without \`getStaticPaths\` are absent from the map.
+//
+// Why we collect ALL routes here instead of resolving on-demand: the
+// SSG plugin's \`resolvePaths\` runs in the OUTER Vite plugin context (no
+// access to the bundled routes module). The SSR sub-build is the only
+// place where the user's compiled route exports are reachable, so we
+// expose a sync collector that lets the plugin call user functions
+// indirectly via the entry's exports.
+function collectStaticPathsRegistry(rs, out) {
+  for (const r of rs) {
+    if (typeof r.getStaticPaths === "function" && typeof r.path === "string") {
+      out.set(r.path, r.getStaticPaths)
+    }
+    if (Array.isArray(r.children)) collectStaticPathsRegistry(r.children, out)
+  }
+  return out
+}
+
+/** Map of \`urlPath → getStaticPaths function\` for every dynamic route. */
+export const __getStaticPathsRegistry = collectStaticPathsRegistry(routes, new Map())
+
+// ─── 404 emission (PR C) ────────────────────────────────────────────────────
+//
+// Locales the build was configured for (PR H: \`zero({ i18n: { locales } })\`).
+// Injected as a JSON-literal by the outer plugin so the walker can detect
+// which RouteRecord serves which locale by matching its \`path\` against
+// the \`/\${locale}\` / \`/\${locale}/*\` prefix. Empty array = no i18n,
+// single-default-locale shape, walker collects exactly one entry keyed
+// by \`null\` and the closeBundle writes a single \`dist/404.html\`.
+const __i18nLocales = ${i18nLocalesLiteral}
+
+// Walk the route tree and return ALL \`notFoundComponent\` references,
+// keyed by which locale subtree they were found in (or \`null\` for the
+// default / no-i18n case). fs-router attaches \`_404.tsx\` to its parent
+// layout's RouteRecord (or to each page record when no wrapping layout
+// exists — which is the per-locale subtree shape under PR H's root-
+// layout-skip). The walker collects the FIRST match per locale via
+// depth-first traversal: the per-locale subtree's \`notFoundComponent\`
+// wins over the root's for that locale.
+//
+// Locale detection: a RouteRecord serves locale \`X\` if its \`path\`
+// matches \`/X\` or starts with \`/X/\`. The default-locale entry
+// (under \`prefix-except-default\` strategy) is keyed by \`null\` since
+// its path doesn't carry a locale prefix.
+function findNotFoundComponentsByLocale(rs, currentLocale) {
+  const result = new Map()
+  function walk(records, ambient) {
+    for (const r of records) {
+      const path = typeof r.path === "string" ? r.path : ""
+      let locale = ambient
+      for (const l of __i18nLocales) {
+        if (path === \`/\${l}\` || path.startsWith(\`/\${l}/\`)) {
+          locale = l
+          break
+        }
+      }
+      if (typeof r.notFoundComponent === "function") {
+        if (!result.has(locale)) result.set(locale, r.notFoundComponent)
+      }
+      if (Array.isArray(r.children)) walk(r.children, locale)
+    }
+  }
+  walk(rs, currentLocale)
+  return result
+}
+export const __notFoundComponentsByLocale = findNotFoundComponentsByLocale(routes, null)
+
+// Back-compat: legacy single-export, picks up whatever the walker
+// classified as \`null\`-locale (default-locale or non-i18n root 404).
+// External callers (none currently in main, but downstream consumers
+// that imported this export pre-PR) keep working.
+export const __notFoundComponent = __notFoundComponentsByLocale.get(null) ?? null
+
+// Render the not-found component THROUGH the router (PR L5). We navigate
+// to a synthetic non-matching probe URL per locale — \`resolveRoute\`
+// (post-L5) walks the route tree finding the deepest parent
+// \`notFoundComponent\` and builds a matched chain
+// \`[...ancestorLayouts, syntheticLeaf]\`. The leaf carries the
+// not-found component; rendering through the normal pipeline produces
+// HTML WITH layout chrome — same headers, footers, navigation as
+// regular pages. The locale prefix in the probe URL ensures the right
+// per-locale layout subtree matches (under PR H's prefix strategy).
+//
+// Pre-L5 behavior (\`h(component, null)\` standalone) is preserved as a
+// fallback when the route tree has \`notFoundComponent\` at the root
+// but no \`isNotFound\` chain forms (older route shapes). The outer
+// plugin checks \`__notFoundComponentsByLocale\` first to gate emission
+// — if no notFoundComponent exists anywhere, \`__renderNotFound\` is
+// never called.
+export async function __renderNotFound(locale) {
+  // Probe URL chosen to be highly improbable as a real route. The
+  // suffix is deliberately literal (no \`Math.random\`) so build
+  // outputs are deterministic across runs.
+  const probePath = locale == null
+    ? "/__pyreon_not_found_probe__"
+    : \`/\${locale}/__pyreon_not_found_probe__\`
+
+  // Try the router-driven path first. If the route tree has a parent
+  // \`notFoundComponent\` reachable from the probe URL, resolveRoute's
+  // fallback builds the chain through the layout and the normal render
+  // pipeline produces 404 HTML wrapped in layout chrome.
+  //
+  // PR C — pass \`isNotFound: true\` so renderPath skips parent-layout
+  // loaders. Layout loaders that hit auth resources / external APIs
+  // shouldn't fire when generating a static 404 page (the build has
+  // no real request context). Lazy components still resolve; only
+  // \`r.loader()\` invocations are skipped.
+  const result = await renderPath(probePath, { isNotFound: true })
+  if (result && result.kind === "html") {
+    return {
+      appHtml: result.appHtml,
+      head: result.head,
+      loaderScript: result.loaderScript,
+    }
+  }
+
+  // Fallback for tree shapes where the resolver returns empty matched
+  // (no notFoundComponent walkable from this probe path). Render the
+  // component standalone — same shape pre-L5.
+  const component = locale == null
+    ? (__notFoundComponentsByLocale.get(null) ?? __notFoundComponent)
+    : __notFoundComponentsByLocale.get(locale)
+  if (typeof component !== "function") return null
+
+  return runWithRequestContext(async () => {
+    const vnode = h(component, null)
+    const { html: appHtml, head } = await renderWithHead(vnode)
+
+    const styleTag = __pyreonGetStylerTag()
+    const isEmpty = !styleTag || styleTag.indexOf("></style>") !== -1
+    const finalHead = isEmpty ? head : styleTag + "\\n" + head
+
+    return { appHtml, head: finalHead, loaderScript: "" }
+  })
+}
+`.trimStart()
+}
+
+const SSR_ENTRY_FILENAME = '__pyreon-zero-ssg-entry.js'
+
+/** Per-route enumerator. URL pattern (`/posts/:id`) → params list. */
+export type GetStaticPathsRegistry = Map<
+  string,
+  () => Promise<Array<{ params: Record<string, string> }>> | Array<{ params: Record<string, string> }>
+>
+
+/**
+ * Substitute concrete values for `:param` / `:param*` segments in a URL
+ * pattern. Mirrors the inverse of `filePathToUrlPath`.
+ *
+ *   /posts/:id            × { id: 'a' }            → /posts/a
+ *   /posts/:id/:slug      × { id: 'a', slug: 'b' } → /posts/a/b
+ *   /blog/:rest*          × { rest: 'a/b' }         → /blog/a/b   (catch-all preserves slashes)
+ *
+ * Missing params or empty values throw — the SSG plugin treats this as a
+ * `getStaticPaths` error and records it in the per-path errors array.
+ */
+export function expandUrlPattern(pattern: string, params: Record<string, string>): string {
+  return pattern
+    .split('/')
+    .map((seg) => {
+      if (!seg.startsWith(':')) return seg
+      const isCatchAll = seg.endsWith('*')
+      const name = isCatchAll ? seg.slice(1, -1) : seg.slice(1)
+      const value = params[name]
+      if (value === undefined || value === '') {
+        throw new Error(
+          `[zero:ssg] getStaticPaths for "${pattern}" returned params without "${name}"`,
+        )
+      }
+      return value
+    })
+    .join('/')
+}
+
+/**
+ * Auto-detect static paths from the route tree AND expand dynamic routes
+ * via each route's `getStaticPaths` export (when present). A "static" path
+ * is one with NO dynamic segments (`[id]`, `[...rest]`); a "dynamic" path
+ * with `getStaticPaths` is expanded via the registry; remaining dynamic
+ * routes are silently skipped (the user must hand-list them in
+ * `ssg.paths`).
+ */
+async function autoDetectStaticPaths(
+  routesDir: string,
+  registry?: GetStaticPathsRegistry,
+  errors: { path: string; error: unknown }[] = [],
+  i18n?: I18nRoutingConfig,
+): Promise<string[]> {
+  // Routes dir missing → fall back to "/" anyway. A project that doesn't
+  // expose routes via fs-routing (custom routes module, single-page app
+  // shell, etc.) still needs at least an index.html so static hosts have
+  // a default response. The user can always set explicit `ssg.paths` to
+  // override this floor.
+  if (!existsSync(routesDir)) return ['/']
+  const files = await scanRouteFiles(routesDir)
+  // PR H — fan routes into per-locale variants when `i18n` is configured.
+  // Each duplicated FileRoute carries the same `getStaticPaths` enumerator
+  // (via `exports`) so dynamic + i18n cardinality compounds naturally:
+  // `/blog/[slug]` × `[en, de]` × 3 slugs → 6 paths under
+  // `prefix-except-default`.
+  const baseRoutes = parseFileRoutes(files)
+  const fileRoutes = i18n ? expandRoutesForLocales(baseRoutes, i18n) : baseRoutes
+
+  const out: string[] = []
+  for (const r of fileRoutes) {
+    if (r.isLayout || r.isError || r.isLoading || r.isNotFound) continue
+    const path = r.urlPath
+    if (!path) continue
+
+    // Static path — emit as-is.
+    if (!/[:*]/.test(path)) {
+      out.push(path)
+      continue
+    }
+
+    // Dynamic path — expand via getStaticPaths if available.
+    const enumerator = registry?.get(path)
+    if (!enumerator) continue // no getStaticPaths → skip silently
+
+    try {
+      const result = await enumerator()
+      if (!Array.isArray(result)) {
+        throw new Error(
+          `getStaticPaths for "${path}" must return an array, got ${typeof result}`,
+        )
+      }
+      for (const entry of result) {
+        if (!entry || typeof entry !== 'object' || !entry.params) {
+          throw new Error(
+            `getStaticPaths for "${path}" returned an entry without "params"`,
+          )
+        }
+        out.push(expandUrlPattern(path, entry.params))
+      }
+    } catch (error) {
+      errors.push({ path, error })
+    }
+  }
+
+  // Always include "/" as a fallback if no static routes were found —
+  // a project with only dynamic routes still needs an index.html for the
+  // host to know where to send unmatched URLs.
+  return out.length > 0 ? out : ['/']
+}
+
+async function resolvePaths(
+  config: ZeroConfig,
+  routesDir: string,
+  registry?: GetStaticPathsRegistry,
+  errors: { path: string; error: unknown }[] = [],
+): Promise<string[]> {
+  const explicit = config.ssg?.paths
+  if (typeof explicit === 'function') {
+    const result = await explicit()
+    return Array.isArray(result) ? result : []
+  }
+  if (Array.isArray(explicit)) return explicit
+  return autoDetectStaticPaths(routesDir, registry, errors, config.i18n)
+}
+
+/**
+ * Write `content` to `target` atomically: write to a sibling temp file first,
+ * then `rename` into place. Rename is an atomic syscall on POSIX (and Windows
+ * for same-volume renames) — readers either see the OLD content or the FULL
+ * new content, never a half-written file.
+ *
+ * M2.1 — Use this for manifests that adapters consume (`_redirects`,
+ * `_pyreon-ssg-paths.json`, `_pyreon-revalidate.json`, etc.). A SIGINT during
+ * a sequential plain-`writeFile` chain in `closeBundle` would leave partial
+ * state: half the manifests pointing at the new render, half the old. Atomic
+ * writes mean each manifest is independently consistent — readers see either
+ * the old build's manifest or the new build's, never a mix.
+ *
+ * Per-page HTML writes (`dist/<path>/index.html`) intentionally do NOT use
+ * this — they're individually-readable files (no cross-file invariants), and
+ * the rename-per-page cost on 10k-path sites would be significant.
+ *
+ * Temp filename embeds `pid + perf-counter` so concurrent runs (e.g. CI
+ * pipelines that fight over the same dist) don't collide. The tmp file is
+ * cleaned up in a finally block — even if the rename fails, no orphaned
+ * `.tmp.*` files leak.
+ *
+ * @internal Exposed via `_internal.writeFileAtomic` for unit tests.
+ */
+let _atomicSeq = 0
+async function writeFileAtomic(target: string, content: string | Uint8Array): Promise<void> {
+  const tmp = `${target}.tmp.${process.pid}.${++_atomicSeq}`
+  try {
+    await writeFile(tmp, content)
+    await rename(tmp, target)
+  } catch (err) {
+    // Best-effort cleanup — if rename succeeded the tmp file is gone; if it
+    // failed (or writeFile failed), unlink it. unlink-on-missing is fine.
+    try {
+      await unlink(tmp)
+    } catch {
+      // Already gone (rename succeeded, or writeFile never produced it).
+    }
+    throw err
+  }
+}
+
+/**
+ * Build the per-locale breakdown summary string for the closeBundle log.
+ *
+ * M2.5 — Computes per-locale path counts from `writtenPaths` by checking
+ * each path's leading segment against the configured locale list. Paths
+ * with no locale prefix go to the default locale (under
+ * `prefix-except-default`) or are skipped (under `prefix`, where every
+ * locale carries an explicit prefix — unprefixed paths are unexpected).
+ *
+ * Returns `` ` [en: 100, de: 100, cs: 100]` `` (with leading space) for
+ * pretty concatenation into the summary line, or empty string when i18n
+ * is unconfigured / writtenPaths is empty.
+ *
+ * @internal Exposed via `_internal.buildLocaleSummary` for unit tests.
+ */
+function buildLocaleSummary(
+  writtenPaths: readonly string[],
+  i18n: I18nRoutingConfig,
+): string {
+  if (writtenPaths.length === 0 || i18n.locales.length === 0) return ''
+  const counts = new Map<string, number>()
+  for (const locale of i18n.locales) counts.set(locale, 0)
+  const defaultLocale = i18n.defaultLocale ?? i18n.locales[0] ?? ''
+  const strategy = i18n.strategy ?? 'prefix-except-default'
+  for (const p of writtenPaths) {
+    // Split on '/' — `/de/about` → ['', 'de', 'about']; `/about` → ['', 'about']
+    const firstSeg = p.split('/')[1]
+    if (firstSeg && counts.has(firstSeg)) {
+      counts.set(firstSeg, (counts.get(firstSeg) ?? 0) + 1)
+    } else if (strategy === 'prefix-except-default' && defaultLocale) {
+      // Unprefixed path under prefix-except-default belongs to the default locale.
+      counts.set(defaultLocale, (counts.get(defaultLocale) ?? 0) + 1)
+    }
+    // Under `prefix` strategy: unprefixed paths are unexpected (every
+    // locale should carry an explicit prefix). Silently skip — the
+    // path-collision detector (M1.4) would have caught structurally
+    // invalid duplicates anyway.
+  }
+  const parts: string[] = []
+  for (const locale of i18n.locales) parts.push(`${locale}: ${counts.get(locale) ?? 0}`)
+  return ` [${parts.join(', ')}]`
+}
+
+/**
+ * Detect duplicate URLs in the resolved-paths list. Returns the duplicates
+ * (sorted, unique). Empty array = no collisions.
+ *
+ * The render loop's `writtenPaths.push(p)` would silently last-wins on
+ * duplicates — two routes producing the same URL would have one's HTML
+ * overwrite the other's with no error. Catching the collision before
+ * render makes the conflict visible at the source-of-truth (the routes
+ * tree), not at the symptom (mysterious HTML drift between rebuilds).
+ *
+ * @internal Exposed via `_internal.detectPathCollisions` for unit tests.
+ */
+function detectPathCollisions(paths: readonly string[]): string[] {
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  for (const p of paths) {
+    if (seen.has(p)) duplicates.add(p)
+    seen.add(p)
+  }
+  return [...duplicates].sort()
+}
+
+/** Format a path-collision error message with actionable guidance. */
+/**
+ * Wiring helper: run the collision detector + throw with the formatted error
+ * when any collisions are found. The closeBundle handler calls this between
+ * `resolvePaths` and the render loop. Factored out so unit tests can exercise
+ * the full "detect → throw" path without spinning up a Vite SSR sub-build.
+ *
+ * @internal Exposed via `_internal.assertNoPathCollisions` for unit tests.
+ */
+function assertNoPathCollisions(paths: readonly string[]): void {
+  const collisions = detectPathCollisions(paths)
+  if (collisions.length > 0) {
+    throw new Error(formatPathCollisionError(collisions))
+  }
+}
+
+function formatPathCollisionError(duplicates: readonly string[]): string {
+  const list = duplicates.map((p) => `  - ${p}`).join('\n')
+  return `[Pyreon] SSG path collision — ${duplicates.length} URL(s) resolved by multiple routes:\n${list}\nThis happens when a static route + getStaticPaths return overlap, or two getStaticPaths enumerators produce the same URL. Inspect your routes tree and ensure each URL is produced by exactly one route.`
+}
+
+function resolveOutputPath(distDir: string, path: string): string {
+  if (path === '/') return join(distDir, 'index.html')
+  if (path.endsWith('.html')) return join(distDir, path)
+  return join(distDir, path, 'index.html')
+}
+
+// ─── Redirect emission (PR B) ──────────────────────────────────────────────
+//
+// The shape returned by the SSG entry's renderPath when a loader throws
+// `redirect()`. The `kind` discriminator lets the closeBundle loop branch
+// to the right writer (HTML file vs. redirect-manifest entry).
+export interface RedirectEntry {
+  from: string
+  to: string
+  status: number
+}
+
+/**
+ * Render Netlify / Cloudflare Pages `_redirects` file content. One line
+ * per redirect, format: `<from> <to> <status>`. Both platforms parse this
+ * format identically; Vercel ignores it (use the JSON below). Lines with
+ * leading `#` are comments — included so the file is self-documenting in
+ * a deploy log.
+ */
+function renderNetlifyRedirects(entries: RedirectEntry[]): string {
+  if (entries.length === 0) return ''
+  const lines = ['# Auto-generated by @pyreon/zero SSG. Do not edit.']
+  for (const e of entries) {
+    lines.push(`${e.from} ${e.to} ${e.status}`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * Render Vercel `_redirects.json` content. Vercel reads this from the
+ * `vercel.json` `redirects` array shape — but the bare `_redirects.json`
+ * file ships alongside as documentation / fallback for adapters that
+ * read either format. The 308/301/302/307 status maps to Vercel's
+ * `permanent: true|false` boolean (308/301 → permanent; 302/307 →
+ * temporary).
+ */
+function renderVercelRedirectsJson(entries: RedirectEntry[]): string {
+  return `${JSON.stringify(
+    {
+      redirects: entries.map((e) => ({
+        source: e.from,
+        destination: e.to,
+        permanent: e.status === 301 || e.status === 308,
+        statusCode: e.status,
+      })),
+    },
+    null,
+    2,
+  )}\n`
+}
+
+/**
+ * Render a meta-refresh HTML stub for static hosts that don't read
+ * `_redirects` (plain S3, GitHub Pages, simple file servers). The
+ * `<meta http-equiv="refresh" content="0; url=…">` triggers a
+ * client-side refresh; the canonical link is for SEO so search
+ * engines de-dupe the source path against the target. Status code
+ * has no HTML equivalent — a meta-refresh is always "client-side."
+ */
+function renderMetaRefreshHtml(target: string): string {
+  // Escape the target for HTML attribute context. Targets are typically
+  // absolute paths (`/login`) or absolute URLs — HTML special chars are
+  // rare but possible (`?q=a&b=c`). Always escape `&`, `<`, `>`, `"`,
+  // `'` to be safe.
+  const escaped = target
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="refresh" content="0; url=${escaped}">
+  <link rel="canonical" href="${escaped}">
+  <title>Redirecting to ${escaped}</title>
+</head>
+<body>
+  <p>Redirecting to <a href="${escaped}">${escaped}</a>...</p>
+</body>
+</html>
+`
+}
+
+/**
+ * Serialize the captured render-loop errors as a stable JSON artifact.
+ * Each entry has `{ path, message, name, stack }`. Errors that aren't
+ * `Error` instances (e.g. a loader that threw a string) are coerced via
+ * `String()` for `message`; `name` falls back to `'Error'`; `stack` is
+ * `undefined` (omitted from JSON output).
+ *
+ * Wrapped in `{ errors: [...] }` rather than emitted as a bare array so
+ * future fields (timing, build metadata) can be added without breaking
+ * existing CI consumers. Pretty-printed with 2-space indent — the file
+ * is meant to be read both by tooling AND humans diagnosing a failed
+ * build, so byte-density is not the priority.
+ */
+/**
+ * Drain `items` through `concurrency` parallel workers, calling
+ * `processItem(item)` on each and `onSettled(item, idx)` once each
+ * settles (regardless of resolve/reject). The work-stealing pattern
+ * (each worker pulls from a shared `nextIdx++` cursor) keeps load
+ * balanced even when individual `processItem` calls vary widely in
+ * duration — a fast item doesn't make its worker idle until the slowest
+ * peer finishes.
+ *
+ * Settle ordering: `onSettled` fires in the order items finish, NOT in
+ * input order. `idx` is the index into `items` (same identity across
+ * `processItem` and `onSettled`), useful for "completed N of M"
+ * progress reporting.
+ *
+ * Concurrency clamping: ≤ 0 inputs ARE clamped to 1 — the worker pool
+ * is meaningless without at least one worker, but a value of `0` from
+ * a misconfiguration shouldn't silently hang. The actual worker count
+ * is `min(concurrency, items.length)` so a 2-item list with concurrency
+ * 10 only spawns 2 workers (no idle workers spawned).
+ *
+ * Errors from `processItem` are NOT caught here — callers must handle
+ * exceptions inside `processItem` (the SSG path does so via try/catch
+ * in `renderOne`). Errors from `onSettled` likewise propagate; in the
+ * SSG path the caller wraps it to record into `errors[]`. We don't
+ * silently swallow because that would hide real bugs.
+ *
+ * Atomic operations under Node's single-threaded JS: `nextIdx++` is
+ * atomic — workers never observe a partial increment, so two workers
+ * never claim the same index. The pool relies on this invariant; do
+ * NOT port to a multi-threaded runtime without revisiting.
+ */
+async function runWithConcurrency<T>(
+  items: readonly T[],
+  concurrency: number,
+  processItem: (item: T, idx: number) => Promise<void>,
+  onSettled?: (item: T, idx: number) => Promise<void> | void,
+): Promise<void> {
+  const cap = Math.max(1, concurrency)
+  const workerCount = Math.min(cap, items.length)
+  if (workerCount === 0) return
+
+  let nextIdx = 0
+
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const idx = nextIdx++
+      if (idx >= items.length) return
+      const item = items[idx]!
+      await processItem(item, idx)
+      if (onSettled) await onSettled(item, idx)
+    }
+  }
+
+  await Promise.all(Array.from({ length: workerCount }, () => worker()))
+}
+
+/**
+ * PR I — build the revalidate manifest from scanned FileRoutes + the
+ * list of paths that successfully rendered.
+ *
+ * For each FileRoute with a `revalidateLiteral` (captured at scan time
+ * via `detectRouteExports`), parse the literal as JSON (numbers and
+ * `false` are valid JSON tokens), build a regex from the route's
+ * urlPath pattern, and match against `writtenPaths`. Each matching
+ * concrete path goes into the manifest under the route's revalidate
+ * value.
+ *
+ * Returns `{}` when no routes have a revalidate literal — the caller
+ * checks `Object.keys(...).length > 0` before writing the manifest.
+ *
+ * Static routes match exactly (urlPath === concretePath). Dynamic
+ * routes (`/posts/:id`) compile to `^\/posts\/[^/]+$`. Catch-alls
+ * (`/blog/:slug*`) compile to `^\/blog\/.*$`. Layout / error / loading
+ * / not-found routes are skipped — they don't appear in writtenPaths
+ * anyway, but the explicit guard keeps the helper stand-alone-testable.
+ *
+ * Exposed via `_internal.buildRevalidateManifest` so it can be unit-
+ * tested without a full SSG round-trip.
+ */
+export function buildRevalidateManifest(
+  fileRoutes: ReadonlyArray<{
+    urlPath: string
+    isLayout: boolean
+    isError: boolean
+    isLoading: boolean
+    isNotFound: boolean
+    exports?: { revalidateLiteral?: string }
+  }>,
+  writtenPaths: readonly string[],
+): Record<string, number | false> {
+  const manifest: Record<string, number | false> = {}
+  for (const route of fileRoutes) {
+    if (route.isLayout || route.isError || route.isLoading || route.isNotFound) continue
+    const literal = route.exports?.revalidateLiteral
+    if (literal === undefined) continue
+    let parsed: unknown
+    try {
+      // The literal text is a number (`60`, `3600`) or boolean
+      // (`false`). JSON.parse handles both. Other values (`true`,
+      // strings, objects) aren't valid `revalidate` shapes — skip
+      // silently rather than throw.
+      parsed = JSON.parse(literal)
+    } catch {
+      continue
+    }
+    if (typeof parsed !== 'number' && parsed !== false) continue
+    const value = parsed as number | false
+    const matcher = compileUrlPatternMatcher(route.urlPath)
+    for (const concretePath of writtenPaths) {
+      if (matcher(concretePath)) {
+        manifest[concretePath] = value
+      }
+    }
+  }
+  return manifest
+}
+
+/**
+ * Compile a route's urlPath pattern (`/posts/:id`, `/blog/:slug*`,
+ * `/about`) into a predicate that returns `true` for any concrete
+ * path that matches. Static patterns return a `===` comparator.
+ * Dynamic / catch-all patterns return a regex predicate.
+ *
+ * Internal helper to `buildRevalidateManifest`. Mirrors the routing
+ * matcher's behaviour for `:param` (single segment) and `:param*`
+ * (catch-all, zero-or-more segments). Doesn't need to handle every
+ * router edge case — the writtenPaths it matches against are already
+ * concrete (no params, no wildcards).
+ */
+function compileUrlPatternMatcher(urlPath: string): (concrete: string) => boolean {
+  if (!urlPath.includes(':') && !urlPath.includes('*')) {
+    return (concrete) => concrete === urlPath
+  }
+  // Escape regex metachars (except `:` and `*` which we handle
+  // explicitly), then substitute `:name*` → `.*` and `:name` → `[^/]+`.
+  // Order matters — `:name*` MUST be replaced before `:name`.
+  const regex = urlPath
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/:([A-Za-z_$][\w$]*)\*/g, '.*')
+    .replace(/:([A-Za-z_$][\w$]*)/g, '[^/]+')
+  const re = new RegExp(`^${regex}$`)
+  return (concrete) => re.test(concrete)
+}
+
+function renderErrorArtifact(entries: { path: string; error: unknown }[]): string {
+  const errors = entries.map(({ path, error }) => ({
+    path,
+    message: error instanceof Error ? error.message : String(error),
+    name: error instanceof Error ? error.name : 'Error',
+    stack: error instanceof Error ? error.stack : undefined,
+  }))
+  return `${JSON.stringify({ errors }, null, 2)}\n`
+}
+
+/**
+ * Inject a rendered SSR result into the index.html template. Prefers
+ * Pyreon's `<!--pyreon-head-->` / `<!--pyreon-app-->` /
+ * `<!--pyreon-scripts-->` placeholders; falls back to inserting before
+ * `</head>` / inside `<div id="app">` / before `</body>` so a bare
+ * Vite-style `index.html` (no Pyreon comments) still receives content.
+ *
+ * Factored out of the per-path render loop so the 404 emission path can
+ * reuse the exact same injection rules — keeps the rendered _404.tsx
+ * subject to the same head/body/scripts pipeline as regular pages
+ * (styler tag, @pyreon/head meta, hashed asset preload links).
+ */
+function injectIntoTemplate(
+  template: string,
+  result: { appHtml: string; head: string; loaderScript: string },
+): string {
+  let html = template
+  if (html.includes('<!--pyreon-head-->')) {
+    html = html.replace('<!--pyreon-head-->', result.head)
+  } else if (result.head) {
+    html = html.replace('</head>', `${result.head}</head>`)
+  }
+  if (html.includes('<!--pyreon-app-->')) {
+    html = html.replace('<!--pyreon-app-->', result.appHtml)
+  } else if (result.appHtml) {
+    const appDivMatch = html.match(/<div\s+id=["']app["']\s*>([\s\S]*?)<\/div>/)
+    if (appDivMatch) {
+      html = html.replace(appDivMatch[0], `<div id="app">${result.appHtml}</div>`)
+    } else {
+      html = html.replace('</body>', `<div id="app">${result.appHtml}</div></body>`)
+    }
+  }
+  if (html.includes('<!--pyreon-scripts-->')) {
+    html = html.replace('<!--pyreon-scripts-->', result.loaderScript)
+  } else if (result.loaderScript) {
+    html = html.replace('</body>', `${result.loaderScript}</body>`)
+  }
+  return html
+}
+
+/**
+ * Plugin that performs SSG when `mode: "ssg"` is configured. Wires into
+ * Vite's `closeBundle` hook so it runs once after the main client build
+ * completes. The recursive SSR sub-build is gated by an env flag.
+ */
+export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
+  const config = resolveConfig(userConfig)
+  let root = ''
+  let distDir = ''
+  // Track whether this plugin instance is running inside the inner SSR
+  // sub-build (where it must be a no-op) vs. the outer client build.
+  const isInnerBuild = process.env[SSG_BUILD_FLAG] === '1'
+
+  return {
+    name: 'pyreon-zero-ssg',
+    apply: 'build',
+    enforce: 'post',
+
+    configResolved(resolved) {
+      root = resolved.root
+      distDir = resolve(root, resolved.build.outDir)
+    },
+
+    async closeBundle() {
+      if (config.mode !== 'ssg') return
+      if (isInnerBuild) return
+
+      const ssrOutDir = join(distDir, '.zero-ssg-server')
+      const indexHtmlPath = join(distDir, 'index.html')
+
+      if (!existsSync(indexHtmlPath)) {
+        // Client build hasn't produced index.html — nothing we can wrap.
+        // Most likely: user is running `vite build --ssr` directly, in
+        // which case this plugin shouldn't be active anyway.
+        // oxlint-disable-next-line no-console
+        console.warn(
+          `[zero:ssg] Skipping SSG — ${indexHtmlPath} not found. Did the client build complete?`,
+        )
+        return
+      }
+
+      // Materialize the SSR entry to disk inside the routes directory so
+      // its imports resolve relative to the user's source tree. Doing this
+      // INSIDE node_modules-equivalent paths breaks Vite's plugin-resolution
+      // semantics; placing it next to the user's routes lets zero's main
+      // plugin pick it up identically to user code. Cleaned up after the
+      // build.
+      const entryPath = join(root, SSR_ENTRY_FILENAME)
+      // PR K: bake the configured locales into the SSG entry source so the
+      // per-locale 404 walker can detect which RouteRecord serves which
+      // locale at module-eval time inside the SSR sub-build.
+      const i18nLocales = config.i18n?.locales ?? []
+      await writeFile(entryPath, renderSsrEntrySource(i18nLocales), 'utf-8')
+
+      // Vite's programmatic build API. Loaded lazily so the plugin doesn't
+      // pull `vite` into the runtime dep graph at module-evaluation time.
+      const { build } = await import('vite')
+
+      // Inner SSR sub-build. Re-assembles zero's plugin chain plus
+      // `@pyreon/vite-plugin` (JSX compiler) — every Pyreon app already
+      // has both because zero is built on top of pyreon. Loading both
+      // lazily keeps the SSG plugin off the module-eval critical path.
+      // Env-flag gate prevents the inner ssgPlugin instance from
+      // re-triggering itself.
+      process.env[SSG_BUILD_FLAG] = '1'
+      try {
+        const [{ zeroPlugin }, pyreonModule] = await Promise.all([
+          import('./vite-plugin'),
+          import('@pyreon/vite-plugin'),
+        ])
+        const pyreon = (pyreonModule as { default: () => unknown }).default
+
+        await build({
+          root,
+          mode: 'production',
+          logLevel: 'error',
+          configFile: false,
+          publicDir: false,
+          plugins: [pyreon(), zeroPlugin(userConfig)] as Plugin[],
+          resolve: { conditions: ['bun'] },
+          build: {
+            ssr: entryPath,
+            outDir: ssrOutDir,
+            emptyOutDir: true,
+            target: 'esnext',
+            rollupOptions: {
+              input: entryPath,
+              output: {
+                format: 'es',
+                entryFileNames: 'entry-server.mjs',
+              },
+              external: [/^node:/],
+            },
+          },
+        })
+      } finally {
+        delete process.env[SSG_BUILD_FLAG]
+        // Remove the synthetic entry file so it never lands in user's
+        // working tree.
+        try {
+          await rm(entryPath, { force: true })
+        } catch {
+          // best-effort cleanup
+        }
+      }
+
+      // Load the built renderer. Use a file:// URL to avoid Node import
+      // cache collisions across multiple builds within the same process.
+      const handlerPath = join(ssrOutDir, 'entry-server.mjs')
+      if (!existsSync(handlerPath)) {
+        // oxlint-disable-next-line no-console
+        console.warn(`[zero:ssg] SSR build did not produce ${handlerPath} — skipping prerender`)
+        return
+      }
+      // The path is computed at runtime from a freshly-built SSR artifact
+      // — Vite's `dynamic-import-vars` plugin can't statically analyze the
+      // import. Without the `@vite-ignore` hint, Vite emits a console
+      // warning on every consumer's dev server boot ("The above dynamic
+      // import cannot be analyzed by Vite"), which looks alarming but is
+      // expected here. Suppress per Vite's own recommendation.
+      const handlerMod = (await import(/* @vite-ignore */ pathToFileURL(handlerPath).href)) as {
+        // PR B — return shape is a discriminated union: regular paths
+        // produce HTML, redirect-throwing loaders produce a redirect
+        // descriptor for the manifest writer.
+        default: (
+          path: string,
+        ) => Promise<
+          | { kind: 'html'; appHtml: string; head: string; loaderScript: string }
+          | { kind: 'redirect'; from: string; to: string; status: number }
+        >
+        // PR A — getStaticPaths registry collected from the routes tree.
+        __getStaticPathsRegistry?: GetStaticPathsRegistry
+        // PR C — 404 emission. The synthetic SSG entry walks the routes
+        // tree at module-eval time and exports the first
+        // `notFoundComponent` it finds (root-level `_404.tsx` in the
+        // common case), plus an async `__renderNotFound()` that pushes
+        // it through the same renderWithHead pipeline as regular paths.
+        // The outer plugin reads both: presence gates the emission,
+        // the renderer produces the same `{ appHtml, head, loaderScript }`
+        // shape so `injectIntoTemplate` can reuse the same injection
+        // rules. The `?` keeps zero forward-compatible — an entry built
+        // before PR C just doesn't expose these and emit404 silently
+        // no-ops.
+        __notFoundComponent?: unknown
+        __notFoundComponentsByLocale?: Map<string | null, unknown>
+        __renderNotFound?: (
+          locale?: string | null,
+        ) => Promise<{ appHtml: string; head: string; loaderScript: string } | null>
+      }
+      const renderPath = handlerMod.default
+      const registry = handlerMod.__getStaticPathsRegistry
+
+      // Read the user's built index.html template. Vite has just produced it
+      // with hashed asset URLs (`/assets/index-XYZ.js`), preload links, etc.
+      // We inject the rendered head/body/loader-data into placeholder
+      // comments — same convention as zero's dev SSR. If the template lacks
+      // the placeholders, we fall back to inserting before `</head>` and
+      // `</body>` respectively so a bare `index.html` still works.
+      const template = await readFile(indexHtmlPath, 'utf-8')
+
+      // Errors from getStaticPaths run AND per-page render are collected
+      // into the same array so the post-render summary catches both. The
+      // SSG plugin completes either way — a single bad route shouldn't
+      // abort the whole site build.
+      const errors: { path: string; error: unknown }[] = []
+
+      // Resolve paths and render.
+      const routesDir = join(root, 'src', 'routes')
+      const paths = await resolvePaths(config, routesDir, registry, errors)
+
+      if (paths.length === 0) {
+        // oxlint-disable-next-line no-console
+        console.warn('[zero:ssg] No static paths to prerender — set ssg.paths in zero config')
+        await rm(ssrOutDir, { recursive: true, force: true })
+        return
+      }
+
+      // M1.4 — Detect duplicate paths BEFORE the render loop. Two routes
+      // producing the same URL (a static `/posts/foo.tsx` + a dynamic
+      // `[id].tsx` with `getStaticPaths: [{id:'foo'}]`) would silently
+      // last-wins under `writtenPaths.push(p)`. Surface as an actionable
+      // error with the duplicate URL listed so users can fix the source
+      // route conflict instead of wondering why HTML mysteriously changes
+      // between rebuilds. Bisect-verified via `assertNoPathCollisions` unit
+      // tests: removing the call → fixture with dupes proceeds to render
+      // and silently overwrites; restoring → throws with the formatted
+      // error listing every duplicate URL.
+      assertNoPathCollisions(paths)
+
+      let pages = 0
+      // PR B — collect redirects from loader-throws so the post-render
+      // step can write `_redirects` / `_redirects.json` / meta-refresh
+      // HTML files. Loader redirects DON'T produce a per-path index.html
+      // — the redirect IS the response.
+      const redirects: RedirectEntry[] = []
+      // PR F — track every path that produced a `dist/<path>/index.html` so
+      // the post-loop step can emit `dist/_pyreon-ssg-paths.json` for
+      // `seoPlugin({ sitemap: { useSsgPaths: true } })` to read at its
+      // own `closeBundle`. We track the resolved URL paths (post-
+      // getStaticPaths expansion + per-locale duplication when PR H
+      // ships) — exactly what the sitemap.xml needs. Paths that errored
+      // OR redirected are intentionally absent: errored pages have no
+      // HTML to link to, and redirect sources go to `_redirects`, not
+      // sitemap.xml (linking to a redirect source confuses crawlers).
+      const writtenPaths: string[] = []
+      const start = Date.now()
+
+      // PR D — render a single path. Extracted from the inline loop body
+      // so the worker-pool below can call it concurrently. All side
+      // effects (redirects.push, errors.push, writtenPaths.push, pages++)
+      // are append-only mutations on shared arrays/counter — safe under
+      // the concurrent worker pattern because Node is single-threaded
+      // (each worker yields at every `await`, never in mid-statement).
+      //
+      // Returns the path on settle so the worker can fire onProgress with
+      // it. Throws are NOT propagated — they're caught here and recorded
+      // in `errors[]`, so a single failed path can't take down the worker.
+      const renderOne = async (p: string): Promise<void> => {
+        // M2.3 — emit `ssg.pathRender` per attempted render. Pair with
+        // `ssg.pathWrite` / `ssg.pathRedirect` / `ssg.pathError` to see
+        // per-path settle distribution.
+        if (__DEV__) _countSink.__pyreon_count__?.('ssg.pathRender')
+        try {
+          const result = await Promise.race([
+            renderPath(p),
+            new Promise<never>((_, reject) =>
+              setTimeout(() => reject(new Error(`Prerender timeout for "${p}" (30s)`)), 30_000),
+            ),
+          ])
+
+          if (result.kind === 'redirect') {
+            // M2.3 — track redirect outcomes separately from successful renders.
+            if (__DEV__) _countSink.__pyreon_count__?.('ssg.pathRedirect')
+            // PR B — loader threw `redirect()`. Record for the manifest;
+            // optionally emit a meta-refresh HTML stub at the source path.
+            redirects.push({ from: result.from, to: result.to, status: result.status })
+
+            if (config.ssg?.redirectsAsHtml === 'meta-refresh') {
+              const filePath = resolveOutputPath(distDir, p)
+              const resolvedOut = resolve(distDir)
+              if (!resolve(filePath).startsWith(resolvedOut)) {
+                errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
+                return
+              }
+              await mkdir(dirname(filePath), { recursive: true })
+              await writeFile(filePath, renderMetaRefreshHtml(result.to), 'utf-8')
+            }
+            return
+          }
+
+          const html = injectIntoTemplate(template, result)
+
+          const filePath = resolveOutputPath(distDir, p)
+
+          // Path-traversal guard — same as @pyreon/server's prerender.
+          const resolvedOut = resolve(distDir)
+          if (!resolve(filePath).startsWith(resolvedOut)) {
+            errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
+            return
+          }
+
+          await mkdir(dirname(filePath), { recursive: true })
+          await writeFile(filePath, html, 'utf-8')
+          pages++
+          writtenPaths.push(p)
+          // M2.3 — track successful HTML emits. `ssg.pathRender - ssg.pathWrite
+          // - ssg.pathRedirect - ssg.pathError` should sum to roughly zero;
+          // non-zero residual = paths swallowed silently somewhere.
+          if (__DEV__) _countSink.__pyreon_count__?.('ssg.pathWrite')
+        } catch (error) {
+          // M2.3 — track render-error outcomes.
+          if (__DEV__) _countSink.__pyreon_count__?.('ssg.pathError')
+          errors.push({ path: p, error })
+          // PR G — onPathError fallback hook. The user-supplied callback
+          // can return HTML to write at the path's URL, OR null to skip.
+          // The error is ALREADY recorded in `errors[]` before this call
+          // so the post-build summary catches it regardless of what the
+          // callback does. The callback's own throws are caught + recorded
+          // as a separate entry — a buggy callback shouldn't take down
+          // the whole build, AND we surface the bug instead of swallowing.
+          if (config.ssg?.onPathError) {
+            try {
+              const fallbackHtml = await config.ssg.onPathError(p, error)
+              if (typeof fallbackHtml === 'string') {
+                const filePath = resolveOutputPath(distDir, p)
+                const resolvedOut = resolve(distDir)
+                if (!resolve(filePath).startsWith(resolvedOut)) {
+                  errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
+                  return
+                }
+                await mkdir(dirname(filePath), { recursive: true })
+                await writeFile(filePath, fallbackHtml, 'utf-8')
+                pages++
+              }
+            } catch (callbackError) {
+              errors.push({ path: `${p} (onPathError)`, error: callbackError })
+            }
+          }
+        }
+      }
+
+      // PR D — worker-pool concurrency. Default 4 workers in flight; the
+      // user can opt into more via `ssg.concurrency` (CI multi-core) or
+      // back to 1 for fully sequential (the pre-PR-D shape). Per-path
+      // logic lives in `renderOne()`; the pool primitive lives in
+      // `runWithConcurrency()` (testable in isolation).
+      //
+      // Progress ordering: `onProgress` fires in path-SETTLE order, NOT
+      // input order. Across workers, callbacks may run in parallel —
+      // the runtime doesn't serialize them. If you need strict serial
+      // output (e.g. a progress bar painting one line at a time), wrap
+      // the callback to push to a single-consumer queue.
+      const concurrency = Math.max(1, config.ssg?.concurrency ?? 4)
+      let completed = 0
+
+      await runWithConcurrency(paths, concurrency, renderOne, async (p) => {
+        completed++
+        if (config.ssg?.onProgress) {
+          try {
+            await config.ssg.onProgress({
+              completed,
+              total: paths.length,
+              currentPath: p,
+              elapsed: Date.now() - start,
+            })
+          } catch (callbackError) {
+            errors.push({ path: `${p} (onProgress)`, error: callbackError })
+          }
+        }
+      })
+
+      // PR F — Sitemap path manifest.
+      //
+      // Write the resolved URL paths to `dist/_pyreon-ssg-paths.json` so
+      // `seoPlugin({ sitemap: { useSsgPaths: true } })` can read them at
+      // its own `closeBundle` and emit a sitemap that includes dynamic-
+      // route enumerations (PR A's `getStaticPaths`) AND per-locale
+      // variants (PR H, when shipped). Without this manifest, `seoPlugin`
+      // walks the file-system route tree directly and silently skips
+      // dynamic routes (`[id]`) because their concrete values aren't
+      // knowable at file-scan time.
+      //
+      // The 404 path is omitted intentionally — error pages don't belong
+      // in sitemap.xml. Redirected sources are ALSO omitted (they're
+      // already absent from `writtenPaths` because the loop hits the
+      // redirect branch + `continue` before the push).
+      //
+      // Always emit when SSG ran. Filename starts with `_` so static
+      // hosts that publish the dist root don't ALSO publish this internal
+      // manifest as a public asset — convention matches `_redirects` /
+      // `_redirects.json`. The seoPlugin reads + cleans it up after use.
+      if (writtenPaths.length > 0) {
+        // PR K (i18n follow-up): also embed the i18n config in the manifest
+        // when present so `seoPlugin({ sitemap: { useSsgPaths: true } })`
+        // can emit hreflang cross-references without duplicating the i18n
+        // declaration. Zero-config win — users opt into i18n routing via
+        // `zero({ i18n: { ... } })` once and both the route duplication
+        // (PR H) AND the sitemap hreflang automatically pick it up.
+        // M2.1 — atomic write so the seoPlugin (or any consumer) never reads
+        // a half-written manifest if the build is interrupted mid-flush.
+        await writeFileAtomic(
+          join(distDir, '_pyreon-ssg-paths.json'),
+          `${JSON.stringify(
+            {
+              paths: writtenPaths,
+              ...(config.i18n ? { i18n: config.i18n } : {}),
+            },
+            null,
+            2,
+          )}\n`,
+        )
+      }
+
+      // PR I — Build-time ISR revalidate manifest.
+      //
+      // Walk the route files for `export const revalidate = <n|false>`
+      // declarations (captured as a literal at scan time), match each
+      // declaration's url-pattern against the rendered written paths,
+      // and emit `dist/_pyreon-revalidate.json` mapping concrete path
+      // → revalidate value. Adapters (vercel/cloudflare/netlify) read
+      // this manifest at deploy time to wire platform-specific ISR
+      // (Vercel `output/config.json`, Cloudflare cache rules, Netlify
+      // redirect headers).
+      //
+      // Path matching: static routes (`/about`) match writtenPaths[i]
+      // exactly. Dynamic routes (`/posts/:id`) and catch-all
+      // (`/blog/:slug*`) compile to a regex and match every concrete
+      // child. Same revalidate value applies to all enumerated children
+      // — `posts/[id].tsx` with `export const revalidate = 60` gives
+      // `/posts/1`, `/posts/2`, `/posts/3` ALL `60` in the manifest.
+      //
+      // Filename starts with `_` so the static-host publish step
+      // doesn't expose it as a public asset (matches `_redirects` /
+      // `_redirects.json` / `_pyreon-ssg-paths.json` convention).
+      // ONLY emit when at least one route has a revalidate literal —
+      // empty manifests aren't useful, and absence is a meaningful
+      // signal to adapters ("no per-route ISR config, fall through to
+      // platform defaults").
+      // M2.5 — track the count for the build summary breakdown.
+      let revalidateCount = 0
+      if (existsSync(routesDir)) {
+        try {
+          const fileRoutesWithExports = await scanRouteFilesWithExports(routesDir, config.mode)
+          const revalidateManifest = buildRevalidateManifest(
+            fileRoutesWithExports,
+            writtenPaths,
+          )
+          revalidateCount = Object.keys(revalidateManifest).length
+          if (revalidateCount > 0) {
+            // M2.1 — atomic write. Adapters polling for the manifest at
+            // deploy time should see the full document or nothing.
+            await writeFileAtomic(
+              join(distDir, '_pyreon-revalidate.json'),
+              `${JSON.stringify({ revalidate: revalidateManifest }, null, 2)}\n`,
+            )
+          }
+        } catch (err) {
+          // Manifest emission is opt-in via the `revalidate` export.
+          // A scan failure shouldn't abort the build — just record it
+          // alongside the other SSG errors so CI surfaces it.
+          errors.push({ path: '(revalidate-manifest)', error: err })
+        }
+      }
+
+      // PR C — Auto-emit dist/404.html from _404.tsx convention.
+      // PR K (i18n follow-up) — also emit dist/{locale}/404.html for every
+      // locale subtree that has its own _404 (i.e. every non-default locale
+      // under `prefix-except-default`, every locale under `prefix`).
+      //
+      // fs-router scans `_404.tsx` / `_not-found.tsx` and attaches it as
+      // `notFoundComponent` on its parent layout RouteRecord (or directly
+      // on the page record when no wrapping layout exists — which is the
+      // per-locale subtree shape after PR H's root-layout-skip). The
+      // synthetic SSG entry walks the routes tree at module-eval time,
+      // collects per-locale 404 components into a Map keyed by locale
+      // (or `null` for the default / no-i18n case), and exposes an
+      // async `__renderNotFound(locale)` that renders the matching one.
+      //
+      // We iterate that map here and write each to the right path:
+      //   - `null` locale → `dist/404.html` (static-host convention —
+      //     Netlify / Cloudflare Pages / GitHub Pages / S3+CloudFront
+      //     serve this for unmatched URLs by default)
+      //   - non-null locale `de` → `dist/de/404.html` (mirrors how those
+      //     same hosts serve per-prefix 404s when configured with the
+      //     `errors_404` field per directory in `netlify.toml` / etc.)
+      //
+      // Per-locale 404 lets search engines + users see a 404 page in the
+      // right language with the right navigation chrome, not the
+      // default-locale page bolted onto a German URL.
+      //
+      // Gated by `config.ssg.emit404 !== false` (default true). Skipped
+      // silently when no `_404.tsx` exists anywhere — the Map is empty
+      // and the loop body never runs.
+      let emitted404Count = 0
+      if (config.ssg?.emit404 !== false && handlerMod.__renderNotFound) {
+        // Back-compat: old SSG entries (pre-PR-K) expose only the singular
+        // `__notFoundComponent`; new entries expose the Map. Build a synthetic
+        // single-entry iterator from the singular when the Map isn't there
+        // so users with a stale SSR_ENTRY cache or downstream consumers that
+        // never rebuilt their lib/ keep emitting one 404.html.
+        const localeEntries: (string | null)[]
+          = handlerMod.__notFoundComponentsByLocale instanceof Map
+            ? [...handlerMod.__notFoundComponentsByLocale.keys()]
+            : handlerMod.__notFoundComponent
+              ? [null]
+              : []
+
+        for (const locale of localeEntries) {
+          try {
+            const result = await Promise.race([
+              handlerMod.__renderNotFound(locale),
+              new Promise<never>((_, reject) =>
+                setTimeout(
+                  () =>
+                    reject(
+                      new Error(
+                        `Prerender timeout for ${locale == null ? '404' : `${locale}/404`} (30s)`,
+                      ),
+                    ),
+                  30_000,
+                ),
+              ),
+            ])
+            if (result) {
+              const html = injectIntoTemplate(template, result)
+              const filePath
+                = locale == null
+                  ? join(distDir, '404.html')
+                  : join(distDir, locale, '404.html')
+              // Ensure the locale subdirectory exists before writeFile —
+              // dist/de/ may not have been created yet if no static pages
+              // landed under that locale, but most apps will have at
+              // least the locale-root index.html so this is usually a no-op.
+              if (locale != null) {
+                await mkdir(join(distDir, locale), { recursive: true })
+              }
+              await writeFile(filePath, html, 'utf-8')
+              emitted404Count++
+              // M2.3 — track per-locale 404 emits.
+              if (__DEV__) _countSink.__pyreon_count__?.('ssg.404Emit')
+            }
+          } catch (error) {
+            errors.push({
+              path: locale == null ? '404.html' : `${locale}/404.html`,
+              error,
+            })
+          }
+        }
+      }
+
+      // PR B — emit redirect manifests when loaders threw `redirect()`.
+      // Both Netlify (`_redirects`) and Vercel (`_redirects.json`)
+      // formats ship together so the user doesn't have to pick at SSG
+      // time. The file is empty / absent when no redirects fired.
+      if (redirects.length > 0 && config.ssg?.emitRedirects !== false) {
+        // M2.1 — atomic so an interrupted build doesn't leave a half-
+        // written `_redirects` file that adapters / static hosts misparse.
+        await writeFileAtomic(
+          join(distDir, '_redirects'),
+          renderNetlifyRedirects(redirects),
+        )
+        await writeFileAtomic(
+          join(distDir, '_redirects.json'),
+          renderVercelRedirectsJson(redirects),
+        )
+      }
+
+      // PR G — emit `dist/_pyreon-ssg-errors.json` summarising every error
+      // captured during the render loop (path traversal, render exception,
+      // getStaticPaths throw, onPathError throw, 404 render fail). 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.
+      //
+      // Default: 'json' (write the artifact). Set `errorArtifact: 'none'`
+      // to opt out — errors stay console-only, matching pre-PR-G behaviour.
+      if (errors.length > 0 && config.ssg?.errorArtifact !== 'none') {
+        // M2.1 — atomic so CI that reads this manifest (`jq '.errors | length'`)
+        // never sees a partial-JSON parse error from an interrupted build.
+        await writeFileAtomic(
+          join(distDir, '_pyreon-ssg-errors.json'),
+          renderErrorArtifact(errors),
+        )
+      }
+
+      // PR J — adapter.build() invocation for SSG mode. Each platform
+      // adapter (vercel/cloudflare/netlify) writes its routing config
+      // for the prerendered dist; static / node / bun adapters no-op
+      // for SSG (they're SSR runners or trivial).
+      //
+      // Pre-PR-J: Adapter.build() was implemented per-platform but
+      // never invoked from any build pipeline — the methods existed
+      // but no production code path called them. SSG is the natural
+      // first hook because the dist/ shape is final at this point
+      // (all paths rendered, redirects + sitemap manifests written).
+      // Adapter throws are caught here so a buggy adapter can't take
+      // down the rest of the build (sitemap, error artifact, summary
+      // log all already ran). The error lands in the error log + the
+      // _pyreon-ssg-errors.json if errorArtifact was set, but we
+      // emit it AFTER the artifact write so the path-render errors
+      // already in the file aren't displaced.
+      const adapter = resolveAdapter(config)
+      try {
+        await adapter.build({ kind: 'ssg', outDir: distDir, config })
+      } catch (adapterError) {
+        errors.push({ path: `(adapter:${adapter.name})`, error: adapterError })
+      }
+
+      // Cleanup the SSR build artifacts — they're an implementation detail
+      // and shouldn't ship to the static host.
+      await rm(ssrOutDir, { recursive: true, force: true })
+
+      const elapsed = Date.now() - start
+      const redirectsSummary = redirects.length > 0 ? ` + ${redirects.length} redirect(s)` : ''
+      const concurrencySummary = concurrency > 1 ? ` (concurrency: ${concurrency})` : ''
+      const adapterSummary = adapter.name !== 'node' ? ` [adapter: ${adapter.name}]` : ''
+      // M2.5 — revalidate-manifest entry count surfaces in the summary so
+      // users see at a glance whether per-route ISR config landed in
+      // `_pyreon-revalidate.json` (vs silently empty because no route
+      // exported a `revalidate` literal).
+      const revalidateSummary =
+        revalidateCount > 0 ? ` + ${revalidateCount} revalidate path(s)` : ''
+      // M2.5 — per-locale breakdown when i18n config is active. The
+      // breakdown is computed from `writtenPaths` — each path either has a
+      // locale prefix (`/de/...`) or belongs to the default locale (under
+      // `prefix-except-default`) / is locale-less (no i18n). Surfaces
+      // shape mismatches: `[en: 100, de: 90, cs: 100]` flags that de had
+      // 10 paths skipped relative to the others.
+      const localeSummary = config.i18n ? buildLocaleSummary(writtenPaths, config.i18n) : ''
+      // oxlint-disable-next-line no-console
+      console.log(
+        `[zero:ssg] Prerendered ${pages} page(s)${
+          emitted404Count > 0
+            ? emitted404Count === 1
+              ? ' + 404.html'
+              : ` + ${emitted404Count} 404 pages`
+            : ''
+        }${redirectsSummary}${revalidateSummary} in ${elapsed}ms${concurrencySummary}${adapterSummary}${localeSummary}` +
+          (errors.length > 0 ? ` (${errors.length} error(s))` : ''),
+      )
+      for (const { path: errPath, error } of errors) {
+        // oxlint-disable-next-line no-console
+        console.error(`[zero:ssg] Failed to prerender "${errPath}":`, error)
+      }
+    },
+  } satisfies Plugin
+}
+
+// ─── Test exports ─────────────────────────────────────────────────────────────
+//
+// Internal helpers exposed for unit tests. Not part of the public API.
+
+export const _internal = {
+  resolvePaths,
+  autoDetectStaticPaths,
+  resolveOutputPath,
+  expandUrlPattern,
+  injectIntoTemplate,
+  renderNetlifyRedirects,
+  renderVercelRedirectsJson,
+  renderMetaRefreshHtml,
+  renderErrorArtifact,
+  runWithConcurrency,
+  buildRevalidateManifest,
+  renderSsrEntrySource,
+  SSR_ENTRY_FILENAME,
+  detectPathCollisions,
+  formatPathCollisionError,
+  assertNoPathCollisions,
+  writeFileAtomic,
+  buildLocaleSummary,
+}