@christianirack/brainllm-runtime 0.5.0 → 0.6.1

package/brain-ai.js

@@ -55,16 +55,24 @@ async function create(kind, o = {}) {
   return N.create(rest)
 }
 
-// one base session per system prompt; each stateless call works on a clone, so calls never share history
-const bases = new Map()
+// one base session per system prompt; each stateless call works on a clone, so calls never share history. A system
+// prompt built from data (a name, a date) would open a native session per value: keep the 8 most recent, destroy the rest.
+const bases = new Map(), BASES = 8
 async function base(o) {
   const k = o.system || ''
-  if (!bases.has(k)) {
-    const p = create('prompt', { ...(o.system ? { initialPrompts: [{ role: 'system', content: o.system }] } : {}), ...(o.onProgress ? { onProgress: o.onProgress } : {}) })
-    p.catch(() => bases.delete(k))
-    bases.set(k, p)
+  let p = bases.get(k)
+  if (p) bases.delete(k)
+  else {
+    p = create('prompt', { ...(o.system ? { initialPrompts: [{ role: 'system', content: o.system }] } : {}), ...(o.onProgress ? { onProgress: o.onProgress } : {}) })
+    p.catch(() => bases.get(k) === p && bases.delete(k))
+    if (bases.size >= BASES) {
+      const [old, q] = bases.entries().next().value
+      bases.delete(old)
+      q.then(s => s.destroy && s.destroy(), () => {})
+    }
   }
-  return (await bases.get(k)).clone()
+  bases.set(k, p)
+  return (await p).clone()
 }
 const opts = o => ({ ...(o.signal ? { signal: o.signal } : {}), ...(o.schema ? { responseConstraint: o.schema } : {}) })
 

package/brain-analytics.js

@@ -0,0 +1,401 @@
+// BRAINLLM behavior analytics collector (docs/backend/analytics.md). First-party and off the critical path: the native
+// backend serves this module at `/_brain/analytics.js` and the server adds it to HTML pages as an async module, so it
+// never counts toward a route's budget. With no backend nothing loads and nothing is recorded.
+//
+// One delegated, capture-phase listener per action type on the document records what every element receives
+// (click, keyboard activation, focus, input, change, toggles, submit, copy/cut/paste, media, drag/drop, context menu,
+// hover intent), plus page views, scroll depth, dwell and SPA navigations. Each event carries a stable descriptor of the
+// element: `c` the component hash (`data-b`, the same id the compiler gives every component root), `t` tag, `i` ordinal
+// among same-tag elements of that component, `n` accessible name, `x` data-track, `o` role, `y` type, `f` field or form
+// name, `h` link route. `brain analytics report` maps `c` + `t` + `i`/`n` back to `file:line` of the .brain source.
+//
+// Never recorded: field values, typed keys, copied text, IP addresses. Password, card and one-time-code fields are only
+// counted. Global Privacy Control, Do Not Track and automated browsers turn the collector off; `consent: "required"`
+// waits for consent('analytics') from brain-consent.js.
+//
+// Custom events from app code, with no import:
+//   dispatchEvent(new CustomEvent('brain:track', { detail: { name: 'add_to_cart', props: { sku: 'A1' } } }))
+// or declaratively: <button data-track="add_to_cart">.
+const VISITOR = 'brain:vid'
+const SESSION = 'brain:sid'
+const IDLE_MS = 30 * 60 * 1000
+const FLUSH_MS = 5000
+const BATCH = 64
+const HOVER_MS = 500
+const RAGE = 3
+const RAGE_MS = 1000
+const DEAD_MS = 1000
+const TAGS = /^(A|BUTTON|INPUT|SELECT|TEXTAREA|SUMMARY|DETAILS|LABEL|OPTION|VIDEO|AUDIO|FORM|IFRAME)$/
+const ROLES =
+  /^(button|link|tab|menuitem|menuitemcheckbox|menuitemradio|checkbox|radio|switch|option|combobox|slider|textbox|searchbox|treeitem|gridcell)$/
+const FIELDS = /^(INPUT|SELECT|TEXTAREA|LABEL|OPTION|VIDEO|AUDIO|IFRAME|FORM|DETAILS)$/
+const SECRET = /pass|card|cvc|cvv|ccv|iban|ssn|secret|token|otp|pin$/i
+const TOKEN = /^[\w.:-]{1,64}$/
+
+export function start(config = {}, env = globalThis) {
+  const doc = env.document
+  const win = env.window || env
+  const nav = env.navigator || {}
+  const loc = () => env.location || { pathname: '/', search: '', href: '/', origin: '' }
+  const store = env.localStorage
+  const now = () => (env.performance ? env.performance.now() : Date.now())
+  if (!doc || config.enabled === false) return null
+  if (nav.globalPrivacyControl === true || nav.doNotTrack === '1' || win.doNotTrack === '1' || nav.webdriver) return null
+  const endpoint = config.endpoint || (config.base || '/') + '_brain/analytics'
+  const consented = () => {
+    if (config.consent !== 'required') return true
+    try {
+      return !!(JSON.parse(store.getItem('brain:consent')) || {}).analytics
+    } catch {
+      return false
+    }
+  }
+  const get = k => {
+    try {
+      return JSON.parse(store.getItem(k))
+    } catch {
+      return null
+    }
+  }
+  const put = (k, v) => {
+    try {
+      store.setItem(k, JSON.stringify(v))
+    } catch {}
+  }
+  const uuid = () =>
+    env.crypto && env.crypto.randomUUID
+      ? env.crypto.randomUUID()
+      : '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, c =>
+          (c ^ ((Math.random() * 16) >> (c / 4))).toString(16),
+        )
+
+  // ── identity: anonymous first-party visitor (localStorage) and a session that ends after 30 idle minutes
+  let session = null
+  const ids = () => {
+    const t = Date.now()
+    let vid = get(VISITOR)
+    if (typeof vid !== 'string') put(VISITOR, (vid = uuid()))
+    if (!session) session = get(SESSION)
+    if (!session || typeof session.id !== 'string' || t - session.last > IDLE_MS) session = { id: uuid(), last: t, pv: 0, ctx: 0 }
+    session.last = t
+    put(SESSION, session)
+    return vid
+  }
+
+  // ── element descriptor
+  const attr = (n, k) => (n && n.getAttribute && n.getAttribute(k)) || ''
+  const actionable = el => {
+    for (let n = el; n && n.nodeType === 1; n = n.parentNode)
+      if (TAGS.test(n.tagName) || ROLES.test(attr(n, 'role')) || n.hasAttribute('data-track') || n.hasAttribute('tabindex')) return n
+    return null
+  }
+  const secret = el =>
+    el.tagName !== 'A' &&
+    (attr(el, 'type') === 'password' ||
+      /^(cc-|one-time-code)/.test(attr(el, 'autocomplete')) ||
+      SECRET.test(attr(el, 'name') + ' ' + attr(el, 'id')) ||
+      el.hasAttribute('data-private'))
+  const text = s => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 64)
+  const accessibleName = el => {
+    const label = attr(el, 'aria-label')
+    if (label) return text(label)
+    const by = attr(el, 'aria-labelledby')
+    if (by) {
+      const n = doc.getElementById(by.split(/\s+/)[0])
+      if (n) return text(n.textContent)
+    }
+    if (/^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName)) {
+      const id = attr(el, 'id')
+      const l = id && doc.querySelector && doc.querySelector(`label[for=${id}]`)
+      return text((l && l.textContent) || attr(el, 'placeholder') || attr(el, 'title'))
+    }
+    return text(attr(el, 'title') || attr(el, 'alt') || el.textContent)
+  }
+  const component = el => {
+    for (let n = el; n && n.nodeType === 1; n = n.parentNode) if (n.hasAttribute('data-b')) return n
+    return null
+  }
+  // Ordinal among same-tag elements of the component, in document order, skipping nested components.
+  const ordinal = (root, el) => {
+    const hash = attr(root, 'data-b')
+    let i = 0
+    let found = -1
+    const walk = n => {
+      for (const c of n.childNodes || []) {
+        if (found >= 0 || c.nodeType !== 1) continue
+        if (c.hasAttribute('data-b') && attr(c, 'data-b') !== hash) continue
+        if (c === el) return void (found = i)
+        if (c.tagName === el.tagName) i++
+        walk(c)
+      }
+    }
+    const roots = root.parentNode ? [...root.parentNode.childNodes].filter(c => c.nodeType === 1 && attr(c, 'data-b') === hash) : [root]
+    for (const r of roots) {
+      if (found >= 0) break
+      if (r === el) found = i
+      else {
+        if (r.tagName === el.tagName) i++
+        walk(r)
+      }
+    }
+    return found
+  }
+  const route = href => {
+    try {
+      const u = new URL(href, loc().href)
+      return u.origin === loc().origin ? u.pathname : null
+    } catch {
+      return null
+    }
+  }
+  const describe = el => {
+    if (!el || el.nodeType !== 1) return null
+    const d = { t: el.tagName.toLowerCase() }
+    const root = component(el)
+    if (root) {
+      d.c = attr(root, 'data-b')
+      const i = ordinal(root, el)
+      if (i >= 0 && i < 10000) d.i = i
+    }
+    const track = attr(el, 'data-track')
+    if (TOKEN.test(track)) d.x = track
+    const role = attr(el, 'role')
+    if (TOKEN.test(role)) d.o = role
+    if (/^(INPUT|BUTTON)$/.test(el.tagName) && TOKEN.test(attr(el, 'type'))) d.y = attr(el, 'type')
+    if (secret(el)) return (d.y = 'secret'), d // counted, never named
+    const field = attr(el, 'name') || (/^(INPUT|SELECT|TEXTAREA|FORM)$/.test(el.tagName) ? attr(el, 'id') : '')
+    if (TOKEN.test(field)) d.f = field
+    if (el.tagName === 'A') {
+      const h = route(attr(el, 'href'))
+      if (h) d.h = h
+    }
+    if (el.tagName === 'FORM') {
+      const h = route(attr(el, 'action') || loc().href)
+      if (h) d.h = h
+    } else if (actionable(el) === el) {
+      const n = accessibleName(el) // only controls are named: the text of arbitrary content is never read
+      if (n) d.n = n
+    }
+    return d
+  }
+
+  // ── queue and transport
+  let queue = []
+  let timer = null
+  let pv = 0
+  let pageAt = now()
+  let visibleMs = 0
+  let visibleAt = now()
+  let maxScroll = 0
+  let path = loc().pathname
+  let stopped = false
+  const send = () => {
+    clearTimeout(timer)
+    timer = null
+    if (!queue.length) return
+    const vid = ids()
+    while (queue.length) {
+      const body = { v: 1, vid, sid: session.id, ev: queue.splice(0, BATCH) }
+      if (!session.ctx) {
+        const q = new URLSearchParams(loc().search || '')
+        const utm = {}
+        for (const k of ['source', 'medium', 'campaign', 'term', 'content']) if (q.get('utm_' + k)) utm[k] = q.get('utm_' + k).slice(0, 128)
+        body.ctx = { ref: doc.referrer || undefined, utm, lang: nav.language, w: win.innerWidth | 0 }
+        session.ctx = 1
+        put(SESSION, session)
+      }
+      const json = JSON.stringify(body)
+      let ok = false
+      try {
+        ok = !!(nav.sendBeacon && nav.sendBeacon(endpoint, json))
+      } catch {}
+      if (!ok && env.fetch)
+        env
+          .fetch(endpoint, { method: 'POST', body: json, keepalive: true, credentials: 'same-origin', headers: { 'content-type': 'text/plain' } })
+          .catch(() => {})
+    }
+  }
+  const record = (k, el, v, p) => {
+    if (stopped || !consented()) return
+    if (!pv && k !== 'page') page() // consent arrived after load: open the page view first
+    const e = { k, r: path, pv, t: Math.max(0, Math.round(now() - pageAt)), at: Date.now() }
+    const d = el ? describe(el) : null
+    if (d) e.el = d
+    if (v != null && isFinite(v)) e.v = Math.round(v)
+    if (p) e.p = p
+    queue.push(e)
+    if (queue.length >= BATCH / 2) send()
+    else if (!timer) timer = setTimeout(send, FLUSH_MS)
+  }
+
+  // ── page views, dwell, scroll
+  const visible = () => doc.visibilityState !== 'hidden'
+  const dwell = () => visibleMs + (visible() ? now() - visibleAt : 0)
+  const page = () => {
+    if (!consented()) return
+    ids()
+    pv = ++session.pv
+    put(SESSION, session)
+    pageAt = visibleAt = now()
+    visibleMs = maxScroll = 0
+    record('page', null)
+  }
+  const leave = () => {
+    flushInputs()
+    if (pv) record('leave', null, dwell(), { scroll: Math.round(maxScroll) })
+  }
+  const navigated = () => {
+    const p = loc().pathname
+    if (p === path) return
+    leave()
+    path = p
+    page()
+  }
+  const scrolled = () => {
+    const el = doc.documentElement || {}
+    const h = (el.scrollHeight || 0) - (win.innerHeight || 0)
+    const pct = h > 0 ? (100 * (win.scrollY || el.scrollTop || 0)) / h : 100
+    if (pct > maxScroll) maxScroll = Math.min(100, pct)
+  }
+
+  // ── interactions
+  const off = []
+  const listen = (t, f, target = doc) => {
+    if (!target.addEventListener) return
+    const o = { capture: true, passive: true }
+    target.addEventListener(t, f, o)
+    off.push(() => target.removeEventListener(t, f, o))
+  }
+  const clicks = []
+  let mutations = 0
+  const Observer = env.MutationObserver
+  const mo = Observer && new Observer(r => (mutations += r.length))
+  if (mo) mo.observe(doc, { subtree: true, childList: true, attributes: true, characterData: true })
+  const changes = () => (mutations += mo && mo.takeRecords ? mo.takeRecords().length : 0)
+  listen('click', e => {
+    const el = actionable(e.target) || e.target
+    const touch = e.pointerType === 'touch' || e.pointerType === 'pen'
+    record('click', el, null, touch ? { tap: 1 } : undefined)
+    const t = now()
+    while (clicks.length && t - clicks[0].t > RAGE_MS) clicks.shift()
+    clicks.push({ el, t })
+    const same = clicks.filter(c => c.el === el).length
+    if (same === RAGE) record('rage', el, same)
+    const plainLink = el.tagName === 'A' && !el.hasAttribute('target') && !el.hasAttribute('download') && route(attr(el, 'href'))
+    // dead click: a control that changed nothing (no DOM mutation, no navigation, no focus move) within a second
+    if (actionable(e.target) && !FIELDS.test(el.tagName) && (el.tagName !== 'A' || plainLink)) {
+      const seen = changes()
+      const href = loc().href
+      const active = doc.activeElement
+      setTimeout(() => {
+        if (changes() === seen && loc().href === href && doc.activeElement === active) record('dead', el)
+      }, DEAD_MS)
+    }
+  })
+  listen('keydown', e => {
+    const el = actionable(e.target)
+    if (!el || (e.key !== 'Enter' && e.key !== ' ')) return
+    const textual = el.tagName === 'TEXTAREA' || (el.tagName === 'INPUT' && !/^(checkbox|radio|button|submit|reset)$/.test(attr(el, 'type')))
+    if (!textual) record('key', el, null, { key: e.key === ' ' ? 'space' : 'enter' })
+  })
+  const focused = new Map()
+  const typed = new Map()
+  const flushInputs = () => {
+    for (const [el, n] of typed) record('input', el, n)
+    typed.clear()
+  }
+  listen('focusin', e => {
+    const el = actionable(e.target)
+    if (el) focused.set(el, now())
+  })
+  listen('focusout', e => {
+    const el = actionable(e.target)
+    if (!el || !focused.has(el)) return
+    if (typed.has(el)) record('input', el, typed.get(el)), typed.delete(el)
+    record('focus', el, now() - focused.get(el))
+    focused.delete(el)
+  })
+  listen('input', e => {
+    const el = actionable(e.target)
+    if (el) typed.set(el, (typed.get(el) || 0) + 1) // one coalesced `input` event per field visit, never the value
+  })
+  listen('change', e => {
+    const el = e.target
+    if (!el || el.nodeType !== 1) return
+    const kind = attr(el, 'type')
+    if (el.tagName === 'INPUT' && (kind === 'checkbox' || kind === 'radio')) record('toggle', el, secret(el) ? null : el.checked ? 1 : 0)
+    else if (el.tagName === 'SELECT') record('toggle', el, secret(el) ? null : el.selectedIndex)
+    else record('change', el)
+  })
+  listen('toggle', e => {
+    if (e.target && e.target.tagName === 'DETAILS') record('toggle', e.target, e.target.hasAttribute('open') ? 1 : 0)
+  })
+  const invalid = new WeakSet()
+  listen('submit', e => record('submit', e.target, null, { o: 'sent' }))
+  listen('invalid', e => {
+    const form = e.target && e.target.form
+    if (!form || invalid.has(form)) return
+    invalid.add(form)
+    setTimeout(() => invalid.delete(form), RAGE_MS)
+    record('submit', form, null, { o: 'invalid' })
+  })
+  for (const k of ['copy', 'cut', 'paste', 'drop']) listen(k, e => record(k, actionable(e.target) || e.target))
+  listen('dragstart', e => record('drag', actionable(e.target) || e.target))
+  listen('contextmenu', e => record('context', actionable(e.target) || e.target))
+  for (const a of ['play', 'pause', 'seeked', 'ended'])
+    listen(a, e => {
+      const el = e.target
+      if (el && /^(VIDEO|AUDIO)$/.test(el.tagName)) record('media', el, el.currentTime, { a })
+    })
+  const hovered = new WeakSet()
+  let hover = null
+  listen('pointerover', e => {
+    const el = actionable(e.target)
+    if (!el || hovered.has(el) || (hover && hover.el === el)) return
+    if (hover) clearTimeout(hover.t)
+    hover = { el, t: setTimeout(() => (hovered.add(el), (hover = null), record('hover', el, HOVER_MS)), HOVER_MS) }
+  })
+  listen('pointerout', e => {
+    if (hover && actionable(e.target) === hover.el) clearTimeout(hover.t), (hover = null)
+  })
+  listen('scroll', scrolled, win)
+
+  // ── SPA navigation, visibility, page exit
+  const history = env.history
+  if (history)
+    for (const m of ['pushState', 'replaceState']) {
+      const orig = history[m]
+      if (typeof orig === 'function')
+        history[m] = function (...a) {
+          const r = orig.apply(this, a)
+          navigated()
+          return r
+        }
+    }
+  listen('popstate', navigated, win)
+  listen('visibilitychange', () => {
+    if (visible()) visibleAt = now()
+    else (visibleMs += now() - visibleAt), flushInputs(), send()
+  })
+  listen('pagehide', () => (leave(), send()), win)
+  const track = (name, props) => {
+    if (!TOKEN.test(String(name))) return
+    const p = { name: String(name) }
+    for (const [k, v] of Object.entries(props || {}).slice(0, 15)) if (/^\w{1,32}$/.test(k) && v !== Object(v)) p[k] = v
+    record('track', null, null, p)
+  }
+  listen('brain:track', e => e.detail && track(e.detail.name, e.detail.props), win)
+  listen('click', e => {
+    const el = actionable(e.target)
+    const name = el && attr(el, 'data-track')
+    if (TOKEN.test(name)) track(name)
+  })
+  const stop = () => {
+    stopped = true
+    clearTimeout(timer)
+    for (const f of off) f()
+    if (mo) mo.disconnect()
+  }
+  page()
+  return { track, send, stop, queue: () => queue, describe }
+}

