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

package/src/instance.ts

@@ -0,0 +1,98 @@
+import { effect as coreEffect, signal, type Dispose, type Signal } from './signal'
+import type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
+
+/** Defined by `brust build --dev` (true) and every other build (false): the dev code below is removed from production bundles. */
+declare const __BRUST_DEV__: boolean | undefined
+/** Dev only (L14): the live instances, for the devtools (`globalThis.__brustDev.instances`). */
+function devTrack(i: Instance, on: boolean): void {
+  const g = globalThis as { __brustDev?: { instances: Set<Instance> } }
+  const dev = (g.__brustDev ??= { instances: new Set<Instance>() })
+  if (on) dev.instances.add(i)
+  else dev.instances.delete(i)
+}
+
+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
+  /** Effects the component declared while its factory ran: they start once the instance is bound (x-ref, x-on), like React's commit (F97). */
+  private pending: Array<[() => void | (() => void), Dispose?]> | null = []
+
+  constructor(public host: HTMLElement, public name: string, public parent: Instance | null, initialProps: Record<string, unknown>) {
+    this.props = signal(initialProps)
+    parent?.children.add(this)
+    if (typeof __BRUST_DEV__ !== 'undefined' && __BRUST_DEV__) devTrack(this, true)
+  }
+
+  effect(fn: () => void | (() => void)): Dispose {
+    const d = coreEffect(fn); this.disposers.push(d); return d
+  }
+  /** `ctx.effect`: deferred until `start()` while the factory runs, immediate afterwards. */
+  private componentEffect(fn: () => void | (() => void)): Dispose {
+    if (!this.pending) return this.effect(fn)
+    const q: [() => void | (() => void), Dispose?] = [fn]
+    this.pending.push(q)
+    return () => { q[0] = () => {}; q[1]?.() }
+  }
+  /**
+   * Runs the queued component effects, in declaration order. Call after the initial bind pass.
+   * Order across hosts: a static nested host mounts after its parent (document order), so a
+   * parent's effects start before the child is bound; hosts created by x-if / x-for during the
+   * parent's bind pass start their own effects first. A throwing effect is handled like a
+   * throwing factory: logged, the instance disposed; returns false then.
+   */
+  start(): boolean {
+    const queue = this.pending
+    this.pending = null
+    for (const q of queue ?? []) {
+      if (this.disposed) break
+      try { q[1] = this.effect(q[0]) }
+      catch (e) { console.error(`[brust] effect threw: ${this.name}`, e); this.dispose(); instances.delete(this.host); return false }
+    }
+    return true
+  }
+  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.componentEffect(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
+    if (typeof __BRUST_DEV__ !== 'undefined' && __BRUST_DEV__) devTrack(this, false)
+    this.pending = null   // effects not yet started never run
+    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: () => {} }
+
+/** Late-bound by the `island` feature (features/island.ts) so a page without React islands never loads the hydration glue. */
+export const islandHooks: { schedule: (root: ParentNode) => void; cancel: (root: Node) => void } = { schedule: () => {}, cancel: () => {} }

package/src/island.ts

@@ -0,0 +1,89 @@
+// 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, insideRaw } from './core-api'
+
+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
+/** Longest an island waits for an idle period. Without a timeout `requestIdleCallback` never fires while
+ *  the main thread has no idle gap (a loaded runner, a throttled or hidden tab), and an island whose host
+ *  is already painted would stay server HTML indefinitely. */
+export const IDLE_TIMEOUT_MS = 250
+const defaultIdle: Idle = (cb) => {
+  const ric = (globalThis as { requestIdleCallback?: (cb: () => void, opts?: { timeout: number }) => number }).requestIdleCallback
+  if (typeof ric === 'function') ric(cb, { timeout: IDLE_TIMEOUT_MS }); 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 (insideRaw(host)) return   // inside dangerouslySetInnerHTML markup: never hydrated
+  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, islandHooks, nearestInstance } from './instance'
+import { untracked } from './signal'
+import { whenBehavior } from './registry'
+import { bindHost } from './directives/index'
+import { insideRaw } from './directives/common'
+import { warnOnce } from './warn'
+import { bindPropsFromParent } from './props-bind'
+
+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
+    if (!inst.start()) return   // F97: refs and handlers are bound; now the component's effects
+    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) if (!insideRaw(h)) mountHost(h)
+  islandHooks.schedule(root)
+}
+hooks.mountTree = (root) => untracked(() => mountTree(root))
+
+function disposeTree(root: Node): void {
+  if (!(root instanceof Element)) return
+  islandHooks.cancel(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)
+  try { e.run() } catch (x) { e.dispose(); throw x }   // F98: a first run that throws must not stay subscribed
+  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,106 @@
+// 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, isSignal } from '../core-api'
+import { type StoreInstanceRecord, computeSnapshot, 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()
+    return computeSnapshot(rec) as Snapshot<S>
+  }
+  // The snapshot the SSR HTML was rendered from (browser); React islands hydrate against it. Absent on the server.
+  ;(handle as unknown as Record<symbol, unknown>)[Symbol.for('brust.ssrSnapshot')] = () => resolve().ssr ?? handle.snapshot()
+  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,21 @@
+// 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 {
+      // Hydration must see the markup the server rendered, not a value a native mount effect wrote since (#418).
+      const ssr = (store as unknown as Record<symbol, (() => Snapshot<S>) | undefined>)[Symbol.for('brust.ssrSnapshot')]
+      return ssr ? ssr() : store.snapshot()
+    } catch {
+      return {} as Snapshot<S>
+    }
+  }
+  return useSyncExternalStore(store.subscribe, store.snapshot, serverSnapshot)
+}