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

package/README.md

@@ -1,3 +1,94 @@
-# 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 < 17 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
+
+- **`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-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` 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.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.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"
+  }
+}

package/src/directives/bind.ts

@@ -0,0 +1,32 @@
+import { BINDERS } from './index'
+import { parsed, read } from './common'
+import { warnOnce } from '../warn'
+
+// 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
+      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))
+    })
+  },
+})

package/src/directives/common.ts

@@ -0,0 +1,23 @@
+import { parseValue, resolve, resolveMember, type ParsedValue, type Scope } from '../value'
+import { warnOnce } from '../warn'
+import type { Instance } from '../instance'
+
+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,85 @@
+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'
+
+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)
+        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/if.ts

@@ -0,0 +1,27 @@
+import { BINDERS, bindElement, walkChildren } from './index'
+import { parsed, read } from './common'
+import { hooks } from '../instance'
+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,33 @@
+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 {
+  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,33 @@
+import { BINDERS } from './index'
+import { parsed, member } from './common'
+import { isSignal, type Signal } from '../signal'
+import { warnOnce } from '../warn'
+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,17 @@
+import { BINDERS } from './index'
+import { parsed, member } from './common'
+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 './index'
+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/register.ts

@@ -0,0 +1,8 @@
+import './text'
+import './show'
+import './bind'
+import './on'
+import './if'
+import './model'
+import './for'
+import './ref'

package/src/directives/show.ts

@@ -0,0 +1,12 @@
+import { BINDERS } from './index'
+import { parsed, read } from './common'
+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,15 @@
+import { BINDERS } from './index'
+import { parsed, read, mismatch } from './common'
+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/index.ts

@@ -0,0 +1,9 @@
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
+export type { Signal, Computed, Dispose } from './signal'
+export { defineStore } from './store/define-store'
+export type { StoreHandle, Snapshot } from './store/define-store'
+export { defineBehavior, setChunkLoader } from './registry'
+export type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
+export { mount, unmount } from './mount'
+export { defineIsland } from './island'
+export type { IslandHydrate } from './island'

package/src/instance.ts

@@ -0,0 +1,56 @@
+import { effect as coreEffect, signal, type Dispose, type Signal } from './signal'
+import type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
+
+export class Instance {
+  members: BehaviorInstance = {}
+  props: Signal<Record<string, unknown>>
+  refs = new Map<string, { current: Element | null }>()
+  children = new Set<Instance>()
+  private disposers: Dispose[] = []
+  private cleanups: Array<() => void> = []
+  disposed = false
+  /** false until the initial bind pass finishes; the first-paint tripwire only applies before then. */
+  booted = false
+
+  constructor(public host: HTMLElement, public name: string, public parent: Instance | null, initialProps: Record<string, unknown>) {
+    this.props = signal(initialProps)
+    parent?.children.add(this)
+  }
+
+  effect(fn: () => void | (() => void)): Dispose {
+    const d = coreEffect(fn); this.disposers.push(d); return d
+  }
+  onCleanup(fn: () => void): void { this.cleanups.push(fn) }
+  ref<E extends Element = HTMLElement>(name: string): { current: E | null } {
+    let r = this.refs.get(name)
+    if (!r) { r = { current: null }; this.refs.set(name, r) }
+    return r as { current: E | null }
+  }
+  ctx(): BehaviorCtx {
+    return { el: this.host, props: this.props, effect: (fn) => this.effect(fn), onCleanup: (fn) => this.onCleanup(fn), ref: (n) => this.ref(n) }
+  }
+  init(factory: BehaviorFactory): void {
+    const m = factory(this.ctx())
+    if (m && typeof m === 'object') this.members = m
+    if (typeof this.members.init === 'function') (this.members.init as () => void)()
+  }
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    for (const c of Array.from(this.children)) c.dispose()
+    this.parent?.children.delete(this)
+    for (const d of this.disposers.splice(0)) d()
+    for (const c of this.cleanups.splice(0)) { try { c() } catch (e) { console.error('[brust] cleanup threw', e) } }
+  }
+}
+
+export const instances = new WeakMap<Element, Instance>()
+export function instanceOf(el: Element): Instance | undefined { return instances.get(el) }
+/** Instance of the nearest ancestor HOST. A host that has not mounted yet (chunk loading) yields null: wait, never skip to a farther ancestor. */
+export function nearestInstance(el: Element): Instance | null {
+  const h = el.parentElement?.closest('[x-data]')
+  return (h && instances.get(h)) || null
+}
+
+/** Late-bound by mount.ts so binders (x-if, x-for) can mount nested hosts synchronously without an import cycle. */
+export const hooks: { mountTree: (root: ParentNode) => void } = { mountTree: () => {} }

