@brust/runtime-dom 0.0.0-stage → 2.0.0-alpha.10

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @brust/runtime-dom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 < 18 KB minified
+(`bun scripts/build.ts`).
+
+## Public surface
+
+```ts
+import { signal, computed, effect, batch, untracked, defineBehavior, setChunkLoader, mount, unmount } from '@brust/runtime-dom'
+```
+
+- Signals (`test/signal.test.ts`): writes are `Object.is`-deduped; `computed` is lazy and cached; `effect(fn)` runs now and on
+  change, a returned function is a cleanup that runs before each re-run and on dispose; `batch` defers effects to its end;
+  `untracked` reads without subscribing.
+- `defineBehavior(name, factory)`: `factory({ el, props, effect, onCleanup, ref })` returns the instance **members**
+  (signals, computeds, functions, plain values). `props` is a **signal** of the props object. An `init` member, if a function, runs after the factory.
+- `setChunkLoader(load)`: called once per unknown behavior name; the loader is expected to call `defineBehavior(name, …)`. Default: none (hosts wait).
+- `mount(root = document.body)`: idempotent; mounts every `[x-data]` in document order (parents first) and starts a `MutationObserver`
+  that mounts added hosts and disposes removed ones (a removed-then-reinserted host is disposed, then mounted fresh).
+  `unmount(root)` disposes instances under `root` and stops the observer. A factory that throws is logged and its instance discarded; other hosts still mount.
+
+## Directive value grammar
+
+```
+value    := path (":" bindings)?
+path     := ident ("." ident)*          // looked up on the instance members; a signal/computed hop is unwrapped
+bindings := ident ("," ident)*          // loop-scope names (x-for item/index); the member must be a function and is called with them
+```
+
+Anything else (`x + 1`, `fn()`) is not parsed: a warning is logged once and the DOM is left as rendered. An unknown member behaves the same.
+
+## 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.
+- **`x-bind-<attr>="value"`**: `class` → `className`; `value` → `.value`; `disabled checked selected readonly required hidden open multiple` → property + attribute (present/absent);
+  anything else: `null`/`undefined`/`false` removes the attribute, otherwise `setAttribute`. **Refused** (warn once): `on*` and `srcdoc` attributes, and, in `href src action formaction poster data`, any URL whose parsed scheme is not `http(s):`/`mailto:`/`tel:` (relative URLs are fine; `java\tscript:` is caught because the URL is parsed, not pattern-matched).
+- **`x-on-<event>="member[:binding]"`**: calls the member with the bound scope values first, then the event: `pick(item, index, event)`.
+- **`x-model="member"`**: the member must be a writable signal (else warns). text-like: `input` event ↔ `.value`; checkbox: `change` ↔ boolean `.checked`;
+  radio: `change` writes `.value` when checked, signal sets `.checked`; single `select`: `change` ↔ `.value`, re-applied whenever its options change. `select[multiple]` is unsupported (warns).
+- **`x-for="item[, index] in source by keyFn"`**: `source := path (":" bindings)?` is a member path to an array (or signal/computed of one); with bindings the member is a function called with the outer loop names, so a nested list reads the outer row, e.g. `<tr x-for="row in rows by k1"><td x-for="c in cells:row by k2">`; `keyFn` is a member function of the item.
+  Server-rendered sibling rows carrying the same `x-for` are **adopted in order** on first run; with zero rows the server emits a `<!--x-for-->` comment followed by one `hidden` template element
+  (carrying `x-for`) which is cloned. Rows are reconciled by key (moves keep DOM identity); a reused row whose item/index changed has its binders re-run. Duplicate keys warn once and fall back to index identity.
+  Elements with `x-for` are owned by the directive: their other `x-*` attributes are bound on the rows, with scope `{ item, index }`.
+- **`x-ref="name"`**: `ctx.ref('name').current` is the element after mount, `null` after dispose.
+
+## 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` / `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
+
+`bun test` · `bunx tsc --noEmit -p .` (`bun check` needs Bun ≥ 1.4.3) · `bun scripts/build.ts` (fails if the bundle imports React).
+
+## React islands
+
+The server paints a react-tier component as
+`<brust-island data-id="<componentId>" x-props='<json>'>…server HTML…</brust-island>`.
+The island's chunk registers its hydrate function without importing the runtime:
+
+    ;(globalThis.__brustIslands ||= []).push(['<componentId>', (host, props) => hydrateRoot(host, <Comp {...props}/>)])
+    globalThis.__brustIslandReady?.()
+
+The runtime hydrates every host once, when the browser is idle (`requestIdleCallback`, else
+`setTimeout(…, 1)`), and sets `data-hydrated="1"` on success. Load order between the runtime
+script and island chunks does not matter. Bad `x-props` JSON hydrates with `{}` and warns once;
+a hydrate that throws is reported on `console.error` and the server HTML stays. This is the only
+strategy in M2 (spec S12).
+
+## Store
+The 0.1.x `brustjs/store` API on the same reactive core the directives use (one graph, even across module copies:
+tracking state lives on `globalThis[Symbol.for('brust.reactive.ctx')]`).
+
+- `@brust/runtime-dom/store` (also the runtime entry, and `@brust/core/store`): `signal computed effect batch
+  untracked isSignal isComputed defineStore` and the types `Signal Computed Dispose StoreHandle Snapshot`.
+- `defineStore(name, factory)` returns a handle: `store.field`, `store.snapshot()`, `store.serialize()`,
+  `store.hydrate(state)`, `store.subscribe(cb)`. First factory wins per name.
+- The browser keeps one instance per name in `globalThis[Symbol.for('brust.stores')]`. The first access to a
+  name seeds it from `<script type="application/json" data-brust-store="NAME">` (lazy, once).
+- `@brust/runtime-dom/store/react` (also `@brust/core/store/react`): `useStore(store)` via
+  `useSyncExternalStore`. React is an **optional peer**, imported only by this subpath; the runtime bundle stays
+  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,6 +1,70 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.10",
+  "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"
+    },
+    "./store/react": {
+      "types": "./src/store/react.ts",
+      "default": "./src/store/react.ts"
+    },
+    "./store/internal": {
+      "types": "./src/store/internal.ts",
+      "default": "./src/store/internal.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun check",
+    "build": "bun scripts/build.ts"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.0.0",
+    "@types/bun": "^1.4.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "happy-dom": "^20.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "src"
+  ],
+  "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/core-api.ts

