@christianirack/brainllm-runtime 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Irack Flores Maldonado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @christianirack/brainllm-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runtime of [BRAINLLM](https://chrisifm.github.io/BRAINLLM/), the web compiler for LLMs built in Rust: dependency-free ES modules (signals, DOM, router, data, forms, channels, service worker, server).
+The `brain` binary embeds this same version and serves it at `/@brain/*`; install this package only for tooling that
+needs the modules on disk.

package/brain-ai.js

@@ -0,0 +1,129 @@
+// Built-in AI (Chrome's on-device Gemini Nano, INTERNALS §19, docs checked 2026-10-29): `ai` is a primitive, so a view
+// uses it without an import. Every call feature-detects the browser API; on the server or in a browser without it,
+// `ai.ready()` answers 'unavailable' and the other calls throw an Error with `code: 'unavailable'`, so the app decides
+// what to show instead. What the model does is up to the app: the runtime only opens the door.
+//   await ai.ready()                       'available' | 'downloadable' | 'downloading' | 'unavailable' (Prompt API)
+//   await ai.ready('summarizer')           same for summarizer, detector, writer, rewriter, proofreader
+//   await ai.ready('translator', { from: 'en', to: 'es' })   the translator needs its two languages
+//   await ai.prompt('Name three colors', { system, schema, signal, onProgress })   → string (stateless call)
+//   for await (const part of ai.stream('Tell a story')) …                          → text chunks as they arrive
+//   const chat = await ai.session({ system })   native session: chat.prompt(), append(), clone(), destroy()
+//   await ai.summarize(text, { type, format, length, context })                     → string
+//   await ai.translate(text, { from: 'en', to: 'es' })                              → string
+//   await ai.detect(text)                                                           → [{ detectedLanguage, confidence }]
+//   await ai.write(task) · ai.rewrite(text, { tone }) · ai.proofread(text)
+// Status (Chrome 138+ stable): Summarizer, Translator and LanguageDetector on the web; the Prompt API is an origin
+// trial on the web (Chrome 148) and stable in extensions; Writer, Rewriter and Proofreader are trials. The Prompt API
+// runs in the top window and same-origin iframes (`allow="language-model"` for others), not in Web Workers. A model
+// that is 'downloadable' starts downloading on the first create, which Chrome only allows after a user gesture: call
+// these from an event handler the first time; `onProgress(0..1)` follows the download.
+const G = globalThis
+const API = {
+  prompt: 'LanguageModel',
+  summarizer: 'Summarizer',
+  translator: 'Translator',
+  detector: 'LanguageDetector',
+  writer: 'Writer',
+  rewriter: 'Rewriter',
+  proofreader: 'Proofreader',
+}
+const native = kind => {
+  const name = API[kind]
+  if (!name) throw Error(`ai: unknown model \`${kind}\`; use one of ${Object.keys(API).join(', ')}`)
+  return G[name] || null
+}
+const missing = kind => Object.assign(Error(`Built-in AI is not available in this browser (${API[kind]})`), { code: 'unavailable' })
+
+// `{ from, to }` are the translator's languages, as in ai.translate (Translator.availability needs them)
+const langs = ({ from, to, ...o } = {}) => ({ ...o, ...(from ? { sourceLanguage: from } : {}), ...(to ? { targetLanguage: to } : {}) })
+async function ready(kind = 'prompt', options) {
+  const N = native(kind)
+  if (!N || !N.availability) return 'unavailable'
+  try {
+    return await N.availability(langs(options))
+  } catch {
+    return 'unavailable'
+  }
+}
+
+// create(options) with the download progress wired to onProgress (e.loaded is 0..1)
+async function create(kind, o = {}) {
+  const N = native(kind)
+  if (!N || !N.create) throw missing(kind)
+  const { onProgress, ...rest } = o
+  if (onProgress) rest.monitor = m => m.addEventListener('downloadprogress', e => onProgress(e.loaded))
+  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()
+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)
+  }
+  return (await bases.get(k)).clone()
+}
+const opts = o => ({ ...(o.signal ? { signal: o.signal } : {}), ...(o.schema ? { responseConstraint: o.schema } : {}) })
+
+async function prompt(text, o = {}) {
+  const s = await base(o)
+  try {
+    const out = await s.prompt(text, opts(o))
+    return o.schema && typeof out === 'string' ? JSON.parse(out) : out
+  } finally {
+    s.destroy && s.destroy()
+  }
+}
+
+async function* stream(text, o = {}) {
+  const s = await base(o)
+  try {
+    for await (const part of s.promptStreaming(text, opts(o))) yield part
+  } finally {
+    s.destroy && s.destroy()
+  }
+}
+
+// a native session that keeps history (a chat); `system` becomes its first prompt
+const session = (o = {}) => {
+  const { system, ...rest } = o
+  return create('prompt', { ...(system ? { initialPrompts: [{ role: 'system', content: system }, ...(rest.initialPrompts || [])] } : {}), ...rest })
+}
+
+// one model per kind and options, created on first use and reused
+const tools = new Map()
+const tool = (kind, o) => {
+  const { onProgress, signal, ...rest } = o || {}
+  const k = kind + JSON.stringify(rest)
+  if (!tools.has(k)) {
+    const p = create(kind, { ...rest, ...(onProgress ? { onProgress } : {}) })
+    p.catch(() => tools.delete(k))
+    tools.set(k, p)
+  }
+  return tools.get(k)
+}
+const call = (kind, method, keys) => async (text, o = {}) => {
+  const make = {}, run = {}
+  for (const [k, v] of Object.entries(o)) (keys.includes(k) ? run : make)[k] = v
+  if (o.signal) run.signal = o.signal
+  return (await tool(kind, make))[method](text, run)
+}
+
+export const ai = {
+  ready,
+  prompt,
+  stream,
+  session,
+  summarize: call('summarizer', 'summarize', ['context']),
+  translate: (text, o = {}) => {
+    const { from, to, ...rest } = o
+    return call('translator', 'translate', ['signal'])(text, { sourceLanguage: from, targetLanguage: to, ...rest })
+  },
+  detect: call('detector', 'detect', []),
+  write: call('writer', 'write', ['context']),
+  rewrite: call('rewriter', 'rewrite', ['context']),
+  proofread: call('proofreader', 'proofread', []),
+}

