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

package/src/config.ts

@@ -1,14 +1,18 @@
 // Runtime configuration (spec §8). Precedence, high → low:
 //   env (BRUST_ADDR / BRUST_PORT / BRUST_WORKERS / BRUST_RENDER_SLOTS / BRUST_DRAIN_TIMEOUT_MS /
-//        BRUST_BOOT_TIMEOUT_MS / BRUST_CALL_TIMEOUT_MS)
-//   > CLI flags (`brust start --port/--workers`)
-//   > brust.toml ([server] address / port, [workers] count)
-//   > defaults (localhost, 1337, availableParallelism(), 1, 10000, 30000, 30000).
+//        BRUST_BOOT_TIMEOUT_MS / BRUST_CALL_TIMEOUT_MS / BRUST_SLOT_BYTES / BRUST_MAX_LOADER_RESPONSE_BYTES)
+//   > CLI flags (`brust start --port/--workers`) and `run({ config })`
+//   > brust.toml ([server] address / port / max_loader_response_bytes, [workers] count / slot_bytes, [cors], [actions] base_url / credentials)
+//   > defaults (localhost, 1337, availableParallelism(), 1, 10000, 30000, 30000, 262144, 8388608).
+// L16 R16.1: `actionsBaseUrl` follows env (BRUST_ACTIONS_BASE_URL) > run({ config }) > toml `[actions] base_url`.
+// `cors` has no env layer; `run({ config: { cors } })` replaces a toml `[cors]` as a whole (never merged), and
+// `cors: null` turns a toml `[cors]` off.
 // `brust start`'s BRUST_DIST_DIR / BRUST_APP_ENTRY follow the same env > flag rule (run.ts).
 // A missing brust.toml is fine; a present one with the wrong shape is an error. Messages follow
 // 0.1.x `runtime/config.ts`.
 import { availableParallelism } from 'node:os'
 import { join } from 'node:path'