package/brain-budget.js

@@ -1,63 +1,84 @@
 // Preventive checkpoints for compiler-owned code. Native/foreign calls cannot be preempted here.
 import { _rt, fx } from './brain.js'
 const I = _rt(), owners = new WeakMap(), active = []
-const LIMITS = Object.freeze({ steps: 1000000, depth: 128, ms: 200, rows: 100000, signals: 100000, resources: 1024, pending: 32, workerMs: 30000 })
-const now = () => globalThis.performance ? performance.now() : Date.now()
-const metaOf = m => ({ file: typeof m?.file === 'string' ? m.file.slice(0, 256) : null, component: typeof m?.component === 'string' ? m.component.slice(0, 80) : null, line: Number.isSafeInteger(m?.line) && m.line > 0 ? m.line : null, column: Number.isSafeInteger(m?.column) && m.column > 0 ? m.column : null })
-const limitsOf = options => Object.fromEntries(Object.entries(LIMITS).map(([k, max]) => [k, Number.isFinite(options?.[k]) && options[k] >= 1 ? Math.min(max, options[k]) : max]))
-const failure = (code, kind, limit, meta) => Object.assign(new Error(`${code}: ${kind} budget exceeded`), { code, kind: 'budget', budget: kind, limit, ...metaOf(meta), fix: kind === 'ms' || kind === 'steps' || kind === 'depth' ? 'Bound the work or move it to an owned worker.' : 'Bound the collection and dispose resources with their owner.' })
+const LIMITS = { steps: 1000000, depth: 128, ms: 200, rows: 100000, signals: 100000, resources: 1024, pending: 32, workerMs: 30000 } // module-private, never mutated
+const now = () => performance.now()
+const str = (v, n) => typeof v == 'string' ? v.slice(0, n) : null, pos = v => v > 0 ? v | 0 : null
+const metaOf = m => ({ file: str(m?.file, 256), component: str(m?.component, 80), line: pos(m?.line), column: pos(m?.column) })
+const limitsOf = options => Object.fromEntries(Object.entries(LIMITS).map(([k, max]) => [k, Math.min(max, options?.[k] >= 1 ? options[k] : max)]))
+const failure = (code, kind, limit, meta) => Object.assign(new Error(`${code}: ${kind} budget exceeded`), { code, kind: 'budget', budget: kind, limit, ...metaOf(meta), fix: code == 'B0910' ? 'Bound the work or use an owned worker.' : 'Bound it; dispose with its owner.' })
+const start = r => { r.running = true; r.started = now() }
 function charge(root) {
-  if (root.running) { const t = now(); root.work += Math.max(0, t - root.started); root.started = t }
+  if (root.running) { const t = now(); root.work += t - root.started; root.started = t }
 }
