@christianirack/brainllm-runtime 0.0.0-stage → 0.1.0

package/brain-why.js

@@ -0,0 +1,198 @@
+// BRAINLLM update provenance (INTERNALS §43.2-§43.1, #198). Development only: the dev client loads it next to
+// brain-dev.js; nothing ships to production and the core carries no hook for it.
+// - why(selector | node) → for a node that updated: which signal write caused each change (component, field,
+//   `file.brain:line` of the write) and the chain of drv between them. MCP `brain_why` (TOOLCHAIN #200) calls it
+//   through globalThis.__brainWhy.
+// - interactions() → per user interaction (click, input, change, keydown, submit): how many DOM mutations it caused
+//   and on how many nodes, for the impact report (`brain_impact`, "updates per interaction").
+// How: it wraps, in dev only, the signal setter (records the write and its stack), the node run (an effect run
+// knows, before it re-runs, which of its sources were written: those are its causes) and the DOM write methods
+// (each mutation made while an effect runs is attributed to that effect's causes).
+import { sig } from './brain.js'
+import { names, mounts as M } from './brain-dev.js'
+
+const G = globalThis
+const N = sig(0).constructor, P = N.prototype
+const KEEP = 10, LAST = 50
+const WR = new Map() // sig → write record, for the current flush (cleared once it settles)
+const BY = new WeakMap() // node → [mutation records], newest first
+const INT = [] // last interactions
+let RUN = null // causes of the effect running now
+let cur = null // interaction being measured
+let clearing = 0
+
+// ---------- signal writes ----------
+const vd = Object.getOwnPropertyDescriptor(P, 'v')
+Object.defineProperty(P, 'v', {
+  configurable: true,
+  get: vd.get,
+  set(x) {
+    if (!this.f && !Object.is(x, this._)) {
+      const info = names.get(this)
+      WR.set(this, { sig: this, name: (info && info.name) || null, comp: (info && info.comp) || null, from: this._, to: x, stack: new Error().stack || '' })
+      if (!clearing) (clearing = 1), setTimeout(() => ((clearing = 0), WR.clear()), 0) // after the flush microtasks
+    }
+    vd.set.call(this, x)
+  },
+})
+
+// causes of a node's next run: its sources that were written, or reached through a drv chain
+function causesOf(n, via = [], seen = new Set()) {
+  const out = [], S = n.S
+  if (!S) return out
+  for (let i = 0; i < S.length; i += 2) {
+    const s = S[i]
+    if (seen.has(s)) continue
+    seen.add(s)
+    const w = WR.get(s)
+    if (w) out.push({ w, via })
+    else if (s.f && !s.e) out.push(...causesOf(s, [...via, (names.get(s) && names.get(s).name) || 'drv'], seen))
+  }
+  return out
+}
+const r0 = P.r
+P.r = function () {
+  if (!this.e || !WR.size) return r0.call(this)
+  const prev = RUN
+  RUN = causesOf(this)
+  try {
+    return r0.call(this)
+  } finally {
+    RUN = prev
+  }
+}
+
+// ---------- DOM writes ----------
+function note(node, kind) {
+  if (!node || !RUN || !RUN.length) return
+  const rec = { kind, t: Date.now(), causes: RUN }
+  for (const n of node.nodeType === 3 && node.parentNode ? [node, node.parentNode] : [node]) {
+    const a = BY.get(n) || (BY.set(n, []), BY.get(n))
+    a.unshift(rec)
+    a.length = Math.min(a.length, KEEP)
+  }
+  if (cur) cur.mutations++, cur.nodes.add(node)
+}
+const owner = (o, k) => {
+  for (; o; o = Object.getPrototypeOf(o)) {
+    const d = Object.getOwnPropertyDescriptor(o, k)
+    if (d) return [o, d]
+  }
+  return []
+}
+function wrap(sample, k, kind) {
+  const [o, d] = owner(sample, k)
+  if (!o || (d.value && d.value.$why) || (d.set && d.set.$why)) return
+  if (typeof d.value === 'function') {
+    const f = d.value
+    const g = function (...a) {
+      note(kind.node ? kind.node(this, a) : this, typeof kind === 'function' ? kind(a) : kind.k(a))
+      return f.apply(this, a)
+    }
+    g.$why = 1
+    Object.defineProperty(o, k, { ...d, value: g })
+  } else if (d.set) {
+    const set = function (v) {
+      note(this, kind)
+      d.set.call(this, v)
+    }
+    set.$why = 1
+    Object.defineProperty(o, k, { ...d, set })
+  }
+}
+function install() {
+  const d = G.document
+  if (!d || G.__brainWhy) return
+  const el = d.createElement('div'), tx = d.createTextNode(''), cm = d.createComment('')
+  wrap(el, 'setAttribute', a => 'attr:' + a[0])
+  wrap(el, 'removeAttribute', a => 'attr:' + a[0])
+  wrap(el, 'textContent', 'text')
+  wrap(tx, 'data', 'text')
+  wrap(tx, 'nodeValue', 'text')
+  wrap(el, 'insertBefore', { node: (_, a) => a[0], k: () => 'insert' })
+  wrap(el, 'appendChild', { node: (_, a) => a[0], k: () => 'insert' })
+  wrap(el, 'removeChild', { node: (_, a) => a[0], k: () => 'remove' })
+  for (const n of [el, tx, cm]) wrap(n, 'remove', () => 'remove')
+  for (const k of ['value', 'checked', 'selected']) wrap(d.createElement('input'), k, 'prop:' + k)
+  // classList / style have no link back to their element: map them through the element's getter (browsers)
+  for (const [k, m] of [['classList', 'toggle'], ['style', 'setProperty']]) {
+    const [o, dd] = owner(el, k)
+    if (!o || !dd.get) continue
+    const back = new WeakMap()
+    Object.defineProperty(o, k, { ...dd, get() { const v = dd.get.call(this); back.set(v, this); return v } })
+    const [po, pd] = owner(el[k], m)
+    if (po && typeof pd.value === 'function') {
+      const f = pd.value
+      Object.defineProperty(po, m, { ...pd, value(...a) { note(back.get(this), (k === 'style' ? 'style:' : 'class:') + a[0]); return f.apply(this, a) } })
+    }
+  }
+  // interactions: everything a user event causes until the updates settle
+  for (const t of ['click', 'input', 'change', 'keydown', 'submit'])
+    d.addEventListener(t, e => {
+      if (cur) return
+      cur = { type: t, target: describe(e.target), mutations: 0, nodes: new Set(), t0: G.performance ? performance.now() : Date.now() }
+      setTimeout(() => {
+        const c = cur
+        cur = null
+        INT.unshift({ type: c.type, target: c.target, mutations: c.mutations, nodes: c.nodes.size, ms: Math.round(((G.performance ? performance.now() : Date.now()) - c.t0) * 10) / 10 })
+        INT.length = Math.min(INT.length, LAST)
+      }, 0)
+    }, true)
+  G.__brainWhy = { why, interactions, mounts, clear }
+}
+const describe = n => {
+  if (!n || n.nodeType !== 1) return n && n.parentNode ? describe(n.parentNode) : null
+  const id = n.getAttribute('id'), c = n.getAttribute('class')
+  return n.tagName.toLowerCase() + (id ? '#' + id : '') + (c ? '.' + c.trim().split(/\s+/).join('.') : '')
+}
+
+// ---------- answers ----------
+const RT = /\/(@brain|_b)\/brain[\w-]*\.js|\/runtime\/brain[\w-]*\.js|\/brain-why\.js/
+const MAPS = new Map()
+// the first app frame of the write's stack, as file.brain:line when the dev module carries its source map
+async function where(stack) {
+  for (const l of String(stack).split('\n').slice(1)) {
+    const m = /\(?((?:https?|file):\/\/[^\s)]+?):(\d+):\d+\)?\s*$/.exec(l)
+    if (!m || RT.test(m[1])) continue
+    const url = m[1], line = +m[2]
+    if (!MAPS.has(url)) MAPS.set(url, load(url))
+    const lines = await MAPS.get(url)
+    const path = url.replace(/^\w+:\/\/[^/]*/, '').replace(/^\//, '').replace(/\?.*$/, '')
+    return lines && lines[line - 1] ? `${path}:${lines[line - 1]}` : `${path}:${line}`
+  }
+  return null
+}
+async function load(url) {
+  try {
+    if (!/^https?:/.test(url) || !G.fetch) return null
+    const t = await (await fetch(url)).text()
+    const m = /sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/.exec(t)
+    if (!m) return null
+    const { decode } = await import('./brain-err.js')
+    return decode(JSON.parse(atob(m[1])).mappings)
+  } catch {
+    return null
+  }
+}
+const val = v => (typeof v === 'function' ? 'fn' : v && typeof v === 'object' ? JSON.stringify(v).slice(0, 80) : v)
+
+// why('#total') → [{ kind: 'text', at, causes: [{ signal: 'cart.total', comp: 'views/cart.brain', src:
+// 'views/cart.brain:12', from, to, via: ['subtotal'] }] }], newest first; [] when that node never updated
+export async function why(target) {
+  const n = typeof target === 'string' ? G.document && document.querySelector(target) : target
+  if (!n) return { error: `no element matches ${target}` }
+  const recs = [...(BY.get(n) || [])]
+  return Promise.all(
+    recs.map(async r => ({
+      kind: r.kind,
+      at: r.t,
+      causes: await Promise.all(r.causes.map(async c => ({ signal: c.w.name, comp: c.w.comp, src: await where(c.w.stack), from: val(c.w.from), to: val(c.w.to), via: c.via }))),
+    }))
+  )
+}
+export const interactions = () => INT.slice()
+// last mounts, newest first: [{ comp: 'comp/x.brain', ms, at, hmr }] (brain-dev measures each one)
+export const mounts = () => M.slice()
+export const clear = () => (INT.length = 0)
+
+install()