package/brain-anim.js

@@ -0,0 +1,21 @@
+// BRAINLLM transitions (INTERNALS §41.6): `transition:fade|slide|scale` on an element inside {#if}/{#each} compiles to
+// `transition(el, 'fade', { ms, in, out })` right after the element is created. The enter animation plays once the
+// element is in the document; the exit one is left on the element as `el.$out` (→ Promise), which the core's removal
+// (when/list) waits for before taking the node out. Web Animations API; nothing with prefers-reduced-motion, without
+// `el.animate` or while the server renders.
+const G = globalThis
+const K = {
+  fade: [{ opacity: 0 }, { opacity: 1 }],
+  scale: [{ opacity: 0, transform: 'scale(.95)' }, { opacity: 1, transform: 'none' }],
+  slide: [{ opacity: 0, transform: 'translateY(-8px)' }, { opacity: 1, transform: 'none' }],
+}
+const still = () => !!(G.matchMedia && G.matchMedia('(prefers-reduced-motion: reduce)').matches)
+
+export function transition(el, kind = 'fade', o = {}) {
+  const k = K[kind]
+  if (!k) throw Error(`transition: unknown kind "${kind}" (fade, slide, scale)`)
+  if (!el.animate || G.__brainSSR || G.__brainRoute || still()) return
+  const opts = { duration: o.ms ?? 200, easing: 'cubic-bezier(.22,1,.36,1)' }
+  if (o.in !== false) queueMicrotask(() => el.isConnected && el.animate(k, opts))
+  if (o.out !== false) el.$out = () => el.animate([...k].reverse(), { ...opts, fill: 'forwards' }).finished.catch(() => {})
+}

package/brain-ch.js

