@brust/runtime-dom 2.0.0-alpha.3 → 2.0.0-alpha.30

package/README.md

@@ -2,7 +2,7 @@
 
 React-free browser runtime that binds a compiled client chunk (`defineBehavior`) to server-rendered HTML
 through `x-*` attributes. **This README is the output format the M1c client backend prints against**; every
-behaviour below is pinned by a test in `test/`. Zero dependencies, eval-free, bundle < 17 KB minified
+behaviour below is pinned by a test in `test/`. Zero dependencies, eval-free, bundle < 18 KB minified
 (`bun scripts/build.ts`).
 
 ## Public surface
@@ -33,12 +33,15 @@ Anything else (`x + 1`, `fn()`) is not parsed: a warning is logged once and the
 
 ## Attributes
 
+Directives come only from compiler output: the compiler never prints an `x-*` attribute written in component JSX (warning `reserved-attr`), and the runtime does not bind inside `dangerouslySetInnerHTML` markup (`x-html` / `x-raw`) or a React island (`<brust-island>`).
+
 - **`x-data="name"`**: one instance per host. Nested hosts are bound by their own instance, not the parent's walker.
 - **`x-props='{"json":1}'`**: seeds `ctx.props`. Invalid JSON warns and seeds `{}`.
 - **`x-props-bind="member[:binding]"`**: on a child host, rebinds the child's `props` signal reactively to the nearest ancestor instance's member
   (an object, typically a `computed`; function values pass through). Inside `x-for` the row's scope supplies the bindings. If the parent is not mounted yet
   (chunk still loading) the child links up when the parent mounts. No ancestor: warns, keeps the `x-props` seed.
 - **`x-text="value"`**: sets `textContent`; `null`/`undefined` → `''`.
+- **`x-html="value"`**: sets `innerHTML` (raw markup, unescaped); `null`/`undefined` → `''`. Emitted only by the compiler, for a `dangerouslySetInnerHTML` whose value changes after first paint; the author sanitises the markup (same contract as React). The first-paint check compares parsed markup, so equivalent spellings do not warn.
 - **`x-show="value"`**: `style.display = ''` when truthy, `'none'` otherwise.
 - **`x-if="value"`**: the element is replaced by a `<!--x-if-->` comment anchor; a clone is inserted after it while truthy and removed otherwise.
   Nested `x-data` hosts in the clone mount/dispose with it. Server HTML omits the element when false.
@@ -55,7 +58,7 @@ Anything else (`x + 1`, `fn()`) is not parsed: a warning is logged once and the
 
 ## First-paint rule
 
-Nothing re-renders on mount: server HTML is the initial state. A binder writes the DOM only when its effect re-runs after a change, **or** when the initial `x-text` value differs from the server text,
+Nothing re-renders on mount: server HTML is the initial state. A binder writes the DOM only when its effect re-runs after a change, **or** when the initial `x-text` / `x-html` value differs from the server text,
 in which case it corrects it and warns once (`first-paint mismatch …`): a mismatch is a compiler bug the runtime must not hide. Elements created after mount (new rows, `x-if` clones) never trip this check.
 
 ## Gates
@@ -92,3 +95,13 @@ tracking state lives on `globalThis[Symbol.for('brust.reactive.ctx')]`).
   React-free.
 - `@brust/runtime-dom/store/internal`: the server-resolver hook and serialization helpers the Bun worker uses.
   Not part of the public surface.
+
+## Feature modules (L33, F139)
+
+The runtime is a core plus feature modules, so a page loads only what its components use and the client JS does not grow as the compiler learns more of React.
+
+- `@brust/runtime-dom/core` (`src/core.ts`): signals, `defineBehavior`/`setChunkLoader`, `mount`/`unmount`, the binder registry (`BINDERS`) and the internals features need (`src/core-api.ts`). It knows no directive by name.
+- `@brust/runtime-dom/features/<name>` (`src/features/*.ts`): `basics` (`x-text`, `x-show`, `x-bind-*`, `x-on-*`, `x-ref`), `if`, `for`, `model`, `html`, `island` (React island hydration glue). A feature registers itself with the core when imported and imports the core only through `core-api`; in the browser build `core-api` is the shared core file, so there is one signal graph and one binder registry per page.
+- `@brust/runtime-dom` (`src/index.ts`) is core + every feature, for tests and non-split consumers. The browser build never uses it.
+
+**The rule for a new feature.** The micro-directives nearly every interactive page uses ship together in `basics`. Anything else gets its OWN module when it is at least about 1 KB gzip OR used by a minority of pages: `store`, `island`, `if`/`for`/`model`/`html` as measured, and every future feature (context, portal, focus trap, ...). Do not add a feature to `basics` or the core to save a file; add it as a module the compiler requests only for routes that use it. The CI byte budget (core + `basics`) holds the line.

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.30",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./core": {
+      "types": "./src/core.ts",
+      "default": "./src/core.ts"
+    },
+    "./features/*": {
+      "types": "./src/features/*.ts",
+      "default": "./src/features/*.ts"
+    },
     "./store": {
       "types": "./src/store/index.ts",
       "default": "./src/store/index.ts"
@@ -36,7 +44,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.4",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "happy-dom": "^20.0.0",
@@ -49,5 +57,14 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "homepage": "https://brust.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git",
+    "directory": "packages/runtime-dom"
+  },
+  "bugs": {
+    "url": "https://github.com/AssetsArt/brust/issues"
   }
 }

