@brust/runtime-dom 2.0.0-alpha.1 → 2.0.0-alpha.10

package/README.md

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

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "2.0.0-alpha.1",
+  "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"
@@ -49,5 +57,14 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "homepage": "https://brust.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git",
+    "directory": "packages/runtime-dom"
+  },
+  "bugs": {
+    "url": "https://github.com/AssetsArt/brust/issues"
   }
 }

package/src/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

@@ -1,6 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read } from './common'
-import { warnOnce } from '../warn'
+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'])
@@ -16,7 +14,8 @@ BINDERS.push({
     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 }
+      // 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)

package/src/directives/common.ts

@@ -2,6 +2,10 @@ import { parseValue, resolve, resolveMember, type ParsedValue, type Scope } from
 import { warnOnce } from '../warn'
 import type { Instance } from '../instance'
 
+/** Markup inside a `dangerouslySetInnerHTML` element (`x-html` / `x-raw`, compiler-emitted) or a React island is inert: nothing under it is bound, mounted or hydrated. */
+export const RAW_SEL = '[x-html],[x-raw],brust-island'
+export const insideRaw = (el: Element): boolean => !!el.parentElement?.closest(RAW_SEL)
+
 export function parsed(inst: Instance, attr: string, raw: string): ParsedValue | null {
   const p = parseValue(raw)
   if (!p) warnOnce(`p:${inst.name}:${attr}:${raw}`, `${attr}="${raw}" in ${inst.name}: not a member path`)

package/src/directives/for.ts

@@ -1,8 +1,4 @@
-import { BINDERS, bindElement, walkChildren } from './index'
-import { parsed, read, member } from './common'
-import { warnOnce } from '../warn'
-import { computed, signal, type Signal } from '../signal'
-import { hooks } from '../instance'
+import { BINDERS, bindElement, walkChildren, parsed, read, member, warnOnce, computed, signal, hooks, type Signal } from '../core-api'
 
 type RowScope = Record<string, unknown> & { __own: Signal<number> }
 
@@ -44,7 +40,10 @@ BINDERS.push({
       const seen = new Set<unknown>()
       list.forEach((item, i) => {
         let key = (keyFn as (x: unknown) => unknown)(item)
-        if (seen.has(key)) { warnOnce(`fd:${inst.name}:${raw}`, `x-for in ${inst.name}: duplicate key ${JSON.stringify(key)}`); key = `__dup_${i}` }
+        // `undefined` is a row whose element arm is null (`it.link && <li key={it.link.id}/>`): it
+        // carries no key in React either, so it is positional and never a duplicate.
+        if (key === undefined) key = `__nil_${i}`
+        else if (seen.has(key)) { warnOnce(`fd:${inst.name}:${raw}`, `x-for in ${inst.name}: duplicate key ${JSON.stringify(key)}`); key = `__dup_${i}` }
         seen.add(key)
         const pool = rows.get(key)
         let node = pool?.shift()

package/src/directives/html.ts

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

package/src/directives/if.ts

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

package/src/directives/index.ts

@@ -12,6 +12,7 @@ export function bindHost(inst: Instance, el: Element, scope: Scope): void {
   walkChildren(inst, el, scope)
 }
 export function walkChildren(inst: Instance, el: Element, scope: Scope): void {
+  if (el.hasAttribute('x-html') || el.hasAttribute('x-raw') || el.localName === 'brust-island') return   // raw markup / React island: inert
   for (const child of Array.from(el.children)) {
     if ('__scope' in child) continue                          // x-for row: already bound with its own scope
     if (child.hasAttribute('x-for')) { bindElement(inst, child, scope); continue } // x-for owns the element (even when it is also a host)

package/src/directives/model.ts

@@ -1,7 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, member } from './common'
-import { isSignal, type Signal } from '../signal'
-import { warnOnce } from '../warn'
+import { BINDERS, parsed, member, isSignal, warnOnce, type Signal } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-model',
   bind: ({ inst, el, attr, raw }) => {

package/src/directives/on.ts

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

package/src/directives/ref.ts

@@ -1,4 +1,4 @@
-import { BINDERS } from './index'
+import { BINDERS } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-ref',
   bind: ({ inst, el, raw }) => {

package/src/directives/show.ts

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

package/src/directives/text.ts

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

package/src/features/basics.ts

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

package/src/features/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

@@ -1,9 +1,8 @@
-export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
-export type { Signal, Computed, Dispose } from './signal'
+// 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 { 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'
+import './features/index'

package/src/instance.ts

@@ -1,6 +1,16 @@
 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>>
@@ -11,15 +21,42 @@ export class Instance {
   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)
@@ -27,7 +64,7 @@ export class Instance {
     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) }
+    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())
@@ -37,6 +74,8 @@ export class Instance {
   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()
@@ -54,3 +93,6 @@ export function nearestInstance(el: Element): Instance | 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

@@ -1,7 +1,7 @@
 // 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'
+import { warnOnce, insideRaw } from './core-api'
 
 export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void
 type QueueEntry = [string, IslandHydrate]
@@ -33,9 +33,13 @@ export function whenIsland(id: string, cb: (h: IslandHydrate) => void): void {
 
 // ---- 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) => number }).requestIdleCallback
-  if (typeof ric === 'function') ric(cb); else setTimeout(cb, 1)
+  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 }
@@ -57,6 +61,7 @@ function hydrateHost(host: HTMLElement, id: string, hydrate: IslandHydrate): voi
 }
 
 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)

package/src/mount.ts

@@ -1,11 +1,10 @@
-import { Instance, hooks, instances, nearestInstance } from './instance'
+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'
-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
 
@@ -27,6 +26,7 @@ function mountHost(host: HTMLElement): void {
     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) => {
@@ -41,14 +41,14 @@ function mountTree(root: ParentNode): void {
   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)
+  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
-  cancelIslands(root)
+  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) } }

package/src/signal.ts

@@ -88,7 +88,7 @@ class EffectImpl implements Subscriber {
 
 export function effect(fn: () => void | (() => void)): Dispose {
   const e = new EffectImpl(fn)
-  e.run()
+  try { e.run() } catch (x) { e.dispose(); throw x }   // F98: a first run that throws must not stay subscribed
   return () => e.dispose()
 }
 

package/src/store/define-store.ts

@@ -1,7 +1,7 @@
 // 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'
+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
@@ -80,15 +80,10 @@ export function defineStore<S extends object>(name: string, factory: () => S): S
   }
   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>
+    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)) {

package/src/store/react.ts

@@ -10,7 +10,9 @@ export function useStore<S extends object>(store: StoreHandle<S> & S): Snapshot<
   // factory-default markup; the client resolves the real registry instance and hydrates.
   const serverSnapshot = (): Snapshot<S> => {
     try {
-      return store.snapshot()
+      // 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>
     }

package/src/store/registry.ts

@@ -1,5 +1,6 @@
 // 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 { isComputed, isSignal, untracked } from '../core-api'
 import { parseStoreScript } from './serialize'
 
 // The resolved per-scope store record, shared by the browser registry and the server per-request
@@ -11,9 +12,23 @@ export interface StoreInstanceRecord {
   subs: Set<() => void>
   version: { n: number }
   snap: { value: Record<string, unknown>; version: number } | null
+  /** Browser only: the snapshot the SSR HTML was rendered from (script seed applied, nothing written since). Islands hydrate against it (G13). */
+  ssr?: Record<string, unknown>
   handle?: { serialize(): Record<string, unknown> }
 }
 
+/** Plain-value view of a record (signals and computeds read, actions dropped), memoized in `rec.snap` per version. */
+export function computeSnapshot(rec: StoreInstanceRecord): Record<string, unknown> {
+  if (rec.snap && rec.snap.version === rec.version.n) return rec.snap.value
+  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
+}
+
 export type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord
 
 const STORES = Symbol.for('brust.stores') // C7
@@ -58,9 +73,11 @@ export function resolveRecord(
   const reg = browserRegistry()
   let rec = reg[name]
   if (!rec) {
-    rec = reg[name] = create(false)
+    const made = (rec = reg[name] = create(false))
     const el = seedScript(name)
     if (el) seed(rec, parseStoreScript(el))
+    // Identity-stable: the same object stays `rec.snap` until the first write.
+    rec.ssr = untracked(() => computeSnapshot(made)) // a first access inside an effect must not subscribe it
   }
   return rec
 }
@@ -77,6 +94,7 @@ export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>
       const v = inst[key]
       if (v && typeof v.set === 'function') v.set(state[key])
     }
+    entry.ssr = untracked(() => computeSnapshot(entry)) // R11.1: the payload is the new server truth for islands hydrating later
   }
 }
 

package/src/directives/register.ts

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