@@ -0,0 +1,10 @@
+// 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, walkChildren } from './directives/index'
+export type { Binder } from './directives/index'
+export { parsed, read, member, mismatch, insideRaw, RAW_SEL } from './directives/common'
+export { hooks, islandHooks } 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

@@ -0,0 +1,31 @@
+import { BINDERS, parsed, read, warnOnce } from '../core-api'
+
+// 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'])
+BINDERS.push({
+  match: (a) => a.startsWith('x-bind-'),
+  bind: ({ inst, el, attr, raw, scope }) => {
+    const name = attr.slice('x-bind-'.length)
+    if (name.startsWith('on') || name === 'srcdoc') { warnOnce(`b:${inst.name}:${name}`, `${attr} in ${inst.name} refused (use x-on-*)`); return }
+    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
+      // setAttribute: `className` is a getter-only SVGAnimatedString on SVG elements (F96a).
+      if (name === 'class') { el.setAttribute('class', 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))
+    })
+  },
+})

package/src/directives/common.ts

@@ -0,0 +1,27 @@
+import { parseValue, resolve, resolveMember, type ParsedValue, type Scope } from '../value'
+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`)
+  return p
+}
+export function read(inst: Instance, p: ParsedValue, scope: Scope, attr: string): { ok: boolean; value: unknown } {
+  const r = resolve(inst.members, p, scope)
+  if (!r.ok) warnOnce(`m:${inst.name}:${attr}:${p.path.join('.')}`, `${attr}="${p.path.join('.')}" in ${inst.name}: no such member`)
+  return r.ok ? r : { ok: false, value: undefined }
+}
+export function member(inst: Instance, p: ParsedValue, attr: string): unknown {
+  const m = resolveMember(inst.members, p)
+  if (m === undefined) warnOnce(`m:${inst.name}:${attr}:${p.path.join('.')}`, `${attr}="${p.path.join('.')}" in ${inst.name}: no such member`)
+  return m
+}
+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
+  warnOnce(`x:${inst.name}:${attr}`, `first-paint mismatch ${attr} in ${inst.name}: ${JSON.stringify(server)} vs ${JSON.stringify(client)}`)
+}

package/src/directives/for.ts

@@ -0,0 +1,84 @@
+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>()
+
+BINDERS.push({
+  match: (a) => a === 'x-for',
+  bind: ({ inst, el, attr, raw, scope }) => {
+    if (done.has(el)) return
+    const m = SYNTAX.exec(raw)
+    if (!m) { warnOnce(`for:${inst.name}:${raw}`, `x-for="${raw}" in ${inst.name}: bad syntax`); return }
+    const [, itemName, indexName, sourcePath, keyPath] = m as unknown as [string, string, string | undefined, string, string]
+    const src = parsed(inst, attr, sourcePath)!; const keyP = parsed(inst, attr, keyPath)!
+
+    // 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)
+    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')
+    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'))
+    if (!adopt.includes(el)) el.remove()
+    let firstRun = true
+
+    let rows = new Map<unknown, Element[]>()  // key -> elements (array to tolerate duplicates)
+    let order: Element[] = []
+
+    inst.effect(() => {
+      const r = read(inst, src, scope, attr); if (!r.ok) return
+      const list = Array.isArray(r.value) ? (r.value as unknown[]) : []
+      const keyFn = member(inst, keyP, attr)
+      if (typeof keyFn !== 'function') return
+      const created: Element[] = []
+      const next = new Map<unknown, Element[]>(); const nextOrder: Element[] = []
+      const seen = new Set<unknown>()
+      list.forEach((item, i) => {
+        let key = (keyFn as (x: unknown) => unknown)(item)
+        // `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()
+        if (node) {
+          // Reused row: refresh its scope and poke its tick so every binder that read the scope re-runs.
+          const rs = (node as unknown as { __scope: RowScope }).__scope
+          if (!Object.is(rs[itemName], item) || (indexName && rs[indexName] !== i)) {
+            rs[itemName] = item; if (indexName) rs[indexName] = i
+            rs.__own.set((n) => n + 1)
+          }
+        }
+        if (!node) {
+          const adopted = firstRun ? adopt.shift() : undefined
+          node = adopted ?? (template.cloneNode(true) as Element)
+          if (!adopted) created.push(node)
+          adopted?.removeAttribute('x-for')
+          const own = signal(0)
+          const outer = scope.__tick as (() => number) | undefined
+          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) }
+        }
+        ;(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 left of adopt.splice(0)) left.remove()
+      firstRun = false
+      // place in order after the anchor
+      let ref: Node = anchor
+      for (const node of nextOrder) { if (ref.nextSibling !== node) parent.insertBefore(node, ref.nextSibling); ref = node }
+      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() })
+  },
+})

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

