@christianirack/brainllm-runtime 0.3.1 → 0.4.0

package/brain-sqlite.js

@@ -0,0 +1,122 @@
+// Official SQLite Wasm adapter for a project-owned worker. IndexedDB remains the dependency-free default.
+const G = globalThis
+const fault = (code, fix) => Object.assign(new Error(fix), { code, fix })
+const nameOK = x => typeof x === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/.test(x)
+
+export function sqlite(initialize, options = {}) {
+  const name = options.name || 'app', namespace = options.namespace || 'app'
+  if (!nameOK(name) || !nameOK(namespace) || typeof initialize !== 'function') throw fault('B0916', 'sqlite: provide the official initializer and stable names')
+  let opening, db, pool, release, closed = false, pending = 0, chain = Promise.resolve()
+  const lease = new Promise(resolve => { release = resolve })
+  async function open() {
+    if (closed) throw fault('B0916', 'Local SQL handle is closed; create a new worker')
+    if (opening) return opening
+    if (G.document || !G.navigator?.storage?.getDirectory || !G.navigator?.locks?.request || typeof G.postMessage !== 'function') throw fault('B0916', 'Persistent SQLite needs an owned worker with OPFS and Web Locks; use database() when unavailable')
+    opening = new Promise((resolve, reject) => {
+      G.navigator.locks.request(`brain:sqlite:${namespace}:${name}`, { ifAvailable: true }, async lock => {
+        if (!lock) throw fault('B0916', 'This local SQL database is open in another worker; close its handle before retrying')
+        let stage = 'official SDK initialization'
+        try {
+          const engine = await initialize({ print() {}, printErr() {} })
+          if (closed) throw fault('B0916', 'Local SQL handle closed while initializing')
+          if (!engine.capi || engine.capi.sqlite3_libversion_number() < 3054000) throw fault('B0916', 'SQLite 3.54 or newer is required for non-destructive OPFS initialization')
+          stage = 'non-destructive OPFS initialization'
+          pool = await engine.installOpfsSAHPoolVfs({ name: `brain-${namespace}-${name}`, directory: `/brain-sqlite/${namespace}/${name}`, initialCapacity: 6, clearOnInit: false, preserveOnInitFailure: true })
+          stage = 'OPFS database open'
+          db = new pool.OpfsSAHPoolDb(`/${name}.sqlite3`)
+          stage = 'SQLite resource limits'
+          const c = engine.capi
+          for (const [constant, value] of [['SQLITE_LIMIT_LENGTH',1048576],['SQLITE_LIMIT_SQL_LENGTH',65536],['SQLITE_LIMIT_COLUMN',128],['SQLITE_LIMIT_EXPR_DEPTH',100],['SQLITE_LIMIT_COMPOUND_SELECT',16],['SQLITE_LIMIT_VARIABLE_NUMBER',128],['SQLITE_LIMIT_ATTACHED',0],['SQLITE_LIMIT_TRIGGER_DEPTH',16],['SQLITE_LIMIT_VDBE_OP',100000]]) {
+            if (typeof c[constant] !== 'number') throw fault('B0916', 'Official SQLite limit API is incomplete; verify the installed SDK version')
+            c.sqlite3_limit(db.pointer, c[constant], value)
+          }
+          db.exec('PRAGMA page_size=4096; PRAGMA cache_size=-2048; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=1000;')
+          const pageSize = Number(db.selectValue('PRAGMA page_size')), pages = Number(db.selectValue('PRAGMA page_count'))
+          if (!Number.isSafeInteger(pageSize) || pageSize < 512 || pageSize > 65536 || pages * pageSize > 67108864) throw fault('B0914', 'Local SQL database exceeds its 64 MiB budget; archive or migrate it explicitly')
+          db.exec('PRAGMA max_page_count=' + Math.floor(67108864 / pageSize))
+          if (closed) throw fault('B0916', 'Local SQL handle closed while initializing')
+          resolve({ db, c })
+          await lease
+        } catch (e) {
+          reject(e?.code === 'B0916' ? e : fault('B0916', 'Persistent SQLite failed during ' + stage + '; existing data is preserved. Check storage capabilities and the official SDK assets'))
+        } finally {
+          try { db?.close() } catch {}
+          try { pool?.pauseVfs() } catch {}
+          db = null
+        }
+      }).catch(e => reject(e?.code === 'B0916' ? e : fault('B0916', 'Local SQL lock failed; close competing workers and retry')))
+    })
+    return opening
+  }
+  function enqueue(work) {
+    if (closed) return Promise.reject(fault('B0916', 'Local SQL handle is closed'))
+    if (pending >= 32) return Promise.reject(fault('B0914', 'Local SQL queue is full; await pending queries'))
+    pending++
+    const result = chain.then(async () => { const state = await open(); if (closed) throw fault('B0916', 'Local SQL handle is closed'); return work(state) })
+    chain = result.catch(() => {}).finally(() => pending--)
+    return result
+  }
+  function statement(state, sql, bind = [], readonly = false) {
+    if (typeof sql !== 'string' || !sql.trim() || new TextEncoder().encode(sql).length > 65536 || sql.includes('\0')) throw fault('B0916', 'Local SQL needs one statement of at most 64 KiB; use bound values')
+    if (!Array.isArray(bind) || bind.length > 128 || bind.some(v => !(v == null || ['string','number','bigint'].includes(typeof v) || v instanceof Uint8Array))) throw fault('B0916', 'Local SQL bindings must be at most 128 scalar or binary values')
+    let bytes = 0
+    for (const value of bind) {
+      if (typeof value === 'number' && !Number.isFinite(value)) throw fault('B0916', 'Local SQL numeric bindings must be finite')
+      bytes += value instanceof Uint8Array ? value.byteLength : typeof value === 'string' ? new TextEncoder().encode(value).length : 8
+      if (bytes > 1048576) throw fault('B0914', 'Local SQL bindings exceed 1 MiB; split the operation')
+    }
+    const leading = sql.replace(/^(?:\s+|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)+/, '')
+    if (/^(?:begin|commit|rollback|savepoint|release|attach|detach|pragma|vacuum)\b/i.test(leading)) throw fault('B0916', 'Use native batch() for transactions; attachment, pragma and maintenance commands are not public query operations')
+    let stmt, phase = "prepare"
+    try {
+      stmt = state.db.prepare(sql)
+      phase = "statement boundary"
+      const consumed = state.c.sqlite3_sql(stmt.pointer)
+      if (typeof consumed !== 'string' || !/^[\s;]*$/.test(sql.slice(consumed.length))) throw fault('B0916', 'Use batch() for multiple SQL statements')
+      phase = "read-only validation"
+      if (readonly && !state.c.sqlite3_stmt_readonly(stmt.pointer)) throw fault('B0916', 'query() accepts read-only statements; use execute() or batch() for mutations')
+      phase = "binding"
+      if (stmt.parameterCount !== bind.length) throw fault('B0916', 'Local SQL binding count does not match the prepared statement')
+      if (bind.length) stmt.bind(bind)
+      phase = "execution"
+      const rows = []
+      let size = 0
+      while (stmt.step()) {
+        if (rows.length >= 200) throw fault('B0914', 'Local SQL returned more than 200 rows; add LIMIT and keyset pagination')
+        const row = stmt.get(Object.create(null))
+        for (const key of Object.keys(row)) {
+          if (typeof row[key] === 'bigint') row[key] = String(row[key])
+          const value = row[key]
+          if (typeof value === 'number' && !Number.isFinite(value)) throw fault('B0916','Local SQL returned a non-finite number; cast it to a bounded application value')
+          size += key.length * 2 + (value instanceof Uint8Array ? value.byteLength : typeof value === 'string' ? new TextEncoder().encode(value).length : 8)
+        }
+        if (size > 2097152) throw fault('B0914', 'Local SQL response exceeds 2 MiB; select fewer columns or rows')
+        rows.push(row)
+      }
+      return { rows, changes: state.db.changes(), bytes:size }
+    } catch (e) {
+      throw /^B091[46]$/.test(e?.code || '') ? e : fault('B0916', 'Local SQL operation failed during ' + phase + '; inspect the query and schema in development without exposing SQL values in production')
+    } finally { try { stmt?.finalize() } catch { throw fault('B0916','Local SQL statement cleanup failed; close the owned worker before retrying') } }
+  }
+  return {
+    query(sql, bind) { return enqueue(state => statement(state, sql, bind, true).rows) },
+    execute(sql, bind) { return enqueue(state => { let result; state.db.transaction(() => { result = statement(state, sql, bind) }); return result }) },
+    batch(operations) {
+      if (!Array.isArray(operations) || operations.length > 64) return Promise.reject(fault('B0914', 'Local SQL batches accept at most 64 operations'))
+      return enqueue(state => {
+        let result
+        state.db.transaction(() => {
+          let bytes=0, rows=0
+          result=operations.map(o => {
+            const value=statement(state,o.sql,o.bind); bytes+=value.bytes; rows+=value.rows.length
+            if (bytes>2097152 || rows>200) throw fault('B0914','Local SQL batch response exceeds 200 rows or 2 MiB; paginate the operation')
+            return value
+          })
+        })
+        return result
+      })
+    },
+    close() { closed = true; release(); return chain.then(() => true) },
+    info() { return { engine:'official-sqlite-wasm', storage:'opfs-sahpool', namespace, name, pending, closed, maxRows:200, maxDatabaseBytes:67108864 } },
+  }
+}

