@christianirack/brainllm-runtime 0.0.0-stage → 0.3.1

package/brain-island.js

@@ -0,0 +1,106 @@
+// BRAINLLM islands (SPEC §6.1). A prerendered island is its root element (`data-b`) followed by
+// `<script type="b/state">{"c": chunk, "x": export, "p": props}</script>`. hydrate() listens on the document:
+// intent (pointerdown, focusin, keydown) only preloads the chunk and lets the native event act on the prerendered DOM,
+// so typing and the press that starts a click are never lost. The first real event (click, submit, input, change)
+// mounts the island in place, carrying over what the user already did there (values, checked, focus and caret), and
+// replays that event once on the live node.
+// No import of the core: brain.js loads this module with import() and passes { mount, _rt } (a static import back
+// would make a cycle that content-hashed chunks cannot name).
+import { adopter } from './brain-hydrate.js' // no imports of its own: no hash cycle
+
+let mount, I
+const load = (el, s) => el.$m || (el.$m = import(new URL(JSON.parse(s.textContent).c, document.baseURI).href).catch(_cf))
+const at = (n, path) => {
+  for (const i of path) n = n && n.childNodes[i]
+  return n
+}
+const pathOf = (n, root, a = []) => {
+  for (; n && n !== root; n = n.parentNode) a.unshift([].indexOf.call(n.parentNode.childNodes, n))
+  return n ? a : null
+}
+async function resume(el, s) {
+  const { c, x = 'default', p = {} } = JSON.parse(s.textContent)
+  const m = await load(el, s)
+  // #285: a server render stamped for adoption (data-hk) resumes on its own nodes: nothing is replaced, so internal
+  // scroll, a playing video, focus and animations survive. Any mismatch falls back to rendering fresh below.
+  if (el.getAttribute('data-hk') && I.adopt) {
+    let d = null
+    try {
+      I.adopt(adopter(el))
+      const ns = I.root(z => ((d = z), I.nodes(m[x](p))), null)
+      if (ns[0] !== el) throw Error('adopt: another root')
+      I.adopt(null)
+      I.dev(null, c)
+      el.$d = d // the router disposes islands it swaps out
+      s.remove()
+      return el
+    } catch {
+      I.adopt(null)
+      if (d) d()
+    }
+  }
+  const f = document.createDocumentFragment()
+  const d = mount(m[x], f, p)
+  I.dev(null, c) // dev: hydrate event for brain-inspect
+  // dev: the prerendered HTML and the first client render must match (B0214, §31): else the page flashes on resume
+  if (globalThis.__brainDev && f.firstChild) {
+    const norm = h => h.replace(/<!--[\s\S]*?-->/g, '').replace(/>\s+</g, '><').replace(/\s+(data-b|nonce)="[^"]*"/g, '').trim()
+    const a0 = norm(el.outerHTML), b0 = norm(f.firstChild.outerHTML)
+    if (a0 !== b0) {
+      let i = 0
+      while (a0[i] === b0[i]) i++
+      console.warn(Object.assign(Error(`B0214: ${c} renders differently on the client than in the prerendered HTML near: server "${a0.slice(Math.max(0, i - 20), i + 40)}" · client "${b0.slice(Math.max(0, i - 20), i + 40)}"`), { code: 'B0214' }))
+    }
+  }
+  const n = f.firstChild, q = 'input,select,textarea', a = el.querySelectorAll(q), b = n.querySelectorAll(q)
+  for (let i = 0; i < a.length && i < b.length; i++)
+    /^(checkbox|radio)$/.test(a[i].type) ? (b[i].checked = a[i].checked) : a[i].value !== b[i].value && (b[i].value = a[i].value)
+  const act = document.activeElement, fp = act && el.contains(act) && pathOf(act, el)
+  n.$d = d // the router disposes islands it swaps out
+  el.replaceWith(f)
+  s.remove()
+  const g = fp && at(n, fp)
+  if (g && g.focus) {
+    g.focus({ preventScroll: true })
+    try {
+      g.setSelectionRange(act.selectionStart, act.selectionEnd, act.selectionDirection)
+    } catch {}
+  }
+  return n
+}
+// A chunk that cannot be imported (deleted by a newer deploy) reloads the page once per build, never in a loop.
+export function _cf(e) {
+  const b = document.querySelector('meta[name=brain-build]'), k = 'brain:reload:' + (b ? b.getAttribute('content') : '')
+  try {
+    if (!sessionStorage.getItem(k)) sessionStorage.setItem(k, 1), location.reload()
+  } catch {}
+  throw e
+}
+export function hydrate(r = document, rt) {
+  ;({ mount } = rt)
+  I = rt._rt()
+  if (r.$h) return // idempotent: the router re-runs page scripts on every navigation
+  r.$h = 1
+  for (const t of ['click', 'submit', 'input', 'change', 'pointerdown', 'focusin', 'keydown'])
+    r.addEventListener(
+      t,
+      e => {
+        const path = []
+        let el = e.target, s
+        for (; el && el.nodeType === 1; el = el.parentNode) {
+          s = el.nextSibling
+          if (s && s.type === 'b/state' && el.hasAttribute('data-b')) break
+          path.unshift([].indexOf.call(el.parentNode.childNodes, el))
+        }
+        if (!el || el.nodeType !== 1) return
+        if ('pointerdown focusin keydown'.includes(t)) return void load(el, s) // intent: preload only, the native event goes on
+        e.preventDefault()
+        e.stopPropagation()
+        ;(el.$b || (el.$b = resume(el, s))).then(
+          n => (n = at(n, path)) && n.dispatchEvent(new e.constructor(t, e)),
+          x => I.oops(x, null, 'island') // reported once to the catcher, never an unhandled rejection
+        )
+      },
+      true
+    )
+}

