@christianirack/brainllm-runtime 0.8.12 → 0.9.0

package/brain-links.js

@@ -14,8 +14,10 @@ export default function links(lang, b, p, re, s) {
     const t = tables[document.documentElement.getAttribute('lang')]
     if (!t || !h || h[0] !== '/' || h[1] === '/') return h
     const a = t.b && (h + '/').startsWith(t.b + '/') ? h.slice(t.b.length) || '/' : h
-    const m = /^[^?#]*/.exec(a)[0]
-    const n = t.s[m] || (t.re.test(m) && (m === '/' ? t.p : t.p + m))
+    const m = /^[^?#]*/.exec(a)[0], key = m.replace(/\/+$/, '') || '/'
+    if (key === t.p || key.startsWith(t.p + '/')) return h
+    let n = t.s[key] || (t.re.test(key) && (key === '/' ? t.p : t.p + key))
+    if (n && key !== '/' && m.endsWith('/') && !n.endsWith('/')) n += '/'
     return n ? t.b + n + a.slice(m.length) : h
   }
   G.__brainHref = to

package/brain-list.js

@@ -0,0 +1,9 @@
+// Pure bounded integer iteration, outside the runtime core.
+export function range(from, to) {
+  if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to)) throw new RangeError('range requires two safe integer endpoints')
+  const length = Math.max(0, to - from)
+  if (length > 10000) throw new RangeError('range cannot emit more than 10000 integers')
+  const values = new Array(length)
+  for (let i = 0; i < length; i++) values[i] = from + i
+  return values
+}

package/brain-prefetch-shared.js

@@ -29,7 +29,7 @@ export async function prefetchPage(url, signal) {
     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)
+      if (asset.origin === base.origin && (asset.pathname.includes('/_b/') || /\/[a-z0-9]{8}\.(?:js|mjs|jsbrain|css|cssbrain)$/.test(asset.pathname))) assets.push(asset.href)
     }
     return { ok: true, status: r.status, url: r.url, headers: r.headers, text, bytes, assets }
   } catch { return null }

package/brain-router.js

