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

package/src/dev/proxy.ts

@@ -0,0 +1,236 @@
+// The long-lived parent of `brust dev` for the Bun target (R13.1, R13.2): owns the user's port with
+// `Bun.serve`, proxies to the active child (`brust start` on a loopback port), injects the dev client
+// into every HTML response and serves the WebSocket the client listens on.
+import { join } from 'node:path'
+import type { Server, ServerWebSocket } from 'bun'
+import { DEV_CLIENT_JS } from './client'
+import type { Diag } from './diag'
+import type { DevState } from './tui'
+
+export interface DevView {
+  gen(): number
+  state(): DevState
+  diag(): Diag | null
+  /** The active child's loopback port; null before the first successful boot. */
+  upstream(): number | null
+  onRequest(r: { method: string; path: string; status: number; ms: number; cache: string | null; trace: unknown | null }): void
+  /** The active build's `dev.json` (L14), or null before the first build. */
+  meta(): unknown | null
+}
+
+/** One entry of the dev trace list (`/_brust/dev/traces`, newest last, at most [`MAX_TRACES`]). */
+export interface TraceEntry {
+  id: number
+  at: number
+  kind: 'page' | 'action' | 'request'
+  method: string
+  path: string
+  status: number
+  ms: number
+  /** The core's trace (`x-brust-dev`), pages only. */
+  trace: unknown | null
+}
+export const MAX_TRACES = 50
+
+export interface DevProxy {
+  server: Server<undefined>
+  port: number
+  /** The last [`MAX_TRACES`] traced requests, oldest first. */
+  traces(): TraceEntry[]
+  /** Send to every connected browser. */
+  broadcast(msg: Record<string, unknown>): void
+  clients(): number
+  stop(): void
+}
+
+export const CLIENT_PATH = '/_brust/dev/client.js'
+export const WS_PATH = '/_brust/dev/ws'
+export const DEVTOOLS_PATH = '/_brust/dev/devtools.js'
+export const TRACES_PATH = '/_brust/dev/traces'
+export const META_PATH = '/_brust/dev/meta'
+const scriptTag = (gen: number) => `<script type="module" src="${CLIENT_PATH}?g=${gen}"></script><script type="module" src="${DEVTOOLS_PATH}"></script>`
+
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string)
+
+/** `html` with the dev client script before `</head>` (else at the end). */
+export function inject(html: string, gen: number, trace: unknown | null = null): string {
+  const tag = scriptTag(gen) + (trace ? traceTag(trace) : '')
+  const i = html.search(/<\/head\s*>/i)
+  return i >= 0 ? html.slice(0, i) + tag + html.slice(i) : html + tag
+}
+
+function isDocument(req: Request): boolean {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return false
+  const dest = req.headers.get('sec-fetch-dest')
+  if (dest) return dest === 'document'
+  return (req.headers.get('accept') ?? '').includes('text/html')
+}
+
+/** `<script type=application/json id=__brust_trace>` for a traced page (`<` escaped: it cannot close the tag). */
+const traceTag = (trace: unknown) => `<script type="application/json" id="__brust_trace">${JSON.stringify(trace).replace(/</g, '\\u003c')}</script>`
+
+/** The core's `x-brust-dev` header (base64 of JSON) → the trace object; null when absent or malformed. */
+export function decodeTrace(h: string | null): unknown | null {
+  if (!h) return null
+  try {
+    return JSON.parse(Buffer.from(h, 'base64').toString('utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** A small HTML page (so even a plain-text 5xx or "no child yet" carries the client script). */
+function htmlPage(status: number, title: string, body: string, gen: number, trace: unknown | null = null): Response {
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>${scriptTag(gen)}${trace ? traceTag(trace) : ''}</head><body style="font:14px ui-monospace,monospace;padding:24px"><h1>${esc(title)}</h1><pre style="white-space:pre-wrap">${esc(body)}</pre></body></html>`
+  return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } })
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+/** The `Host` names the dev server answers to (DNS-rebinding guard): loopback, the configured bind host, and
+ * `BRUST_DEV_ALLOWED_HOSTS` (comma separated) for a tunnel or a custom local name. */
+export function allowedHosts(bind: string, extra: string | undefined): Set<string> {
+  return new Set([...LOOPBACK, bind.toLowerCase(), ...(extra ?? '').split(',').map((h) => h.trim().toLowerCase()).filter(Boolean)])
+}
+
+const hostName = (hostHeader: string): string => {
+  const h = hostHeader.toLowerCase()
+  return h.startsWith('[') ? h.slice(0, h.indexOf(']') + 1) : (h.split(':')[0] ?? '')
+}
+
+/** A WebSocket (or any request) from a page of ANOTHER origin must not reach the dev channel: `Origin`, when sent,
+ * has to be the host the request was addressed to. */
+export function sameOriginOrNone(origin: string | null, hostHeader: string | null): boolean {
+  if (origin === null) return true
+  try {
+    return new URL(origin).host.toLowerCase() === (hostHeader ?? '').toLowerCase()
+  } catch {
+    return false
+  }
+}
+
+let devtoolsJs: Promise<string> | null = null
+/** `<brust-devtools>` (L15), bundled from `devtools.ts` on first request and kept: it is only ever served by this proxy. */
+function devtoolsBundle(): Promise<string> {
+  devtoolsJs ??= Bun.build({ entrypoints: [join(import.meta.dir, 'devtools.ts')], target: 'browser', format: 'esm', minify: false }).then(async (r) => {
+    const out = r.outputs[0]
+    if (!r.success || !out) throw new Error(`devtools bundle failed: ${r.logs.map(String).join('\n')}`)
+    return out.text()
+  })
+  return devtoolsJs
+}
+
+/** The trace a proxied response carried (read by `onRequest`; the header itself never reaches the browser). */
+const traceOf = new WeakMap<Response, unknown>()
+
+export function startProxy(o: { hostname: string; port: number; allowedHosts?: string; token: string }, view: DevView): DevProxy {
+  const traces: TraceEntry[] = []
+  let seq = 0
+  const allowed = allowedHosts(o.hostname, o.allowedHosts ?? process.env.BRUST_DEV_ALLOWED_HOSTS)
+  const sockets = new Set<ServerWebSocket<undefined>>()
+  const send = (ws: ServerWebSocket<undefined>, msg: unknown) => {
+    try {
+      ws.send(JSON.stringify(msg))
+    } catch {}
+  }
+  const hello = () => ({ type: 'hello', gen: view.gen(), state: view.state(), diag: view.state() === 'error' ? view.diag() : null })
+
+  async function forward(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    const gen = view.gen()
+    const doc = isDocument(req)
+    const port = view.upstream()
+    if (port === null) {
+      const d = view.diag()
+      return htmlPage(503, d ? `brust dev: ${d.rule}` : 'brust dev: building…', d?.raw ?? 'The first build is running. This page reloads when it is ready.', gen)
+    }
+    const headers = new Headers(req.headers)
+    // The token only this proxy knows: whatever a browser sent under that name is overwritten.
+    headers.set('x-brust-dev-token', o.token)
+    const t0 = performance.now()
+    // Injection needs an identity body; `Host` and `Origin` are kept as the browser sent them (the actions cross-site guard reads both).
+    headers.set('accept-encoding', 'identity')
+    const hasBody = req.method !== 'GET' && req.method !== 'HEAD' && req.body !== null
+    let res: Response
+    try {
+      res = await fetch(`http://127.0.0.1:${port}${url.pathname}${url.search}`, {
+        method: req.method,
+        headers,
+        ...(hasBody ? { body: req.body, duplex: 'half' } : {}),
+        redirect: 'manual',
+        // biome-ignore lint/suspicious/noExplicitAny: Bun's fetch option
+      } as any)
+    } catch (e) {
+      return htmlPage(502, 'brust dev: the server is not reachable', String((e as Error).message ?? e), gen)
+    }
+    const out = new Headers(res.headers)
+    // The trace never reaches the browser as a header: it travels in the page (`#__brust_trace`) and `/_brust/dev/traces`.
+    const trace = decodeTrace(res.headers.get('x-brust-dev'))
+    out.delete('x-brust-dev')
+    const isAction = req.method !== 'GET' && req.method !== 'HEAD' ? true : url.pathname.startsWith('/_brust/action')
+    if (trace || isAction) {
+      traces.push({ id: ++seq, at: Date.now(), kind: trace ? 'page' : 'action', method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), trace })
+      if (traces.length > MAX_TRACES) traces.shift()
+    }
+    const tag = (r: Response) => (traceOf.set(r, trace), r)
+    out.set('cache-control', 'no-store')
+    out.delete('content-length')
+    out.delete('content-encoding')
+    const loc = out.get('location')
+    if (loc) out.set('location', loc.replace(`http://127.0.0.1:${port}`, url.origin))
+    const type = res.headers.get('content-type') ?? ''
+    if (req.method === 'HEAD' || res.status === 204 || res.status === 304) return new Response(null, { status: res.status, headers: out })
+    if (/text\/html/i.test(type)) {
+      out.set('content-type', type)
+      return tag(new Response(inject(await res.text(), gen, trace), { status: res.status, headers: out }))
+    }
+    if (doc && res.status >= 500) return tag(htmlPage(res.status, `${res.status} ${res.statusText || 'server error'}`, await res.text(), gen, trace))
+    return tag(new Response(res.body, { status: res.status, headers: out }))
+  }
+
+  const server = Bun.serve<undefined>({
+    hostname: o.hostname,
+    port: o.port,
+    async fetch(req, srv) {
+      const url = new URL(req.url)
+      // DNS rebinding: a page on evil.example whose name resolves to 127.0.0.1 would otherwise read the app and the
+      // source paths in build errors. Only the dev server's own names are answered.
+      if (!allowed.has(hostName(req.headers.get('host') ?? ''))) return new Response('brust dev: unexpected Host header (set BRUST_DEV_ALLOWED_HOSTS to allow it)', { status: 421 })
+      if (url.pathname === WS_PATH && !sameOriginOrNone(req.headers.get('origin'), req.headers.get('host'))) return new Response('brust dev: cross-origin WebSocket refused', { status: 403 })
+      if (url.pathname === WS_PATH) return srv.upgrade(req, { data: undefined }) ? undefined : new Response('websocket expected', { status: 426 })
+      if (url.pathname === TRACES_PATH) return Response.json({ traces }, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === META_PATH) return Response.json(view.meta() ?? {}, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === DEVTOOLS_PATH) {
+        return devtoolsBundle().then(
+          (js) => new Response(js, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } }),
+          (e: Error) => new Response(e.message, { status: 500 }),
+        )
+      }
+      if (url.pathname === CLIENT_PATH) return new Response(DEV_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } })
+      const t0 = performance.now()
+      const res = await forward(req)
+      view.onRequest({ method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), cache: res.headers.get('x-brust-cache'), trace: traceOf.get(res) ?? null })
+      return res
+    },
+    websocket: {
+      open(ws) {
+        sockets.add(ws)
+        send(ws, hello())
+      },
+      close(ws) {
+        sockets.delete(ws)
+      },
+      message() {},
+    },
+  })
+  return {
+    server,
+    port: server.port ?? o.port,
+    broadcast(msg) {
+      for (const ws of sockets) send(ws, msg)
+    },
+    traces: () => traces,
+    clients: () => sockets.size,
+    stop: () => void server.stop(true),
+  }
+}

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,81 @@
+// 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, statSync, watch } from 'node:fs'
+import { join, 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>
+}
+
+export function watchLoop(o: { root: 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 watcher: FSWatcher = watch(o.root, { recursive: true }, (_ev, name) => {
+    if (!name) return
+    const rel = String(name).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(join(o.root, rel)).isDirectory()) return
+    } catch {}
+    queue(rel)
+  })
+  return {
+    trigger: (rel = '.') => queue(rel),
+    close() {
+      closed = true
+      clearTimeout(timer)
+      pending.clear()
+      watcher.close()
+      for (const w of idleWaiters.splice(0)) w()
+    },
+    idle: () => (!running && pending.size === 0 ? Promise.resolve() : new Promise<void>((r) => idleWaiters.push(r))),
+  }
+}
+
+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,9 @@
 // `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 { defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
 
 export interface DevOptions {
   appRoot: string
@@ -15,7 +15,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 +53,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 +64,12 @@ 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 loop: WatchLoop = watchLoop({
+    root: appRoot,
+    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 +77,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

@@ -141,6 +141,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 +187,8 @@ 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
 }): Handlers {
   const byId = new Map(opts.leaves.map((l) => [l.id, l]))
   const literals = literalsIndex(opts.manifest)
@@ -206,7 +241,8 @@ export function makeHandlers(opts: {
             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 })
             } catch (e) {
               if (isHttpErrorTrigger(e)) return { verdict: 'httpError', status: e.status, body: e.body } as LoaderResponse
               throw e
@@ -217,7 +253,10 @@ export function makeHandlers(opts: {
             }
             if (r && typeof r === 'object') Object.assign(merged, r)
           }
-          return withStore({ ok: true, data: merged } as LoaderResponse)
+          const ok = withStore({ ok: true, data: merged } as LoaderResponse)
+          const headers = (ok as { headers?: Record<string, string> }).headers
+          if (opts.ssg && headers && Object.keys(headers).length > 0) opts.ssg({ kind: 'headers', routeId: req.routeId, path: req.path, names: Object.keys(headers) })
+          return ok
         } catch (e) {
           return { error: String(e) } as LoaderResponse
         }

package/src/index.ts

@@ -1,4 +1,6 @@
+/// <reference path="./css-modules.d.ts" />
 // `@brust/core`: the app-facing API.
+export { buildTime } from './build-time'
 export { cache } from './cache'
 export { type BrustConfig, BrustConfigError, loadConfig } from './config'
 export { type RunOptions, run } from './run'
@@ -15,4 +17,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'