package/src/attr-kinds.ts

@@ -0,0 +1,6 @@
+// GENERATED from crates/brust-jinja/src/lib.rs (BOOLEAN_ATTRS, OVERLOADED_ATTRS, STRINGIFY_ATTRS); do not edit.
+// Regenerate: bun scripts/gen-attr-kinds.ts. test/attr-kinds.test.ts fails when this drifts.
+const set = (s: string): Set<string> => new Set(s.split(' '))
+export const BOOLEAN = set('allowfullscreen async autofocus autoplay checked controls default defer disabled disablepictureinpicture disableremoteplayback formnovalidate hidden inert itemscope loop multiple muted nomodule novalidate open playsinline readonly required reversed scoped seamless selected')
+export const OVERLOADED = set('capture download')
+export const STRINGIFY = set('autoreverse contenteditable draggable externalresourcesrequired focusable preservealpha spellcheck value')

package/src/core-api.ts

@@ -0,0 +1,11 @@
+// What a feature module may import from the core, and nothing else. In the browser build the core is one shared
+// ESM file and every feature is a separate file that imports these names from it (bundle.ts maps this module to the
+// core URL), so a feature registers on the page's single binder registry and signal graph.
+export { BINDERS, bindHost, bindElement, bindRef, walkChildren } from './directives/index'
+export type { Binder } from './directives/index'
+export { parsed, read, member, mismatch, insideRaw, RAW_SEL } from './directives/common'
+export { hooks, islandHooks, collectionHooks } from './instance'
+export type { CollectionItem } from './instance'
+export { warnOnce } from './warn'
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
+export type { Signal, Computed, Dispose } from './signal'

package/src/core.ts

@@ -0,0 +1,8 @@
+// The always-loaded core: signals, the behavior registry, mount/unmount and the binder registry. Features
+// (./features/*) register their binders on import; nothing here knows a directive by name.
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
+export type { Signal, Computed, Dispose } from './signal'
+export { defineBehavior, setChunkLoader } from './registry'
+export type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
+export { mount, unmount } from './mount'
+export * from './core-api'

package/src/directives/bind.ts

@@ -1,12 +1,38 @@
-import { BINDERS } from './index'
-import { parsed, read } from './common'
-import { warnOnce } from '../warn'
+import { reactEvent } from './on'
+import { BINDERS, parsed, read, warnOnce } from '../core-api'
+import { BOOLEAN, OVERLOADED, STRINGIFY } from '../attr-kinds'
+import type { Instance } from '../instance'
 
 // Attributes that execute or load code from a string; a bound value must never reach them as-is.
 const URL_ATTRS = new Set(['href', 'src', 'action', 'formaction', 'poster', 'data', 'xlink:href', 'ping'])
 // Scheme allowlist on the parsed URL (relative URLs resolve to http): new URL() applies the browser's tab/newline/control-char stripping.
 const safeUrl = (v: string): boolean => { try { return ['http:', 'https:', 'mailto:', 'tel:'].includes(new URL(v, 'http://x').protocol) } catch { return false } }
