brustjs 0.1.63-alpha → 0.1.65-alpha

package/runtime/native/runtime.ts

@@ -12,22 +12,25 @@ export type Instance = Record<string, unknown>
  *                    for side-effects on signal change (sync localStorage, the DOM
  *                    outside the component, timers). Returns the disposer too.
  *  - `onCleanup(fn)` — register a one-shot teardown for unmount (e.g. removeEventListener). */
-export interface BehaviorCtx {
-  el: HTMLElement
+export interface BehaviorCtx<Host extends Element = HTMLElement> {
+  el: Host
   props: unknown
   // biome-ignore lint/suspicious/noConfusingVoidType: React useEffect return shape (`void | Destructor`) — see store `effect`.
   effect: (fn: () => void | (() => void)) => () => void
   onCleanup: (fn: () => void) => void
 }
-export type Behavior = (ctx: BehaviorCtx) => Instance
+export type Behavior<Host extends Element = HTMLElement> = (ctx: BehaviorCtx<Host>) => Instance
 
 interface Mounted {
   disposers: Array<() => void>
 }
 
-const registry = new Map<string, Behavior>()
-const mounted = new WeakMap<HTMLElement, Mounted>()
+type RegisteredBehavior = Behavior<Element>
+
+const registry = new Map<string, RegisteredBehavior>()
+const mounted = new WeakMap<Element, Mounted>()
 const loading = new Map<string, Promise<unknown>>()
+const pending = new Map<string, Set<Element>>()
 let started = false
 
 /** Per-component behavior chunk URL. Each native interactive component is built to
@@ -39,8 +42,15 @@ const CHUNK_BASE = '/_brust/islands/'
 /** Register a component behavior under `name`. Called by `<name>.directive.js` chunks
  * via the global handle below (they do NOT import this module — keeps each chunk to
  * just its behavior, with the runtime shared as the single `_directives.js` copy). */
-export function register(name: string, behavior: Behavior): void {
-  registry.set(name, behavior)
+export function register<Host extends Element = HTMLElement>(
+  name: string,
+  behavior: Behavior<Host>,
+): void {
+  registry.set(name, behavior as unknown as RegisteredBehavior)
+  const hosts = pending.get(name)
+  if (!hosts) return
+  pending.delete(name)
+  for (const el of hosts) mountElement(el)
 }
 // Expose `register` on a global so dynamically-imported behavior chunks self-register
 // into THIS runtime's registry without importing/duplicating the runtime. Symbol.for
@@ -72,8 +82,8 @@ export function start(root?: ParentNode): void {
 }
 
 function scanAndMount(scope: ParentNode): void {
-  if (scope instanceof HTMLElement && scope.hasAttribute('x-data')) mountElement(scope)
-  for (const el of Array.from(scope.querySelectorAll<HTMLElement>('[x-data]'))) {
+  if (scope instanceof Element && scope.hasAttribute('x-data')) mountElement(scope)
+  for (const el of Array.from(scope.querySelectorAll<Element>('[x-data]'))) {
     mountElement(el)
   }
   // R10 — OPEN shadow roots host their own component trees: scan each the same
@@ -81,8 +91,8 @@ function scanAndMount(scope: ParentNode): void {
   // per root, since neither the body observer nor an outer root's observer sees
   // mutations inside an inner shadow tree. Closed roots expose `shadowRoot ===
   // null` and are unreachable by design. The walk-all is per added subtree only.
-  if (scope instanceof HTMLElement && scope.shadowRoot) scanShadowRoot(scope.shadowRoot)
-  for (const el of Array.from(scope.querySelectorAll<HTMLElement>('*'))) {
+  if (scope instanceof Element && scope.shadowRoot) scanShadowRoot(scope.shadowRoot)
+  for (const el of Array.from(scope.querySelectorAll<Element>('*'))) {
     if (el.shadowRoot) scanShadowRoot(el.shadowRoot)
   }
 }
@@ -92,7 +102,7 @@ function scanShadowRoot(root: ShadowRoot): void {
   observeRoot(root)
 }
 
-function mountElement(el: HTMLElement): void {
+function mountElement(el: Element): void {
   if (mounted.has(el)) return
   // Removed mid-scan (e.g. an initial-falsy x-if subtree pruned while scanAndMount's
   // snapshot loop was still iterating): mounting a detached element would leak its
@@ -101,6 +111,12 @@ function mountElement(el: HTMLElement): void {
   const name = el.getAttribute('x-data') ?? ''
   const behavior = registry.get(name)
   if (!behavior) {
+    let hosts = pending.get(name)
+    if (!hosts) {
+      hosts = new Set()
+      pending.set(name, hosts)
+    }
+    hosts.add(el)
     // Behavior chunk not loaded yet → fetch it on demand, then mount this name.
     loadBehavior(name)
     return
@@ -124,12 +140,12 @@ function mountElement(el: HTMLElement): void {
   mounted.set(el, m)
   // ctxEffect/onCleanup typed via BehaviorCtx so the `void | Destructor` shape is
   // declared in one place (the interface) — no inline void-union to suppress here.
-  const ctxEffect: BehaviorCtx['effect'] = (fn) => {
+  const ctxEffect: BehaviorCtx<Element>['effect'] = (fn) => {
     const dispose = effect(fn)
     m.disposers.push(dispose)
     return dispose
   }
-  const onCleanup: BehaviorCtx['onCleanup'] = (fn) => {
+  const onCleanup: BehaviorCtx<Element>['onCleanup'] = (fn) => {
     m.disposers.push(fn)
   }
   const instance = behavior({ el, props, effect: ctxEffect, onCleanup })
@@ -150,6 +166,7 @@ function mountElement(el: HTMLElement): void {
 function loadBehavior(name: string): void {
   if (registry.has(name) || loading.has(name)) return
   if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+    pending.delete(name)
     console.warn(`[brust] unsafe x-data component name "${name}" — not loaded`)
     return
   }
@@ -159,17 +176,16 @@ function loadBehavior(name: string): void {
     .then(() => import(/* @vite-ignore */ `${CHUNK_BASE}${name}.directive.js`))
     .then(() => {
       if (!registry.has(name)) {
+        loading.delete(name)
+        pending.delete(name)
         console.warn(`[brust] "${name}.directive.js" loaded but did not register "${name}"`)
-        return
-      }
-      // Mount every element waiting on this name (initial + swapped-in).
-      if (typeof document !== 'undefined') {
-        for (const el of Array.from(document.querySelectorAll<HTMLElement>(`[x-data="${name}"]`))) {
-          mountElement(el)
-        }
       }
     })
-    .catch((e) => console.error(`[brust] failed to load directive component "${name}":`, e))
+    .catch((e) => {
+      loading.delete(name)
+      pending.delete(name)
+      console.error(`[brust] failed to load directive component "${name}":`, e)
+    })
   loading.set(name, p)
 }
 
@@ -180,7 +196,7 @@ function loadBehavior(name: string): void {
 // independently via scanAndMount's shadow-root scan (R10), never inheriting the
 // enclosing instance's scope. (The `el.children` walk below naturally excludes
 // shadow content; this is by design, not an accident.)
-function bindTree(el: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+function bindTree(el: Element, instance: Instance, disposers: Array<() => void>): void {
   // Coexistence check MUST precede the x-for early-exit, else x-for preempts and the
   // warn never fires. Strip x-if so x-for's template clones don't carry it either.
   if (el.hasAttribute('x-if') && el.hasAttribute('x-for')) {
@@ -197,7 +213,7 @@ function bindTree(el: HTMLElement, instance: Instance, disposers: Array<() => vo
   }
   bindAttrs(el, instance, disposers)
   for (const child of Array.from(el.children)) {
-    if (!(child instanceof HTMLElement)) continue
+    if (!(child instanceof Element)) continue
     if (child.hasAttribute('x-data')) continue
     bindTree(child, instance, disposers)
   }
@@ -243,7 +259,7 @@ export function parseFor(raw: string): ForExpr | null {
 }
 
 interface ForEntry {
-  node: HTMLElement
+  node: Element
   itemSig: Signal<unknown>
   idxSig?: Signal<number>
   disposers: Array<() => void>
@@ -259,7 +275,7 @@ const forMountGuard = new WeakMap<Node, Set<string>>()
 // (legacy v1, now with optional plain index). With `by <keypath>...` it is an opt-in
 // keyed reconcile that reuses DOM nodes (focus/scroll survive) and is reactive
 // per-item via a per-clone `signal(item)` resolved through `read`'s unwrap-each-hop.
-function bindFor(tplEl: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+function bindFor(tplEl: Element, instance: Instance, disposers: Array<() => void>): void {
   const expr = parseFor(tplEl.getAttribute('x-for') ?? '')
   if (!expr) {
     console.warn(`[brust] malformed x-for expression: "${tplEl.getAttribute('x-for')}"`)
@@ -292,12 +308,12 @@ function bindFor(tplEl: HTMLElement, instance: Instance, disposers: Array<() =>
   const anchor = tplEl.ownerDocument.createComment(`x-for:${itemName}`)
   parent.insertBefore(anchor, tplEl)
   tplEl.removeAttribute('x-for')
-  const template = tplEl.cloneNode(true) as HTMLElement
+  const template = tplEl.cloneNode(true) as Element
   tplEl.remove()
 
   // ---- legacy (no `by`) — full re-render, with optional plain index ----
   if (!keyPaths) {
-    const rendered: HTMLElement[] = []
+    const rendered: Element[] = []
     const childDisposers: Array<() => void> = []
     const clear = () => {
       for (const d of childDisposers.splice(0)) {
@@ -315,7 +331,7 @@ function bindFor(tplEl: HTMLElement, instance: Instance, disposers: Array<() =>
         const list = read(instance, listPath)
         if (!Array.isArray(list)) return
         for (let i = 0; i < list.length; i++) {
-          const clone = template.cloneNode(true) as HTMLElement
+          const clone = template.cloneNode(true) as Element
           const childScope: Instance = Object.create(instance)
           childScope[itemName] = list[i]
           if (indexName) childScope[indexName] = i
@@ -340,7 +356,7 @@ function installKeyedReconcile(
   instance: Instance,
   parent: Node,
   expr: ForExpr,
-  template: HTMLElement,
+  template: Element,
   anchor: Comment,
   initialMap: Map<string, ForEntry>,
   disposers: Array<() => void>,
@@ -382,7 +398,7 @@ function installKeyedReconcile(
           live.delete(key)
           next.set(key, existing)
         } else {
-          const clone = template.cloneNode(true) as HTMLElement
+          const clone = template.cloneNode(true) as Element
           const itemSig = signal(item)
           const idxSig = indexName ? signal(i) : undefined
           const childScope: Instance = Object.create(instance)
@@ -409,11 +425,11 @@ function installKeyedReconcile(
  *  `data-x-key-0`). Only direct children — the key attr lives on the for-item
  *  root, never a descendant. The x-for match prevents a sibling x-for list under
  *  the same parent from having its seeds consumed by this one. */
-function collectSeeds(parent: Node, keyPaths: string[], xforRaw: string): HTMLElement[] {
+function collectSeeds(parent: Node, keyPaths: string[], xforRaw: string): Element[] {
   const sel = keyPaths.length > 1 ? '[data-x-key-0]' : '[data-x-key]'
-  const out: HTMLElement[] = []
+  const out: Element[] = []
   for (const c of Array.from((parent as Element).children ?? [])) {
-    if (c instanceof HTMLElement && c.matches(sel) && c.getAttribute('x-for') === xforRaw) {
+    if (c instanceof Element && c.matches(sel) && c.getAttribute('x-for') === xforRaw) {
       out.push(c)
     }
   }
@@ -422,14 +438,14 @@ function collectSeeds(parent: Node, keyPaths: string[], xforRaw: string): HTMLEl
 
 /** The seed's key from markup — must match the reconcile's computed key (single
  *  `data-x-key`, OR `data-x-key-*` joined with `\x00` IN JS — NUL never in HTML). */
-function seedKey(node: HTMLElement, keyPaths: string[]): string {
+function seedKey(node: Element, keyPaths: string[]): string {
   if (keyPaths.length > 1) {
     return keyPaths.map((_, i) => node.getAttribute(`data-x-key-${i}`) ?? '').join('\x00')
   }
   return node.getAttribute('data-x-key') ?? ''
 }
 
-function stripKeyAttrs(el: HTMLElement, keyPaths: string[]): void {
+function stripKeyAttrs(el: Element, keyPaths: string[]): void {
   if (keyPaths.length > 1) {
     for (let i = 0; i < keyPaths.length; i++) el.removeAttribute(`data-x-key-${i}`)
   } else {
@@ -440,10 +456,10 @@ function stripKeyAttrs(el: HTMLElement, keyPaths: string[]): void {
 /** Bind an adopted seed node as a plain subtree. The node KEEPS its x-for attr so
  *  the parent bindTree loop's later re-visit routes back to bindFor → mount guard
  *  no-ops; do NOT route the node itself through bindFor again here. */
-function bindAdoptedNode(node: HTMLElement, scope: Instance, disposers: Array<() => void>): void {
+function bindAdoptedNode(node: Element, scope: Instance, disposers: Array<() => void>): void {
   bindAttrs(node, scope, disposers)
   for (const child of Array.from(node.children)) {
-    if (!(child instanceof HTMLElement)) continue
+    if (!(child instanceof Element)) continue
     if (child.hasAttribute('x-data')) continue
     bindTree(child, scope, disposers)
   }
@@ -453,7 +469,7 @@ function bindAdoptedNode(node: HTMLElement, scope: Instance, disposers: Array<()
  *  each item-signal from the matching client item by key, wire reactivity, then
  *  hand the pre-populated map to the shared reconcile (first run = all reused). */
 function bindForAdopt(
-  seeds: HTMLElement[],
+  seeds: Element[],
   instance: Instance,
   parent: Node,
   expr: ForExpr,
@@ -469,7 +485,7 @@ function bindForAdopt(
   }
   const keys = keyPaths as string[]
   // template for future creates: stripped clone of the first seed.
-  const template = seeds[0].cloneNode(true) as HTMLElement
+  const template = seeds[0].cloneNode(true) as Element
   template.removeAttribute('x-for')
   stripKeyAttrs(template, keys)
   // anchor AFTER the last seed so future inserts keep document order.
@@ -489,7 +505,7 @@ function bindForAdopt(
   // adopt each seed in place.
   const map = new Map<string, ForEntry>()
   for (let si = 0; si < seeds.length; si++) {
-    const node = seeds[si] as HTMLElement
+    const node = seeds[si] as Element
     let key = seedKey(node, keys)
     if (map.has(key)) {
       // mirror the reconcile's dup-key handling: suffix so the entry is tracked
@@ -518,15 +534,15 @@ function bindForAdopt(
  * the node and runs those disposers. The per-clone disposers cover only non-x-data
  * teardown (bindTree skips nested x-data); nested x-data dispose/mount is delegated
  * to the MutationObserver on removal/insert — single-owner discipline. */
-function bindIf(el: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+function bindIf(el: Element, instance: Instance, disposers: Array<() => void>): void {
   const path = el.getAttribute('x-if') ?? ''
   const parent = el.parentNode
   if (!parent) return
   const anchor = el.ownerDocument.createComment('x-if')
   parent.insertBefore(anchor, el)
   el.removeAttribute('x-if')
-  const template = el.cloneNode(true) as HTMLElement // capture FIRST (before initial effect)
-  let current: HTMLElement | null = el // the original, adopted if initially truthy
+  const template = el.cloneNode(true) as Element // capture FIRST (before initial effect)
+  let current: Element | null = el // the original, adopted if initially truthy
   let bound = false // original starts unbound; clones are bound at creation
   const currentDisposers: Array<() => void> = []
   const teardown = () => {
@@ -557,7 +573,7 @@ function bindIf(el: HTMLElement, instance: Instance, disposers: Array<() => void
         }
         return
       }
-      const clone = template.cloneNode(true) as HTMLElement
+      const clone = template.cloneNode(true) as Element
       bindTree(clone, instance, currentDisposers) // bind BEFORE insert (observer mounts nested x-data after)
       anchor.parentNode?.insertBefore(clone, anchor.nextSibling)
       current = clone
@@ -657,13 +673,14 @@ function bindModel(
   )
 }
 
-function bindAttrs(el: HTMLElement, scope: Instance, disposers: Array<() => void>): void {
+function bindAttrs(el: Element, scope: Instance, disposers: Array<() => void>): void {
   for (const attr of Array.from(el.attributes)) {
     const name = attr.name
     const value = attr.value
     if (name === 'x-data' || name === 'x-props') continue
     if (name === 'x-model') {
-      bindModel(el, scope, value, disposers)
+      if (el instanceof HTMLElement) bindModel(el, scope, value, disposers)
+      else console.warn('[brust] x-model is only supported on HTML elements — binding skipped')
       continue
     }
     if (name === 'x-text') {
@@ -678,7 +695,11 @@ function bindAttrs(el: HTMLElement, scope: Instance, disposers: Array<() => void
     if (name === 'x-show') {
       disposers.push(
         effect(() => {
-          el.style.display = read(scope, value) ? '' : 'none'
+          if ('style' in el) {
+            ;(el as Element & { style: CSSStyleDeclaration }).style.display = read(scope, value)
+              ? ''
+              : 'none'
+          }
         }),
       )
       continue
@@ -718,40 +739,40 @@ function observeRoot(root: Node): void {
   const obs = new MutationObserver((records) => {
     for (const rec of records) {
       for (const node of Array.from(rec.removedNodes)) {
-        if (node instanceof HTMLElement) disposeTree(node)
+        if (node instanceof Element) disposeTree(node)
       }
       for (const node of Array.from(rec.addedNodes)) {
-        if (node instanceof HTMLElement) scanAndMount(node)
+        if (node instanceof Element) scanAndMount(node)
       }
     }
   })
   obs.observe(root, { childList: true, subtree: true })
 }
 
-function disposeTree(node: HTMLElement): void {
+function disposeTree(node: Element): void {
   if (mounted.has(node)) disposeElement(node)
-  for (const el of Array.from(node.querySelectorAll<HTMLElement>('[x-data]'))) {
+  for (const el of Array.from(node.querySelectorAll<Element>('[x-data]'))) {
     disposeElement(el)
   }
   // R10 — a removed HOST's shadow contents never reach any observer: the host's
   // removal fires on the light tree's observer, and the shadow root's own
   // observer only sees mutations INSIDE the root. Walk shadow roots explicitly.
   if (node.shadowRoot) disposeShadowContents(node.shadowRoot)
-  for (const el of Array.from(node.querySelectorAll<HTMLElement>('*'))) {
+  for (const el of Array.from(node.querySelectorAll<Element>('*'))) {
     if (el.shadowRoot) disposeShadowContents(el.shadowRoot)
   }
 }
 
 function disposeShadowContents(root: ShadowRoot): void {
-  for (const el of Array.from(root.querySelectorAll<HTMLElement>('[x-data]'))) {
+  for (const el of Array.from(root.querySelectorAll<Element>('[x-data]'))) {
     disposeElement(el)
   }
-  for (const el of Array.from(root.querySelectorAll<HTMLElement>('*'))) {
+  for (const el of Array.from(root.querySelectorAll<Element>('*'))) {
     if (el.shadowRoot) disposeShadowContents(el.shadowRoot)
   }
 }
 
-function disposeElement(el: HTMLElement): void {
+function disposeElement(el: Element): void {
   const m = mounted.get(el)
   if (!m) return
   for (const d of m.disposers.splice(0)) {
@@ -766,15 +787,19 @@ function disposeElement(el: HTMLElement): void {
 
 const BOOL_PROPS = new Set(['disabled', 'checked', 'hidden', 'readonly', 'required', 'selected'])
 
-/** Apply a bound value to a DOM attr/property. class → className; boolean props →
- * property (when present) + attribute presence; value → property; else attribute. */
-export function setBound(el: HTMLElement, attr: string, value: unknown): void {
+/** Apply a bound value to a DOM attr/property. class → HTML className or a
+ * namespace-safe attribute; boolean/value properties are used only when present. */
+export function setBound(el: Element, attr: string, value: unknown): void {
   if (attr === 'class') {
-    el.className = value == null ? '' : String(value)
+    if (el instanceof HTMLElement) el.className = value == null ? '' : String(value)
+    else if (value == null) el.removeAttribute('class')
+    else el.setAttribute('class', String(value))
     return
   }
   if (attr === 'value') {
-    ;(el as unknown as { value: unknown }).value = value == null ? '' : value
+    if ('value' in el) (el as unknown as { value: unknown }).value = value == null ? '' : value
+    else if (value == null) el.removeAttribute(attr)
+    else el.setAttribute(attr, String(value))
     return
   }
   if (BOOL_PROPS.has(attr)) {

package/runtime/render/inject-ai-client.ts

@@ -0,0 +1,38 @@
+const ENC = new TextEncoder()
+
+/** Splice `snippet` into `body` immediately before the first `</head>`
+ * (case-insensitive on the four ASCII letters only). Returns the original body
+ * untouched if `snippet` is null/empty or if `</head>` is absent.
+ *
+ * AI pages are document-only: fragment templates skip this injection entirely. */
+export function injectAiClient(body: Uint8Array, snippet: string | null): Uint8Array {
+  if (!snippet) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) return body
+  const tagBytes = ENC.encode(snippet)
+  const out = new Uint8Array(body.length + tagBytes.length)
+  out.set(body.subarray(0, pos), 0)
+  out.set(tagBytes, pos)
+  out.set(body.subarray(pos), pos + tagBytes.length)
+  return out
+}
+
+function findHeadCloseTag(body: Uint8Array): number {
+  const LT = 0x3c,
+    SL = 0x2f,
+    GT = 0x3e
+  for (let i = 0, max = body.length - 6; i < max; i++) {
+    if (body[i] !== LT || body[i + 1] !== SL) continue
+    if (!isLetter(body[i + 2], 0x48)) continue
+    if (!isLetter(body[i + 3], 0x45)) continue
+    if (!isLetter(body[i + 4], 0x41)) continue
+    if (!isLetter(body[i + 5], 0x44)) continue
+    if (body[i + 6] !== GT) continue
+    return i
+  }
+  return -1
+}
+
+function isLetter(b: number, u: number): boolean {
+  return b === u || b === (u | 0x20)
+}

package/runtime/render/stream.ts

@@ -7,6 +7,7 @@ import { Writable } from 'node:stream'
 import { IslandUsedContext, createIslandUsedBox } from '../islands/island.tsx'
 import { ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 import { injectCssLink } from './inject-css-link.ts'
+import { injectAiClient } from './inject-ai-client.ts'
 import { getCssHrefs, getCssHrefsForRoute } from '../css.ts'
 import { injectDevClient } from './inject-dev-client.ts'
 import { injectActionPrefix, getActionPrefixSnippet } from './inject-action-prefix.ts'
@@ -14,6 +15,7 @@ import { injectBrustStore, buildStoreScripts } from './inject-store.ts'
 import { getDevClientSnippet } from '../dev/inject.ts'
 import { getGeneratorMeta, injectGeneratorMeta } from './inject-generator.ts'
 import { injectShellMeta, shellMetaTag } from './inject-shell-meta.ts'
+import { aiScriptTag } from '../generator.ts'
 
 export interface RenderBranchStreamingArgs {
   element: ReactNode
@@ -184,6 +186,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             body = injectGeneratorMeta(body, getGeneratorMeta())
             body = injectShellMeta(body, args.shellId ?? '')
             body = injectDevClient(body, getDevClientSnippet())
+            body = injectAiClient(body, process.env.BRUST_AI === '1' ? aiScriptTag() : null)
             body = injectActionPrefix(body, getActionPrefixSnippet())
             body = injectBrustStore(body, args.storeSnapshot ?? null)
             const meta = makeMeta({
@@ -246,6 +249,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               .map((h) => `<link rel="stylesheet" href="${h}">`)
               .join('')
             const devTag = getDevClientSnippet() ?? ''
+            const aiTag = process.env.BRUST_AI === '1' ? aiScriptTag() : ''
             const prefixTag = getActionPrefixSnippet() ?? ''
             const storeTag = buildStoreScripts(args.storeSnapshot ?? null)
             const genTag = getGeneratorMeta() ?? ''
@@ -253,6 +257,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             if (
               linkTagsStr.length > 0 ||
               devTag.length > 0 ||
+              aiTag.length > 0 ||
               prefixTag.length > 0 ||
               storeTag.length > 0 ||
               genTag.length > 0 ||
@@ -261,9 +266,10 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               const prepend = encoder.encode(
                 genTag + shellTag + linkTagsStr + prefixTag + devTag + storeTag,
               )
-              const out = new Uint8Array(flushed.length + prepend.length)
-              out.set(flushed, 0)
-              out.set(prepend, flushed.length)
+              const out = new Uint8Array(prepend.length + aiTag.length + flushed.length)
+              out.set(prepend, 0)
+              out.set(encoder.encode(aiTag), prepend.length)
+              out.set(flushed, prepend.length + aiTag.length)
               flushed = out
             }
             const meta = makeMeta({ status: successStatus, streaming: true, headers: extraHeaders })

package/types/ai/manifest.d.ts

@@ -0,0 +1,17 @@
+import type { FlatRoute } from '../routes.ts';
+export interface AiPageEntry {
+    path: string;
+    params: string[];
+    catchAll: boolean;
+    kind: 'react' | 'native' | 'md';
+    shellId: string;
+    title?: string;
+    description?: string;
+}
+export interface AiManifest {
+    version: 1;
+    pages: AiPageEntry[];
+}
+export declare function extractAiManifest(routes: FlatRoute[]): AiManifest;
+export declare function writeManifest(cwd: string, manifest: AiManifest): Promise<void>;
+export declare function readManifest(cwd: string): Promise<AiManifest | null>;

package/types/cli/native-routes-emit.d.ts

@@ -71,7 +71,11 @@ export declare function countMainTags(template: string): number;
  *
  * Exported for the md emit step (runtime/md/emit.ts), which bakes the same tag
  * under its `withDevClient` option — md pages render Rust-side too, so without
- * it they never auto-reload in dev. */
+ * it they never auto-reload in dev.
+ *
+ * The AI runtime script is injected here as well when BRUST_AI=1. The tag is
+ * document-only: the compiler emits a head anchor for full documents, while
+ * fragment templates (no head) are left unchanged. */
 export declare function injectDevClientIntoTemplate(template: string): string;
 /** Bake the directive runtime loader into a native template iff it uses any
  * x-data directive. Idempotent. Wrapped in {% raw %} for symmetry with the islands

package/types/config.d.ts

@@ -10,6 +10,8 @@ export interface BrustConfig {
     cacheMaxEntries?: number;
     /** L2 page-cache capacity (entries). Undefined → Rust default of 1000. */
     cachePageMaxEntries?: number;
+    /** AI runtime toggle from BRUST_AI. Dev mode enables it separately. */
+    ai?: boolean;
     /** R9 cross-process cache invalidation: redis/dragonfly URL. Absent →
      * feature disabled (current single-process behavior). */
     cacheSyncUrl?: string;

package/types/generator.d.ts

@@ -4,6 +4,11 @@ export interface GeneratorStrings {
     /** X-Powered-By value, e.g. `brust/0.1.48-alpha` */
     header: string;
 }
+/** Full browser entry tag for the AI runtime chunk. */
+export declare function aiScriptTag(): string;
+/** Insert the AI runtime tag immediately before the first `</head>`.
+ * Document-only: fragment templates with no head are left unchanged. */
+export declare function injectAiScriptIntoTemplate(template: string): string;
 /** Build the resolved strings. Version comes from the brustjs package.json
  * (readVersion never throws — "unknown" degrades to name-only, never a crash).
  * The version is sanitized to attr/header-safe bytes; semver chars only. */

package/types/index.d.ts

@@ -183,6 +183,8 @@ export declare const brust: {
         /** Optional global CORS policy — see {@link CorsOptions}. Threaded to
          * serve() like `actionPrefix`. */
         cors?: CorsOptions;
+        /** AI runtime toggle. Dev mode enables it automatically. */
+        ai?: boolean;
         /** Overrides merged into the underlying `serve()` call (main thread). */
         serve?: Partial<Omit<ServeOptions, "entry" | "actions" | "mcp">>;
         /** Per-worker SAB size in bytes. Default 256 KB. */

package/types/islands/build.d.ts

@@ -18,6 +18,14 @@ export interface BuildIslandsOptions {
      * on the output filename (X.module.css + X.tsx → both X.js). */
     plugins?: BunPlugin[];
 }
+export interface BuildAiRuntimeOptions {
+    /** Override the output directory. Default: `<cwd>/.brust/islands`. */
+    outDir?: string;
+    /** Override the browser entry file. Default: `runtime/ai/index.ts`. */
+    entryFile?: string;
+    /** Build plugins passed straight to `Bun.build` for the AI runtime chunk. */
+    plugins?: BunPlugin[];
+}
 /** Scan a routes entry file for `<Island component={X} />` usage and derive the
  * island chunk list (componentName → absolute source path). Replaces the old
  * static config-file lookup — the chunk set is derived from source.
@@ -46,4 +54,5 @@ export declare function scanIslandChunks(routesEntryFile: string, extraIslands?:
 /** Build the runtime chunks + all island chunks + bootstrap. Returns the
  * absolute output directory; caller passes it to `brust.configureIslandsDir`. */
 export declare function buildIslands(islands: Map<string, string>, options?: BuildIslandsOptions): Promise<IslandsBuildResult>;
+export declare function buildAiRuntime(options?: BuildAiRuntimeOptions): Promise<string | null>;
 export declare function buildOne(entrypoints: string[], outdir: string, naming: string, external: string[], plugins?: BunPlugin[]): Promise<void>;

package/types/md/emit.d.ts

@@ -27,6 +27,9 @@ export interface MdEmitOpts {
      * BRUST_DEV injection — md pages render Rust-side and never pass through the
      * React renderer's dev-client injection). */
     withDevClient?: boolean;
+    /** Bake the AI runtime tag into document-style md templates. Fragments skip
+     * the injection entirely. */
+    aiEnabled?: boolean;
     /** What to do when a route's md file no longer exists on disk (deleted after
      * the route table was built). emitMdTemplates serves BOTH `brust build` and
      * the dev re-emit, and the two must diverge here:

package/types/native/runtime.d.ts

@@ -6,17 +6,17 @@ export type Instance = Record<string, unknown>;
  *                    for side-effects on signal change (sync localStorage, the DOM
  *                    outside the component, timers). Returns the disposer too.
  *  - `onCleanup(fn)` — register a one-shot teardown for unmount (e.g. removeEventListener). */
-export interface BehaviorCtx {
-    el: HTMLElement;
+export interface BehaviorCtx<Host extends Element = HTMLElement> {
+    el: Host;
     props: unknown;
     effect: (fn: () => void | (() => void)) => () => void;
     onCleanup: (fn: () => void) => void;
 }
-export type Behavior = (ctx: BehaviorCtx) => Instance;
+export type Behavior<Host extends Element = HTMLElement> = (ctx: BehaviorCtx<Host>) => Instance;
 /** Register a component behavior under `name`. Called by `<name>.directive.js` chunks
  * via the global handle below (they do NOT import this module — keeps each chunk to
  * just its behavior, with the runtime shared as the single `_directives.js` copy). */
-export declare function register(name: string, behavior: Behavior): void;
+export declare function register<Host extends Element = HTMLElement>(name: string, behavior: Behavior<Host>): void;
 /** Scan `root` (default: document) for [x-data], mount each, and (once) attach a
  * MutationObserver for dynamic mount/dispose. Idempotent. NOTE: `root` scopes the
  * INITIAL scan only; the observer always watches the global `document.body` (one
@@ -39,9 +39,9 @@ export declare function parseFor(raw: string): ForExpr | null;
  * for multi-hop paths). The LEAF is never called: `isSignal(leaf)` → `.set(value)`,
  * else warn once and skip. */
 export declare function writePath(scope: Instance, path: string, value: unknown): void;
-/** Apply a bound value to a DOM attr/property. class → className; boolean props →
- * property (when present) + attribute presence; value → property; else attribute. */
-export declare function setBound(el: HTMLElement, attr: string, value: unknown): void;
+/** Apply a bound value to a DOM attr/property. class → HTML className or a
+ * namespace-safe attribute; boolean/value properties are used only when present. */
+export declare function setBound(el: Element, attr: string, value: unknown): void;
 /** Walk a dotted member path against `scope`, unwrapping a signal/computed at EVERY
  * hop (so an intermediate item-signal is tracked by `effect`); at the LEAF also call
  * a plain function to obtain its value (this read is what `effect` tracks). */

package/types/render/inject-ai-client.d.ts

@@ -0,0 +1,6 @@
+/** Splice `snippet` into `body` immediately before the first `</head>`
+ * (case-insensitive on the four ASCII letters only). Returns the original body
+ * untouched if `snippet` is null/empty or if `</head>` is absent.
+ *
+ * AI pages are document-only: fragment templates skip this injection entirely. */
+export declare function injectAiClient(body: Uint8Array, snippet: string | null): Uint8Array;