package/brain-worker.js

@@ -0,0 +1,66 @@
+// BRAINLLM Web Worker bridge (INTERNALS §35.5). The compiler turns `*.worker.jsbrain` into a worker chunk that ends in
+// `serve({ parseCsv, default: $default })`, and every importer into `const w = worker(new URL('…', import.meta.url))`
+// plus `const parseCsv = (...a) => w.call('parseCsv', a)`. Messages use structured clone: { id, name, args } →
+// { id, ok } | { id, err: { message, name, stack } }. The worker starts on the first call; a remote error is rethrown
+// in the page as an Error with the same message and name (its stack in `remoteStack`).
+
+// Worker side. `name` may be a path into the map ('default.mean'); the result may be a promise.
+export function serve(map, scope = globalThis) {
+  scope.onmessage = async e => {
+    const { id, name, args } = e.data || {}
+    try {
+      let f = map, self
+      for (const k of String(name).split('.')) (self = f), (f = f == null ? undefined : f[k])
+      if (typeof f !== 'function') throw new TypeError(`worker: \`${name}\` is not an exported function`)
+      const ok = await f.apply(self, args || [])
+      scope.postMessage({ id, ok }) // throws DataCloneError for a result that cannot be cloned → reported below
+    } catch (x) {
+      scope.postMessage({ id, err: { message: (x && x.message) || String(x), name: (x && x.name) || 'Error', stack: x && x.stack } })
+    }
+  }
+}
+
+// Page side.
+export function worker(url) {
+  let w = null, n = 0
+  const wait = new Map()
+  const failAll = err => {
+    for (const [, p] of wait) p[1](err)
+    wait.clear()
+    w = null // the next call starts a fresh worker
+  }
+  const start = () => {
+    w = new Worker(url, { type: 'module' })
+    w.onmessage = e => {
+      const { id, ok, err } = e.data || {}
+      const p = wait.get(id)
+      if (!p) return
+      wait.delete(id)
+      if (err) p[1](Object.assign(new Error(err.message), { name: err.name, remoteStack: err.stack }))
+      else p[0](ok)
+    }
+    w.onerror = e => {
+      if (e && e.preventDefault) e.preventDefault()
+      failAll(new Error('worker failed: ' + ((e && e.message) || url)))
+    }
+  }
+  return {
+    call(name, args) {
+      if (!w) start()
+      const id = ++n
+      return new Promise((ok, fail) => {
+        wait.set(id, [ok, fail])
+        try {
+          w.postMessage({ id, name, args })
+        } catch (x) {
+          wait.delete(id)
+          fail(x) // DataCloneError: an argument cannot cross to the worker (functions, DOM nodes…)
+        }
+      })
+    },
+    terminate() {
+      if (w) w.terminate()
+      failAll(new Error('worker terminated'))
+    },
+  }
+}