@@ -0,0 +1,25 @@
+import { BINDERS, bindElement, walkChildren, parsed, read, hooks } from '../core-api'
+BINDERS.push({
+  match: (a) => a === 'x-if',
+  bind: ({ inst, el, attr, raw, scope }) => {
+    const p = parsed(inst, attr, raw); if (!p) return
+    const anchor = document.createComment('x-if')
+    const template = el.cloneNode(true) as Element
+    template.removeAttribute('x-if'); template.removeAttribute('hidden')
+    el.replaceWith(anchor)                 // the server-rendered element becomes the first clone below
+    let current: Element | null = null
+    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
+      }
+    })
+    inst.onCleanup(() => { current?.remove() })
+  },
+})

package/src/directives/index.ts

@@ -0,0 +1,34 @@
+import type { Instance } from '../instance'
+import type { Scope } from '../value'
+
+export type Binder = (ctx: { inst: Instance; el: Element; attr: string; raw: string; scope: Scope }) => void
+/** attribute-name prefix → binder. Exact names first, then prefixes (x-bind-, x-on-). */
+export const BINDERS: Array<{ match: (attr: string) => boolean; bind: Binder }> = []
+
+const HOST_ATTR = 'x-data'
+/** Install binders for every x-* attribute under `el` (inclusive), not descending into nested hosts. */
+export function bindHost(inst: Instance, el: Element, scope: Scope): void {
+  bindElement(inst, el, scope)
+  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
+    bindElement(inst, child, scope)
+    if (!child.hasAttribute('x-if')) walkChildren(inst, child, scope)   // x-if owns its subtree
+  }
+}
+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.
+  const structural = el.hasAttribute('x-for') ? 'x-for' : el.hasAttribute('x-if') ? 'x-if' : null
+  for (const attr of Array.from(el.attributes)) {
+    if (structural && attr.name !== structural) continue
+    if (!attr.name.startsWith('x-') || attr.name === HOST_ATTR || attr.name === 'x-props' || attr.name === 'x-props-bind') continue
+    const b = BINDERS.find((b) => b.match(attr.name))
+    if (b) b.bind({ inst, el, attr: attr.name, raw: attr.value, scope })
+  }
+}

