@brust/core 2.0.0-alpha.1 → 2.0.0-alpha.10

package/src/build/pkg-src.ts

@@ -0,0 +1,383 @@
+// Package sources (shadcn S3 step 1, F153c, R34.61/R34.62): the compiler analyses a package component from the
+// AUTHORED source its source map carries (`sourcesContent`), never from the published JS (G1, G2). This module runs
+// no package code: sources are read, transpiled for the integrity check, and written, never imported; the compiler
+// only parses them, and the build never evaluates a slot of a component compiled from them (L2). (The route scan
+// imports the app graph, and with it the packages' published JS, as it always has: that is not new here.)
+//
+// For every bare import the app reaches (and, transitively, every bare import of a package source written here),
+// the package's ESM entry is resolved, its `.map` read, and the `.ts`/`.tsx` sources written under
+// `<app>/.brust/pkg-src/p-<hash>/` (the hash of the package's path: bun's store installs one copy per dependant; no
+// text the package controls is ever part of a path). The compiler gets the resolution map (`PackageSources`), so it reads only what this build wrote:
+// the directory is removed first, and a stale one is never consulted.
+//
+// Fail closed: a package with no ESM entry, no map, no source for its entry, a source outside the package, a
+// relative import the map does not carry, a dynamic `import()` or `eval`, or a source whose literals and names are
+// not all in the published JS (R34.62: the React build runs the dist, not the map; a containment check of literals and
+// names, i.e. fidelity, not a security boundary: the author controls both files) is REFUSED, with the reason;
+// the compiler then renders its components as React islands of the package export, exactly as before.
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+import { BuildError } from './errors'
+
+/** What the compiler reads (`AnalyzeOptions.packages`): per importing scope (`""` = the app, else the root-relative
+ * directory of a written package), each bare specifier → the root-relative path of its written entry source, or the
+ * reason it was refused. */
+export interface PackageSources {
+  scopes: Record<string, Record<string, string>>
+  refused: Record<string, Record<string, string>>
+  /** Each written directory (root-relative) → the package's real directory: a bare import in an artifact compiled from
+   * a package source resolves from the package, as it does in a real install (not read by the compiler). */
+  dirs: Record<string, string>
+}
+
+/** The last build's written directories (absolute) → the package's real directory, for the bundler. */
+const writtenDirs = new Map<string, string>()
+
+/** The real directory of the package whose written source `file` (absolute) is, if it is one. */
+export function packageDirOf(file: string): string | undefined {
+  for (const [dir, real] of writtenDirs) if (file.startsWith(dir + sep) || file.startsWith(`${dir}/`)) return real
+  return undefined
+}
+
+/** Where the sources go, relative to the app root. */
+export const PKG_SRC_DIR = '.brust/pkg-src'
+
+const lstatSyncOrNull = (p: string) => {
+  try {
+    return lstatSync(p)
+  } catch {
+    return null
+  }
+}
+
+/** Never followed: the React runtime itself, brust, and platform modules. */
+const NEVER = (spec: string) =>
+  /^(react|react-dom|scheduler)(\/|$)/.test(spec) ||
+  /^(@brust\/|brust(\/|$)|brustjs(\/|$))/.test(spec) ||
+  /^(node|bun):/.test(spec) ||
+  // L23 inlines lucide icons from the package export; the icons pass owns them.
+  /^lucide-react(\/|$)/.test(spec)
+
+const LIMITS = { packages: 256, bytesPerPackage: 4 * 1024 * 1024, totalBytes: 64 * 1024 * 1024 }
+
+type Outcome = { ok: true; dir: string; entry: string; imports: string[] } | { ok: false; reason: string }
+
+/** `@scope/name/sub` → [`@scope/name`, `sub`]. */
+export function splitSpecifier(spec: string): [string, string] {
+  const parts = spec.split('/')
+  const n = spec.startsWith('@') ? 2 : 1
+  return [parts.slice(0, n).join('/'), parts.slice(n).join('/')]
+}
+
+/** The first `node_modules/<name>` from `from` upwards, as a real path. */
+function findPackage(name: string, from: string): string | null {
+  for (let dir = from; ; ) {
+    const p = join(dir, 'node_modules', name)
+    if (existsSync(join(p, 'package.json'))) return realpathSync(p)
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+/** The package's ESM entry for `import` (exports `.` → `import`/`module`/`default`, then `module`). */
+function esmEntry(pj: Record<string, unknown>): string | null {
+  const pick = (x: unknown): string | null => {
+    if (typeof x === 'string') return x
+    if (!x || typeof x !== 'object') return null
+    const o = x as Record<string, unknown>
+    for (const k of ['import', 'module', 'default']) if (k in o) return pick(o[k])
+    return null
+  }
+  const exp = pj.exports
+  const dot = typeof exp === 'string' ? exp : exp && typeof exp === 'object' ? (exp as Record<string, unknown>)['.'] : undefined
+  const viaExports = dot === undefined ? null : pick(dot)
+  if (viaExports) return viaExports
+  return typeof pj.module === 'string' ? pj.module : null
+}
+
+/** The source map of `file`: its `sourceMappingURL` (a relative file), else `<file>.map`. */
+function mapOf(file: string): string | null {
+  const text = readFileSync(file, 'utf8')
+  const m = /\/\/# sourceMappingURL=([^\s'"]+)\s*$/.exec(text)
+  if (m && !m[1]!.startsWith('data:') && !/^[a-z]+:/i.test(m[1]!)) {
+    const p = join(dirname(file), m[1]!)
+    if (existsSync(p)) return p
+  }
+  return existsSync(`${file}.map`) ? `${file}.map` : null
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Integrity (R34.62): every string/number literal and every name of the transpiled sources occurs in the published
+// file the map belongs to. Both sides go through the same transpiler first, so quoting and type syntax agree.
+
+/** Names the JSX transform and esbuild add or rename (`undefined` prints as `void 0`); not evidence either way. */
+const JSX_NAMES = new Set(['createElement', '__name', '__defProp', 'React', 'undefined'])
+const JSX_RUNTIME = /^(?:jsx|jsxs|jsxDEV|Fragment)(?:_[\w$]+)?$/
+/** Keywords are syntax, not names: esbuild prints `const` as `var` and drops `type`/`interface` with the types. */
+const KEYWORDS = new Set(
+  'await break case catch class const continue debugger default delete do else enum export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield async of get set as from type declare readonly abstract namespace module satisfies keyof infer is unique asserts override accessor'.split(' '),
+)
+
+export interface Skeleton {
+  strings: Set<string>
+  names: Set<string>
+}
+
+/** Literals and names of transpiled JS (a small lexer: strings, templates, comments, numbers, identifiers; a regex
+ * literal may be read as names, which only makes a mismatch more likely: fail closed). */
+export function skeleton(js: string): Skeleton {
+  const strings = new Set<string>()
+  const names = new Set<string>()
+  let i = 0
+  const n = js.length
+  const templateDepth: number[] = []
+  let braces = 0
+  const readTemplateChunk = () => {
+    // at the char after '`' or after the '}' that closes `${`
+    let s = ''
+    while (i < n) {
+      const c = js[i]!
+      if (c === '\\') {
+        s += js.slice(i, i + 2)
+        i += 2
+      } else if (c === '`') {
+        i++
+        strings.add(s)
+        return
+      } else if (c === '$' && js[i + 1] === '{') {
+        i += 2
+        strings.add(s)
+        templateDepth.push(braces)
+        braces++
+        return
+      } else {
+        s += c
+        i++
+      }
+    }
+  }
+  while (i < n) {
+    const c = js[i]!
+    if (c === '/' && js[i + 1] === '/') {
+      while (i < n && js[i] !== '\n') i++
+    } else if (c === '/' && js[i + 1] === '*') {
+      const end = js.indexOf('*/', i + 2)
+      i = end < 0 ? n : end + 2
+    } else if (c === '"' || c === "'") {
+      let s = ''
+      i++
+      while (i < n && js[i] !== c) {
+        if (js[i] === '\\') {
+          s += js.slice(i, i + 2)
+          i += 2
+        } else s += js[i++]
+      }
+      i++
+      strings.add(s)
+    } else if (c === '`') {
+      i++
+      readTemplateChunk()
+    } else if (c === '{') {
+      braces++
+      i++
+    } else if (c === '}') {
+      braces--
+      i++
+      if (templateDepth.length && templateDepth[templateDepth.length - 1] === braces) {
+        templateDepth.pop()
+        readTemplateChunk()
+      }
+    } else if (/[0-9]/.test(c) || (c === '.' && /[0-9]/.test(js[i + 1] ?? ''))) {
+      const m = /^(?:0[xX][0-9a-fA-F_]+|0[bB][01_]+|0[oO][0-7_]+|(?:\d[\d_]*\.?\d*(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?))n?/.exec(js.slice(i))
+      const tok = m ? m[0] : c
+      const num = Number(tok.replace(/_/g, '').replace(/n$/, ''))
+      strings.add(Number.isNaN(num) ? tok : `#${num}`)
+      i += tok.length
+    } else if (/[A-Za-z_$]/.test(c)) {
+      const m = /^[A-Za-z_$][\w$]*/.exec(js.slice(i))!
+      names.add(m[0])
+      i += m[0].length
+    } else i++
+  }
+  return { strings, names }
+}
+
+const transpile = (code: string, loader: 'tsx' | 'ts' | 'js') =>
+  new Bun.Transpiler({ loader, target: 'browser', minifyWhitespace: false, deadCodeElimination: false, trimUnusedImports: false }).transformSync(code)
+
+/** What of `sources` is not in `published`; empty = the sources are what the published file was built from. */
+export function integrityGaps(sources: { path: string; text: string }[], published: string): string[] {
+  const pub = skeleton(transpile(published, 'js'))
+  const gaps: string[] = []
+  for (const s of sources) {
+    const loader = s.path.endsWith('.tsx') ? 'tsx' : 'ts'
+    const sk = skeleton(transpile(s.text, loader))
+    // Import specifiers are module names, which bundling replaces; they are checked as imports instead.
+    for (const im of new Bun.Transpiler({ loader }).scanImports(s.text)) sk.strings.delete(im.path)
+    for (const v of sk.strings) if (!pub.strings.has(v)) gaps.push(`${s.path}: literal ${JSON.stringify(v.startsWith('#') ? v.slice(1) : v).slice(0, 60)}`)
+    for (const v of sk.names) if (!JSX_NAMES.has(v) && !JSX_RUNTIME.test(v) && !KEYWORDS.has(v) && !pub.names.has(v)) gaps.push(`${s.path}: name \`${v}\``)
+  }
+  return gaps
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+
+/** Reads one package (real directory `dir`), checks it, and writes its sources under `outRoot`. */
+function writePackage(appRoot: string, dir: string, budget: { bytes: number }): Outcome {
+  const pj = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as Record<string, unknown>
+  const entryRel = esmEntry(pj)
+  if (!entryRel) return { ok: false, reason: 'no ESM entry (exports `import` or `module`)' }
+  const entry = join(dir, entryRel)
+  if (!existsSync(entry) || !statSync(entry).isFile()) return { ok: false, reason: `the ESM entry ${entryRel} is missing` }
+  const mapFile = mapOf(entry)
+  if (!mapFile) return { ok: false, reason: 'no source map for the ESM entry' }
+  let map: { sources?: unknown; sourcesContent?: unknown }
+  try {
+    map = JSON.parse(readFileSync(mapFile, 'utf8'))
+  } catch {
+    return { ok: false, reason: 'the source map is not JSON' }
+  }
+  const sources = Array.isArray(map.sources) ? (map.sources as unknown[]) : []
+  const contents = Array.isArray(map.sourcesContent) ? (map.sourcesContent as unknown[]) : []
+  // Each source as a path inside the package; anything outside it, or not TS/TSX, is not ours to read.
+  const files: { path: string; text: string }[] = []
+  for (const [k, s] of sources.entries()) {
+    const text = contents[k]
+    if (typeof s !== 'string' || typeof text !== 'string') continue
+    const abs = posix.normalize(posix.join(relative(dir, dirname(mapFile)).split(sep).join('/'), s))
+    if (abs.startsWith('..') || posix.isAbsolute(abs) || /^[a-z]+:/i.test(s)) return { ok: false, reason: `the source ${s} lies outside the package` }
+    if (!/\.tsx?$/.test(abs)) continue
+    files.push({ path: abs, text })
+  }
+  if (files.length === 0) return { ok: false, reason: 'the source map carries no TypeScript sources (`sourcesContent`)' }
+  const bytes = files.reduce((a, f) => a + f.text.length, 0)
+  if (bytes > LIMITS.bytesPerPackage) return { ok: false, reason: `the sources are ${bytes} bytes (limit ${LIMITS.bytesPerPackage})` }
+  if (budget.bytes + bytes > LIMITS.totalBytes) return { ok: false, reason: 'the package-source budget of this build is spent' }
+  // Imports: relative ones must be in the map (the compiler would otherwise fail on them), bare ones are followed.
+  const have = new Set(files.map((f) => f.path))
+  const bare = new Set<string>()
+  const imported = new Set<string>()
+  for (const f of files) {
+    if (/\beval\s*\(|\bnew\s+Function\b/.test(f.text)) return { ok: false, reason: `${f.path} calls eval or new Function` }
+    let imports: { path: string; kind: string }[]
+    try {
+      imports = new Bun.Transpiler({ loader: f.path.endsWith('.tsx') ? 'tsx' : 'ts' }).scanImports(f.text)
+    } catch (e) {
+      return { ok: false, reason: `${f.path} does not parse: ${String(e instanceof Error ? e.message : e).split('\n')[0]}` }
+    }
+    for (const im of imports) {
+      // The JSX transform's own runtime import (the transpiler adds it), and React itself.
+      if (NEVER(im.path)) continue
+      if (im.kind === 'dynamic-import' || im.kind === 'require-call' || im.kind === 'require-resolve') return { ok: false, reason: `${f.path} has a ${im.kind} (${im.path})` }
+      if (im.path.startsWith('./') || im.path.startsWith('../')) {
+        const base = posix.normalize(posix.join(posix.dirname(f.path), im.path))
+        const hit = [base, `${base}.tsx`, `${base}.ts`, `${base}/index.tsx`, `${base}/index.ts`].find((c) => have.has(c))
+        if (hit) imported.add(hit)
+        else return { ok: false, reason: `${f.path} imports ${im.path}, which the source map does not carry` }
+      } else if (im.path.startsWith('/') || /^[a-z]+:/i.test(im.path)) return { ok: false, reason: `${f.path} imports ${im.path}` }
+      else bare.add(im.path)
+    }
+  }
+  // The entry source: the one `package.json#source` names, else the only source no other source imports.
+  const declared = typeof pj.source === 'string' ? posix.normalize(pj.source.replace(/^\.\//, '')) : null
+  const roots = files.filter((f) => !imported.has(f.path))
+  const entrySrc = files.find((f) => f.path === declared) ?? (roots.length === 1 ? roots[0] : undefined)
+  if (!entrySrc) return { ok: false, reason: `the source map has ${files.length} sources and none is the entry (no \`source\` field, ${roots.length} unimported)` }
+  // R34.62: the published file must be what these sources were built into.
+  let gaps: string[]
+  try {
+    gaps = integrityGaps(files, readFileSync(entry, 'utf8'))
+  } catch (e) {
+    return { ok: false, reason: `the integrity check could not read the sources or ${entryRel}: ${String(e instanceof Error ? e.message : e).split('\n')[0]}` }
+  }
+  if (gaps.length > 0) return { ok: false, reason: `the sources do not match the published ${entryRel} (${gaps.length} differences, first: ${gaps[0]})` }
+  // Keyed on where the package sits relative to the app (stable across machines), not its absolute path.
+  // Review F1 (security): no package-controlled text in the path. The directory is named by a hash of where the package
+  // sits relative to the app (stable across machines), and every target must resolve inside the directory this build
+  // owns before anything is created; a `name`/`version` of `../..` cannot move a write.
+  const hash = createHash('sha256').update(relative(appRoot, dir).split(sep).join('/')).digest('hex').slice(0, 16)
+  const outRel = posix.join(PKG_SRC_DIR, `p-${hash}`)
+  const own = resolve(appRoot, PKG_SRC_DIR) + sep
+  const targets = files.map((f) => ({ f, target: resolve(appRoot, outRel, f.path) }))
+  const escaped = targets.find((t) => !t.target.startsWith(own))
+  if (escaped) return { ok: false, reason: `the source ${escaped.f.path} would be written outside ${PKG_SRC_DIR}` }
+  for (const { f, target } of targets) {
+    mkdirSync(dirname(target), { recursive: true })
+    // The directories just made are this build's: a real path elsewhere means a link was planted in between.
+    if (!`${realpathSync(dirname(target))}${sep}`.startsWith(realpathSync(resolve(appRoot, PKG_SRC_DIR)) + sep))
+      return { ok: false, reason: `the source ${f.path} would be written outside ${PKG_SRC_DIR}` }
+    writeFileSync(target, f.text)
+  }
+  budget.bytes += bytes
+  return { ok: true, dir: outRel, entry: posix.join(outRel, entrySrc.path), imports: [...bare].sort() }
+}
+
+/**
+ * Writes the sources of every package `specs` reaches from the app (and of every package those sources import),
+ * and returns the resolution map for the compiler. The directory is rebuilt from nothing on every call.
+ */
+export function preparePackageSources(appRoot: string, specs: Iterable<string>): PackageSources {
+  const root = realpathSync(appRoot)
+  // BEFORE anything is removed (Mellow N1, F163): neither `.brust` nor `.brust/pkg-src` may be a link out of the app, or
+  // the recursive remove below would delete whatever the link points at.
+  for (const p of [dirname(PKG_SRC_DIR), PKG_SRC_DIR].map((d) => join(root, d))) {
+    if (!lstatSyncOrNull(p)) continue
+    let real = '' // a dangling link resolves to nothing: refused as well
+    try {
+      real = realpathSync(p)
+    } catch {}
+    if (!`${real}${sep}`.startsWith(root + sep)) throw new BuildError('package-source', `${relative(root, p)} resolves outside the app root (a link?); remove it and build again`)
+  }
+  rmSync(join(root, PKG_SRC_DIR), { recursive: true, force: true })
+  mkdirSync(join(root, PKG_SRC_DIR), { recursive: true })
+  if (!realpathSync(join(root, PKG_SRC_DIR)).startsWith(root + sep)) throw new BuildError('package-source', `${PKG_SRC_DIR} resolves outside the app root (a link?); remove it and build again`)
+  const out: PackageSources = { scopes: {}, refused: {}, dirs: {} }
+  writtenDirs.clear()
+  const byDir = new Map<string, Outcome>()
+  const budget = { bytes: 0 }
+  // (scope, the real directory bare imports resolve from, specifier)
+  const queue: [string, string, string][] = [...new Set(specs)].sort().map((s) => ['', root, s])
+  const seen = new Set<string>()
+  while (queue.length > 0) {
+    const [scope, from, spec] = queue.shift()!
+    const key = `${scope}\0${spec}`
+    if (seen.has(key) || NEVER(spec)) continue
+    seen.add(key)
+    const refuse = (reason: string) => {
+      ;(out.refused[scope] ??= {})[spec] = reason
+    }
+    const [name, sub] = splitSpecifier(spec)
+    if (sub) {
+      refuse('a package subpath import is not followed')
+      continue
+    }
+    const dir = findPackage(name, from)
+    if (!dir) {
+      refuse('not installed')
+      continue
+    }
+    let o = byDir.get(dir)
+    if (!o) {
+      try {
+        o = byDir.size >= LIMITS.packages ? { ok: false, reason: `more than ${LIMITS.packages} packages` } : writePackage(root, dir, budget)
+      } catch (e) {
+        // An unreadable package.json or map is a refusal: a package never fails the build here.
+        o = { ok: false, reason: `unreadable: ${String(e instanceof Error ? e.message : e).split('\n')[0]}` }
+      }
+      byDir.set(dir, o)
+      // A refusal is reported where it matters: the compiler names it on the island it leaves (`external-component`).
+      if (o.ok) {
+        out.dirs[o.dir] = dir
+        writtenDirs.set(join(root, o.dir), dir)
+        for (const im of o.imports) queue.push([o.dir, dir, im])
+      }
+    }
+    if (o.ok) (out.scopes[scope] ??= {})[spec] = o.entry
+    else refuse(o.reason)
+  }
+  mkdirSync(join(root, PKG_SRC_DIR), { recursive: true })
+  writeFileSync(join(root, PKG_SRC_DIR, 'index.json'), `${JSON.stringify(out, null, 2)}\n`)
+  return out
+}

package/src/build/scan.ts

@@ -1,15 +1,19 @@
-// 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'
+import { installServerOnlyRuntime } from './server-only'
 
-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
+  installServerOnlyRuntime() // `server-only` resolves to an empty module: a loader may import server-only code
   try {
     mod = await import(entryFile)
   } catch (e) {
@@ -21,22 +25,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/server-only.ts

@@ -0,0 +1,39 @@
+// 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' }))
+    },
+  })
+}

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