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

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>>
@@ -8,26 +18,71 @@ export class Instance {
   children = new Set<Instance>()
   private disposers: Dispose[] = []
   private cleanups: Array<() => void> = []
+  /** F415: while an `x-if` branch or an `x-for` row binds, what it registers is owned by that part (`capture`). */
+  private sink: Array<() => void> | null = null
   disposed = false
   /** false until the initial bind pass finishes; the first-paint tripwire only applies before then. */
   booted = false
+  /** Mounted after the page booted: nothing of it was in the server markup (`BehaviorCtx.late`). */
+  late = false
+  /** F277: started from props other than the ones its markup was printed with (a host an `x-if` or a row created after
+   * first paint, linked to its parent's current value): its first bind is not a first paint, so no tripwire. */
+  reseeded = 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?, number?]> | 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
+  effect(fn: () => void | (() => void), tier = 0): Dispose {
+    const d = coreEffect(fn, tier); (this.sink ?? this.disposers).push(d); return d
+  }
+  /** `ctx.effect`: deferred until `start()` while the factory runs, immediate afterwards. A compiled effect re-runs after
+   * the bindings: layout (`layout` true) before passive (F288, ruling 94404307 amended). */
+  private componentEffect(fn: () => void | (() => void), layout = false): Dispose {
+    const tier = layout ? 1 : 2
+    if (!this.pending) return this.effect(fn, tier)
+    const q: [() => void | (() => void), Dispose?, number?] = [fn, undefined, tier]
+    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], q[2]) }
+      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.sink ?? this.cleanups).push(fn) }
+  /** F415/F416: runs `fn` with the effects and cleanups it registers owned by the returned disposer, which an `x-if`
+   * branch or an `x-for` row runs when it is removed: its effects stop and its cleanups run (an `x-ref` lets go of the
+   * node), in the order they were registered. */
+  capture(fn: () => void): () => void {
+    const prev = this.sink; const own: Array<() => void> = (this.sink = [])
+    try { fn() } finally { this.sink = prev }
+    return () => runCleanups(own)
   }
-  onCleanup(fn: () => void): void { this.cleanups.push(fn) }
-  ref<E extends Element = HTMLElement>(name: string): { current: E | null } {
+  ref<E extends Element = HTMLElement>(name: string, init?: unknown): { current: E | null } {
     let r = this.refs.get(name)
-    if (!r) { r = { current: null }; this.refs.set(name, r) }
+    // `useRef(init)`: the cell starts at `init`; an `x-ref` element replaces it when it binds (React attaches the same way).
+    if (!r) { r = { current: (init ?? null) as Element | 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) }
+    return { el: this.host, props: this.props, effect: (fn, layout) => this.componentEffect(fn, layout), onCleanup: (fn) => this.onCleanup(fn), ref: (n, init) => this.ref(n, init), late: this.late, items: () => collectionHooks.items(this.host) }
   }
   init(factory: BehaviorFactory): void {
     const m = factory(this.ctx())
@@ -37,13 +92,19 @@ 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()
-    for (const c of this.cleanups.splice(0)) { try { c() } catch (e) { console.error('[brust] cleanup threw', e) } }
+    runCleanups(this.cleanups)
   }
 }
 
+function runCleanups(list: Array<() => void>): void {
+  for (const c of list.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. */
@@ -54,3 +115,11 @@ 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: () => {} }
+
+/** One item of a collection (R34.141): the data its host handed over, the element, and `ref.current` (Radix's item shape). */
+export type CollectionItem = { ref: { current: Element }; element: Element } & Record<string, unknown>
+/** Late-bound by the `collection` feature (features/collection.ts): `ctx.items()` is a no-op list until it loads. */
+export const collectionHooks: { items: (from: Element) => CollectionItem[] } = { items: () => [] }
+
+/** 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,9 +1,11 @@
 // 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
+/** Hydrates `host`. It may return a dispose function (the React shim returns `() => root.unmount()`): the runtime
+ *  calls it once, when the host leaves the document, so effects clean up like a React route change. */
+export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void | (() => void)
 type QueueEntry = [string, IslandHydrate]
 declare global { var __brustIslands: QueueEntry[] | undefined; var __brustIslandReady: (() => void) | undefined }
 
@@ -33,14 +35,20 @@ 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 }
 
 const pending = new Set<HTMLElement>()