package/src/island.ts

@@ -0,0 +1,84 @@
+// React islands: the server paints <brust-island data-id x-props>HTML</brust-island>; the island's
+// chunk registers a hydrate function through a global queue (no import of the runtime); the runtime
+// hydrates each host once, when idle (spec S12). Load order between runtime and chunks is free.
+import { warnOnce } from './warn'
+
+export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void
+type QueueEntry = [string, IslandHydrate]
+declare global { var __brustIslands: QueueEntry[] | undefined; var __brustIslandReady: (() => void) | undefined }
+
+// One entry per island id: the hydrate fn once registered, else the callbacks waiting for it.
+const slots = new Map<string, IslandHydrate | Array<(h: IslandHydrate) => void>>()
+
+export function defineIsland(id: string, hydrate: IslandHydrate): void {
+  const w = slots.get(id)
+  slots.set(id, hydrate)
+  if (Array.isArray(w)) w.forEach((cb) => cb(hydrate))
+}
+
+/** Move every queued [id, hydrate] from the global array into the registry. Idempotent. */
+function drain(): void {
+  const q = (globalThis.__brustIslands ||= [])
+  while (q.length) defineIsland(...q.shift()!)
+  globalThis.__brustIslandReady = drain
+}
+
+export function whenIsland(id: string, cb: (h: IslandHydrate) => void): void {
+  drain()
+  const s = slots.get(id)
+  if (typeof s === 'function') cb(s)
+  else if (s) s.push(cb)
+  else slots.set(id, [cb])
+}
+
+// ---- scheduler ----------------------------------------------------------------------------
+type Idle = (cb: () => void) => void
+const defaultIdle: Idle = (cb) => {
+  const ric = (globalThis as { requestIdleCallback?: (cb: () => void) => number }).requestIdleCallback
+  if (typeof ric === 'function') ric(cb); else setTimeout(cb, 1)
+}
+let idle: Idle = defaultIdle
+export function _setIdle(fn: Idle | null): void { idle = fn ?? defaultIdle }
+
+const pending = new Set<HTMLElement>()
+
+function readIslandProps(host: HTMLElement, id: string): Record<string, unknown> {
+  const raw = host.getAttribute('x-props')
+  if (!raw) return {}
+  try { const v = JSON.parse(raw); return v && typeof v === 'object' ? v : {} }
+  catch { warnOnce(`ij:${id}:${raw.slice(0, 40)}`, `bad x-props JSON in island ${id}`); return {} }
+}
+
+function hydrateHost(host: HTMLElement, id: string, hydrate: IslandHydrate): void {
+  pending.delete(host)
+  if (!host.isConnected || host.hasAttribute('data-hydrated')) return
+  try { hydrate(host, readIslandProps(host, id)); host.setAttribute('data-hydrated', '1') }
+  catch (e) { console.error(`[brust] hydrate threw: ${id}`, e) }
+}
+
+function scheduleHost(host: HTMLElement): void {
+  if (pending.has(host) || host.hasAttribute('data-hydrated')) return
+  const id = host.getAttribute('data-id')!
+  pending.add(host)
+  whenIsland(id, (hydrate) => { if (pending.has(host)) idle(() => hydrateHost(host, id, hydrate)) })
+}
+
+/** Schedule every not-yet-hydrated island under `root` (inclusive). Called by mount() and the observer. */
+export function scheduleIslands(root: ParentNode): void {
+  if (root instanceof HTMLElement && root.tagName === 'BRUST-ISLAND' && root.hasAttribute('data-id')) scheduleHost(root)
+  root.querySelectorAll<HTMLElement>('brust-island[data-id]').forEach(scheduleHost)
+}
+
+/** Forget pending hosts under a subtree that left the document. */
+export function cancelIslands(root: Node): void {
+  if (!(root instanceof Element)) return
+  if (root instanceof HTMLElement && pending.has(root)) pending.delete(root)
+  root.querySelectorAll<HTMLElement>('brust-island[data-id]').forEach((h) => pending.delete(h))
+}
+
+/** Test helper: forget registrations, waiters, pending hosts and the global queue. */
+export function _resetIslands(): void {
+  slots.clear(); pending.clear(); idle = defaultIdle
+  globalThis.__brustIslands = []
+  globalThis.__brustIslandReady = undefined
+}

package/src/mount.ts