package/brain-storage.js

@@ -0,0 +1,143 @@
+// Native structured local data. Browser storage is untrusted, evictable and never an authentication authority.
+const G = globalThis
+const error = (code, fix, cause) => Object.assign(new Error(fix), { code, fix, cause })
+const identifier = n => typeof n === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(n)
+
+export async function storageInfo() {
+  const s = G.navigator?.storage
+  let estimate = null, persisted = false
+  try { estimate = s?.estimate ? await s.estimate() : null; persisted = s?.persisted ? await s.persisted() : false } catch {}
+  return { indexedDB: !!G.indexedDB, opfs: !!s?.getDirectory, persisted,
+    usage: Number.isFinite(estimate?.usage) ? estimate.usage : null,
+    quota: Number.isFinite(estimate?.quota) ? estimate.quota : null }
+}
+
+// Request only from a user action; browsers may refuse. Never promise permanent storage.
+export async function persistStorage() {
+  return G.navigator?.storage?.persist ? !!(await G.navigator.storage.persist()) : false
+}
+
+export function database(name, options = {}) {
+  if (!identifier(name)) throw error('B0913', 'database: use a stable alphanumeric name of at most 80 characters')
+  const namespace = options.namespace || 'app'
+  if (!identifier(namespace)) throw error('B0913', 'database: use an explicit stable application namespace')
+  const build = options.build == null ? '' : String(options.build)
+  if (build.length > 128) throw error('B0913', 'database: build identifiers must be at most 128 characters')
+  let opening = null, connection = null, closed = false, pending = 0
+  const active = new Set()
+  const deadline = Math.max(100, Math.min(30000, Number(options.timeout) || 10000))
+  const fail = e => error(e?.name === 'QuotaExceededError' ? 'B0914' : 'B0913',
+    e?.name === 'QuotaExceededError' ? 'Local storage quota exceeded; evict owned cache records or reduce stored data' : 'Local database unavailable; keep authoritative data on the server and retry the operation', e)
+  function open() {
+    if (closed) return Promise.reject(error('B0913', 'database: connection was closed; create a new handle'))
+    if (opening) return opening
+    if (!G.indexedDB) return Promise.reject(error('B0913', 'IndexedDB is unavailable; use a server-backed data source'))
+    opening = new Promise((resolve, reject) => {
+      let settled = false
+      const r = G.indexedDB.open(`brain:db:${namespace}:${name}`, 1)
+      const timer = setTimeout(() => done(error('B0913', 'Local database open timed out; close an older tab holding an upgrade lock')), deadline)
+      const done = e => { if (!settled) { settled = true; clearTimeout(timer); reject(e) } }
+      r.onupgradeneeded = () => { if (!r.result.objectStoreNames.contains('records')) r.result.createObjectStore('records') }
+      r.onblocked = () => done(error('B0913', 'Local database upgrade blocked; close older tabs and retry'))
+      r.onerror = () => done(fail(r.error))
+      r.onsuccess = () => {
+        if (settled || closed) { r.result.close(); return }
+        settled = true; clearTimeout(timer)
+        connection = r.result
+        connection.onversionchange = () => { connection?.close(); connection = null; opening = null }
+        connection.onclose = () => { connection = null; opening = null }
+        resolve(connection)
+      }
+    }).catch(e => { opening = null; throw e })
+    return opening
+  }
+  function key(k) {
+    if (typeof k !== 'string' || !k.length || k.length > 256) throw error('B0913', 'database: keys must contain between 1 and 256 characters')
+    return k
+  }
+  function record(value, ttl) {
+    if (!Number.isFinite(ttl) || ttl < 0 || ttl > 31536000000) throw error('B0913', 'database: ttl must be between zero and one year in milliseconds')
+    let bytes, json
+    try { json = JSON.stringify(value); if (json === undefined) throw new TypeError('undefined'); bytes = new TextEncoder().encode(json).length } catch (e) { throw error('B0913', 'database: values must be JSON-serializable', e) }
+    if (bytes > 1048576) throw error('B0914', 'database: split records larger than 1 MiB or use OPFS for large files')
+    return { v: 1, build, expires: ttl ? Date.now() + ttl : 0, value: JSON.parse(json) }
+  }
+  const valid = r => r?.v === 1 && r.build === build && (!r.expires || r.expires > Date.now())
+  async function transaction(mode, work) {
+    if (pending >= 32) throw error('B0914', 'database: await pending local operations before scheduling more work')
+    pending++
+    try {
+      const db = await open()
+      if (closed) throw error('B0913', 'database: handle was closed')
+      return await new Promise((resolve, reject) => {
+        const tx = db.transaction('records', mode), store = tx.objectStore('records')
+        active.add(tx)
+        let result, reason
+        const timer = setTimeout(() => { reason = error('B0913', 'Local transaction timed out; reduce the batch size'); try { tx.abort() } catch {} }, deadline)
+        tx.oncomplete = () => { clearTimeout(timer); active.delete(tx); resolve(result) }
+        tx.onabort = tx.onerror = () => { clearTimeout(timer); active.delete(tx); reject(reason || fail(tx.error)) }
+        try { work(store, v => { result = v }) } catch (e) { reason = e; try { tx.abort() } catch { clearTimeout(timer); reject(e) } }
+      })
+    } catch (e) { throw e?.code ? e : fail(e) } finally { pending-- }
+  }
+  const api = {
+    get(k) { key(k); return transaction('readonly', (s, done) => { const r = s.get(k); r.onsuccess = () => done(valid(r.result) ? r.result.value : null) }) },
+    put(k, value, o = {}) { key(k); const r = record(value, o.ttl ?? 0); return transaction('readwrite', s => s.put(r, k)) },
+    delete(k) { key(k); return transaction('readwrite', s => s.delete(k)) },
+    clear() { return transaction('readwrite', s => s.clear()) },
+    batch(operations) {
+      if (!Array.isArray(operations) || operations.length > 128) throw error('B0914', 'database: atomic batches accept at most 128 operations')
+      let bytes = 0
+      const ops = operations.map(o => {
+        key(o.key)
+        if (o.op === 'delete') return { op: 'delete', key: o.key }
+        if (o.op !== 'put') throw error('B0913', 'database: batch operations must be put or delete')
+        const r = record(o.value, o.ttl ?? 0)
+        bytes += new TextEncoder().encode(JSON.stringify(r)).length
+        if (bytes > 4194304) throw error('B0914', 'database: atomic batch exceeds 4 MiB')
+        return { op: 'put', key: o.key, record: r }
+      })
+      return transaction('readwrite', s => { for (const o of ops) o.op === 'put' ? s.put(o.record, o.key) : s.delete(o.key) })
+    },
+    scan(o = {}) {
+      const limit = Math.max(1, Math.min(200, Number(o.limit) || 50)), prefix = o.prefix || '', after = o.after || ''
+      if (typeof prefix !== 'string' || prefix.length > 256 || typeof after !== 'string' || after.length > 256) throw error('B0913', 'database: scan prefixes and cursors must be strings of at most 256 characters')
+      return transaction('readonly', (s, done) => {
+        const items = [], r = s.openCursor(after ? G.IDBKeyRange.lowerBound(after, true) : prefix ? G.IDBKeyRange.lowerBound(prefix) : null)
+        let visited = 0, bytes = 0, previous = null
+        r.onsuccess = () => {
+          const c = r.result
+          if (!c) return done({ items, cursor: null })
+          const k = String(c.key)
+          if (prefix && k < prefix) { c.continue(prefix); return }
+          if (prefix && !k.startsWith(prefix)) return done({ items, cursor: null })
+          visited++
+          if (valid(c.value)) {
+            bytes += new TextEncoder().encode(JSON.stringify(c.value.value)).length
+            if (bytes > 2097152) return done({ items, cursor: previous })
+            items.push({ key: k, value: c.value.value })
+          }
+          previous = k
+          if (items.length >= limit || visited >= 1000) return done({ items, cursor: k })
+          c.continue()
+        }
+      })
+    },
+    prune() {
+      return transaction('readwrite', (s, done) => {
+        let visited = 0, deleted = 0
+        const r = s.openCursor()
+        r.onsuccess = () => {
+          const c = r.result
+          if (!c || visited >= 1000) return done({ visited, deleted, truncated: !!c })
+          visited++
+          if (!valid(c.value)) { c.delete(); deleted++ }
+          c.continue()
+        }
+      })
+    },
+    close() { closed = true; for (const tx of active) { try { tx.abort() } catch {} }; connection?.close(); connection = null },
+    info: storageInfo,
+  }
+  return api
+}