+/** Dispose functions of hydrated hosts, until the host leaves the document. */
+const live = new Map<HTMLElement, () => void>()
 
 function readIslandProps(host: HTMLElement, id: string): Record<string, unknown> {
   const raw = host.getAttribute('x-props')
@@ -52,11 +60,16 @@ function readIslandProps(host: HTMLElement, id: string): Record<string, unknown>
 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') }
+  try {
+    const dispose = hydrate(host, readIslandProps(host, id))
+    if (typeof dispose === 'function') live.set(host, dispose)
+    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)
@@ -69,16 +82,24 @@ export function scheduleIslands(root: ParentNode): void {
   root.querySelectorAll<HTMLElement>('brust-island[data-id]').forEach(scheduleHost)
 }
 
-/** Forget pending hosts under a subtree that left the document. */
+/** A subtree left the document: forget its pending hosts and unmount the roots of its hydrated ones. */
 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))
+  const hosts = root.querySelectorAll<HTMLElement>('brust-island[data-id]')
+  const forget = (h: HTMLElement) => {
+    pending.delete(h)
+    const dispose = live.get(h)
+    if (!dispose) return
+    live.delete(h)
+    try { dispose() } catch (e) { console.error('[brust] island unmount threw', e) }
+  }
+  if (root instanceof HTMLElement) forget(root)
+  hosts.forEach(forget)
 }
 
 /** Test helper: forget registrations, waiters, pending hosts and the global queue. */
 export function _resetIslands(): void {
-  slots.clear(); pending.clear(); idle = defaultIdle
+  slots.clear(); pending.clear(); live.clear(); idle = defaultIdle
   globalThis.__brustIslands = []
   globalThis.__brustIslandReady = undefined
 }

package/src/mount.ts

@@ -1,13 +1,16 @@
-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)
+import { bindPropsFromParent, initialProps } from './props-bind'
 
 let observer: MutationObserver | null = null
+/** True once the first `mount()` pass has run: a host that mounts after it is `late`. */
+let pageBooted = false
+/** > 0 while a binder (x-if, x-for) mounts the hosts of a clone it just created: nothing of them was server-rendered. */
+let cloning = 0
 
 function readProps(host: HTMLElement): Record<string, unknown> {
   const raw = host.getAttribute('x-props')
@@ -16,17 +19,31 @@ function readProps(host: HTMLElement): Record<string, unknown> {
   catch { warnOnce(`j:${host.outerHTML.slice(0, 80)}`, `bad x-props JSON in ${host.getAttribute('x-data')}`); return {} }
 }
 
+function sameJson(a: unknown, b: unknown): boolean {
+  try { return JSON.stringify(a) === JSON.stringify(b) } catch { return false }
+}
+
 function mountHost(host: HTMLElement): void {
   if (instances.has(host) || !host.isConnected) return
   const name = host.getAttribute('x-data')!
+  // decided now, not when a lazy chunk arrives: a server-rendered host stays hydrated however late its code loads
+  const late = pageBooted
+  const cloned = cloning > 0
   whenBehavior(name, (factory) => {
     if (instances.has(host) || !host.isConnected) return
     const parent = nearestInstance(host)
-    const inst = new Instance(host, name, parent, readProps(host))
+    const printed = readProps(host)
+    const props = initialProps(host, parent, printed)
+    const inst = new Instance(host, name, parent, props)
+    inst.reseeded = props !== printed && !sameJson(props, printed)
+    inst.late = late
+    // a clone made by a binder has no server markup to compare its first paint with (a navigation's content has)
+    inst.booted = cloned
     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) => {
@@ -41,14 +58,18 @@ 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))
+hooks.mountTree = (root) =>
+  untracked(() => {
+    cloning++
+    try { mountTree(root) } finally { cloning-- }
+  })
 
 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) } }