@@ -0,0 +1,76 @@
+import { Instance, hooks, instances, nearestInstance } from './instance'
+import { untracked } from './signal'
+import { whenBehavior } from './registry'
+import { bindHost } from './directives/index'
+import { warnOnce } from './warn'
+import { bindPropsFromParent } from './props-bind'
+import { scheduleIslands, cancelIslands } from './island'
+import './directives/register'   // Tasks 3–6 add binders here (file created in Task 3; create it empty now)
+
+let observer: MutationObserver | null = null
+
+function readProps(host: HTMLElement): Record<string, unknown> {
+  const raw = host.getAttribute('x-props')
+  if (!raw) return {}
+  try { const v = JSON.parse(raw); return v && typeof v === 'object' ? v : {} }
+  catch { warnOnce(`j:${host.outerHTML.slice(0, 80)}`, `bad x-props JSON in ${host.getAttribute('x-data')}`); return {} }
+}
+
+function mountHost(host: HTMLElement): void {
+  if (instances.has(host) || !host.isConnected) return
+  const name = host.getAttribute('x-data')!
+  whenBehavior(name, (factory) => {
+    if (instances.has(host) || !host.isConnected) return
+    const parent = nearestInstance(host)
+    const inst = new Instance(host, name, parent, readProps(host))
+    instances.set(host, inst)
+    try { inst.init(factory) } catch (e) { console.error(`[brust] init threw: ${name}`, e); inst.dispose(); instances.delete(host); return }
+    bindHost(inst, host, {})
+    inst.booted = true
+    bindPropsFromParent(inst)
+    // Children that mounted before this instance existed (parent chunk arrived late) link up now.
+    host.querySelectorAll<HTMLElement>('[x-data]').forEach((h) => {
+      const child = instances.get(h)
+      if (child && !child.parent && h.parentElement?.closest('[x-data]') === host) { child.parent = inst; inst.children.add(child); bindPropsFromParent(child) }
+    })
+  })
+}
+
+function mountTree(root: ParentNode): void {
+  const hosts: HTMLElement[] = []
+  if (root instanceof HTMLElement && root.hasAttribute('x-data')) hosts.push(root)
+  root.querySelectorAll<HTMLElement>('[x-data]').forEach((h) => hosts.push(h))
+  // document order = parents before children, so nearestInstance finds a mounted parent
+  for (const h of hosts) mountHost(h)
+  scheduleIslands(root)
+}
+hooks.mountTree = (root) => untracked(() => mountTree(root))
+
+function disposeTree(root: Node): void {
+  if (!(root instanceof Element)) return
+  cancelIslands(root)
+  const hosts: Element[] = root.hasAttribute('x-data') ? [root] : []
+  root.querySelectorAll('[x-data]').forEach((h) => hosts.push(h))
+  for (const h of hosts) { const i = instances.get(h); if (i) { i.dispose(); instances.delete(h) } }
+}
+
+export function mount(root: ParentNode = document.body): void {
+  // Observe first: binders (x-if, x-for) insert nested hosts during the initial pass.
+  if (!observer) startObserver(root); else if (root !== observedRoot) observer.observe(root, { childList: true, subtree: true })
+  mountTree(root)
+}
+let observedRoot: ParentNode | null = null
+function startObserver(root: ParentNode): void {
+  observedRoot = root
+  observer = new MutationObserver((records) => {
+    for (const r of records) {
+      r.removedNodes.forEach((n) => { if (!n.isConnected) disposeTree(n) })
+      r.addedNodes.forEach((n) => { if (n instanceof Element && n.isConnected) mountTree(n) })
+    }
+  })
+  observer.observe(root, { childList: true, subtree: true })
+}
+export function unmount(root: ParentNode = document.body): void {
+  if (root === observedRoot) { observer?.disconnect(); observer = null; observedRoot = null }
+  disposeTree(root as Node)
+}

package/src/props-bind.ts

@@ -0,0 +1,30 @@
+import type { Instance } from './instance'
+import { parseValue, resolve } from './value'
+import { warnOnce } from './warn'
+import { nearestInstance } from './instance'
+
+function scopeOf(el: Element): Record<string, unknown> {
+  let e: Element | null = el
+  while (e) { const s = (e as unknown as { __scope?: Record<string, unknown> }).__scope; if (s) return s; e = e.parentElement }
+  return {}
+}
+
+export function bindPropsFromParent(inst: Instance): void {
+  const raw = inst.host.getAttribute('x-props-bind'); if (!raw) return
+  const p = parseValue(raw)
+  if (!p) { warnOnce(`pp:${inst.name}`, `x-props-bind="${raw}" in ${inst.name}: not a member path`); return }
+  const parent = inst.parent ?? nearestInstance(inst.host)
+  if (!parent) {
+    // An unmounted ancestor host means "wait" (the parent's mount links us); only a truly parentless host is an error.
+    if (!inst.host.parentElement?.closest('[x-data]')) warnOnce(`po:${inst.name}`, `x-props-bind="${raw}" in ${inst.name}: no parent`)
+    return
+  }
+  const scope = scopeOf(inst.host)
+  inst.effect(() => {
+    const r = resolve(parent.members, p, scope)
+    if (!r.ok) { warnOnce(`pm:${inst.name}`, `x-props-bind="${raw}": no such member in ${parent.name}`); return }
+    const v = r.value
+    if (v && typeof v === 'object') inst.props.set(v as Record<string, unknown>)
+    else warnOnce(`pn:${inst.name}`, `x-props-bind="${raw}" in ${inst.name}: not an object`)
+  })
+}

