@christianirack/brainllm-runtime 0.3.1 → 0.4.0

package/brain-err.js

@@ -12,7 +12,7 @@ const RT = new URL('.', import.meta.url).href
 // Core hook: records (capture active) or console.error, and falls back to the nearest boundary's fallback (not for
 // event handlers).
 const I = _err((e, x, w) => {
-  on ? record(e, x, w) : G.console && console.error(e)
+  on ? record(e, x, w) : print(e)
   // §42: a failing event handler never destroys its component (it is reported; brain-guard shows the toast)
   if (String(w).startsWith('on:')) return
   for (; x; x = x.p || x.parentNode) {
@@ -20,6 +20,7 @@ const I = _err((e, x, w) => {
     if (b) return fall(b)
   }
 })
+const print = (e, ref) => G.console && console.error(I.development?.() ? e : `BRAIN_ERROR: Operation failed. Reference: ${ref || 'unavailable'}`)
 // Boundaries: owner N and its root elements → { fb, n: nodes, r: owner, f: already fell }.
 const BW = new WeakMap()
 const fbn = fb => {
@@ -50,7 +51,7 @@ export const fallback = (C, fb) =>
         try {
           a = I.nodes(C($p))
         } catch (e) {
-          on ? record(e, r, 'render') : G.console && console.error(e)
+          on ? record(e, r, 'render') : print(e)
           r.q()
           ;(b.f = 1), (a = fbn(fb))
         }
@@ -67,6 +68,7 @@ const crumbs = []
 let opts = {}, on = false, sent = 0, F0 = null
 
 export function crumb(k, d) {
+  k = clean(k, 40); d = clean(d, 200)
   const l = crumbs[crumbs.length - 1]
   if (l && l.k === k && l.d === d) return void l.n++ // the same repeated action is counted, not stacked
   crumbs.push({ k, d, n: 1, at: Date.now() })
@@ -82,22 +84,49 @@ const path = u => {
   try {
     return new URL(u, G.location && G.location.href).pathname // no query: it may carry sensitive data
   } catch {
-    return String(u).split('?')[0]
+    return String(u).split(/[?#]/)[0]
   }
 }
-// "url:line:col" of each frame; the first one outside the runtime is the app line.
+const LIMIT = { frames: 24, causes: 6, stackBytes: 16384, stackLines: 256, maps: 64, sourceBytes: 1048576, mapLines: 65536, loads: 2, pending: 64, deadline: 2000 }
+const get = (o, k) => { try { return o && o[k] } catch { return null } }
+const clean = (s, max = 500) => String(s == null ? '' : s).slice(0, max).replace(/(?:https?|file):\/\/[^\s)]+/g, u => u.split(/[?#]/)[0]).replace(/([/\w.:%-]+)[?#][^\s)'"]*/g, '$1')
+// Only structural stack locations are retained, never argument lists or the raw stack header.
 function frames(e) {
-  const out = []
-  for (const l of String((e && e.stack) || '').split('\n')) {
+  const raw = String(get(e, 'stack') || ''), out = []
+  let omitted = raw.length > LIMIT.stackBytes
+  const lines = raw.slice(0, LIMIT.stackBytes).split('\n')
+  if (lines.length > LIMIT.stackLines) omitted = true
+  for (const l of lines.slice(0, LIMIT.stackLines)) {
     const m = l.match(/((?:https?|file):\/\/[^\s)]+):(\d+):(\d+)/)
-    if (m) out.push({ url: m[1], line: +m[2], col: +m[3], rt: m[1].startsWith(RT) && !m[1].slice(RT.length).includes('/') })
+    if (!m) continue
+    if (![+m[2], +m[3]].every(n => Number.isSafeInteger(n) && n > 0)) { omitted = true; continue }
+    if (out.length >= LIMIT.frames) { omitted = true; break }
+    out.push({ url: m[1], line: +m[2], col: +m[3], rt: m[1].startsWith(RT) && !m[1].slice(RT.length).includes('/') })
   }
-  return out
+  return { frames: out, truncated: omitted }
+}
+const generated = t => t ? { file: path(t.url).slice(-1024), line: t.line, column: t.col } : null
+const location = (t, c) => ({ component: c ? clean(c.name || c.h || '', 120) || null : null, file: t ? path(t.url).slice(-1024) : c && c.file ? c.file : null, line: t ? t.line : null, column: t ? t.col : null, precision: t ? 'generated' : 'component-only' })
+function trace(e, c) {
+  const f = frames(e), top = f.frames.find(t => !t.rt) || null
+  return { rawFrames: f.frames, location: location(top, c), generatedLocation: generated(top), frames: f.frames.map(t => ({ generated: generated(t), source: null, runtime: t.rt })), truncated: { stack: f.truncated, frames: f.truncated, locations: f.frames.some(t => path(t.url).length > 1024) } }
+}
+function causes(e, c) {
+  const seen = new Set([e]), out = []
+  let next = get(e, 'cause'), truncated = false
+  while (next != null) {
+    if (seen.has(next) || out.length >= LIMIT.causes) { truncated = true; break }
+    seen.add(next)
+    const t = trace(next, c)
+    out.push({ depth: out.length + 1, type: clean(get(next, 'name') || typeof next, 80), code: clean(get(next, 'code') || '', 80) || null, msg: clean(get(next, 'message') || (typeof next === 'string' ? next : ''), 300), ...t })
+    next = get(next, 'cause')
+  }
+  return { entries: out, truncated }
 }
 // Component via the DOM: roots with data-b="<hash>" (prod) → parent chain via ancestors with data-b.
 function byDom(el) {
   const chain = []
-  for (; el; el = el.parentNode) if (el.getAttribute && el.getAttribute('data-b')) chain.push({ h: el.getAttribute('data-b') })
+  for (; el && chain.length < 33; el = el.parentNode) if (el.getAttribute && el.getAttribute('data-b')) chain.push({ h: el.getAttribute('data-b') })
   return chain.length ? { ...chain[0], chain: chain.map(c => c.h) } : null
 }
 // Prod chunk /_b/<hash>.brain → component hash.
@@ -110,18 +139,21 @@ const byStack = f => {
 // line to its .brain line. With `maps`, a recorded error is enriched asynchronously: `src` ('views/home.brain:12', the
 // first app frame) and `brainStack`; subscribers (brain_errors, overlay, doctor) are notified again. The file path
 // comes from the module URL (two `index.brain` in different folders never mix); prod chunks carry no map: no-op.
-const MAPS = new Map()
+const MAPS = new Map(), pending = []
+let loading = 0, enriching = 0
 const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
 export function decode(m) {
+  if (typeof m !== 'string' || m.length > LIMIT.sourceBytes) return []
   const lines = []
   let src = 0
-  for (const seg of m.split(';')) {
+  for (const seg of m.split(';').slice(0, LIMIT.mapLines)) {
     let line = null
     for (const part of seg.split(',')) {
       if (!part) continue
       const v = []
       for (let i = 0, n = 0, sh = 0; i < part.length; i++) {
         const d = B64.indexOf(part[i])
+        if (d < 0 || sh > 30) return []
         n += (d & 31) << sh
         if (d & 32) sh += 5
         else (v.push(n & 1 ? -(n >> 1) : n >> 1), (n = 0), (sh = 0))
@@ -132,54 +164,147 @@ export function decode(m) {
   }
   return lines
 }
-const mapOf = url => {
-  if (!MAPS.has(url))
-    MAPS.set(
-      url,
-      Promise.resolve(opts.load ? opts.load(url) : F0(url).then(r => r.text()))
-        .then(t => {
-          const m = /sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/.exec(t)
-          return m ? decode(JSON.parse(atob(m[1])).mappings) : null
-        })
-        .catch(() => null)
-    )
-  return MAPS.get(url)
-}
-async function toBrain(r, f) {
-  const out = []
-  for (const t of f.slice(0, 12)) {
-    const lines = t.rt ? null : await mapOf(t.url)
-    const l = lines && lines[t.line - 1]
-    if (l) out.push(`${path(t.url).replace(/^\//, '')}:${l}`)
+async function source(url, signal) {
+  if (opts.load) {
+    const text = await opts.load(url, { signal })
+    return typeof text === 'string' && text.length <= LIMIT.sourceBytes && new TextEncoder().encode(text).byteLength <= LIMIT.sourceBytes ? text : null
   }
-  if (!out.length) return
-  r.src = out[0]
-  r.brainStack = out
+  if (!F0) return null
+  const r = await F0(url, { signal, credentials: 'same-origin' })
+  if (r.ok === false || +(r.headers && r.headers.get('content-length')) > LIMIT.sourceBytes) return null
+  if (!r.body || !r.body.getReader) { const text = await r.text(); return text.length <= LIMIT.sourceBytes && new TextEncoder().encode(text).byteLength <= LIMIT.sourceBytes ? text : null }
+  const reader = r.body.getReader(), decoder = new TextDecoder()
+  let text = '', bytes = 0
+  try {
+    for (;;) {
+      const part = await reader.read()
+      if (part.done) break
+      bytes += part.value.byteLength
+      if (bytes > LIMIT.sourceBytes) { await reader.cancel(); return null }
+      text += decoder.decode(part.value, { stream: true })
+    }
+    return text + decoder.decode()
+  } finally { reader.releaseLock() }
+}
+function pump() {
+  while (loading < LIMIT.loads && pending.length) {
+    const task = pending.shift()
+    if (task.done) continue
+    loading++
+    Promise.resolve().then(() => source(task.url, task.controller.signal)).then(text => {
+      const m = text && /sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/.exec(text)
+      const map = m && JSON.parse(atob(m[1]))
+      const lines = map && map.version === 3 && decode(map.mappings)
+      task.finish({ lines: lines && lines.length ? lines : null, status: lines && lines.length ? 'mapped' : 'unavailable' })
+    }).catch(() => task.finish({ lines: null, status: 'unavailable' })).finally(() => { loading--; pump() })
+  }
+}
+function mapOf(input) {
+  let url
+  try {
+    const u = new URL(input), origin = G.location && G.location.origin
+    if (!['http:', 'https:', 'file:'].includes(u.protocol) || (u.protocol !== 'file:' && origin && origin !== 'null' && u.origin !== origin)) return Promise.resolve({ lines: null, status: 'unavailable' })
+    u.hash = ''; url = u.href
+  } catch { return Promise.resolve({ lines: null, status: 'unavailable' }) }
+  const hit = MAPS.get(url)
+  if (hit) { MAPS.delete(url); MAPS.set(url, hit); return hit.promise }
+  if (pending.length >= LIMIT.pending) return Promise.resolve({ lines: null, status: 'limited' })
+  if (MAPS.size >= LIMIT.maps) {
+    const old = [...MAPS].find(([, e]) => e.done)
+    if (!old) return Promise.resolve({ lines: null, status: 'limited' })
+    MAPS.delete(old[0])
+  }
+  const entry = { done: false }
+  entry.promise = new Promise(resolve => {
+    const task = { url, done: false, controller: new AbortController(), finish(result) {
+      if (task.done) return
+      task.done = entry.done = true
+      clearTimeout(timer)
+      const at = pending.indexOf(task)
+      if (at >= 0) pending.splice(at, 1)
+      if (result.status !== 'mapped' && MAPS.get(url) === entry) MAPS.delete(url)
+      resolve(result)
+    } }
+    const timer = setTimeout(() => { task.controller.abort(); task.finish({ lines: null, status: 'timeout' }) }, LIMIT.deadline)
+    pending.push(task)
+  })
+  MAPS.set(url, entry)
+  pump()
+  return entry.promise
+}
+async function toBrain(r, traces) {
+  const jobs = []
+  for (const item of traces) for (const [index, t] of item.rawFrames.entries()) {
+    if (t.rt) continue
+    jobs.push(mapOf(t.url).then(result => {
+      const line = result.lines && result.lines[t.line - 1]
+      if (Number.isSafeInteger(line) && line > 0 && item.frames[index]) item.frames[index].source = { file: path(t.url).replace(/^\//, '').slice(-1024), line, column: null }
+      return result.status
+    }))
+  }
+  const status = await Promise.all(jobs)
+  for (const item of traces) {
+    const first = item.frames.find(t => t.source)
+    if (first) item.location = { component: item.location.component, ...first.source, precision: 'source-line' }
+    delete item.rawFrames
+  }
+  for (let i = 1; i < traces.length; i++) r.causes[i - 1].location = traces[i].location
+  r.location = traces[0].location
+  r.frames = traces[0].frames
+  const out = r.frames.filter(t => t.source).map(t => `${t.source.file}:${t.source.line}`)
+  if (out.length) { r.src = out[0]; r.brainStack = out }
+  r.mapping = { status: status.includes('timeout') ? 'timeout' : status.includes('limited') ? 'limited' : out.length ? 'mapped' : 'unavailable' }
+  r.truncated.mapping = status.some(s => s === 'timeout' || s === 'limited')
+  boundRecord(r)
   for (const s of sub) s(r)
 }
 
+// Bound the serialized notification too, including mapped locations and nested causes.
+function boundRecord(r) {
+  const size = () => new TextEncoder().encode(JSON.stringify(r)).byteLength
+  r.truncated.output ||= false
+  while (size() > 65536) {
+    r.truncated.output = true
+    const nested = [...r.causes].reverse().find(c => c.frames.length)
+    if (nested) { nested.frames.pop(); nested.truncated.frames = true; continue }
+    if (r.frames.length > 1) { r.frames.pop(); r.stack.pop(); if (r.brainStack) r.brainStack.pop(); r.truncated.frames = true; continue }
+    if (r.causes.length) { r.causes.pop(); r.truncated.causes = true; continue }
+    break
+  }
+}
 function record(e, x, w) {
   if (e && e.kind === 'aborted') return // a cancelled request (brain-data ApiError): not an error
-  const f = frames(e), top = f.find(t => !t.rt) || null
-  const c = (opts.who && opts.who(x)) || (x && x.nodeType ? byDom(x) : null) || byStack(top)
-  const type = (e && e.code) || (e && e.name) || typeof e
-  const line = top ? `${path(top.url)}:${top.line}` : null
+  const extracted = frames(e), f = extracted.frames, top = f.find(t => !t.rt) || null
+  const owner = (opts.who && opts.who(x)) || (x && x.nodeType ? byDom(x) : null) || byStack(top)
+  const c = owner ? { id: typeof owner.id === 'number' ? owner.id : null, h: clean(owner.h || '', 120) || null, name: clean(owner.name || '', 120) || null, file: owner.file ? clean(owner.file, 500).split(/[?#]/)[0] : null, chain: Array.isArray(owner.chain) ? owner.chain.slice(0, 32).map(n => clean(n, 120)) : [] } : null
+  const type = clean(get(e, 'code') || get(e, 'name') || typeof e, 80)
+  const line = top ? `${path(top.url).slice(-1024)}:${top.line}` : null
   const fp = hash([type, c && c.h, line, w].join('|'))
   let r = errors.find(r => r.fp === fp)
   if (r) (r.n++, (r.last = Date.now()))
   else {
+    const t = trace(e, c), chain = causes(e, c)
     r = {
-      fp, code: (e && e.code) || null, type, msg: MSG[e && e.code] || String((e && e.message) || e).slice(0, 500), where: w || null, comp: c, line,
-      stack: f.slice(0, 12).map(t => `${path(t.url)}:${t.line}:${t.col}`), crumbs: crumbs.map(c => ({ ...c })),
-      build: opts.build || null, ua: G.navigator ? navigator.userAgent : null, at: Date.now(), last: Date.now(), n: 1,
+      fp, code: clean(get(e, 'code') || '', 80) || null, type, msg: MSG[get(e, 'code')] || clean(get(e, 'message') || e), where: clean(w || '', 120) || null, comp: c, line,
+      stack: f.slice(0, LIMIT.frames).map(t => `${path(t.url).slice(-1024)}:${t.line}:${t.col}`), location: t.location, generatedLocation: t.generatedLocation, frames: t.frames, causes: chain.entries.map(({ rawFrames, ...item }) => item), truncated: { ...t.truncated, causes: chain.truncated, componentChain: !!(owner && owner.chain && owner.chain.length > 32), breadcrumbs: crumbs.length >= 30, locations: f.some(t => path(t.url).length > 1024), mapping: false }, mapping: { status: opts.maps ? 'pending' : 'disabled' }, crumbs: crumbs.map(c => ({ ...c })),
+      build: clean(opts.build || '', 200) || null, ua: G.navigator ? clean(navigator.userAgent, 300) : null, at: Date.now(), last: Date.now(), n: 1,
     }
+    boundRecord(r)
     errors.push(r)
     if (errors.length > 100) errors.shift()
-    if (opts.maps) toBrain(r, f)
+    if (opts.maps && enriching < 100) {
+      enriching++
+      const traces = [t, ...chain.entries.slice(0, r.causes.length)]
+      for (let i = 0; i < r.causes.length; i++) chain.entries[i].frames = r.causes[i].frames
+      toBrain(r, traces).finally(() => { enriching-- })
+    } else {
+      if (opts.maps) { r.mapping.status = 'limited'; r.truncated.mapping = true }
+      for (const item of chain.entries) delete item.rawFrames
+    }
     if (opts.report && G.navigator && navigator.sendBeacon && sent < (opts.max || 20)) sent++, navigator.sendBeacon(opts.report, JSON.stringify(r))
   }
   for (const s of sub) s(r)
-  if (opts.log !== false && G.console) console.error(e)
+  if (opts.log !== false) print(e, r.fp)
   return r
 }
 
@@ -200,7 +325,7 @@ export function capture(o = {}) {
     G.addEventListener('error', ev => record(ev.error || ev.message, null, 'onerror'))
     G.addEventListener('unhandledrejection', ev => record(ev.reason, null, 'promise'))
     G.addEventListener('popstate', () => crumb('nav', path(location.href)))
-    G.addEventListener('hashchange', () => crumb('nav', path(location.href) + location.hash))
+    G.addEventListener('hashchange', () => crumb('nav', path(location.href)))
   }
   const d = G.document
   if (d && d.addEventListener) {

package/brain-form.js

@@ -15,7 +15,7 @@
 // Unsaved changes (§41.5): `f.dirty` is true while values differ from the last saved ones (init, reset() or a successful
 // submit); leaving the page (client navigation or closing the tab) then asks first. No API.
 import { sig, fx, batch, untrack, _rt } from './brain.js'
-import { rule, check, msg } from './brain-schema.js'
+import { rule, check, checkText, checkScalar, msg } from './brain-schema.js'
 
 export { rule, check } // server.mjs validates posted forms with the same rules (§38)
 
@@ -41,9 +41,18 @@ if (globalThis.addEventListener && !globalThis.__brainDirtyHook) {
     for (const f of DIRTY) if (f.dirty && !f.busy) return void (e.preventDefault(), (e.returnValue = ''))
   })
 }
-const empty = v => v == null || v === '' || (Array.isArray(v) && !v.length)
+const empty = v => v == null || typeof v === 'string' && v.trim() === '' || Array.isArray(v) && !v.length
 const init0 = r => (r.list ? [] : r.t === 'bool' ? false : '')
-const out = (r, v) => (r.list ? v || [] : r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v)
+const out = (r, v) => {
+  if (r.list) {
+    if (!Array.isArray(v)) return []
+    if (r.t !== 'num') return v
+    const numbers = new Array(v.length)
+    for (let i = 0; i < v.length; i++) numbers[i] = Number(v[i])
+    return numbers
+  }
+  return r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v
+}
 
 // state left by the server: globalThis.__brainForms while it renders, or the page's #brain-forms JSON
 let SEEN
@@ -62,6 +71,46 @@ function posted(id) {
 }
 
 export function form(schema, o = {}) {
+  if (rule(schema).t !== 'obj') throw Error('form: schema must be a nested field object')
+  return createForm(schema, o, rule, check, remoteCheck)
+}
+// Compiler-only flat literal schema bytecode. Dynamic/public form() keeps the full parser.
+export function formStatic(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, remoteCheck)
+}
+export function formScalars(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, remoteCheck)
+}
+// Compiler-only options proven not to configure or dynamically install async checks.
+export function formStaticSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, null)
+}
+export function formScalarsSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, null)
+}
+function compiledForm(schema, o, types, validate, remote) {
+  if (remote === null && ('check' in o || 'validate' in o)) throw Error('form: invalid compiled synchronous options')
+  if (!schema || Object.getPrototypeOf(schema) !== Object.prototype || Object.keys(schema).length > 4096) throw Error('form: invalid compiled schema')
+  return createForm(schema, o, (value, key) => {
+    if (['__proto__', 'prototype', 'constructor'].includes(key) || !Array.isArray(value) || value.length !== 2 || !types.includes(value[0]) || typeof value[1] !== 'boolean') throw Error('form: invalid compiled schema')
+    return { t: value[0], req: value[1], list: false, min: null, max: null }
+  }, validate, remote)
+}
+// Only public/dynamic or check-configured forms retain this optional capability.
+function remoteCheck(o, x, checking) {
+  const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
+  if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
+  checking.v++
+  return Promise.resolve()
+    .then(() => c(v))
+    .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || msg('form.check_failed', 'Could not check this value.')))
+    .then(m => {
+      if (untrack(() => x.s.v) === v) x.e.v = m
+      return untrack(() => x.e.v)
+    })
+    .finally(() => checking.v--)
+}
+function createForm(schema, o, readRule, validateRule, remote) {
   const id = 'f' + ++seq, owner = I.owner() // aria effects are created later (in handlers) but live with the component
   const busy = sig(false), error = sig(''), shown = sig(0) // shown: bumped when touched set changes
   const checking = sig(0), saved = sig('') // async checks running · JSON of the last saved values
@@ -72,7 +121,7 @@ export function form(schema, o = {}) {
   function build(sch, base, init) {
     const v = {}, err = {}
     for (const k of Object.keys(sch)) {
-      const r = rule(sch[k]), path = base ? base + '.' + k : k
+      const r = readRule(sch[k], k), path = base ? base + '.' + k : k
       if (r.t === 'obj') {
         const sub = build(r.s, path, (init && init[k]) || {})
         Object.defineProperty(v, k, { enumerable: true, value: sub.v })
@@ -115,23 +164,9 @@ export function form(schema, o = {}) {
   const touch = x => {
     validate(x)
     if (!x.touched) (x.touched = true), shown.v++
-    remote(x)
-  }
-  // async check of one field (only when its own rule passes); resolves to its message
-  const remote = x => {
-    const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
-    if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
-    checking.v++
-    return Promise.resolve()
-      .then(() => c(v))
-      .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || msg('form.check_failed', 'Could not check this value.')))
-      .then(m => {
-        if (untrack(() => x.s.v) === v) x.e.v = m // a stale answer (the value changed meanwhile) is ignored
-        return untrack(() => x.e.v)
-      })
-      .finally(() => checking.v--)
+    if (remote) remote(o, x, checking)
   }
-  const validate = x => (x.e.v = untrack(() => check(x.r, x.s.v)))
+  const validate = x => (x.e.v = untrack(() => validateRule(x.r, x.s.v)))
   const fid = p => `${id}-${p.replace(/\./g, '-')}-err`
 
   // A form posted without JS (§38) comes back from the server with its values and messages: start from them, already
@@ -196,7 +231,7 @@ export function form(schema, o = {}) {
       return checking.v > 0
     },
     get ok() {
-      for (const x of F) if (check(x.r, x.s.v)) return false
+      for (const x of F) if (validateRule(x.r, x.s.v)) return false
       return true
     },
     id: path => fid(path),
@@ -244,8 +279,8 @@ export function form(schema, o = {}) {
       busy.v = true
       if (fm) fm.setAttribute('aria-busy', 'true') // assistive tech hears the form is working
       try {
-        if (o.check) {
-          await Promise.all(F.map(remote))
+        if (remote && o.check) {
+          await Promise.all(F.map(x => remote(o, x, checking)))
           first = F.find(x => untrack(() => x.e.v))
           if (first) return void (shown.v++, first.el && first.el.focus && first.el.focus())
         }

package/brain-hash.js

@@ -0,0 +1,17 @@
+// Web Crypto owns cryptography in browsers and Node. No hashing implementation is bundled.
+export async function hashText(value, algorithm = 'SHA-256') {
+  if (!['SHA-256', 'SHA-384', 'SHA-512'].includes(algorithm)) throw RangeError('hashText: SHA-256, SHA-384 or SHA-512 required')
+  if (typeof value !== 'string') throw TypeError('hashText: text input required')
+  if (value.length > 8388608) throw RangeError('hashText: input exceeds 8 MiB')
+  const bytes = new TextEncoder().encode(value)
+  if (bytes.byteLength > 8388608) throw RangeError('hashText: UTF-8 input exceeds 8 MiB')
+  if (!globalThis.crypto?.subtle) throw Error('hashText: Web Crypto requires a secure browser context or Node 22+')
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(algorithm, bytes))
+  let hex = ''
+  for (let i = 0; i < digest.length; i++) hex += digest[i].toString(16).padStart(2, '0')
+  return hex
+}
+export async function shortHash(value, length = 32) {
+  if (!Number.isInteger(length) || length < 8 || length > 64) throw RangeError('shortHash: length must be 8..64 hex characters')
+  return (await hashText(value)).slice(0, length)
+}

package/brain-inspect.js

@@ -16,8 +16,8 @@ const now = () => Date.now()
 const pnow = () => (G.performance ? performance.now() : now())
 const syncHeap = () => (G.performance && performance.memory ? performance.memory.usedJSHeapSize : G.process && process.memoryUsage ? process.memoryUsage().heapUsed : null)
 
-let out = [], seq = 0, opts = {}, started = false
-const push = r => out.push(r)
+let out = [], seq = 0, opts = {}, started = false, dropped = 0
+const push = r => { if (out.length >= 2000) { out.shift(); dropped++ } out.push(r) }
 
 // ---------- instance identity and current owner ----------
 const ids = new WeakMap()
@@ -612,6 +612,8 @@ export function tick() {
 export function drain() {
   if (!out.length) return null
   const m = { t: 'm', v: 2, seq: seq++, at: now(), d: out }
+  if (dropped) m.dropped = dropped
+  dropped = 0
   out = []
   if (opts.send) opts.send(JSON.stringify(m))
   return m
@@ -629,7 +631,7 @@ export function inspect(o) {
       else i = instOf(x)
       if (!i) return null
       const chain = []
-      for (let j = i; j; j = instOf(j.p)) chain.push(nameOf(j))
+      for (let j = i; j && chain.length < 33; j = instOf(j.p)) chain.push(nameOf(j))
       return { id: idOf(i), h: i.h, name: nameOf(i), file: (i.C && (i.C.f || (i.C.C && i.C.C.f))) || null, chain }
     },
     sigName,
@@ -643,7 +645,7 @@ export function inspect(o) {
     if (done) done.add(key)
     push({ k: 'chan', kind, name, role, id: i ? idOf(i) : null, h: i ? i.h : null, comp: i ? nameOf(i) : null })
   })
-  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, crumbs: r.crumbs, n: r.n, at: r.last }))
+  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, brainStack: r.brainStack || null, location: r.location, generatedLocation: r.generatedLocation, frames: r.frames, causes: r.causes, truncated: r.truncated, mapping: r.mapping, crumbs: r.crumbs, n: r.n, at: r.last }))
   patchTimers()
   patchGlobalListeners()
   patchHandlers()

package/brain-interop.js

@@ -0,0 +1,50 @@
+// Explicit foreign-DOM ownership. The adapter, SDK and any React runtime belong to the app.
+import { _rt, fx, untrack } from './brain.js'
+
+const I = _rt()
+
+// Call during component setup. Resolve the bound element only after insertion.
+// mount must synchronously return a cleanup function or { update?, destroy }.
+export function interop(element, adapter, props = {}, options = {}) {
+  const owner = I.owner()
+  if (!owner) throw Error('interop: call during component setup')
+  let alive = true, instance = null, pending = props, ready = false
+  const report = (error, phase) => {
+    if (typeof options.onError === 'function') options.onError(error, phase)
+    else I.oops(error, owner, 'interop:' + phase)
+  }
+  const destroy = () => {
+    if (!alive) return
+    alive = false
+    const old = instance
+    instance = null
+    if (old) try { old.destroy() } catch (error) { report(error, 'destroy') }
+  }
+  const controller = {
+    update(next) {
+      if (!alive) throw Error('interop: boundary has been destroyed')
+      pending = next
+      if (!ready) return
+      if (!instance || typeof instance.update !== 'function') throw Error('interop: adapter does not support updates')
+      try { untrack(() => instance.update(next)) } catch (error) { report(error, 'update') }
+    },
+    destroy,
+  }
+  // No SDK execution during SSR or prerender. Disposal still invalidates this controller.
+  fx(() => destroy)
+  if (globalThis.__brainSSR || globalThis.__brainRoute) return controller
+  queueMicrotask(() => {
+    if (!alive) return
+    try {
+      const el = typeof element === 'function' ? untrack(element) : element
+      if (!el || el.nodeType !== 1) throw Error('interop: expected a bound DOM element')
+      if (!adapter || typeof adapter.mount !== 'function') throw Error('interop: adapter.mount is required')
+      const result = untrack(() => adapter.mount(el, pending))
+      if (typeof result === 'function') instance = { destroy: result }
+      else if (result && typeof result.destroy === 'function' && typeof result.then !== 'function') instance = result
+      else throw Error('interop: mount must return cleanup or { update, destroy }; asynchronous mounts are unsupported')
+      ready = true
+    } catch (error) { report(error, 'mount') }
+  })
+  return controller
+}

package/brain-overlay.js

@@ -24,10 +24,21 @@ export function forLLM(d) {
     })
   if (d.fix) out.push(`fix: ${d.fix}`)
   if (d.brainStack) out.push('stack:', ...[].concat(d.brainStack))
+  if (d.location || d.frames || d.causes || d.rid) out.push('structured trace (development only):', JSON.stringify(traceOf(d)))
+  if (d.mapping?.status && d.mapping.status !== 'mapped') out.push('Location mapping is incomplete; do not treat generated coordinates as original source coordinates.')
+  out.push('Agent next steps: inspect the exact source revision, apply a focused change, run brain check --json, then reproduce the failing action. Record evidence with brain history and refresh brain quality.')
   if (d.file) out.push('brain check --json:', JSON.stringify((byFile.get(d.file) || [d]).map(({ snippet, ...x }) => x)))
   return out.join('\n')
 }
 
+function traceOf(d) {
+  return { schemaVersion: 1, requestId: d.rid || d.requestId || null, component: d.comp || null,
+    location: d.location || null, generatedLocation: d.generatedLocation || null,
+    mapping: d.mapping || null, truncated: d.truncated || null,
+    frames: Array.isArray(d.frames) ? d.frames.slice(0, 24) : [],
+    causes: Array.isArray(d.causes) ? d.causes.slice(0, 6) : [] }
+}
+
 function item(d, i) {
   const loc = d.file ? `${d.file}:${d.line || ''}${d.col ? ':' + d.col : ''}` : d.src || ''
   const snip = d.snippet && d.snippet.text
@@ -35,6 +46,7 @@ function item(d, i) {
     : ''
   return `<li class="${d.level === 'warning' || d.level === 'info' ? d.level : 'error'}"><p class="t"><b>${esc(d.code || 'Error')}</b> <span>${esc(loc)}</span></p>` +
     `<p>${esc(d.msg)}</p>${snip}${d.fix ? `<p class="fix">fix: ${esc(d.fix)}</p>` : ''}` +
+    `${d.location || d.frames || d.causes ? `<details><summary>Development trace and mapping</summary><pre>${esc(JSON.stringify(traceOf(d), null, 2))}</pre></details>` : ''}` +
     `<button type="button" data-copy="${i}">Copy for the LLM</button></li>`
 }
 

package/brain-preferences.js

@@ -0,0 +1,64 @@
+// Small public preferences only. Authentication belongs to HttpOnly server cookies, never Web Storage.
+const G = globalThis
+const privateName = /password|secret|token|authorization|sessionid|csrf|jwt|credit/i
+const valid = name => typeof name === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(name) && !privateName.test(name)
+const problem = fix => Object.assign(new Error(fix), { code: 'B0913', fix })
+
+export function storage(name, options = {}) {
+  if (!valid(name) || !valid(options.namespace || 'app')) throw problem('storage: use public preference names; keep authentication in server sessions')
+  if (options.scope && !['local', 'session'].includes(options.scope)) throw problem('storage: scope must be local or session')
+  const prefix = `brain:pref:${options.namespace || 'app'}:${name}:`, version = options.version || 1
+  const backend = () => {
+    let s
+    try { s = options.scope === 'session' ? G.sessionStorage : G.localStorage } catch {}
+    if (!s) throw problem('Web Storage is unavailable; use an in-memory preference or a server data source')
+    return s
+  }
+  const key = k => { if (!valid(k)) throw problem('storage: keys must be bounded public preference names'); return prefix + k }
+  const keys = s => {
+    if (s.length > 4096) throw problem('storage: origin contains too many keys; reduce stored preferences')
+    const result = []
+    for (let i = 0; i < s.length; i++) { const k = s.key(i); if (k?.startsWith(prefix)) result.push(k) }
+    return result
+  }
+  return {
+    get(k, fallback = null) {
+      const s = backend(), raw = s.getItem(key(k))
+      if (raw == null) return fallback
+      if (raw.length > 8192) throw problem('storage: preference exceeds 8 KiB; use database() for structured data')
+      let r; try { r = JSON.parse(raw) } catch { throw problem('storage: malformed preference; explicitly delete or replace this key') }
+      return r?.v === version ? r.data : fallback
+    },
+    set(k, value) {
+      const s = backend(), target = key(k)
+      let raw
+      try { raw = JSON.stringify({v:version,data:value}); if (value === undefined) throw Error() } catch { throw problem('storage: values must be JSON-serializable') }
+      if (new TextEncoder().encode(raw).length > 8192) throw problem('storage: preference exceeds 8 KiB; use database() for structured data')
+      const existing = keys(s)
+      if (existing.length >= 128 && !existing.includes(target)) throw problem('storage: namespace exceeds 128 preference keys')
+      let total = new TextEncoder().encode(raw).length
+      for (const name of existing) if (name !== target) total += new TextEncoder().encode(s.getItem(name) || '').length
+      if (total > 65536) throw problem('storage: namespace exceeds 64 KiB; move structured data to database()')
+      try { s.setItem(target, raw) } catch { throw problem('storage: write failed or quota exceeded; reduce stored preferences') }
+    },
+    delete(k) { backend().removeItem(key(k)) },
+    clear() { const s = backend(); for (const k of keys(s)) s.removeItem(k) },
+  }
+}
+
+export function cookie(name, value, options = {}) {
+  if (!valid(name)) throw problem('cookie: use a public preference name; authentication cookies belong to the backend')
+  if (!G.document) throw problem('cookie: browser document unavailable; use ctx.cookies on the server')
+  const key = `brain_pref_${name}`
+  if (value === undefined) {
+    const matches = G.document.cookie.split(';').map(x => x.trim()).filter(x => x.startsWith(key + '='))
+    if (matches.length !== 1) return null
+    try { return decodeURIComponent(matches[0].slice(key.length + 1)) } catch { return null }
+  }
+  const encoded = value === null ? '' : encodeURIComponent(String(value))
+  if (encoded.length > 2048) throw problem('cookie: preferences must be at most 2 KiB; use database() for larger data')
+  const age = value === null ? 0 : options.maxAge ?? 2592000
+  if (!Number.isSafeInteger(age) || age < 0 || age > 31536000) throw problem('cookie: maxAge must be between zero and one year in seconds')
+  G.document.cookie = `${key}=${encoded}; Path=/; Secure; SameSite=Lax; Max-Age=${age}`
+  return value
+}