@christianirack/brainllm-runtime 0.1.0 → 0.4.0

package/brain-form.js

@@ -15,7 +15,7 @@
 // Unsaved changes (§41.5): `f.dirty` is true while values differ from the last saved ones (init, reset() or a successful
 // submit); leaving the page (client navigation or closing the tab) then asks first. No API.
 import { sig, fx, batch, untrack, _rt } from './brain.js'
-import { rule, check } from './brain-schema.js'
+import { rule, check, checkText, checkScalar, msg } from './brain-schema.js'
 
 export { rule, check } // server.mjs validates posted forms with the same rules (§38)
 
@@ -23,7 +23,7 @@ const I = _rt()
 
 const D = globalThis.document
 let seq = 0
-const GENERIC = 'Something went wrong. Try again.' // the text callForm (server.mjs) shows without JS
+const GENERIC = 'Something went wrong. Try again.' // the text callForm (server.mjs) shows without JS (key form.error)
 // navigate through the client router when it is loaded (no reload, base path applied), else a normal load
 const go = u => {
   const G = globalThis
@@ -41,9 +41,18 @@ if (globalThis.addEventListener && !globalThis.__brainDirtyHook) {
     for (const f of DIRTY) if (f.dirty && !f.busy) return void (e.preventDefault(), (e.returnValue = ''))
   })
 }
-const empty = v => v == null || v === '' || (Array.isArray(v) && !v.length)
+const empty = v => v == null || typeof v === 'string' && v.trim() === '' || Array.isArray(v) && !v.length
 const init0 = r => (r.list ? [] : r.t === 'bool' ? false : '')
-const out = (r, v) => (r.list ? v || [] : r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v)
+const out = (r, v) => {
+  if (r.list) {
+    if (!Array.isArray(v)) return []
+    if (r.t !== 'num') return v
+    const numbers = new Array(v.length)
+    for (let i = 0; i < v.length; i++) numbers[i] = Number(v[i])
+    return numbers
+  }
+  return r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v
+}
 
 // state left by the server: globalThis.__brainForms while it renders, or the page's #brain-forms JSON
 let SEEN