package/src/registry.ts

@@ -0,0 +1,38 @@
+import type { Dispose, Signal } from './signal'
+
+export interface BehaviorCtx {
+  el: HTMLElement
+  props: Signal<Record<string, unknown>>
+  effect: (fn: () => void | (() => void)) => Dispose
+  onCleanup: (fn: () => void) => void
+  ref: <E extends Element = HTMLElement>(name: string) => { current: E | null }
+}
+export type BehaviorInstance = Record<string, unknown>
+export type BehaviorFactory = (ctx: BehaviorCtx) => BehaviorInstance | void
+
+const registry = new Map<string, BehaviorFactory>()
+const waiters = new Map<string, Array<(f: BehaviorFactory) => void>>()
+let loader: ((name: string) => Promise<unknown>) | null = null
+const requested = new Set<string>()
+
+export function defineBehavior(name: string, factory: BehaviorFactory): BehaviorFactory {
+  registry.set(name, factory)
+  const w = waiters.get(name); waiters.delete(name)
+  w?.forEach((cb) => cb(factory))
+  return factory
+}
+export function setChunkLoader(load: (name: string) => Promise<unknown>): void { loader = load; requested.clear() }
+export function getBehavior(name: string): BehaviorFactory | undefined { return registry.get(name) }
+
+/** Resolve a factory now or when its chunk arrives. Requests the chunk at most once per name. */
+export function whenBehavior(name: string, cb: (f: BehaviorFactory) => void): void {
+  const f = registry.get(name)
+  if (f) { cb(f); return }
+  const list = waiters.get(name) ?? []; list.push(cb); waiters.set(name, list)
+  if (loader && !requested.has(name)) {
+    requested.add(name)
+    loader(name).catch((e) => console.error(`[brust] chunk load failed: ${name}`, e))
+  }
+}
+/** Test helper: forget everything. */
+export function _resetRegistry(): void { registry.clear(); waiters.clear(); loader = null; requested.clear() }

package/src/signal.ts