@@ -0,0 +1,254 @@
+// BRAINLLM channels (INTERNALS §12): context (provide/use/key), store, bus and exposed API. Props, the `~` model,
+// events (`emit` → `$p["on:x"]`) and slots are resolved by the codegen with no extra runtime.
+// Every channel use notifies `seen` (fn(kind, name, role, owner)): the inspector builds the Graph view without this
+// module retaining owners.
+import { _rt, sig, fx, batch, untrack } from './brain.js'
+
+const G = globalThis
+const I = _rt((pairs, f) => {
+  for (const [k, v] of pairs) provide(k, v)
+  return f()
+})
+export const seen = new Set()
+const note = (k, n, role) => {
+  if (seen.size) for (const f of seen) f(k, n, role, I.owner())
+}
+
+// ---------- context ----------
+// The key is an object exported from channels/*.jsbrain (`export const Theme = key('theme')`): no collisions.
+export const key = (name, d) => ({ name, d })
+const CTX = new WeakMap() // owner N → Map(key → value)
+// Components built afterwards under the same owner see it. To isolate siblings, the codegen wraps the component that
+// calls provide with `scope(C)`: that way the value stays only in its subtree.
+export function provide(k, v) {
+  const o = I.owner()
+  if (!o) throw Error('provide outside a component')
+  const m = CTX.get(o) || (CTX.set(o, new Map()), CTX.get(o))
+  m.set(k, v)
+  note('ctx', k.name, 'provide')
+  return v
+}
+export function use(k) {
+  note('ctx', k.name, 'use')
+  for (let o = I.owner(); o; o = o.p) {
+    const m = CTX.get(o)
+    if (m && m.has(k)) return m.get(k)
+  }
+  if (k.d !== undefined) return k.d
+  throw Object.assign(Error(`B0807: use(${k.name}) without provide(${k.name}) in the ancestors`), { code: 'B0807' })
+}
+// Own owner for a component (the codegen emits it if the component calls provide).
+export const scope = C => Object.assign($p => I.root(() => C($p), I.owner()), { C, h: C.h, f: C.f, p: C.p, form: C.form })
+// Tests and app.brain: mount with provided values (`withProvide([[Api, fakeApi]], () => Comp(props))`).
+export const withProvide = (pairs, f) =>
+  I.root(() => {
+    for (const [k, v] of pairs) provide(k, v)
+    return f()
+  }, I.owner())
+
+// Reactive context read (codegen): `let theme = use(Theme)` → `drv(((u) => () => val(u))(use(Theme)))`. A provided
+// sig/drv is read (tracked); any other value, including objects with a `v` field, is returned as is.
+const N = sig(0).constructor
+export const val = x => (x instanceof N ? x.v : x)
+
+// state from another tab, the server or storage is untrusted JSON: prototype keys are dropped (§31)
+const safe = (k, v) => (k === '__proto__' || k === 'constructor' || k === 'prototype' ? undefined : v)
+
+// ---------- store ----------
+// `store({ items: [], total: 0 })` → object with a reactive getter/setter per field (`cart.items = [...]`).
+// `$set(patch)` writes several in one batch; `$snap()` flat copy; `$reset()` restores init. Valid in channels/ (one
+// global instance) and inside `provide(K, store(…))` (one instance per subtree, §41.2). sync: 'tab' (BroadcastChannel) | 'storage'
+// (localStorage + storage event) | 'ws' (WebSocket at `url`, see ws() below). `id` is set by the codegen (channel
+// path); if missing, it is derived from init.
+export function store(init, o = {}, id) {
+  const name = id || o.name || 'store:' + Object.keys(init).join(',')
+  const S = {}, s = {}
+  let last = '' // JSON of the last state sent or received: cuts the echo between tabs
+  for (const k of Object.keys(init)) {
+    S[k] = sig(init[k], name + '.' + k) // named: dev tools (brain_why, HMR) see `cart.total`
+    Object.defineProperty(s, k, {
+      enumerable: true,
+      get: () => (note('store', name, 'read'), S[k].v),
+      set: v => (note('store', name, 'write'), (S[k].v = v)),
+    })
+  }
+  const snap = () => {
+    const r = {}
+    for (const k in S) r[k] = untrack(() => S[k].v)
+    return r
+  }
+  const apply = d => {
+    const n = snap()
+    for (const k in d) if (k in S) n[k] = d[k]
+    last = JSON.stringify(n) // before the batch: the sync fx runs when it closes and must see the echo
+    batch(() => {
+      for (const k in n) S[k].v = n[k]
+    })
+  }
+  Object.defineProperties(s, {
+    $set: { value: d => batch(() => { for (const k in d) if (k in S) s[k] = d[k] }) },
+    $snap: { value: snap },
+    $reset: { value: () => apply({ ...init }) }, // back to the initial state (persisted and synced like any write)
+  })
+  const K = 'brain:' + name
+  if (o.persist) {
+    // Persistence (INTERNALS §35.4), versioned by the shape of init. Small states live in localStorage and are restored
+    // here, synchronously, before the first render; brain-persist.js (loaded on demand) handles IndexedDB for large ones
+    // and the writes. `ready()` resolves once every persisted store is restored.
+    const P = 'brain:p:' + name, v = shape(init)
+    let big = false
+    try {
+      const r = JSON.parse(localStorage.getItem(P), safe)
+      if (r && r.v === v) r.idb ? (big = true) : apply(r.d)
+      else if (r) localStorage.removeItem(P) // another shape: the old data is discarded, never applied
+    } catch {}
+    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 })))
+  }
+  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)))
+  }
+  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
+  if (w) Object.defineProperty(s, '$close', { value: w.close })
+  if (bc) {
+    bc.onmessage = e => (e.data === '?' ? bc.postMessage(snap()) : apply(e.data))
+    bc.postMessage('?') // a new tab asks the open ones for the state
+  }
+  last = JSON.stringify(snap()) // the initial state is not broadcast: a new tab asks for it with '?'
+  // a store created inside provide() lives in that subtree: its sync effect is disposed with it
+  if (o.sync)
+    I.root(() =>
+      fx(() => {
+        const d = {}
+        for (const k in S) d[k] = S[k].v // reads everything: re-runs on any change
+        const j = JSON.stringify(d)
+        if (j === last) return
+        last = j
+        if (bc) bc.postMessage(d)
+        else if (w) w.send(d)
+        else
+          try {
+            if (j.length > 2e6) throw Error('over 2 MB') // localStorage is ~5 MB per origin for the whole app
+            localStorage.setItem(K, j)
+          } catch (e) {
+            // full or too big: the state stays in memory, the page keeps working, and the author is told why (§31)
+            console.warn(`store ${name}: not saved to localStorage (${e && e.message}); it is kept in memory only`)
+          }
+      }),
+    I.owner())
+  return s
+}
+
+// Real-time sync (INTERNALS §22). One socket per url, shared by its stores. Protocol (JSON text frames):
+//   client → server  {s, d}  local change (full state) · {s, q:1}  asks for the current state (after each connect)
+//   server → client  {s, d}  state of store s (the server keeps the last one per s and relays it to the others)
+// While offline, the latest local state waits and is sent on reconnect BEFORE asking (the server's reply then matches it).
+// Reconnection: exponential backoff 0.5 s → 30 s with ±50 % jitter, reset on open; `online` and returning to a
+// visible tab retry at once. `$close()` stops it.
+const WS = new Map()
+function ws(url, s, apply) {
+  let c = WS.get(url)
+  if (!c) {
+    const subs = new Map(), wait = new Map()
+    let sock, n = 0, t, off = false
+    const u = new URL(url, G.location && location.href).href.replace(/^http/, 'ws')
+    const put = (k, d) => sock && sock.readyState === 1 && (sock.send(JSON.stringify(d ? { s: k, d } : { s: k, q: 1 })), true)
+    const open = () => {
+      clearTimeout(t)
+      if (off || (sock && sock.readyState < 2)) return
+      sock = new WebSocket(u)
+      sock.onopen = () => {
+        n = 0
+        for (const [k, d] of wait) put(k, d)
+        wait.clear()
+        for (const k of subs.keys()) put(k)
+      }
+      sock.onmessage = e => {
+        let m
+        try {
+          m = JSON.parse(e.data, safe)
+        } catch {
+          return
+        }
+        const f = m && subs.get(m.s)
+        if (f && m.d && typeof m.d === 'object') f(m.d)
+      }
+      sock.onclose = () => {
+        if (off) return
+        const ms = Math.min(30000, 500 * 2 ** n++)
+        t = setTimeout(open, ms * (0.5 + Math.random()))
+      }
+    }
+    const now = () => ((n = 0), open())
+    G.addEventListener && G.addEventListener('online', now)
+    G.document && document.addEventListener && document.addEventListener('visibilitychange', () => document.visibilityState === 'visible' && open())
+    c = {
+      subs,
+      sub(k, f) {
+        subs.set(k, f)
+        if (!put(k)) open()
+      },
+      send: (k, d) => put(k, d) || (wait.set(k, d), open()),
+      close() {
+        off = true
+        clearTimeout(t)
+        sock && sock.close()
+        WS.delete(url)
+        G.removeEventListener && G.removeEventListener('online', now)
+      },
+    }
+    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()) }
+}
+
+// Shape of a store: field names + kind of each initial value. A persisted state with another shape is discarded.
+const kind = x => (Array.isArray(x) ? 'list' : x === null ? 'null' : typeof x)
+const shape = init => Object.keys(init).sort().map(k => k + ':' + kind(init[k])).join(',')
+const READY = []
+export const ready = () => Promise.all(READY)
+
+// ---------- bus ----------
+// Stateless notification: `toast.send(msg)` · `toast.on(fn)` → off. Inside a component it unsubscribes itself on
+// unmount. A failing handler does not stop the others (reportError → onerror → brain-err).
+export function bus(name) {
+  const subs = new Set()
+  return {
+    name,
+    send(m) {
+      note('bus', name, 'send')
+      for (const f of [...subs])
+        try {
+          f(m)
+        } catch (e) {
+          G.reportError ? reportError(e) : queueMicrotask(() => { throw e })
+        }
+    },
+    on(f) {
+      note('bus', name, 'on')
+      subs.add(f)
+      const off = () => subs.delete(f)
+      if (I.owner()) fx(() => off)
+      return off
+    },
+  }
+}
+
+// ---------- exposed API ----------
+// Child with `<meta expose="open close">`: the codegen emits `expose($p, { open, close })` at the end of setup; the parent
+// `<Modal bind:api={m} />` passes `"bind:api": a => (m = a)`. When the child unmounts, the parent receives null.
+export function expose($p, api) {
+  const f = $p['bind:api']
+  note('api', Object.keys(api).join(' '), 'expose')
+  if (f) {
+    f(Object.freeze(api))
+    if (I.owner()) fx(() => () => f(null))
+  }
+  return api
+}