@@ -62,6 +71,46 @@ function posted(id) {
 }
 
 export function form(schema, o = {}) {
+  if (rule(schema).t !== 'obj') throw Error('form: schema must be a nested field object')
+  return createForm(schema, o, rule, check, remoteCheck)
+}
+// Compiler-only flat literal schema bytecode. Dynamic/public form() keeps the full parser.
+export function formStatic(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, remoteCheck)
+}
+export function formScalars(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, remoteCheck)
+}
+// Compiler-only options proven not to configure or dynamically install async checks.
+export function formStaticSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, null)
+}
+export function formScalarsSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, null)
+}
+function compiledForm(schema, o, types, validate, remote) {
+  if (remote === null && ('check' in o || 'validate' in o)) throw Error('form: invalid compiled synchronous options')
+  if (!schema || Object.getPrototypeOf(schema) !== Object.prototype || Object.keys(schema).length > 4096) throw Error('form: invalid compiled schema')
+  return createForm(schema, o, (value, key) => {
+    if (['__proto__', 'prototype', 'constructor'].includes(key) || !Array.isArray(value) || value.length !== 2 || !types.includes(value[0]) || typeof value[1] !== 'boolean') throw Error('form: invalid compiled schema')
+    return { t: value[0], req: value[1], list: false, min: null, max: null }
+  }, validate, remote)
+}
+// Only public/dynamic or check-configured forms retain this optional capability.
+function remoteCheck(o, x, checking) {
+  const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
+  if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
+  checking.v++
+  return Promise.resolve()
+    .then(() => c(v))
+    .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || msg('form.check_failed', 'Could not check this value.')))
+    .then(m => {
+      if (untrack(() => x.s.v) === v) x.e.v = m
+      return untrack(() => x.e.v)
+    })
+    .finally(() => checking.v--)
+}
+function createForm(schema, o, readRule, validateRule, remote) {
   const id = 'f' + ++seq, owner = I.owner() // aria effects are created later (in handlers) but live with the component
   const busy = sig(false), error = sig(''), shown = sig(0) // shown: bumped when touched set changes
   const checking = sig(0), saved = sig('') // async checks running · JSON of the last saved values
@@ -72,7 +121,7 @@ export function form(schema, o = {}) {
   function build(sch, base, init) {
     const v = {}, err = {}
     for (const k of Object.keys(sch)) {
-      const r = rule(sch[k]), path = base ? base + '.' + k : k
+      const r = readRule(sch[k], k), path = base ? base + '.' + k : k
       if (r.t === 'obj') {
         const sub = build(r.s, path, (init && init[k]) || {})
         Object.defineProperty(v, k, { enumerable: true, value: sub.v })
@@ -115,23 +164,9 @@ export function form(schema, o = {}) {
   const touch = x => {
     validate(x)
     if (!x.touched) (x.touched = true), shown.v++
-    remote(x)
-  }
-  // async check of one field (only when its own rule passes); resolves to its message
-  const remote = x => {
-    const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
-    if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
-    checking.v++
-    return Promise.resolve()
-      .then(() => c(v))
-      .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || 'Could not check this value.'))
-      .then(m => {
-        if (untrack(() => x.s.v) === v) x.e.v = m // a stale answer (the value changed meanwhile) is ignored
-        return untrack(() => x.e.v)
-      })
-      .finally(() => checking.v--)
+    if (remote) remote(o, x, checking)
   }
-  const validate = x => (x.e.v = untrack(() => check(x.r, x.s.v)))
+  const validate = x => (x.e.v = untrack(() => validateRule(x.r, x.s.v)))
   const fid = p => `${id}-${p.replace(/\./g, '-')}-err`
 
   // A form posted without JS (§38) comes back from the server with its values and messages: start from them, already
@@ -165,9 +200,24 @@ export function form(schema, o = {}) {
     })
   }
 
+  // `f.v` and `f.err` are the form's live fields: replacing the object (`f.v = { … }`) would leave the inputs bound to
+  // signals the form no longer reads (submit then sees every field empty), so it fails loudly instead (§14, B0133)
+  const fixed = k => {
+    throw Error(`form: \`${k}\` cannot be replaced; start from values with form(schema, { init }) or load them later with f.reset(values)`)
+  }
   const f = {
-    v,
-    err,
+    get v() {
+      return v
+    },
+    set v(_) {
+      fixed('f.v')
+    },
+    get err() {
+      return err
+    },
+    set err(_) {
+      fixed('f.err')
+    },
     get busy() {
       return busy.v
     },
@@ -181,7 +231,7 @@ export function form(schema, o = {}) {
       return checking.v > 0
     },
     get ok() {
-      for (const x of F) if (check(x.r, x.s.v)) return false
+      for (const x of F) if (validateRule(x.r, x.s.v)) return false
       return true
     },
     id: path => fid(path),
@@ -229,8 +279,8 @@ export function form(schema, o = {}) {
       busy.v = true
       if (fm) fm.setAttribute('aria-busy', 'true') // assistive tech hears the form is working
       try {
-        if (o.check) {
-          await Promise.all(F.map(remote))
+        if (remote && o.check) {
+          await Promise.all(F.map(x => remote(o, x, checking)))
           first = F.find(x => untrack(() => x.e.v))
           if (first) return void (shown.v++, first.el && first.el.focus && first.el.focus())
         }
@@ -247,7 +297,7 @@ export function form(schema, o = {}) {
         if (x && x.errors) mark(x.errors)
         // a server failure reads the same as without JS: 4xx and the author's own errors keep their message; 5xx and a
         // TypeError (the network dropped, or a bug) get the generic one
-        else if (!(x && x.kind === 'aborted')) error.v = (x && x.message && !(x.status >= 500) && x.name !== 'TypeError' && x.message) || GENERIC
+        else if (!(x && x.kind === 'aborted')) error.v = (x && x.message && !(x.status >= 500) && x.name !== 'TypeError' && x.message) || msg('form.error', GENERIC)
       } finally {
         busy.v = false
         if (fm) fm.removeAttribute('aria-busy')

package/brain-hash.js

@@ -0,0 +1,17 @@
+// Web Crypto owns cryptography in browsers and Node. No hashing implementation is bundled.
+export async function hashText(value, algorithm = 'SHA-256') {
+  if (!['SHA-256', 'SHA-384', 'SHA-512'].includes(algorithm)) throw RangeError('hashText: SHA-256, SHA-384 or SHA-512 required')
+  if (typeof value !== 'string') throw TypeError('hashText: text input required')
+  if (value.length > 8388608) throw RangeError('hashText: input exceeds 8 MiB')
+  const bytes = new TextEncoder().encode(value)
+  if (bytes.byteLength > 8388608) throw RangeError('hashText: UTF-8 input exceeds 8 MiB')
+  if (!globalThis.crypto?.subtle) throw Error('hashText: Web Crypto requires a secure browser context or Node 22+')
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(algorithm, bytes))
+  let hex = ''
+  for (let i = 0; i < digest.length; i++) hex += digest[i].toString(16).padStart(2, '0')
+  return hex
+}
+export async function shortHash(value, length = 32) {
+  if (!Number.isInteger(length) || length < 8 || length > 64) throw RangeError('shortHash: length must be 8..64 hex characters')
+  return (await hashText(value)).slice(0, length)
+}

package/brain-inspect.js

@@ -16,8 +16,8 @@ const now = () => Date.now()
 const pnow = () => (G.performance ? performance.now() : now())
 const syncHeap = () => (G.performance && performance.memory ? performance.memory.usedJSHeapSize : G.process && process.memoryUsage ? process.memoryUsage().heapUsed : null)
 
-let out = [], seq = 0, opts = {}, started = false
-const push = r => out.push(r)
+let out = [], seq = 0, opts = {}, started = false, dropped = 0
+const push = r => { if (out.length >= 2000) { out.shift(); dropped++ } out.push(r) }
 
 // ---------- instance identity and current owner ----------
 const ids = new WeakMap()
@@ -612,6 +612,8 @@ export function tick() {
 export function drain() {
   if (!out.length) return null
   const m = { t: 'm', v: 2, seq: seq++, at: now(), d: out }
+  if (dropped) m.dropped = dropped
+  dropped = 0
   out = []
   if (opts.send) opts.send(JSON.stringify(m))
   return m
@@ -629,7 +631,7 @@ export function inspect(o) {
       else i = instOf(x)
       if (!i) return null
       const chain = []
-      for (let j = i; j; j = instOf(j.p)) chain.push(nameOf(j))
+      for (let j = i; j && chain.length < 33; j = instOf(j.p)) chain.push(nameOf(j))
       return { id: idOf(i), h: i.h, name: nameOf(i), file: (i.C && (i.C.f || (i.C.C && i.C.C.f))) || null, chain }
     },
     sigName,
@@ -643,7 +645,7 @@ export function inspect(o) {
     if (done) done.add(key)
     push({ k: 'chan', kind, name, role, id: i ? idOf(i) : null, h: i ? i.h : null, comp: i ? nameOf(i) : null })
   })
-  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, crumbs: r.crumbs, n: r.n, at: r.last }))
+  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, brainStack: r.brainStack || null, location: r.location, generatedLocation: r.generatedLocation, frames: r.frames, causes: r.causes, truncated: r.truncated, mapping: r.mapping, crumbs: r.crumbs, n: r.n, at: r.last }))
   patchTimers()
   patchGlobalListeners()
   patchHandlers()

package/brain-interop.js

@@ -0,0 +1,50 @@
+// Explicit foreign-DOM ownership. The adapter, SDK and any React runtime belong to the app.
+import { _rt, fx, untrack } from './brain.js'
+
+const I = _rt()
+
+// Call during component setup. Resolve the bound element only after insertion.
+// mount must synchronously return a cleanup function or { update?, destroy }.
+export function interop(element, adapter, props = {}, options = {}) {
+  const owner = I.owner()
+  if (!owner) throw Error('interop: call during component setup')
+  let alive = true, instance = null, pending = props, ready = false
+  const report = (error, phase) => {
+    if (typeof options.onError === 'function') options.onError(error, phase)
+    else I.oops(error, owner, 'interop:' + phase)
+  }
+  const destroy = () => {
+    if (!alive) return
+    alive = false
+    const old = instance
+    instance = null
+    if (old) try { old.destroy() } catch (error) { report(error, 'destroy') }
+  }
+  const controller = {
+    update(next) {
+      if (!alive) throw Error('interop: boundary has been destroyed')
+      pending = next
+      if (!ready) return
+      if (!instance || typeof instance.update !== 'function') throw Error('interop: adapter does not support updates')
+      try { untrack(() => instance.update(next)) } catch (error) { report(error, 'update') }
+    },
+    destroy,
+  }
+  // No SDK execution during SSR or prerender. Disposal still invalidates this controller.
+  fx(() => destroy)
+  if (globalThis.__brainSSR || globalThis.__brainRoute) return controller
+  queueMicrotask(() => {
+    if (!alive) return
+    try {
+      const el = typeof element === 'function' ? untrack(element) : element
+      if (!el || el.nodeType !== 1) throw Error('interop: expected a bound DOM element')
+      if (!adapter || typeof adapter.mount !== 'function') throw Error('interop: adapter.mount is required')
+      const result = untrack(() => adapter.mount(el, pending))
+      if (typeof result === 'function') instance = { destroy: result }
+      else if (result && typeof result.destroy === 'function' && typeof result.then !== 'function') instance = result
+      else throw Error('interop: mount must return cleanup or { update, destroy }; asynchronous mounts are unsupported')
+      ready = true
+    } catch (error) { report(error, 'mount') }
+  })
+  return controller
+}

package/brain-mcp.js

@@ -5,6 +5,8 @@
 // parameters use form()'s mini-language and become a JSON Schema; arguments are validated before `run` is called and
 // a bad call answers with the field's message instead of running. Tools act with the page's permissions only:
 // anything destructive should still ask for confirmation in the UI.
+// Optional 5th argument (WebMCP draft 2026-10-27): { title, readOnly, consequential, untrusted } → `title` and
+// `annotations: { readOnlyHint, consequentialHint, untrustedContentHint }` on the registration; only the keys given.
 import { fx } from './brain.js'
 import { rule, check } from './brain-schema.js'
 
@@ -32,27 +34,40 @@ export function schema(params = {}) {
 
 const text = v => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v ?? null) }] })
 