@@ -0,0 +1,110 @@
+// A small push-pull reactive core. Signals push "dirty" to subscribers; computeds pull lazily.
+type Subscriber = { mark(): void; deps: Set<Node> }
+type Node = { subs: Set<Subscriber> }
+type Runnable = { disposed: boolean; run(): void }
+interface ReactiveCtx { currentSub: Subscriber | null; batchDepth: number; pending: Set<Runnable> }
+
+const CTX = Symbol.for('brust.reactive.ctx')          // M3-F C7
+const SIGNAL = Symbol.for('brust.signal')             // M3-F C7
+const COMPUTED = Symbol.for('brust.computed')         // M3-F C7
+// ONE object per realm. Every copy of this module binds `ctx` once at load; hot paths do one
+// property load on a module-constant object. The shape is fixed: a copy never adds fields, so
+// copies of any version agree.
+const ctx: ReactiveCtx = ((globalThis as { [CTX]?: ReactiveCtx })[CTX] ??= { currentSub: null, batchDepth: 0, pending: new Set() })
+
+function track(node: Node) {
+  const s = ctx.currentSub
+  if (s) { node.subs.add(s); s.deps.add(node) }
+}
+function notify(node: Node) {
+  for (const s of Array.from(node.subs)) s.mark()
+}
+function flush() {
+  if (ctx.batchDepth > 0) return
+  const pending = ctx.pending
+  while (pending.size) {
+    const batch = Array.from(pending); pending.clear()
+    for (const e of batch) if (!e.disposed) e.run()
+  }
+}
+
+export interface Signal<T> { (): T; set(next: T | ((prev: T) => T)): void; readonly peek: () => T; readonly [SIGNAL]: true }
+export interface Computed<T> { (): T; readonly peek: () => T; readonly [COMPUTED]: true }
+export type Dispose = () => void
+
+export function signal<T>(initial: T): Signal<T> {
+  let value = initial
+  const node: Node = { subs: new Set() }
+  const read = (() => { track(node); return value }) as Signal<T>
+  read.set = (next) => {
+    const v = typeof next === 'function' ? (next as (p: T) => T)(value) : next
+    if (Object.is(v, value)) return
+    value = v
+    notify(node)
+    flush()
+  }
+  ;(read as { peek: () => T }).peek = () => value
+  ;(read as { [SIGNAL]: true })[SIGNAL] = true
+  return read
+}
+
+export function computed<T>(fn: () => T): Computed<T> {
+  let value: T; let dirty = true
+  const node: Node = { subs: new Set() }
+  const sub: Subscriber = { deps: new Set(), mark() { if (!dirty) { dirty = true; notify(node) } } }
+  const recompute = () => {
+    for (const d of sub.deps) d.subs.delete(sub); sub.deps.clear()
+    const prev = ctx.currentSub; ctx.currentSub = sub
+    try { value = fn() } finally { ctx.currentSub = prev }
+    dirty = false
+  }
+  const read = (() => { track(node); if (dirty) recompute(); return value }) as Computed<T>
+  ;(read as { peek: () => T }).peek = () => { if (dirty) recompute(); return value }
+  ;(read as { [COMPUTED]: true })[COMPUTED] = true
+  return read
+}
+
+// Cleanups run untracked: a read inside one must not subscribe whichever effect is running around it.
+function runCleanup(c: () => void) { const prev = ctx.currentSub; ctx.currentSub = null; try { c() } finally { ctx.currentSub = prev } }
+
+class EffectImpl implements Subscriber {
+  deps = new Set<Node>(); disposed = false; cleanup: void | (() => void) = undefined
+  constructor(private fn: () => void | (() => void)) {}
+  mark() { ctx.pending.add(this) }
+  run() {
+    if (this.disposed) return
+    if (this.cleanup) { const c = this.cleanup; this.cleanup = undefined; runCleanup(c) }
+    for (const d of this.deps) d.subs.delete(this); this.deps.clear()
+    const prev = ctx.currentSub; ctx.currentSub = this
+    try { this.cleanup = this.fn() } finally { ctx.currentSub = prev }
+  }
+  dispose() {
+    if (this.disposed) return
+    this.disposed = true; ctx.pending.delete(this)
+    for (const d of this.deps) d.subs.delete(this); this.deps.clear()
+    if (this.cleanup) { const c = this.cleanup; this.cleanup = undefined; runCleanup(c) }
+  }
+}
+
+export function effect(fn: () => void | (() => void)): Dispose {
+  const e = new EffectImpl(fn)
+  e.run()
+  return () => e.dispose()
+}
+
+export function batch(fn: () => void): void {
+  ctx.batchDepth++
+  try { fn() } finally { ctx.batchDepth--; flush() }
+}
+
+export function untracked<T>(fn: () => T): T {
+  const prev = ctx.currentSub; ctx.currentSub = null
+  try { return fn() } finally { ctx.currentSub = prev }
+}
+
+export function isSignal(x: unknown): x is Signal<unknown> { return typeof x === 'function' && (x as { [SIGNAL]?: true })[SIGNAL] === true }
+export function isComputed(x: unknown): x is Computed<unknown> { return typeof x === 'function' && (x as { [COMPUTED]?: true })[COMPUTED] === true }
+/** Signal or computed: what directive paths unwrap. Internal (not in D1). */
+export function isReactive(x: unknown): x is Signal<unknown> | Computed<unknown> {
+  return typeof x === 'function' && ((x as { [SIGNAL]?: true })[SIGNAL] === true || (x as { [COMPUTED]?: true })[COMPUTED] === true)
+}

package/src/store/define-store.ts

