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

package/src/dev/tui.ts

@@ -0,0 +1,144 @@
+// The inline terminal UI of `brust dev` (R13.5). NEVER the alternate screen: request log lines scroll
+// normally, and a status block of at most 6 lines is redrawn at the bottom (cursor-up + clear, wrapped
+// lines counted, resize aware). Not a TTY, `CI` or `NO_COLOR` -> plain line logs, no redraw, no raw mode.
+
+export type DevState = 'building' | 'ready' | 'error'
+
+export interface TuiStatus {
+  state: DevState
+  url: string
+  gen: number
+  buildMs?: number
+  /** The last page request (route + status) until L14's per-page trace lands. */
+  last?: { method: string; path: string; status: number; /** Components of the last page by tier (from its trace + `dev.json`). */ tiers?: { static: number; native: number; react: number } }
+  warnings: string[]
+  /** One line shown under the state while `error` (the first line of the diagnostic). */
+  error?: string
+}
+
+export interface TuiOut {
+  write(s: string): unknown
+  columns?: number
+  isTTY?: boolean
+}
+
+const STATE_DOT: Record<DevState, string> = { building: '◌', ready: '●', error: '✖' }
+const STATE_COLOR: Record<DevState, string> = { building: '33', ready: '32', error: '31' }
+export const HOTKEYS = '[r]eload  [o]pen  [w]arnings  [c]lear  [q]uit'
+export const MAX_STATUS_LINES = 6
+
+/** Visible length (ANSI escapes do not count). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escapes
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]/g
+export const visibleLen = (s: string): number => [...s.replace(ANSI, '')].length
+
+/** `s` cut to `width` visible columns, with a trailing `…` when it was cut (escapes are not split: input is plain here). */
+function fit(s: string, width: number): string {
+  const cs = [...s]
+  return cs.length <= width ? s : `${cs.slice(0, Math.max(0, width - 1)).join('')}…`
+}
+
+/** The status block, plain text (colour is added by the caller), every line at most `width` columns. */
+export function renderStatus(s: TuiStatus, width: number): string[] {
+  const w = Math.max(20, width - 1)
+  const head = `${STATE_DOT[s.state]} ${s.state}  ${s.url}  gen ${s.gen}${s.buildMs !== undefined ? ` · built in ${s.buildMs}ms` : ''}`
+  const lines = [head]
+  if (s.state === 'error' && s.error) lines.push(`  error: ${s.error}`)
+  else if (s.last) lines.push(`  last: ${s.last.method} ${s.last.path} → ${s.last.status}${s.last.tiers ? `  ·  ${s.last.tiers.static} static ${s.last.tiers.native} native ${s.last.tiers.react} react` : ''}`)
+  else lines.push('  last: (no request yet)')
+  if (s.warnings.length > 0) lines.push(`  warnings: ${s.warnings.length} — ${s.warnings[0]}`)
+  lines.push(`  ${HOTKEYS}`)
+  return lines.slice(0, MAX_STATUS_LINES).map((l) => fit(l, w))
+}
+
+/** Rows `lines` occupy on a terminal `width` columns wide (a line wider than the terminal wraps). */
+export function rowsFor(lines: string[], width: number): number {
+  const w = Math.max(1, width)
+  return lines.reduce((n, l) => n + Math.max(1, Math.ceil(visibleLen(l) / w)), 0)
+}
+
+/** Colour is on for a TTY unless NO_COLOR; the redraw is on only for an interactive TTY outside CI. */
+export function tuiMode(out: TuiOut, env: Record<string, string | undefined>): { interactive: boolean; color: boolean } {
+  const tty = out.isTTY === true
+  const interactive = tty && !env.CI && !env.NO_COLOR
+  return { interactive, color: interactive }
+}
+
+export class Tui {
+  private status: TuiStatus | null = null
+  private drawn: string[] = []
+  private closed = false
+  private lastPlain = ''
+
+  constructor(
+    private readonly out: TuiOut,
+    private readonly interactive: boolean,
+    private readonly color = interactive,
+  ) {}
+
+  private width(): number {
+    return this.out.columns && this.out.columns > 0 ? this.out.columns : 80
+  }
+
+  private paint(l: string, i: number): string {
+    if (!this.color || !this.status) return l
+    if (i === 0) return `\x1b[${STATE_COLOR[this.status.state]}m${l}\x1b[0m`
+    return `\x1b[2m${l}\x1b[0m`
+  }
+
+  private erase(): string {
+    if (this.drawn.length === 0) return ''
+    const rows = rowsFor(this.drawn, this.width())
+    this.drawn = []
+    return `\r\x1b[${rows}A\x1b[J`
+  }
+
+  private draw(): string {
+    if (!this.status) return ''
+    const lines = renderStatus(this.status, this.width())
+    this.drawn = lines
+    return `${lines.map((l, i) => this.paint(l, i)).join('\n')}\n`
+  }
+
+  /** One scrolling log line (a request, a warning, a message). */
+  log(raw: string): void {
+    if (this.closed) return
+    // Colour only where colour is on: a child's ANSI-coloured tracing line is plain text in plain mode.
+    const line = this.color ? raw : raw.replace(ANSI, '')
+    if (!this.interactive) {
+      this.out.write(`${line}\n`)
+      return
+    }
+    this.out.write(`${this.erase()}${line}\n${this.draw()}`)
+  }
+
+  /** Replace the status block. Plain mode prints a line only when the state line changes. */
+  setStatus(s: TuiStatus): void {
+    if (this.closed) return
+    this.status = s
+    if (!this.interactive) {
+      const l = `[brust] ${s.state} ${s.url} gen ${s.gen}${s.buildMs !== undefined ? ` (${s.buildMs}ms)` : ''}${s.error ? ` — ${s.error}` : ''}`
+      if (l !== this.lastPlain) this.out.write(`${l}\n`)
+      this.lastPlain = l
+      return
+    }
+    this.out.write(`${this.erase()}${this.draw()}`)
+  }
+
+  /** Redraw after a terminal resize (the rows the old block took are recounted at the new width). */
+  resize(): void {
+    if (this.interactive && !this.closed) this.out.write(`${this.erase()}${this.draw()}`)
+  }
+
+  /** The `c` hotkey: clear the screen and redraw the block. */
+  clear(): void {
+    if (!this.interactive) return
+    this.drawn = []
+    this.out.write(`\x1b[2J\x1b[H${this.draw()}`)
+  }
+
+  /** Leave the final block on screen and stop drawing. */
+  close(): void {
+    this.closed = true
+  }
+}