-export function tool(name, description, params, run) {
+const HINTS = [['readOnly', 'readOnlyHint'], ['consequential', 'consequentialHint'], ['untrusted', 'untrustedContentHint']]
+
+// The registration dictionary: name, description, inputSchema, then title/annotations only when given.
+export function definition(name, description, params, opts) {
+  const def = { name, description, inputSchema: schema(params) }
+  if (!opts) return def
+  if (typeof opts.title === 'string' && opts.title) def.title = opts.title
+  let annotations = null
+  for (let i = 0; i < HINTS.length; i++) {
+    const v = opts[HINTS[i][0]]
+    if (v != null) (annotations || (annotations = {}))[HINTS[i][1]] = !!v
+  }
+  if (annotations) def.annotations = annotations
+  return def
+}
+
+export function tool(name, description, params, run, opts) {
   const mc = context()
   if (!mc || !mc.registerTool || G.__brainSSR || G.__brainRoute) return
   const rules = Object.fromEntries(Object.entries(params || {}).map(([k, s]) => [k, rule(s)]))
   fx(() => {
-    const reg = mc.registerTool({
-      name,
-      description,
-      inputSchema: schema(params),
-      async execute(args = {}) {
-        for (const k in rules) {
-          const m = check(rules[k], args[k])
-          if (m) return text(`${k}: ${m}`)
-        }
-        try {
-          return text(await run(args))
-        } catch (e) {
-          return text(`Error: ${(e && e.message) || e}`)
-        }
-      },
-    })
+    const def = definition(name, description, params, opts)
+    def.execute = async (args = {}) => {
+      for (const k in rules) {
+        const m = check(rules[k], args[k])
+        if (m) return text(`${k}: ${m}`)
+      }
+      try {
+        return text(await run(args))
+      } catch (e) {
+        return text(`Error: ${(e && e.message) || e}`)
+      }
+    }
+    const reg = mc.registerTool(def)
     return () => (reg && reg.unregister ? reg.unregister() : mc.unregisterTool && mc.unregisterTool(name))
   })
 }

package/brain-overlay.js

@@ -24,10 +24,21 @@ export function forLLM(d) {
     })
   if (d.fix) out.push(`fix: ${d.fix}`)
   if (d.brainStack) out.push('stack:', ...[].concat(d.brainStack))