@@ -58,6 +79,7 @@ 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)
+  pageBooted = true
 }
 let observedRoot: ParentNode | null = null
 function startObserver(root: ParentNode): void {
@@ -71,6 +93,6 @@ function startObserver(root: ParentNode): void {
   observer.observe(root, { childList: true, subtree: true })
 }
 export function unmount(root: ParentNode = document.body): void {
-  if (root === observedRoot) { observer?.disconnect(); observer = null; observedRoot = null }
+  if (root === observedRoot) { observer?.disconnect(); observer = null; observedRoot = null; pageBooted = false }   // torn down: the next mount() is a fresh boot
   disposeTree(root as Node)
 }

package/src/nav/chain.ts

@@ -0,0 +1,57 @@
+// The layout chain of a brust document (design §5.9): the root level from the nav tag's `data-brust-root`, then the
+// `<!--brust-l:<id>:<hash>-->…<!--/brust-l:<id>-->` pairs the server wraps around every inner level, outermost first.
+
+/** One level: `key` is `<id>:<shellHash>`; an inner level has its two comments. */
+export interface Level { key: string; open?: Comment; close?: Comment }
+
+/** null when the document has no usable chain (no root, unbalanced, crossing or sibling pairs): swap the whole body. */
+export function readChain(doc: Document): Level[] | null {
+  const root = doc.querySelector('script[data-brust-nav]')?.getAttribute('data-brust-root')
+  if (!root || !doc.body) return null
+  const out: Level[] = [{ key: root }]
+  const open: Level[] = []
+  const w = doc.createTreeWalker(doc.body, 128 /* NodeFilter.SHOW_COMMENT */)
+  for (let n: Node | null; (n = w.nextNode()); ) {
+    const v = (n as Comment).data
+    if (v.startsWith('brust-l:')) {
+      // a level opens inside the deepest open one, never beside a closed one: the chain is a line
+      if (open.length !== out.length - 1) return null
+      const l: Level = { key: v.slice(8), open: n as Comment }
+      out.push(l)
+      open.push(l)
+    } else if (v.startsWith('/brust-l:')) {
+      const l = open.pop()
+      if (!l || l.key.slice(0, l.key.lastIndexOf(':')) !== v.slice(9)) return null
+      l.close = n as Comment
+    }
+  }
+  return open.length ? null : out
+}
+
+/**
+ * A pair can be a range only when the parser kept its two comments siblings (a block in a `<p>` splits them), and not
+ * in a table section: there the comments stay put while the parser moves the content out in front of the table
+ * (foster parenting), so the range would hold nothing of the level.
+ */
+const usable = (l: Level) => l.open!.parentNode === l.close!.parentNode && !/^T(ABLE|BODY|HEAD|FOOT|R)$/.test(l.open!.parentNode!.nodeName)
+
+/**
+ * The level to replace: the first one whose id or hash differs, else the page (never kept), moved up while its pair is
+ * not a sibling pair in either document. 0 = the whole body.
+ */
+export function swapLevel(a: Level[] | null, b: Level[] | null): number {
+  if (!a || !b || a[0]!.key !== b[0]!.key) return 0
+  const leaf = Math.min(a.length, b.length) - 1
+  let i = 1
+  while (i < leaf && a[i]!.key === b[i]!.key) i++
+  if (i > leaf) return 0
+  while (i && !(usable(a[i]!) && usable(b[i]!))) i--
+  return i
+}
+
+/** The nodes of a level's range, both comments included. */
+export function between(l: Level): ChildNode[] {
+  const out: ChildNode[] = []
+  for (let n: ChildNode | null = l.open!; n; n = n === l.close ? null : n.nextSibling) out.push(n)
+  return out
+}

package/src/nav/index.ts

@@ -0,0 +1,5 @@
+// The `nav` asset (design §5.8): SPA navigation on every full brust document, also on a page that loads no runtime.
+// Standalone: nothing under nav/ imports the runtime core. `navigate()` reaches it through `Symbol.for('brust.nav')`.
+import { boot } from './nav'
+
+boot()