@@ -0,0 +1,111 @@
+// defineStore (M3-F D1): the 0.1.x `brustjs/store` handle on the shared reactive core and the
+// globalThis registry. Resolution (browser registry / server resolver) lives in ./registry.
+import { type Computed, type Signal, isComputed, isSignal } from '../signal'
+import { type StoreInstanceRecord, resolveRecord } from './registry'
+
+// Unwrap a Signal/Computed to its value type; `never` if it is neither. Uses `infer` (not
+// `extends Signal<unknown>`): `Signal<T>.set(next: T)` is contravariant in T, so
+// `Signal<TeamMember[]>` is NOT assignable to `Signal<unknown>` — a concrete-`unknown` check wrongly
+// drops every typed signal key from the snapshot.
+type StoreValue<X> = X extends Signal<infer T> ? T : X extends Computed<infer T> ? T : never
+
+// Snapshot = plain-value view of a store: Signal<T>/Computed<T> → T, plain values kept as-is, action
+// functions dropped. The `[…] extends [never]` tuple wrap stops `never` from distributing.
+export type Snapshot<S> = {
+  [K in keyof S as [StoreValue<S[K]>] extends [never]
+    ? S[K] extends (...a: never[]) => unknown
+      ? never
+      : K
+    : K]: [StoreValue<S[K]>] extends [never] ? S[K] : StoreValue<S[K]>
+}
+
+// C8. `then` is reserved so a store with a signal named `then` can't make the proxy an accidental
+// thenable (await/Promise.resolve(handle) misbehaving).
+const RESERVED = new Set(['name', 'subscribe', 'snapshot', 'serialize', 'hydrate', 'then'])
+
+export interface StoreHandle<S extends object> {
+  (): S
+  readonly name: string
+  subscribe(cb: () => void): () => void
+  snapshot(): Snapshot<S>
+  serialize(): Record<string, unknown>
+  hydrate(state: Record<string, unknown>): void
+}
+
+// Each instance's signals must notify the store's subscriber set on write. After factory(), for every
+// signal property we wrap .set to also bump the version and fire the store-level subscribers (computeds
+// downstream recompute lazily; React re-reads snapshot).
+function bridgeSubscribers(instance: Record<string, unknown>, subs: Set<() => void>, version: { n: number }): void {
+  for (const key of Object.keys(instance)) {
+    const sig = instance[key]
+    if (!isSignal(sig)) continue
+    const origSet = sig.set.bind(sig)
+    sig.set = (next) => {
+      // peek, not sig(): 0.1.x read with sig(), which subscribes a running effect to the written signal.
+      const before = sig.peek()
+      origSet(next as never)
+      if (Object.is(before, sig.peek())) return
+      version.n += 1
+      for (const cb of Array.from(subs)) cb()
+    }
+  }
+}
+
+export function hydrateRecord(rec: StoreInstanceRecord, state: Record<string, unknown>): void {
+  const inst = rec.instance as Record<string, unknown>
+  for (const key of Object.keys(state)) {
+    const v = inst[key]
+    if (isSignal(v)) v.set(state[key])
+  }
+}
+
+export function defineStore<S extends object>(name: string, factory: () => S): StoreHandle<S> & S {
+  const create = (server: boolean): StoreInstanceRecord => {
+    const instance = factory() as Record<string, unknown>
+    const rec: StoreInstanceRecord = { instance, subs: new Set(), version: { n: 0 }, snap: null }
+    bridgeSubscribers(instance, rec.subs, rec.version)
+    if (server) rec.handle = handle // collectSnapshot() serializes through it
+    return rec
+  }
+  const resolve = () => resolveRecord(name, create, hydrateRecord)
+
+  const handle = (() => resolve().instance) as StoreHandle<S> & S
+  Object.defineProperty(handle, 'name', { value: name })
+  handle.subscribe = (cb) => {
+    const rec = resolve()
+    rec.subs.add(cb)
+    return () => {
+      rec.subs.delete(cb)
+    }
+  }
+  handle.snapshot = () => {
+    const rec = resolve()
+    if (rec.snap && rec.snap.version === rec.version.n) return rec.snap.value as Snapshot<S>
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(rec.instance)) {
+      const v = (rec.instance as Record<string, unknown>)[key]
+      if (isSignal(v) || isComputed(v)) out[key] = v()
+    }
+    rec.snap = { value: out, version: rec.version.n }
+    return out as Snapshot<S>
+  }
+  handle.serialize = () => {
+    const out: Record<string, unknown> = {}
+    for (const [k, s] of Object.entries(resolve().instance)) {
+      if (!isSignal(s)) continue
+      const v = s.peek()
+      if (v === undefined || typeof v === 'function') continue // spec §4
+      if (typeof v === 'bigint') throw new TypeError(`store '${name}': '${k}' holds a BigInt, which JSON cannot carry`)
+      out[k] = v
+    }
+    return out
+  }
+  handle.hydrate = (state) => hydrateRecord(resolve(), state)
+
+  return new Proxy(handle, {
+    get(target, prop, recv) {
+      if (typeof prop === 'symbol' || RESERVED.has(prop)) return Reflect.get(target, prop, recv)
+      return (resolve().instance as Record<string, unknown>)[prop]
+    },
+  })
+}

package/src/store/index.ts

@@ -0,0 +1,5 @@
+// The D1 surface, nothing else (aliasable to the runtime URL, C6)
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from '../signal'
+export type { Signal, Computed, Dispose } from '../signal'
+export { defineStore } from './define-store'
+export type { StoreHandle, Snapshot } from './define-store'

