@christianirack/brainllm-runtime 0.0.0-stage → 0.3.1

package/brain-guard.js

@@ -0,0 +1,242 @@
+// BRAINLLM component boundaries (INTERNALS §42). The compiler wraps every comp/, views/ and app.brain component as
+// `guard(Comp, '<meta fallback text>')`; nothing for the author to write. The core routes each error to the nearest
+// boundary (owner chain for fx/drv/list rows, DOM ancestors for handlers):
+//  - render, fx, drv, list rows: the component's effects stop and its nodes are replaced by the fallback — a short
+//    notice with a Retry button that remounts only this component (3 failures in 10 s → no button, no retry loop);
+//  - event handlers (sync, or an async one whose await rejects): the component stays as it was and the user sees a
+//    short toast (the error's message for HTTP errors, a generic one otherwise).
+// The error itself is reported first by the core (brain-err when present, else the console). During SSR the failing
+// component renders its fallback into the HTML and the error is collected in globalThis.__brainSSR for the server log.
+import { _rt, fx, sig } from './brain.js'
+
+const G = globalThis, I = _rt(), LIMIT = 3, WINDOW = 10000
+const TEXT = 'This section could not load.'
+
+// ---------- circuit breaker (§30.3) ----------
+// Per instance budgets, checked as its effects run: runs of one effect per second, continuous work per flush (over budget in
+// 3 flushes in a row), and, once per flush that touched it, its DOM nodes (a native count) and list rows (a walk, only when it has
+// more nodes than the rows budget, at most once a second unless it grew by a quarter: QA #302, counting every 64 runs cost 250 ms per
+// jsfb operation). Crossing one trips THAT instance: its effects stop, a neutral notice replaces it
+// (no Retry: it would trip again), B0908 is reported with the budget, the value and the component; the rest of the
+// page keeps running. Defaults below; `guard(C, fb, { rows: 200000 })` (from `<meta budget="rows:200000">`) overrides.
+// nodes 200 000 and rows 100 000 (QA #302/#303): a legitimate 10,000-row table is ~80 000 nodes, measured without the
+// rows walk
+const BUDGET = { nodes: 200000, rows: 100000, runs: 1000, ms: 200 }
+const STOPPED = 'This part stopped to protect the page.'
+const OWN = new WeakMap() // root owner → instance
+const now = () => (G.performance ? performance.now() : Date.now())
+// work per flush: the time between two effect runs belongs to the earlier one (the hook fires as a run starts); the
+// last run of a flush is settled by a microtask queued at the flush's first run
+let LX = null, LT = 0, inFlush = false
+const touched = new Set()
+// elements under a root, and the most element children any one of them has (the rows of a list)
+const count = (e, c) => {
+  if (e.nodeType !== 1) return
+  c.nodes++
+  let k = 0
+  for (const n of e.childNodes) if (n.nodeType === 1) k++, count(n, c)
+  if (k > c.rows) c.rows = k
+}
+// elements under a root: native when the DOM has it (the shim walks)
+const elems = r => {
+  if (r.nodeType !== 1) return 0
+  if (r.getElementsByTagName) return 1 + r.getElementsByTagName('*').length
+  const c = { nodes: 0, rows: 0 }
+  count(r, c)
+  return c.nodes
+}
+const size = (x, t) => {
+  if (x.off) return
+  let n = 0
+  for (const r of x.nodes()) n += elems(r)
+  if (n > x.b.nodes) return x.trip('nodes', n)
+  if (n > x.b.rows && (t - x.rt > 1000 || n > 1.25 * x.rn)) {
+    x.rt = t
+    x.rn = n
+    const c = { nodes: 0, rows: 0 }
+    for (const r of x.nodes()) count(r, c)
+    if (c.rows > x.b.rows) x.trip('rows', c.rows)
+  }
+}
+const settle = t => {
+  if (LX && !LX.off) LX.work += t - LT
+}
+// a busy device can make one flush slow: only an instance over budget in 3 flushes in a row is runaway work
+const close = x => {
+  if (x.off) return
+  x.slow = x.work > x.b.ms ? (x.slow || 0) + 1 : 0
+  if (x.slow >= 3) x.trip('ms', Math.round(x.work))
+}
+// the hook fires as an effect starts running: N.prototype.r is wrapped (the core has no hook for it, #288). A first run
+// (no sources yet) cannot be a loop: it only closes the work of the run before it (QA #302: creating 1,000 rows is 3,000
+// first runs, and the full check on each one was the slowdown).
+const NP = sig(0).constructor.prototype, run = NP.r
+NP.r = function () {
+  if (this.e)
+    try {
+      this.S ? check(this) : born()
+    } catch {} // the breaker never breaks a page
+  return run.call(this)
+}
+function born() {
+  const t = now()
+  settle(t)
+  LX = null
+  LT = t
+}
+function check(n) {
+  let o = n
+  while (o && !OWN.has(o)) o = o.p
+  const x = o && OWN.get(o), t = now()
+  settle(t)
+  LX = x && !x.off ? x : null
+  LT = t
+  if (!inFlush) {
+    inFlush = true
+    queueMicrotask(() => {
+      settle(now())
+      LX = null
+      inFlush = false
+      const t = now()
+      for (const y of touched) close(y), size(y, t), (y.work = 0)
+      touched.clear()
+    })
+  }
+  if (!LX) return
+  touched.add(x)
+  // runs of ONE effect per second (QA #290): creating or updating 1,000 rows runs 1,000 different effects once each,
+  // which is legitimate; a runaway loop re-runs the same effect. Runaway = over budget in 2 consecutive seconds, or 10×
+  // the budget inside one second.
+  if (t - x.t0 > 1000) (x.hot = x.max > x.b.runs && t - x.t0 < 2000 ? (x.hot || 0) + 1 : 0), (x.t0 = t), (x.max = 0), (x.per = new WeakMap())
+  const k = (x.per.get(n) || 0) + 1
+  x.per.set(n, k)
+  if (k > x.max) x.max = k
+  if (k > x.b.runs && (x.hot >= 1 || k > 10 * x.b.runs)) return x.trip('runs', k)
+}
+
+let tEl = null, tT = 0
+function toast(msg) {
+  const d = G.document
+  if (!d || !d.body) return
+  if (!tEl) {
+    tEl = d.createElement('div')
+    tEl.setAttribute('role', 'status')
+    tEl.setAttribute('aria-live', 'polite')
+    tEl.setAttribute('class', 'brain-toast')
+    tEl.setAttribute('style',
+      'position:fixed;left:50%;bottom:16px;transform:translateX(-50%);max-width:90vw;z-index:2147483647;padding:10px 14px;' +
+      'border-radius:var(--radius-sm);border:1px solid var(--line);background:var(--surface);color:var(--fg);box-shadow:var(--shadow);font:14px/1.4 var(--font)')
+    d.body.appendChild(tEl)
+  }
+  tEl.textContent = msg
+  tEl.removeAttribute('hidden')
+  clearTimeout(tT)
+  tT = setTimeout(() => tEl.setAttribute('hidden', ''), 4000)
+}
+// HTTP/API errors carry a message meant for people (ApiError, rpc); anything else gets a generic line
+const human = e => (e && (e.kind || e.status || e.code === 'rpc' || e.code === 'api') && e.message) || 'Something went wrong. Try again.'
+
+export function guard(C, fb, budget) {
+  const W = $p => {
+    const own = I.owner(), end = G.document.createComment('')
+    let nodes = [], dispose = null, fails = []
+    const notice = (retry, text) => {
+      if (typeof fb === 'function' && !text) return I.nodes(fb())
+      const box = G.document.createElement('div')
+      box.setAttribute('role', 'alert')
+      box.setAttribute('class', 'brain-fallback')
+      box.textContent = text || fb || TEXT
+      if (retry) {
+        const b = G.document.createElement('button')
+        b.setAttribute('type', 'button')
+        b.textContent = 'Retry'
+        b.addEventListener('click', () => again())
+        box.appendChild(G.document.createTextNode(' '))
+        box.appendChild(b)
+      }
+      return [box]
+    }
+    const report = (e, w) => {
+      if (G.__brainSSR) G.__brainSSR.push({ e, w, comp: W.f || C.f || C.name || null })
+    }
+    let building = false, pending = null
+    const fall = (e, w, text) => {
+      if (building) return void (pending = pending || [e, w]) // a child effect failed while this builds: settled by build()
+      const now = Date.now()
+      fails = [...fails.filter(t => now - t < WINDOW), now]
+      if (dispose) dispose(), (dispose = null) // stops its fx, drv and handlers
+      const p = end.parentNode
+      I.rm(nodes)
+      nodes = notice(!text && fails.length < LIMIT, text)
+      if (p) for (const n of nodes) p.insertBefore(n, end)
+      report(e, w)
+    }
+    // breaker state of this instance (see NP.r above)
+    const x = {
+      b: budget ? { ...BUDGET, ...budget } : BUDGET,
+      t0: now(), // the first runs window belongs to this instance, not the process clock epoch
+      rt: -1e9, // last rows walk (performance.now() starts near 0 with the page)
+      rn: 0, // nodes at that walk: a list that grew by a quarter is walked again sooner
+      max: 0, // most runs of one effect in this second
+      per: new WeakMap(), // effect → its runs in this second
+      work: 0,
+      off: false,
+      nodes: () => nodes,
+      trip(k, v) {
+        x.off = true
+        const e = Object.assign(Error(`B0908: ${W.f || C.f || C.name || 'a component'} crossed its ${k} budget (${v} > ${x.b[k]}); it was stopped to protect the page`), { code: 'B0908', budget: k, value: v, limit: x.b[k], comp: W.f || C.f || null })
+        I.oops(e, null, 'B0908') // reported (brain-err, dev overlay, doctor); the boundary handles it below
+        queueMicrotask(() => fall(e, 'B0908', STOPPED)) // after the run that tripped it
+      },
+    }
+    const handler = (e, w) => (String(w).startsWith('on:') ? (toast(human(e)), report(e, w)) : fall(e, w))
+    // requests started from this component's handlers (brain-data registers them in `$c`): cancelled with it
+    const reqs = new Set()
+    const build = () =>
+      I.root(d => {
+        dispose = d
+        if (!G.__brainSSR) OWN.set(I.owner(), x)
+        x.off = false
+        I.guard(I.owner(), handler)
+        fx(() => () => reqs.forEach(c => c.abort()))
+        building = true
+        pending = null
+        try {
+          nodes = I.nodes(C($p))
+        } catch (e) {
+          I.oops(e, null, 'render') // report only (no owner: the boundary itself handles it below)
+          pending = [e, 'render']
+        } finally {
+          building = false
+        }
+        // the render threw, or one of its effects failed during it: the half-built nodes never reach the page
+        if (pending) {
+          d()
+          dispose = null
+          const now = Date.now()
+          fails = [...fails.filter(t => now - t < WINDOW), now]
+          nodes = notice(fails.length < LIMIT)
+          report(pending[0], pending[1])
+          pending = null
+        }
+        for (const n of nodes) if (n.nodeType === 1) (n.$g = handler), (n.$c = reqs)
+      }, own)
+    function again() {
+      const p = end.parentNode
+      I.rm(nodes)
+      build()
+      if (p) for (const n of nodes) p.insertBefore(n, end)
+    }
+    build()
+    // when the parent unmounts this component, whatever it shows now (content or fallback) goes with it
+    if (own)
+      I.root(() => fx(() => () => {
+        if (dispose) dispose()
+        for (const n of nodes) if (n.nodeType === 1) (n.$g = null), (n.$c = null) // see brain-dev: no node → instance links
+        I.rm(nodes)
+      }), own)
+    return [...nodes, end]
+  }
+  // every static the compiler puts on the component (h, f, p, form, seo, head…) stays visible on the wrapper
+  return Object.assign(W, C, { C })
+}