+import { ACTION_CREDENTIALS, type ActionCredentials, baseUrlError } from './actions/prefix'
 
 /** `[cors]` in brust.toml; same shape and validation as the Rust `CorsConfig` (crates/brust-server/src/config.rs). */
 export interface CorsConfig {
@@ -32,10 +36,22 @@ export interface BrustConfig {
   callTimeoutMs: number
   /** tokio threads of the HTTP runtime (renders every page); absent = one per core (server default). */
   ioThreads?: number
-  /** From brust.toml `[cors]` only (runtime config: no env / CLI layer); absent = CORS off. */
+  /** The SAB response slot of one render slot, bytes (`slot_bytes`, env BRUST_SLOT_BYTES); 64 KiB..16 MiB. */
+  slotBytes: number
+  /** The biggest loader/jobs reply that crosses by heap when it does not fit the slot (`max_loader_response_bytes`,
+   * env BRUST_MAX_LOADER_RESPONSE_BYTES); 256 KiB..64 MiB. */
+  maxLoaderResponseBytes: number
+  /** `run({ config: { cors } })` over brust.toml `[cors]` (a whole-object replace); absent = CORS off. No env layer. */
   cors?: CorsConfig
+  /** L16 R16.1: the origin the browser `client()` calls (page script `__BRUST_ACTION_BASE__`); absent = same origin. */
+  actionsBaseUrl?: string
+  /** L16 R16.2: the client's default `RequestInit.credentials` (`__BRUST_ACTION_CREDENTIALS__`); absent = `same-origin`. */
+  actionsCredentials?: ActionCredentials
 }
 
+/** What `run({ config })` / `loadConfig`'s `cli` accepts: any setting, and `cors: null` to turn a toml `[cors]` off. */
+export type ConfigOverrides = Omit<Partial<BrustConfig>, 'cors'> & { cors?: (Omit<CorsConfig, 'credentials'> & { credentials?: boolean }) | null }
+
 export class BrustConfigError extends Error {
   override name = 'BrustConfigError'
   constructor(
@@ -46,11 +62,11 @@ export class BrustConfigError extends Error {
   }
 }
 
-const DEFAULTS = { host: 'localhost', port: 1337, drainTimeoutMs: 10_000, bootTimeoutMs: 30_000, callTimeoutMs: 30_000 }
+const DEFAULTS = { host: 'localhost', port: 1337, drainTimeoutMs: 10_000, bootTimeoutMs: 30_000, callTimeoutMs: 30_000, slotBytes: 256 * 1024, maxLoaderResponseBytes: 8_388_608 }
 
 /** Ceilings: ms values cross napi as `u32` (a larger number would wrap), more than 1024 Bun
- * workers is a misconfiguration, not a deployment, and each render slot is a 256 KiB shared
- * response buffer per worker (more than 64 would only exhaust memory). */
+ * workers is a misconfiguration, not a deployment, and each render slot is a `slotBytes` (default 256 KiB)
+ * shared response buffer per worker (more than 64 would only exhaust memory). */
 export const MAX_MS = 0xffff_ffff
 /** `max_age_seconds` crosses napi as `u32`, like the ms values. */
 const MAX_U32 = 0xffff_ffff
@@ -58,8 +74,14 @@ const MAX_U32 = 0xffff_ffff
 export const MAX_IO_THREADS = 256
 export const MAX_WORKERS = 1024
 export const MAX_RENDER_SLOTS = 64
+/** `slotBytes` (L10): 64 KiB..16 MiB. */
+export const MIN_SLOT_BYTES = 64 * 1024
+export const MAX_SLOT_BYTES = 16 * 1024 * 1024
+/** `maxLoaderResponseBytes` (L10): 256 KiB..64 MiB, like the actions limits. */
+export const MIN_LOADER_RESPONSE_BYTES = 256 * 1024
+export const MAX_LOADER_RESPONSE_BYTES = 64 * 1024 * 1024
 
-export async function loadConfig(cwd: string = process.cwd(), cli: Partial<BrustConfig> = {}): Promise<BrustConfig> {
+export async function loadConfig(cwd: string = process.cwd(), cli: ConfigOverrides = {}): Promise<BrustConfig> {
   const tomlPath = join(cwd, 'brust.toml')
   let fromToml: Partial<BrustConfig> = {}
   const file = Bun.file(tomlPath)
@@ -75,6 +97,8 @@ export async function loadConfig(cwd: string = process.cwd(), cli: Partial<Brust
   }
   const env = fromEnv()
   checkCli(cli)
+  // cli (validated, normalised) over toml as a whole object (R10.2); `null` = off.
+  const cors = cli.cors === undefined ? fromToml.cors : cli.cors === null ? undefined : checkCors(cli.cors, 'config.cors', null, false)
   return {
     host: env.host ?? cli.host ?? fromToml.host ?? DEFAULTS.host,
     port: env.port ?? cli.port ?? fromToml.port ?? DEFAULTS.port,
@@ -84,13 +108,35 @@ export async function loadConfig(cwd: string = process.cwd(), cli: Partial<Brust
     drainTimeoutMs: env.drainTimeoutMs ?? cli.drainTimeoutMs ?? DEFAULTS.drainTimeoutMs,
     bootTimeoutMs: env.bootTimeoutMs ?? cli.bootTimeoutMs ?? DEFAULTS.bootTimeoutMs,
     callTimeoutMs: env.callTimeoutMs ?? cli.callTimeoutMs ?? DEFAULTS.callTimeoutMs,
+    slotBytes: env.slotBytes ?? cli.slotBytes ?? fromToml.slotBytes ?? DEFAULTS.slotBytes,
+    maxLoaderResponseBytes: env.maxLoaderResponseBytes ?? cli.maxLoaderResponseBytes ?? fromToml.maxLoaderResponseBytes ?? DEFAULTS.maxLoaderResponseBytes,
     ioThreads: env.ioThreads ?? cli.ioThreads,
-    ...(fromToml.cors !== undefined ? { cors: fromToml.cors } : {}),
+    ...(cors ? { cors } : {}),
+    ...pick('actionsBaseUrl', env.actionsBaseUrl ?? cli.actionsBaseUrl ?? fromToml.actionsBaseUrl),
+    ...pick('actionsCredentials', cli.actionsCredentials ?? fromToml.actionsCredentials),
+  }
+}
+
+const pick = <K extends string, V>(k: K, v: V | undefined) => (v === undefined ? {} : ({ [k]: v } as { [P in K]: V }))
+
+/** `[cors]` of brust.toml and nothing else (no env, no cli): what the Cloudflare build ships in CONFIG.
+ * Throws `BrustConfigError` on a bad table, exactly like `loadConfig`. */
+export async function loadCors(cwd: string): Promise<CorsConfig | undefined> {
+  const tomlPath = join(cwd, 'brust.toml')
+  const file = Bun.file(tomlPath)
+  if (!(await file.exists())) return undefined
+  let parsed: unknown
+  try {
+    parsed = Bun.TOML.parse(await file.text())
+  } catch (e) {
+    throw new BrustConfigError(`failed to parse ${tomlPath}: ${(e as Error).message}`, tomlPath)
   }
+  const root = (parsed ?? {}) as Record<string, unknown>
+  return 'cors' in root ? parseCors(root.cors, tomlPath) : undefined
 }
 
 /** CLI / programmatic overrides get the same bounds as env (a CLI `--port 0` = any free port). */
-function checkCli(cli: Partial<BrustConfig>): void {
+function checkCli(cli: ConfigOverrides): void {
   const check = (name: string, v: number | undefined, min: number, max: number) => {
     if (v !== undefined && (!Number.isInteger(v) || v < min || v > max))
       throw new BrustConfigError(`${name} must be an integer in ${min}..${max} (got ${JSON.stringify(v)})`, null)
@@ -102,6 +148,14 @@ function checkCli(cli: Partial<BrustConfig>): void {
   check('bootTimeoutMs', cli.bootTimeoutMs, 1, MAX_MS)
   check('callTimeoutMs', cli.callTimeoutMs, 1, MAX_MS)
   check('ioThreads', cli.ioThreads, 1, MAX_IO_THREADS)
+  check('slotBytes', cli.slotBytes, MIN_SLOT_BYTES, MAX_SLOT_BYTES)
+  check('maxLoaderResponseBytes', cli.maxLoaderResponseBytes, MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES)
+  if (cli.actionsBaseUrl !== undefined) {
+    const why = baseUrlError(cli.actionsBaseUrl)
+    if (why) throw new BrustConfigError(`config.actionsBaseUrl ${why}`, null)
+  }
+  if (cli.actionsCredentials !== undefined && !ACTION_CREDENTIALS.includes(cli.actionsCredentials))
+    throw new BrustConfigError(`config.actionsCredentials must be one of ${ACTION_CREDENTIALS.join(', ')} (got ${JSON.stringify(cli.actionsCredentials)})`, null)
 }
 
 function table(v: unknown, what: string, file: string): Record<string, unknown> {
@@ -109,12 +163,21 @@ function table(v: unknown, what: string, file: string): Record<string, unknown>
   return v as Record<string, unknown>
 }
 
+function tomlInt(v: unknown, name: string, min: number, max: number, file: string): number | undefined {
+  if (v === undefined) return undefined
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < min || v > max)
+    throw new BrustConfigError(`${file}: ${name} must be an integer in ${min}..${max} (got ${JSON.stringify(v)})`, file)
+  return v
+}
+
 function fromTomlTable(parsed: unknown, file: string): Partial<BrustConfig> {
   const root = table(parsed, 'top level', file)
   const out: Partial<BrustConfig> = {}
   if ('server' in root) {
     const server = table(root.server, '[server]', file)
     const { port, address } = server
+    const cap = tomlInt(server.max_loader_response_bytes, 'server.max_loader_response_bytes', MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES, file)
+    if (cap !== undefined) out.maxLoaderResponseBytes = cap
     if (port !== undefined) {
       if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535)
         throw new BrustConfigError(`${file}: server.port must be an integer in 1..65535 (got ${JSON.stringify(port)})`, file)
@@ -127,7 +190,10 @@ function fromTomlTable(parsed: unknown, file: string): Partial<BrustConfig> {
     }
   }
   if ('workers' in root) {
-    const { count } = table(root.workers, '[workers]', file)
+    const w = table(root.workers, '[workers]', file)
+    const { count } = w
+    const slot = tomlInt(w.slot_bytes, 'workers.slot_bytes', MIN_SLOT_BYTES, MAX_SLOT_BYTES, file)
+    if (slot !== undefined) out.slotBytes = slot
     if (count !== undefined) {
       if (typeof count !== 'number' || !Number.isInteger(count) || count < 1 || count > MAX_WORKERS)
         throw new BrustConfigError(`${file}: workers.count must be an integer in 1..${MAX_WORKERS} (got ${JSON.stringify(count)})`, file)
@@ -135,34 +201,62 @@ function fromTomlTable(parsed: unknown, file: string): Partial<BrustConfig> {
     }
   }
   if ('cors' in root) out.cors = parseCors(root.cors, file)
+  if ('actions' in root) {
+    const a = table(root.actions, '[actions]', file)
+    if (a.base_url !== undefined) {
+      const why = baseUrlError(a.base_url)
+      if (why) throw new BrustConfigError(`${file}: actions.base_url ${why}`, file)
+      out.actionsBaseUrl = a.base_url as string
+    }
+    if (a.credentials !== undefined) {
+      if (typeof a.credentials !== 'string' || !ACTION_CREDENTIALS.includes(a.credentials as ActionCredentials))
+        throw new BrustConfigError(`${file}: actions.credentials must be one of ${ACTION_CREDENTIALS.join(', ')} (got ${JSON.stringify(a.credentials)})`, file)
+      out.actionsCredentials = a.credentials as ActionCredentials
+    }
+  }
   return out
 }
 
 function parseCors(v: unknown, file: string): CorsConfig {
-  const t = table(v, 'cors', file)
+  return checkCors(corsFromToml(table(v, 'cors', file)), `${file}: cors`, file, true)
+}
+
+/** brust.toml `[cors]` (snake_case keys) → the camelCase shape [`checkCors`] validates. Unknown toml keys are ignored, as always. */
+function corsFromToml(t: Record<string, unknown>): Record<string, unknown> {
+  return { origins: t.origins, methods: t.methods, headers: t.headers, exposeHeaders: t.expose_headers, credentials: t.credentials, maxAgeSeconds: t.max_age_seconds }
+}
+
+const CORS_KEYS = ['origins', 'methods', 'headers', 'exposeHeaders', 'credentials', 'maxAgeSeconds']
+
+/** The one `[cors]` validator (Rust `CorsConfig::validate`, verbatim), for toml (`where` = `<file>: cors`, key names in
+ * snake_case) and for `run({ config: { cors } })` (`where` = `config.cors`, camelCase; an unknown key is an error). */
+function checkCors(c: unknown, where: string, file: string | null, snake: boolean): CorsConfig {
+  const fail = (m: string) => new BrustConfigError(m, file)
+  if (c === null || typeof c !== 'object' || Array.isArray(c)) throw fail(`${where} must be ${file === null ? 'an object (or null)' : 'a table'} (got ${JSON.stringify(c)})`)
+  const t = c as Record<string, unknown>
+  if (!snake) {
+    const bad = Object.keys(t).find((k) => !CORS_KEYS.includes(k))
+    if (bad !== undefined) throw fail(`${where}.${bad} is not a cors option (expected ${CORS_KEYS.join(', ')})`)
+  }
+  const name = (k: string) => (snake ? k.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`) : k)
   const strings = (val: unknown, key: string): string[] | undefined => {
     if (val === undefined) return undefined
-    if (!Array.isArray(val) || val.some((x) => typeof x !== 'string'))
-      throw new BrustConfigError(`${file}: cors.${key} must be an array of strings (got ${JSON.stringify(val)})`, file)
+    if (!Array.isArray(val) || val.some((x) => typeof x !== 'string')) throw fail(`${where}.${name(key)} must be an array of strings (got ${JSON.stringify(val)})`)
     return val as string[]
   }
   const origins = strings(t.origins, 'origins') ?? []
   const methods = strings(t.methods, 'methods')
   const headers = strings(t.headers, 'headers')
-  const exposeHeaders = strings(t.expose_headers, 'expose_headers')
-  if (t.credentials !== undefined && typeof t.credentials !== 'boolean')
-    throw new BrustConfigError(`${file}: cors.credentials must be a boolean (got ${JSON.stringify(t.credentials)})`, file)
+  const exposeHeaders = strings(t.exposeHeaders, 'exposeHeaders')
+  if (t.credentials !== undefined && typeof t.credentials !== 'boolean') throw fail(`${where}.credentials must be a boolean (got ${JSON.stringify(t.credentials)})`)
   const credentials = t.credentials === true
-  const age = t.max_age_seconds
+  const age = t.maxAgeSeconds
   if (age !== undefined && (typeof age !== 'number' || !Number.isInteger(age) || age < 0 || age > MAX_U32))
-    throw new BrustConfigError(`${file}: cors.max_age_seconds must be an integer in 0..${MAX_U32} (got ${JSON.stringify(age)})`, file)
+    throw fail(`${where}.${name('maxAgeSeconds')} must be an integer in 0..${MAX_U32} (got ${JSON.stringify(age)})`)
   // Rust CorsConfig::validate, verbatim.
-  if (origins.length === 0) throw new BrustConfigError(`${file}: cors.origins must be non-empty`, file)
+  if (origins.length === 0) throw fail(`${where}.origins must be non-empty`)
   if (credentials && origins.includes('*'))
-    throw new BrustConfigError(
-      `${file}: cors.credentials cannot be combined with a wildcard origin '*' (browsers reject Access-Control-Allow-Origin: * with credentials); list explicit origins instead`,
-      file,
-    )
+    throw fail(`${where}.credentials cannot be combined with a wildcard origin '*' (browsers reject Access-Control-Allow-Origin: * with credentials); list explicit origins instead`)
   return {
     origins,
     ...(methods ? { methods } : {}),
@@ -195,6 +289,14 @@ function fromEnv(): Partial<BrustConfig> {
   out.drainTimeoutMs = envInt('BRUST_DRAIN_TIMEOUT_MS', 0, MAX_MS, `an integer in 0..${MAX_MS}`)
   out.bootTimeoutMs = envInt('BRUST_BOOT_TIMEOUT_MS', 1, MAX_MS, `an integer in 1..${MAX_MS}`)
   out.callTimeoutMs = envInt('BRUST_CALL_TIMEOUT_MS', 1, MAX_MS, `an integer in 1..${MAX_MS}`)
+  out.slotBytes = envInt('BRUST_SLOT_BYTES', MIN_SLOT_BYTES, MAX_SLOT_BYTES, `an integer in ${MIN_SLOT_BYTES}..${MAX_SLOT_BYTES}`)
+  out.maxLoaderResponseBytes = envInt('BRUST_MAX_LOADER_RESPONSE_BYTES', MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES, `an integer in ${MIN_LOADER_RESPONSE_BYTES}..${MAX_LOADER_RESPONSE_BYTES}`)
   out.ioThreads = envInt('BRUST_WORKER_THREADS', 1, MAX_IO_THREADS, `an integer in 1..${MAX_IO_THREADS}`)
+  const base = process.env.BRUST_ACTIONS_BASE_URL
+  if (base !== undefined && base !== '') {
+    const why = baseUrlError(base)
+    if (why) throw new BrustConfigError(`BRUST_ACTIONS_BASE_URL ${why}`, null)
+    out.actionsBaseUrl = base
+  }
   return out
 }

package/src/css-modules.d.ts

@@ -0,0 +1,8 @@
+// L19 (R19.4): a `.module.css` import is its class map (the build's `cssPlugin`); any other `.css`
+// import is a side-effect import the server links (R19.3). Pulled in by a `/// <reference>` from the
+// entries apps import, so both forms typecheck.
+declare module '*.module.css' {
+  const classes: { readonly [name: string]: string }
+  export default classes
+}
+declare module '*.css' {}

package/src/dev/bun.ts

@@ -0,0 +1,365 @@
+// `brust dev` for the Bun target (R13): a long-lived parent owns the port (proxy.ts), every successful
+// build is booted as a NEW child (`brust start` on a loopback port) and swapped in blue/green. A failed
+// build or a failed boot keeps the old child serving. Never an in-process reload: one SERVER per
+// process, workers never restart, SABs are never freed (R13.1).
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { loadConfig } from '../config'
+import { type Diag, parseBuildError, parseWarnings } from './diag'
+import { tierCounts } from './devtools-data'
+import { type DevProxy, startProxy } from './proxy'
+import { HOTKEYS, Tui, type TuiOut, tuiMode } from './tui'
+import { defaultIgnored, watchLoop } from './watch'
+
+export interface BunDevOptions {
+  appRoot: string
+  entry: string
+  port?: number
+  /** Bun workers of each child; default 1 (R13.4). */
+  workers?: number
+  out?: TuiOut
+  env?: Record<string, string | undefined>
+  /** Fires with the user-visible URL once the proxy listens (tests). */
+  onListening?: (url: string) => void
+}
+
+const DEBOUNCE_MS = 150
+const BOOT_TIMEOUT_MS = 60_000
+const TAIL_LINES = 40
+const cliPath = join(import.meta.dir, '..', 'cli.ts')
+
+/** A free loopback port (bind port 0, read it, release it). */
+export function freePort(): number {
+  const s = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') })
+  const p = s.port as number
+  s.stop(true)
+  return p
+}
+
+function pumpLines(stream: ReadableStream<Uint8Array> | null | undefined, onLine: (l: string) => void): void {
+  if (!stream) return
+  void (async () => {
+    const dec = new TextDecoder()
+    let buf = ''
+    for await (const chunk of stream) {
+      buf += dec.decode(chunk, { stream: true })
+      let i = buf.indexOf('\n')
+      while (i >= 0) {
+        onLine(buf.slice(0, i).replace(/\r$/, ''))
+        buf = buf.slice(i + 1)
+        i = buf.indexOf('\n')
+      }
+    }
+    if (buf) onLine(buf)
+  })()
+}
+
+/** L19/L21 dev swap: the built stylesheets of the old and the new generation, paired by source stem
+ * (`<stem>-<hex10>.css`), as `/_brust/client/<old>` → `/_brust/client/<new>`. `null` when the pairing is not
+ * one-to-one (a stylesheet was added or removed, or two sources share a stem): the page must reload. */
+export function cssSwapMap(oldDir: string, newDir: string): Record<string, string> | null {
+  const byStem = (dir: string) => {
+    const m = new Map<string, string>()
+    let files: string[] = []
+    try {
+      files = readdirSync(join(dir, 'client'))
+    } catch {}
+    for (const f of files) {
+      const s = /^(.*)-[0-9a-f]{10}\.css$/.exec(f)?.[1]
+      if (s === undefined) continue
+      if (m.has(s)) return null
+      m.set(s, f)
+    }
+    return m
+  }
+  const a = byStem(oldDir)
+  const b = byStem(newDir)
+  if (!a || !b || a.size !== b.size) return null
+  const map: Record<string, string> = {}
+  for (const [stem, f] of a) {
+    const g = b.get(stem)
+    if (g === undefined) return null
+    if (g !== f) map[`/_brust/client/${f}`] = `/_brust/client/${g}`
+  }
+  return map
+}
+
+/** The child server's own tracing chatter is not forwarded; the app's console output is. */
+const NOISE = /\b(INFO|DEBUG)\b|^\[brust\] (listening on|ready)|^\s*$/
+
+interface Child {
+  proc: ReturnType<typeof Bun.spawn>
+  port: number
+  dir: string
+}
+
+export async function runBunDev(o: BunDevOptions): Promise<number> {
+  const appRoot = resolve(o.appRoot)
+  const entry = resolve(appRoot, o.entry)
+  const out: TuiOut = o.out ?? (process.stdout as unknown as TuiOut)
+  const env = o.env ?? process.env
+  const mode = tuiMode(out, env)
+  const tui = new Tui(out, mode.interactive, mode.color)
+  const cfg = await loadConfig(appRoot, o.port !== undefined ? { port: o.port } : {})
+  const workers = o.workers ?? 1
+  const devRoot = join(appRoot, '.brust', 'dev')
+  rmSync(devRoot, { recursive: true, force: true })
+  mkdirSync(devRoot, { recursive: true })
+
+  // R14.1: only this process and its children know the token; the core traces a request only if it carries it.
+  const devToken = crypto.randomUUID()
+  let counter = 0
+  let gen = 0
+  let state: 'building' | 'ready' | 'error' = 'building'
+  let diag: Diag | null = null
+  let active: Child | null = null
+  let buildMs: number | undefined
+  let warnings: string[] = []
+  let last: { method: string; path: string; status: number; tiers?: { static: number; native: number; react: number } } | undefined
+  let stopping = false
+  let url = ''
+  /** Processes spawned by an in-flight cycle (a build, a booting child): `stop()` must reach them (R13.5, own PIDs only). */
+  const inflight = new Set<ReturnType<typeof Bun.spawn>>()
+
+  const publish = () =>
+    tui.setStatus({
+      state,
+      url,
+      gen,
+      buildMs,
+      last,
+      warnings,
+      error: diag && state === 'error' ? `${diag.rule} ${diag.file ? `${diag.file}${diag.line ? `:${diag.line}` : ''} ` : ''}${diag.message}`.trim() : undefined,
+    })
+
+  const devMeta = (): unknown | null => {
+    try {
+      return active ? JSON.parse(readFileSync(join(active.dir, 'dev.json'), 'utf8')) : null
+    } catch {
+      return null
+    }
+  }
+
+  const proxy: DevProxy = startProxy(
+    { hostname: cfg.host, port: cfg.port, token: devToken },
+    {
+      gen: () => gen,
+      state: () => state,
+      diag: () => diag,
+      upstream: () => active?.port ?? null,
+      meta: devMeta,
+      onRequest(r) {
+        tui.log(`${r.method} ${r.path} ${r.status} ${r.ms}ms${r.cache ? ` ${r.cache}` : ''}`)
+        if (!r.path.startsWith('/_brust/')) {
+          const rendered = (r.trace as { rendered?: string[] } | null)?.rendered
+          last = { method: r.method, path: r.path, status: r.status, ...(rendered ? { tiers: tierCounts(rendered, devMeta() as Parameters<typeof tierCounts>[1]) } : {}) }
+          publish()
+        }
+      },
+    },
+  )
+  url = `http://${cfg.host}:${proxy.port}`
+  o.onListening?.(url)
+
+  /** Build into `dir`; a child process, so module caches never leak between builds. */
+  async function build(dir: string): Promise<{ ok: boolean; text: string; ms: number }> {
+    const t0 = performance.now()
+    const p = Bun.spawn([process.execPath, cliPath, 'build', o.entry, '--out-dir', dir, '--dev'], {
+      cwd: appRoot,
+      env: { ...process.env, NODE_ENV: 'development', BRUST_BUILD_MODE: 'development' },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    inflight.add(p)
+    const [so, se, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    inflight.delete(p)
+    return { ok: code === 0, text: `${so}\n${se}`, ms: Math.round(performance.now() - t0) }
+  }
+
+  /** Boot `brust start` over `dir`; resolves once `[brust] ready`, rejects with the output tail. */
+  function boot(dir: string): Promise<Child> {
+    const port = freePort()
+    const proc = Bun.spawn([process.execPath, cliPath, 'start', '--dist-dir', dir, '--entry', entry, '--workers', String(workers)], {
+      cwd: appRoot,
+      env: {
+        ...process.env,
+        NODE_ENV: 'development',
+        BRUST_PORT: String(port),
+        BRUST_ADDR: '127.0.0.1',
+        BRUST_WORKERS: String(workers),
+        BRUST_DIST_DIR: dir,
+        BRUST_APP_ENTRY: entry,
+        BRUST_DEV_TOKEN: devToken,
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    inflight.add(proc)
+    const tail: string[] = []
+    let ready = false
+    return new Promise<Child>((resolveBoot, reject) => {
+      const timer = setTimeout(() => {
+        proc.kill('SIGKILL')
+        reject(new Error(`the new build did not become ready within ${BOOT_TIMEOUT_MS / 1000}s\n${tail.join('\n')}`))
+      }, BOOT_TIMEOUT_MS)
+      const line = (l: string) => {
+        tail.push(l)
+        if (tail.length > TAIL_LINES) tail.shift()
+        if (!ready && /\[brust\] ready/.test(l)) {
+          ready = true
+          clearTimeout(timer)
+          resolveBoot({ proc, port, dir })
+        } else if (ready && !NOISE.test(l)) tui.log(l)
+      }
+      pumpLines(proc.stdout as ReadableStream<Uint8Array>, line)
+      pumpLines(proc.stderr as ReadableStream<Uint8Array>, line)
+      void proc.exited.then((code) => {
+        inflight.delete(proc)
+        clearTimeout(timer)
+        if (!ready) reject(new Error(`the new build exited with code ${code} before it was ready\n${tail.join('\n')}`))
+        else if (active?.proc === proc && !stopping) tui.log(`[brust] the server process exited (code ${code})`)
+      })
+    })
+  }
+
+  async function stopChild(c: Child): Promise<void> {
+    c.proc.kill('SIGINT')
+    if ((await Promise.race([c.proc.exited, Bun.sleep(4000).then(() => undefined)])) === undefined) {
+      c.proc.kill('SIGKILL')
+      await c.proc.exited
+    }
+    rmSync(c.dir, { recursive: true, force: true })
+  }
+
+  function fail(d: Diag): void {
+    state = 'error'
+    diag = d
+    proxy.broadcast({ type: 'error', diag: d })
+    tui.log(`[brust] ${d.rule}${d.file ? ` ${d.file}${d.line ? `:${d.line}${d.col ? `:${d.col}` : ''}` : ''}` : ''} ${d.message}`)
+    publish()
+  }
+
+  /** One build -> boot -> swap cycle. */
+  async function cycle(cssOnly = false): Promise<void> {
+    state = 'building'
+    publish()
+    const g = ++counter
+    const dir = join(devRoot, `g${g}`)
+    const b = await build(dir)
+    if (stopping) {
+      rmSync(dir, { recursive: true, force: true })
+      return
+    }
+    warnings = parseWarnings(b.text)
+    if (!b.ok) {
+      rmSync(dir, { recursive: true, force: true })
+      fail(parseBuildError(b.text) ?? { rule: 'build', message: b.text.trim().split('\n').pop() ?? 'build failed', raw: b.text.trim() })
+      return
+    }
+    let child: Child
+    try {
+      child = await boot(dir)
+    } catch (e) {
+      rmSync(dir, { recursive: true, force: true })
+      if (stopping) return
+      const raw = (e as Error).message
+      fail({ rule: 'boot', message: raw.split('\n')[0] ?? raw, raw })
+      return
+    }
+    // Stopped while this child booted, or a newer generation already took over: this child must not be adopted.
+    if (stopping || g < gen) {
+      await stopChild(child)
+      return
+    }
+    const old = active
+    active = child
+    gen = g
+    buildMs = b.ms
+    state = 'ready'
+    diag = null
+    // A stylesheet-only edit (L19/L21): the pages keep their DOM and swap their brust CSS links.
+    const swap = cssOnly && old ? cssSwapMap(old.dir, child.dir) : null
+    if (swap) {
+      proxy.broadcast({ type: 'css-swap', gen, map: swap })
+      tui.log(`[brust] css rebuilt (${Object.keys(swap).length} stylesheet${Object.keys(swap).length === 1 ? '' : 's'} swapped, no reload)`)
+    } else proxy.broadcast({ type: 'reload', gen })
+    publish()
+    if (old) void stopChild(old)
+  }
+
+  const isCss = (rel: string) => rel.startsWith('public/') && rel.endsWith('.css')
+
+  const loop = watchLoop({
+    root: appRoot,
+    ignored: (rel) => defaultIgnored(rel, 'dist'),
+    debounceMs: DEBOUNCE_MS,
+    async run(changed) {
+      // A change to public/*.css skips the build: copy it into the active dist and swap the <link> (R13.3).
+      if (active && state === 'ready' && [...changed].every((r) => isCss(r) && existsSync(join(appRoot, r)))) {
+        const v = Date.now()
+        for (const rel of changed) {
+          cpSync(join(appRoot, rel), join(active.dir, rel))
+          proxy.broadcast({ type: 'css', href: `/${rel}`, v })
+        }
+        tui.log(`[brust] css ${[...changed].join(', ')} (no reload)`)
+        return
+      }
+      tui.log(`[brust] change detected: ${[...changed].slice(0, 3).join(', ')}${changed.size > 3 ? ` +${changed.size - 3}` : ''}`)
+      // Only built stylesheets changed (L19/L21): rebuild, boot, then swap the links instead of reloading.
+      await cycle(active !== null && state === 'ready' && [...changed].every((r) => r.endsWith('.css') && !isCss(r)))
+    },
+  })
+
+  let exit: (code: number) => void = () => {}
+  const done = new Promise<number>((r) => {
+    exit = r
+  })
+  let stdinRaw = false
+  const stop = async () => {
+    if (stopping) return
+    stopping = true
+    loop.close()
+    proxy.stop()
+    if (stdinRaw) {
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+    }
+    tui.close()
+    // A build or a booting child of an in-flight cycle: SIGINT, then SIGKILL (own PIDs only).
+    const mid = [...inflight]
+    for (const p of mid) p.kill('SIGINT')
+    await Promise.all(mid.map(async (p) => {
+      if ((await Promise.race([p.exited, Bun.sleep(4000).then(() => undefined)])) === undefined) p.kill('SIGKILL')
+    }))
+    if (active) await stopChild(active)
+    rmSync(devRoot, { recursive: true, force: true })
+    exit(0)
+  }
+
+  if (mode.interactive && process.stdin.isTTY) {
+    stdinRaw = true
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+    process.stdin.on('data', (b) => {
+      for (const k of b.toString()) {
+        if (k === 'q' || k === '\x03') void stop()
+        else if (k === 'r') proxy.broadcast({ type: 'reload' })
+        else if (k === 'o') Bun.spawn([process.platform === 'darwin' ? 'open' : 'xdg-open', url], { stdout: 'ignore', stderr: 'ignore' })
+        else if (k === 'w') for (const w of warnings.length ? warnings : ['no warnings']) tui.log(`warning ${w}`)
+        else if (k === 'c') tui.clear()
+      }
+    })
+    ;(out as unknown as NodeJS.WriteStream).on?.('resize', () => tui.resize())
+  }
+  process.on('SIGINT', () => void stop())
+  process.on('SIGTERM', () => void stop())
+
+  tui.log(`[brust] dev server on ${url} — ${HOTKEYS}`)
+  publish()
+  // The first build goes through the loop too, so it is single-flight with every later one: an edit saved while it
+  // runs waits for it and then builds on top (never a second cycle racing the first).
+  loop.trigger('.')
+  void loop.idle()
+  return done
+}