package/src/dev/watch.ts

@@ -0,0 +1,130 @@
+// The shared watch/build loop of `brust dev` (bun and cloudflare targets): debounced file events,
+// ONE run at a time, and every change that arrives while a run is in flight is kept for the next
+// run (post-mortem 8f29c26: an edit during a rebuild was dropped). `run` receives the app-relative
+// paths that changed since the previous run started.
+import { type FSWatcher, readdirSync, statSync, watch } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+
+export interface WatchLoop {
+  /** Queue a run as if `rel` changed (the `r` hotkey, tests). */
+  trigger(rel?: string): void
+  /** Stop watching and drop queued changes; an in-flight run is left to finish. */
+  close(): void
+  /** Resolves when no run is in flight and nothing is queued. */
+  idle(): Promise<void>
+}
+
+/** F273: a source root holding more files than this gets a warning (a root that broad slows every rebuild check). */
+export const ROOT_FILE_WARN = 5_000
+
+/** Files under `dir` (skipping dependency/VCS dirs), counting stops once past `limit`. */
+export function countFiles(dir: string, limit: number): number {
+  let n = 0
+  const walk = (d: string): void => {
+    let ents: import('node:fs').Dirent[]
+    try {
+      ents = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of ents) {
+      if (n > limit) return
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(join(d, e.name))
+      } else n++
+    }
+  }
+  walk(dir)
+  return n
+}
+
+/** Warning lines for source roots broader than `ROOT_FILE_WARN` files; `roots` are absolute. */
+export function broadRootWarnings(roots: string[], appRoot: string, limit = ROOT_FILE_WARN): string[] {
+  return roots.flatMap((r) => (countFiles(r, limit) > limit ? [`[brust] warning: source root ${relative(appRoot, r) || r} holds more than ${limit} files; watching it slows every change check. Point source_roots at a narrower directory`] : []))
+}
+
+export function watchLoop(o: { root: string; /** F273: `[build] source_roots`, absolute: watched too; their changes are reported app-relative (`../shared/x.ts`). */ extraRoots?: string[]; ignored: (rel: string) => boolean; debounceMs: number; run: (changed: Set<string>) => Promise<void> }): WatchLoop {
+  let pending = new Set<string>()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running = false
+  let closed = false
+  let idleWaiters: (() => void)[] = []
+  const pump = async () => {
+    if (running) return // the running loop picks `pending` up when it finishes
+    running = true
+    try {
+      while (pending.size > 0 && !closed) {
+        const batch = pending
+        pending = new Set()
+        try {
+          await o.run(batch)
+        } catch (e) {
+          console.error(`[brust] dev run failed: ${(e as Error).stack ?? String(e)}`)
+        }
+      }
+    } finally {
+      running = false
+      if (pending.size === 0) for (const w of idleWaiters.splice(0)) w()
+    }
+  }
+  const queue = (rel: string) => {
+    if (closed) return
+    pending.add(rel)
+    clearTimeout(timer)
+    timer = setTimeout(() => void pump(), o.debounceMs)
+  }
+  const onEvent = (base: string) => (_ev: string, name: string | null) => {
+    if (!name) return
+    const abs = join(base, String(name))
+    const rel = (base === o.root ? String(name) : relative(o.root, abs)).split(sep).join('/')
+    if (o.ignored(rel)) return
+    // A directory's own event is metadata noise (reading a dir bumps its atime, which FSEvents reports): a real
+    // change inside it reports the file itself. A path that no longer exists is a delete, which counts.
+    try {
+      if (statSync(abs).isDirectory()) return
+    } catch {}
+    queue(rel)
+  }
+  const watchers: FSWatcher[] = [watch(o.root, { recursive: true }, onEvent(o.root))]
+  for (const r of o.extraRoots ?? []) {
+    const abs = resolve(r)
+    // a root inside the app is already watched; one that cannot be watched must not stop the session
+    if (abs === o.root || abs.startsWith(o.root + sep)) continue
+    try {
+      watchers.push(watch(abs, { recursive: true }, onEvent(abs)))
+    } catch (e) {
+      console.error(`[brust] cannot watch source root ${abs}: ${(e as Error).message}`)
+    }
+  }
+  return {
+    trigger: (rel = '.') => queue(rel),
+    close() {
+      closed = true
+      clearTimeout(timer)
+      pending.clear()
+      for (const w of watchers) w.close()
+      for (const w of idleWaiters.splice(0)) w()
+    },
+    idle: () => (!running && pending.size === 0 ? Promise.resolve() : new Promise<void>((r) => idleWaiters.push(r))),
+  }
+}
+
+/** F133: the line `brust dev` logs for a batch of changed paths, or null when the batch is only the boot trigger (`.`,
+ * the app root itself: the first build goes through the loop, and a watcher can report the root too). */
+export function changeLine(changed: Iterable<string>): string | null {
+  const paths = [...changed].filter((r) => r !== '.')
+  if (paths.length === 0) return null
+  return `[brust] change detected: ${paths.slice(0, 3).join(', ')}${paths.length > 3 ? ` +${paths.length - 3}` : ''}`
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.wrangler', '.brust'])
+const SKIP_FILE = /(^|\/)(\.DS_Store|4913)$|~$|\.(swp|swx|tmp|log)$|\.(sqlite|db)(-wal|-shm|-journal)?$/
+
+/** Paths a dev session never rebuilds for: dependency/VCS dirs, brust's own output, editor temp files, databases. */
+export function defaultIgnored(rel: string, outDirRel: string): boolean {
+  const segs = rel.split('/')
+  if (segs.some((s) => SKIP_DIRS.has(s))) return true
+  const out = outDirRel.replace(/\/+$/, '')
+  if (rel === out || rel.startsWith(`${out}/`) || rel.startsWith(`${out}.`) || rel.startsWith(`.${out}.brust-`)) return true
+  return SKIP_FILE.test(rel)
+}

package/src/dev.ts

@@ -1,9 +1,10 @@
 // `brust dev [entry] --target cloudflare [-- <wrangler args>]` (M4-CF R10): build, run `wrangler dev` on the
 // generated project, rebuild + restart wrangler on a source change. No HMR. Each build runs in a child
 // process: a failed build keeps the old wrangler, and module caches never leak between builds.
-import { type FSWatcher, watch } from 'node:fs'
-import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import { BuildError } from './build/errors'
+import { loadBuildConfig } from './build/config'
+import { broadRootWarnings, defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
 
 export interface DevOptions {
   appRoot: string
@@ -15,7 +16,6 @@ export interface DevOptions {
   log: (s: string) => void
 }
 
-const IGNORED = new Set(['node_modules', '.wrangler', '.git'])
 const DEBOUNCE_MS = 300
 
 function wranglerBin(appRoot: string): string {
@@ -54,7 +54,7 @@ export async function runDev(o: DevOptions): Promise<number> {
     child = c
     c.exited.then((code) => {
       if (child !== c || stopping || restarting) return
-      watcher?.close()
+      loop.close()
       exitCode(code)
     })
   }
@@ -65,17 +65,15 @@ export async function runDev(o: DevOptions): Promise<number> {
     await c.exited
   }
 
-  let timer: ReturnType<typeof setTimeout> | undefined
-  let building = false
-  let again = false
-  const rebuild = async () => {
-    if (building) {
-      again = true
-      return
-    }
-    building = true
-    do {
-      again = false
+  // The shared watch/build loop (dev/watch.ts): one rebuild at a time, edits during a rebuild are kept for the next.
+  const extraRoots = await loadBuildConfig(appRoot).then((c) => c.sourceRoots.map((r) => resolve(appRoot, r)), () => [] as string[])
+  for (const w of broadRootWarnings(extraRoots, appRoot)) o.log(w)
+  const loop: WatchLoop = watchLoop({
+    root: appRoot,
+    extraRoots,
+    ignored: (rel) => defaultIgnored(rel, relative(appRoot, dist)),
+    debounceMs: DEBOUNCE_MS,
+    async run() {
       o.log('[brust] change detected; rebuilding')
       if ((await build()) === 0) {
         restarting = true
@@ -83,25 +81,14 @@ export async function runDev(o: DevOptions): Promise<number> {
         restarting = false
         if (!stopping) spawn()
       } else o.log('[brust] rebuild failed; keeping the running wrangler')
-    } while (again && !stopping)
-    building = false
-  }
-  const ignored = (rel: string) => {
-    const abs = resolve(appRoot, rel)
-    return rel.split(sep).some((s) => IGNORED.has(s)) || abs === dist || abs.startsWith(dist + sep) || abs.startsWith(`${dist}.`) || abs.startsWith(join(dirname(dist), `.${basename(dist)}.brust-`)) || relative(dist, abs) === ''
-  }
-  let watcher: FSWatcher | null = watch(appRoot, { recursive: true }, (_ev, name) => {
-    if (!name || ignored(String(name))) return
-    clearTimeout(timer)
-    timer = setTimeout(() => void rebuild(), DEBOUNCE_MS)
+    },
   })
 
   spawn()
   const stop = () => {
     if (stopping) return
     stopping = true
-    clearTimeout(timer)
-    watcher?.close()
+    loop.close()
     void stopChild().then(() => exitCode(0))
   }
   process.on('SIGINT', stop)

package/src/handlers.ts

@@ -3,6 +3,7 @@
 // `worker.ts` re-exports everything here, so existing importers are unchanged.
 import { installServerResolver, type StoreSnapshot } from './store/core-adapter'
 import { collectSnapshot, getServerInstance, runInStoreContext, touchStores } from './store/server-context'
+import { NAVIGATION_MODULE } from './store/builtin'
 import { type FlatRoute, isHttpErrorTrigger, isVerdict, type LoaderReq, type Route, type Verdict } from './routes'
 
 installServerResolver(getServerInstance)
@@ -19,11 +20,14 @@ export interface LoaderRequest {
   plan?: boolean
 }
 
+/** Response headers as `[name, value]` pairs: a repeated name (`set-cookie`) stays repeated. */
+export type HeaderPairs = [string, string][]
+
 export type LoaderResponse =
-  | { ok: true; data: Record<string, unknown>; headers?: Record<string, string>; store?: StoreSnapshot | null }
-  | { verdict: 'notFound'; data: unknown; store?: StoreSnapshot | null }
-  | { verdict: 'redirect'; location: string; status: number }
-  | { verdict: 'httpError'; status: number; body: string }
+  | { ok: true; data: Record<string, unknown>; headers?: HeaderPairs; store?: StoreSnapshot | null }
+  | { verdict: 'notFound'; data: unknown; headers?: HeaderPairs; store?: StoreSnapshot | null }
+  | { verdict: 'redirect'; location: string; status: number; headers?: HeaderPairs }
+  | { verdict: 'httpError'; status: number; body: string; contentType: string; headers?: HeaderPairs }
   | { error: string }
 
 export type JobKind = 'precompute' | 'ssr'
@@ -68,7 +72,7 @@ export interface ManifestLike {
   >
   jobs_module?: string
   /** `brust build` (M3-F A3): the actions entry, relative to dist. Absent/null = no actions. */
-  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number } | null
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; stream?: string[] } | null
 }
 
 export function toJson(out: unknown): string {
@@ -131,6 +135,50 @@ function withStore<T extends LoaderResponse>(r: T): T {
 
 // ---- handlers ----
 
+// ---- response headers (F464) ----
+
+/** Names the server owns: the framing, the page's type, and a redirect's target (`redirect()`). */
+const REFUSED_HEADERS = new Set(['content-type', 'content-length', 'transfer-encoding', 'connection', 'location'])
+
+const refusedMessage = (name: string) =>
+  `a loader cannot set "${name}" (the server sets it${name.trim().toLowerCase() === 'location' ? '; use redirect()' : ''})`
+
+/** `res.headers`: a `Headers` that refuses the server's names, by a throw in dev (the loader fails with a 500 that
+ * names it) and by a warning in production (the call does nothing). */
+class LoaderHeaders extends Headers {
+  constructor(private readonly dev: boolean) {
+    super()
+  }
+  private allowed(name: string): boolean {
+    if (!REFUSED_HEADERS.has(name.trim().toLowerCase())) return true
+    const msg = `res.headers: ${refusedMessage(name)}`
+    if (this.dev) throw new Error(msg)
+    console.warn(`[brust] warning ${msg}; dropped`)
+    return false
+  }
+  override set(name: string, value: string): void {
+    if (this.allowed(name)) super.set(name, value)
+  }
+  override append(name: string, value: string): void {
+    if (this.allowed(name)) super.append(name, value)
+  }
+}
+
+/** The wire pairs, absent when empty. `Set-Cookie` one pair per cookie (iteration would join them). */
+function headerPairs(h: Headers): HeaderPairs | undefined {
+  const out: HeaderPairs = []
+  for (const [k, v] of h) if (k !== 'set-cookie') out.push([k, v])
+  for (const c of h.getSetCookie()) out.push(['set-cookie', c])
+  return out.length > 0 ? out : undefined
+}
+
+/** `r` with `headers` set when there are any. */
+function withHeaders<T extends LoaderResponse>(r: T, h: Headers): T {
+  const pairs = headerPairs(h)
+  if (pairs) (r as { headers?: HeaderPairs }).headers = pairs
+  return r
+}
+
 /** `parent`: the data the chain merged before the verdict. A notFound renders the route's
  * template (layouts included), so the layouts' data stays under the verdict's own keys. */
 function verdictJson(v: Verdict, parent: Record<string, unknown>): LoaderResponse {
@@ -141,6 +189,39 @@ function verdictJson(v: Verdict, parent: Record<string, unknown>): LoaderRespons
   return { verdict: 'redirect', location: v.headers?.Location ?? '/', status: v.status }
 }
 
+/** What a loader did during a static render (gaps round R9.5) that a static file cannot honour. */
+export type SsgRecord =
+  | { kind: 'read'; routeId: string; path: string; field: 'headers' | 'cookies' | 'search'; key: string }
+  | { kind: 'headers'; routeId: string; path: string; names: string[] }
+
+/** R9.5: the request a loader sees while rendering static output: a visitor with no headers, cookies
+ * or query. Every read of `headers` / `cookies` / `search` (a key, `in`, or a listing: key `*`) is
+ * recorded, so the build can warn that the page written ignores it. */
+export function ssgRequest(req: LoaderReq, routeId: string, path: string, record: (r: SsgRecord) => void): LoaderReq {
+  const watched = (field: 'headers' | 'cookies' | 'search') => {
+    const read = (key: string) => record({ kind: 'read', routeId, path, field, key })
+    return new Proxy(Object.create(null) as Record<string, string>, {
+      get: (t, k) => {
+        if (typeof k === 'string') read(k)
+        return Reflect.get(t, k)
+      },
+      has: (t, k) => {
+        if (typeof k === 'string') read(k)
+        return Reflect.has(t, k)
+      },
+      ownKeys: (t) => {
+        read('*')
+        return Reflect.ownKeys(t)
+      },
+      getOwnPropertyDescriptor: (t, k) => {
+        if (typeof k === 'string') read(k)
+        return Reflect.getOwnPropertyDescriptor(t, k)
+      },
+    })
+  }
+  return { method: 'GET', url: req.url, headers: watched('headers'), cookies: watched('cookies'), search: watched('search') }
+}
+
 export interface Handlers {
   loader(req: LoaderRequest): Promise<LoaderResponse>
   jobs(req: JobsRequest): Promise<JobsResponse>
@@ -154,6 +235,10 @@ export function makeHandlers(opts: {
   manifest?: ManifestLike
   /** `jobs.js` `stores` table (R2): C3 path -> module namespace. */
   stores?: Record<string, object>
+  /** Static output (R9.5): loaders see `ssgRequest`, and what a static file drops is recorded. */
+  ssg?: (r: SsgRecord) => void
+  /** `brust dev`: a refused `res.headers` name throws instead of being dropped with a warning (F464). */
+  dev?: boolean
 }): Handlers {
   const byId = new Map(opts.leaves.map((l) => [l.id, l]))
   const literals = literalsIndex(opts.manifest)
@@ -199,25 +284,46 @@ export function makeHandlers(opts: {
       // loader's data is assigned as data, as the spread copied it.
       return runInStoreContext(async () => {
         const merged: Record<string, unknown> = Object.create(null)
+        const res = { headers: new LoaderHeaders(opts.dev === true) }
+        // R9.5: a static file carries no headers; the build warns, naming them.
+        const out = <T extends LoaderResponse>(r: T): T => {
+          withHeaders(r, res.headers)
+          const names = (r as { headers?: HeaderPairs }).headers?.map(([n]) => n)
+          if (opts.ssg && names) opts.ssg({ kind: 'headers', routeId: req.routeId, path: req.path, names: [...new Set(names)] })
+          return r
+        }
         try {
           const touch = storeIdx.get(req.routeId)
-          if (touch) touchStores(touch, storeTable)
+          if (touch) {
+            touchStores(touch, storeTable)
+            // The built-in `navigation` store (design §11) paints the request's path + search on first paint.
+            if (touch.includes(NAVIGATION_MODULE)) (storeTable[NAVIGATION_MODULE] as { navigation?: { hydrate(s: object): void } } | undefined)?.navigation?.hydrate({ url: req.req.url })
+          }
           for (const node of leaf.chain) {
             if (!node.loader) continue
             let r: unknown
             try {
-              r = await node.loader({ params: req.params, path: req.path, req: req.req })
+              const lreq = opts.ssg ? ssgRequest(req.req, req.routeId, req.path, opts.ssg) : req.req
+              r = await node.loader({ params: req.params, path: req.path, req: lreq, res })
             } catch (e) {
-              if (isHttpErrorTrigger(e)) return { verdict: 'httpError', status: e.status, body: e.body } as LoaderResponse
+              if (isHttpErrorTrigger(e)) {
+                // httpError's own `headers` option adds to what the chain set. A refused name is dropped with a warning
+                // in dev too: a throw here would hide the error the loader meant to send (F466).
+                for (const [k, v] of Object.entries(e.headers ?? {})) {
+                  if (REFUSED_HEADERS.has(k.trim().toLowerCase())) console.warn(`[brust] warning httpError headers: ${refusedMessage(k)}; dropped`)
+                  else res.headers.append(k, v)
+                }
+                return out({ verdict: 'httpError', status: e.status, body: e.body, contentType: e.contentType } as LoaderResponse)
+              }
               throw e
             }
             if (isVerdict(r)) {
-              const v = verdictJson(r, merged)
+              const v = out(verdictJson(r, merged))
               return 'verdict' in v && v.verdict === 'notFound' ? withStore(v) : v
             }
             if (r && typeof r === 'object') Object.assign(merged, r)
           }
-          return withStore({ ok: true, data: merged } as LoaderResponse)
+          return out(withStore({ ok: true, data: merged } as LoaderResponse))
         } catch (e) {
           return { error: String(e) } as LoaderResponse
         }

package/src/index.ts

@@ -1,4 +1,9 @@
+/// <reference path="./css-modules.d.ts" />
+/// <reference path="./assets.d.ts" />
 // `@brust/core`: the app-facing API.
+export { buildTime } from './build-time'
+export { clearNavigationCache, navigate } from './navigate'
+export type { NavErrorDetail, NavLoadDetail, NavigateOptions, NavSuccessDetail, NavTrigger } from './navigate'
 export { cache } from './cache'
 export { type BrustConfig, BrustConfigError, loadConfig } from './config'
 export { type RunOptions, run } from './run'
@@ -15,4 +20,4 @@ export {
   Outlet,
   redirect,
 } from './routes'
-export type { ComponentType, FlatRoute, HttpErrorOpts, HttpErrorTrigger, LoaderCtx, LoaderReq, Route, RouteCacheConfig, Verdict } from './routes'
+export type { ComponentType, FlatRoute, HttpErrorOpts, HttpErrorTrigger, LoaderCtx, LoaderReq, Route, RouteCacheConfig, RouteSsgConfig, Verdict } from './routes'

package/src/native.ts

@@ -22,6 +22,8 @@ export interface StartOptions {
   workers: number
   claimTimeoutMs?: number
   callTimeoutMs?: number
+  /** L10: the biggest loader/jobs reply that may cross the heap when it does not fit the slot; absent = 8388608. */
+  maxLoaderResponseBytes?: number
   /** tokio I/O threads; absent = one per core. */
   workerThreads?: number
   l1Capacity?: number
@@ -31,8 +33,12 @@ export interface StartOptions {
   cors?: CorsOptions
   /** The actions subtree (M3-F A3); absent = no actions. Boot error `actions: …` when invalid. */
   actions?: ActionsOptions
+  /** L16: what the page tells the browser `client()` (base URL, credentials, a non-default prefix); absent = from `actions` alone. */
+  actionsClient?: ActionsClientOptions
   /** The cache adapter (`manifest.cache`); absent = none (byte-identical server). */
   l2?: L2Options
+  /** `brust dev` only (L14): a request carrying this token (`x-brust-dev-token`) is traced; absent in production. */
+  devToken?: string
 }
 /** napi `NapiL2Options`; defaults 50 ms, 1048576 bytes. */
 export interface L2Options {
@@ -51,8 +57,14 @@ export interface CorsOptions {
   credentials?: boolean
   maxAgeSeconds?: number
 }
+/** napi `NapiActionsClient`. */
+export interface ActionsClientOptions {
+  prefix?: string
+  baseUrl?: string
+  credentials?: 'same-origin' | 'include' | 'omit'
+}
 /** napi `NapiActionsOptions`; defaults `/_brust/action`, 1048576, 8388608. */
-export interface ActionsOptions {
+export interface ActionsOptions extends StreamOptions {
   prefix?: string
   maxBodyBytes?: number
   /** F82: response body cap (bytes). Default 8388608. */
@@ -60,6 +72,15 @@ export interface ActionsOptions {
   /** F87: cross-site mutating requests. Default `reject`. */
   crossSite?: 'reject' | 'allow'
 }
+/** F475: the streamed action bodies (napi `NapiActionsOptions`): `["POST /upload"]` relative to the prefix, and the bounds
+ * (defaults 268435456 bytes, 30000 ms idle, 900000 ms in all, a quarter of the worker slots at once). */
+export interface StreamOptions {
+  stream?: string[]
+  maxStreamBytes?: number
+  streamIdleMs?: number
+  streamTotalMs?: number
+  maxStreams?: number
+}
 export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch' | 'cache', requestJson: string, slot: number) => Promise<number>
 export interface NativeBinding {
   startServer(opts: StartOptions): void
@@ -71,16 +92,23 @@ export interface NativeBinding {
   localAddr(): string
   /** M3-P P6 — see crates/brust-napi/src/server.rs `plan_jobs`. Never throws. */
   planJobs(slot: number, len: number): string
+  /** L10 — `planJobs` for a loader response too large for the slot: the bytes are handed over directly. Never throws. */
+  planJobsBuf(slot: number, buf: Uint8Array): string
   /** F82 — the heap request body of the in-flight `fetch` call, once; null if none. Never throws. */
   takeFetchBody(slot: number): Uint8Array | null
   /** F82 — hand Rust a response body too large for the slot; false = declined. Never throws. */
   putFetchReply(slot: number, body: Uint8Array): boolean
+  /** F475 — the next chunk of the in-flight `fetch` call's streamed body (A1 `{stream: {token}}`): bytes, `null` at the end,
+   * or why it failed (`max_stream_bytes` | `idle` | `io`). Never rejects. */
+  pullFetchBody(slot: number, token: number): Promise<Uint8Array | string | null>
   /** cache adapter R10 — a foreign broadcast event: tier 1 + the floor at `seq`; never re-published. */
   cacheReplay(args: InvalidateArgs, seq: number | null): InvalidateResult
   /** cache adapter R9 — bump `stats.l2[name]`; false = unknown name / no adapter / no server. Never throws. */
   cacheL2Count(name: string): boolean
   /** cache adapter R10 — drop both tier-1 caches (a broadcast gap); the L1 entries removed. */
   cacheClear(): number
+  /** Static output (gaps round R9.4): the request reads of a cache key expression; throws when it does not parse. */
+  cacheExprReads(src: string): string[]
 }
 
 let binding: NativeBinding | null = null
@@ -107,8 +135,11 @@ export const cacheInvalidate = (args: InvalidateArgs): InvalidateResult => nativ
 export const cacheStats = (): string => native().cacheStats()
 export const localAddr = (): string => native().localAddr()
 export const planJobs = (slot: number, len: number): string => native().planJobs(slot, len)
+export const planJobsBuf = (slot: number, buf: Uint8Array): string => native().planJobsBuf(slot, buf)
 export const takeFetchBody = (slot: number): Uint8Array | null => native().takeFetchBody(slot)
 export const putFetchReply = (slot: number, body: Uint8Array): boolean => native().putFetchReply(slot, body)
+export const pullFetchBody = (slot: number, token: number): Promise<Uint8Array | string | null> => native().pullFetchBody(slot, token)
 export const cacheReplay = (args: InvalidateArgs, seq: number | null): InvalidateResult => native().cacheReplay(args, seq)
 export const cacheL2Count = (name: string): boolean => native().cacheL2Count(name)
 export const cacheClear = (): number => native().cacheClear()
+export const cacheExprReads = (src: string): string[] => native().cacheExprReads(src)

package/src/navigate-browser.ts

@@ -0,0 +1,19 @@
+// `navigate()` in the browser: runs the SPA flow through the `nav` module (`Symbol.for('brust.nav')`, the same
+// cross-chunk pattern as `brust.stores`) and resolves after `success` or `error`. Without `nav` it is a full load.
+import type { NavigateOptions } from './navigate'
+
+type Bridge = { navigate(url: string, opts?: NavigateOptions): Promise<void>; clearCache(): void }
+const bridge = () => (globalThis as { [k: symbol]: Bridge | undefined })[Symbol.for('brust.nav')]
+
+export function navigate(url: string, opts?: NavigateOptions): Promise<void> {
+  const b = bridge()
+  if (b) return b.navigate(url, opts)
+  if (opts?.replace) location.replace(url)
+  else location.assign(url)
+  return Promise.resolve()
+}
+
+/** Drop every page the SPA navigation cache holds (design §10.1), e.g. after a mutation made outside `client()`. */
+export function clearNavigationCache(): void {
+  bridge()?.clearCache()
+}