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

package/src/dev/client.ts

@@ -0,0 +1,92 @@
+// The browser half of `brust dev`, served as `/_brust/dev/client.js?g=<gen>` and injected into every HTML
+// response by the proxy. One WebSocket to the parent (`/_brust/dev/ws`):
+//   hello  {gen, state, diag}  on every (re)connect — a page older than `gen` reloads (the catch-up), a failing
+//                              build shows the overlay above the stale page
+//   reload                      a new generation is serving
+//   error  {diag}               a build/boot failed
+//   css    {href, v}            a public/*.css changed: swap the <link>, keep the page
+//   css-swap {gen, map}          only built stylesheets changed (L19/L21): a new generation serves; swap each
+//                              data-brust-css link old href -> new href, keep the page (no reload)
+// WS, not SSE: SSE holds one of the six per-host connections, so six tabs would stall (R13.2).
+// The overlay lives in a shadow root, so page CSS cannot touch it and it cannot touch the page.
+export const DEV_CLIENT_JS = String.raw`
+let pageGen = Number(new URL(import.meta.url).searchParams.get('g') || 0)
+let host = null
+let delay = 150
+
+function esc(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
+}
+
+function clearOverlay() {
+  host?.remove()
+  host = null
+}
+
+function showOverlay(diag) {
+  clearOverlay()
+  host = document.createElement('brust-dev-overlay')
+  const root = host.attachShadow({ mode: 'open' })
+  const where = diag.file ? esc(diag.file) + (diag.line ? ':' + diag.line + (diag.col ? ':' + diag.col : '') : '') : ''
+  root.innerHTML =
+    '<style>:host{all:initial}.box{position:fixed;inset:0;z-index:2147483647;overflow:auto;background:rgba(20,0,0,.88);color:#fdd;font:14px/1.5 ui-monospace,Menlo,monospace;padding:32px}' +
+    'h1{margin:0 0 8px;font-size:18px;color:#ff8a80}.where{color:#ffd180;margin-bottom:12px}pre{white-space:pre-wrap;margin:0;color:#fff}small{display:block;margin-top:24px;color:#bbb}</style>' +
+    '<div class="box" role="alert" data-testid="brust-dev-overlay"><h1>brust: ' + esc(diag.rule || 'error') + '</h1>' +
+    (where ? '<div class="where">' + where + '</div>' : '') +
+    '<pre>' + esc(diag.raw || diag.message || '') + '</pre><small>The page below is the last good build. Fix the error and save: this overlay goes away on its own.</small></div>'
+  document.documentElement.appendChild(host)
+}
+
+function swapCss(href, v) {
+  for (const old of document.querySelectorAll('link[rel~="stylesheet"]')) {
+    const u = new URL(old.href, location.href)
+    if (u.origin !== location.origin || u.pathname !== href) continue
+    const next = old.cloneNode()
+    next.href = href + '?v=' + v
+    next.onload = () => old.remove()
+    next.onerror = () => next.remove()
+    old.after(next)
+  }
+}
+
+function swapBuiltCss(map) {
+  for (const old of document.querySelectorAll('link[data-brust-css]')) {
+    const to = map[new URL(old.href, location.href).pathname]
+    if (!to) continue
+    const next = old.cloneNode()
+    next.href = to
+    next.onload = () => old.remove()
+    next.onerror = () => next.remove()
+    old.after(next)
+  }
+}
+
+function handle(m) {
+  if (m.type === 'hello') {
+    if (m.state === 'error' && m.diag) showOverlay(m.diag)
+    else {
+      clearOverlay()
+      if (m.gen > pageGen) location.reload()
+    }
+  } else if (m.type === 'reload') location.reload()
+  else if (m.type === 'error') showOverlay(m.diag)
+  else if (m.type === 'css') swapCss(m.href, m.v)
+  else if (m.type === 'css-swap') {
+    pageGen = m.gen
+    swapBuiltCss(m.map)
+  }
+}
+
+function connect() {
+  const ws = new WebSocket((location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/_brust/dev/ws')
+  ws.onopen = () => {
+    delay = 150
+  }
+  ws.onmessage = (e) => handle(JSON.parse(e.data))
+  ws.onclose = () => {
+    setTimeout(connect, delay)
+    delay = Math.min(delay * 2, 2000)
+  }
+}
+connect()
+`

package/src/dev/devtools-data.ts

@@ -0,0 +1,23 @@
+// Pure data helpers of the devtools overlay (no DOM at import time: unit-testable under Bun).
+export type Tier = 'static' | 'native' | 'react'
+export interface DevMeta { components?: Record<string, { tier: Tier }> }
+
+export function tierCounts(rendered: string[], meta: DevMeta | null): Record<Tier, number> {
+  const out = { static: 0, native: 0, react: 0 }
+  for (const id of rendered) {
+    const t = meta?.components?.[id]?.tier
+    if (t) out[t]++
+  }
+  return out
+}
+
+/** Contrast ratio of two sRGB colours given as `[r, g, b]` 0..255 (WCAG 2.x). */
+export function contrast(a: [number, number, number], b: [number, number, number]): number {
+  const lum = (c: [number, number, number]) => {
+    const [r, g, bl] = c.map((v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4 }) as [number, number, number]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * bl
+  }
+  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x) as [number, number]
+  return (hi + 0.05) / (lo + 0.05)
+}
+

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