+  if (d.location || d.frames || d.causes || d.rid) out.push('structured trace (development only):', JSON.stringify(traceOf(d)))
+  if (d.mapping?.status && d.mapping.status !== 'mapped') out.push('Location mapping is incomplete; do not treat generated coordinates as original source coordinates.')
+  out.push('Agent next steps: inspect the exact source revision, apply a focused change, run brain check --json, then reproduce the failing action. Record evidence with brain history and refresh brain quality.')
   if (d.file) out.push('brain check --json:', JSON.stringify((byFile.get(d.file) || [d]).map(({ snippet, ...x }) => x)))
   return out.join('\n')
 }
 
+function traceOf(d) {
+  return { schemaVersion: 1, requestId: d.rid || d.requestId || null, component: d.comp || null,
+    location: d.location || null, generatedLocation: d.generatedLocation || null,
+    mapping: d.mapping || null, truncated: d.truncated || null,
+    frames: Array.isArray(d.frames) ? d.frames.slice(0, 24) : [],
+    causes: Array.isArray(d.causes) ? d.causes.slice(0, 6) : [] }
+}
+
 function item(d, i) {
   const loc = d.file ? `${d.file}:${d.line || ''}${d.col ? ':' + d.col : ''}` : d.src || ''
   const snip = d.snippet && d.snippet.text
@@ -35,6 +46,7 @@ function item(d, i) {
     : ''
   return `<li class="${d.level === 'warning' || d.level === 'info' ? d.level : 'error'}"><p class="t"><b>${esc(d.code || 'Error')}</b> <span>${esc(loc)}</span></p>` +
     `<p>${esc(d.msg)}</p>${snip}${d.fix ? `<p class="fix">fix: ${esc(d.fix)}</p>` : ''}` +
+    `${d.location || d.frames || d.causes ? `<details><summary>Development trace and mapping</summary><pre>${esc(JSON.stringify(traceOf(d), null, 2))}</pre></details>` : ''}` +
     `<button type="button" data-copy="${i}">Copy for the LLM</button></li>`
 }
 

package/brain-preferences.js

@@ -0,0 +1,64 @@
+// Small public preferences only. Authentication belongs to HttpOnly server cookies, never Web Storage.
+const G = globalThis
+const privateName = /password|secret|token|authorization|sessionid|csrf|jwt|credit/i
+const valid = name => typeof name === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(name) && !privateName.test(name)
+const problem = fix => Object.assign(new Error(fix), { code: 'B0913', fix })
+
+export function storage(name, options = {}) {
+  if (!valid(name) || !valid(options.namespace || 'app')) throw problem('storage: use public preference names; keep authentication in server sessions')
+  if (options.scope && !['local', 'session'].includes(options.scope)) throw problem('storage: scope must be local or session')
+  const prefix = `brain:pref:${options.namespace || 'app'}:${name}:`, version = options.version || 1
+  const backend = () => {
+    let s
+    try { s = options.scope === 'session' ? G.sessionStorage : G.localStorage } catch {}
+    if (!s) throw problem('Web Storage is unavailable; use an in-memory preference or a server data source')
+    return s
+  }
+  const key = k => { if (!valid(k)) throw problem('storage: keys must be bounded public preference names'); return prefix + k }
+  const keys = s => {
+    if (s.length > 4096) throw problem('storage: origin contains too many keys; reduce stored preferences')
+    const result = []
+    for (let i = 0; i < s.length; i++) { const k = s.key(i); if (k?.startsWith(prefix)) result.push(k) }
+    return result
+  }
+  return {
+    get(k, fallback = null) {
+      const s = backend(), raw = s.getItem(key(k))
+      if (raw == null) return fallback
+      if (raw.length > 8192) throw problem('storage: preference exceeds 8 KiB; use database() for structured data')
+      let r; try { r = JSON.parse(raw) } catch { throw problem('storage: malformed preference; explicitly delete or replace this key') }
+      return r?.v === version ? r.data : fallback
+    },
+    set(k, value) {
+      const s = backend(), target = key(k)
+      let raw
+      try { raw = JSON.stringify({v:version,data:value}); if (value === undefined) throw Error() } catch { throw problem('storage: values must be JSON-serializable') }
+      if (new TextEncoder().encode(raw).length > 8192) throw problem('storage: preference exceeds 8 KiB; use database() for structured data')
+      const existing = keys(s)
+      if (existing.length >= 128 && !existing.includes(target)) throw problem('storage: namespace exceeds 128 preference keys')
+      let total = new TextEncoder().encode(raw).length
+      for (const name of existing) if (name !== target) total += new TextEncoder().encode(s.getItem(name) || '').length
+      if (total > 65536) throw problem('storage: namespace exceeds 64 KiB; move structured data to database()')
+      try { s.setItem(target, raw) } catch { throw problem('storage: write failed or quota exceeded; reduce stored preferences') }
+    },
+    delete(k) { backend().removeItem(key(k)) },
+    clear() { const s = backend(); for (const k of keys(s)) s.removeItem(k) },
+  }
+}
+
+export function cookie(name, value, options = {}) {
+  if (!valid(name)) throw problem('cookie: use a public preference name; authentication cookies belong to the backend')
+  if (!G.document) throw problem('cookie: browser document unavailable; use ctx.cookies on the server')
+  const key = `brain_pref_${name}`
+  if (value === undefined) {
+    const matches = G.document.cookie.split(';').map(x => x.trim()).filter(x => x.startsWith(key + '='))
+    if (matches.length !== 1) return null
+    try { return decodeURIComponent(matches[0].slice(key.length + 1)) } catch { return null }
+  }
+  const encoded = value === null ? '' : encodeURIComponent(String(value))
+  if (encoded.length > 2048) throw problem('cookie: preferences must be at most 2 KiB; use database() for larger data')
+  const age = value === null ? 0 : options.maxAge ?? 2592000
+  if (!Number.isSafeInteger(age) || age < 0 || age > 31536000) throw problem('cookie: maxAge must be between zero and one year in seconds')
+  G.document.cookie = `${key}=${encoded}; Path=/; Secure; SameSite=Lax; Max-Age=${age}`
+  return value
+}

package/brain-prefetch-shared.js

@@ -0,0 +1,36 @@
+// Pure bounded transport shared by the page fallback and its dedicated module worker.
+// No owners, DOM hooks, listeners or app modules execute when this module is imported.
+export async function prefetchPage(url, signal) {
+  try {
+    const r = await fetch(url, { headers: { 'x-brain-nav': '1', 'x-brain-prefetch': '1' }, credentials: 'same-origin', priority: 'low', redirect: 'error', signal })
+    const limit = 512 * 1024
+    if (!r.ok || r.redirected || !/text\/html/i.test(r.headers?.get('content-type') || '') || +(r.headers.get('content-length') || 0) > limit) {
+      await r.body?.cancel?.(); return null
+    }
+    let text, bytes = 0
+    if (r.body?.getReader) {
+      const reader = r.body.getReader(), decoder = new TextDecoder(), parts = []
+      try {
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          bytes += value.byteLength
+          if (bytes > limit) { await reader.cancel(); return null }
+          parts.push(decoder.decode(value, { stream: true }))
+        }
+        parts.push(decoder.decode()); text = parts.join('')
+      } finally { reader.releaseLock?.() }
+    } else {
+      text = await r.text(); bytes = text.length * 2
+      if (bytes > limit) return null
+    }
+    const assets = [], base = new URL(url)
+    const pattern = /<script[^>]+src=["']([^"']+)["']|\bfrom\s*["']([^"']+\.(?:js|jsbrain))["']|\bimport\(\s*["']([^"']+\.(?:js|jsbrain))["']/g
+    let hit
+    while ((hit = pattern.exec(text)) && assets.length < 16) {
+      const asset = new URL(hit[1] || hit[2] || hit[3], base)
+      if (asset.origin === base.origin && asset.pathname.includes('/_b/')) assets.push(asset.href)
+    }
+    return { ok: true, status: r.status, url: r.url, headers: r.headers, text, bytes, assets }
+  } catch { return null }
+}

package/brain-prefetch.js

@@ -0,0 +1,19 @@
+// Dedicated speculative-fetch worker. Only bounded HTML/assets cross the bridge; app scripts never run.
+import { prefetchPage } from './brain-prefetch-shared.js'
+const jobs = new Map()
+self.onmessage = async e => {
+  const m = e.data
+  if (!m || !Number.isSafeInteger(m.id)) return
+  if (m.cancel) { jobs.get(m.id)?.abort(); return }
+  if (jobs.size >= 2 || jobs.has(m.id) || typeof m.url !== 'string') return
+  let url
+  try { url = new URL(m.url); if (url.origin !== self.location.origin) return } catch { return }
+  const controller = new AbortController()
+  jobs.set(m.id, controller)
+  const timer = setTimeout(() => controller.abort(), 6000)
+  try {
+    const result = await prefetchPage(url.href, controller.signal)
+    self.postMessage(result ? { id: m.id, ...result, headers: [...result.headers] } : { id: m.id, ok: false })
+  } catch { self.postMessage({ id: m.id, ok: false }) }
+  finally { clearTimeout(timer); controller.abort(); jobs.delete(m.id) }
+}