package/src/store/internal.ts

@@ -0,0 +1,5 @@
+// Server and later-wave plumbing; never documented, never aliased to the runtime URL.
+export { __setServerResolver, applyStoreSnapshot } from './registry'
+export type { ServerResolver, StoreInstanceRecord } from './registry'
+export { hydrateRecord } from './define-store'
+export { toScriptJson, storeScriptTag, parseStoreScript } from './serialize'

package/src/store/react.ts

@@ -0,0 +1,19 @@
+// React bridge (M3-F D8). React is a PEER of @brust/runtime-dom, imported only here; src/index.ts never
+// reaches this file, so the runtime bundle stays react-free (scripts/build.ts). Type-only import from
+// the core: bundling this file into an island adds no second core (ruling R2).
+import { useSyncExternalStore } from 'react'
+import type { Snapshot, StoreHandle } from './define-store'
+
+export function useStore<S extends object>(store: StoreHandle<S> & S): Snapshot<S> {
+  // An ssr island can render (renderToString) on the server OUTSIDE a request store scope; there
+  // store.snapshot() throws. Degrade to an empty snapshot for the server render so the island SSRs its
+  // factory-default markup; the client resolves the real registry instance and hydrates.
+  const serverSnapshot = (): Snapshot<S> => {
+    try {
+      return store.snapshot()
+    } catch {
+      return {} as Snapshot<S>
+    }
+  }
+  return useSyncExternalStore(store.subscribe, store.snapshot, serverSnapshot)
+}

package/src/store/registry.ts

@@ -0,0 +1,85 @@
+// Browser store registry + the server-resolver hook (M3-F D3/D6/C7).
+// The registry lives on globalThis (C7) so two copies of this module share one instance per name.
+import { parseStoreScript } from './serialize'
+
+// The resolved per-scope store record, shared by the browser registry and the server per-request
+// map. `version` bumps on every signal write so `snapshot()` returns a referentially-stable object
+// (useSyncExternalStore contract) until a change; `snap` memoizes it. `handle` is set only on
+// records created for a resolver, so collectSnapshot() can serialize a touched store.
+export interface StoreInstanceRecord {
+  instance: object
+  subs: Set<() => void>
+  version: { n: number }
+  snap: { value: Record<string, unknown>; version: number } | null
+  handle?: { serialize(): Record<string, unknown> }
+}
+
+export type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord
+
+const STORES = Symbol.for('brust.stores') // C7
+type Registry = Record<string, StoreInstanceRecord>
+
+// Module-local on purpose (as in 0.1.x): a second runtime-dom copy on the SERVER has no resolver
+// and throws loudly instead of leaking request state into a shared registry.
+let serverResolver: ServerResolver | null = null
+
+/** Installed once at worker boot by packages/brust/src/store/server-context.ts; null uninstalls (tests). */
+export function __setServerResolver(fn: ServerResolver | null): void {
+  serverResolver = fn
+}
+
+function browserRegistry(): Registry {
+  const g = globalThis as { [STORES]?: Registry }
+  return (g[STORES] ??= Object.create(null) as Registry)
+}
+
+// Attribute comparison, never a built selector: the name is not escaped for CSS.
+function seedScript(name: string): Element | null {
+  for (const el of Array.from(document.querySelectorAll('script[data-brust-store]'))) {
+    if (el.getAttribute('data-brust-store') === name) return el
+  }
+  return null
+}
+
+/**
+ * Resolution order (ruling R4): an installed resolver takes EVERY access; otherwise the browser
+ * registry when `document` exists (created, then lazily seeded from the page's script tag on the
+ * first access per name, D6); otherwise throw.
+ */
+export function resolveRecord(
+  name: string,
+  create: (server: boolean) => StoreInstanceRecord,
+  seed: (rec: StoreInstanceRecord, state: Record<string, unknown>) => void,
+): StoreInstanceRecord {
+  if (serverResolver) return serverResolver(name, () => create(true))
+  if (typeof document === 'undefined') {
+    throw new Error(`store '${name}' accessed on the server without a request scope`)
+  }
+  const reg = browserRegistry()
+  let rec = reg[name]
+  if (!rec) {
+    rec = reg[name] = create(false)
+    const el = seedScript(name)
+    if (el) seed(rec, parseStoreScript(el))
+  }
+  return rec
+}
+
+/** Apply a navigation-payload snapshot to live client stores. Reserved for the SPA wave (D9): no callers yet. */
+export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>): void {
+  const reg = (globalThis as { [STORES]?: Registry })[STORES]
+  if (!reg) return
+  for (const [name, state] of Object.entries(snap)) {
+    const entry = reg[name]
+    if (!entry) continue // not defined on the client yet: the initial-load <script> covers it
+    const inst = entry.instance as Record<string, { set?: (x: unknown) => void } | undefined>
+    for (const key of Object.keys(state)) {
+      const v = inst[key]
+      if (v && typeof v.set === 'function') v.set(state[key])
+    }
+  }
+}
+
+export function _resetStores(): void {
+  delete (globalThis as { [STORES]?: unknown })[STORES]
+}