package/brain-threads.js

@@ -0,0 +1,49 @@
+// Thin adapters over platform APIs. Experimental worklets are capabilities, never assumed browser support.
+const G = globalThis
+const fail = fix => Object.assign(new Error(fix), {code:'B0917',fix})
+function local(url) {
+  if (!G.location) throw fail('Thread module loading requires a browser context')
+  const value = new URL(url,G.location.href)
+  if (value.origin !== G.location.origin || value.username || value.password || !/^https?:$/.test(value.protocol)) throw fail('Use a same-origin versioned module URL without credentials')
+  return value.href
+}
+export function threadCapabilities() {
+  return { dedicated:typeof G.Worker==='function', shared:typeof G.SharedWorker==='function',
+    service:!!G.navigator?.serviceWorker, messageChannel:typeof G.MessageChannel==='function',
+    transferableArrayBuffer:typeof G.ArrayBuffer==='function', sharedMemory:!!G.crossOriginIsolated&&typeof G.SharedArrayBuffer==='function'&&!!G.Atomics,
+    offscreenCanvas:typeof G.OffscreenCanvas==='function', wasm:!!G.WebAssembly,
+    audioWorklet:typeof G.AudioWorkletNode==='function', paintWorklet:!!G.CSS?.paintWorklet?.addModule,
+    layoutWorklet:!!G.CSS?.layoutWorklet?.addModule, animationWorklet:!!G.CSS?.animationWorklet?.addModule,
+    indexedDB:!!G.indexedDB, opfs:!!G.navigator?.storage?.getDirectory,
+    backgroundSync:!!G.ServiceWorkerRegistration?.prototype&&'sync' in G.ServiceWorkerRegistration.prototype,
+    push:typeof G.PushManager==='function' }
+}
+export async function loadWorklet(kind,url,options={}) {
+  const target = kind==='audio' ? options.context?.audioWorklet : kind==='paint' ? G.CSS?.paintWorklet : kind==='layout' ? G.CSS?.layoutWorklet : kind==='animation' ? G.CSS?.animationWorklet : null
+  if (!target?.addModule) {
+    if (typeof options.fallback==='function') return options.fallback()
+    throw fail('Requested worklet is unavailable; supply an explicit rendering/audio fallback')
+  }
+  // addModule has no portable cancellation. Bound outstanding requests and avoid spawning an AudioContext implicitly.
+  if (loading>=4) throw fail('Too many worklet loads; await existing modules')
+  loading++
+  try { await target.addModule(local(url),{credentials:'omit'}); return {available:true,kind} }
+  catch { throw fail('Worklet module could not load; check its same-origin asset URL and production CSP') }
+  finally { loading-- }
+}
+let loading=0
+export function messageChannel() {
+  if (!G.MessageChannel) throw fail('MessageChannel is unavailable in this context')
+  const c=new G.MessageChannel()
+  return {port1:c.port1,port2:c.port2,close(){c.port1.close();c.port2.close()}}
+}
+export function offscreen(canvas) {
+  if (!canvas?.transferControlToOffscreen) throw fail('OffscreenCanvas transfer is unavailable; keep the canvas on the main thread')
+  try { return canvas.transferControlToOffscreen() }
+  catch { throw fail('Canvas was already initialized or transferred; transfer it before acquiring a rendering context') }
+}
+export function sharedMemory(bytes) {
+  if (!threadCapabilities().sharedMemory) throw fail('Shared memory needs cross-origin isolation and browser support; use transferable ArrayBuffers otherwise')
+  if (!Number.isSafeInteger(bytes)||bytes<1||bytes>8388608) throw fail('Shared memory buffers must contain between 1 byte and 8 MiB')
+  return new G.SharedArrayBuffer(bytes)
+}

