@brust/core 2.0.0-alpha.3 → 2.0.0-alpha.30

package/src/build/server-only.ts

@@ -0,0 +1,62 @@
+// The `server-only` marker package (Next.js convention): a module that starts with `import 'server-only'` is server code.
+// The published package throws when it is resolved without the `react-server` condition, which both lets server-only code
+// into a browser bundle whenever the marker is stubbed (a bundler alias, an empty `node_modules/server-only`) and breaks a
+// correct app whose route scan imports it under the default condition. brust does not rely on the throw:
+//   - a BROWSER build that reaches the specifier is refused (`server-only-in-client`, bundle.ts `isServerOnly`);
+//   - every SERVER side (route scan, worker import of the app, jobs / actions / cache-adapter / build-eval / Worker
+//     bundles) resolves it to an empty module, the same thing the `react-server` condition resolves to.
+import type { BunPlugin } from 'bun'
+
+const MARKER = /^server-only(\/.*)?$/
+const NS = 'brust-server-only-empty'
+
+/** `server-only` itself or one of its subpaths. */
+export const isServerOnlyMarker = (spec: string): boolean => MARKER.test(spec)
+
+/** A build plugin for a SERVER bundle: the marker becomes an empty module. */
+export function serverOnlyEmptyPlugin(): BunPlugin {
+  return {
+    name: 'brust-server-only-empty',
+    setup(b) {
+      b.onResolve({ filter: MARKER }, (a) => ({ path: a.path, namespace: NS }))
+      b.onLoad({ filter: /.*/, namespace: NS }, () => ({ contents: 'export {}', loader: 'js' }))
+    },
+  }
+}
+
+let installed = false
+/** For code the process imports directly (the build's route scan, the worker's import of the app entry): a virtual
+ * module, so a bare `import 'server-only'` never reaches the package. Idempotent; only the marker is touched. */
+export function installServerOnlyRuntime(): void {
+  if (installed) return
+  installed = true
+  Bun.plugin({
+    name: 'brust-server-only-runtime',
+    setup(b) {
+      b.module('server-only', () => ({ exports: {}, loader: 'object' }))
+    },
+  })
+}
+
+let jsxDevInstalled = false
+/** F425: Bun picks the dev JSX transform (`jsxDEV` from `react/jsx-dev-runtime`) for modules the process imports directly
+ * when NODE_ENV is unset as Bun boots (a plain shell `brust start`), but React's production `react/jsx-dev-runtime` has no
+ * `jsxDEV`, and run.ts sets NODE_ENV=production for the workers afterwards. A module that builds a JSX element at import
+ * time (`export const el = <b/>`) then died with "jsxDEV_… is not a function". In production, `react/jsx-dev-runtime` is the
+ * production `jsx`/`jsxs` (resolved from the app, so it is the app's one React) with a `jsxDEV` over them; dev keeps React's own. */
+export function installProductionJsxDev(appDir: string): void {
+  if (jsxDevInstalled || process.env.NODE_ENV !== 'production') return
+  jsxDevInstalled = true
+  Bun.plugin({
+    name: 'brust-jsx-dev-production',
+    setup(b) {
+      b.module('react/jsx-dev-runtime', async () => {
+        const rt = await import(Bun.resolveSync('react/jsx-runtime', appDir))
+        return {
+          exports: { Fragment: rt.Fragment, jsx: rt.jsx, jsxs: rt.jsxs, jsxDEV: (type: unknown, props: unknown, key: unknown, isStatic: boolean) => (isStatic ? rt.jsxs : rt.jsx)(type, props, key) },
+          loader: 'object',
+        }
+      })
+    },
+  })
+}

package/src/build/ssg-render.ts