+// Elapsed time is wall-clock (browsers expose no CPU clock): a loaded machine inflates it, so an overrun is a
+// diagnostic, not a failure. It is reported once per execution with its source and measured time, without an owner
+// (no error boundary replaces the view), and the page keeps running. Steps and depth are deterministic and always
+// fatal: they stop runaway loops and recursion.
 function enforce(frame, kind, value) {
   const r = frame.root
   if (r.error) throw r.error
-  if (value > r.limits[kind]) throw (r.error = failure('B0910', kind, r.limits[kind], frame.meta))
+  if (value > r.limits[kind]) {
+    const e = failure('B0910', kind, r.limits[kind], frame.meta)
+    if (kind != 'ms') throw (r.error = e)
+    r.limits.ms = 1 / 0
+    console.warn(e.message += ` at ${e.file}:${e.line}: ${e.measured = value | 0} ms`), I.oops(e, null, 'budget')
+  }
 }
 export function budgetOwner() { return I.owner() }
 export function budgetEnter(meta, owner = I.owner(), options) {
-  const parent = active[active.length - 1]
-  const root = parent?.root || { limits: limitsOf(options), steps: 0, work: 0, depth: 0, running: false, started: 0, error: null }
+  const parent = active.at(-1)
+  const root = parent?.root || { limits: limitsOf(options), steps: 0, work: 0, depth: 0 }
   const f = { root, meta: metaOf(meta), owner, state: 'active' }
   charge(root)
   enforce(f, 'depth', root.depth + 1)
   root.depth++
-  if (!root.running) { root.running = true; root.started = now() }
+  if (!root.running) start(root)
   active.push(f)
   return f
 }
 export function budgetStep(frame, site) {
-  if (!frame || frame.state !== 'active') throw failure('B0910', 'inactive-frame', 0, site)
+  if (!frame || frame.state != 'active') throw failure('B0910', 'inactive-frame', 0, site)
   if (site) frame.meta = metaOf(site)
   const r = frame.root
+  // A synchronous throw inside a paused await expression must not leave the clock stopped.
+  if (frame.paused) frame.paused = 0, start(r)
   charge(r)
   enforce(frame, 'steps', ++r.steps)
   enforce(frame, 'ms', r.work)
 }
 function detach(f) {
-  if (f.state !== 'active') return
+  if (f.state != 'active') return
   const index = active.lastIndexOf(f)
   if (index >= 0) active.splice(index, 1)
   const r = f.root
   charge(r)
   r.depth--
-  if (!active.some(x => x.root === r)) r.running = false
+  // Native code continuing a paused await expression is not charged.
+  const top = active.at(-1)
+  if (top?.root != r || top.paused) r.running = false
 }
 export function budgetLeave(frame) {
-  if (!frame || frame.state === 'closed') return
+  if (!frame || frame.state == 'closed') return
   detach(frame)
   frame.state = 'closed'
 }
