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

package/src/dev/devtools.ts

@@ -0,0 +1,356 @@
+// `<brust-devtools>` (L15): the browser overlay of `brust dev`. Served by the dev proxy as `/_brust/dev/devtools.js`
+// (bundled from this file on first request) and injected by it into HTML responses: nothing of it exists under
+// `brust start` or in a production build. Everything it shows comes from the trace (`#__brust_trace`,
+// `/_brust/dev/traces`), `dev.json` (`/_brust/dev/meta`), the DOM or the dev global (`__brustDev`): nothing is invented.
+// It lives in a shadow root: no style leaks either way.
+
+import { tierCounts, type Tier } from './devtools-data'
+interface Diag { class: string; rule: string; line: number; col: number; message: string; remediation: string }
+export interface DevComponent { file: string; tier: Tier; reason?: string; diagnostics: Diag[] }
+interface DevMeta { components?: Record<string, DevComponent> }
+interface TraceJob { call_id: string; kind: string; component_id: string; user_key: string | null; tags: string[]; hit: boolean }
+interface Trace {
+  route: { id: string; pattern: string; chain: string[]; params: Record<string, string> } | null
+  status: number
+  cache: string
+  loader_ms: number | null
+  render_ms: number | null
+  render_error: string | null
+  bun_calls: number
+  jobs: TraceJob[]
+  jobs_more: number
+  rendered: string[]
+  truncated?: boolean
+}
+interface Entry { id: number; at: number; kind: string; method: string; path: string; status: number; ms: number; trace: Trace | null }
+interface BuildState { state: 'building' | 'ready' | 'error'; gen: number; diag: { rule: string; file?: string; line?: number; col?: number; message: string } | null }
+
+const TABS = ['Page', 'Components', 'Jobs', 'Store', 'Islands', 'Build', 'Requests'] as const
+type TabName = (typeof TABS)[number]
+
+const CSS = `
+:host { all: initial; position: fixed; width: 0; height: 0; --bg: #ffffff; --fg: #1a1a1f; --muted: #4a4a55; --line: #c9c9d2; --accent: #0b57d0; --accent-fg: #ffffff;
+  --static: #0b6b3a; --native: #0b57d0; --react: #8a3b00; --err: #b3261e; --warn: #7a5300; --hl: rgba(11, 87, 208, .25); }
+@media (prefers-color-scheme: dark) { :host { --bg: #1b1b1f; --fg: #f2f2f5; --muted: #c4c4cf; --line: #4a4a55; --accent: #8ab4f8; --accent-fg: #0a0a0c;
+  --static: #6ee7a8; --native: #8ab4f8; --react: #ffb27a; --err: #ff8a80; --warn: #ffd180; --hl: rgba(138, 180, 248, .3); } }
+* { box-sizing: border-box; }
+button { font: inherit; color: inherit; }
+.ind { position: fixed; right: 12px; bottom: 12px; z-index: 2147483646; display: flex; gap: 8px; align-items: center; padding: 6px 10px; border-radius: 999px;
+  background: var(--bg); color: var(--fg); border: 1px solid var(--line); font: 12px/1.2 ui-monospace, Menlo, monospace; cursor: pointer; box-shadow: 0 2px 8px rgba(0,0,0,.25); }
+.ind:focus-visible, .tab:focus-visible, .x:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.dot { width: 9px; height: 9px; border-radius: 50%; background: var(--static); }
+.dot.building { background: var(--warn); } .dot.error { background: var(--err); }
+.panel { position: fixed; right: 12px; bottom: 52px; z-index: 2147483646; width: min(560px, calc(100vw - 24px)); max-height: min(70vh, 560px); display: flex; flex-direction: column;
+  background: var(--bg); color: var(--fg); border: 1px solid var(--line); border-radius: 8px; font: 12px/1.45 ui-monospace, Menlo, monospace; box-shadow: 0 6px 24px rgba(0,0,0,.35); }
+.panel[hidden] { display: none; }
+.bar { display: flex; align-items: center; border-bottom: 1px solid var(--line); }
+.tabs { display: flex; flex: 1; overflow-x: auto; }
+.tab { padding: 8px 10px; background: none; border: 0; border-bottom: 2px solid transparent; cursor: pointer; color: var(--muted); }
+.tab[aria-selected="true"] { color: var(--fg); border-bottom-color: var(--accent); }
+.x { padding: 6px 10px; background: none; border: 0; cursor: pointer; color: var(--muted); }
+.body { padding: 10px; overflow: auto; }
+table { border-collapse: collapse; width: 100%; } th, td { text-align: left; padding: 3px 6px; border-bottom: 1px solid var(--line); vertical-align: top; }
+th { color: var(--muted); font-weight: 600; }
+.b { display: inline-block; padding: 0 6px; border-radius: 4px; border: 1px solid currentColor; font-weight: 700; }
+.b.static { color: var(--static); } .b.native { color: var(--native); } .b.react { color: var(--react); }
+.err { color: var(--err); } .warn { color: var(--warn); } .muted { color: var(--muted); }
+ul.tree { list-style: none; margin: 0; padding-left: 14px; } ul.tree.root { padding-left: 0; }
+.node { padding: 2px 4px; border-radius: 4px; cursor: default; } .node:hover, .node:focus { background: var(--hl); outline: none; }
+.hl { position: fixed; z-index: 2147483645; pointer-events: none; background: var(--hl); border: 2px solid var(--accent); border-radius: 3px; }
+code { font: inherit; } h3 { margin: 0 0 6px; font-size: 12px; }
+`
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string> = {}, ...kids: (Node | string)[]): HTMLElementTagNameMap[K] => {
+  const e = document.createElement(tag)
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v)
+  for (const k of kids) e.append(k)
+  return e
+}
+const badge = (t: Tier | 'unknown') => el('span', { class: `b ${t}` }, t)
+const ms = (n: number | null | undefined) => (typeof n === 'number' ? `${n.toFixed(2)} ms` : '—')
+
+class BrustDevtools extends HTMLElement {
+  private root = this.attachShadow({ mode: 'open' })
+  private ind!: HTMLButtonElement
+  private panel!: HTMLElement
+  private body!: HTMLElement
+  private tabs: HTMLButtonElement[] = []
+  private hl = el('div', { class: 'hl', hidden: '' })
+  private tab: TabName = 'Page'
+  private opener: Element | null = null
+  private meta: DevMeta | null = null
+  private entries: Entry[] = []
+  private build: BuildState = { state: 'building', gen: 0, diag: null }
+  private trace: Trace | null = null
+
+  connectedCallback(): void {
+    this.trace = readTrace()
+    const style = el('style'); style.textContent = CSS
+    this.ind = el('button', { class: 'ind', type: 'button', 'aria-haspopup': 'dialog', 'aria-expanded': 'false', 'aria-label': 'brust devtools' })
+    this.panel = el('div', { class: 'panel', role: 'dialog', 'aria-label': 'brust devtools', hidden: '' })
+    const tablist = el('div', { class: 'tabs', role: 'tablist', 'aria-label': 'devtools panels' })
+    for (const t of TABS) {
+      const b = el('button', { class: 'tab', type: 'button', role: 'tab', id: `tab-${t}`, 'aria-selected': 'false', tabindex: '-1', 'aria-controls': 'body' }, t)
+      b.onclick = () => this.select(t)
+      this.tabs.push(b); tablist.append(b)
+    }
+    const close = el('button', { class: 'x', type: 'button', 'aria-label': 'Close devtools' }, '✕')
+    close.onclick = () => this.close()
+    this.body = el('div', { class: 'body', id: 'body', role: 'tabpanel' })
+    this.panel.append(el('div', { class: 'bar' }, tablist, close), this.body)
+    this.root.append(style, this.hl, this.ind, this.panel)
+    this.ind.onclick = () => this.toggle()
+    tablist.onkeydown = (e) => this.tabKeys(e)
+    this.panel.onkeydown = (e) => { if (e.key === 'Escape') { e.stopPropagation(); this.close() } }
+    window.addEventListener('keydown', (e) => { if (e.altKey && e.shiftKey && (e.key === 'B' || e.key === 'b' || e.code === 'KeyB')) { e.preventDefault(); this.toggle() } })
+    this.paintIndicator()
+    void this.loadMeta()
+    this.connect()
+  }
+
+  private async loadMeta(): Promise<void> {
+    try { this.meta = (await (await fetch('/_brust/dev/meta')).json()) as DevMeta } catch { this.meta = null }
+    this.paintIndicator()
+    if (!this.panel.hidden) this.render()
+  }
+
+  private async loadEntries(): Promise<void> {
+    try { this.entries = ((await (await fetch('/_brust/dev/traces')).json()) as { traces: Entry[] }).traces } catch { this.entries = [] }
+  }
+
+  private connect(): void {
+    const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/_brust/dev/ws`)
+    ws.onmessage = (e) => {
+      const m = JSON.parse(e.data as string) as { type: string; gen?: number; state?: BuildState['state']; diag?: BuildState['diag'] }
+      if (m.type === 'hello') this.build = { state: m.state ?? 'ready', gen: m.gen ?? 0, diag: m.diag ?? null }
+      else if (m.type === 'error') this.build = { state: 'error', gen: this.build.gen, diag: m.diag ?? null }
+      else return
+      this.paintIndicator()
+      if (!this.panel.hidden && this.tab === 'Build') this.render()
+    }
+    ws.onclose = () => setTimeout(() => this.connect(), 1000)
+  }
+
+  private counts(): Record<Tier, number> { return tierCounts(this.trace?.rendered ?? [], this.meta) }
+
+  private paintIndicator(): void {
+    const c = this.counts()
+    this.ind.replaceChildren(el('span', { class: `dot ${this.build.state}`, 'aria-hidden': 'true' }), `${this.build.state} · ${c.static}s ${c.native}n ${c.react}r`)
+    this.ind.setAttribute('data-state', this.build.state)
+    this.ind.title = `static ${c.static} · native ${c.native} · react ${c.react} (Alt+Shift+B)`
+  }
+
+  toggle(): void { if (this.panel.hidden) this.open(); else this.close() }
+
+  open(): void {
+    this.opener = deepActive()
+    this.panel.hidden = false
+    this.ind.setAttribute('aria-expanded', 'true')
+    void this.loadEntries().then(() => { if (this.tab === 'Requests') this.render() })
+    this.select(this.tab)
+    this.tabs[TABS.indexOf(this.tab)]?.focus()
+  }
+
+  close(): void {
+    this.panel.hidden = true
+    this.hl.hidden = true
+    this.ind.setAttribute('aria-expanded', 'false')
+    const back = this.opener instanceof HTMLElement && this.opener !== document.body && this.opener.isConnected && !this.contains(this.opener) ? this.opener : this.ind
+    back.focus()
+  }
+
+  private tabKeys(e: KeyboardEvent): void {
+    const i = TABS.indexOf(this.tab)
+    const to = e.key === 'ArrowRight' ? (i + 1) % TABS.length : e.key === 'ArrowLeft' ? (i + TABS.length - 1) % TABS.length : e.key === 'Home' ? 0 : e.key === 'End' ? TABS.length - 1 : -1
+    if (to < 0) return
+    e.preventDefault()
+    this.select(TABS[to] as TabName)
+    this.tabs[to]?.focus()
+  }
+
+  private select(t: TabName): void {
+    this.tab = t
+    this.tabs.forEach((b, i) => { const on = TABS[i] === t; b.setAttribute('aria-selected', String(on)); b.tabIndex = on ? 0 : -1 })
+    this.body.setAttribute('aria-labelledby', `tab-${t}`)
+    this.render()
+  }
+
+  private render(): void {
+    const t = this.trace
+    const kids: Node[] = []
+    switch (this.tab) {
+      case 'Page': kids.push(this.pagePanel(t)); break
+      case 'Components': kids.push(this.componentsPanel(t)); break
+      case 'Jobs': kids.push(this.jobsPanel(t)); break
+      case 'Store': kids.push(this.storePanel()); break
+      case 'Islands': kids.push(this.islandsPanel()); break
+      case 'Build': kids.push(this.buildPanel()); break
+      case 'Requests': kids.push(this.requestsPanel()); break
+    }
+    this.body.replaceChildren(...kids)
+  }
+
+  private kv(rows: [string, string | Node][]): HTMLElement {
+    const tb = el('table')
+    for (const [k, v] of rows) tb.append(el('tr', {}, el('th', { scope: 'row' }, k), el('td', {}, v)))
+    return tb
+  }
+
+  private pagePanel(t: Trace | null): Node {
+    if (!t?.route) return el('p', { class: 'muted' }, 'No trace for this page (not served through a traced core, or the route did not match).')
+    const params = Object.entries(t.route.params)
+    return this.kv([
+      ['route', `${t.route.id}  ${t.route.pattern}`],
+      ['params', params.length ? params.map(([k, v]) => `${k}=${v}`).join(', ') : '—'],
+      ['status', String(t.status)],
+      ['cache', t.cache === '-' ? 'none (this route has no cache)' : t.cache],
+      ['loader', ms(t.loader_ms)],
+      ['render', ms(t.render_ms)],
+      ['worker calls', String(t.bun_calls)],
+      ['render error', t.render_error ?? '—'],
+      ...(t.truncated ? ([['trace', 'truncated to fit the header']] as [string, string][]) : []),
+    ])
+  }
+
+  private componentsPanel(t: Trace | null): Node {
+    const chain = t?.route?.chain ?? []
+    if (chain.length === 0) return el('p', { class: 'muted' }, 'No component data for this page.')
+    const extras = (t?.rendered ?? []).filter((id) => !chain.includes(id))
+    const node = (id: string, nested: Node | null): HTMLElement => {
+      const c = this.meta?.components?.[id]
+      const row = el('div', { class: 'node', tabindex: '0', 'data-component': id }, badge(c?.tier ?? 'unknown'), ' ', el('code', {}, id), c ? el('span', { class: 'muted' }, `  ${c.file}`) : '')
+      if (c?.tier === 'react') {
+        row.append(el('div', { class: 'muted' }, `reason: ${c.reason ?? '—'}`))
+        for (const d of c.diagnostics.filter((x) => x.class !== 'error')) row.append(el('div', { class: 'warn' }, `${c.file}:${d.line}:${d.col} ${d.rule}`))
+      }
+      const on = () => this.highlight(id)
+      row.onmouseenter = on; row.onfocus = on
+      row.onmouseleave = () => { this.hl.hidden = true }; row.onblur = () => { this.hl.hidden = true }
+      const li = el('li', {}, row)
+      if (nested) li.append(nested)
+      return li
+    }
+    let tree: Node | null = null
+    for (const id of [...chain].reverse()) tree = el('ul', { class: 'tree' }, node(id, tree))
+    const rootList = el('ul', { class: 'tree root' })
+    rootList.append(...(tree ? [...tree.childNodes] : []))
+    const out = el('div', {}, rootList)
+    if (extras.length) out.append(el('h3', {}, 'Also on the page (children)'), el('ul', { class: 'tree root' }, ...extras.map((id) => node(id, null))))
+    return out
+  }
+
+  /** Highlight a component on the page: chain marker (Range between `<!--brust:id-->` and its close), native `[x-data]`, island `brust-island`. */
+  private highlight(id: string): void {
+    const rects = componentRects(id)
+    if (rects.length === 0) { this.hl.hidden = true; return }
+    const r = rects[0] as DOMRect
+    Object.assign(this.hl.style, { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` })
+    this.hl.hidden = false
+  }
+
+  private jobsPanel(t: Trace | null): Node {
+    if (!t) return el('p', { class: 'muted' }, 'No trace for this page.')
+    if (t.jobs.length === 0) return el('p', { class: 'muted' }, t.cache === 'HIT' ? 'A cache HIT: no jobs ran.' : 'No jobs on this page.')
+    const tb = el('table', {}, el('tr', {}, ...['call', 'kind', 'result', 'key / tags'].map((h) => el('th', {}, h))))
+    for (const j of t.jobs) tb.append(el('tr', {}, el('td', {}, j.call_id), el('td', {}, j.kind), el('td', {}, j.hit ? 'hit' : 'miss'), el('td', {}, [j.user_key, ...j.tags].filter(Boolean).join(', ') || '—')))
+    const out = el('div', {}, tb)
+    if (t.jobs_more) out.append(el('p', { class: 'muted' }, `+${t.jobs_more} more not listed`))
+    return out
+  }
+
+  private storePanel(): Node {
+    const seeds = [...document.querySelectorAll('script[data-brust-store]')]
+    if (seeds.length === 0) return el('p', { class: 'muted' }, 'No stores on this page.')
+    const reg = (globalThis as Record<symbol, Record<string, { instance: Record<string, unknown> }> | undefined>)[Symbol.for('brust.stores')]
+    const out = el('div')
+    for (const s of seeds) {
+      const name = s.getAttribute('data-brust-store') ?? '?'
+      let seed: unknown = null
+      try { seed = JSON.parse(s.textContent ?? 'null') } catch { seed = s.textContent }
+      out.append(el('h3', {}, name), this.kv([['seed (SSR)', JSON.stringify(seed)], ['live', reg?.[name] ? JSON.stringify(liveValues(reg[name].instance)) : 'not mounted natively (no native component read it)']]))
+    }
+    return out
+  }
+
+  private islandsPanel(): Node {
+    const islands = [...document.querySelectorAll('brust-island')]
+    if (islands.length === 0) return el('p', { class: 'muted' }, 'No React islands on this page.')
+    const tb = el('table', {}, el('tr', {}, ...['island', 'hydrated'].map((h) => el('th', {}, h))))
+    for (const i of islands) tb.append(el('tr', {}, el('td', {}, i.getAttribute('data-id') ?? '?'), el('td', { class: i.getAttribute('data-hydrated') === '1' ? '' : 'warn' }, i.getAttribute('data-hydrated') === '1' ? 'yes' : 'no')))
+    return tb
+  }
+
+  private buildPanel(): Node {
+    const out = el('div', {}, el('p', {}, `build: ${this.build.state} (generation ${this.build.gen})`))
+    const d = this.build.diag
+    if (d) out.append(el('p', { class: 'err' }, `${d.rule}${d.file ? ` ${d.file}${d.line ? `:${d.line}${d.col ? `:${d.col}` : ''}` : ''}` : ''} ${d.message}`))
+    const rows: Node[] = []
+    for (const [id, c] of Object.entries(this.meta?.components ?? {})) {
+      for (const x of c.diagnostics) rows.push(el('tr', {}, el('td', { class: x.class === 'error' ? 'err' : 'warn' }, x.class), el('td', {}, `${c.file}:${x.line}:${x.col}`), el('td', {}, x.rule), el('td', {}, x.message + (x.remediation ? ` — ${x.remediation}` : '')), el('td', { class: 'muted' }, id)))
+    }
+    if (rows.length === 0) out.append(el('p', { class: 'muted' }, 'No warnings.'))
+    else out.append(el('table', {}, el('tr', {}, ...['class', 'location', 'rule', 'message', 'component'].map((h) => el('th', {}, h))), ...rows))
+    return out
+  }
+
+  private requestsPanel(): Node {
+    if (this.entries.length === 0) return el('p', { class: 'muted' }, 'No traced requests yet.')
+    const tb = el('table', {}, el('tr', {}, ...['', 'request', 'status', 'ms', 'cache'].map((h) => el('th', {}, h))))
+    for (const e of [...this.entries].reverse()) tb.append(el('tr', {}, el('td', { class: 'muted' }, e.kind), el('td', {}, `${e.method} ${e.path}`), el('td', { class: e.status >= 500 ? 'err' : '' }, String(e.status)), el('td', {}, String(e.ms)), el('td', {}, e.trace?.cache ?? '—')))
+    return tb
+  }
+}
+
+/** The focused element, looking through shadow roots (the devtools' own buttons live in one). */
+function deepActive(): Element | null {
+  let a: Element | null = document.activeElement
+  while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement
+  return a
+}
+
+function readTrace(): Trace | null {
+  try { return JSON.parse(document.getElementById('__brust_trace')?.textContent ?? 'null') as Trace | null } catch { return null }
+}
+
+/** Live values of a store instance. Only signals and computeds are READ (marked by the runtime with `Symbol.for`); actions are never called. */
+function liveValues(instance: Record<string, unknown>): Record<string, unknown> {
+  const SIGNAL = Symbol.for('brust.signal'); const COMPUTED = Symbol.for('brust.computed')
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(instance)) {
+    if (typeof v !== 'function') continue
+    const f = v as unknown as Record<symbol, unknown> & (() => unknown)
+    if (f[SIGNAL] === true || f[COMPUTED] === true) out[k] = f()
+  }
+  return out
+}
+
+/** Client rects of component `id` on the page. */
+export function componentRects(id: string): DOMRect[] {
+  const rects: DOMRect[] = []
+  for (const e of document.querySelectorAll(`[x-data]`)) if (e.getAttribute('x-data') === id) rects.push(e.getBoundingClientRect())
+  for (const e of document.querySelectorAll('brust-island')) if (e.getAttribute('data-id') === id) rects.push(e.getBoundingClientRect())
+  if (rects.length) return rects
+  // A chain level: the nodes between `<!--brust:id-->` and its matching `<!--/brust-->`.
+  const w = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT)
+  let open: Comment | null = null
+  let depth = 0
+  for (let n = w.nextNode() as Comment | null; n; n = w.nextNode() as Comment | null) {
+    const v = n.nodeValue ?? ''
+    if (!open) { if (v === `brust:${id}`) { open = n; depth = 1 } continue }
+    if (v.startsWith('brust:')) depth++
+    else if (v === '/brust' && --depth === 0) {
+      const r = document.createRange()
+      r.setStartAfter(open); r.setEndBefore(n)
+      const box = r.getBoundingClientRect()
+      return box.width || box.height ? [box] : []
+    }
+  }
+  return []
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('brust-devtools')) {
+  customElements.define('brust-devtools', BrustDevtools)
+  const mount = () => { if (!document.querySelector('brust-devtools')) document.body.append(document.createElement('brust-devtools')) }
+  if (document.body) mount()
+  else addEventListener('DOMContentLoaded', mount)
+}