@@ -0,0 +1,65 @@
+// The child process `brust build --target static` renders in (gaps round L9): boots the real server
+// on loopback with the normal workers (`run()`, so every byte is what `brust start` sends), fetches
+// each planned path, writes the responses to `BRUST_SSG_OUT`, then drains. A child process, because
+// the napi server is a per-process singleton. Input: `BRUST_SSG_PLAN` (a JSON list of paths).
+import { appendFileSync, readFileSync, writeFileSync } from 'node:fs'
+import { run } from '../run'
+
+export interface Rendered {
+  path: string
+  status: number
+  headers: Record<string, string>
+  /** base64 */
+  body: string
+}
+
+/** A page that did not answer within the per-page limit (review N3). */
+export class PageTimeout extends Error {
+  constructor(
+    readonly path: string,
+    readonly ms: number,
+  ) {
+    super(`GET ${path} did not answer within ${ms} ms`)
+  }
+}
+
+/** The seam an in-process host can replace later: GET each path from `base`, uncompressed, no redirect
+ * following, each within `pageMs` (`PageTimeout`). `started` hears each path before it is requested. */
+export async function renderPaths(base: string, paths: string[], pageMs = 30_000, started: (path: string) => void = () => {}): Promise<Rendered[]> {
+  const out: Rendered[] = []
+  for (const path of paths) {
+    started(path)
+    const signal = AbortSignal.timeout(pageMs)
+    try {
+      const r = await fetch(base + path, { redirect: 'manual', headers: { 'accept-encoding': 'identity' }, signal })
+      out.push({ path, status: r.status, headers: Object.fromEntries(r.headers), body: Buffer.from(await r.arrayBuffer()).toString('base64') })
+    } catch (e) {
+      if (signal.aborted) throw new PageTimeout(path, pageMs)
+      throw e
+    }
+  }
+  return out
+}
+
+if (import.meta.main) {
+  const env = process.env
+  const paths = JSON.parse(readFileSync(env.BRUST_SSG_PLAN!, 'utf8')) as string[]
+  await run({
+    distDir: env.BRUST_DIST_DIR,
+    entry: env.BRUST_APP_ENTRY,
+    config: { host: '127.0.0.1', port: 0 },
+    onReady: async (addr) => {
+      const pageMs = Number(env.BRUST_SSG_PAGE_TIMEOUT_MS) || 30_000
+      const progress = env.BRUST_SSG_PROGRESS
+      try {
+        const pages = await renderPaths(`http://${addr}`, paths, pageMs, (p) => progress && appendFileSync(progress, `${p}\n`))
+        writeFileSync(env.BRUST_SSG_OUT!, JSON.stringify({ addr, pages }))
+        return 0
+      } catch (e) {
+        if (!(e instanceof PageTimeout)) throw e
+        writeFileSync(env.BRUST_SSG_OUT!, JSON.stringify({ addr, timeout: { path: e.path, ms: e.ms } }))
+        return 1
+      }
+    },
+  })
+}

package/src/build/ssg.ts

