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

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

@@ -0,0 +1,93 @@
+// `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 { join, relative, resolve } from 'node:path'
+import { BuildError } from './build/errors'
+import { defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
+
+export interface DevOptions {
+  appRoot: string
+  entry: string
+  outDir: string
+  port?: number
+  wranglerArgs: string[]
+  fromSource: boolean
+  log: (s: string) => void
+}
+
+const DEBOUNCE_MS = 300
+
+function wranglerBin(appRoot: string): string {
+  const fake = process.env.BRUST_WRANGLER
+  if (fake) return fake
+  const found = Bun.which('wrangler', { PATH: `${join(appRoot, 'node_modules', '.bin')}:${process.env.PATH ?? ''}` })
+  if (!found) throw new BuildError('cf-dev', 'wrangler not found (bun add -d wrangler)')
+  return found
+}
+
+/** Resolves with the exit code once the session ends (SIGINT/SIGTERM -> 0, or the child's own exit code). */
+export async function runDev(o: DevOptions): Promise<number> {
+  const appRoot = resolve(o.appRoot)
+  const dist = resolve(appRoot, o.outDir)
+  const bin = wranglerBin(appRoot)
+  const build = (): Promise<number> => {
+    const p = Bun.spawn([process.execPath, join(import.meta.dir, 'cli.ts'), 'build', o.entry, '--target', 'cloudflare', '--out-dir', o.outDir, ...(o.fromSource ? ['--wasm-from-source'] : [])], {
+      cwd: appRoot,
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    return p.exited
+  }
+  if ((await build()) !== 0) return 1
+
+  const args = ['dev', '-c', join(dist, 'cf', 'wrangler.jsonc'), '--persist-to', join(appRoot, '.wrangler', 'state'), ...(o.port !== undefined ? ['--port', String(o.port)] : []), ...o.wranglerArgs]
+  let child: ReturnType<typeof Bun.spawn> | null = null
+  let stopping = false
+  let restarting = false
+  let exitCode: (c: number) => void = () => {}
+  const done = new Promise<number>((r) => {
+    exitCode = r
+  })
+  const spawn = () => {
+    const c = Bun.spawn([bin, ...args], { cwd: appRoot, stdio: ['inherit', 'inherit', 'inherit'] })
+    child = c
+    c.exited.then((code) => {
+      if (child !== c || stopping || restarting) return
+      loop.close()
+      exitCode(code)
+    })
+  }
+  const stopChild = async () => {
+    const c = child
+    if (!c) return
+    c.kill('SIGTERM')
+    await c.exited
+  }
+
+  // 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
+        await stopChild()
+        restarting = false
+        if (!stopping) spawn()
+      } else o.log('[brust] rebuild failed; keeping the running wrangler')
+    },
+  })
+
+  spawn()
+  const stop = () => {
+    if (stopping) return
+    stopping = true
+    loop.close()
+    void stopChild().then(() => exitCode(0))
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+  return done
+}

package/src/handlers.ts