package/brain-lazy.js

@@ -0,0 +1,88 @@
+// BRAINLLM lazy components (INTERNALS §22): `<Chart lazy />` (visible), `lazy="idle"`, `lazy="interaction"`.
+// The codegen renders a placeholder element in the template (its fallback content, or an empty sized box) and emits
+// `lazy(el, () => import('/_b/<h>'), mode, $props)`. When the trigger fires, the chunk is imported and the component
+// is built under the owner that called lazy (context, disposal and the error catcher work as if it were inline);
+// its nodes replace the placeholder. If the owner is disposed first, the trigger is cancelled; afterwards, the
+// component is disposed with it. An import failure is reported (reportError → brain-err) and the placeholder stays.
+// `el.$l` is the load promise (prefetch: `el.$l || el.$go()`).
+import { _rt, fx } from './brain.js'
+
+const G = globalThis
+const I = _rt()
+const ACT = ['pointerover', 'pointerdown', 'focusin', 'touchstart', 'click', 'keydown']
+// A chunk deleted by a newer deploy: reload the page once per build (sessionStorage guard), never in a loop (§35.7).
+function reloadOnce() {
+  try {
+    const b = document.querySelector('meta[name=brain-build]'), k = 'brain:reload:' + (b ? b.getAttribute('content') : '')
+    if (sessionStorage.getItem(k)) return false
+    sessionStorage.setItem(k, 1)
+    location.reload()
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function lazy(el, imp, mode, props = {}) {
+  const owner = I.owner()
+  let dead = false, stop = () => {}, retry = () => {}, clicked = null, built
+  const go = () => {
+    if (dead) return
+    stop()
+    el.setAttribute('aria-busy', 'true')
+    return (el.$l ||= Promise.resolve()
+      .then(imp)
+      .then(m => {
+        if (dead) return
+        const C = (m && m.default) || m
+        built = I.root(() => I.nodes(C(props)), owner) // adopted by owner: disposed with it
+        el.replaceWith(...built)
+        // the click that triggered the load landed on the placeholder: replay it on the real component
+        const t = clicked && built.find(n => n.nodeType === 1)
+        if (t) t.dispatchEvent(new clicked.constructor('click', clicked))
+        return built
+      })
+      .catch(e => {
+        el.$l = null
+        if (dead) return
+        el.setAttribute('aria-busy', 'false')
+        retry()
+        if (!reloadOnce()) G.reportError ? reportError(e) : queueMicrotask(() => { throw e })
+      }))
+  }
+  el.$go = go
+  if (mode === 'idle') {
+    if (G.requestIdleCallback) {
+      const h = requestIdleCallback(go, { timeout: 2000 })
+      stop = () => cancelIdleCallback(h)
+    } else {
+      const h = setTimeout(go, 1)
+      stop = () => clearTimeout(h)
+    }
+  } else if (mode === 'interaction') {
+    const f = e => {
+      if (e.type === 'keydown') {
+        if (e.key !== 'Enter' && e.key !== ' ') return
+        e.preventDefault()
+      }
+      if (e.type === 'click') (clicked = e), e.preventDefault(), e.stopPropagation()
+      go()
+    }
+    retry = () => { for (const t of ACT) el.addEventListener(t, f, t === 'click') }
+    retry()
+    stop = () => {
+      for (const t of ACT) el.removeEventListener(t, f, t === 'click')
+    }
+  } else if (G.IntersectionObserver) {
+    const io = new IntersectionObserver(es => es.some(e => e.isIntersecting) && go(), { rootMargin: '200px' })
+    io.observe(el)
+    stop = () => io.disconnect()
+  } else go()
+  if (owner)
+    fx(() => () => {
+      dead = true
+      stop()
+      if (built) I.rm(built)
+    })
+  return el
+}

package/brain-mcp.js

@@ -0,0 +1,73 @@
+// BRAINLLM agent tools (WebMCP, INTERNALS §32). A component exposes functions to the browser's AI agent:
+//   tool('search_products', 'Search the catalog by text', { q: 'str!', max: 'num<=50' }, ({ q, max }) => …)
+// Registered when the component mounts, unregistered when it unmounts; a no-op where the browser has no model context
+// (feature-detected: document.modelContext, the newer name, or navigator.modelContext, Chrome's origin trial). The
+// parameters use form()'s mini-language and become a JSON Schema; arguments are validated before `run` is called and
+// a bad call answers with the field's message instead of running. Tools act with the page's permissions only:
+// anything destructive should still ask for confirmation in the UI.
+// Optional 5th argument (WebMCP draft 2026-10-27): { title, readOnly, consequential, untrusted } → `title` and
+// `annotations: { readOnlyHint, consequentialHint, untrustedContentHint }` on the registration; only the keys given.
+import { fx } from './brain.js'
+import { rule, check } from './brain-schema.js'
+
+const G = globalThis
+export const context = () => (G.document && G.document.modelContext) || (G.navigator && G.navigator.modelContext) || null
+
+const TYPE = { str: 'string', email: 'string', url: 'string', date: 'string', num: 'number', bool: 'boolean' }
+// { q: 'str!', tags: '[str]' } → JSON Schema (object, properties, required)
+export function schema(params = {}) {
+  const properties = {}, required = []
+  for (const [k, src] of Object.entries(params)) {
+    const r = rule(src), item = { type: TYPE[r.t] || 'string' }
+    if (r.t === 'email') item.format = 'email'
+    if (r.t === 'url') item.format = 'uri'
+    if (r.t === 'date') item.format = 'date'
+    if (r.t === 'num' && r.min != null) item.minimum = r.min
+    if (r.t === 'num' && r.max != null) item.maximum = r.max
+    if (r.t === 'str' && r.min != null) item.minLength = r.min
+    if (r.t === 'str' && r.max != null) item.maxLength = r.max
+    properties[k] = r.list ? { type: 'array', items: item } : item
+    if (r.req) required.push(k)
+  }
+  return { type: 'object', properties, required }
+}
+
+const text = v => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v ?? null) }] })
+
+const HINTS = [['readOnly', 'readOnlyHint'], ['consequential', 'consequentialHint'], ['untrusted', 'untrustedContentHint']]
+
+// The registration dictionary: name, description, inputSchema, then title/annotations only when given.
+export function definition(name, description, params, opts) {
+  const def = { name, description, inputSchema: schema(params) }
+  if (!opts) return def
+  if (typeof opts.title === 'string' && opts.title) def.title = opts.title
+  let annotations = null
+  for (let i = 0; i < HINTS.length; i++) {
+    const v = opts[HINTS[i][0]]
+    if (v != null) (annotations || (annotations = {}))[HINTS[i][1]] = !!v
+  }
+  if (annotations) def.annotations = annotations
+  return def
+}
+
+export function tool(name, description, params, run, opts) {
+  const mc = context()
+  if (!mc || !mc.registerTool || G.__brainSSR || G.__brainRoute) return
+  const rules = Object.fromEntries(Object.entries(params || {}).map(([k, s]) => [k, rule(s)]))
+  fx(() => {
+    const def = definition(name, description, params, opts)
+    def.execute = async (args = {}) => {
+      for (const k in rules) {
+        const m = check(rules[k], args[k])
+        if (m) return text(`${k}: ${m}`)
+      }
+      try {
+        return text(await run(args))
+      } catch (e) {
+        return text(`Error: ${(e && e.message) || e}`)
+      }
+    }
+    const reg = mc.registerTool(def)
+    return () => (reg && reg.unregister ? reg.unregister() : mc.unregisterTool && mc.unregisterTool(name))
+  })
+}

