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

package/src/build/index.ts

@@ -7,14 +7,20 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
-import { BrustRouteError, validateRoutes } from '../routes'
-import { type BrowserCtx, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, storeModules } from './bundle'
+import { BrustRouteError, type FlatRoute, validateRoutes } from '../routes'
+import { type BrowserCtx, setDevBuild, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, storeModules } from './bundle'
+import { runActionsOnly } from './actions-only'
 import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflare'
-import { compileApp } from './compile'
+import { renderIcons } from './build-icons'
+import { evaluateBuildSlots } from './build-eval'
+import { type Compiled, compileApp } from './compile'
+import { buildCss, CssGraph, directCss, resolveGlobals, routeCssSources } from './css'
 import { type ActionsBuildConfig, type CacheBuildConfig, loadBuildConfig } from './config'
 import { BuildError } from './errors'
-import { type CacheRecord, type ManifestJson, writeManifest } from './manifest'
+import { type CacheRecord, type ManifestJson, tierOf, writeManifest } from './manifest'
 import { scanRoutes } from './scan'
+import { type ExprReads, prepareStatic, writeStatic } from './static'
+import { writeStaticWorker } from './static-worker'
 
 export { BuildError } from './errors'
 
@@ -80,21 +86,40 @@ export async function runBuild(opts: {
   outDir: string
   /** Replace a non-empty out dir even without a previous build's marker. */
   force?: boolean
-  /** `cloudflare` also writes `<out>/cf/` (M4-CF); default `bun` = the unchanged build. */
-  target?: 'bun' | 'cloudflare'
+  /** `cloudflare` also writes `<out>/cf/` (M4-CF); `static` also writes `<out>/static/` (gaps round
+   * L9); default `bun` = the unchanged build. */
+  target?: 'bun' | 'cloudflare' | 'static'
+  /** `--strict` (static): a loader that reads the request fails the build. */
+  strict?: boolean
+  /** The cache key grammar's read-set (static; tests swap it). Default: the addon. */
+  exprReads?: ExprReads
   /** `--wasm-from-source` (cloudflare only). */
   wasmFromSource?: boolean
+  /** `--actions-only` (L16 R16.3): no pages, only the `[actions]` app; with `bun` (default) or `cloudflare`. */
+  actionsOnly?: boolean
+  /** `brust build --dev` (L14, used by `brust dev`): also writes `dev.json` and builds the client runtime with `__BRUST_DEV__`. */
+  dev?: boolean
   log: (s: string) => void
 }): Promise<void> {
+  setDevBuild(opts.dev === true)
   const appRoot = resolve(opts.appRoot)
   const entry = resolve(appRoot, opts.entry)
   const dist = resolve(appRoot, opts.outDir)
   assertSafeOutDir(dist, appRoot, [entry, join(appRoot, 'public')])
   assertReplaceable(dist, opts.force)
-  const { serverOnly, actions, cloudflare, cache } = await loadBuildConfig(appRoot)
+  const built = await loadBuildConfig(appRoot, { actionsOnly: opts.actionsOnly === true })
+  if (opts.actionsOnly)
+    return runActionsOnly({ appRoot, dist, config: built, target: opts.target, wasmFromSource: opts.wasmFromSource === true, statOk, assertSafeOutDir, log: opts.log })
+  const { serverOnly, cloudflare, cache, cssGlobal } = built
+  // L16 R16.4b: `[actions]` with a `base_url` and no actions file (the default name, not one written in the toml)
+  // is a page-only build: the app is deployed elsewhere, so nothing is bundled or mounted here.
+  const remote =
+    built.actions !== null && built.actions.baseUrl !== undefined && !built.actions.entryExplicit && !statOk(resolve(appRoot, built.actions.entry)) ? built.actions : null
+  const actions = remote ? null : built.actions
+  if (actions?.prefix === '/') throw new BuildError('config', 'actions.prefix "/" is only for an actions-only build (brust build --actions-only) or a page-only build that points at one')
 
   // Everything that can fail on the app's own input runs before a byte is written.
-  const { routes, componentFile } = await scanRoutes(entry)
+  const { routes, componentFile, componentIssue } = await scanRoutes(entry, appRoot)
   let leaves: ReturnType<typeof validateRoutes>
   try {
     leaves = validateRoutes(routes)
@@ -129,8 +154,16 @@ export async function runBuild(opts: {
   }
   assertSafeOutDir(dist, appRoot, [...componentFile.values(), ...(actionsEntry ? [actionsEntry] : []), ...(cacheModule ? [cacheModule] : [])])
 
+  // R9.3/R9.4: every reason to refuse a static build, before any write.
+  const ssgPlan =
+    opts.target === 'static'
+      ? await prepareStatic(leaves, actions !== null, opts.exprReads ?? (await import('../native')).cacheExprReads, opts.log, cache)
+      : null
+
   // Config, @brust/core-cf resolution and the user's wrangler file fail here, before any write.
-  const cf = opts.target === 'cloudflare' ? await prepareCloudflare(appRoot, cloudflare, { fromSource: opts.wasmFromSource === true, env: process.env }) : null
+  // L12: a static build with `[actions]` also builds the Cloudflare worker (its Pages `_worker.js`).
+  const hybrid = ssgPlan !== null && actions !== null
+  const cf = opts.target === 'cloudflare' || hybrid ? await prepareCloudflare(appRoot, cloudflare, { fromSource: opts.wasmFromSource === true, env: process.env }) : null
 
   // Sibling of `dist` (same filesystem: the final rename is atomic), fixed name (no random bytes in
   // anything the bundler sees).
@@ -138,7 +171,13 @@ export async function runBuild(opts: {
   rmSync(tmp, { recursive: true, force: true })
   mkdirSync(tmp, { recursive: true })
   try {
-    await buildInto(tmp, { appRoot, entry, dist, leaves, componentFile, serverOnly, actions, actionsEntry, cache, cacheModule, cf, log: opts.log })
+    await buildInto(tmp, { dev: opts.dev === true, appRoot, entry, dist, leaves, componentFile, componentIssue, serverOnly, actions, actionsEntry, cache, cacheModule, cf, hybrid, cssGlobal, actionsRemote: remote?.prefix ?? null, log: opts.log })
+    if (ssgPlan) {
+      // Rendered from the finished temp dist, so a failed render leaves the previous dist untouched.
+      const version: string = (await Bun.file(join(import.meta.dir, '../../package.json')).json()).version
+      await writeStatic(tmp, { entry, appRoot, plan: ssgPlan, version, strict: opts.strict === true, log: opts.log, shownDir: join(dist, 'static') })
+      if (hybrid && cf && actions) writeStaticWorker(tmp, actions, cf, opts.log)
+    }
     rmSync(join(tmp, '.stage'), { recursive: true, force: true })
     if (existsSync(dist)) {
       const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
@@ -156,12 +195,15 @@ export async function runBuild(opts: {
 async function buildInto(
   out: string,
   o: {
+    /** Write `dev.json` (L14). */
+    dev: boolean
     appRoot: string
     entry: string
     /** The final dist dir (`index.js` points at the entry relative to it). */
     dist: string
     leaves: ReturnType<typeof validateRoutes>
     componentFile: Map<Function, string>
+    componentIssue: Map<Function, string>
     serverOnly: string[]
     actions: ActionsBuildConfig | null
     /** Absolute path of the actions entry (null when `[actions]` is off). */
@@ -170,21 +212,52 @@ async function buildInto(
     /** Absolute path of a custom cache adapter module. */
     cacheModule: string | null
     cf: CfPrepared | null
+    /** `[css] global` as written (app-root relative). */
+    cssGlobal: string[]
+    /** L16 R16.4b: the prefix of an actions app deployed elsewhere (a page-only build); absent = a local app or none. */
+    actionsRemote: string | null
+    /** `--target static` with `[actions]`: the worker is built without the cache (static pages are never cached). */
+    hybrid: boolean
     log: (s: string) => void
   },
 ): Promise<void> {
   const { appRoot, entry, leaves } = o
-  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [] }
+  // L19: every stylesheet first, so each JS build below reads one set of CSS Module class maps.
+  const graph = new CssGraph()
+  const chainFiles = (l: FlatRoute) => l.chain.flatMap((n) => (n.Component && o.componentFile.has(n.Component) ? [o.componentFile.get(n.Component)!] : []))
+  const routeCss = routeCssSources(leaves, chainFiles, resolveGlobals(appRoot, o.cssGlobal), graph)
+  const serverCss = [o.actionsEntry, o.cacheModule].flatMap((f) => (f ? graph.of(f) : []))
+  mkdirSync(join(out, 'client'), { recursive: true })
+  // Review N3: `brust dev` builds with BRUST_BUILD_MODE=development (as the JS bundles): readable, unminified CSS.
+  const css = await buildCss(out, [...new Set([...[...routeCss.values()].flat(), ...serverCss])], process.env.BRUST_BUILD_MODE !== 'development', { appRoot, log: o.log })
+  for (const c of directCss(entry))
+    o.log(`[brust] warning css ${relative(appRoot, entry)} imports ${c}: the route entry belongs to no route, so it is linked nowhere; import it from a layout, or list it in [css] global`)
+  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [], cssMaps: css.maps }
   // The runtime first: its hashed URL is the `runtimeImport` every client chunk is compiled with.
   const runtime = await buildRuntime(out, ctx)
-  const { compiled, routeComponent } = compileApp({
+  const compileOpts = {
     appRoot,
     leaves,
     componentFile: o.componentFile,
+    componentIssue: o.componentIssue,
     runtimeImport: `/_brust/${runtime}`,
     serverOnly: o.serverOnly,
-    log: o.log,
-  })
+    cssMaps: css.maps,
+  }
+  const firstLog: string[] = []
+  let { compiled, routeComponent } = compileApp({ ...compileOpts, log: (l) => firstLog.push(l) })
+  // L23: lucide icons the compiler could inline are rendered here (react-dom/server); L2: slots that read
+  // nothing request- or time-dependent are computed once, here. The app is compiled again with both (an icon with
+  // no markup stays the L22 island; a slot with a value is a literal: no job, no worker). The first compile's
+  // warnings describe icons that are inline now, so when icons were rendered only the last compile's are shown.
+  const hasIcons = [...compiled.values()].some((c) => (c.ir.icon_requests ?? []).length > 0)
+  const iconSvgs = hasIcons ? await renderIcons(compiled, appRoot, o.log) : undefined
+  const slotValues = await evaluateBuildSlots(out, compiled, ctx.sourceOf, appRoot, o.log)
+  const hasSlots = Object.keys(slotValues).length > 0
+  if (hasIcons || hasSlots) {
+    if (!hasIcons) firstLog.forEach((l) => o.log(l))
+    ;({ compiled, routeComponent } = compileApp({ ...compileOpts, iconSvgs, iconsFinal: hasIcons, slotValues, log: hasIcons ? o.log : () => {} }))
+  } else firstLog.forEach((l) => o.log(l))
 
   mkdirSync(join(out, 'jinja'), { recursive: true })
   for (const c of compiled.values()) writeFileSync(join(out, 'jinja', `${c.id}.jinja`), c.jinja)
@@ -192,13 +265,19 @@ async function buildInto(
   const runtimeUrl = `/_brust/${runtime}`
   const chunks = new Map([...(await buildClientChunks(out, compiled, ctx, runtimeUrl)), ...(await buildReactChunks(out, compiled, ctx, runtimeUrl))])
   const manifest = writeManifest({ leaves, routeComponent, compiled, runtime, chunks })
-  await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest))
+  for (const r of manifest.routes) {
+    const files = [...new Set((routeCss.get(r.id) ?? []).flatMap((s) => (css.file.has(s) ? [css.file.get(s)!] : [])))]
+    if (files.length > 0) r.css = files
+  }
+  await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest), css.maps)
   manifest.actions =
     o.actions && o.actionsEntry
-      ? { entry: await buildActions(out, o.actionsEntry), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }
+      ? { entry: await buildActions(out, o.actionsEntry, css.maps), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }
       : null
-  if (o.cache) manifest.cache = await cacheRecord(out, manifest, o.cache, o.cacheModule)
+  if (o.actionsRemote !== null) manifest.actions_remote = { prefix: o.actionsRemote }
+  if (o.cache) manifest.cache = await cacheRecord(out, manifest, o.cache, o.cacheModule, css.maps)
   writeFileSync(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  if (o.dev) writeFileSync(join(out, 'dev.json'), `${JSON.stringify(devJson(appRoot, compiled), null, 2)}\n`)
   writeFileSync(join(out, MARKER), 'generated by `brust build`: this directory is replaced on every build\n')
 
   const pub = join(appRoot, 'public')
@@ -206,7 +285,19 @@ async function buildInto(
   if (o.cf) {
     const warnings = await buildCloudflare(
       out,
-      { appRoot, entry, dist: o.dist, compiled, manifest, sourceOf: ctx.sourceOf, actionsEntry: o.actionsEntry, cacheModule: o.cacheModule, cacheGetTimeoutMs: o.cache?.getTimeoutMs, log: o.log },
+      {
+        appRoot,
+        entry,
+        dist: o.dist,
+        compiled,
+        manifest: o.hybrid ? { ...manifest, cache: undefined } : manifest,
+        sourceOf: ctx.sourceOf,
+        actionsEntry: o.actionsEntry,
+        cacheModule: o.hybrid ? null : o.cacheModule,
+        cacheGetTimeoutMs: o.hybrid ? undefined : o.cache?.getTimeoutMs,
+        cssMaps: css.maps,
+        log: o.log,
+      },
       o.cf,
     )
     for (const w of warnings) o.log(w)
@@ -227,10 +318,34 @@ async function buildInto(
   )
 }
 
+/** `dev.json` (L14, R14.2): component id → source file, tier, the react reason, diagnostics. Only `brust build --dev` writes it. */
+export function devJson(appRoot: string, compiled: Map<string, Compiled>): { version: 1; components: Record<string, DevComponent> } {
+  const components: Record<string, DevComponent> = {}
+  for (const c of compiled.values()) {
+    const tier = tierOf(c.ir)
+    const t = c.ir.tier
+    components[c.id] = {
+      file: relative(appRoot, c.file),
+      tier,
+      ...(tier === 'react' && t && typeof t === 'object' && 'React' in t ? { reason: String((t as { React: { reason: string } }).React.reason) } : {}),
+      diagnostics: (c.diagnostics ?? []).map((d) => ({ class: d.class, rule: d.rule, line: d.line, col: d.col, message: d.message, remediation: d.remediation })),
+    }
+  }
+  return { version: 1, components }
+}
+
+export interface DevComponent {
+  file: string
+  tier: 'static' | 'native' | 'react'
+  /** Why the compiler chose the react tier (the IR's `React.reason`). */
+  reason?: string
+  diagnostics: { class: string; rule: string; line: number; col: number; message: string; remediation: string }[]
+}
+
 /** `manifest.cache` (R7, R8): the custom module bundled for the worker, the native defaults, and the
  * build id every L2 key carries. */
-async function cacheRecord(out: string, manifest: ManifestJson, c: CacheBuildConfig, moduleAbs: string | null): Promise<CacheRecord> {
-  const module = moduleAbs ? await buildCacheAdapter(out, moduleAbs) : undefined
+async function cacheRecord(out: string, manifest: ManifestJson, c: CacheBuildConfig, moduleAbs: string | null, cssMaps: Map<string, Record<string, string>>): Promise<CacheRecord> {
+  const module = moduleAbs ? await buildCacheAdapter(out, moduleAbs, cssMaps) : undefined
   return {
     adapter: c.adapter,
     ...(module ? { module } : {}),

package/src/build/manifest.ts

@@ -29,6 +29,10 @@ export interface ChildRecord {
   id: string
   instances: string
   props: Record<string, string>
+  /** F105: constant props; part of the child's job keys. */
+  literals?: Record<string, unknown>
+  /** F105: jinja over `__props` (and `__row`/`__idx` per row) the server evaluates. */
+  exprs?: Record<string, string>
 }
 
 export interface ComponentRecord {
@@ -49,6 +53,8 @@ export interface RouteRecord {
   loaders: string[]
   cache: { ttl_seconds: number; prefix: string | null; bypass: true | string | null; tags: string[] } | null
   catch_all: boolean
+  /** L19 (R19.3): `client/<file>.css` in cascade order; absent when the route has none. */
+  css?: string[]
 }
 
 /** `manifest.actions` (A3): `entry` is relative to dist; `maxBodyBytes`/`maxResponseBytes` are camelCase by contract. */
@@ -60,13 +66,20 @@ export interface ActionsRecord {
   crossSite: 'reject' | 'allow'
 }
 
+/** The manifest format the Rust loader accepts (`MANIFEST_VERSION` in brust-core `manifest.rs`): the one place TS names it. */
+export const MANIFEST_VERSION = 2 as const
+
 export interface ManifestJson {
-  version: 1
+  version: typeof MANIFEST_VERSION
   routes: RouteRecord[]
   components: Record<string, ComponentRecord>
   assets: { runtime: string }
   jobs_module: string
   actions: ActionsRecord | null
+  /** L16 R16.3: an actions-only build (no routes, no templates); everything but the prefix is a 404 problem+json. */
+  actions_only?: true
+  /** L16 R16.4b: a page-only build: no local actions app, `base_url` points at the deployment that has it. */
+  actions_remote?: { prefix: string }
   /** `[cache]` (cache adapters); absent without one (the manifest is then byte-identical). */
   cache?: CacheRecord
 }
@@ -231,10 +244,16 @@ export function childRecords(c: Compiled, clientOnly: string[] = []): ChildRecor
     const props: Record<string, string> = {}
     for (const [name, path] of Object.entries(inst.props)) {
       if (path === null)
-        throw new BuildError('instance-prop-path', `${ir.id}: child ${inst.child_id} prop ${name} is not a props path`)
+        throw new BuildError(
+          'instance-prop-path',
+          `${ir.id}: child ${inst.child_id} prop ${name} is not a props path, a JSON literal or a template expression over props; compute it in a loader, or wrap the child's derived value in cache()`,
+        )
       props[name] = path
     }
-    return { id: inst.child_id, instances: list === undefined ? 'static' : `per-row:${list}`, props }
+    const rec: ChildRecord = { id: inst.child_id, instances: list === undefined ? 'static' : `per-row:${list}`, props }
+    if (inst.literals && Object.keys(inst.literals).length > 0) rec.literals = { ...inst.literals }
+    if (inst.exprs && Object.keys(inst.exprs).length > 0) rec.exprs = { ...inst.exprs }
+    return rec
   })
   for (const id of clientOnly) out.push({ id, instances: 'static', props: {} })
   return out
@@ -302,7 +321,7 @@ export function writeManifest(opts: {
     }
   })
   linkNativeChunks(routes, compiled, components)
-  return { version: 1, routes, components, assets: { runtime: opts.runtime }, jobs_module: 'jobs.js', actions: opts.actions ?? null }
+  return { version: MANIFEST_VERSION, routes, components, assets: { runtime: opts.runtime }, jobs_module: 'jobs.js', actions: opts.actions ?? null }
 }
 
 /** S6 amendment (F66): the server's asset injection walks only each chain component's direct

package/src/build/scan.ts

@@ -1,13 +1,15 @@
-// Route scan (plan T5): import the route entry, then map every route Component to the `.tsx`
-// file it is the default export of. The compiler only ever sees files, never functions.
-import { readFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+// Route scan (plan T5, gaps L7): import the route entry, then walk its static import graph (inside the app root,
+// outside node_modules) and map every Component to the `.tsx` file it is the default export of. The compiler only ever sees files, never functions.
+import { readFileSync, realpathSync } from 'node:fs'
+import { dirname, resolve, sep } from 'node:path'
 import { BrustRouteError, type Route } from '../routes'
 import { BuildError } from './errors'
 
-const DEFAULT_IMPORT = /^\s*import\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\})?\s+from\s+['"]([^'"]+)['"]/gm
-
-export async function scanRoutes(entryFile: string): Promise<{ routes: Route[]; componentFile: Map<Function, string> }> {
+/** `componentIssue` explains a Component the walk saw but could not map (named-only, outside the root, in node_modules). */
+export async function scanRoutes(
+  entryFile: string,
+  appRoot?: string,
+): Promise<{ routes: Route[]; componentFile: Map<Function, string>; componentIssue: Map<Function, string> }> {
   // biome-ignore lint/suspicious/noExplicitAny: an arbitrary user module
   let mod: any
   try {
@@ -21,22 +23,59 @@ export async function scanRoutes(entryFile: string): Promise<{ routes: Route[];
   if (!Array.isArray(routes))
     throw new BuildError('route-entry', `${entryFile} exports neither \`routes\` nor a default route array`)
 
-  const src = readFileSync(entryFile, 'utf8')
-  const real = new Set(new Bun.Transpiler({ loader: 'tsx' }).scanImports(src).map((i) => i.path))
   const componentFile = new Map<Function, string>()
-  for (const m of src.matchAll(DEFAULT_IMPORT)) {
-    const spec = m[2]!
-    if (!real.has(spec)) continue // inside a comment or string: not an import
-    let file: string
+  const componentIssue = new Map<Function, string>()
+  const root = realpathSync(resolve(appRoot ?? dirname(entryFile)))
+  const transpiler = new Bun.Transpiler({ loader: 'tsx' })
+  const inRoot = (f: string) => f.startsWith(root + sep) && !f.split(sep).includes('node_modules')
+  const visited = new Set<string>()
+  // Post-order: a file's imports are mapped before the file itself, and the first file to claim a function
+  // keeps it, so the module that defines a Component beats a barrel that re-exports it.
+  const visit = async (file: string): Promise<void> => {
+    if (visited.has(file)) return
+    visited.add(file)
+    let src: string
     try {
-      file = Bun.resolveSync(spec, dirname(entryFile))
+      src = readFileSync(file, 'utf8')
     } catch {
-      continue // a bare specifier the route file never uses as a Component; checked below
+      return
+    }
+    const loader = file.endsWith('.tsx') ? transpiler : file.endsWith('.ts') ? new Bun.Transpiler({ loader: 'ts' }) : null
+    if (!loader) return
+    const deps: string[] = []
+    // Only static imports are followed: a dynamic import() is not part of the route table's static graph.
+    for (const imp of loader.scanImports(src)) {
+      if (imp.kind !== 'import-statement') continue
+      let dep: string
+      try {
+        dep = Bun.resolveSync(imp.path, dirname(file))
+      } catch {
+        continue // a bare specifier that does not resolve; a route using it fails in compileApp
+      }
+      if (!dep.endsWith('.tsx') && !dep.endsWith('.ts')) continue
+      if (inRoot(dep)) deps.push(dep)
+      else if (dep.endsWith('.tsx')) await note(dep, dep.split(sep).includes('node_modules') ? 'in node_modules' : `outside the app root ${root}`)
+    }
+    for (const dep of deps) await visit(dep)
+    if (!file.endsWith('.tsx')) return
+    const m = await import(file)
+    for (const [name, v] of Object.entries(m)) {
+      if (typeof v !== 'function') continue
+      if (name === 'default') {
+        if (!componentFile.has(v)) componentFile.set(v, file)
+      } else if (!componentIssue.has(v)) {
+        componentIssue.set(v, `${v.name || name} is only a named export of ${file} (export ${name}): export it as default`)
+      }
     }
-    if (!file.endsWith('.tsx')) continue // not a component source; a route using it fails in compileApp
-    const def = (await import(file)).default
-    // Bun's module cache: the same function object the routes tree holds.
-    if (typeof def === 'function') componentFile.set(def, file)
   }
-  return { routes, componentFile }
+  const note = async (file: string, why: string) => {
+    try {
+      const def = (await import(file)).default
+      if (typeof def === 'function' && !componentIssue.has(def)) componentIssue.set(def, `${def.name || '(anonymous)'} lives in ${file}, which is ${why}`)
+    } catch {}
+  }
+  await visit(entryFile)
+  // A function reachable as a default somewhere is fine; only an unmapped one keeps its explanation.
+  for (const f of componentFile.keys()) componentIssue.delete(f)
+  return { routes, componentFile, componentIssue }
 }

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
+  })
+}