package/brain-consent.js

@@ -0,0 +1,38 @@
+// BRAINLLM consent (INTERNALS §32, Google Consent Mode v2). The build injects Analytics/Tag Manager with every consent
+// type denied by default; the app grants what the visitor accepted:
+//   consent('analytics') · consent('ads') · consent('analytics', false) (revoke) · consented('analytics') → true/false
+// The answer is remembered in localStorage and applied again on the next visit as soon as this module loads.
+const G = globalThis
+const KEY = 'brain:consent'
+const TYPES = {
+  analytics: ['analytics_storage'],
+  ads: ['ad_storage', 'ad_user_data', 'ad_personalization'],
+  functional: ['functionality_storage'],
+  personal: ['personalization_storage'],
+}
+const read = () => {
+  try {
+    return JSON.parse(G.localStorage.getItem(KEY)) || {}
+  } catch {
+    return {}
+  }
+}
+const apply = state => {
+  const u = {}
+  for (const k in state) for (const t of TYPES[k] || []) u[t] = state[k] ? 'granted' : 'denied'
+  if (!Object.keys(u).length) return
+  if (typeof G.gtag === 'function') G.gtag('consent', 'update', u)
+  else if (G.dataLayer) G.dataLayer.push(['consent', 'update', u]) // gtag not loaded yet: queued the way gtag reads it
+}
+
+export function consent(kind, granted = true) {
+  if (!TYPES[kind]) throw Error(`consent: unknown kind "${kind}" (${Object.keys(TYPES).join(', ')})`)
+  const s = { ...read(), [kind]: !!granted }
+  try {
+    G.localStorage.setItem(KEY, JSON.stringify(s))
+  } catch {}
+  apply({ [kind]: !!granted })
+}
+export const consented = kind => !!read()[kind]
+
+apply(read()) // a returning visitor: their earlier answer, before any tag reads the defaults