package/src/directives/model.ts

@@ -0,0 +1,30 @@
+import { BINDERS, parsed, member, isSignal, warnOnce, type Signal } from '../core-api'
+BINDERS.push({
+  match: (a) => a === 'x-model',
+  bind: ({ inst, el, attr, raw }) => {
+    const p = parsed(inst, attr, raw); if (!p) return
+    const sig = member(inst, p, attr)
+    if (!isSignal(sig) || typeof (sig as Signal<unknown>).set !== 'function') {
+      warnOnce(`model:${inst.name}:${raw}`, `x-model="${raw}" in ${inst.name} needs a signal`); return
+    }
+    const s = sig as Signal<unknown>
+    const input = el as HTMLInputElement
+    const type = input.type
+    if (input instanceof HTMLInputElement && type === 'checkbox') {
+      const h = () => s.set(input.checked); el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
+      inst.effect(() => { input.checked = Boolean(s()) })
+    } else if (input instanceof HTMLInputElement && type === 'radio') {
+      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 ?? '') }
+      inst.effect(apply)
+      const mo = new MutationObserver(() => apply()); mo.observe(el, { childList: true }); inst.onCleanup(() => mo.disconnect())
+    } else {
+      const h = () => s.set(input.value); el.addEventListener('input', h); inst.onCleanup(() => el.removeEventListener('input', h))
+      inst.effect(() => { const v = s(); if (input.value !== String(v ?? '')) input.value = String(v ?? '') })
+    }
+  },
+})

package/src/directives/on.ts

@@ -0,0 +1,16 @@
+import { BINDERS, parsed, member } from '../core-api'
+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) => {
+      const fn = member(inst, p, attr)
+      if (typeof fn !== 'function') return
+      const args = p.bindings.map((b) => scope[b])
+      ;(fn as (...a: unknown[]) => void)(...args, e)
+    }
+    el.addEventListener(event, handler)
+    inst.onCleanup(() => el.removeEventListener(event, handler))
+  },
+})

package/src/directives/ref.ts

@@ -0,0 +1,9 @@
+import { BINDERS } 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 })
+  },
+})

package/src/directives/show.ts

@@ -0,0 +1,11 @@
+import { BINDERS, parsed, read } from '../core-api'
+BINDERS.push({
+  match: (a) => a === 'x-show',
+  bind: ({ inst, el, attr, raw, scope }) => {
+    const p = parsed(inst, attr, raw); if (!p) return
+    inst.effect(() => {
+      const r = read(inst, p, scope, attr); if (!r.ok) return
+      ;(el as HTMLElement).style.display = r.value ? '' : 'none'
+    })
+  },
+})

package/src/directives/text.ts

@@ -0,0 +1,14 @@
+import { BINDERS, parsed, read, mismatch } from '../core-api'
+BINDERS.push({
+  match: (a) => a === 'x-text',
+  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 (el.textContent !== next) { mismatch(inst, attr, el, el.textContent, next); el.textContent = next }; return }
+      el.textContent = next
+    })
+  },
+})

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/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,8 @@
+// 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'

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'

package/src/index.ts

@@ -0,0 +1,8 @@
+// The full runtime: the core plus every feature. Tests and non-split consumers import this; the browser build
+// loads `./core` and only the `./features/*` a route needs.
+export * from './core'
+export { defineStore } from './store/define-store'
+export type { StoreHandle, Snapshot } from './store/define-store'
+export { defineIsland } from './island'
+export type { IslandHydrate } from './island'
+import './features/index'