@@ -0,0 +1,146 @@
+// `brust build --target static` planner (gaps round L9, R9.2-R9.3): which paths to render and the
+// file each one is written to. Pure: no server, no filesystem. `params()` results come in resolved.
+import type { FlatRoute, RouteSsgConfig } from '../routes'
+import { BuildError } from './errors'
+
+/** The path the `*` route is rendered at: no route matches it, so the server answers the 404 page. */
+export const NOT_FOUND_PATH = '/__brust_ssg_not_found__'
+
+export interface PlannedPage {
+  /** The request path (each `{name}` value percent-encoded). */
+  path: string
+  /** Relative to the static dir: `index.html`, `docs.html`, `docs/x.html`, `404.html`. */
+  file: string
+  routeId: string
+  pattern: string
+  /** 200, or 404 for the `*` route. */
+  expect: 200 | 404
+}
+
+export interface StaticPlan {
+  pages: PlannedPage[]
+  /** Routes `ssg: false` left out (listed in the report). */
+  skipped: { routeId: string; pattern: string }[]
+  /** No `*` route: the build writes a default 404.html. */
+  defaultNotFound: boolean
+}
+
+/** A leaf's own `ssg` field (the last node of its chain). */
+export function ssgOf(leaf: FlatRoute): RouteSsgConfig | undefined {
+  return leaf.chain[leaf.chain.length - 1]?.ssg
+}
+
+const SEGMENT = /\{(\*?)([^}]*)\}/g
+
+/** The `{name}` / `{*name}` segment names of a pattern, in order. */
+export function patternParams(pattern: string): { name: string; rest: boolean }[] {
+  return [...pattern.matchAll(SEGMENT)].map((m) => ({ name: m[2]!, rest: m[1] === '*' }))
+}
+
+/** The file a request path is written to: `/` → `index.html`, `/a/b` → `a/b.html` (decoded, so a
+ * host that decodes the URL finds it). A segment that is not valid percent-encoding (a stray `%`)
+ * is a `ssg-param-encoding` error naming `where` (review N1), never a URIError. */
+export function fileFor(path: string, where = path): string {
+  if (path === '/') return 'index.html'
+  const decoded = path
+    .slice(1)
+    .split('/')
+    .map((s) => {
+      try {
+        return decodeURIComponent(s)
+      } catch {
+        throw new BuildError('ssg-param-encoding', `${where}: path segment ${JSON.stringify(s)} is not valid percent-encoding (write a literal % as %25)`)
+      }
+    })
+    .join('/')
+  return `${decoded}.html`
+}
+
+/** `encodeURIComponent`, as an `ssg-param-encoding` error naming `where` for a lone surrogate (review N1). */
+function encodeSegment(v: string, where: string): string {
+  try {
+    return encodeURIComponent(v)
+  } catch {
+    throw new BuildError('ssg-param-encoding', `${where} = ${JSON.stringify(v)} is not encodable (a lone UTF-16 surrogate)`)
+  }
+}
+
+/** One `{name}` value: a non-empty string; `/` only in a `{*rest}` value, and never an empty, `.`
+ * or `..` segment (the file name would leave its directory). */
+function checkValue(leaf: FlatRoute, i: number, name: string, rest: boolean, v: unknown): string {
+  const where = `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}].${name}`
+  if (typeof v !== 'string' || v === '') throw new BuildError('ssg-params', `${where} is ${v === '' ? 'empty' : 'missing'}: every {${name}} needs a non-empty string`)
+  if (!rest && v.includes('/')) throw new BuildError('ssg-params', `${where} = ${JSON.stringify(v)} contains '/': a {${name}} value is one path segment`)
+  for (const seg of v.split('/'))
+    if (seg === '' || seg === '.' || seg === '..') throw new BuildError('ssg-params', `${where} = ${JSON.stringify(v)} has an empty, '.' or '..' segment`)
+  return v
+}
+
+/** Plans every page. `params` holds each dynamic route's resolved `ssg.params()` by route id. */
+export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): StaticPlan {
+  const pages: PlannedPage[] = []
+  const skipped: StaticPlan['skipped'] = []
+  let catchAll: FlatRoute | undefined
+  for (const leaf of leaves) {
+    const ssg = ssgOf(leaf)
+    if (ssg === false) {
+      skipped.push({ routeId: leaf.id, pattern: leaf.pattern })
+      continue
+    }
+    if (leaf.catchAll) {
+      catchAll = leaf
+      continue
+    }
+    const names = patternParams(leaf.pattern)
+    if (names.length === 0) {
+      pages.push({ path: leaf.pattern, file: fileFor(leaf.pattern, `route ${leaf.id} (${leaf.pattern})`), routeId: leaf.id, pattern: leaf.pattern, expect: 200 })
+      continue
+    }
+    if (!ssg || ssg.params === undefined)
+      throw new BuildError(
+        'ssg-params-missing',
+        `route ${leaf.id} (${leaf.pattern}) is dynamic: add ssg: { params: () => [{ ${names.map((n) => `${n.name}: '…'`).join(', ')} }] } or ssg: false`,
+      )
+    const recs = params.get(leaf.id)
+    if (!Array.isArray(recs)) throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() must return an array of records`)
+    recs.forEach((rec, i) => {
+      if (typeof rec !== 'object' || rec === null || Array.isArray(rec)) throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}] is not a record`)
+      const r = rec as Record<string, unknown>
+      let k = 0
+      const path = leaf.pattern.replace(SEGMENT, () => {
+        const { name, rest } = names[k++]!
+        const v = checkValue(leaf, i, name, rest, r[name])
+        return v
+          .split('/')
+          .map((seg) => encodeSegment(seg, `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}].${name}`))
+          .join('/')
+      })
+      pages.push({ path, file: fileFor(path, `route ${leaf.id} (${leaf.pattern})`), routeId: leaf.id, pattern: leaf.pattern, expect: 200 })
+    })
+  }
+  const seen = new Map<string, PlannedPage>()
+  // Keyed case-folded (review N2): macOS and Windows file systems are case-insensitive, so `/A` and
+  // `/a` would overwrite each other's file.
+  for (const p of pages) {
+    const key = p.file.toLowerCase()
+    const prev = seen.get(key)
+    if (prev && prev.file === p.file) throw new BuildError('ssg-params', `${prev.path} (route ${prev.routeId}) and ${p.path} (route ${p.routeId}) both write ${p.file}`)
+    if (prev)
+      throw new BuildError(
+        'ssg-path-collision',
+        `${prev.path} (route ${prev.routeId}, ${prev.file}) and ${p.path} (route ${p.routeId}, ${p.file}) differ only by case: on a case-insensitive file system one file overwrites the other`,
+      )
+    seen.set(key, p)
+  }
+  if (seen.has('404.html')) throw new BuildError('ssg-params', `${seen.get('404.html')!.path} would overwrite 404.html`)
+  if (catchAll) pages.push({ path: NOT_FOUND_PATH, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
+  return { pages, skipped, defaultNotFound: catchAll === undefined }
+}
+
+/** The output paths `ssg.params()` must be resolved for: dynamic leaves with `ssg.params`. */
+export function paramRoutes(leaves: FlatRoute[]): FlatRoute[] {
+  return leaves.filter((l) => {
+    const ssg = ssgOf(l)
+    return !l.catchAll && ssg && ssg.params !== undefined && patternParams(l.pattern).length > 0
+  })
+}

package/src/build/static-worker.ts

@@ -0,0 +1,91 @@
+// `brust build --target static` with `[actions]` (gaps round L12, R12.1): the static tree plus a
+// Cloudflare Pages advanced-mode Worker that serves ONLY the action prefix.
+//   static/_worker.js/index.js   a WorkerEntrypoint: the action prefix -> the Cloudflare core, everything else -> env.ASSETS
+//   static/_worker.js/core/      the `--target cloudflare` worker tree (glue + wasm + brust-app.js), verbatim
+//   static/_routes.json          include: the prefix only, so pages and assets never invoke the Worker
+//   wrangler.jsonc         the Pages project file (name, compatibility date); sits next to `static/`
+import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type CfPrepared, cacheNeeds } from './cloudflare'
+import { workerNameOf } from './cf-wrangler'
+import { BuildError } from './errors'
+import { CF_MIN_COMPAT_DATE } from './config'
+import type { CacheRecord } from './manifest'
+
+/** `.assetsignore`: the Worker source and the routes file are deploy inputs, never public assets. */
+export const ASSETS_IGNORE = '_worker.js\n_routes.json\n.assetsignore\n'
+
+/** The deploy inputs the Worker answers with a 404 (N1). */
+export const HIDDEN = ['/_worker.js', '/_worker.js/*', '/_routes.json', '/.assetsignore']
+
+/** `_routes.json` (R12.1): the prefix itself and everything under it reach the Worker, and so do the
+ * deploy inputs (N1): a static host that would otherwise serve `_worker.js/*` as files (the local
+ * `wrangler pages dev` does) is answered by the Worker's 404 instead. Pages and assets never do. */
+export function routesJson(prefix: string): string {
+  return `${JSON.stringify({ version: 1, include: [prefix, `${prefix}/*`, ...HIDDEN], exclude: [] }, null, 2)}\n`
+}
+
+/** `_worker.js/index.js`. Pages' pipeline wants a module object with `fetch`, not the class the core
+ * exports (a WorkerEntrypoint whose `fetch` reads `this.env` and `this.ctx`), so the core's method is
+ * called with exactly those two. A request that reaches the Worker and is not an action (a path
+ * `_routes.json` keeps away, or a probe) falls through to the static files, except the deploy inputs
+ * themselves (`_worker.js/*`, `_routes.json`, `.assetsignore`), which are a 404 whatever serves the assets (N1). */
+export function workerSource(main: string, prefix: string): string {
+  const q = JSON.stringify
+  return `${[
+    '// generated by `brust build --target static` (actions on Pages) — do not edit',
+    `import Core from ${q(`./core/${main}`)}`,
+    `const PREFIX = ${q(prefix)}`,
+    'export default {',
+    '  fetch(request, env, ctx) {',
+    '    const path = new URL(request.url).pathname',
+    '    if (path === PREFIX || path.startsWith(`${PREFIX}/`)) return Core.prototype.fetch.call({ env, ctx }, request)',
+    '    let plain = path',
+    '    try { plain = decodeURIComponent(path) } catch {}',
+    '    if (/^\\/(_worker\\.js(\\/|$)|_routes\\.json$|\\.assetsignore$)/i.test(plain)) return new Response("Not Found", { status: 404 })',
+    '    return env.ASSETS.fetch(request)',
+    '  },',
+    '}',
+  ].join('\n')}\n`
+}
+
+/** The Pages project file: bindings and secrets are the user's (`wrangler pages` / the dashboard), never baked. */
+export function pagesConfig(p: CfPrepared): string {
+  const name = p.cfg.name ?? (p.pkgName ? workerNameOf(p.pkgName) : undefined)
+  const compatibilityDate = p.cfg.compatibilityDate ?? p.core.meta.compatibilityDate
+  if (compatibilityDate < CF_MIN_COMPAT_DATE) throw new BuildError('config', `compatibility_date ${compatibilityDate} is older than ${CF_MIN_COMPAT_DATE}`)
+  const c = { ...(name !== undefined ? { name } : {}), pages_build_output_dir: './static', compatibility_date: compatibilityDate }
+  return `// generated by \`brust build --target static\` — bindings and secrets: \`wrangler pages secret put\` / the dashboard (docs/cloudflare.md §12)\n${JSON.stringify(c, null, 2)}\n`
+}
+
+/** R12: `[cache]` does not apply to static pages, and the Worker serves actions only, so an adapter
+ * that needs a Cloudflare binding (KV, Durable Object) has nowhere to be used: refused before any write. */
+export function assertNoCacheBindings(cache: Pick<CacheRecord, 'adapter' | 'broadcast' | 'options' | 'broadcastOptions'> | null | undefined): void {
+  const need = cacheNeeds(cache ?? undefined)
+  if (need)
+    throw new BuildError(
+      'ssg-actions-cache',
+      `[cache] adapter "${cache!.adapter}" needs a Cloudflare binding (${[need.kv && `KV ${need.kv}`, need.do && `Durable Object ${need.do}`].filter(Boolean).join(', ')}), which the static + actions Worker does not carry (static pages are never cached, the Worker serves actions only); drop [cache], or use --target cloudflare`,
+    )
+}
+
+/** Turns `<dist>/cf/` (built by `buildCloudflare`) into the Pages Worker inside `<dist>/static/`, then
+ * drops `cf/`: the build is `--target static`, its only output is `static/`. */
+export function writeStaticWorker(dist: string, actions: { prefix: string }, p: CfPrepared, log: (s: string) => void): void {
+  const staticDir = join(dist, 'static')
+  const worker = join(dist, 'cf', 'worker')
+  if (!existsSync(join(worker, p.core.meta.main))) throw new BuildError('cf-wasm', `the Cloudflare build wrote no worker/${p.core.meta.main}`)
+  const out = join(staticDir, '_worker.js')
+  rmSync(out, { recursive: true, force: true })
+  cpSync(worker, join(out, 'core'), { recursive: true })
+  writeFileSync(join(out, 'index.js'), workerSource(p.core.meta.main, actions.prefix))
+  writeFileSync(join(staticDir, '_routes.json'), routesJson(actions.prefix))
+  // Workers Static Assets uploads the whole directory as public files unless told otherwise; Pages never serves these two.
+  writeFileSync(join(staticDir, '.assetsignore'), ASSETS_IGNORE)
+  writeFileSync(join(dist, 'wrangler.jsonc'), pagesConfig(p))
+  const report = join(staticDir, 'ssg.json')
+  const json = JSON.parse(readFileSync(report, 'utf8')) as Record<string, unknown>
+  writeFileSync(report, `${JSON.stringify({ ...json, actions: { prefix: actions.prefix, worker: '_worker.js' } }, null, 2)}\n`)
+  rmSync(join(dist, 'cf'), { recursive: true, force: true })
+  log(`[brust] static: actions under ${actions.prefix} are served by _worker.js (_routes.json keeps pages and assets off the Worker)`)
+}

package/src/build/static.ts

@@ -0,0 +1,259 @@
+// `brust build --target static` (gaps round L9, R9.1-R9.5): after the normal dist is built, render
+// every planned page through the real server (a child process, `ssg-render.ts`) and write
+// `<out>/static/`: one HTML file per page, `404.html`, the assets the native host serves
+// (`layoutAssets`), `_headers`, `_redirects` and an `ssg.json` report. The layout is what
+// Cloudflare Pages and Workers Static Assets (`not_found_handling = "404-page"`) serve as is.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { FlatRoute } from '../routes'
+import { layoutAssets } from './cf-assets'
+import { BuildError } from './errors'
+import type { Rendered } from './ssg-render'
+import { assertNoCacheBindings } from './static-worker'
+import { NOT_FOUND_PATH, type PlannedPage, type StaticPlan, paramRoutes, planStatic, ssgOf } from './ssg'
+
+export interface StaticOptions {
+  /** `--strict`: a loader reading the request fails the build instead of warning. */
+  strict: boolean
+}
+
+/** The request reads of one cache key expression (the server's grammar, through the addon). */
+export type ExprReads = (expr: string) => string[]
+
+/** R9.3/R9.4: everything that refuses a static build, checked before a byte is written; then the
+ * resolved plan. `actions`: whether `[actions]` is configured. */
+export async function prepareStatic(
+  leaves: FlatRoute[],
+  actions: boolean,
+  reads: ExprReads,
+  log: (s: string) => void,
+  cache?: Parameters<typeof assertNoCacheBindings>[0],
+): Promise<StaticPlan> {
+  // L12: `[actions]` makes the output hybrid (static pages + a Pages Worker for the action prefix).
+  if (actions) assertNoCacheBindings(cache)
+  let cacheInfo = false
+  for (const leaf of leaves) {
+    const cache = leaf.chain[leaf.chain.length - 1]?.cache
+    if (!cache || ssgOf(leaf) === false) continue
+    cacheInfo = true
+    for (const [field, expr] of [
+      ['prefix', cache.prefix],
+      ['bypass', typeof cache.bypass === 'string' ? cache.bypass : undefined],
+    ] as const) {
+      if (expr === undefined) continue
+      let r: string[]
+      try {
+        r = reads(expr)
+      } catch (e) {
+        throw new BuildError('ssg-varies', `route ${leaf.id} (${leaf.pattern}) cache.${field}: ${(e as Error).message}`)
+      }
+      if (r.length > 0)
+        throw new BuildError(
+          'ssg-varies',
+          `route ${leaf.id} (${leaf.pattern}) cache.${field} reads ${r.join(', ')}: the page varies per request, and a static file is one page for everyone (set ssg: false on the route, or drop the read)`,
+        )
+    }
+  }
+  if (cacheInfo) log('[brust] static: cache.ttl_seconds does not apply to static files (ignored)')
+  const params = new Map<string, unknown>()
+  for (const leaf of paramRoutes(leaves)) {
+    const ssg = ssgOf(leaf)
+    if (!ssg || !ssg.params) continue
+    try {
+      params.set(leaf.id, await ssg.params())
+    } catch (e) {
+      throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() threw: ${(e as Error).message ?? String(e)}`)
+    }
+  }
+  return planStatic(leaves, params)
+}
+
+export interface StaticReport {
+  pages: { path: string; file: string; routeId: string }[]
+  redirects: { from: string; to: string; status: number }[]
+  skipped: { routeId: string; pattern: string }[]
+  notFound: { file: '404.html'; routeId: string | null }
+  warnings: string[]
+}
+
+type SsgRecord =
+  | { kind: 'read'; routeId: string; path: string; field: string; key: string }
+  | { kind: 'headers'; routeId: string; path: string; names: string[] }
+
+// F468: like every page the build renders, the default 404 carries `<meta name="generator" content="brust/<version>">`.
+const default404 = (version: string) =>
+  `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>404 Not Found</title><meta name="generator" content="brust/${version.replace(/[&"<>]/g, (c) => `&#${c.charCodeAt(0)};`)}"></head><body><h1>404 Not Found</h1></body></html>\n`
+
+/** A `_redirects` source as Cloudflare Pages matches it (review N4): the decoded path, with only what
+ * the file format or the decoding needs escaped (whitespace and control characters, and `%`, so a
+ * literal `%` is not read as an escape). Non-ASCII stays as UTF-8. */
+export function redirectSource(path: string): string {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(path)
+  } catch {
+    decoded = path
+  }
+  return decoded.replace(/[\s%\u0000-\u001f\u007f]/gu, (c) => encodeURIComponent(c))
+}
+
+const text = (r: Rendered) => Buffer.from(r.body, 'base64').toString('utf8')
+const excerpt = (s: string) => (s.length > 300 ? `${s.slice(0, 300)}…` : s).replace(/\s+/g, ' ').trim()
+
+/** Spawns the render child against the dist at `dist`; the rendered responses in plan order and
+ * the loader records. `cwd` is the app root (its `brust.toml` is the server's config). */
+async function render(dist: string, entry: string, cwd: string, paths: string[]): Promise<{ addr: string; rendered: Rendered[]; records: SsgRecord[] }> {
+  const stage = join(dist, '.ssg')
+  mkdirSync(stage, { recursive: true })
+  const plan = join(stage, 'plan.json')
+  const out = join(stage, 'rendered.json')
+  const logFile = join(stage, 'records.jsonl')
+  const progress = join(stage, 'progress.txt')
+  writeFileSync(plan, JSON.stringify(paths))
+  writeFileSync(logFile, '')
+  writeFileSync(progress, '')
+  const proc = Bun.spawn([process.execPath, join(import.meta.dir, 'ssg-render.ts')], {
+    cwd,
+    env: {
+      ...process.env,
+      BRUST_DIST_DIR: dist,
+      BRUST_APP_ENTRY: entry,
+      BRUST_SSG: '1',
+      BRUST_SSG_PLAN: plan,
+      BRUST_SSG_OUT: out,
+      BRUST_SSG_LOG: logFile,
+      BRUST_SSG_PROGRESS: progress,
+      BRUST_ADDR: '127.0.0.1',
+      BRUST_PORT: '',
+    },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  // Review N3: the whole render is bounded too; past it the child (our own PID) is killed.
+  const totalMs = Number(process.env.BRUST_SSG_TIMEOUT_MS) || 600_000
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<'late'>((r) => {
+    timer = setTimeout(() => r('late'), totalMs)
+  })
+  const texts = Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+  const first = await Promise.race([proc.exited, late])
+  clearTimeout(timer)
+  if (first === 'late') {
+    proc.kill('SIGKILL')
+    await proc.exited
+    const last = readFileSync(progress, 'utf8').trim().split('\n').pop() || '(before the first page)'
+    throw new BuildError('ssg-timeout', `the render took longer than ${totalMs} ms (BRUST_SSG_TIMEOUT_MS); it was rendering ${last}`)
+  }
+  const code = first
+  const [stdout, stderr] = await texts
+  const result = existsSync(out) ? (JSON.parse(readFileSync(out, 'utf8')) as { addr: string; pages?: Rendered[]; timeout?: { path: string; ms: number } }) : null
+  if (result?.timeout)
+    throw new BuildError('ssg-timeout', `GET ${result.timeout.path} did not answer within ${result.timeout.ms} ms (BRUST_SSG_PAGE_TIMEOUT_MS)`)
+  if (code !== 0 || !result?.pages) throw new BuildError('ssg-render', `the render server failed (exit ${code}):\n${(stderr || stdout).trim()}`)
+  const { addr, pages: rendered } = result as { addr: string; pages: Rendered[] }
+  const records = readFileSync(logFile, 'utf8')
+    .split('\n')
+    .filter((l) => l !== '')
+    .map((l) => JSON.parse(l) as SsgRecord)
+  rmSync(stage, { recursive: true, force: true })
+  return { addr, rendered, records }
+}
+
+/** Renders `plan` against the built dist at `dist` and writes `<dist>/static/`. Returns the report. */
+export async function writeStatic(
+  dist: string,
+  o: { entry: string; appRoot: string; plan: StaticPlan; version: string; strict: boolean; log: (s: string) => void; /** The dir as the user will find it (the build renders into a temp dist). */ shownDir?: string },
+): Promise<StaticReport> {
+  const dir = join(dist, 'static')
+  rmSync(dir, { recursive: true, force: true })
+  const assetsStage = join(dist, '.ssg-assets')
+  const assets = layoutAssets(dist, assetsStage, o.version)
+  renameSync(join(assetsStage, 'assets'), dir)
+  rmSync(assetsStage, { recursive: true, force: true })
+  const warnings = [...assets.warnings]
+  const warn = (w: string) => {
+    warnings.push(w)
+    o.log(w)
+  }
+  for (const w of assets.warnings) o.log(w)
+
+  // R9.4: [cache] does not apply to static files, so the render must not need its adapter (a Redis
+  // that is not running at build time): the render reads a manifest without `cache`, and the dist
+  // keeps the real one for `brust start`.
+  const manifestFile = join(dist, 'manifest.json')
+  const manifest = readFileSync(manifestFile, 'utf8')
+  const parsed = JSON.parse(manifest) as { cache?: unknown }
+  if (parsed.cache) {
+    o.log('[brust] static: [cache] does not apply to static files (ignored while rendering)')
+    writeFileSync(manifestFile, `${JSON.stringify({ ...parsed, cache: null }, null, 2)}\n`)
+  }
+  let r: Awaited<ReturnType<typeof render>>
+  try {
+    r = await render(dist, o.entry, o.appRoot, o.plan.pages.map((p) => p.path))
+  } finally {
+    writeFileSync(manifestFile, manifest)
+  }
+  const { addr, rendered, records } = r
+  const report: StaticReport = { pages: [], redirects: [], skipped: o.plan.skipped, notFound: { file: '404.html', routeId: null }, warnings }
+  const write = (file: string, body: Buffer) => {
+    mkdirSync(dirname(join(dir, file)), { recursive: true })
+    writeFileSync(join(dir, file), body)
+  }
+  rendered.forEach((r, i) => {
+    const page: PlannedPage = o.plan.pages[i]!
+    const where = `GET ${page.path} (route ${page.routeId} ${page.pattern})`
+    const body = Buffer.from(r.body, 'base64')
+    if (text(r).includes(addr) || (r.headers.location ?? '').includes(addr))
+      throw new BuildError('ssg-render', `${where}: the response names the render server's loopback origin; a static page must not (build absolute URLs from a configured origin)`)
+    if (page.expect === 404) {
+      if (r.status !== 404) throw new BuildError('ssg-render', `${where}: the * route answered ${r.status}, want 404: ${excerpt(text(r))}`)
+      write('404.html', body)
+      report.notFound.routeId = page.routeId
+      return
+    }
+    if (r.status === 200) {
+      write(page.file, body)
+      report.pages.push({ path: page.path, file: page.file, routeId: page.routeId })
+      return
+    }
+    if (r.status >= 300 && r.status < 400 && r.headers.location) {
+      report.redirects.push({ from: page.path, to: r.headers.location, status: r.status })
+      return
+    }
+    throw new BuildError('ssg-render', `${where}: status ${r.status}, want 200 (or a redirect()): ${excerpt(text(r))}`)
+  })
+  if (o.plan.defaultNotFound) {
+    write('404.html', Buffer.from(default404(o.version)))
+    warn("[brust] warning ssg-404 no '*' route: wrote a default 404.html (without one, Cloudflare Pages serves every unknown path as the home page)")
+  }
+  writeFileSync(join(dir, '_redirects'), report.redirects.map((r) => `${redirectSource(r.from)} ${r.to} ${r.status}\n`).join(''))
+
+  const seen = new Set<string>()
+  const reads: string[] = []
+  for (const rec of records) {
+    const leaf = o.plan.pages.find((p) => p.routeId === rec.routeId)
+    const route = `route ${rec.routeId}${leaf ? ` (${leaf.pattern})` : ''}`
+    if (rec.kind === 'headers') {
+      const key = `h ${rec.routeId} ${rec.names.join(',')}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      warn(`[brust] warning ssg-headers ${route}: the loader's response headers (${rec.names.join(', ')}) are dropped: a static file carries none`)
+      continue
+    }
+    const key = `r ${rec.routeId} ${rec.field} ${rec.key}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const what = rec.key === '*' ? `lists req.${rec.field}` : `reads req.${rec.field}[${JSON.stringify(rec.key)}]`
+    reads.push(`${route} ${what} (at ${rec.path}): the static page is what a visitor with no headers, cookies or query sees`)
+  }
+  if (reads.length > 0 && o.strict) throw new BuildError('ssg-request-read', reads.join('\n'))
+  for (const r of reads) warn(`[brust] warning ssg-request-read ${r}`)
+
+  writeFileSync(join(dir, 'ssg.json'), `${JSON.stringify(report, null, 2)}\n`)
+  o.log(
+    `[brust] static: ${report.pages.length} page(s), ${report.redirects.length} redirect(s), 404.html${report.notFound.routeId ? '' : ' (default)'}${report.skipped.length ? `, ${report.skipped.length} route(s) ssg: false` : ''} -> ${o.shownDir ?? dir}`,
+  )
+  return report
+}
+
+export { NOT_FOUND_PATH }