package/brain-hydrate.js

@@ -0,0 +1,72 @@
+// BRAINLLM hydration by adoption (#285, with COMPILER #143). An island resumes on the server's own nodes instead of
+// replacing them, so internal scroll, a playing <video>, focus and CSS animations survive. No imports: the core and
+// brain-island hand it what it needs (a static import of the core would make a hash cycle).
+// How: while the server renders (stamp), every template clone gets `data-hk="<n>"` in render order and every dynamic
+// region is wrapped as <!--[--> … <!--]--> (its anchor comment becomes `]`). While hydrating (adopter), the same render
+// order claims the stamped node instead of cloning, and each region reuses what the server put there.
+// Codegen (COMPILER) navigates with fc/nx instead of .firstChild/.nextSibling: on a fresh clone they are the same, on
+// adopted server HTML they step over a whole region to its anchor.
+
+// first child / next sibling, stepping over a server-rendered dynamic region to its `]` anchor
+const sk = (y, d = 0) => {
+  for (; y; y = y.nextSibling)
+    if (y.data == '[') d++
+    else if (y.data == ']' ? !--d : !d) return y
+}
+export const fc = e => sk(e.firstChild)
+export const nx = n => sk(n.nextSibling)
+
+// Server render (server.mjs, the build's prerender): `const end = stamp(_rt())` before mounting, `end()` after.
+export function stamp(I, doc = globalThis.document) {
+  let c = 0
+  I.adopt({
+    t(n) {
+      const x = n.cloneNode(true)
+      if (x.nodeType === 1) x.setAttribute('data-hk', String(++c))
+      return x
+    },
+    p(end, a) {
+      const p = end.parentNode
+      if (!end.$m) (end.$m = 1), (end.data = ']'), p.insertBefore(doc.createComment('['), end)
+      for (const n of a) p.insertBefore(n, end)
+      return a
+    },
+  })
+  return () => I.adopt(null)
+}
+
+// Hydration of the server's subtree `root` (brain-island): claims stamped nodes in render order; throws on any
+// mismatch so the caller falls back to rendering fresh (a fragment template, another tag, a missing stamp).
+export function adopter(root) {
+  const els = [...root.querySelectorAll('[data-hk]')]
+  if (root.getAttribute('data-hk')) els.unshift(root)
+  const by = new Map(els.map(e => [+e.getAttribute('data-hk'), e]))
+  if (!by.size) throw Error('adopt: nothing stamped')
+  const base = Math.min(...by.keys())
+  let c = 0
+  return {
+    t(n) {
+      const e = by.get(base + c++)
+      if (!e || n.nodeType !== 1 || e.tagName !== n.tagName) throw Error('adopt: the server rendered something else')
+      return e
+    },
+    p(end, a) {
+      // the region the server rendered before this anchor: from its matching `[` to `]`
+      const ex = []
+      if (end.data == ']')
+        for (let y = end.previousSibling, d = 0; y; y = y.previousSibling) {
+          if (y.data == ']') d++
+          else if (y.data == '[' && !d--) break
+          ex.push(y)
+        }
+      ex.reverse()
+      // texts reuse the server's text node; adopted elements are already there; anything else goes in
+      const out = a.map((n, i) => (n.nodeType === 3 && ex[i] && ex[i].nodeType === 3 ? (ex[i].data !== n.data && (ex[i].data = n.data), ex[i]) : n))
+      const keep = new Set(out)
+      for (const y of ex) if (!keep.has(y)) y.remove()
+      const p = end.parentNode
+      for (const n of out) if (n.parentNode !== p) p.insertBefore(n, end) // never move a node already in place
+      return out
+    },
+  }
+}