@@ -0,0 +1,282 @@
+// The host-agnostic half of the worker (M4-CF lane 4): wire shapes + `makeHandlers`. No Bun, no
+// napi, no `node:*` — the Cloudflare entry imports it through `@brust/core/server-handlers`.
+// `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 { type FlatRoute, isHttpErrorTrigger, isVerdict, type LoaderReq, type Route, type Verdict } from './routes'
+
+installServerResolver(getServerInstance)
+
+
+// ---- wire shapes (protocol.rs, camelCase) ----
+
+export interface LoaderRequest {
+  routeId: string
+  params: Record<string, string>
+  path: string
+  req: LoaderReq
+  /** M3-P P6: the chain has jobs — plan them in this call (`planJobs`). Optional to honour. */
+  plan?: boolean
+}
+
+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 }
+  | { error: string }
+
+export type JobKind = 'precompute' | 'ssr'
+
+export interface JobCall {
+  /** Opaque, echoed back: `<componentId>/<jobId>[/<row>]` for a chain job,
+   * `<parentId>/<childId>_<k>/<jobId>[/<row>]` for an inlined child instance (pipeline.rs `plan_one`). */
+  id: string
+  componentId: string
+  kind: JobKind
+  // biome-ignore lint/suspicious/noExplicitAny: job inputs are arbitrary JSON
+  inputs: any
+  /** ssr: the react component to render (D6). */
+  target?: string
+  row?: number
+}
+
+export interface JobsRequest {
+  jobs: JobCall[]
+}
+
+export type JobResult = { id: string; value: unknown } | { id: string; error: string }
+
+export interface JobsResponse {
+  results: JobResult[]
+}
+
+/** The default export of `<dist>/<manifest.jobs_module>` (built by Task 6): component id → job fns. */
+// biome-ignore lint/suspicious/noExplicitAny: props are whatever the component takes
+export type JobsModule = Record<string, { precompute?: (props: any) => unknown; ssr?: (props: any) => string | Promise<string> }>
+
+/** The slice of `manifest.json` the worker reads: ssr job `literals` (S6 amendment). */
+export interface ManifestLike {
+  routes?: { id: string; chain: string[] }[]
+  components: Record<
+    string,
+    {
+      jobs: { id: string; kind?: string; target?: string; literals?: Record<string, unknown> }[]
+      children?: { id: string }[]
+      stores?: string[]
+    }
+  >
+  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
+}
+
+export function toJson(out: unknown): string {
+  try {
+    return JSON.stringify(out)
+  } catch (e) {
+    return JSON.stringify({ error: `response not serialisable: ${String(e)}` })
+  }
+}
+
+// ---- literals (S6 amendment: the worker merges an ssr job's `literals` over `call.inputs`) ----
+
+/** `"<componentId>/<jobId>"` → that job record's `literals` (only records that carry some). */
+export function literalsIndex(manifest: ManifestLike | undefined): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>()
+  for (const [cid, c] of Object.entries(manifest?.components ?? {}))
+    for (const j of c.jobs ?? []) if (j.literals && Object.keys(j.literals).length > 0) out.set(`${cid}/${j.id}`, j.literals)
+  return out
+}
+
+/** The manifest job id of a call: the segment after `componentId` in a chain id
+ * (`<cid>/<jobId>[/<row>]`), else the third segment of a child-instance id
+ * (`<parentId>/<cid>_<k>/<jobId>[/<row>]`). */
+export function jobIdOf(call: Pick<JobCall, 'id' | 'componentId'>): string | undefined {
+  const parts = call.id.split('/')
+  return parts[0] === call.componentId ? parts[1] : parts[2]
+}
+
+// ---- touched stores (M3-F D4) ----
+
+/** route id -> sorted unique union of `stores` over the route's chain, walking each component's
+ * `children[].id` and `jobs[].target` transitively. Routes with an empty union are absent. */
+export function routeStoresIndex(manifest: ManifestLike | undefined): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const comps = manifest?.components ?? {}
+  for (const r of manifest?.routes ?? []) {
+    const acc = new Set<string>()
+    const seen = new Set<string>()
+    const walk = (id: string) => {
+      if (seen.has(id)) return
+      seen.add(id)
+      const c = comps[id]
+      if (!c) return
+      for (const p of c.stores ?? []) acc.add(p)
+      for (const k of c.children ?? []) walk(k.id)
+      for (const j of c.jobs ?? []) if (j.target) walk(j.target)
+    }
+    for (const id of r.chain ?? []) walk(id)
+    if (acc.size > 0) out.set(r.id, [...acc].sort())
+  }
+  return out
+}
+
+/** R1: `store` is assigned only when a store was touched; absent otherwise. */
+function withStore<T extends LoaderResponse>(r: T): T {
+  const s = collectSnapshot()
+  if (s) (r as { store?: StoreSnapshot | null }).store = s
+  return r
+}
+
+// ---- handlers ----
+
+/** `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 {
+  if (v.status === 404) {
+    const own = v.data ?? {}
+    return { verdict: 'notFound', data: typeof own === 'object' && !Array.isArray(own) ? { ...parent, ...own } : own }
+  }
+  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>
+}
+
+/** `leaves` from `flattenRoutes` (ids must match the manifest's route ids); `jobs` the jobs
+ * module; `manifest` supplies ssr `literals` (omit → no merge). */
+export function makeHandlers(opts: {
+  leaves: FlatRoute[]
+  jobs: JobsModule
+  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)
+  const jobs = opts.jobs
+  const storeIdx = routeStoresIndex(opts.manifest)
+  const storeTable = opts.stores ?? {}
+
+  async function runJob(call: JobCall): Promise<JobResult> {
+    const owner = call.kind === 'ssr' ? (call.target ?? call.componentId) : call.componentId // D6
+    const fn = jobs[owner]?.[call.kind]
+    if (typeof fn !== 'function') return { id: call.id, error: `no ${call.kind} job for component ${owner}` }
+    try {
+      let props = call.inputs
+      if (call.kind === 'ssr') {
+        const jid = jobIdOf(call)
+        const lit = jid === undefined ? undefined : literals.get(`${call.componentId}/${jid}`)
+        if (lit) props = { ...(props ?? {}), ...lit }
+        // Precompute runs outside any scope (D8); ssr runs in a scope seeded from `__store`, which props never see.
+        const seed = (props?.__store ?? null) as StoreSnapshot | null
+        if (props && '__store' in props) {
+          const { __store: _, ...rest } = props
+          props = rest
+        }
+        const p = props
+        return { id: call.id, value: await runInStoreContext(() => fn(p), seed) }
+      }
+      return { id: call.id, value: await fn(props) }
+    } catch (e) {
+      return { id: call.id, error: String(e) }
+    }
+  }
+
+  return {
+    // 0.1.x `runNativeChainLoaders`: root → leaf, flat merge (later keys win), first verdict stops
+    // (a notFound keeps what the chain merged so far: verdictJson).
+    async loader(req) {
+      const leaf = byId.get(req.routeId)
+      if (!leaf) return { error: `unknown routeId ${req.routeId}` }
+      // One object for the whole chain: each level's keys are assigned INTO it (later keys win,
+      // first-seen key order — what `{...merged, ...r}` produced) instead of re-spreading every
+      // key once per level (M3-P P1). `merged` is fresh per call; a loader's own object is never
+      // written to. Null prototype: with no `__proto__` setter to hit, an own "__proto__" key in a
+      // loader's data is assigned as data, as the spread copied it.
+      return runInStoreContext(async () => {
+        const merged: Record<string, unknown> = Object.create(null)
+        try {
+          const touch = storeIdx.get(req.routeId)
+          if (touch) touchStores(touch, storeTable)
+          for (const node of leaf.chain) {
+            if (!node.loader) continue
+            let r: unknown
+            try {
+              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
+            }
+            if (isVerdict(r)) {
+              const v = verdictJson(r, merged)
+              return 'verdict' in v && v.verdict === 'notFound' ? withStore(v) : v
+            }
+            if (r && typeof r === 'object') Object.assign(merged, r)
+          }
+          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
+        }
+      })
+    },
+    // One request carries every job of the page; a per-job failure keeps the other results.
+    async jobs(req) {
+      return { results: await Promise.all((req.jobs ?? []).map(runJob)) }
+    },
+  }
+}
+
+/** Wraps an async handler for a JSON-string boundary: parses, calls, serialises; NEVER rejects
+ * (a parse error or a throwing handler resolves `{"error":…}`, like `makeDispatch`). */
+export function jsonCall<Q, R>(fn: (q: Q) => Promise<R>): (json: string) => Promise<string> {
+  return async (json) => {
+    try {
+      return toJson(await fn(JSON.parse(json)))
+    } catch (e) {
+      return toJson({ error: String(e) })
+    }
+  }
+}

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'