-const BOOLEAN = new Set(['disabled', 'checked', 'selected', 'readonly', 'required', 'hidden', 'open', 'multiple'])
+/** Writes one bound attribute value with React's rules (shared by `x-bind-*` and `x-prop-*`, A2: one print path). */
+function writeAttr(inst: Instance, attr: string, el: Element, name: string, v: unknown): void {
+  // setAttribute: `className` is a getter-only SVGAnimatedString on SVG elements (F96a).
+  // F311: undefined/null removes `class` (React does; `className=""` keeps an empty one), and an empty `style` is no attribute (the first paint omits it)
+  if (name === 'class') { if (v == null) el.removeAttribute('class'); else el.setAttribute('class', `${v}`); return }
+  // F434: a multiple select is bound to an array, one pick per option (`null`/`undefined` leave the picks alone, as React does)
+  if (name === 'value' && el instanceof HTMLSelectElement && el.multiple) { if (v != null) { const vs = ([] as unknown[]).concat(v).map(String); for (const o of el.options) o.selected = vs.includes(o.value) } return }
+  if (name === 'value' && 'value' in el) { (el as HTMLInputElement).value = v == null ? '' : String(v); return }
+  // React passes every attribute of a custom element (a tag with `-`) through as given: `true` is ``, `false` omits it.
+  const custom = el.localName.includes('-')
+  if (!custom && BOOLEAN.has(name)) {
+    const on = Boolean(v)
+    if (name in el) (el as unknown as Record<string, unknown>)[name] = on
+    if (on) el.setAttribute(name, '') ; else el.removeAttribute(name)
+    return
+  }
+  // aria-*, data-* and the booleanish strings print `true`/`false`; download/capture print `true` as ``; on any other attribute React omits a boolean.
+  if (!custom && (name.startsWith('aria-') || name.startsWith('data-') || STRINGIFY.has(name))) { if (v == null) el.removeAttribute(name); else el.setAttribute(name, String(v)); return }
+  if ((custom || OVERLOADED.has(name)) && typeof v === 'boolean') { if (v) el.setAttribute(name, ''); else el.removeAttribute(name); return }
+  if (v == null || typeof v === 'boolean' || (name === 'style' && !v)) { el.removeAttribute(name); return }
+  // React writes no `src=""` / `href=""` (it would load the page again); an anchor keeps its empty href.
+  if (v === '' && (name === 'src' || name === 'href') && el.localName !== 'a' && !custom) { el.removeAttribute(name); return }
+  if (URL_ATTRS.has(name) && !safeUrl(String(v))) { warnOnce(`b:${inst.name}:${name}`, `${attr} in ${inst.name}: unsafe URL refused`); return }
+  el.setAttribute(name, String(v))
+}
+
 BINDERS.push({
   match: (a) => a.startsWith('x-bind-'),
   bind: ({ inst, el, attr, raw, scope }) => {
@@ -15,18 +41,39 @@ BINDERS.push({
     const p = parsed(inst, attr, raw); if (!p) return
     inst.effect(() => {
       const r = read(inst, p, scope, attr); if (!r.ok) return
-      const v = r.value
-      if (name === 'class') { (el as HTMLElement).className = v == null ? '' : String(v); return }
-      if (name === 'value' && 'value' in el) { (el as HTMLInputElement).value = v == null ? '' : String(v); return }
-      if (BOOLEAN.has(name)) {
-        const on = Boolean(v)
-        if (name in el) (el as unknown as Record<string, unknown>)[name] = on
-        if (on) el.setAttribute(name, '') ; else el.removeAttribute(name)
-        return
-      }
-      if (v == null || v === false) { el.removeAttribute(name); return }
-      if (URL_ATTRS.has(name) && !safeUrl(String(v))) { warnOnce(`b:${inst.name}:${name}`, `${attr} in ${inst.name}: unsafe URL refused`); return }
-      el.setAttribute(name, String(v))
+      writeAttr(inst, attr, el, name, r.value)
     })
   },
 })
+
+// F329b: `x-prop-<attribute>="<prop key>"` binds the attribute to a prop of THIS instance (`inst.props()`), the key being
+// the VALUE (a prop key is not a member path: `aria-checked`, `tabIndex`). The key set is a property of one call site, so it is
+// printed in the template, never as a chunk member (the chunk stays shared). The attribute name is the lowercase DOM name the
+// server print used (the shared React -> attribute table), so both ends agree.
+// Refused, as `x-bind-*` refuses them and more: event handlers, `srcdoc`, `x-*`, and the keys the server print never
+// binds through a spread (class, style, value, checked, selected, URL-bearing attributes).
+const PROP_REFUSED = new Set(['srcdoc', 'class', 'style', 'value', 'checked', 'selected', ...URL_ATTRS])
+BINDERS.push({
+  match: (a) => a.startsWith('x-prop-'),
+  bind: ({ inst, el, attr, raw }) => {
+    const name = attr.slice('x-prop-'.length)
+    // F369c: `x-prop-on-<event>="<prop key>"` calls the instance's prop (a function a caller handed through the child's rest)
+    // with the event, reading it at call time so a prop that changes is the one that runs. The event is `[a-z0-9]+`.
+    if (name.startsWith('on-')) {
+      const event = name.slice(3)
+      if (!raw || !/^[a-z0-9]+$/.test(event)) { warnOnce(`pb:${inst.name}:${name}`, `${attr} in ${inst.name} refused`); return }
+      const handler = (e: Event) => {
+        reactEvent(e)
+        const ps = inst.props(); const fn = Object.hasOwn(ps, raw) ? ps[raw] : undefined
+        if (typeof fn === 'function') (fn as (e: Event) => void)(e)
+      }
+      el.addEventListener(event, handler)
+      inst.onCleanup(() => el.removeEventListener(event, handler))
+      return
+    }
+    if (!name || !raw || name.startsWith('on') || name.startsWith('x-') || PROP_REFUSED.has(name)) {
+      warnOnce(`pb:${inst.name}:${name}`, `${attr} in ${inst.name} refused`); return
+    }
+    inst.effect(() => { const ps = inst.props(); writeAttr(inst, attr, el, name, Object.hasOwn(ps, raw) ? ps[raw] : undefined) })
+  },
+})

package/src/directives/common.ts

@@ -2,6 +2,10 @@ import { parseValue, resolve, resolveMember, type ParsedValue, type Scope } from
 import { warnOnce } from '../warn'
 import type { Instance } from '../instance'
 
+/** Markup inside a `dangerouslySetInnerHTML` element (`x-html` / `x-raw`, compiler-emitted) or a React island is inert: nothing under it is bound, mounted or hydrated. */
+export const RAW_SEL = '[x-html],[x-raw],brust-island'
+export const insideRaw = (el: Element): boolean => !!el.parentElement?.closest(RAW_SEL)
+
 export function parsed(inst: Instance, attr: string, raw: string): ParsedValue | null {
   const p = parseValue(raw)
   if (!p) warnOnce(`p:${inst.name}:${attr}:${raw}`, `${attr}="${raw}" in ${inst.name}: not a member path`)
@@ -19,5 +23,7 @@ export function member(inst: Instance, p: ParsedValue, attr: string): unknown {
 }
 export function mismatch(inst: Instance, attr: string, _el: Element, server: unknown, client: unknown): void {
   if (inst.booted) return   // element created after mount (new x-for row / x-if clone): nothing was server-rendered
+  if (inst.late) return   // F301: mounted after the page booted (a navigation's markup, a React client mount): no first paint to compare
+  if (inst.reseeded) return   // F277: a host created later, started from its parent's current props, not the printed ones
   warnOnce(`x:${inst.name}:${attr}`, `first-paint mismatch ${attr} in ${inst.name}: ${JSON.stringify(server)} vs ${JSON.stringify(client)}`)
 }

package/src/directives/for.ts

@@ -1,13 +1,14 @@
-import { BINDERS, bindElement, walkChildren } from './index'
-import { parsed, read, member } from './common'
-import { warnOnce } from '../warn'
-import { computed, signal, type Signal } from '../signal'
-import { hooks } from '../instance'
+import { BINDERS, bindElement, walkChildren, parsed, read, member, warnOnce, computed, signal, hooks, type Signal } from '../core-api'
 
 type RowScope = Record<string, unknown> & { __own: Signal<number> }
 
 const SYNTAX = /^\s*([A-Za-z_$][\w$]*)\s*(?:,\s*([A-Za-z_$][\w$]*))?\s+in\s+([A-Za-z_$][\w$.]*(?::[A-Za-z_$][\w$]*(?:\s*,\s*[A-Za-z_$][\w$]*)*)?)\s+by\s+([A-Za-z_$][\w$.]*)\s*$/
 const done = new WeakSet<Element>()
+/** The comments this binder inserted: the server's own `<!--x-for-->` marker is not among them. */
+const anchors = new WeakSet<Node>()
+/** F396: the zero-row template is the element the server prints right after its `<!--x-for-->` marker. A row is not
+ * told apart by `hidden`: a row whose own root is `hidden={cond}` is server-rendered hidden and is still a row. */
+const isTemplate = (s: Element) => { const p = s.previousSibling; return p instanceof Comment && p.data === 'x-for' && !anchors.has(p) }
 
 BINDERS.push({
   match: (a) => a === 'x-for',
@@ -21,16 +22,20 @@ BINDERS.push({
     // All server-rendered siblings carrying the same x-for are rows of this list; the first is the template.
     const parent = el.parentElement!
     const siblings = Array.from(parent.children).filter((c) => c.getAttribute('x-for') === raw)
+    const templates = new Set(siblings.filter(isTemplate))
     siblings.forEach((s) => done.add(s))
     const template = el.cloneNode(true) as Element
     template.removeAttribute('x-for'); template.removeAttribute('hidden')
-    const anchor = document.createComment('x-for')
+    const anchor = document.createComment('x-for'); anchors.add(anchor)
     parent.insertBefore(anchor, el)
-    // Server-rendered rows (not the hidden zero-row template) are adopted in order on the first run.
-    const adopt = siblings.filter((s) => !s.hasAttribute('hidden'))
+    // Server-rendered rows (not the zero-row template) are adopted in order on the first run.
+    const adopt = siblings.filter((s) => !templates.has(s))
     if (!adopt.includes(el)) el.remove()
     let firstRun = true
 
+    // F415: a removed row's effects and cleanups go with it (they were bound under `inst.capture`).
+    const drops = new Map<Element, () => void>()
+    const drop = (n: Element) => { drops.get(n)?.(); drops.delete(n); n.remove() }
     let rows = new Map<unknown, Element[]>()  // key -> elements (array to tolerate duplicates)
     let order: Element[] = []
 
@@ -44,7 +49,10 @@ BINDERS.push({
       const seen = new Set<unknown>()
       list.forEach((item, i) => {
         let key = (keyFn as (x: unknown) => unknown)(item)
-        if (seen.has(key)) { warnOnce(`fd:${inst.name}:${raw}`, `x-for in ${inst.name}: duplicate key ${JSON.stringify(key)}`); key = `__dup_${i}` }
+        // `undefined` is a row whose element arm is null (`it.link && <li key={it.link.id}/>`): it
+        // carries no key in React either, so it is positional and never a duplicate.
+        if (key === undefined) key = `__nil_${i}`
+        else if (seen.has(key)) { warnOnce(`fd:${inst.name}:${raw}`, `x-for in ${inst.name}: duplicate key ${JSON.stringify(key)}`); key = `__dup_${i}` }
         seen.add(key)
         const pool = rows.get(key)
         let node = pool?.shift()
@@ -66,12 +74,12 @@ BINDERS.push({
           const rowScope: RowScope = { ...scope, [itemName]: item, ...(indexName ? { [indexName]: i } : {}), __own: own, __tick: computed(() => (outer ? outer() : 0) + own()) }
           ;(node as unknown as { __scope: RowScope }).__scope = rowScope
           // a row that is itself a nested host is bound by its own instance
-          if (!node.hasAttribute('x-data')) { bindElement(inst, node, rowScope); walkChildren(inst, node, rowScope) }
+          if (!node.hasAttribute('x-data')) { const n = node; drops.set(n, inst.capture(() => { bindElement(inst, n, rowScope); walkChildren(inst, n, rowScope) })) }
         }
         ;(next.get(key) ?? next.set(key, []).get(key)!).push(node)
         nextOrder.push(node)
       })
-      for (const [, pool] of rows) for (const stale of pool) stale.remove()
+      for (const [, pool] of rows) for (const stale of pool) drop(stale)
       for (const left of adopt.splice(0)) left.remove()
       firstRun = false
       // place in order after the anchor
@@ -80,6 +88,6 @@ BINDERS.push({
       rows = next; order = nextOrder
       for (const n of created) hooks.mountTree(n)   // nested hosts in new rows mount now, not on the observer's next tick
     })
-    inst.onCleanup(() => { for (const n of order) n.remove() })
+    inst.onCleanup(() => { for (const n of order) drop(n) })
   },
 })

package/src/directives/html.ts

@@ -0,0 +1,20 @@
+import { BINDERS, parsed, read, mismatch } from '../core-api'
+/** Both sides through the HTML parser (inert `<template>`), so `<br/>` vs `<br>` or entity spelling is not a mismatch. */
+function sameMarkup(el: Element, next: string): boolean {
+  const t = document.createElement('template'); t.innerHTML = next
+  return t.innerHTML === el.innerHTML
+}
+// `x-html` is emitted only by the compiler, for a `dangerouslySetInnerHTML` whose value changes after first paint.
+BINDERS.push({
+  match: (a) => a === 'x-html',
+  bind: ({ inst, el, attr, raw, scope }) => {
+    const p = parsed(inst, attr, raw); if (!p) return
+    let first = true
+    inst.effect(() => {
+      const r = read(inst, p, scope, attr); if (!r.ok) return
+      const next = r.value == null ? '' : String(r.value)
+      if (first) { first = false; if (!sameMarkup(el, next)) { mismatch(inst, attr, el, el.innerHTML, next); el.innerHTML = next }; return }
+      el.innerHTML = next
+    })
+  },
+})

package/src/directives/if.ts

@@ -1,6 +1,11 @@
-import { BINDERS, bindElement, walkChildren } from './index'
-import { parsed, read } from './common'
-import { hooks } from '../instance'
+import { BINDERS, bindElement, walkChildren, parsed, read, hooks } from '../core-api'
+/** The callback refs of the branch being inserted: attached once its whole subtree is bound and mounted (React attaches
+ * refs in the commit, after the DOM is placed and before layout effects). An inner branch inserted with it hands its
+ * refs over, so the outermost attaches them all in DOM post-order (children first, as React's commit does). */
+type Attach = [el: Element, on: () => void]
+let attach: Attach[] | null = null
+/** `a` first when `b` contains it (8) or follows it (4) without being inside it (16). */
+const postOrder = ([a]: Attach, [b]: Attach) => { const p = a.compareDocumentPosition(b); return p & 8 || (p & 20) === 4 ? -1 : 1 }
 BINDERS.push({
   match: (a) => a === 'x-if',
   bind: ({ inst, el, attr, raw, scope }) => {
@@ -10,18 +15,46 @@ BINDERS.push({
     template.removeAttribute('x-if'); template.removeAttribute('hidden')
     el.replaceWith(anchor)                 // the server-rendered element becomes the first clone below
     let current: Element | null = null
+    // F415/F416: what the branch bound (its effects, its x-ref) is let go before the element leaves, as React detaches
+    // a removed host's refs in the same commit.
+    let drop = () => {}
+    const remove = () => { drop(); drop = () => {}; current?.remove(); current = null }   // the observer disposes nested hosts
     inst.effect(() => {
       const r = read(inst, p, scope, attr); if (!r.ok) return
       const want = Boolean(r.value)
       if (want && !current) {
-        current = template.cloneNode(true) as Element
-        anchor.after(current)
-        bindElement(inst, current, scope); walkChildren(inst, current, scope)
-        hooks.mountTree(current)
-      } else if (!want && current) {
-        current.remove(); current = null   // the observer disposes nested hosts
-      }
+        const node = (current = template.cloneNode(true) as Element)
+        anchor.after(node)
+        const outer = attach; const mine: Attach[] = (attach = [])
+        try {
+          // nested hosts mount inside the capture too: an `x-cref` on one registers its detach on this branch
+          drop = inst.capture(() => { bindElement(inst, node, scope); walkChildren(inst, node, scope); hooks.mountTree(node) })
+        } finally { attach = outer }
+        if (outer) outer.push(...mine)
+        else for (const [, on] of mine.sort(postOrder)) on()
+      } else if (!want && current) remove()
     })
-    inst.onCleanup(() => { current?.remove() })
+    inst.onCleanup(remove)
+  },
+})
+// F288 phase B (G5): `x-cref="cell"`, a callback ref inside a branch. The cell holds the callback (or a ref object); it
+// gets the node when the branch is inserted and `null` (or the callback's returned cleanup) when it is removed. On a
+// nested host the host's own instance meets it while it mounts, inside the branch's capture. (A host whose behavior
+// chunk is not loaded yet binds later through whenBehavior, outside the capture: it attaches at once and detaches only
+// with the owner, not the branch: reachable only if an inlined child's root can have its behavior in another chunk.)
+BINDERS.push({
+  match: (a) => a === 'x-cref',
+  bind: ({ inst, el, raw }) => {
+    // on a nested host (an inlined native child's root) the cell is the caller's, as `x-pref`'s is
+    const owner = el === inst.host ? inst.parent : inst
+    if (!owner) return
+    const r = owner.ref(raw.trim()).current as unknown
+    let off: (() => void) | void
+    owner.onCleanup(() => { off?.(); off = undefined })
+    const on = () => {
+      if (typeof r === 'function') { const c = r(el); off = typeof c === 'function' ? c : () => r(null) }
+      else if (r) { (r as { current: unknown }).current = el; off = () => { (r as { current: unknown }).current = null } }
+    }
+    attach ? attach.push([el, on]) : on()
   },
 })

package/src/directives/index.ts

@@ -12,14 +12,25 @@ export function bindHost(inst: Instance, el: Element, scope: Scope): void {
   walkChildren(inst, el, scope)
 }
 export function walkChildren(inst: Instance, el: Element, scope: Scope): void {
+  if (el.hasAttribute('x-html') || el.hasAttribute('x-raw') || el.localName === 'brust-island') return   // raw markup / React island: inert
   for (const child of Array.from(el.children)) {
     if ('__scope' in child) continue                          // x-for row: already bound with its own scope
     if (child.hasAttribute('x-for')) { bindElement(inst, child, scope); continue } // x-for owns the element (even when it is also a host)
-    if (child.hasAttribute(HOST_ATTR)) continue               // nested host: its own instance binds it
+    if (child.hasAttribute(HOST_ATTR)) {                       // nested host: its own instance binds it,
+      const pref = child.getAttribute('x-pref')                // but the ref its caller passed is the caller's (F267/F288)
+      if (pref) bindRef(inst, child, pref)
+      continue
+    }
     bindElement(inst, child, scope)
     if (!child.hasAttribute('x-if')) walkChildren(inst, child, scope)   // x-if owns its subtree
   }
 }
+/** `x-ref` / `x-pref`: the instance's ref cell `name` holds `el` while it is bound. */
+export function bindRef(inst: Instance, el: Element, name: string): void {
+  const r = inst.ref(name.trim())
+  r.current = el as HTMLElement
+  inst.onCleanup(() => { if (r.current === el) r.current = null })
+}
 export function bindElement(inst: Instance, el: Element, scope: Scope): void {
   // Structural directives own the element: x-for/x-if re-create it from a template, so the
   // remaining attributes are bound on the clones (with the right scope), never on this original.

package/src/directives/model.ts

@@ -1,7 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, member } from './common'
-import { isSignal, type Signal } from '../signal'
-import { warnOnce } from '../warn'
+import { BINDERS, parsed, member, isSignal, warnOnce, type Signal } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-model',
   bind: ({ inst, el, attr, raw }) => {
@@ -20,9 +17,10 @@ BINDERS.push({
       const h = () => { if (input.checked) s.set(input.value) }; el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
       inst.effect(() => { input.checked = s() === input.value })
     } else if (el instanceof HTMLSelectElement) {
-      if (el.multiple) { warnOnce(`mm:${inst.name}`, `select[multiple] unsupported`); return }
-      const h = () => s.set(el.value); el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
-      const apply = () => { const v = s(); if (el.value !== String(v)) el.value = String(v ?? '') }
+      // F434: a multiple select is an array of the picked values
+      const many = el.multiple
+      const h = () => s.set(many ? Array.from(el.options).filter((o) => o.selected).map((o) => o.value) : el.value); el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
+      const apply = () => { const v = s(); if (many) { if (v != null) { const vs = ([] as unknown[]).concat(v).map(String); for (const o of el.options) o.selected = vs.includes(o.value) } } else if (el.value !== String(v)) el.value = String(v ?? '') }
       inst.effect(apply)
       const mo = new MutationObserver(() => apply()); mo.observe(el, { childList: true }); inst.onCleanup(() => mo.disconnect())
     } else {

package/src/directives/on.ts

@@ -1,11 +1,26 @@
-import { BINDERS } from './index'
-import { parsed, member } from './common'
+import { BINDERS, parsed, member } from '../core-api'
+
+// React's SyntheticEvent has five members a DOM event lacks; code written for React calls them on the event it is handed
+// (Radix: `event.isPropagationStopped()`), and on a DOM event that is a TypeError (F195). Added to the event the handler
+// receives, never to Event.prototype, so nothing else on the page changes.
+const SYNTHETIC: PropertyDescriptorMap = {
+  isPropagationStopped: { value(this: Event) { return this.cancelBubble } },
+  isDefaultPrevented: { value(this: Event) { return this.defaultPrevented } },
+  persist: { value() {} },
+  isPersistent: { value: () => true },
+  nativeEvent: { get(this: Event) { return this } },
+}
+/** Gives a DOM event the React members (once). Shared with `x-prop-on-*`. */
+export function reactEvent(e: Event): void {
+  if (!('isPropagationStopped' in e)) Object.defineProperties(e, SYNTHETIC)
+}
 BINDERS.push({
   match: (a) => a.startsWith('x-on-'),
   bind: ({ inst, el, attr, raw, scope }) => {
     const event = attr.slice('x-on-'.length)
     const p = parsed(inst, attr, raw); if (!p) return
     const handler = (e: Event) => {
+      reactEvent(e)
       const fn = member(inst, p, attr)
       if (typeof fn !== 'function') return
       const args = p.bindings.map((b) => scope[b])

package/src/directives/ref.ts

@@ -1,9 +1,5 @@
-import { BINDERS } from './index'
+import { BINDERS, bindRef } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-ref',
-  bind: ({ inst, el, raw }) => {
-    const r = inst.ref(raw.trim())
-    r.current = el as HTMLElement
-    inst.onCleanup(() => { if (r.current === el) r.current = null })
-  },
+  bind: ({ inst, el, raw }) => bindRef(inst, el, raw),
 })

package/src/directives/show.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read } from './common'
+import { BINDERS, parsed, read } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-show',
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/directives/text.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read, mismatch } from './common'
+import { BINDERS, parsed, read, mismatch } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-text',
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/features/basics.ts

@@ -0,0 +1,6 @@
+// The directives nearly every interactive page uses, shipped as ONE module (see README "Feature modules").
+import '../directives/text'
+import '../directives/show'
+import '../directives/bind'
+import '../directives/on'
+import '../directives/ref'

package/src/features/collection.ts

@@ -0,0 +1,40 @@
+// The collection feature (R34.140-R34.141): the items a Radix `createCollection` tracks, as the DOM already has them.
+// A root is an element with `x-collection-root`; an item is an element with `data-radix-collection-item` whose NEAREST root
+// above it is that root (a collection nested inside another keeps its items to itself). Document order is the DOM's own,
+// so there is no registry to sort. An item's data (`id`, `focusable`, ...) is what its host's `x-collection-item` member
+// evaluates to when asked: read at call time, so it is never stale.
+import { BINDERS, collectionHooks, parsed, read, RAW_SEL } from '../core-api'
+import type { CollectionItem } from '../core-api'
+
+const ROOT = '[x-collection-root]'
+const ITEM = '[data-radix-collection-item]'
+const DATA = new WeakMap<Element, () => unknown>()
+
+collectionHooks.items = (from) => {
+  const root = from.closest(ROOT)
+  if (!root) return []
+  const out: CollectionItem[] = []
+  for (const el of Array.from(root.querySelectorAll(ITEM))) {
+    // the nearest root ABOVE the item (not the item itself, which may be a root of its own)
+    if (el.parentElement?.closest(ROOT) !== root) continue
+    // an island or raw markup (x-html / x-raw) between the root and the item is inert: its items are not this collection's
+    // (Radix keeps only the nodes registered through its own context, never what a foreign widget or CMS markup holds)
+    const raw = el.parentElement?.closest(RAW_SEL)
+    if (raw && root.contains(raw)) continue
+    const d = DATA.get(el)?.()
+    out.push({ ...(d && typeof d === 'object' ? (d as object) : {}), ref: { current: el }, element: el })
+  }
+  return out
+}
+
+// markers: a root, and a host that reads `ctx.items()` (so the module loads for it); neither binds anything
+BINDERS.push({ match: (a) => a === 'x-collection-root' || a === 'x-collection-use', bind: () => {} })
+BINDERS.push({
+  match: (a) => a === 'x-collection-item',
+  bind: ({ inst, el, attr, raw, scope }) => {
+    const p = parsed(inst, attr, raw)
+    if (!p) return
+    DATA.set(el, () => { const r = read(inst, p, scope, attr); return r.ok ? r.value : undefined })
+    inst.onCleanup(() => DATA.delete(el))
+  },
+})

package/src/features/for.ts

@@ -0,0 +1 @@
+import '../directives/for'

package/src/features/html.ts

@@ -0,0 +1 @@
+import '../directives/html'

package/src/features/if.ts

@@ -0,0 +1 @@
+import '../directives/if'

package/src/features/index.ts

@@ -0,0 +1,9 @@
+// Every feature at once: what `@brust/runtime-dom` (the full entry) loads. The browser build never uses this file;
+// it imports exactly the features a route needs.
+import './basics'
+import './if'
+import './for'
+import './model'
+import './html'
+import './island'
+import './collection'

package/src/features/island.ts

@@ -0,0 +1,9 @@
+// React island hydration glue. Registers on the core's island hooks; hosts already in the document when this module
+// arrives (the core mounts first) are scheduled right away.
+import { islandHooks } from '../core-api'
+import { scheduleIslands, cancelIslands } from '../island'
+islandHooks.schedule = scheduleIslands
+islandHooks.cancel = cancelIslands
+if (typeof document !== 'undefined') scheduleIslands(document.documentElement)
+export { defineIsland } from '../island'
+export type { IslandHydrate } from '../island'

package/src/features/model.ts

@@ -0,0 +1 @@
+import '../directives/model'

package/src/features/store.ts

@@ -0,0 +1,6 @@
+// The store module: `defineStore` plus the reactive primitives a store's code imports (`@brust/core/store` aliases here),
+// re-exported from the core so there is one signal graph per page.
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from '../core-api'
+export type { Signal, Computed, Dispose } from '../core-api'
+export { defineStore } from '../store/define-store'
+export type { StoreHandle, Snapshot } from '../store/define-store'