@christianirack/brainllm-runtime 0.6.1 → 0.8.0

package/brain-schema.js

@@ -1,7 +1,7 @@
 // BRAINLLM schema mini-language (INTERNALS §14, §15): shared by form() (brain-form.js), api() validation
 // (brain-data.js) and server.mjs, so a page that only fetches data does not load the form module.
-// Per field: `str num bool email url date` + `!` required + `<=N >=N` (length for str and lists, value for num) + `[T]`
-// list of T, or a nested schema object.
+// Per field: `str num bool email url date tel file` + `!` required + `<=N >=N` (length for str and lists, value for num,
+// bytes for file) + `[T]` list of T, or a nested schema object. `file(image/*,.pdf)` names the accepted types.
 const RX_EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
 const G = globalThis
 
@@ -9,7 +9,8 @@ const G = globalThis
 // i18n/<locale>.json; plural objects allowed for keys with `{n}`), else the English text. The table is read directly
 // (globalThis.__brainDict, filled by brain-i18n.js `add`) so a page that only validates does not load brain-i18n.js.
 // Keys: form.required form.list form.min_items form.max_items form.item form.number form.min form.max form.email
-// form.url form.date form.text form.boolean form.min_chars form.max_chars.
+// form.url form.date form.text form.boolean form.min_chars form.max_chars form.tel form.file form.file_type
+// form.file_min form.file_max.
 export function msg(key, en, vars) {
   const D = G.__brainDict
   if (D) {
@@ -29,14 +30,21 @@ export function msg(key, en, vars) {
 }
 
 // 'str!<=80' → { t: 'str', req: true, min, max, list: false }
-const TYPES = new Set(['str', 'num', 'bool', 'email', 'url', 'date'])
+const TYPES = new Set(['str', 'num', 'bool', 'email', 'url', 'date', 'tel', 'file'])
+const ACCEPT = /^(?:\.[a-z0-9]+|[a-z]+\/(?:\*|[a-z0-9.+-]+))$/
 function scalarRule(s) {
-  if (typeof s !== 'string' || s.length > 256) throw Error('form: invalid rule (use str num bool email url date, ! required, <=N >=N, [T])')
-  const m = /^(?:([a-z]+)(!)?|\[([a-z]+)(!)?\](!)?)((?:[<>]=-?\d+(?:\.\d+)?)*)$/.exec(s)
-  if (!m || m[4] && m[5]) throw Error(`form: invalid rule '${s}' (use str num bool email url date, ! required, <=N >=N, [T])`)
-  const r = { t: m[1] || m[3], req: !!(m[2] || m[4] || m[5]), list: !!m[3], min: null, max: null }
+  const syntax = '(use str num bool email url date tel file, file(image/*,.pdf), ! required, <=N >=N, [T])'
+  if (typeof s !== 'string' || s.length > 256) throw Error(`form: invalid rule ${syntax}`)
+  const m = /^(?:([a-z]+)(?:\(([^()]*)\))?(!)?|\[([a-z]+)(?:\(([^()]*)\))?(!)?\](!)?)((?:[<>]=-?\d+(?:\.\d+)?)*)$/.exec(s)
+  if (!m || m[6] && m[7]) throw Error(`form: invalid rule '${s}' ${syntax}`)
+  const r = { t: m[1] || m[4], req: !!(m[3] || m[6] || m[7]), list: !!m[4], min: null, max: null }
   if (!TYPES.has(r.t)) throw Error(`form: unknown type '${r.t}'`)
-  for (const [, op, n] of m[6].matchAll(/([<>])=(-?\d+(?:\.\d+)?)/g)) {
+  const accept = m[2] ?? m[5]
+  if (accept != null) {
+    r.accept = accept.split(',').map(a => a.trim().toLowerCase())
+    if (r.t !== 'file' || !r.accept.every(a => ACCEPT.test(a))) throw Error(`form: invalid rule '${s}' ${syntax}`)
+  }
+  for (const [, op, n] of m[8].matchAll(/([<>])=(-?\d+(?:\.\d+)?)/g)) {
     const key = op === '<' ? 'max' : 'min', value = Number(n)
     if (r[key] != null || !Number.isFinite(value) || (!r.list && r.t === 'bool') || ((r.list || r.t !== 'num') && (!Number.isSafeInteger(value) || value < 0))) throw Error(`form: invalid bounds in rule '${s}'`)
     r[key] = value
@@ -73,6 +81,24 @@ function calendarDate(s) {
   return year > 0 && month > 0 && month <= 12 && day > 0 && day <= days[month - 1]
 }
 
+// A phone as people write it: optional leading +, digits with single separators, 7 to 15 digits (E.164's maximum).
+function validTel(s) {
+  const t = s.trim()
+  if (!/^\+?\(?\d(?:[ .()-]{0,2}\d)*$/.test(t)) return false
+  const digits = t.replace(/\D/g, '').length
+  return digits >= 7 && digits <= 15
+}
+// The browser's File/Blob shape. The type and name come from the client: the server has to verify the content again.
+const isFile = v => !!v && typeof v === 'object' && typeof v.size === 'number' && typeof v.type === 'string'
+const accepted = (r, f) => r.accept.some(a => a[0] === '.' ? String(f.name || '').toLowerCase().endsWith(a) : a.endsWith('/*') ? f.type.toLowerCase().startsWith(a.slice(0, -1)) : f.type.toLowerCase() === a)
+function checkFile(r, f) {
+  if (!isFile(f)) return msg('form.file', 'Choose a file')
+  if (r.accept && !accepted(r, f)) return msg('form.file_type', 'This file type is not allowed')
+  if (r.min != null && f.size < r.min) return msg('form.file_min', `The file must be at least ${r.min} bytes`, { n: r.min })
+  if (r.max != null && f.size > r.max) return msg('form.file_max', `The file must be at most ${r.max} bytes`, { n: r.max })
+  return ''
+}
+
 const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`
 
 // Compiler-only validators for proven unbounded scalars. Separate entry points let
@@ -106,6 +132,7 @@ export function check(r, v) {
     }
     return ''
   }
+  if (r.t === 'file' && !empty(v)) return checkFile(r, v)
   if (Array.isArray(v)) return msg(r.t === 'num' ? 'form.number' : r.t === 'bool' ? 'form.boolean' : 'form.text', r.t === 'num' ? 'Enter a number' : r.t === 'bool' ? 'Choose true or false' : 'Enter text')
   if (empty(v)) return r.req ? msg('form.required', 'Required') : ''
   if (r.t === 'bool') return typeof v !== 'boolean' ? msg('form.boolean', 'Choose true or false') : r.req && !v ? msg('form.required', 'Required') : ''
@@ -132,9 +159,14 @@ export function check(r, v) {
     case 'date':
       if (typeof v !== 'string' || !calendarDate(s)) return msg('form.date', 'Enter a valid date')
       break
+    case 'tel':
+      if (typeof v !== 'string' || !validTel(s)) return msg('form.tel', 'Enter a valid phone number')
+      break
     case 'str':
       if (typeof v !== 'string') return msg('form.text', 'Enter text')
       break
+    case 'file':
+      return msg('form.file', 'Choose a file')
     default:
       throw Error(`form: unknown type '${r.t}'`)
   }

package/brain-trace.js

@@ -0,0 +1,269 @@
+// `brain trace`, the browser half (INTERNALS §49). Development only: the dev client (crates/brain-serve/src/client.js)
+// imports it and nothing a production build ships does. It records navigation, prefetch, fetch and RPC with payload and
+// response, console warnings, CSP and CORS failures, sockets and leak findings, and sends them over the HMR socket.
+// Values are redacted by the store before they reach disk. A same-origin request carries `x-brain-trace`, the id the
+// server and the backend then use, so one id follows it through every layer.
+// A new module records without touching any of this: `globalThis.__brainTrace('mymodule', 'mykind', { title, level, data })`.
+const G = globalThis
+const BODY = 65536
+const uuid = () => (G.crypto?.randomUUID ? G.crypto.randomUUID() : '00000000-0000-4000-8000-000000000000'.replace(/0/g, () => (Math.random() * 16 | 0).toString(16)))
+const lasting = () => {
+  try {
+    const known = G.sessionStorage.getItem('brain:trace')
+    if (known) return known
+    const made = uuid()
+    G.sessionStorage.setItem('brain:trace', made)
+    return made
+  } catch { return uuid() }
+}
+export const ids = { session: lasting(), tab: uuid() }
+
+let queue = [], send = null, timer = null
+const flush = () => {
+  timer = null
+  if (!queue.length || !send) return
+  const events = queue.slice(0, 200)
+  if (send(JSON.stringify({ t: 'brain:trace', ...ids, events }))) queue = queue.slice(events.length)
+  if (queue.length) timer = setTimeout(flush, 250)
+}
+export function note(module, kind, fields = {}) {
+  if (queue.length >= 1000) queue.shift()
+  queue.push({ ts: Date.now(), module, kind, route: G.location?.pathname, ...fields })
+  timer ??= setTimeout(flush, 100)
+}
+export function attach(sender) {
+  send = sender
+  timer ??= setTimeout(flush, 0)
+}
+G.__brainTrace = (module, kind, fields) => note(String(module), String(kind), fields)
+
+// ---------- locations: a generated line of a dev module back to its .brain line (the module's inline source map) ----------
+const RUNTIME = '/@brain/'
+const nativeFetch = G.fetch?.bind(G)
+let failedId = null
+// the id of the last failed call, for the error report that follows it (brain-err cannot see the request)
+export const lastFailed = () => failedId
+const MAPS = new Map()
+function mapOf(url) {
+  if (!MAPS.has(url)) {
+    if (MAPS.size > 64) MAPS.clear()
+    MAPS.set(url, (async () => {
+      const text = await (await nativeFetch(url)).text()
+      const found = /sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/.exec(text)
+      if (!found) return null
+      const { decode } = await import('./brain-err.js')
+      return decode(JSON.parse(atob(found[1])).mappings)
+    })().catch(() => null))
+  }
+  return MAPS.get(url)
+}
+export async function mapping(url, line) {
+  try {
+    const u = new URL(url, G.location.href)
+    if (u.origin !== G.location.origin || u.pathname.includes(RUNTIME)) return null
+    u.search = ''
+    const lines = await mapOf(u.href)
+    const original = lines && lines[line - 1]
+    return { file: u.pathname.replace(/^\//, ''), line: original || null, precision: original ? 'source-line' : 'module' }
+  } catch { return null }
+}
+// The first frame outside the runtime: who made this call.
+const callSite = () => {
+  for (const row of String(new Error().stack).split('\n').slice(2)) {
+    const found = /((?:https?):\/\/[^\s)]+):(\d+):\d+/.exec(row)
+    if (found && !found[1].includes(RUNTIME)) return { url: found[1], line: +found[2] }
+  }
+  return null
+}
+const located = async (site, fields) => {
+  const where = site && await mapping(site.url, site.line)
+  return where ? { file: where.file, line: where.line, ...fields } : fields
+}
+
+// ---------- fetch, RPC and prefetch ----------
+// source modules are not responses anyone debugs, and their literals are not data
+const textual = type => /json|text\/(?!event-stream|javascript)|xml|form-urlencoded/i.test(type || '')
+async function bodyOf(response) {
+  const type = response.headers.get('content-type')
+  if (!textual(type)) return type ? `[${type}]` : null
+  const reader = response.clone().body?.getReader()
+  if (!reader) return null
+  const decoder = new TextDecoder()
+  let text = ''
+  try {
+    while (text.length < BODY) {
+      const { done, value } = await reader.read()
+      if (done) return text + decoder.decode()
+      text += decoder.decode(value, { stream: true })
+    }
+    return text.slice(0, BODY) + '…[truncated by the browser]'
+  } finally { reader.cancel().catch(() => {}) }
+}
+const payloadOf = (input, init) => {
+  const body = init?.body
+  if (typeof body === 'string') return body.slice(0, BODY)
+  if (body instanceof G.URLSearchParams) return String(body).slice(0, BODY)
+  if (body != null) return `[${body.constructor?.name || typeof body}]`
+  return input instanceof G.Request && input.method !== 'GET' && input.method !== 'HEAD' ? '[Request body]' : null
+}
+const kindOf = (url, init, headers) =>
+  url.pathname.includes('/_r/') ? 'rpc'
+    : init?.priority === 'low' || headers.has('x-brain-prefetch') ? 'prefetch'
+      : /text\/html/.test(headers.get('accept') || '') ? 'page' : 'fetch'
+function wrapFetch() {
+  if (!nativeFetch || G.fetch.$trace) return
+  const wrapped = function (input, init) {
+    let url
+    try { url = new URL(input instanceof G.Request ? input.url : String(input), G.location.href) } catch { return nativeFetch(input, init) }
+    if (url.pathname.includes(RUNTIME) || !/^https?:$/.test(url.protocol) || /\.(?:js|mjs|brain|jsbrain|cssbrain)$/.test(url.pathname)) return nativeFetch(input, init)
+    const same = url.origin === G.location.origin, id = uuid(), site = callSite(), started = performance.now()
+    const headers = new Headers(init?.headers ?? (input instanceof G.Request ? input.headers : undefined))
+    const kind = kindOf(url, init, headers), method = (init?.method || (input instanceof G.Request ? input.method : 'GET')).toUpperCase()
+    const payload = payloadOf(input, init)
+    if (same) headers.set('x-brain-trace', id)
+    const route = same ? url.pathname + url.search : url.href
+    return nativeFetch(input, same ? { ...init, headers } : init).then(response => {
+      const elapsed = +(performance.now() - started).toFixed(1)
+      if (same && response.status >= 400) failedId = id
+      bodyOf(response).catch(() => null).then(async text => {
+        const fields = { request_id: same ? id : null, route, status: response.status, duration_ms: elapsed, data: { method, payload, response: text } }
+        note('browser', kind, response.status >= 400 ? await located(site, fields) : fields)
+      })
+      return response
+    }, async error => {
+      const elapsed = +(performance.now() - started).toFixed(1), aborted = error?.name === 'AbortError'
+      const fields = { request_id: same ? id : null, route, status: aborted ? null : 0, duration_ms: elapsed, level: aborted ? 'info' : 'error', title: aborted ? 'Request aborted' : same ? String(error?.message || error) : `Cross-origin request to ${url.origin} failed: ${error?.message || error}`, data: { method, payload, aborted } }
+      note('browser', aborted ? 'abort' : same ? kind : 'cors', aborted ? fields : await located(site, fields))
+      throw error
+    })
+  }
+  wrapped.$trace = 1
+  G.fetch = wrapped
+}
+// Uploads with a progress callback use XMLHttpRequest (brain-data).
+function wrapXhr() {
+  const X = G.XMLHttpRequest?.prototype
+  if (!X || X.$trace) return
+  X.$trace = 1
+  const open = X.open, sendRequest = X.send
+  X.open = function (method, url, ...rest) {
+    this.$traced = { method: String(method).toUpperCase(), url: new URL(String(url), G.location.href) }
+    return open.call(this, method, url, ...rest)
+  }
+  X.send = function (body) {
+    const info = this.$traced, started = performance.now(), id = uuid()
+    if (info) {
+      const same = info.url.origin === G.location.origin
+      if (same) this.setRequestHeader('x-brain-trace', id)
+      this.addEventListener('loadend', () => note('browser', 'xhr', { request_id: same ? id : null, route: same ? info.url.pathname + info.url.search : info.url.href, status: this.status, duration_ms: +(performance.now() - started).toFixed(1), data: { method: info.method, payload: typeof body === 'string' ? body.slice(0, BODY) : body == null ? null : `[${body.constructor?.name}]` } }))
+    }
+    return sendRequest.call(this, body)
+  }
+}
+
+// ---------- navigation ----------
+function watchNavigation() {
+  const entry = G.performance?.getEntriesByType?.('navigation')?.[0]
+  const server = entry?.serverTiming?.find(item => item.name === 'rid')?.description
+  // the document itself: the server's id comes back in Server-Timing, the only header a page can read about its own load
+  const first = () => {
+    const done = G.performance?.getEntriesByType?.('navigation')?.[0]
+    note('browser', 'navigation', { request_id: server || null, route: G.location.pathname + G.location.search, status: done?.responseStatus || null, duration_ms: done?.loadEventEnd ? +done.loadEventEnd.toFixed(1) : null, data: { type: done?.type || 'navigate' } })
+  }
+  if (G.document.readyState === 'complete') first()
+  else G.addEventListener('load', () => setTimeout(first), { once: true })
+  G.addEventListener('brain:navigate', () => note('browser', 'navigation', { route: G.location.pathname + G.location.search, data: { type: 'client' } }))
+  G.addEventListener('popstate', () => note('browser', 'navigation', { data: { type: 'history' } }))
+  // <link rel="prefetch"> and speculation never pass through fetch()
+  try {
+    new PerformanceObserver(list => {
+      for (const item of list.getEntries()) {
+        if (item.initiatorType !== 'link' || !G.document.querySelector(`link[rel="prefetch"][href="${new URL(item.name).pathname}"]`)) continue
+        note('browser', 'prefetch', { route: new URL(item.name).pathname, duration_ms: +item.duration.toFixed(1), status: item.responseStatus || null, data: { initiator: 'link' } })
+      }
+    }).observe({ type: 'resource', buffered: true })
+  } catch {}
+}
+
+// ---------- console, CSP ----------
+function watchConsole() {
+  for (const [method, level] of [['warn', 'warn'], ['error', 'error']]) {
+    const original = G.console?.[method]
+    if (!original) continue
+    G.console[method] = function (...args) {
+      // brain-err prints the errors it records: those are already `browser/error` events
+      if (!(args[0] instanceof Error) && !String(args[0]).startsWith('BRAIN_ERROR')) {
+        const site = callSite(), title = args.map(a => (typeof a === 'string' ? a : (() => { try { return JSON.stringify(a) } catch { return String(a) } })())).join(' ').slice(0, 1024)
+        located(site, { level, title }).then(fields => note('browser', 'console', fields))
+      }
+      return original.apply(this, args)
+    }
+  }
+}
+function watchCsp() {
+  G.document.addEventListener('securitypolicyviolation', async event => {
+    const { violatedDirective, effectiveDirective, blockedURI, sourceFile, lineNumber, columnNumber, disposition, sample } = event
+    const where = sourceFile && lineNumber ? await mapping(sourceFile, lineNumber) : null
+    note('browser', 'csp', {
+      level: 'error', title: `CSP ${effectiveDirective || violatedDirective} refused ${blockedURI || 'inline code'}`,
+      // a call made through the runtime's own wrappers says nothing about the app: the event keeps its route
+      file: where?.file ?? (sourceFile && !sourceFile.includes(RUNTIME) ? new URL(sourceFile, G.location.href).pathname : null), line: where ? where.line : sourceFile?.includes(RUNTIME) ? null : lineNumber || null,
+      data: { violation: { directive: effectiveDirective || violatedDirective, blocked: blockedURI, disposition, sample, sourceFile, line: lineNumber, column: columnNumber, precision: where?.precision || 'generated' } },
+    })
+  })
+}
+
+// ---------- sockets ----------
+function wrapSockets() {
+  const C = G.WebSocket
+  if (!C || C.$trace) return
+  const W = new Proxy(C, {
+    construct(target, args, next) {
+      const socket = Reflect.construct(target, args, next), url = String(args[0])
+      if (url.includes(RUNTIME)) return socket
+      const route = (() => { try { return new URL(url).pathname } catch { return url } })(), opened = performance.now()
+      let received = 0, sent = 0
+      socket.addEventListener('message', () => received++)
+      const write = socket.send
+      socket.send = function (...rest) { sent++; return write.apply(this, rest) }
+      socket.addEventListener('open', () => note('browser', 'socket-open', { route, data: { url } }))
+      socket.addEventListener('close', event => {
+        const clean = event.wasClean || event.code === 1000 || event.code === 1001
+        note('browser', clean ? 'socket-close' : 'socket', { route, level: clean ? 'info' : 'error', title: clean ? null : `Socket ${route} closed with code ${event.code}`, duration_ms: +(performance.now() - opened).toFixed(1), data: { url, code: event.code, reason: event.reason, received, sent } })
+      })
+      return socket
+    },
+  })
+  W.$trace = 1
+  G.WebSocket = W
+  const S = G.EventSource
+  if (!S) return
+  G.EventSource = new Proxy(S, {
+    construct(target, args, next) {
+      const source = Reflect.construct(target, args, next), route = String(args[0])
+      source.addEventListener('open', () => note('browser', 'socket-open', { route, data: { transport: 'sse' } }))
+      // a stream the browser will not retry is the failure; the ordinary reconnect is not
+      source.addEventListener('error', () => { if (source.readyState === 2) note('browser', 'socket', { route, level: 'error', title: `Event stream ${route} failed`, data: { transport: 'sse' } }) })
+      return source
+    },
+  })
+}
+
+// brain-inspect finds the leaks and already sends them to the same socket; `inspected` reads its batch for this store.
+export function inspected(batch) {
+  if (!batch.includes('"leak"')) return
+  try {
+    for (const record of JSON.parse(batch).d || []) {
+      if (record.k === 'leak') note('memory', 'leak', { level: 'warn', title: record.msg, code: record.code, fix: record.fix, component: record.name, file: record.file, line: record.line, data: { fx: record.fx } })
+    }
+  } catch {}
+}
+
+if (G.document) {
+  wrapFetch()
+  wrapXhr()
+  wrapSockets()
+  watchConsole()
+  watchCsp()
+  watchNavigation()
+}

package/brain-vitals.js

@@ -0,0 +1,60 @@
+// Core Web Vitals, opt-in: `vitals(report)` measures in this page and `reportVitals(url)` sends the final values.
+// Nothing is emitted unless an app imports this module. Metrics a browser lacks are never reported, so read them as
+// optional: LCP and INP do not exist in every engine. Thresholds are the published web.dev good/poor limits.
+const LIMITS = { LCP: [2500, 4000], CLS: [0.1, 0.25], INP: [200, 500], FCP: [1800, 3000], TTFB: [800, 1800] }
+const rate = (name, value) => (value <= LIMITS[name][0] ? 'good' : value <= LIMITS[name][1] ? 'needs-improvement' : 'poor')
+
+export function vitals(report, env = globalThis) {
+  const PO = env.PerformanceObserver
+  const types = PO?.supportedEntryTypes ?? []
+  const stops = []
+  const send = (name, value) => report({ name, value: name === 'CLS' ? +value.toFixed(4) : Math.round(value), rating: rate(name, value) })
+  const watch = (type, options, read) => {
+    if (!types.includes(type)) return
+    const po = new PO(list => read(list.getEntries()))
+    po.observe({ type, buffered: true, ...options })
+    stops.push(() => po.disconnect())
+  }
+  const nav = env.performance?.getEntriesByType?.('navigation')?.[0]
+  if (nav?.responseStart > 0) send('TTFB', nav.responseStart)
+  watch('paint', {}, list => { for (const e of list) if (e.name === 'first-contentful-paint') send('FCP', e.startTime) })
+  watch('largest-contentful-paint', {}, list => { const last = list[list.length - 1]; if (last) send('LCP', last.startTime) })
+  // CLS: the worst session window (gap under 1 s, at most 5 s long), without shifts caused by recent input.
+  let worst = 0, sum = 0, first = 0, previous = 0
+  watch('layout-shift', {}, list => {
+    for (const e of list) {
+      if (e.hadRecentInput) continue
+      if (sum && e.startTime - previous < 1000 && e.startTime - first < 5000) sum += e.value
+      else { sum = e.value; first = e.startTime }
+      previous = e.startTime
+      if (sum > worst) { worst = sum; send('CLS', worst) }
+    }
+  })
+  // INP: the slowest interaction, one in 50 discarded as an outlier, as the metric's definition says.
+  const slow = new Map()
+  let inp = -1
+  watch('event', { durationThreshold: 40 }, list => {
+    for (const e of list) if (e.interactionId) slow.set(e.interactionId, Math.max(slow.get(e.interactionId) ?? 0, e.duration))
+    const all = [...slow.values()].sort((a, b) => b - a)
+    const value = all[Math.min(all.length - 1, Math.floor(all.length / 50))]
+    if (value !== undefined && value !== inp) send('INP', (inp = value))
+    if (slow.size > 500) for (const key of [...slow.keys()].slice(0, 250)) slow.delete(key)
+  })
+  return () => { for (const stop of stops) stop() }
+}
+
+// One beacon each time the page is hidden, with what changed since the last one; the query string is never sent.
+export function reportVitals(url, env = globalThis) {
+  if (typeof url !== 'string' || !url.startsWith('/')) throw new TypeError('reportVitals(url): pass a same-origin path, such as "/api/vitals"')
+  const doc = env.document
+  const fresh = new Map()
+  const stop = vitals(metric => fresh.set(metric.name, metric), env)
+  const flush = () => {
+    if (doc.visibilityState !== 'hidden' || !fresh.size) return
+    const body = JSON.stringify({ path: env.location.pathname, metrics: [...fresh.values()] })
+    if (env.navigator.sendBeacon?.(url, new Blob([body], { type: 'application/json' }))) fresh.clear()
+  }
+  doc.addEventListener('visibilitychange', flush)
+  env.addEventListener('pagehide', flush)
+  return () => { stop(); doc.removeEventListener('visibilitychange', flush); env.removeEventListener('pagehide', flush) }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christianirack/brainllm-runtime",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "The BRAINLLM runtime for the Rust-built web compiler for LLMs: dependency-free ES modules (signals, DOM, router, data, forms, channels). The brain binary embeds this same version.",
   "type": "module",
   "exports": {

package/server/llm.mjs

@@ -0,0 +1,199 @@
+// Server LLM module (INTERNALS §51): `ctx.llm`, one provider-neutral call for Anthropic and OpenAI. Zero dependencies.
+// Provider contracts reviewed 2026-10-31 against the official documentation:
+// - Anthropic: platform.claude.com/docs/en/api/messages, /api/versioning, /api/errors, /build-with-claude/streaming.
+//   API version 2026-10-21 rejects temperature, top_p and top_k with a 400, so the neutral API has no sampling options.
+// - OpenAI: developers.openai.com/api/reference/resources/responses/methods/create, /api/docs/guides/streaming-responses
+//   and the event schemas of github.com/openai/openai-openapi (Responses API, stored off with `store: false`).
+// Keys come only from the server environment. An error never carries a key; provider text stays in `detail`, redacted.
+const LLM_PROVIDERS = {
+  anthropic: { key: 'ANTHROPIC_API_KEY', model: 'ANTHROPIC_MODEL', base: 'ANTHROPIC_BASE_URL', origin: 'https://api.anthropic.com' },
+  openai: { key: 'OPENAI_API_KEY', model: 'OPENAI_MODEL', base: 'OPENAI_BASE_URL', origin: 'https://api.openai.com' },
+}
+const LLM_ANTHROPIC_VERSION = '2026-10-21'
+const LLM_DEFAULT_TIMEOUT = 60000, LLM_MAX_TIMEOUT = 600000, LLM_DEFAULT_MAX_TOKENS = 1024
+const LLM_MAX_BODY = 32 * 1024 * 1024, LLM_MAX_LINE = 4 * 1024 * 1024, LLM_MAX_DETAIL = 500
+
+export class LlmError extends Error {
+  constructor(code, status, message, fix, extra = {}) {
+    super(message)
+    this.name = 'LlmError'
+    this.code = code
+    this.status = status
+    this.fix = fix
+    Object.assign(this, extra)
+  }
+}
+const llmConfig = (message, fix) => new LlmError('B0921', 503, message, fix)
+const llmFailure = (status, message, extra) => new LlmError('B0922', status, message, 'Inspect err.provider, err.providerStatus and err.detail on the server', extra)
+
+function llmResolve(env, o) {
+  if (!o || typeof o !== 'object') throw llmConfig('ctx.llm needs an options object', 'Pass { messages: [{ role: "user", content: "…" }] } or { prompt: "…" }')
+  const requested = o.provider ?? env.BRAIN_LLM_PROVIDER
+  if (requested != null && requested !== '' && !Object.hasOwn(LLM_PROVIDERS, requested)) throw llmConfig(`Unknown LLM provider "${String(requested).slice(0, 40)}"`, 'Use "anthropic" or "openai"')
+  const present = Object.keys(LLM_PROVIDERS).filter(name => env[LLM_PROVIDERS[name].key])
+  const provider = requested || (present.length === 1 ? present[0] : null)
+  if (!provider) throw llmConfig(present.length ? 'Both LLM provider keys are set and none is selected' : 'No LLM provider key is set', present.length ? 'Pass { provider } or set BRAIN_LLM_PROVIDER in .brain_env' : 'Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .brain_env (never with PUBLIC_)')
+  const p = LLM_PROVIDERS[provider], key = env[p.key]
+  if (!key) throw llmConfig(`${p.key} is not set`, `Set ${p.key} in .brain_env (never with PUBLIC_)`)
+  const model = o.model ?? env[p.model]
+  if (typeof model !== 'string' || !model) throw llmConfig(`No model selected for ${provider}`, `Pass { model } or set ${p.model} in .brain_env; BRAINLLM pins no model`)
+  let base
+  try { base = new URL(env[p.base] || p.origin) } catch { throw llmConfig(`${p.base} is not a URL`, `Set ${p.base} to an https address`) }
+  const loopback = base.hostname === '127.0.0.1' || base.hostname === 'localhost' || base.hostname === '[::1]'
+  if (base.protocol !== 'https:' && !(base.protocol === 'http:' && loopback)) throw llmConfig(`${p.base} must use https`, 'Only a loopback address may use plain http')
+  if (base.username || base.password) throw llmConfig(`${p.base} must not carry credentials`, `Keep the key in ${p.key}`)
+  const messages = o.messages ?? (typeof o.prompt === 'string' ? [{ role: 'user', content: o.prompt }] : null)
+  if (!Array.isArray(messages) || !messages.length) throw new LlmError('B0921', 400, 'ctx.llm needs messages or prompt', 'Pass { messages: [{ role: "user", content: "…" }] }')
+  for (const m of messages) if (!m || (m.role !== 'user' && m.role !== 'assistant') || typeof m.content !== 'string') throw new LlmError('B0921', 400, 'Each message needs role "user" or "assistant" and text content', 'The system prompt goes in { system }')
+  if (o.system != null && typeof o.system !== 'string') throw new LlmError('B0921', 400, 'system must be text', 'Pass { system: "…" }')
+  const maxTokens = o.maxTokens ?? LLM_DEFAULT_MAX_TOKENS
+  if (!Number.isSafeInteger(maxTokens) || maxTokens < 1) throw new LlmError('B0921', 400, 'maxTokens must be a positive integer', `Omit it for ${LLM_DEFAULT_MAX_TOKENS}`)
+  const timeoutMs = o.timeoutMs ?? LLM_DEFAULT_TIMEOUT
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > LLM_MAX_TIMEOUT) throw new LlmError('B0921', 400, `timeoutMs must be between 1 and ${LLM_MAX_TIMEOUT}`, `Omit it for ${LLM_DEFAULT_TIMEOUT}`)
+  return { provider, key, model, root: base.href.replace(/\/+$/, ''), messages, system: o.system ?? null, maxTokens, timeoutMs, signal: o.signal }
+}
+
+function llmRequest(r, stream) {
+  if (r.provider === 'anthropic') return {
+    url: r.root + '/v1/messages',
+    headers: { 'x-api-key': r.key, 'anthropic-version': LLM_ANTHROPIC_VERSION, 'content-type': 'application/json' },
+    body: { model: r.model, max_tokens: r.maxTokens, messages: r.messages, ...(r.system ? { system: r.system } : {}), ...(stream ? { stream: true } : {}) },
+  }
+  return {
+    url: r.root + '/v1/responses',
+    headers: { authorization: 'Bearer ' + r.key, 'content-type': 'application/json' },
+    body: { model: r.model, max_output_tokens: r.maxTokens, input: r.messages, store: false, ...(r.system ? { instructions: r.system } : {}), ...(stream ? { stream: true } : {}) },
+  }
+}
+
+const llmStop = reason => ({ end_turn: 'end', stop_sequence: 'end', completed: 'end', max_tokens: 'length', max_output_tokens: 'length', content_filter: 'filter', refusal: 'filter' })[reason] || 'other'
+const llmRedact = (text, key) => String(text ?? '').split(key).join('[key]').slice(0, LLM_MAX_DETAIL)
+
+function llmParsed(r, json, requestId) {
+  if (r.provider === 'anthropic') {
+    if (!Array.isArray(json?.content)) throw llmFailure(502, 'The model provider sent an unexpected answer', { provider: r.provider })
+    return { provider: r.provider, model: json.model ?? r.model, text: json.content.filter(b => b?.type === 'text').map(b => b.text).join(''), stopReason: llmStop(json.stop_reason), usage: { inputTokens: json.usage?.input_tokens ?? null, outputTokens: json.usage?.output_tokens ?? null }, requestId }
+  }
+  if (json?.status === 'failed') throw llmFailure(502, 'The model provider could not complete the request', { provider: r.provider, detail: llmRedact(json.error?.message, r.key) })
+  if (!Array.isArray(json?.output)) throw llmFailure(502, 'The model provider sent an unexpected answer', { provider: r.provider })
+  const text = json.output.filter(i => i?.type === 'message').flatMap(i => i.content || []).filter(c => c?.type === 'output_text').map(c => c.text).join('')
+  return { provider: r.provider, model: json.model ?? r.model, text, stopReason: llmStop(json.incomplete_details?.reason ?? json.status), usage: { inputTokens: json.usage?.input_tokens ?? null, outputTokens: json.usage?.output_tokens ?? null }, requestId }
+}
+
+async function llmStatusError(r, res) {
+  let detail = ''
+  try { const raw = await res.text(); try { const j = JSON.parse(raw); detail = j?.error?.message ?? raw } catch { detail = raw } } catch {}
+  const providerStatus = res.status, extra = { provider: r.provider, providerStatus, detail: llmRedact(detail, r.key) }
+  if (providerStatus === 429) return llmFailure(429, 'The model provider is rate limiting requests; try again shortly', { ...extra, retryAfter: res.headers.get('retry-after') })
+  if (providerStatus === 401 || providerStatus === 403) return new LlmError('B0921', 503, `The model provider refused the key in ${LLM_PROVIDERS[r.provider].key}`, 'Check the key and its permissions', extra)
+  return llmFailure(providerStatus === 504 || providerStatus === 408 ? 504 : 502, 'The model provider could not complete the request', extra)
+}
+
+async function llmFetch(r, stream, fallback) {
+  const deadline = AbortSignal.timeout(r.timeoutMs)
+  const signal = AbortSignal.any([deadline, ...(fallback ? [fallback] : []), ...(r.signal ? [r.signal] : [])])
+  const q = llmRequest(r, stream)
+  const failed = e => deadline.aborted ? llmFailure(504, 'The model provider did not answer in time', { provider: r.provider }) : signal.aborted ? llmFailure(499, 'The LLM call was cancelled', { provider: r.provider, cancelled: true }) : e instanceof LlmError ? e : llmFailure(502, 'The model provider could not be reached', { provider: r.provider })
+  let res
+  try { res = await fetch(q.url, { method: 'POST', headers: q.headers, body: JSON.stringify(q.body), signal, redirect: 'error' }) } catch (e) { throw failed(e) }
+  return { res, failed, requestId: res.headers.get('request-id') ?? res.headers.get('x-request-id') }
+}
+
+async function llmReadAll(res) {
+  const reader = res.body.getReader(), parts = []
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.length
+    if (total > LLM_MAX_BODY) { await reader.cancel(); throw llmFailure(502, 'The model provider answer is too large') }
+    parts.push(value)
+  }
+  return Buffer.concat(parts).toString('utf8')
+}
+
+// One `data:` payload per server-sent event; the event name is repeated inside each payload by both providers.
+async function* llmEvents(res) {
+  const decoder = new TextDecoder(), reader = res.body.getReader()
+  let buffer = '', data = []
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) return
+      buffer += decoder.decode(value, { stream: true })
+      if (buffer.length > LLM_MAX_LINE) throw llmFailure(502, 'The model provider sent an oversized event')
+      for (let at; (at = buffer.indexOf('\n')) >= 0;) {
+        const line = buffer.slice(0, at).replace(/\r$/, '')
+        buffer = buffer.slice(at + 1)
+        if (line === '') { if (data.length) { const raw = data.join('\n'); data = []; let e; try { e = JSON.parse(raw) } catch { throw llmFailure(502, 'The model provider sent an unreadable event') } yield e } }
+        else if (line.startsWith('data:')) data.push(line.slice(5).trimStart())
+      }
+    }
+  } finally { await reader.cancel().catch(() => {}) }
+}
+
+function llmStream(r, parent) {
+  let settle, reject
+  const result = new Promise((a, b) => { settle = a; reject = b })
+  result.catch(() => {}) // reading `.result` is optional; the iterator throws the same failure
+  const run = async function* () {
+    let opened
+    try { opened = await llmFetch(r, true, parent) } catch (e) { reject(e); throw e }
+    const { res, failed, requestId } = opened
+    const out = { provider: r.provider, model: r.model, text: '', stopReason: 'other', usage: { inputTokens: null, outputTokens: null }, requestId }
+    let finished = false
+    try {
+      if (!res.ok) throw await llmStatusError(r, res)
+      for await (const e of llmEvents(res)) {
+        let piece = ''
+        if (r.provider === 'anthropic') {
+          if (e.type === 'error') throw e.error?.type === 'rate_limit_error' ? llmFailure(429, 'The model provider is rate limiting requests; try again shortly', { provider: r.provider, detail: llmRedact(e.error?.message, r.key) }) : llmFailure(502, 'The model provider failed during the answer', { provider: r.provider, detail: llmRedact(e.error?.message, r.key) })
+          if (e.type === 'message_start') { out.model = e.message?.model ?? out.model; out.usage.inputTokens = e.message?.usage?.input_tokens ?? null; out.usage.outputTokens = e.message?.usage?.output_tokens ?? null }
+          else if (e.type === 'content_block_delta' && e.delta?.type === 'text_delta') piece = e.delta.text
+          else if (e.type === 'message_delta') { out.stopReason = llmStop(e.delta?.stop_reason); if (e.usage?.output_tokens != null) out.usage.outputTokens = e.usage.output_tokens }
+          else if (e.type === 'message_stop') finished = true
+        } else {
+          if (e.type === 'error') throw llmFailure(502, 'The model provider failed during the answer', { provider: r.provider, detail: llmRedact(e.message, r.key) })
+          if (e.type === 'response.failed') throw llmFailure(502, 'The model provider could not complete the request', { provider: r.provider, detail: llmRedact(e.response?.error?.message, r.key) })
+          if (e.type === 'response.output_text.delta') piece = e.delta
+          else if (e.type === 'response.completed' || e.type === 'response.incomplete') {
+            finished = true
+            out.model = e.response?.model ?? out.model
+            out.stopReason = llmStop(e.response?.incomplete_details?.reason ?? e.response?.status)
+            out.usage = { inputTokens: e.response?.usage?.input_tokens ?? null, outputTokens: e.response?.usage?.output_tokens ?? null }
+          }
+        }
+        if (piece) { out.text += piece; yield piece }
+      }
+      if (!finished) throw llmFailure(502, 'The model provider ended the answer early', { provider: r.provider })
+      settle(out)
+    } catch (e) { const f = failed(e); reject(f); throw f }
+  }
+  const iterator = run()
+  // Leaving the loop early closes the provider connection; `.result` then rejects as cancelled.
+  const stop = iterator.return.bind(iterator)
+  return {
+    result,
+    [Symbol.asyncIterator]() { return this },
+    next: () => iterator.next(),
+    return: value => { reject(llmFailure(499, 'The LLM stream was closed before its end', { provider: r.provider, cancelled: true })); return stop(value) },
+  }
+}
+
+// ctx.llm for one request: `signal` is ctx.signal, so a closed client or a passed deadline stops the provider call.
+export function llmClient(env, signal) {
+  return {
+    async complete(o) {
+      const r = llmResolve(env, o)
+      const { res, failed, requestId } = await llmFetch(r, false, signal)
+      try {
+        if (!res.ok) throw await llmStatusError(r, res)
+        let json
+        try { json = JSON.parse(await llmReadAll(res)) } catch (e) { if (e instanceof LlmError) throw e; if (e instanceof SyntaxError) throw llmFailure(502, 'The model provider sent an unreadable answer', { provider: r.provider }); throw e }
+        return llmParsed(r, json, requestId)
+      } catch (e) { throw failed(e) }
+    },
+    // Validates now, connects on the first read. `for await (const text of s)`, then `await s.result`.
+    stream(o) { return llmStream(llmResolve(env, o), signal) },
+  }
+}