package/brain-mock.js

@@ -0,0 +1,80 @@
+// BRAINLLM fake data (brain run --mock, INTERNALS §15, #159). Development only: brain-data never imports it, so no page
+// in production carries it. `fake(schema, seed)` → data that matches an api() schema (form()'s mini-language, nested
+// objects, [Schema] lists), deterministic: the same schema and seed give the same JSON on any machine. Field names steer
+// the values (email, name, title, city, url, phone, price, date, id…) so screens look real; bounds and required hold.
+// `mocker(seed)` is what `http({ mock })` takes: the same seed and URL give the same answer; a write answers its input
+// merged over a fake `out`. TOOLCHAIN #266 wires it: `http({ mock: mocker(seed) })`.
+import { rule } from './brain-schema.js'
+
+const hashOf = s => {
+  let h = 2166136261
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 16777619)
+  return h >>> 0
+}
+const prng = seed => {
+  let a = hashOf(seed)
+  return () => {
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+const FIRST = ['Ada', 'Grace', 'Linus', 'Margaret', 'Alan', 'Barbara', 'Ken', 'Radia', 'Dennis', 'Frances', 'Tim', 'Katherine']
+const LAST = ['Lovelace', 'Hopper', 'Torvalds', 'Hamilton', 'Turing', 'Liskov', 'Thompson', 'Perlman', 'Ritchie', 'Allen', 'Berners-Lee', 'Johnson']
+const WORDS = ['quiet', 'bright', 'river', 'signal', 'garden', 'orbit', 'paper', 'stone', 'harbor', 'window', 'field', 'summer', 'north', 'cedar', 'lantern', 'meadow']
+const CITIES = ['Lisbon', 'Kyoto', 'Montreal', 'Oslo', 'Puebla', 'Cape Town', 'Melbourne', 'Lima', 'Seoul', 'Vienna']
+function fakeField(r, key, rnd, i, who) {
+  const k = String(key || '').toLowerCase(), pick = a => a[Math.floor(rnd() * a.length)]
+  const words = n => Array.from({ length: n }, () => pick(WORDS)).join(' ')
+  const cap = w => w.charAt(0).toUpperCase() + w.slice(1)
+  if (r.t === 'bool') return rnd() < 0.5
+  if (r.t === 'num') {
+    const lo = r.min ?? (/(^|_)id$|count|qty|quantity|age/.test(k) ? 1 : 0), hi = r.max ?? (/age/.test(k) ? 90 : /price|amount|total|cost/.test(k) ? 500 : /(^|_)id$/.test(k) ? 10000 : 100)
+    if (/(^|_)id$/.test(k) && i != null) return i + 1 // ids of a list are unique and stable
+    const v = lo + rnd() * (hi - lo)
+    return /price|amount|total|cost|rate/.test(k) ? Math.round(v * 100) / 100 : Math.round(v)
+  }
+  if (r.t === 'date') return new Date(Date.UTC(2026, 0, 1) + Math.floor(rnd() * 365) * 864e5).toISOString().slice(0, 10)
+  const { first, last } = who || { first: pick(FIRST), last: pick(LAST) } // one person per object: name and email agree
+  let v
+  if (r.t === 'email' || /email/.test(k)) v = `${first}.${last}`.toLowerCase().replace(/[^a-z.]/g, '') + '@example.com'
+  else if (r.t === 'url' || /url|link|website|href/.test(k)) v = `https://example.com/${pick(WORDS)}`
+  else if (/(^|_)id$|slug/.test(k)) v = (i != null ? `${pick(WORDS)}-${i + 1}` : `${pick(WORDS)}-${Math.floor(rnd() * 1000)}`)
+  else if (/^name$|full_?name|author|user/.test(k)) v = `${first} ${last}`
+  else if (/first/.test(k)) v = first
+  else if (/last|surname/.test(k)) v = last
+  else if (/city|town/.test(k)) v = pick(CITIES)
+  else if (/phone|tel/.test(k)) v = `+1 555 01${String(Math.floor(rnd() * 100)).padStart(2, '0')}`
+  else if (/title|subject|headline/.test(k)) v = cap(words(3))
+  else if (/body|text|content|description|summary|bio|note/.test(k)) v = cap(words(12)) + '.'
+  else if (/color|colour/.test(k)) v = '#' + Math.floor(rnd() * 0xffffff).toString(16).padStart(6, '0')
+  else if (/status|state/.test(k)) v = pick(['active', 'pending', 'done'])
+  else v = cap(words(2))
+  if (r.max != null && v.length > r.max) v = v.slice(0, r.max).trim()
+  if (r.min != null && v.length < r.min) v = v.padEnd(r.min, 'x')
+  return v
+}
+function gen(s, key, rnd, i, who) {
+  if (Array.isArray(s)) return Array.from({ length: 3 + Math.floor(rnd() * 4) }, (_, j) => gen(s[0], key, rnd, j))
+  if (s && typeof s === 'object') {
+    const o = {}, me = { first: FIRST[Math.floor(rnd() * FIRST.length)], last: LAST[Math.floor(rnd() * LAST.length)] }
+    for (const k of Object.keys(s)) o[k] = gen(s[k], k, rnd, i, me)
+    return o
+  }
+  let r
+  try {
+    r = rule(s)
+  } catch {
+    return null // a type name the compiler could not resolve: nothing to imitate
+  }
+  if (r.t === 'obj') return gen(r.s, key, rnd, i)
+  if (r.list) return Array.from({ length: Math.max(r.min || 0, 3) }, (_, j) => fakeField(r, key, rnd, j, who))
+  return fakeField(r, key, rnd, i, who)
+}
+export const fake = (schema, seed = 'brain') => gen(schema, '', prng(String(seed)), null)
+
+export const mocker = (seed = 'brain') => (method, url, def, body) => {
+  const out = def && def.out ? fake(def.out, seed + ' ' + method + ' ' + url) : null
+  return method === 'GET' || !out || typeof out !== 'object' || Array.isArray(out) ? out : { ...out, ...body }
+}

package/brain-overlay.js

@@ -0,0 +1,123 @@
+// BRAINLLM dev overlay (INTERNALS §20, #267). Development only: the dev client (crates/brain-serve/src/client.js)
+// imports it; no page in production does. What it shows:
+// - errors (a file that does not compile, or a runtime error from brain-err): a panel at the bottom that does not cover
+//   the page, with the code, the snippet with the line marked, the fix and "Copy for the LLM";
+// - warnings and info: a chip in a corner ("3 warnings") that opens the same list.
+// API (format agreed with TOOLCHAIN #47): show(diags, { file }) replaces the diagnostics of that file (an empty list =
+// it compiles again) · error(record) adds a runtime error (brain-err: { code, msg, src, brainStack }) · clear().
+// A diagnostic has the shape of `brain check --json` plus `snippet: { line, text: [...] }` (a few lines around `line`).
+const G = globalThis
+const byFile = new Map() // file → diagnostics
+let runtime = [] // runtime errors, newest last
+let host = null, root = null, open = false
+
+const esc = s => String(s ?? '').replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
+const all = () => [...byFile.values()].flat()
+
+// The text a model needs to fix it without opening anything else: location, message, snippet, fix and the JSON
+export function forLLM(d) {
+  const out = [`${d.code} ${d.file || d.src || ''}${d.line ? `:${d.line}${d.col ? ':' + d.col : ''}` : ''} (${d.level || 'error'})`, d.msg]
+  if (d.snippet && d.snippet.text)
+    d.snippet.text.forEach((t, i) => {
+      const n = d.snippet.line + i
+      out.push(`${n === d.line ? '>' : ' '} ${String(n).padStart(4)} | ${t}`)
+    })
+  if (d.fix) out.push(`fix: ${d.fix}`)
+  if (d.brainStack) out.push('stack:', ...[].concat(d.brainStack))
+  if (d.file) out.push('brain check --json:', JSON.stringify((byFile.get(d.file) || [d]).map(({ snippet, ...x }) => x)))
+  return out.join('\n')
+}
+
+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
+    ? `<pre class="snip">${d.snippet.text.map((t, j) => `<span class="${d.snippet.line + j === d.line ? 'hit' : ''}">${String(d.snippet.line + j).padStart(4)} │ ${esc(t)}</span>`).join('\n')}</pre>`
+    : ''
+  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>` : ''}` +
+    `<button type="button" data-copy="${i}">Copy for the LLM</button></li>`
+}
+
+function render() {
+  const d = G.document
+  if (!d || !d.body) return
+  const list = [...all(), ...runtime.map(r => ({ level: 'error', ...r }))]
+  const errors = list.filter(x => x.level !== 'warning' && x.level !== 'info'), notes = list.filter(x => x.level === 'warning' || x.level === 'info')
+  if (!list.length) {
+    if (host) host.remove()
+    return
+  }
+  if (!host) {
+    host = d.createElement('brain-overlay')
+    root = host.attachShadow ? host.attachShadow({ mode: 'open' }) : host
+    root.addEventListener('click', e => {
+      let b = e.target
+      while (b && b.tagName !== 'BUTTON') b = b.parentNode
+      if (!b) return
+      if (b.hasAttribute('data-chip')) return void ((open = !open), render())
+      const x = shown[+b.getAttribute('data-copy')]
+      if (x) copy(forLLM(x), b)
+    })
+  }
+  const panel = errors.length || open
+  shown = panel ? (errors.length ? [...errors, ...(open ? notes : [])] : notes) : []
+  root.innerHTML = `<style>${CSS}</style>` +
+    (panel ? `<section class="panel" role="alert" aria-label="Problems"><ul>${shown.map(item).join('')}</ul></section>` : '') +
+    (notes.length ? `<button type="button" class="chip" data-chip aria-expanded="${open}">${notes.length} ${notes.length === 1 ? 'warning' : 'warnings'}</button>` : '')
+  if (!host.isConnected) d.body.appendChild(host)
+}
+let shown = []
+
+function copy(text, btn) {
+  const done = () => ((btn.textContent = 'Copied'), setTimeout(() => (btn.textContent = 'Copy for the LLM'), 1500))
+  const nav = G.navigator
+  if (nav && nav.clipboard && nav.clipboard.writeText) nav.clipboard.writeText(text).then(done, () => {})
+  else done()
+  G.__brainOverlayCopied = text // tests and tools read what was copied
+}
+
+export function show(diags, o = {}) {
+  // show(all, 'comp/x.brain') (the dev client) or show(all, { file })
+  const file = (typeof o === 'string' ? o : o.file) || (diags[0] && diags[0].file) || ''
+  if (diags.length) byFile.set(file, diags)
+  else byFile.delete(file)
+  render()
+}
+export function error(r) {
+  if (!r) return
+  // the same error again (brain-err notifies twice: once more when the source map resolves) merges into the first
+  const same = x => x.code === r.code && x.msg === r.msg && x.src === r.src
+  const old = runtime.find(same)
+  runtime = [...runtime.filter(x => !same(x)), { ...old, ...Object.fromEntries(Object.entries(r).filter(([, v]) => v != null)) }].slice(-20)
+  render()
+}
+export function clear() {
+  byFile.clear()
+  runtime = []
+  open = false
+  render()
+}
+
+const CSS = `
+:host,.panel,.chip{all:initial}
+.panel{position:fixed;left:12px;right:12px;bottom:12px;max-height:45vh;overflow:auto;z-index:2147483647;padding:14px 18px;
+ border-radius:14px;background:rgba(22,22,26,.95);color:#f3f3f5;font:13px/1.5 ui-sans-serif,system-ui,sans-serif;
+ box-shadow:0 1px 2px rgba(0,0,0,.2),0 18px 40px -12px rgba(0,0,0,.45)}
+ul{margin:0;padding:0;list-style:none;display:grid;gap:14px}
+li{border-left:3px solid #ff6b5f;padding-left:12px}
+li.warning{border-color:#f5b54a}
+li.info{border-color:#6aa8ff}
+p{margin:2px 0}
+.t b{color:#ff8a80}
+li.warning .t b{color:#f5b54a}
+.t span{color:#b4b4bd;font:12px ui-monospace,monospace}
+.snip{margin:6px 0;padding:8px 10px;border-radius:8px;background:rgba(255,255,255,.06);font:12px/1.45 ui-monospace,monospace;overflow:auto;white-space:pre}
+.snip .hit{background:rgba(255,107,95,.22);display:inline-block;min-width:100%}
+.fix{color:#9fe0b0}
+button{font:12px ui-sans-serif,system-ui,sans-serif;margin-top:6px;padding:4px 10px;border-radius:8px;border:1px solid rgba(255,255,255,.2);
+ background:rgba(255,255,255,.08);color:#f3f3f5;cursor:pointer}
+.chip{position:fixed;right:16px;bottom:16px;z-index:2147483647;padding:6px 12px;border-radius:999px;border:0;cursor:pointer;
+ font:600 12px ui-sans-serif,system-ui,sans-serif;color:#1a1a1a;background:#f5b54a;box-shadow:0 6px 18px -6px rgba(0,0,0,.35)}
+.panel ~ .chip{top:16px;bottom:auto}
+@media (prefers-reduced-motion:no-preference){button{transition:background .15s}}
+`

package/brain-persist.js

@@ -0,0 +1,65 @@
+// BRAINLLM store persistence (INTERNALS §35.4), loaded on demand by `store(init, { persist: true })` (brain-ch.js).
+// brain-ch restores small states from localStorage synchronously; this module restores large ones from IndexedDB and
+// writes every change (debounced 100 ms): below 4 KB to localStorage, above to IndexedDB with a marker in localStorage.
+// Records carry the shape version `v`; another shape is discarded. Quota or private-mode errors switch that store to
+// memory and are reported once (reportError → brain-err), never thrown.
+import { _rt, fx } from './brain.js'
+
+const G = globalThis, I = _rt(), LIMIT = 4096, WAIT = 100
+let warned = false
+const report = e => {
+  if (warned) return
+  warned = true
+  const x = Object.assign(new Error('persist: ' + ((e && e.message) || e) + '; the store stays in memory'), { code: 'persist', cause: e })
+  G.reportError ? G.reportError(x) : console.warn(x.message)
+}
+
+let dbp = null
+const req = r => new Promise((ok, fail) => ((r.onsuccess = () => ok(r.result)), (r.onerror = () => fail(r.error))))
+const db = () =>
+  (dbp ||= new Promise((ok, fail) => {
+    const r = G.indexedDB.open('brain', 1)
+    r.onupgradeneeded = () => r.result.createObjectStore('kv')
+    r.onsuccess = () => ok(r.result)
+    r.onerror = () => fail(r.error)
+  }).catch(e => ((dbp = null), Promise.reject(e))))
+const idb = async (mode, f) => req(f((await db()).transaction('kv', mode).objectStore('kv')))
+
+export async function persist({ key, v, big, apply, snap, S, base }) {
+  let mem = false, last = base
+  if (big)
+    try {
+      const r = G.indexedDB ? await idb('readonly', s => s.get(key)) : null
+      if (r && r.v === v) apply(r.d), (last = JSON.stringify(snap()))
+    } catch (e) {
+      report(e)
+    }
+  let t = null, inIdb = big
+  const write = async j => {
+    if (mem) return
+    try {
+      if (j.length < LIMIT || !G.indexedDB) {
+        G.localStorage.setItem(key, `{"v":${JSON.stringify(v)},"d":${j}}`)
+        if (inIdb) (inIdb = false), await idb('readwrite', s => s.delete(key))
+      } else {
+        await idb('readwrite', s => s.put({ v, d: JSON.parse(j) }, key))
+        inIdb = true
+        G.localStorage.setItem(key, JSON.stringify({ v, idb: 1 }))
+      }
+    } catch (e) {
+      mem = true
+      report(e)
+    }
+  }
+  I.root(() =>
+    fx(() => {
+      const d = {}
+      for (const k in S) d[k] = S[k].v // tracks every field
+      const j = JSON.stringify(d)
+      if (j === last) return
+      last = j
+      clearTimeout(t)
+      t = setTimeout(() => write(last), WAIT)
+    })
+  )
+}