package/brain.js

@@ -0,0 +1,421 @@
+// BRAINLLM runtime (SPEC §6). Push-pull signals with coloring: a write marks, a read recomputes only what is dirty.
+// N: _ value · f fn · e effect · s state (0 clean 1 check 2 dirty 3 dead) · S sources · o observers
+// S and o hold pairs [node, index of the link on the other side] (O(1) unlink) · c children · x index in p.c
+// k cleanup · p owner. S/o/c start null (RAM). Methods: m mark · u update
+// · r run · q clean · n unlink · d dispose. Short names: brain-min does not rename properties.
+
+// L tracker · O owner · Q pending effects · B batch depth · P flush scheduled · H dev hook · E error hook · V provider (brain-ch)
+let L = null, O = null, Q = [], B = 0, P = 0, H = null, E = null, V, A = null
+// Errors (INTERNALS §18): fx, drv and handlers are caught and the app keeps running. E (brain-err.js, _err) records
+// them and applies per-component fallbacks; without it, console.error.
+// Errors go to the rich catcher (brain-err) or the console, then to the nearest component boundary (§42, brain-guard.js):
+// up the owner chain for fx/drv, up the DOM for handlers.
+const oops = (e, x, w) => {
+  if (e && e.kind == 'aborted') return // a cancelled request (brain-data): never an error to report or show
+  E ? E(e, x, w) : globalThis.reportError ? reportError(e) : console.error(e) // reportError: window error listeners (the dev client) see it
+  for (let o = x; o; o = o.nodeType ? o.parentNode : o.p) {
+    const g = o.$g
+    if (g) return g(e, w)
+  }
+}
+
+const adopt = (p, n) => {
+  n.p = p
+  if (p) n.x = (p.c || (p.c = [])).push(n) - 1
+}
+
+class N {
+  constructor(v, f, e) {
+    this._ = v
+    this.f = f
+    this.e = e
+    this.s = f ? 2 : 0
+    this.S = null
+    this.o = null
+    this.c = null
+    this.k = null
+    this.p = null
+    this.x = 0
+    if (f) adopt(O, this)
+  }
+  get v() {
+    const l = L
+    if (l && l != this) {
+      const s = l.S || (l.S = [])
+      if (s[s.length - 2] != this && !s.includes(this)) {
+        const o = this.o || (this.o = [])
+        s.push(this, o.length)
+        o.push(l, s.length - 2)
+      }
+    }
+    if (this.f) this.u()
+    return this._
+  }
+  set v(x) {
+    if (this.f) throw Error('drv is read-only')
+    if (!Object.is(x, this._)) {
+      this._ = x
+      const o = this.o
+      if (o) for (let i = 0; i < o.length; i += 2) o[i].m(2)
+      if (!B && !P) (P = 1), queueMicrotask(flush)
+    }
+  }
+  m(s) {
+    if (this.s < s) {
+      if (this.e && !this.s) Q.push(this)
+      this.s = s
+      const o = this.o
+      if (o) for (let i = 0; i < o.length; i += 2) o[i].m(1)
+    }
+  }
+  u() {
+    const S = this.S
+    if (this.s == 1 && S) for (let i = 0; i < S.length; i += 2) if ((S[i].u(), this.s == 2)) break
+    if (this.s == 2) this.r()
+    if (this.s < 3) this.s = 0
+  }
+  r() {
+    const pl = L, po = O, old = this._
+    this.q()
+    this.n()
+    L = O = this
+    let r, x = 0
+    try {
+      r = this.f()
+    } catch (e) {
+      ;(x = 1), (r = old), oops(e, this, this.e ? 'fx' : 'drv')
+    } finally {
+      L = pl
+      O = po
+    }
+    if (x) return
+    if (this.e) {
+      if (typeof r == 'function') this.k = r
+    } else if (r !== old) {
+      this._ = r
+      const o = this.o
+      if (o) for (let i = 0; i < o.length; i += 2) if (o[i].s < 3) o[i].s = 2
+    }
+  }
+  q() {
+    const c = this.c
+    if (c) {
+      this.c = null // children see c=null and skip removing themselves one by one
+      for (const n of c) n.d()
+    }
+    const f = this.k
+    if (f) (this.k = null), f()
+  }
+  n() {
+    const S = this.S
+    if (S) {
+      // swap-remove: the last pair of s.o fills the gap and its index in l.S is fixed
+      for (let j = 0; j < S.length; j += 2) {
+        const o = S[j].o, k = S[j + 1], ly = o.pop(), l = o.pop()
+        if (k < o.length) (o[k] = l), (o[k + 1] = ly), (l.S[ly + 1] = k)
+      }
+      S.length = 0 // reused on the next run
+    }
+  }
+  d() {
+    if (this.s < 3) {
+      this.s = 3
+      const c = this.p && this.p.c
+      if (c) {
+        const l = c.pop()
+        if (l != this) (c[this.x] = l), (l.x = this.x)
+      }
+      this.q()
+      this.n()
+    }
+  }
+}
+
+function flush() {
+  P = 0
+  B++
+  let c = null
+  try {
+    for (let i = 0; i < Q.length; i++) {
+      const n = Q[i]
+      if (i > 100) {
+        // B0902: an effect re-run >100 times in one flush is cut off (stays dirty, not requeued)
+        const k = (c || (c = new Map())).get(n) + 1 || 1
+        c.set(n, k)
+        if (k > 100) {
+          if (k < 102) oops(Object.assign(Error('B0902'), { code: 'B0902', fx: n }), n, 'B0902')
+          continue
+        }
+      }
+      n.u()
+    }
+  } finally {
+    Q = []
+    B--
+  }
+}
+
+export const sig = (v, k) => (k && H ? H(new N(v, null, 0), k) : new N(v, null, 0))
+export const drv = f => new N(undefined, f, 0)
+export const fx = f => {
+  const n = new N(undefined, f, 1)
+  n.u()
+  return () => n.d()
+}
+export const batch = f => {
+  B++
+  try {
+    return f()
+  } finally {
+    if (!--B) flush()
+  }
+}
+export const untrack = f => {
+  const p = L
+  L = null
+  try {
+    return f()
+  } finally {
+    L = p
+  }
+}
+
+// Root owner: isolates from tracking and returns what f builds; f receives its dispose.
+function root(f, p) {
+  const r = new N(), pl = L, po = O
+  adopt(p, r)
+  L = null
+  O = r
+  try {
+    return f(() => r.d())
+  } finally {
+    L = pl
+    O = po
+  }
+}
+// Internals for brain-dev.js: installs the named-sig hook; returns root and the current owner.
+export const _dev = h => ((H = h), _rt())
+// RPC (INTERNALS §11.1): codegen stub `(...a) => rpc("<hash>/save", a)`; the client is brain-rpc.js, loaded on the
+// first call (#226: only pages that call the server pay for it).
+export const rpc = (id, a) => import('./brain-rpc.js').then(m => m.rpc(id, a, oops, base()))
+// Internals for sibling modules (brain-err, brain-ch): root, current owner and node helpers; _err installs the hook;
+// brain-ch passes its provider for `mount(C, t, props, { provide })`.
+// Optimistic writes (brain-data) and the circuit breaker (brain-guard) wrap N's prototype instead of a core hook (#288).
+export const _rt = p => ((V = V || p), { root, owner: () => O, nodes, rm, oops, guard: (o, g) => (o.$g = g), adopt: a => (A = a), dev: (a, b) => H && H(a, b) })
+export const _err = h => ((E = h), _rt())
+
+// ---------- DOM ----------
+
+const mk = p => p.appendChild(document.createComment(''))
+// Yield to the browser: scheduler.yield (Chrome 129+), else a MessageChannel task (no 4 ms setTimeout clamp)
+const later = f => {
+  if (globalThis.scheduler && scheduler.yield) return scheduler.yield().then(f)
+  const c = new MessageChannel()
+  c.port1.onmessage = () => (c.port1.close(), f())
+  c.port2.postMessage(0)
+}
+// a node with an exit transition (brain-anim.js `$out` → Promise) leaves once it has played
+const rm = a => {
+  for (const n of a) n.$out ? n.$out().then(() => n.remove()) : n.remove()
+}
+function nodes(v, a = []) {
+  if (v == null || v === true || v === false) return a
+  if (Array.isArray(v)) for (const x of v) nodes(x, a)
+  else if (typeof v == 'function') nodes(v(), a)
+  else if (v.nodeType == 11) a.push(...v.childNodes)
+  else a.push(v.nodeType ? v : document.createTextNode(v))
+  return a
+}
+function place(end, v) {
+  const a = nodes(v), p = end.parentNode
+  if (A) return A.p(end, a)
+  for (const n of a) p.insertBefore(n, end)
+  return a
+}
+// Writes reach the DOM only when the value changed (Object.is): a row whose object changed rewrites only its new fields.
+const bind = (f, s) => {
+  if (typeof f != 'function') return s(f)
+  let last = bind
+  fx(() => {
+    const v = f()
+    if (!Object.is(v, last)) s((last = v))
+  })
+}
+
+export function tpl(h) {
+  let n
+  return () => {
+    if (!n) {
+      const t = document.createElement('template')
+      t.innerHTML = h
+      const c = t.content
+      n = c.childNodes.length == 1 ? c.firstChild : c
+    }
+    // A: SSR stamps the clone, hydration adopts the node the server rendered (#285)
+    return A ? A.t(n) : n.cloneNode(true)
+  }
+}
+export function insert(p, f, end) {
+  end = end || mk(p)
+  if (typeof f != 'function') return void place(end, f)
+  let cur = [], last = insert
+  fx(() => {
+    const v = f()
+    if (Object.is(v, last)) return
+    last = v
+    if (cur.length == 1 && cur[0].nodeType == 3 && (typeof v == 'string' || typeof v == 'number')) cur[0].data = v
+    else
+      untrack(() => {
+        rm(cur)
+        cur = place(end, v)
+      })
+  })
+}
+
+// aria-* and data-* are enumerated, not boolean: true and false render as text (k[4] is their dash)
+export function attr(el, k, f) {
+  bind(
+    f,
+    k.startsWith('style:')
+      ? ((k = k.slice(6)), v => (v == null || v === false ? el.style.removeProperty(k) : el.style.setProperty(k, v)))
+      : /^(value|checked|selected)$/.test(k)
+        ? v => {
+            if (el[k] !== v) el[k] = v
+          }
+        : v => (v == null || (v === false && k[4] != '-') ? el.removeAttribute(k) : el.setAttribute(k, v === true && k[4] != '-' ? '' : /^(href|src|action|formaction|poster)$/.test(k) && typeof v == 'string' ? inBase(v) : v))
+  )
+}
+// Base path (§23 #148): <meta name="brain-base"> in the browser, globalThis.__brainBase while server.mjs renders.
+// A computed app URL ('/posts/7') gets it; literal ones already have it from the build.
+const base = (m = document.querySelector('meta[name=brain-base]')) => globalThis.__brainBase || (m ? m.getAttribute('content') : '/')
+// javascript:, vbscript: and data: (other than data:image/) in a bound URL are dropped and reported (B0213, §31)
+const inBase = (v, b = base()) =>
+  /^\s*(javascript|vbscript|data(?!:image\/)):/i.test(v)
+    ? (oops(Error('B0213 blocked URL scheme')), '')
+    : v[0] == '/' && v[1] != '/' && !(v + '/').startsWith(b) ? b + v.slice(1) : v
+
+export const cls = (el, k, f) => bind(f, v => el.classList.toggle(k, !!v))
+
+// Delegated: walks composedPath (crosses shadow roots). brain-wc.js reuses it in shadow roots (_ev).
+export function _ev(e) {
+  const k = '$' + e.type
+  let n
+  batch(() => {
+    for (n of e.composedPath()) {
+      const h = n[k]
+      if (h) {
+        // a data property, not a getter: V8 keeps accessors in the event's shared hidden class, so a getter closure
+        // would keep the first event (and its component) alive for the life of the page
+        Object.defineProperty(e, 'currentTarget', { configurable: true, value: n })
+        try {
+          // n moves on with the loop: keep the element for a later rejection
+          const r = h.call(n, e), el = n
+          if (r && r.then) r.then(null, x => oops(x, el, 'on:' + e.type)) // async handler: a rejected await too
+        } catch (x) {
+          oops(x, n, 'on:' + e.type)
+        }
+        if (e.cancelBubble) break
+      }
+    }
+  })
+}
+export function on(el, t, h) {
+  if (/^(focus|blur|mouseenter|mouseleave|load|error|scroll)$/.test(t)) return el.addEventListener(t, e => batch(() => h(e)))
+  el['$' + t] = h
+  document.addEventListener(t, _ev) // once per type: the DOM ignores the same listener added again
+}
+
+// Indices of array `a` (−1 = new) that form the longest increasing subsequence.
+function lis(a) {
+  const p = a.slice(), r = []
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i]
+    if (x < 0) continue
+    let lo = 0, hi = r.length
+    while (lo < hi) {
+      const m = (lo + hi) >> 1
+      a[r[m]] < x ? (lo = m + 1) : (hi = m)
+    }
+    p[i] = lo ? r[lo - 1] : -1
+    r[lo] = i
+  }
+  const f = new Uint8Array(a.length)
+  for (let i = r.length ? r[r.length - 1] : -1; i >= 0; i = p[i]) f[i] = 1
+  return f
+}
+
+// render(item, i) receives signals (`item.v`, `i.v`): same key with a new object updates in place.
+export function list(p, f, key, render, end, empty) {
+  end = end || mk(p)
+  const own = O
+  let rows = new Map(), order = [], emp = null
+  fx(() => {
+    const items = f() || [], me = O
+    untrack(() => {
+      // Large updates (>500 rows, some already on screen) create new rows in ≤16 ms slices (one frame; QA #302: 5 ms
+      // split a 1,000-row update into extra frames): the rest is skipped and this fx re-runs after a yield (INP). A first render (no rows yet) is built at once: slicing it only re-walks the list.
+      const first = !order.length, next = [], map = new Map(), pa = end.parentNode, big = items.length > 500 && !first, t0 = big && performance.now()
+      let cut = 0
+      order.forEach((r, j) => (r.o = j))
+      for (let i = 0; i < items.length; i++) {
+        const it = items[i], k = key(it, i)
+        if (map.has(k)) throw Error('duplicate key in each: ' + k)
+        let r = rows.get(k)
+        if (r) rows.delete(k), (r.s.v = it), (r.i.v = i)
+        else if (cut || (big && performance.now() - t0 > 16)) {
+          cut = 1
+          continue
+        } else r = root(d => {
+          const s = sig(it), x = sig(i)
+          return { s, i: x, n: nodes(render(s, x)), d, o: -1 }
+        }, own)
+        next.push(r)
+        map.set(k, r)
+      }
+      if (cut) later(() => (me.m(2), P || B || ((P = 1), queueMicrotask(flush))))
+      for (const r of rows.values()) r.d(), rm(r.n)
+      if (first && next.length && A) A.p(end, next.flatMap(r => r.n))
+      else if (first && next.length) {
+        // nothing to keep or move: one fragment, one insertion
+        const fr = document.createDocumentFragment()
+        for (const r of next) for (const n of r.n) fr.appendChild(n)
+        pa.insertBefore(fr, end)
+      } else {
+      const keep = lis(next.map(r => r.o)), mv = pa.moveBefore && pa.isConnected
+      for (let i = next.length - 1, ref = end; i >= 0; i--) {
+        const r = next[i]
+        // moveBefore keeps focus, iframes, animations and state of moved rows (Chrome 133+); new rows use insertBefore
+        if (!keep[i]) for (const n of r.n) mv && r.o >= 0 ? pa.moveBefore(n, ref) : pa.insertBefore(n, ref)
+        ref = r.n[0] || ref
+      }
+      }
+      rows = map
+      order = next
+      if (!items.length && empty && !emp) emp = root(d => ({ n: place(end, empty()), d }), own)
+      else if (items.length && emp) emp.d(), rm(emp.n), (emp = null)
+    })
+  })
+}
+
+export function when(p, c, a, b, end) {
+  end = end || mk(p)
+  const t = drv(() => !!c())
+  fx(() => {
+    const g = t.v ? a : b
+    const n = g ? untrack(() => place(end, g())) : []
+    return () => rm(n)
+  })
+}
+
+// Tests replace services/context: `mount(C, el, props, { provide: [[Api, fake]] })` (needs brain-ch.js).
+export function mount(C, t, props = {}, o) {
+  return root(d => {
+    const n = nodes(o && o.provide ? V(o.provide, () => C(props)) : C(props))
+    for (const x of n) t.appendChild(x)
+    return () => (d(), rm(n))
+  }, null)
+}
+
+// Islands (SPEC §6.1) live in brain-island.js: only pages with islands load it. It receives what it needs from the
+// core instead of importing it (hashed chunks cannot import each other in a cycle).
+export const hydrate = r => import('./brain-island.js').then(m => m.hydrate(r, { mount, _rt }))