package/brain-time.js

@@ -0,0 +1,77 @@
+// Pure native date operations. Calendar arithmetic is UTC; timezone projection never changes the instant.
+const MS = { ms: 1, second: 1000, minute: 60000, hour: 3600000, day: 86400000, week: 604800000 }
+let zones
+const monthDays = (y, m) => m === 1 ? (y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28) : [31, 0, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][m]
+export function dateParse(value) {
+  if (value instanceof Date) value = value.getTime()
+  if (typeof value === 'number') {
+    const instant = new Date(value).getTime()
+    if (!Number.isFinite(value) || !Number.isFinite(instant)) throw RangeError('dateParse: invalid epoch milliseconds')
+    return instant
+  }
+  if (typeof value !== 'string') throw TypeError('dateParse: use epoch milliseconds, Date or an ISO date')
+  const match = /^(\d{4})-(\d{2})-(\d{2})(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2}))?$/.exec(value)
+  if (!match) throw RangeError('dateParse: datetime strings require an explicit timezone')
+  const y = +match[1], m = +match[2], d = +match[3]
+  if (m < 1 || m > 12 || d < 1 || d > monthDays(y, m - 1)) throw RangeError('dateParse: invalid calendar date')
+  const result = Date.parse(value)
+  if (!Number.isFinite(result)) throw RangeError('dateParse: invalid ISO date')
+  return result
+}
+export function dateAdd(value, amount, unit = 'day') {
+  const start = dateParse(value)
+  if (!Number.isFinite(amount)) throw RangeError('dateAdd: amount must be finite')
+  if (Object.hasOwn(MS, unit)) return dateParse(start + amount * MS[unit])
+  if (!['month', 'year'].includes(unit) || !Number.isSafeInteger(amount)) throw RangeError('dateAdd: use a supported unit and integer calendar amount')
+  const date = new Date(start), day = date.getUTCDate()
+  const months = date.getUTCFullYear() * 12 + date.getUTCMonth() + (unit === 'month' ? amount : 0)
+  const year = Math.floor(months / 12) + (unit === 'year' ? amount : 0), month = months - Math.floor(months / 12) * 12
+  // Set the complete calendar date once: day 1 or the end of a month can be outside Date's valid range.
+  date.setUTCFullYear(year, month, Math.min(day, monthDays(year, month)))
+  if (!Number.isFinite(date.getTime())) throw RangeError('dateAdd: calendar overflow')
+  return dateParse(date)
+}
+export function dateDiff(left, right, unit = 'day') {
+  if (!Object.hasOwn(MS, unit)) throw RangeError('dateDiff: elapsed units are ms, second, minute, hour, day or week')
+  return (dateParse(left) - dateParse(right)) / MS[unit]
+}
+export function dateRange(start, end, options = {}) {
+  let cursor = dateParse(start)
+  const stop = dateParse(end), step = options.step ?? 1, unit = options.unit ?? 'day', limit = options.limit ?? 1000
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000 || !Number.isFinite(step) || step === 0) throw RangeError('dateRange: nonzero step and limit 1..10000 required')
+  if (!Object.hasOwn(MS, unit) && !(['month', 'year'].includes(unit) && Number.isSafeInteger(step))) throw RangeError('dateRange: supported unit and integer calendar step required')
+  if ((stop - cursor) * step < 0) throw RangeError('dateRange: step must point toward the end')
+  const out = []
+  while (step > 0 ? cursor <= stop : cursor >= stop) {
+    if (out.length === limit) throw RangeError('dateRange: result exceeds limit')
+    out.push(cursor)
+    if (cursor === stop) break
+    const next = dateAdd(cursor, step, unit)
+    if (step > 0 ? next <= cursor : next >= cursor) throw RangeError('dateRange: step does not advance')
+    cursor = next
+  }
+  return out
+}
+export function dateZone(value, timeZone) {
+  const instant = dateParse(value)
+  if (typeof timeZone !== 'string' || !timeZone || timeZone.length > 128 || /^[+-]/.test(timeZone)) throw TypeError('dateZone: explicit IANA timezone required')
+  zones ||= new Map()
+  let formatter = zones.get(timeZone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-US-u-ca-gregory-nu-latn', { timeZone, era: 'short', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' })
+    if (zones.size === 16) zones.delete(zones.keys().next().value)
+    zones.set(timeZone, formatter)
+  }
+  const parts = {}
+  for (const part of formatter.formatToParts(instant)) if (part.type !== 'literal') parts[part.type] = part.type === 'era' ? part.value : Number(part.value)
+  if (parts.era === 'BC') parts.year = 1 - parts.year
+  // Gregorian calendars repeat every 400 years. Project both calendar dates into the same safe cycle,
+  // preserving the difference even when the local wall clock lies beyond Date's global epoch bounds.
+  const reference = new Date(instant), cycle = Math.floor(reference.getUTCFullYear() / 400) * 400
+  reference.setUTCFullYear(reference.getUTCFullYear() - cycle)
+  reference.setUTCMilliseconds(0)
+  const local = new Date(0)
+  local.setUTCFullYear(parts.year - cycle, parts.month - 1, parts.day)
+  local.setUTCHours(parts.hour, parts.minute, parts.second, 0)
+  return { timeZone, instant, year: parts.year, month: parts.month, day: parts.day, hour: parts.hour, minute: parts.minute, second: parts.second, offsetMinutes: (local.getTime() - reference.getTime()) / 60000 }
+}