@@ -96,6 +96,10 @@ export function router(o = {}) {
   const region = o.region || 'main'
   const parse = o.parse || (h => new DOMParser().parseFromString(h, 'text/html'))
   const fullLoad = new Set((o.fullLoad || []).map(p => new URL(p, location.href).pathname.replace(/\/+$/, '') || '/'))
+  // COOP belongs to the document, not the swapped view. Only real head markers opt into provider popups.
+  const popup = d => [...((d.head || d.querySelector('head'))?.querySelectorAll('meta') || [])].some(m =>
+    /^(brain-google-signin|brain-apple-signin)$/i.test(m.getAttribute('name') || '') && m.getAttribute('content') === '1')
+  const popupDocument = popup(document)
   let seq = 0, through = null, stale = false
   const ahead = predict(o, (u, p = true) => same(u, p))
   // Build signature (§35.7): the page's <meta name="brain-build">. A navigation response from another build, or the
@@ -205,6 +209,7 @@ export function router(o = {}) {
       if (!r.ok || !/html/.test(hd('content-type') || 'html')) throw Error(r.status)
       const doc = parse(await r.text())
       if (my !== seq) return // a newer navigation won
+      if (popup(doc) !== popupDocument) return hard(url) // entering or leaving a popup page needs fresh HTTP headers
       // another language (§37): a full load brings its own dictionaries, `lang` and `dir`; locales never mix in memory
       const lang = d => d?.documentElement?.getAttribute('lang')
       if (lang(doc) && lang(document) && lang(doc) !== lang(document)) return hard(url)
@@ -308,7 +313,7 @@ export function router(o = {}) {
     const h = e => {
       if (through && e.destination.url === through) return void (through = null)
       if (e.navigationType === 'reload') return // a reload is always a real full load (e.g. after a deploy deleted a chunk)
-      if (!e.canIntercept || e.hashChange || e.downloadRequest || e.formData || !same(e.destination.url)) return
+      if (!e.canIntercept || e.hashChange || e.downloadRequest || e.formData || externalLink(e.sourceElement) || !same(e.destination.url)) return
       if (e.cancelable && !leave()) return e.preventDefault()
       const to = e.destination.url, from = nav.currentEntry?.url
       if (G.__brainURLOnly?.(from || location.href, to)) return e.intercept({ focusReset: 'manual', handler: () => G.__brainURLRestore?.() })
@@ -362,7 +367,7 @@ export function router(o = {}) {
     if (e.defaultPrevented || e.button || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
     let a = e.target
     while (a && a.tagName !== 'A') a = a.parentNode
-    if (!a || !a.getAttribute('href') || a.getAttribute('target') || a.hasAttribute('download') || !same(a.href || a.getAttribute('href'))) return
+    if (!a || !a.getAttribute('href') || a.getAttribute('target') || a.hasAttribute('download') || externalLink(a) || !same(a.href || a.getAttribute('href'))) return
     const u = new URL(a.href || a.getAttribute('href'), location.href)
     if (u.pathname === location.pathname && u.hash) return // in-page anchor: native
     e.preventDefault()
@@ -416,7 +421,7 @@ export function predict(o = {}, same = () => false) {
     return !NOPE.test(u.pathname) && !FILE.test(u.pathname) && !SECRET.test(u.search)
   }
   const ok = a => {
-    if (!a?.getAttribute?.('href') || a.getAttribute('target') || a.hasAttribute('download')) return null
+    if (!a?.getAttribute?.('href') || a.getAttribute('target') || a.hasAttribute('download') || externalLink(a)) return null
     for (let n = a; n?.getAttribute; n = n.parentNode) if (n.getAttribute('data-prefetch') === 'false') return null
     const k = key(a.href || a.getAttribute('href'))
     return safe(k) ? k : null
@@ -426,7 +431,7 @@ export function predict(o = {}, same = () => false) {
     let n = 0
     for (const href of list) {
       const u = key(href)
-      if (!u || pre.has(u) || pre.size > 47 || !same(u) || !new URL(u).pathname.includes('/_b/') || ++n > 8) continue
+      if (!u || pre.has(u) || pre.size > 47 || !same(u) || !(new URL(u).pathname.includes('/_b/') || /\/[a-z0-9]{8}\.(?:js|mjs|jsbrain|css|cssbrain)$/.test(new URL(u).pathname)) || ++n > 8) continue
       const l = document.createElement('link')
       l.setAttribute('rel', /\.(js|jsbrain)(\?|$)/.test(u) ? 'modulepreload' : 'prefetch')
       l.setAttribute('href', u)
@@ -619,3 +624,5 @@ function hold(el) {
     },
   })
 }
+// An absolute navigation can intentionally belong to another site on the same origin.
+const externalLink = a => (a?.getAttribute?.('rel') || '').split(/\s+/).some(token => token.toLowerCase() === 'external') && /^https?:\/\//i.test((a?.getAttribute?.('href') || '').trim())

package/brain-text.js

@@ -0,0 +1,56 @@
+// Pure bounded Unicode matching; no locale, network, DOM or persistent state.
+const letters = value => {
+  if (typeof value !== 'string' || value.length > 8192) throw new RangeError('text helpers require strings of at most 4096 Unicode characters')
+  const result = Array.from(value)
+  if (result.length > 4096) throw new RangeError('text helpers require strings of at most 4096 Unicode characters')
+  return result
+}
+const fold = value => {
+  letters(value)
+  const result = value.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase()
+  letters(result)
+  return result
+}
+// Optimal string alignment: adjacent transpositions count as one edit; the band and row minimum bound work.
+const distance = (left, right, max = 2) => {
+  if (!Number.isInteger(max) || max < 0 || max > 64) throw new RangeError('text.distance max must be an integer from 0 to 64')
+  const a = letters(left), b = letters(right), n = a.length, m = b.length, cap = max + 1
+  if (Math.abs(n - m) > max) return cap
+  if (!n) return Math.min(m, cap)
+  if (!m) return Math.min(n, cap)
+  let before = new Uint16Array(m + 1).fill(cap)
+  let previous = new Uint16Array(m + 1).fill(cap)
+  let current = new Uint16Array(m + 1).fill(cap)
+  for (let j = 0; j <= Math.min(m, max); j++) previous[j] = j
+  for (let i = 1; i <= n; i++) {
+    const low = Math.max(1, i - max), high = Math.min(m, i + max)
+    current[0] = Math.min(i, cap)
+    if (low > 1) current[low - 1] = cap
+    if (high < m) current[high + 1] = cap
+    let minimum = current[0]
+    for (let j = low; j <= high; j++) {
+      let value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1), cap)
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) value = Math.min(value, before[j - 2] + 1)
+      current[j] = value
+      minimum = Math.min(minimum, value)
+    }
+    if (minimum > max) return cap
+    const spare = before; before = previous; previous = current; current = spare
+  }
+  return Math.min(previous[m], cap)
+}
+const fuzzy = (word, list) => {
+  const needle = fold(word), size = letters(needle).length
+  if (!Array.isArray(list) || list.length > 10000) throw new RangeError('text.fuzzy requires at most 10000 candidate strings')
+  const count = list.length, max = size < 4 ? 0 : size < 8 ? 1 : 2
+  const found = []
+  let units = 0
+  for (let i = 0; i < count; i++) {
+    const candidate = list[i]
+    if (typeof candidate !== 'string' || candidate.length > 1048576 - units) throw new RangeError('text.fuzzy candidate text exceeds 1048576 UTF-16 code units or contains a non-string')
+    units += candidate.length
+    if (distance(needle, fold(candidate), max) <= max) found.push(candidate)
+  }
+  return found
+}
+export const text = Object.freeze({ fold, distance, fuzzy })

package/brain-url.js

@@ -45,10 +45,35 @@ export function urlState(initial, options) {
 }
 
 // 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
+export function urlDialog(element, key, options) {
+  if (!element || G.__brainSSR || G.__brainRoute || !G.location) return
   return I.root(dispose => {
     let alive = true
+    if (options?.dismissible === true) {
+      let startedOutside = false
+      const outside = event => {
+        if (event.target !== element || !element.open) return false
+        const bounds = element.getBoundingClientRect()
+        return event.clientX < bounds.left || event.clientX > bounds.right || event.clientY < bounds.top || event.clientY > bounds.bottom
+      }
+      const down = event => { startedOutside = !event.defaultPrevented && event.button === 0 && event.isPrimary !== false && outside(event) }
+      const cancel = () => { startedOutside = false }
+      const click = event => {
+        const dismiss = alive && !event.defaultPrevented && startedOutside && event.button === 0 && outside(event)
+        startedOutside = false
+        if (dismiss) { event.preventDefault(); event.stopPropagation(); element.close() }
+      }
+      element.addEventListener('pointerdown', down)
+      element.addEventListener('pointercancel', cancel)
+      element.addEventListener('click', click)
+      fx(() => () => {
+        alive = false
+        element.removeEventListener('pointerdown', down)
+        element.removeEventListener('pointercancel', cancel)
+        element.removeEventListener('click', click)
+      })
+    }
+    if (!key) return dispose
     const opened = urlState(!!element.open, {key})
     const read = () => { if (alive) opened.v = !!element.open }
     const apply = value => {
@@ -59,7 +84,15 @@ export function urlDialog(element, key) {
     fx(() => {
       const value = opened.v
       if (element.isConnected) apply(value)
-      else queueMicrotask(() => apply(value))
+      else {
+        const wasOpen = !!element.open
+        queueMicrotask(() => {
+          // An exposed open() may run immediately after mount, before this initial deferred sync.
+          // Preserve that newer DOM action instead of applying the old initial state over it.
+          if (alive && !!element.open !== wasOpen) read()
+          else apply(value)
+        })
+      }
     })
     const observer = G.MutationObserver ? new G.MutationObserver(read) : null
     observer?.observe(element, {attributes:true,attributeFilter:['open']})

package/brain.js

@@ -350,20 +350,26 @@ export function _ev(e) {
         // a data property, not a getter: V8 keeps accessors in the event's shared hidden class, so a getter closure
         // would keep the first event (and its component) alive for the life of the page
         Object.defineProperty(e, 'currentTarget', { configurable: true, value: n })
-        try {
-          // n moves on with the loop: keep the element for a later rejection
-          const r = h.call(n, e), el = n
-          if (r && r.then) r.then(null, x => oops(x, el, 'on:' + e.type)) // async handler: a rejected await too
-        } catch (x) {
-          oops(x, n, 'on:' + e.type)
-        }
+        eventCall(n, h, e)
         if (e.cancelBubble) break
       }
     }
   })
 }
+function eventCall(el, h, e) {
+  try {
+    const r = h.call(el, e)
+    if (r && r.then) r.then(null, x => oops(x, el, 'on:' + e.type))
+  } catch (x) { oops(x, el, 'on:' + e.type) }
+}
 export function on(el, t, h) {
-  if (/^(focus|blur|mouseenter|mouseleave|load|error|scroll)$/.test(t)) return el.addEventListener(t, e => batch(() => h(e)))
+  if (/^(focus|blur|mouseenter|mouseleave|pointerenter|pointerleave|load|error|scroll|scrollend|resize|close|cancel|toggle|beforetoggle|invalid|abort|canplay|canplaythrough|durationchange|emptied|ended|loadeddata|loadedmetadata|loadstart|pause|play|playing|progress|ratechange|seeked|seeking|stalled|suspend|timeupdate|volumechange|waiting|encrypted|waitingforkey)$/.test(t)) {
+    const listener = e => batch(() => eventCall(el, h, e))
+    return fx(() => {
+      el.addEventListener(t, listener)
+      return () => el.removeEventListener(t, listener)
+    })
+  }
   el['$' + t] = h
   document.addEventListener(t, _ev) // once per type: the DOM ignores the same listener added again
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christianirack/brainllm-runtime",
-  "version": "0.8.12",
+  "version": "0.9.0",
   "description": "The BRAINLLM runtime for the Rust-built web compiler for LLMs: dependency-free ES modules (signals, DOM, router, data, forms, channels). The brain binary embeds this same version.",
   "type": "module",
   "exports": {

package/server/server.mjs

@@ -26,25 +26,30 @@ import { installNativeSockets } from './native-sockets.mjs'
 import { llmClient } from './llm.mjs'
 import { BlockList, isIP } from 'node:net'
 import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
 import zlib from 'node:zlib'
 import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
-import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync, statSync, lstatSync } from 'node:fs'
+import { constants as FS, existsSync, readFileSync, realpathSync, statSync, lstatSync } from 'node:fs'
+import { open } from 'node:fs/promises'
 import * as Module from 'node:module'
 import { basename, dirname, extname, join, normalize, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const MIME = {
   '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.brain': 'text/html; charset=utf-8', '.jsbrain': 'text/javascript; charset=utf-8', '.cssbrain': 'text/css; charset=utf-8',
   '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
   '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.avif': 'image/avif', '.gif': 'image/gif',
   '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain; charset=utf-8',
   '.xml': 'application/xml', '.webmanifest': 'application/manifest+json', '.map': 'application/json',
   '.mp4': 'video/mp4', '.webm': 'video/webm', '.pdf': 'application/pdf', '.wasm': 'application/wasm',
+  '.m3u8': 'application/vnd.apple.mpegurl', '.m3u': 'application/vnd.apple.mpegurl', '.m4s': 'video/iso.segment',
+  '.mpd': 'application/dash+xml', '.ts': 'video/mp2t', '.vtt': 'text/vtt; charset=utf-8', '.mp3': 'audio/mpeg',
   '.md': 'text/markdown; charset=utf-8', // llms.txt copies of the pages (§33), as brain start's static server sends them
 }
 // feeds are .xml files with their own type (SEO, §32)
 const FEEDS = { 'rss.xml': 'application/rss+xml; charset=utf-8', 'atom.xml': 'application/atom+xml; charset=utf-8' }
-const SECURITY = {
+const DEFAULT_SECURITY = {
   'strict-transport-security': 'max-age=63072000; includeSubDomains',
   'x-content-type-options': 'nosniff',
   'referrer-policy': 'strict-origin-when-cross-origin',
@@ -114,8 +119,10 @@ function safeLocation(value) {
 function linkTo(route, path) {
   const t = route && route.hrefs
   if (!t || typeof path !== 'string' || path[0] !== '/' || path[1] === '/') return path
-  const m = /^[^?#]*/.exec(path)[0]
-  const n = t.s[m] || (new RegExp(t.re).test(m) && (m === '/' ? t.p : t.p + m))
+  const m = /^[^?#]*/.exec(path)[0], key = m.replace(/\/+$/, '') || '/'
+  if (key === t.p || key.startsWith(t.p + '/')) return path
+  let n = t.s[key] || (new RegExp(t.re).test(key) && (key === '/' ? t.p : t.p + key))
+  if (n && key !== '/' && m.endsWith('/') && !n.endsWith('/')) n += '/'
   return n ? n + path.slice(m.length) : path
 }
 function localizeLinks(route, html) {
@@ -194,7 +201,9 @@ const cacheSearch = url => {
   return kept.size ? '?' + kept : ''
 }
 // Messages this file writes itself, safe to log as the cause; anything else in an error message may hold private data.
-const OWN_CAUSES = new Set(['Backend request unavailable', 'Backend request timed out', 'Backend response exceeds its byte budget', 'Backend request capacity is unavailable', 'Backend stream capacity is unavailable', 'Native file request failed', 'Native file response is invalid', 'Native resource response must be JSON', 'Native resource response is invalid', 'Native resource request failed', 'Invalid final response status', 'Invalid configured redirect location', 'timeout'])
+const AUTH_UNAVAILABLE_CAUSES = new Set(['the backend did not answer', 'the server is shutting down', '8 session checks are already in flight', 'the backend took more than 2 s'].map(why => `Native authentication is unavailable: ${why}`))
+const BACKEND_UNAVAILABLE_CAUSES = new Set(['Backend request unavailable', 'Backend request timed out', 'Backend response exceeds its byte budget', 'Native backend is unavailable', 'Native file request failed', 'Native file response is invalid', 'Native resource response must be JSON', 'Native resource response is invalid', 'Native resource request failed', 'Native authentication response is unavailable', ...AUTH_UNAVAILABLE_CAUSES])
+const OWN_CAUSES = new Set([...BACKEND_UNAVAILABLE_CAUSES, 'Backend request capacity is unavailable', 'Backend stream capacity is unavailable', 'Invalid same-site redirect location', 'Invalid redirect status', 'Invalid final response status', 'Invalid configured redirect location', 'Static file validators are busy; retry shortly', 'Static file validator deadline exceeded; retry shortly', 'Static file changed; retry shortly', 'Static file changed while computing its validator', 'timeout'])
 const CODE_SHAPE = /^[A-Z][A-Z0-9_]{0,63}$/
 const varyEncoding = v => (/accept-encoding/i.test(v || '') ? v : [v, 'Accept-Encoding'].filter(Boolean).join(', '))
 function bodyEncoding(req, status, headers) {
@@ -239,6 +248,14 @@ function googleSignInPage(page) {
 
 // One-use provider cookies (Google nonce, Apple nonce, LinkedIn state): relayed to the backend and cleared at logout.
 const PROVIDER_COOKIES = ['__Host-brain-google', '__Host-brain-apple', '__Host-brain-linkedin']
+// The native backend owns state, nonce and provider configuration. Only this fixed protocol destination is external.
+function providerStartRedirect(method, path, status, location) {
+  if (!['GET', 'HEAD'].includes(method) || path !== '/_brain/auth/linkedin/start' || status !== 303 || typeof location !== 'string' || /[\\\x00-\x20\x7f]/.test(location)) return false
+  try {
+    const target = new URL(location)
+    return target.origin === 'https://www.linkedin.com' && target.pathname === '/oauth/v2/authorization' && !target.username && !target.password && !target.hash
+  } catch { return false }
+}
 // One configured loopback authority. No user-controlled target, proxy, redirect, auth cache or pending queue.
 // ctx.backend.files(bucket): the same file calls as job and route handlers (docs/backend/files.md).
 function bucketClient(target, key, bucket, readBudgetMs = () => 0) {
@@ -341,7 +358,15 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession, r
   }
   const safeUser = user => {
     if (!user || typeof user.id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(user.id) || typeof user.email !== 'string' || user.email.length > 254 || typeof user.role !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(user.role) || ['public','owner'].includes(user.role) || typeof user.verified !== 'boolean') throw new HttpError(503,'Native authentication response is unavailable')
-    return Object.freeze({id:user.id,email:user.email,role:user.role,verified:user.verified})
+    const clean = {id:user.id,email:user.email,role:user.role,verified:user.verified}
+    if (typeof user.name === 'string' && user.name.trim() && user.name.length <= 400 && [...user.name].length <= 200 && !/[\u0000-\u001f\u007f-\u009f]/.test(user.name)) clean.name = user.name.trim()
+    if (typeof user.picture === 'string' && Buffer.byteLength(user.picture) <= 2048 && !/[\u0000-\u001f\u007f-\u009f]/.test(user.picture)) {
+      try {
+        const url = new URL(user.picture)
+        if (url.protocol === 'https:' && url.hostname && !url.username && !url.password) clean.picture = user.picture
+      } catch {}
+    }
+    return Object.freeze(clean)
   }
   const unavailable = (why = 'the backend did not answer') => new HttpError(503, `Native authentication is unavailable: ${why}`)
   const call = (incoming, response, path, method, rid, origin) => {
@@ -540,7 +565,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession, r
         const cookies = nativeCookies(backend.headers['set-cookie'])
         if (cookies.length) safe['set-cookie'] = cookies
         if (backend.statusCode >= 500 && !res.$capture) res.$brainCause = 'answered by the native backend'
-        try { reply(res,backend.statusCode || 502,req.method === 'HEAD' ? '' : Buffer.concat(chunks,bytes),safe); resolve() } catch (e) { reject(e) }
+        try { reply(res,backend.statusCode || 502,req.method === 'HEAD' ? '' : Buffer.concat(chunks,bytes),safe,providerStartRedirect(req.method,url.pathname,backend.statusCode,safe.location)); resolve() } catch (e) { reject(e) }
       }
       const cancel = () => { outgoing?.destroy(); finish(true) }
       const data = chunk => {
@@ -999,7 +1024,7 @@ export function createServer(o = {}) {
     // a thrown plain object, string or undefined has no stack: say what kind of value it was (never the value itself)
     if (!(e instanceof Error)) out.thrown = e === null ? 'null' : Array.isArray(e) ? 'array' : typeof e
     if (e && typeof e === 'object' && (e.temporary === true || e.status === 429 || e.status === 503)) out.temporary = true
-    if (e instanceof HttpError && (OWN_CAUSES.has(e.message) || e.message.startsWith('Native authentication is unavailable:'))) out.cause = e.message
+    if (e instanceof HttpError && OWN_CAUSES.has(e.message)) out.cause = e.message
     if (e && e.code === 'ERR_MODULE_NOT_FOUND') out.fix = 'this process runs an older build whose files are gone; restart it after brain build'
     if (e && CODE_SHAPE.test(e.transport || '')) out.transport = e.transport
     if (e && typeof e.code === 'string' && CODE_SHAPE.test(e.code)) out.backendCode = e.code
@@ -1010,6 +1035,11 @@ export function createServer(o = {}) {
     return out
   }
   const mf = readManifest(dist)
+  // The build policy controls attribution independently of CSP and other security headers.
+  let compilerBranding=mf.compilerBranding!==false
+  try {const path=join(dist,'brain-build.json'),meta=lstatSync(path);if(meta.isFile()&&!meta.isSymbolicLink()&&meta.size<=16384&&JSON.parse(readFileSync(path,'utf8')).compilerBranding===false)compilerBranding=false}catch{}
+  const SECURITY={...DEFAULT_SECURITY}
+  if(!compilerBranding)delete SECURITY['x-generated-by']
   // brain.json `server` (§11.1), written into the manifest by the build; createServer options and env still win
   const SL = mf.server || {}
   const TIMEOUT = +(o.timeout ?? env.BRAIN_TIMEOUT_MS ?? SL.timeoutMs ?? 10000)
@@ -1183,17 +1213,22 @@ export function createServer(o = {}) {
   // HTML: `no-cache` + ETag (strong for files, weak for SSR) → a repeat visit gets 304 with no body (§35); the ETag is
   // taken before the per-response nonce is injected, so it is stable
   const html = (res, status, page, headers = {}, etag) => {
+    // A 304 updates the cached document's policy too; keep it identical to its 200 without minting a CSP nonce.
+    headers = { 'cache-control': 'no-cache', ...(googleSignInPage(page) ? { 'cross-origin-opener-policy': 'same-origin-allow-popups' } : {}), ...(mf.build ? { 'x-brain-build': mf.build } : {}), ...headers }
     if (etag && status === 200) {
       headers = { etag, ...headers }
       const inm = res.req.headers['if-none-match']
       if (inm && inm.split(',').some(t => t.trim().replace(/^W\//, '') === etag.replace(/^W\//, ''))) return send(res, 304, '', headers)
     }
+    // RFC 9111 section 4.3.5 lets HEAD update cached GET headers without replacing its body.
+    // As with 304, omit a new body-bound policy so the cached script nonce remains authorized.
+    if (res.req.method === 'HEAD') return send(res, status, '', { 'content-type': MIME['.html'], ...headers })
     const nonce = randomBytes(16).toString('base64')
     // behavior analytics (docs/backend/analytics.md): with a native backend every page loads its collector as an async
     // module served by that backend, outside the build and the route budgets; BRAIN_ANALYTICS=off skips the tag
     if (analyticsTag && !page.includes(analyticsTag)) page = page.includes('</head>') ? page.replace('</head>', analyticsTag + '</head>') : page + analyticsTag
     const body = page.replace(/<script(?![^>]*\bnonce=)/g, `<script nonce="${nonce}"`)
-    send(res, status, body, { 'content-type': MIME['.html'], 'content-security-policy': withNonce(mf.csp || CSP0, nonce), 'cache-control': 'no-cache', ...(googleSignInPage(page) ? { 'cross-origin-opener-policy': 'same-origin-allow-popups' } : {}), ...(mf.build ? { 'x-brain-build': mf.build } : {}), ...headers })
+    send(res, status, body, { 'content-type': MIME['.html'], 'content-security-policy': withNonce(mf.csp || CSP0, nonce), ...headers })
   }
   const notFound = (req, res) => failPage(res, 404, res.getHeader('x-request-id'))
   // `gone()` from load (§33): 410 tells crawlers the URL was removed for good; views/410.brain, else the 404 page
@@ -1206,7 +1241,7 @@ export function createServer(o = {}) {
   }
   // `/403`, `/404.html`, `/503`…: the status when the app has that page, else 0 and the path is an ordinary one
   const reservedStatus = pathname => {
-    const m = /^\/(403|404|410|5\d\d)(?:\.html)?$/.exec(pathname)
+    const m = /^\/(403|404|410|5\d\d)(?:\.(?:html|brain))?$/.exec(pathname)
     if (!m) return 0
     const n = +m[1]
     return file(`${n}.html`) || (mf.errors && mf.errors[n]) || (n === 403 && mf.forbidden) || (n === 404 && mf.notFound) ? n : 0
@@ -1357,16 +1392,30 @@ export function createServer(o = {}) {
   }
   const anonymous = req => (req.method === 'GET' || req.method === 'HEAD') && !req.headers.authorization && !req.headers.cookie
 
+  const preloadHints = new WeakMap()
   async function ssr(req, res, route, params, url, rid, forms = null, status = 200, fixed = null, nocache = false) {
     // the route's preloads (the same Link values as _headers): on the response, where hosts turn them into early hints,
     // capped so a long list cannot trip a proxy's header buffer. A 103 (#232) only when opted in, and never to HTTP/1.0.
     if (route.links && route.links.length && !res.$capture && !res.$hinted) {
       res.$hinted = true
-      const link = route.links.join(', ')
-      if (link.length <= 2048 && !res.headersSent) res.setHeader('link', link)
-      if (EARLY_HINTS && res.writeEarlyHints && req.httpVersion !== '1.0') {
+      let selected = preloadHints.get(route)
+      if (!selected) {
+        selected = []
+        let bytes = 0
+        // Preserve graph order within a priority; render-blocking styles and fonts precede script hints.
+        const priority = value => /(?:^|;)\s*as=(?:style|font)(?:;|$)/.test(value) ? 0 : 1
+        for (const value of [...route.links].sort((a, b) => priority(a) - priority(b))) {
+          const size = Buffer.byteLength(value) + (selected.length ? 2 : 0)
+          if (bytes + size > 2048) continue
+          selected.push(value); bytes += size
+        }
+        preloadHints.set(route, selected)
+        if (selected.length < route.links.length) log('warn', 'preload hints trimmed to 2048 bytes; fix: reduce the route preload graph', { route: route.path, kept: selected.length, dropped: route.links.length - selected.length })
+      }
+      if (selected.length && !res.headersSent) res.setHeader('link', selected.join(', '))
+      if (selected.length && EARLY_HINTS && res.writeEarlyHints && req.httpVersion !== '1.0') {
         try {
-          res.writeEarlyHints({ link: route.links })
+          res.writeEarlyHints({ link: selected })
         } catch {}
       }
     }
@@ -1445,7 +1494,7 @@ export function createServer(o = {}) {
     // a page behind a guard passes it only for its visitor: it stays out of the index even when it renders (§33)
     if (route.guards && route.guards.length) res.setHeader('x-robots-tag', NOINDEX)
     // with seo.trailingSlash "ignore" both forms answer: the canonical takes the form the sitemap lists (no slash)
-    let out = head(page, seo, SLASH === 'always' || url.pathname === '/' ? url.pathname : url.pathname.replace(/\/+$/, '') || '/', url.search)
+    let out = head(page, seo, SLASH === 'always' || url.pathname === '/' ? url.pathname : url.pathname.replace(/\/+$/, '') || '/', url.search, route, BASE.slice(0, -1))
     // route params for route() in the browser (the client has no route table)
     if (params && Object.keys(params).length) out = out.replace('</head>', () => `<meta name="brain-params" content="${esc(JSON.stringify(params))}"></head>`)
     if (forms) out = out.replace('</body>', () => `<script type="application/json" id="brain-forms">${jsonInHtml(forms)}</script></body>`)
@@ -1483,9 +1532,18 @@ export function createServer(o = {}) {
     const seoF = sm.seo || (await load(route.view)).default.seo
     if (route.i18n) await load(route.i18n)
     const nonce = randomBytes(16).toString('base64'), n = h => h.replace(/<script(?![^>]*\bnonce=)/g, `<script nonce="${nonce}"`)
+    globalThis.__brainLocale = route.locale || null
+    let seo0 = null
+    try {
+      seo0 = typeof seoF === 'function' ? seoF({}) : null
+    } finally {
+      globalThis.__brainLocale = null
+    }
+    const initialHead = head(top, seo0, url.pathname, url.search, route, BASE.slice(0, -1))
     const enc = COMPRESS && req.method !== 'HEAD' ? acceptedEncodings(req.headers['accept-encoding'], DYNAMIC)[0] : null
     res.writeHead(200, {
-      ...SECURITY, 'content-type': MIME['.html'], 'content-security-policy': withNonce(mf.csp || CSP0, nonce), 'cache-control': 'no-cache',
+      ...SECURITY, 'content-type': MIME['.html'], ...(req.method === 'HEAD' ? {} : { 'content-security-policy': withNonce(mf.csp || CSP0, nonce) }), 'cache-control': 'no-cache',
+      ...(googleSignInPage(initialHead) ? { 'cross-origin-opener-policy': 'same-origin-allow-popups' } : {}),
       ...(mf.build ? { 'x-brain-build': mf.build } : {}), ...extra, ...ctx.session.headers(),
       ...(COMPRESS ? { vary: varyEncoding(extra.vary) } : {}), ...(enc ? { 'content-encoding': enc } : {}),
     })
@@ -1493,15 +1551,8 @@ export function createServer(o = {}) {
     const zs = enc ? encodeStream(enc) : null
     if (zs) zs.pipe(res)
     const write = s => (zs ? (zs.write(s), zs.flush()) : res.write(s))
-    globalThis.__brainLocale = route.locale || null
-    let seo0 = null
-    try {
-      seo0 = typeof seoF === 'function' ? seoF({}) : null
-    } finally {
-      globalThis.__brainLocale = null
-    }
     const at = { path: url.pathname, params: params || {}, query: Object.fromEntries(url.searchParams) }
-    write(n(head(top, seo0, url.pathname, url.search)))
+    write(n(initialHead))
     // QA #253: the folder's _loading.brain goes in the region with the first chunk (SPEC: shows while load runs),
     // between two marker comments; the last chunk starts with a script that removes them and what is between
     let clear = ''
@@ -1779,7 +1830,9 @@ export function createServer(o = {}) {
   }
   // §33 S01: every sitemap file holds at most 50 000 URLs and SITEMAP_BYTES bytes of UTF-8 XML; the dynamic URLs fill
   // /sitemap-dynamic.xml, /sitemap-dynamic-2.xml, … in sitemap() order, so the split is deterministic
-  const SET_HEAD = '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
+  const XML_SIGNATURE = compilerBranding ? '<!-- by BRAINLLM https://chrisifm.github.io/BRAINLLM/ -->' : ''
+  const XML_HEADER = `<?xml version="1.0" encoding="UTF-8"?>\n${XML_SIGNATURE}\n`
+  const SET_HEAD = XML_HEADER + '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
   const SET_FOOT = '</urlset>\n'
   const bytes = t => Buffer.byteLength(t)
   function pages(urls) {
@@ -1797,7 +1850,9 @@ export function createServer(o = {}) {
   async function serveSitemap(req, res, url) {
     const f = file('/sitemap.xml')
     if (!f) return false
-    const text = readFileSync(f, 'utf8')
+    const original = readFileSync(f, 'utf8')
+    const declaration = original.startsWith('<?xml') ? original.indexOf('?>') + 2 : 0
+    const text = !XML_SIGNATURE || original.includes(XML_SIGNATURE) ? original : declaration > 1 ? original.slice(0, declaration) + '\n' + XML_SIGNATURE + original.slice(declaration) : XML_SIGNATURE + '\n' + original
     const origin = mf.site || [...text.matchAll(/<loc>(https?:\/\/[^<]+)<\/loc>/g)].map(m => URL.canParse(m[1]) && new URL(m[1]).origin).find(Boolean)
     if (!origin) return false
     const index = text.includes('<sitemapindex')
@@ -1817,13 +1872,47 @@ export function createServer(o = {}) {
       index
         ? text.replace('</sitemapindex>', `${kids}</sitemapindex>`)
         : split
-          ? `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${child('/sitemap-static.xml')}${kids}</sitemapindex>\n`
+          ? `${XML_HEADER}<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${child('/sitemap-static.xml')}${kids}</sitemapindex>\n`
           : text.replace('</urlset>', sets[0] + '</urlset>'),
     )
     return true
   }
 
   // ---------- static ----------
+  // Content validators use bounded buffers and a bounded metadata cache; a full media file never enters the heap.
+  const fileTags = new Map(), hashingFiles = new Map()
+  async function fileTag(handle, stat) {
+    const key = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`
+    if (fileTags.has(key)) return fileTags.get(key)
+    if (hashingFiles.has(key)) return hashingFiles.get(key)
+    if (hashingFiles.size >= 8) throw new HttpError(503, 'Static file validators are busy; retry shortly')
+    const task = (async () => {
+      const hash = createHash('sha256'), buf = Buffer.alloc(65536), until = performance.now() + 30000
+      let offset = 0
+      while (offset < stat.size) {
+        if (performance.now() > until) throw new HttpError(503, 'Static file validator deadline exceeded; retry shortly')
+        const { bytesRead } = await handle.read(buf, 0, Math.min(buf.length, stat.size - offset), offset)
+        if (!bytesRead) throw new HttpError(503, 'Static file changed while computing its validator')
+        hash.update(buf.subarray(0, bytesRead)); offset += bytesRead
+      }
+      const after = await handle.stat()
+      if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) throw new HttpError(503, 'Static file changed; retry shortly')
+      const etag = '"' + hash.digest('base64url') + '"'
+      fileTags.set(key, etag)
+      if (fileTags.size > 256) fileTags.delete(fileTags.keys().next().value)
+      return etag
+    })()
+    hashingFiles.set(key, task)
+    try { return await task } finally { hashingFiles.delete(key) }
+  }
+  async function streamFile(req, res, handle, status, headers, span) {
+    if (req.method === 'HEAD') return send(res, status, '', headers)
+    res.writeHead(status, { ...SECURITY, ...(server.draining ? { connection: 'close' } : {}), ...headers })
+    // The descriptor stays pinned from stat and hashing through transmission, including atomic deployments.
+    const length = Number(headers['content-length'])
+    if (!length) return res.end()
+    await pipeline(handle.createReadStream({ start: 0, end: length - 1, ...span, autoClose: false }), res)
+  }
   // Never served (brain-pack private.rs holds the same list for the Rust handler and every generated host config).
   const PRIVATE_PREFIXES = ['_server', '_brain', 'server.mjs']
   const PRIVATE_FILES = ['_headers', '_redirects']
@@ -1851,7 +1940,7 @@ export function createServer(o = {}) {
   // site configured) or with a per-request pattern gets no header, so this never invents a URL.
   function twinCanonical(path) {
     const stem = path.replace(/\.md$/, '').replace(/\/+$/, '')
-    const page = file(stem ? stem + '.html' : 'index.html') || file(stem + '/index.html')
+    const page = file(stem ? stem + '.html' : 'index.html') || file(stem + '/index.html') || file(stem ? stem + '.brain' : 'index.brain') || file(stem + '/index.brain')
     if (!page) return {}
     const tag = /<link\b[^>]*\brel=["']canonical["'][^>]*>/i.exec(readFileSync(page, 'utf8'))?.[0]
     const href = tag && /\bhref="(https?:\/\/[^"<>\s]+)"/.exec(tag)?.[1].replaceAll('&amp;', '&')
@@ -1860,21 +1949,21 @@ export function createServer(o = {}) {
   // What exists whatever the routes say: generated sitemaps, built files and the icon browsers ask for by habit.
   async function serveFixed(req, res, url) {
     if (DYN.length && /^\/sitemap(-static|-dynamic(-\d+)?)?\.xml$/.test(url.pathname) && (await serveSitemap(req, res, url))) return true
-    if (serveStatic(req, res, url)) return true
+    if (await serveStatic(req, res, url)) return true
     if (url.pathname !== '/favicon.ico' || !file('favicon.svg')) return false
     send(res, 301, '', { location: withBase('/favicon.svg'), 'cache-control': 'public, max-age=86400' })
     return true
   }
 
-  function serveStatic(req, res, url) {
+  async function serveStatic(req, res, url) {
     const p = publicStaticPath(url.pathname)
     if (p === null) return false
-    const candidates = p.endsWith('/') ? [p + 'index.html', ...(p.length > 1 ? [p.slice(0, -1) + '.html'] : [])] : [p, p + '.html', p + '/index.html']
+    const candidates = p.endsWith('/') ? [p + 'index.html', p + 'index.brain', ...(p.length > 1 ? [p.slice(0, -1) + '.html', p.slice(0, -1) + '.brain'] : [])] : [p, p + '.html', p + '/index.html', p + '.brain', p + '/index.brain']
     for (const c of candidates) {
       const f = file(c)
       if (!f) continue
       const ext = extname(f), type = FEEDS[basename(f)] || MIME[ext] || 'application/octet-stream'
-      if (ext === '.html') {
+      if (ext === '.html' || ext === '.brain') {
         // §33: the page's Markdown twin (`/pricing` → pricing.md) when the client prefers text/markdown
         if (serveTwin(req, res, url)) return true
         const md = file(mdPath(p))
@@ -1886,34 +1975,39 @@ export function createServer(o = {}) {
         ...(ext === '.md' ? twinCanonical(p) : {}),
         'content-type': type,
         // the worker script must be revalidated on every check, or a CDN could keep an old worker for an hour (§35.7)
-        'cache-control': p.startsWith('/_b/') ? 'public, max-age=31536000, immutable' : p === '/sw.js' ? 'no-cache' : 'public, max-age=3600',
+        'cache-control': p.startsWith('/_b/') ? 'public, max-age=31536000, immutable' : p === '/sw.js' || /\.(m3u8?|mpd)$/i.test(p) ? 'no-cache' : 'public, max-age=3600',
         vary: 'accept-encoding',
       }
-      // Range: media players ask for byte spans (Safari plays no video without them). The span is of the plain file, so
-      // a ranged request skips the precompressed siblings; If-Range has no validator to match here, so it gets it all.
-      const span = req.headers.range && !req.headers['if-range'] ? byteRange(req.headers.range, statSync(f).size) : null
-      if (span === false) return send(res, 416, '', { 'content-range': `bytes */${statSync(f).size}` }), true
-      if (span) {
-        const len = span.end - span.start + 1, buf = Buffer.alloc(req.method === 'HEAD' ? 0 : len)
-        if (buf.length) {
-          const fd = openSync(f, 'r')
-          try { readSync(fd, buf, 0, len, span.start) } finally { closeSync(fd) }
-        }
-        send(res, 206, buf, { ...headers, 'accept-ranges': 'bytes', 'content-range': `bytes ${span.start}-${span.end}/${statSync(f).size}`, 'content-length': String(len) })
-        return true
-      }
       // the smallest precompressed sibling the client accepts (the build keeps only those smaller than the file)
       let best = null
-      for (const enc of acceptedEncodings(req.headers['accept-encoding'])) {
+      for (const enc of req.headers.range ? [] : acceptedEncodings(req.headers['accept-encoding'])) {
         const encoded = file(c + (enc === 'br' ? '.br' : enc === 'zstd' ? '.zst' : '.gz'))
         const size = encoded ? statSync(encoded).size : Infinity
         if (encoded && (!best || size < best.size)) best = { enc, encoded, size }
       }
-      if (best) {
-        send(res, 200, req.method === 'HEAD' ? '' : readFileSync(best.encoded), { ...headers, 'content-encoding': best.enc })
-        return true
+      const selected = best ? best.encoded : f
+      const handle = await open(selected, FS.O_RDONLY | (FS.O_NOFOLLOW || 0) | (FS.O_NONBLOCK || 0))
+      try {
+        const stat = await handle.stat()
+        if (!stat.isFile()) throw new Error('Static output must be a regular file')
+        headers.etag = await fileTag(handle, stat)
+        if (res.destroyed) return true
+        if (!best) headers['accept-ranges'] = 'bytes'
+        const inm = req.headers['if-none-match']
+        if (inm && inm.split(',').some(t => t.trim() === '*' || t.trim().replace(/^W\//, '') === headers.etag)) return send(res, 304, '', headers), true
+        const span = req.headers.range && (!req.headers['if-range'] || req.headers['if-range'] === headers.etag) ? byteRange(req.headers.range, stat.size) : null
+        if (span === false) return send(res, 416, '', { ...headers, 'content-range': `bytes */${stat.size}` }), true
+        if (span) {
+          headers['content-range'] = `bytes ${span.start}-${span.end}/${stat.size}`
+          headers['content-length'] = String(span.end - span.start + 1)
+        } else {
+          headers['content-length'] = String(stat.size)
+          if (best) headers['content-encoding'] = best.enc
+        }
+        await streamFile(req, res, handle, span ? 206 : 200, headers, span)
+      } finally {
+        await handle.close()
       }
-      send(res, 200, req.method === 'HEAD' ? '' : readFileSync(f), { ...headers, 'accept-ranges': 'bytes' })
       return true
     }
     return false
@@ -2049,7 +2143,7 @@ export function createServer(o = {}) {
       const post = req.method === 'POST'
       if (!post && req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'Method not allowed', { allow: 'GET, HEAD, POST' })
       // a status page opened directly answers its own status: `/403` is never a 200 that a crawler or a probe can trust
-      const reserved = post ? 0 : reservedStatus(url.pathname)
+      const reserved = post ? 0 : reservedStatus(publicStaticPath(url.pathname) ?? url.pathname)
       if (reserved === 403) return forbidden(req, res, url, rid, '')
       if (reserved) {
         // Anyone can open it, so the note about it is bounded and is not an error.
@@ -2062,11 +2156,12 @@ export function createServer(o = {}) {
       for (const route of routes) {
         const m = route.rx.exec(url.pathname)
         if (!m) continue
+        const protectedRoute = route.guards?.length || route.middleware?.length
         // a form page without load is prerendered: GET serves that file (build ETag); only its POST needs the server
-        if (!post && route.forms && serveStatic(req, res, url)) return
+        if (!post && !protectedRoute && route.forms && (await serveStatic(req, res, url))) return
         // a parameter never hides a real file: `/[code]` must not swallow /favicon.svg, /sitemap.xml or a prerendered /login
-        if (!post && m.groups && (await serveFixed(req, res, url))) return
-        if (!post && serveTwin(req, res, url)) return
+        if (!post && !protectedRoute && m.groups && (await serveFixed(req, res, url))) return
+        if (!post && !protectedRoute && serveTwin(req, res, url)) return
         const paged = post ? null : pageParameter(route, url)
         if (paged === 404) return notFound(req, res)
         if (paged) return send(res, 301, '', { location: withBase(paged), 'cache-control': 'public, max-age=3600' })
@@ -2080,7 +2175,7 @@ export function createServer(o = {}) {
     } catch (e) {
       const busy = e instanceof HttpError && e.code === 'BRIDGE_BUSY'
       if (busy) log('warn', 'backend bridge busy', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], fix: e.fix })
-      else if (e instanceof HttpError && OWN_CAUSES.has(e.message)) log('warn', 'backend unavailable', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], status: e.status, cause: e.message, ...(CODE_SHAPE.test(e.transport || '') ? { transport: e.transport } : {}) })
+      else if (e instanceof HttpError && e.status >= 500 && BACKEND_UNAVAILABLE_CAUSES.has(e.message)) log('warn', 'backend unavailable', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], status: e.status, cause: e.message, ...(CODE_SHAPE.test(e.transport || '') ? { transport: e.transport } : {}) })
       else log('error', 'unhandled', { rid, path: req.url, ...trace(e) })
       try {
         if (busy && !res.headersSent) { res.setHeader('retry-after', String(e.retryAfter)); failPage(res, 503, rid, { code: e.code, message: 'Service Unavailable', fix: e.fix }) }
@@ -2674,10 +2769,23 @@ export function prefersMarkdown(accept) {
   if (html < 0) (html = any), (htmlAt = Infinity) // an explicit type beats a wildcard of the same weight
   return md > 0 && (md > html || (md === html && mdAt < htmlAt))
 }
+// Root-relative image metadata follows the app base; bare references follow the canonical document URL.
+export function metadataImage(root, canonical, value) {
+  const encode = s => encodeURI(s.toWellFormed()).replaceAll('%25', '%')
+  value = value.trim()
+  if (!value) return ''
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) || !root) return encode(value)
+  try {
+    const home = new URL(root.endsWith('/') ? root : root + '/')
+    const prefix = home.pathname.replace(/\/$/, '')
+    if (/^\/(?!\/)/.test(value)) value = new URL(value === prefix || value.startsWith(prefix + '/') ? value : prefix + value, home.origin).href
+    return new URL(value, canonical || home).href
+  } catch { return encode(value) }
+}
 // SEO head from View.seo(props): title, description, canonical, og:*/twitter:*, JSON-LD and the view's <head> block
 // F5: the build writes an SSR route's canonical/og:url from its pattern (/posts/:slug); the request has the real path.
 // A view's own <head> tags replace the generated ones with the same name/property (one tag per key, SPEC «SEO»).
-function head(page, seo, path, search = '') {
+function head(page, seo, path, search = '', route, base = '') {
   let h = page
   // `<meta seo query="page">`: these parameters make a different page; any other (a dialog, a tracking tag) does not
   let identity = '', query = ''
@@ -2689,11 +2797,13 @@ function head(page, seo, path, search = '') {
   })
   if (path) {
     // the attribute is already escaped HTML: only the request path that replaces a pattern is escaped
-    const real = v => v.replace(/^(https?:\/\/[^/]+)?(\/[^"]*)$/, (m, o = '', p) => (/\/[:*]/.test(p) ? o + esc(path) : m)) + identity
+    const real = v => v.replace(/^(https?:\/\/[^/]+)?(\/[^"]*)$/, (m, o = '', p) => (/\/[:*]/.test(p) ? o + esc(base + path) : m)) + identity
     h = h.replace(/(<link[^>]*rel=["']canonical["'][^>]*href=")([^"]*)(")/i, (m, a, v, b) => a + real(v) + b)
     h = h.replace(/(<meta[^>]*property=["']og:url["'][^>]*content=")([^"]*)(")/i, (m, a, v, b) => a + real(v) + b)
   }
-  if (!seo) return graph(h, path, query)
+  if (!seo) return graph(h, path ? base + path : path, query)
+  // Match prerendering: blank optional fields are absent; zero and false remain distinct values.
+  seo = Object.fromEntries(Object.entries(seo).filter(([, v]) => v != null && !(typeof v === 'string' && !v.trim())))
   const meta = (attr, key, val, escaped) => {
     const tag = `<meta ${attr}="${esc(key)}" content="${escaped ? val.replace(/"/g, '&quot;') : esc(val)}">`
     const rx = new RegExp(`<meta[^>]*\\b${attr}=["']${key.replace(/[.*+?^${}()|[\]\\:]/g, '\\$&')}["'][^>]*>`, 'i')
@@ -2706,20 +2816,27 @@ function head(page, seo, path, search = '') {
     else if (k === 'canonical') {
       // a root-relative canonical takes the origin the build wrote into the template (PUBLIC_SITE_URL), as it does on
       // a prerendered page: a relative canonical is ignored by search engines
-      const built = /^\/(?!\/)/.test(v) && /<link[^>]*rel=["']canonical["'][^>]*href="(https?:\/\/[^/"]+)/i.exec(h)?.[1]
-      const url = built ? built + v : v
+      const relative = base && (v + '/').startsWith(base + '/') ? v.slice(base.length) || '/' : v
+      const translated = linkTo(route, relative)
+      const local = /^\/(?!\/)/.test(translated) ? base + translated : translated
+      const built = /^\/(?!\/)/.test(local) && /<link[^>]*rel=["']canonical["'][^>]*href="(https?:\/\/[^/"]+)/i.exec(h)?.[1]
+      const url = built ? built + local : local
       const tag = `<link rel="canonical" href="${esc(url)}">`
       h = /<link[^>]*rel=["']canonical["'][^>]*>/i.test(h) ? h.replace(/<link[^>]*rel=["']canonical["'][^>]*>/i, () => tag) : h.replace('</head>', () => tag + '</head>')
       if (seo['og:url'] == null) meta('property', 'og:url', url) // og:url follows the canonical unless the view sets its own
     } else if (k === 'jsonld') h = h.replace('</head>', () => `<script type="application/ld+json">${jsonInHtml(v)}</script></head>`)
-    else if (/^(og|twitter|article):/.test(k)) meta('property', k, v)
+    else if (/^(og|twitter|article):/.test(k)) meta(k.startsWith('twitter:') ? 'name' : 'property', k, v)
     else if (typeof v === 'string') meta('name', k, v)
   }
   // What the build writes for a prerendered page and can only be known here: the social card of this request's values
   // (brain-seo social::head, prerender seo_head). The view's own value always wins.
   const shared = /<title>([\s\S]*?)<\/title>/i.exec(h)?.[1]
   const origin = /<link[^>]*rel=["']canonical["'][^>]*href="(https?:\/\/[^/"]+)/i.exec(h)?.[1]
-  if (typeof seo['og:image'] === 'string' && origin && /^\/(?!\/)/.test(seo['og:image'])) meta('property', 'og:image', encodeURI(origin + seo['og:image']))
+  const canonical = /<link[^>]*rel=["']canonical["'][^>]*href="([^"]+)"/i.exec(h)?.[1].replaceAll('&amp;', '&')
+  for (const key of ['og:image', 'og:image:url', 'og:image:secure_url', 'twitter:image', 'twitter:image:src']) if (typeof seo[key] === 'string') {
+    seo[key] = metadataImage(origin ? origin + base : null, canonical, seo[key])
+    meta(key.startsWith('twitter:') ? 'name' : 'property', key, seo[key])
+  }
   if (seo.title != null && seo['og:title'] == null) meta('property', 'og:title', shared, true)
   if (seo.description != null && seo['og:description'] == null) meta('property', 'og:description', seo.description)
   if (seo['og:image'] != null) {
@@ -2735,19 +2852,21 @@ function head(page, seo, path, search = '') {
     if (seo.title != null) node[/^(Article|BlogPosting|NewsArticle|TechArticle|Report)$/.test(T) ? 'headline' : 'name'] = String(seo.title).slice(0, 110)
     if (seo.description != null) node.description = String(seo.description)
     if (canon) node.url = canon[1].replace(/&amp;/g, '&')
-    if (seo['og:image'] != null) node.image = String(seo['og:image']).replace(/^\/(?!\/)/, () => (canon && /^https?:\/\/[^/]+/.exec(node.url) || [''])[0] + '/')
+    if (seo['og:image'] != null) node.image = seo['og:image']
     if (seo.lastmod != null) node.dateModified = String(seo.lastmod)
     const own = new RegExp(`<script[^>]*type=["']application/ld\\+json["'][^>]*>\\s*\\{"@context":"https://schema\\.org","@type":"${T}"[\\s\\S]*?</script>`, 'i')
     const tag = `<script type="application/ld+json">${jsonInHtml(node)}</script>`
     h = own.test(h) ? h.replace(own, () => tag) : h.replace('</head>', () => tag + '</head>')
   }
   if (seo.$head) {
-    for (const [, attr, key] of seo.$head.matchAll(/<meta[^>]*\b(property|name)=["']([^"']+)["'][^>]*>/gi))
-      h = h.replace(new RegExp(`<meta[^>]*\\b${attr}=["']${key.replace(/[.*+?^${}()|[\]\\:]/g, '\\$&')}["'][^>]*>`, 'gi'), '')
+    for (const [, attr, key] of seo.$head.matchAll(/<meta[^>]*\b(property|name)=["']([^"']+)["'][^>]*>/gi)) {
+      const attributes = key.startsWith('twitter:') ? '(?:property|name)' : attr
+      h = h.replace(new RegExp(`<meta[^>]*\\b${attributes}=["']${key.replace(/[.*+?^${}()|[\]\\:]/g, '\\$&')}["'][^>]*>`, 'gi'), '')
+    }
     if (/<link[^>]*rel=["']canonical["']/i.test(seo.$head)) h = h.replace(/<link[^>]*rel=["']canonical["'][^>]*>/gi, '')
     h = h.replace('</head>', () => seo.$head + '</head>')
   }
-  return graph(h, path, query, seo)
+  return graph(h, path ? base + path : path, query, seo)
 }
 // The WebSite + WebPage graph the build wrote into the template (brain-seo ServerHead::apply): its pattern URLs become
 // this request's, like the canonical, and the WebPage takes this request's title and description.
@@ -2763,27 +2882,32 @@ function graph(h, path, query, seo) {
       if ([node['@type']].flat().includes('WebPage')) {
         if (title && node.name == null) node.name = title.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
         if (seo?.description != null && node.description == null) node.description = String(seo.description)
+        if (typeof seo?.['og:image'] === 'string' && seo.jsonld == null) {
+          const image = node.primaryImageOfPage
+          if (!image || (image['@type'] === 'ImageObject' && !image['@id'])) node.primaryImageOfPage = { '@type': 'ImageObject', ...image, url: seo['og:image'] }
+        }
       }
     }
     return a + jsonInHtml(g) + b
   })
 }
-// `/_b/<hash>.js` imports inside the chunks resolve to files in dist/ (same hook as the build's prerender)
+// Only compiler-owned chunks receive the own-extension module format; ordinary Node imports keep their loader.
+function resolveChunk(s, c, next, base, app) {
+  if (app !== '/' && s.startsWith(app + '_b/')) s = s.slice(app.length - 1)
+  const mapped = s.startsWith('/_b/')
+  const url = mapped ? new URL('.' + s, base) : s.startsWith('file:') ? new URL(s) : s.startsWith('.') && c.parentURL?.startsWith('file:') ? new URL(s, c.parentURL) : null
+  const owned = new URL('_b/', base).href
+  if (url?.href.startsWith(owned) && url.pathname.endsWith('.jsbrain')) return { url: url.href, format: 'module', shortCircuit: true }
+  if (mapped) return { url: url.href, shortCircuit: true }
+  return next(s, c)
+}
 let hooked = false
 function hook(base, app = '/') {
   if (hooked) return
   hooked = true
-  // chunks import '/_b/x.js', or '/app/_b/x.js' under a base path: both are dist/_b/x.js
-  const own = s => {
-    if (app !== '/' && s.startsWith(app + '_b/')) s = s.slice(app.length - 1)
-    return s.startsWith('/_b/') && { url: new URL('.' + s, base).href, shortCircuit: true }
-  }
-  // registerHooks (Node 22.15+, in-thread) replaces the deprecated register (DEP0205)
-  if (Module.registerHooks) return void Module.registerHooks({ resolve: (s, c, next) => own(s) || next(s, c) })
-  Module.register(
-    'data:text/javascript,' +
-      encodeURIComponent(`export async function resolve(s, c, n) { const a = ${json(app)}; if (a !== '/' && s.startsWith(a + '_b/')) s = s.slice(a.length - 1); return s.startsWith('/_b/') ? { url: new URL('.' + s, ${json(base)}).href, shortCircuit: true } : n(s, c) }`)
-  )
+  // registerHooks (Node 22.15+, in-thread) and the compatibility loader share exactly the same resolver.
+  if (Module.registerHooks) return void Module.registerHooks({ resolve: (s, c, next) => resolveChunk(s, c, next, base, app) })
+  Module.register('data:text/javascript,' + encodeURIComponent(`${resolveChunk.toString()};export async function resolve(s,c,n){return resolveChunk(s,c,n,${json(base)},${json(app)})}`))
 }
 
 const LISTEN_WAIT_MS = 10000

package/shim/dom.js

@@ -6,28 +6,19 @@ const VOID = new Set(['area', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link'
 const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 const unesc = s => s.replace(/&(amp|lt|gt|quot|#39);/g, (_, e) => ({ amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'" })[e])
 
-export class Event {
+// Keep Node's native event brand: SSR and its test DOM share a process with fetch/WebSocket EventTargets.
+const NativeEvent = globalThis.Event
+export class Event extends NativeEvent {
   constructor(type, init = {}) {
-    this.type = type
-    this.bubbles = !!init.bubbles
-    this.cancelable = !!init.cancelable
-    this.target = null
-    this.currentTarget = null
-    this.cancelBubble = false
-    this.defaultPrevented = false
+    super(type, init)
     this._p = []
   }
   composedPath() {
-    return this._p
+    return this._p.length ? this._p : super.composedPath()
   }
   stopImmediatePropagation() {
-    this.cancelBubble = this._stop = true
-  }
-  stopPropagation() {
-    this.cancelBubble = true
-  }
-  preventDefault() {
-    this.defaultPrevented = true
+    this._stop = true
+    super.stopImmediatePropagation()
   }
 }
 export class MouseEvent extends Event {}
@@ -162,7 +153,7 @@ class Node {
     if (i >= 0) a.splice(i, 1)
   }
   dispatchEvent(e) {
-    e.target = this
+    Object.defineProperty(e, 'target', { configurable: true, writable: true, value: this })
     const path = []
     for (let n = this; n; n = n.parentNode || n.host) path.push(n)
     if (path[path.length - 1].nodeType === 9 && path[path.length - 1].defaultView) path.push(path[path.length - 1].defaultView)

package/sw/brain-sw.js

@@ -14,9 +14,16 @@
 // cache that survives builds, bounded by entries and age; personal responses are never stored. `cache.update:
 // "prompt"` keeps a new worker waiting (while an older one controls tabs) until a page posts `brain:skip-waiting`.
 const B = self.BRAIN_BUILD || { hash: 'dev', precache: [], offline: null }
+const IMMUTABLE = Array.isArray(B.immutable) ? new Set(B.immutable) : null
+const isHashed = path => IMMUTABLE ? IMMUTABLE.has(path) : path.startsWith(BASE + '_b/')
 const BASE = B.base || '/' // app served under a base path (§23 #148); precache/offline URLs already carry it
 const NS = 'brain' + BASE.replace(/\/$/, '') // `brain` at the root, `brain/app` under /app/
 const BUILD = NS + '-' + B.hash, META = NS + ':meta'
+let priorImmutable
+const previousAssets = () => priorImmutable ||= caches.open(META).then(cache => cache.match('/__brain_immutable')).then(async response => {
+  const manifests = response ? await response.json() : {}
+  return new Set(Object.values(manifests).filter(Array.isArray).flat().filter(path => typeof path === 'string'))
+}).catch(() => new Set())
 const NAV_TIMEOUT = 3000
 // precache downloads at once: hundreds in one burst tripped per-IP proxy rate limits (429) and competed with the page
 const PRECACHE_PARALLEL = 4
@@ -40,7 +47,7 @@ self.addEventListener('install', e => {
       // update downloads only what changed
       const olds = (await caches.keys()).filter(k => k.startsWith(NS + '-') && k !== BUILD)
       const kept = async u => {
-        if (!u.startsWith(BASE + '_b/')) return null
+        if (!isHashed(u)) return null
         for (const k of olds) {
           const r = await (await caches.open(k)).match(u)
           if (r) return r
@@ -74,6 +81,24 @@ self.addEventListener('activate', e => {
       const gens = r ? await r.json() : []
       const keep = [...gens.filter(g => g !== BUILD).slice(-1), BUILD]
       await meta.put('/__brain_generations', new Response(JSON.stringify(keep)))
+      // Keep exact custom asset identities for the same two generations as their bytes, including old open tabs.
+      const stored = await meta.match('/__brain_immutable')
+      if (IMMUTABLE || stored) {
+        const decoded = stored ? await stored.json().catch(() => ({})) : {}
+        const old = decoded && typeof decoded === 'object' ? decoded : {}
+        const manifests = {}
+        for (const generation of keep) {
+          if (generation === BUILD) manifests[generation] = [...(IMMUTABLE || [])]
+          else if (Array.isArray(old[generation])) manifests[generation] = old[generation]
+          else if (generation.startsWith(NS + '-')) {
+            // A pre-inventory worker treated only its historical namespace as immutable; infer no other cached URL.
+            const entries = await (await caches.open(generation)).keys()
+            manifests[generation] = entries.map(entry => new URL(entry.url, self.location.origin)).filter(url => url.origin === self.location.origin && url.pathname.startsWith(BASE + '_b/')).map(url => url.pathname)
+          }
+        }
+        await meta.put('/__brain_immutable', new Response(JSON.stringify(manifests)))
+        priorImmutable = Promise.resolve(new Set(Object.values(manifests).flat()))
+      }
       for (const k of await caches.keys())
         if ((k.startsWith(NS + '-') && !keep.includes(k)) || (k.startsWith(NS + ':route:') && !ROUTES.some(r => r.cache === k))) await caches.delete(k)
       await self.clients.claim()
@@ -91,10 +116,18 @@ self.addEventListener('fetch', e => {
   if (req.method !== 'GET') return
   const url = new URL(req.url)
   if (url.origin !== self.location.origin || url.pathname.startsWith(BASE + '_r/') || url.pathname === BASE + 'sw.js') return
+  // A cached whole response cannot satisfy a byte range; live manifests must never lag one revalidation behind.
+  if (req.headers?.has?.('range') || /\.(m3u8?|mpd)$/i.test(url.pathname)) return
   // offline: false (B.offline null) → navigations go straight to the network: no page cache, no offline page
   if (req.mode === 'navigate') return B.offline ? e.respondWith(navigate(e)) : undefined
-  if (url.pathname.startsWith(BASE + '_b/')) return e.respondWith(hashed(e))
+  if (isHashed(url.pathname)) return e.respondWith(hashed(e))
   const rt = route(url.pathname)
+  // A custom layout can change between builds; only exact retained inventory entries use old immutable bytes.
+  if (IMMUTABLE) return e.respondWith((async () => {
+    if ((await previousAssets()).has(url.pathname)) return hashed(e)
+    if (rt) return rt.strategy === 'network-only' ? fetch(req) : data(e, rt)
+    return req.destination ? revalidate(e) : fetch(req)
+  })())
   if (rt) return e.respondWith(rt.strategy === 'network-only' ? fetch(req) : data(e, rt))
   // only files the page itself loads (img, style, script, font, manifest…); fetch()/XHR data is never touched (§35:
   // data is not cached by default)

package/ui/dialog.brain

@@ -1,10 +1,10 @@
-<meta props="title:str closeLabel:str='Close' urlKey:str=''" emits="close" expose="open close">
+<meta props="title:str closeLabel:str='Close' urlKey:str='' dismissible:bool=false" emits="close" expose="open close">
 <script>
   let dlg = ref()
   // native modal <dialog>: focus moves inside, the rest of the page is inert, Escape closes
   const open = () => { if (!dlg.open) dlg.showModal() }
   const close = () => { if (dlg.open) dlg.close() }
-  fx(() => { if (dlg) return urlDialog(dlg, urlKey) })
+  fx(() => { if (dlg) return urlDialog(dlg, urlKey, { dismissible }) })
 </script>
 <dialog bind:ref={dlg} aria-labelledby="dlg-title" on:close={emit('close')}>
   <header>