package/brain-i18n.js

@@ -0,0 +1,111 @@
+// BRAINLLM languages (INTERNALS §37): our own small standard, no library. Static `t('key')` calls are resolved by the
+// compiler; this module serves what is left at runtime (plurals, dynamic keys, islands) plus formatting and the switcher.
+// Dictionaries arrive per view and locale as chunks that call `add(locale, { key: text | { one, other, … } })` before
+// the page mounts; only the current locale is ever loaded (switching language is a full load of the other URL).
+const G = globalThis
+// locale → { key: text | plural object }. One table for the whole process: the server and the prerender may load this
+// module twice (their own copy and the build's), and a dictionary added through either must be seen by both (BUILD)
+const D = (G.__brainDict ||= {})
+const RTL = /^(ar|he|fa|ur|ps|sd|ug|yi|dv)(-|$)/i
+let warned = null
+
+export function add(loc, dict) {
+  Object.assign((D[loc] ||= {}), dict)
+}
+// The page's language: the server sets __brainLocale while it renders; in the browser it is <html lang>.
+export function locale() {
+  return G.__brainLocale || (G.document && document.documentElement && document.documentElement.getAttribute('lang')) || 'en'
+}
+const def = () => (G.document && document.documentElement && document.documentElement.getAttribute('data-default-lang')) || 'en'
+export const dirOf = loc => (RTL.test(loc) ? 'rtl' : 'ltr')
+
+// t('posts.count', { n: 3 }) → '3 posts'. A plural object is chosen by Intl.PluralRules on `n` (or `count`); `=0`-style
+// exact keys win. `{var}` placeholders: numbers are formatted for the locale. A missing key falls back to the default
+// locale, then to the key itself (reported once in dev).
+export function t(key, vars) {
+  const loc = locale()
+  let m = (D[loc] && D[loc][key]) ?? (D[def()] && D[def()][key])
+  if (m == null) {
+    if (G.__brainDev && (warned ||= new Set()) && !warned.has(key)) warned.add(key), console.warn(`i18n: missing key "${key}" for ${loc}`)
+    return key
+  }
+  if (typeof m === 'object') {
+    const n = vars && (vars.n ?? vars.count)
+    m = m['=' + n] ?? m[pr(loc).select(+n || 0)] ?? m.other ?? ''
+    if (vars && vars.n == null) vars = { ...vars, n } // `{n}` works with either name
+  }
+  return vars ? m.replace(/\{(\w+)\}/g, (s, k) => (k in vars ? (typeof vars[k] === 'number' ? fmt.number(vars[k]) : String(vars[k])) : s)) : m
+}
+
+const cache = new Map()
+const memo = (k, f) => (cache.has(k) ? cache.get(k) : (cache.set(k, f()), cache.get(k)))
+const pr = loc => memo('p' + loc, () => new Intl.PluralRules(loc))
+const nf = (loc, o) => memo('n' + loc + JSON.stringify(o), () => new Intl.NumberFormat(loc, o))
+const df = (loc, o) => memo('d' + loc + JSON.stringify(o), () => new Intl.DateTimeFormat(loc, o))
+const rf = loc => memo('r' + loc, () => new Intl.RelativeTimeFormat(loc, { numeric: 'auto' }))
+const UNITS = [['year', 31536e6], ['month', 2592e6], ['week', 6048e5], ['day', 864e5], ['hour', 36e5], ['minute', 6e4], ['second', 1e3]]
+
+// Formatting for the current locale, over Intl (cached formatters).
+export const fmt = {
+  number: (n, o) => nf(locale(), o).format(n),
+  money: (n, currency = 'USD', o) => nf(locale(), { style: 'currency', currency, ...o }).format(n),
+  date: (d, o = { dateStyle: 'medium' }) => df(locale(), o).format(new Date(d)),
+  // "3 days ago", "in 2 hours", "yesterday": the largest unit that fits
+  relative(d, now = Date.now()) {
+    const ms = new Date(d) - now
+    for (const [u, size] of UNITS) if (Math.abs(ms) >= size || u === 'second') return rf(locale()).format(Math.round(ms / size), u)
+  },
+}
+
+// The same page in every language of the site, from the <link rel="alternate" hreflang> tags the build emits; keeps the
+// current query and hash; each language named in itself ("Deutsch", "Nederlands"). One language → [] (switcher hidden).
+// While the server renders (SSR or prerender) the links come from globalThis.__brainAlternates ([{ locale, href }], set
+// per route from the manifest), so the switcher is in the HTML before any JS runs (§38).
+export function alternates() {
+  const d = G.document, cur = locale(), out = []
+  const links = G.__brainAlternates || (d && d.head ? [...d.head.querySelectorAll('link[rel=alternate][hreflang]')].map(l => ({ locale: l.getAttribute('hreflang'), href: l.getAttribute('href') })) : [])
+  const here = G.location && G.location.href
+  for (const l of links) {
+    if (l.locale === 'x-default') continue
+    let href = l.href
+    if (here) {
+      const u = new URL(l.href, here)
+      u.search = G.location.search
+      u.hash = G.location.hash
+      href = u.pathname + u.search + u.hash
+    }
+    out.push({ locale: l.locale, href, name: nameOf(l.locale), current: l.locale === cur })
+  }
+  return out.length > 1 ? out : []
+}
+const nameOf = loc => {
+  try {
+    const n = new Intl.DisplayNames([loc], { type: 'language' }).of(loc)
+    return n.charAt(0).toLocaleUpperCase(loc) + n.slice(1)
+  } catch {
+    return loc
+  }
+}
+
+// One-time suggestion: the browser prefers another language this site has (never an automatic redirect, §37).
+// Returns { locale, href, name } once per browser, or null; `dismiss()` remembers the answer.
+const SEEN = 'brain:lang-suggested'
+export function suggest() {
+  try {
+    if (G.localStorage && localStorage.getItem(SEEN)) return null
+  } catch {}
+  const alts = alternates(), cur = locale()
+  if (!alts.length || !G.navigator) return null
+  for (const want of navigator.languages || [navigator.language]) {
+    const base = String(want).toLowerCase().split('-')[0]
+    if (cur.toLowerCase().split('-')[0] === base) return null // already in a language the user reads
+    const a = alts.find(x => x.locale.toLowerCase() === String(want).toLowerCase() || x.locale.toLowerCase().split('-')[0] === base)
+    if (a) return { locale: a.locale, href: a.href, name: a.name }
+  }
+  return null
+}
+export function dismiss() {
+  try {
+    G.localStorage && localStorage.setItem(SEEN, '1')
+  } catch {}
+}