package/src/store/serialize.ts

@@ -0,0 +1,33 @@
+// Snapshot serialization for the store (M3-F D6). JSON for embedding in a <script> TEXT node (not an
+// attribute): brust runs AutoEscape::None and a request-derived value can reach a serialized signal,
+// so escape against </script> / <!-- breakout. C4: the Rust emitter (render.rs::inject_assets_into)
+// mirrors these bytes; test 'C4 golden bytes' is the shared contract.
+
+const ESC: Record<string, string> = {
+  '<': '\\u003c',
+  '>': '\\u003e',
+  '&': '\\u0026',
+  '\u2028': '\\u2028',
+  '\u2029': '\\u2029',
+}
+
+export function toScriptJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (c) => ESC[c]!)
+}
+
+export function storeScriptTag(name: string, state: unknown): string {
+  // name comes from defineStore (developer literal), not request data; still
+  // guard the attribute against quote breakout by rejecting unexpected chars.
+  const safeName = String(name).replace(/[^a-zA-Z0-9_.:-]/g, '')
+  return `<script type="application/json" data-brust-store="${safeName}">${toScriptJson(state)}</script>`
+}
+
+export function parseStoreScript(el: { textContent: string | null }): Record<string, unknown> {
+  const text = el.textContent ?? '{}'
+  try {
+    return JSON.parse(text) as Record<string, unknown>
+  } catch (e) {
+    console.warn('[brust] store: invalid snapshot JSON', e)
+    return {}
+  }
+}

package/src/value.ts

@@ -0,0 +1,47 @@
+import { isReactive } from './signal'
+export interface ParsedValue { path: string[]; bindings: string[] }
+const IDENT = /^[A-Za-z_$][\w$]*$/
+
+export function parseValue(raw: string): ParsedValue | null {
+  const [pathPart, bindPart, ...rest] = raw.trim().split(':')
+  if (rest.length || !pathPart) return null
+  const path = pathPart.split('.')
+  if (!path.every((p) => IDENT.test(p))) return null
+  const bindings = bindPart === undefined ? [] : bindPart.split(',').map((b) => b.trim())
+  if (!bindings.every((b) => IDENT.test(b))) return null
+  return { path, bindings }
+}
+
+export type Scope = Record<string, unknown>
+
+/** Resolve a parsed directive value against instance members. Reads signals (tracked). */
+export function resolve(members: Record<string, unknown>, v: ParsedValue, scope: Scope): { ok: true; value: unknown } | { ok: false } {
+  // x-for rows expose a tick that changes when the row's item/index is refreshed; reading it subscribes.
+  const tick = scope.__tick
+  if (typeof tick === 'function') tick()
+  let cur: unknown = members
+  for (const key of v.path) {
+    if (isReactive(cur)) cur = cur()
+    if (cur === null || typeof cur !== 'object') return { ok: false }
+    if (!(key in (cur as object))) return { ok: false }
+    cur = (cur as Record<string, unknown>)[key]
+  }
+  if (v.bindings.length) {
+    if (typeof cur !== 'function') return { ok: false }
+    const args = v.bindings.map((b) => scope[b])
+    return { ok: true, value: (cur as (...a: unknown[]) => unknown)(...args) }
+  }
+  if (isReactive(cur)) cur = cur()
+  return { ok: true, value: cur }
+}
+
+/** Like resolve but returns the member itself (for handlers and x-model signals). */
+export function resolveMember(members: Record<string, unknown>, v: ParsedValue): unknown {
+  let cur: unknown = members
+  for (const key of v.path) {
+    if (isReactive(cur)) cur = cur()
+    if (cur === null || typeof cur !== 'object' || !(key in (cur as object))) return undefined
+    cur = (cur as Record<string, unknown>)[key]
+  }
+  return cur
+}

package/src/warn.ts

@@ -0,0 +1,9 @@
+const seen = new Set<string>()
+export function warnOnce(key: string, message: string): void {
+  if (seen.has(key)) return
+  seen.add(key)
+  console.warn(`[brust] ${message}`)
+}
+
+/** test-only; the browser harness calls it between cases */
+export function __resetWarnOnce(): void { seen.clear() }