package/src/dev/diag.ts

@@ -0,0 +1,30 @@
+// Parsing `brust build` output for the dev server: `error <rule> <file:line:col> <message>` (cli.ts) and
+// `warning <rule> <file:line:col> <message>` (compile.ts).
+export interface Diag {
+  rule: string
+  file?: string
+  line?: number
+  col?: number
+  message: string
+  /** The whole error text (stack, extra lines). */
+  raw: string
+}
+
+/** The first `error …` line of `out` and everything after it; null when there is none. */
+export function parseBuildError(out: string): Diag | null {
+  const i = out.search(/^error /m)
+  if (i < 0) return null
+  const raw = out.slice(i).trim()
+  const m = /^error (\S+) (?:(\S+?):(\d+):(\d+)[: ]\s*)?([^\n]*)/.exec(raw)
+  if (!m) return { rule: 'build', message: raw.split('\n')[0] ?? raw, raw }
+  const [, rule, file, line, col, message] = m
+  return { rule: rule ?? 'build', ...(file ? { file, line: Number(line), col: Number(col) } : {}), message: message ?? '', raw }
+}
+
+/** Every `warning …` line of `out`, without the `warning ` prefix. */
+export function parseWarnings(out: string): string[] {
+  return out
+    .split('\n')
+    .filter((l) => l.startsWith('warning '))
+    .map((l) => l.slice('warning '.length).trim())
+}

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