+// Generated as `budgetSuspend(frame)(expr)`: the clock stops before `expr` runs, so native work
+// (a fetch's connection setup) is not charged; author functions called inside it restart the clock.
 // The outcome always resolves: the generated resume runs even on a rejected await, preserving catch/finally.
-export function budgetSuspend(frame, promise) {
-  detach(frame)
-  frame.state = 'suspended'
-  return Promise.resolve(promise).then(value => ({ ok: true, value }), error => ({ ok: false, error }))
+export function budgetSuspend(frame) {
+  if (frame.state == 'active') charge(frame.root), frame.root.running = false, frame.paused = 1
+  return promise => {
+    frame.paused = 0
+    detach(frame)
+    frame.state = 'suspended'
+    return Promise.resolve(promise).then(value => ({ ok: true, value }), error => ({ ok: false, error }))
+  }
 }
 export function budgetResume(frame, outcome) {
-  if (frame.state !== 'suspended') throw failure('B0910', 'inactive-frame', 0, frame.meta)
+  if (frame.state != 'suspended') throw failure('B0910', 'inactive-frame', 0, frame.meta)
   const r = frame.root
-  if (!r.running) { r.running = true; r.started = now() }
+  if (!r.running) start(r)
   r.depth++
   frame.state = 'active'
   active.push(frame)
@@ -67,11 +88,11 @@ export function budgetResume(frame, outcome) {
   return outcome.value
 }
 function ledger(owner, meta, options) {
-  if (!owner || typeof owner !== 'object') throw failure('B0911', 'missing-owner', 0, meta)
-  if (owner.s === 3) throw failure('B0911', 'disposed-owner', 0, meta)
+  if (!owner || typeof owner != 'object') throw failure('B0911', 'missing-owner', 0, meta)
+  if (owner.s == 3) throw failure('B0911', 'disposed-owner', 0, meta)
   let l = owners.get(owner)
   if (!l) {
-    l = { limits: limitsOf(options), counts: Object.create(null), releases: new Set(), disposed: false }
+    l = { limits: limitsOf(options), counts: {}, releases: new Set(), disposed: false }
     owners.set(owner, l)
     I.root(() => fx(() => () => {
       l.disposed = true
@@ -86,10 +107,10 @@ function ledger(owner, meta, options) {
 export function budgetAllocation(kind, owner, units) {
   if (!owner) return // Module-level shared state has no disposable component owner.
   if (!['rows', 'signals'].includes(kind) || !Number.isSafeInteger(units) || units < 0) throw failure('B0911', 'invalid-allocation', 0, null)
-  const frame = active[active.length - 1]
+  const frame = active.at(-1)
   const meta = frame?.meta
   const l = ledger(owner, meta)
-  const next = kind === 'signals' ? (l.counts.signals || 0) + units : units
+  const next = kind == 'signals' ? (l.counts.signals || 0) + units : units
   if (next > l.limits[kind]) throw failure('B0911', kind, l.limits[kind], meta)
   l.counts[kind] = next
 }

package/brain-ch.js

@@ -119,12 +119,14 @@ export function store(init, o = {}, id) {
     const base = JSON.stringify(snap()) // the state as created: changes made before the module loads are still saved
     READY.push(import('./brain-persist.js').then(m => m.persist({ key: P, v, big, apply, snap, S, base })))
   }
+  let onStorage = null
   if (o.sync === 'storage' && G.localStorage) {
     try {
       const v = localStorage.getItem(K)
       if (v) apply(JSON.parse(v, safe))
     } catch {}
-    G.addEventListener && G.addEventListener('storage', e => e.key === K && e.newValue && apply(JSON.parse(e.newValue, safe)))
+    onStorage = e => e.key === K && e.newValue && apply(JSON.parse(e.newValue, safe))
+    G.addEventListener && G.addEventListener('storage', onStorage)
   }
   const bc = o.sync === 'tab' && G.BroadcastChannel ? new BroadcastChannel(K) : null
   const w = o.sync === 'ws' && G.WebSocket ? ws(o.url || '/_ws', K, apply) : null
@@ -155,6 +157,14 @@ export function store(init, o = {}, id) {
           }
       }),
     I.owner())
+  // a store owned by a subtree (provide inside a component) releases its channel, listener and socket with it;
+  // a global store (channels/, no owner) lives as long as the page
+  if (o.sync && I.owner())
+    I.root(() => fx(() => () => {
+      if (bc && bc.close) bc.close()
+      if (onStorage && G.removeEventListener) G.removeEventListener('storage', onStorage)
+      if (w) w.close()
+    }), I.owner())
   return s
 }
 
@@ -199,8 +209,9 @@ function ws(url, s, apply) {
       }
     }
     const now = () => ((n = 0), open())
+    const shown = () => document.visibilityState === 'visible' && open()
     G.addEventListener && G.addEventListener('online', now)
-    G.document && document.addEventListener && document.addEventListener('visibilitychange', () => document.visibilityState === 'visible' && open())
+    G.document && document.addEventListener && document.addEventListener('visibilitychange', shown)
     c = {
       subs,
       sub(k, f) {
@@ -212,14 +223,16 @@ function ws(url, s, apply) {
         off = true
         clearTimeout(t)
         sock && sock.close()
-        WS.delete(url)
+        if (WS.get(url) === c) WS.delete(url)
         G.removeEventListener && G.removeEventListener('online', now)
+        G.document && document.removeEventListener && document.removeEventListener('visibilitychange', shown)
       },
     }
     WS.set(url, c)
   }
   c.sub(s, apply)
-  return { send: d => c.send(s, d), close: () => (c.subs.delete(s), c.subs.size || c.close()) }
+  let gone = false // $close() and the owner's cleanup may both run: release once
+  return { send: d => c.send(s, d), close: () => gone || ((gone = true), c.subs.delete(s), c.subs.size || c.close()) }
 }
 
 // Shape of a store: field names + kind of each initial value. A persisted state with another shape is discarded.

package/brain-data.js

@@ -186,8 +186,9 @@ function request(path, M, def, arg, o) {
   // optimistic: () => (list = [...list, item]) — applied now, undone if the request fails
   const undo = o.optimistic ? rec(o.optimistic) : null
   // a call made from an event handler is cancelled when its component unmounts (brain-guard keeps `$c` on its nodes)
+  let reg = null
   if (!CUR && G.event && G.event.target) for (let el = G.event.target; el; el = el.parentNode) if (el.$c) {
-    const c = el.$c
+    const c = (reg = el.$c)
     c.add(ctl)
     ctl.signal.addEventListener('abort', () => c.delete(ctl))
     break
@@ -238,6 +239,8 @@ function request(path, M, def, arg, o) {
     batch(() => { for (let i = undo.length - 2; i >= 0; i -= 2) undo[i].v = undo[i + 1] })
     throw e
   })
+  // a settled request leaves its component's registry: a long-lived view must not keep every finished call
+  if (reg) p.then(() => reg.delete(ctl), () => reg.delete(ctl))
   p.cancel = () => ctl.abort()
   if (file) Object.defineProperty(p, 'progress', { get: () => up.v }) // 0–1, a signal read
   return p

package/brain-env.js

@@ -24,10 +24,11 @@ export function mounted(f) {
   onDispose(() => ((alive = false), typeof c === 'function' && c()))
 }
 
-// watch(() => src, (v, old) => …): runs the callback when the source changes, not on the first read; the callback is
-// not tracked. A returned function is its cleanup (before the next run and on unmount).
-export function watch(src, cb) {
-  let first = true, old
+// watch(() => src, (v, old) => …): runs the callback when the source changes, not on the first read (with
+// `{ immediate: true }` also once with the initial value, `old` undefined); the callback is not tracked. A returned
+// function is its cleanup (before the next run and on unmount).
+export function watch(src, cb, options) {
+  let first = !options?.immediate, old
   fx(() => {
     const v = src()
     if (first) return void ((first = false), (old = v))