package/brain-url.js

@@ -0,0 +1,125 @@
+// Shareable public navigation state. Credentials, form contents and transient busy/error state do not belong in URLs.
+import { sig, fx, _rt, untrack } from './brain.js'
+const G = globalThis, I = _rt(), bindings = new Map(), known = new Set()
+const privateKey = /password|secret|token|authorization|session|csrf|jwt|email|credit/i
+let listening = false, reports = 0
+const report = fix => { if (reports++ < 32) { const e = Object.assign(new Error(fix), { code: 'B0915', fix }); G.reportError ? G.reportError(e) : console.warn(e.message) } }
+const scalar = v => typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v))
+const safe = v => scalar(v) && String(v).length <= 512 && !/[\u0000-\u001f\u007f]/.test(String(v)) && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(v))
+const encode = v => Array.isArray(v) ? (v.length <= 32 && v.every(safe) ? JSON.stringify(v) : null) : safe(v) ? String(v) : null
+function decode(raw, base) {
+  if (raw == null) return base
+  let v = raw
+  if (typeof base === 'boolean') { if (!/^(true|false)$/.test(raw)) return base; v = raw === 'true' }
+  else if (typeof base === 'number') { if (!/^-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(raw)) return base; v = Number(raw) }
+  else if (Array.isArray(base)) { try { v = JSON.parse(raw) } catch { return base }; if (!Array.isArray(v) || (base.length && v.some(x => typeof x !== typeof base[0]))) return base }
+  return encode(v) == null ? base : v
+}
+function restore() {
+  if (!G.location) return
+  const url = new URL(G.location.href)
+  for (const [key, b] of bindings) if (b.path === url.pathname) {
+    const value = decode(url.searchParams.get(key), b.base)
+    b.last = encode(value)
+    b.cell.v = value
+  }
+  G.__brainRouted?.()
+}
+G.__brainURLOnly = (from, to) => {
+  try {
+    const a = new URL(from, G.location.href), b = new URL(to, G.location.href)
+    if (a.origin !== b.origin || a.pathname !== b.pathname || a.hash !== b.hash) return false
+    if (a.href === b.href) return true
+    for (const key of known) { a.searchParams.delete(key); b.searchParams.delete(key) }
+    return a.href === b.href
+  } catch { return false }
+}
+G.__brainURLRestore = restore
+
+export function urlState(initial, options) {
+  const cell = sig(initial)
+  if (!options?.disabled) urlBind(cell, options?.key, options)
+  return cell
+}
+
+// A native UI primitive stays stateless in author source; its DOM adapter owns navigation state and cleanup.
+export function urlDialog(element, key) {
+  if (!element || !key || G.__brainSSR || G.__brainRoute || !G.location) return
+  return I.root(dispose => {
+    let alive = true
+    const opened = urlState(!!element.open, {key})
+    const read = () => { if (alive) opened.v = !!element.open }
+    const apply = value => {
+      if (!alive || !element.isConnected) return
+      if (value && !element.open) element.showModal()
+      else if (!value && element.open) element.close()
+    }
+    fx(() => {
+      const value = opened.v
+      if (element.isConnected) apply(value)
+      else queueMicrotask(() => apply(value))
+    })
+    const observer = G.MutationObserver ? new G.MutationObserver(read) : null
+    observer?.observe(element, {attributes:true,attributeFilter:['open']})
+    element.addEventListener('close',read)
+    element.addEventListener('toggle',read)
+    fx(() => () => {
+      alive = false
+      observer?.disconnect()
+      element.removeEventListener('close',read)
+      element.removeEventListener('toggle',read)
+    })
+    return dispose
+  }, I.owner())
+}
+
+// Internal compiler binding for public select/tab/modal signals, once during component setup.
+export function urlBind(cell, key, options = {}) {
+  if (G.__brainRoute || G.__brainSSR) {
+    if (typeof key === 'string' && key.length <= 200 && !privateKey.test(key) && encode(untrack(() => cell.v)) != null) {
+      const raw = G.__brainRoute?.query?.[key]
+      cell.v = decode(typeof raw === 'string' ? raw : null, untrack(() => cell.v))
+    }
+    return cell
+  }
+  if (!G.location || !G.history) return cell
+  if (typeof key !== 'string' || !key.length || key.length > 200 || privateKey.test(key) || encode(untrack(() => cell.v)) == null) {
+    report('URL state needs a stable public key and bounded scalar value; keep credentials and form contents in private state')
+    return cell
+  }
+  const owner = I.owner()
+  if (!owner) { report('URL state must belong to a component so its listeners can be disposed'); return cell }
+  const previous = bindings.get(key)
+  if (previous) {
+    if (previous.cell !== cell) report('Repeated URL state key; give repeated components distinct stable urlState keys')
+    return cell
+  }
+  if (bindings.size >= 128 || known.size >= 512) { report('URL state key capacity exceeded; reduce public state or reuse stable keys'); return cell }
+  const base = untrack(() => cell.v), url = new URL(G.location.href)
+  if (url.search.length > 8192) { report('URL state exceeds 8 KiB; shorten public selections'); return cell }
+  cell.v = decode(url.searchParams.get(key), base)
+  const b = { cell, base, path: url.pathname, last: encode(cell.v) }
+  bindings.set(key, b); known.add(key)
+  if (!listening) { G.addEventListener('popstate', restore); listening = true }
+  fx(() => {
+    const value = encode(cell.v)
+    if (value === b.last) return
+    b.last = value
+    if (value == null) { report('URL state value is private, unsupported or too large; keep it out of navigation state'); return }
+    const next = new URL(G.location.href)
+    if (next.pathname !== b.path) return
+    if (value === encode(base)) next.searchParams.delete(key)
+    else next.searchParams.set(key, value)
+    if (next.search.length > 8192) { report('URL state exceeds 8 KiB; shorten public selections'); return }
+    if (next.href === G.location.href) return
+    try {
+      G.history[options.history === 'replace' ? 'replaceState' : 'pushState'](G.history.state, '', next.href)
+      G.__brainRouted?.()
+    } catch { report('URL state history write failed; reduce the frequency of changes or use history: replace') }
+  })
+  fx(() => () => {
+    if (bindings.get(key) === b) bindings.delete(key)
+    if (!bindings.size && listening) { G.removeEventListener('popstate', restore); listening = false }
+  })
+  return cell
+}