brustjs 0.1.50-alpha → 0.1.51-alpha

package/runtime/native/runtime.ts

@@ -50,7 +50,9 @@ export function register(name: string, behavior: Behavior): void {
 /** Scan `root` (default: document) for [x-data], mount each, and (once) attach a
  * MutationObserver for dynamic mount/dispose. Idempotent. NOTE: `root` scopes the
  * INITIAL scan only; the observer always watches the global `document.body` (one
- * observer per document handles every later mount/dispose, incl. SPA-nav swaps). */
+ * observer per document handles every later mount/dispose, incl. SPA-nav swaps),
+ * plus one observer per discovered OPEN shadow root (a body observer cannot see
+ * mutations inside a shadow tree). */
 export function start(root?: ParentNode): void {
   const scope: ParentNode | undefined =
     root ?? (typeof document !== 'undefined' ? document : undefined)
@@ -59,7 +61,7 @@ export function start(root?: ParentNode): void {
     scanAndMount(scope)
     if (!started) {
       started = true
-      observe()
+      if (typeof document !== 'undefined' && document.body) observeRoot(document.body)
     }
   }
   if (typeof document !== 'undefined' && document.readyState === 'loading') {
@@ -74,10 +76,28 @@ function scanAndMount(scope: ParentNode): void {
   for (const el of Array.from(scope.querySelectorAll<HTMLElement>('[x-data]'))) {
     mountElement(el)
   }
+  // R10 — OPEN shadow roots host their own component trees: scan each the same
+  // way (the recursion covers roots nested within roots) and attach an observer
+  // per root, since neither the body observer nor an outer root's observer sees
+  // mutations inside an inner shadow tree. Closed roots expose `shadowRoot ===
+  // null` and are unreachable by design. The walk-all is per added subtree only.
+  if (scope instanceof HTMLElement && scope.shadowRoot) scanShadowRoot(scope.shadowRoot)
+  for (const el of Array.from(scope.querySelectorAll<HTMLElement>('*'))) {
+    if (el.shadowRoot) scanShadowRoot(el.shadowRoot)
+  }
+}
+
+function scanShadowRoot(root: ShadowRoot): void {
+  scanAndMount(root)
+  observeRoot(root)
 }
 
 function mountElement(el: HTMLElement): void {
   if (mounted.has(el)) return
+  // Removed mid-scan (e.g. an initial-falsy x-if subtree pruned while scanAndMount's
+  // snapshot loop was still iterating): mounting a detached element would leak its
+  // effects forever — the MutationObserver never saw it removed.
+  if (!el.isConnected) return
   const name = el.getAttribute('x-data') ?? ''
   const behavior = registry.get(name)
   if (!behavior) {
@@ -154,12 +174,27 @@ function loadBehavior(name: string): void {
 }
 
 // Bind this element's directives, then recurse — but never descend into a nested
-// [x-data] (it owns its own subtree and is mounted independently).
+// [x-data] (it owns its own subtree and is mounted independently). bindTree also
+// does NOT descend into shadow roots of elements inside an x-data subtree: a
+// shadow root is its own composition boundary — its x-data components mount
+// independently via scanAndMount's shadow-root scan (R10), never inheriting the
+// enclosing instance's scope. (The `el.children` walk below naturally excludes
+// shadow content; this is by design, not an accident.)
 function bindTree(el: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+  // Coexistence check MUST precede the x-for early-exit, else x-for preempts and the
+  // warn never fires. Strip x-if so x-for's template clones don't carry it either.
+  if (el.hasAttribute('x-if') && el.hasAttribute('x-for')) {
+    console.warn('[brust] x-if and x-for on the same element — x-if ignored; nest it instead')
+    el.removeAttribute('x-if')
+  }
   if (el.hasAttribute('x-for')) {
     bindFor(el, instance, disposers)
     return
   }
+  if (el.hasAttribute('x-if')) {
+    bindIf(el, instance, disposers)
+    return
+  }
   bindAttrs(el, instance, disposers)
   for (const child of Array.from(el.children)) {
     if (!(child instanceof HTMLElement)) continue
@@ -475,11 +510,162 @@ function bindForAdopt(
   installKeyedReconcile(instance, parent, expr, template, anchor, map, disposers)
 }
 
+/** `x-if="path"` — conditional MOUNT/UNMOUNT (vs x-show's display toggle). A comment
+ * anchor marks the position; the element is captured as a template BEFORE the initial
+ * evaluation. Truthy-initial ADOPTS the original in place (no re-clone — SSR markup
+ * kept); falsy removes it. Each later falsy→truthy inserts a FRESH clone bound with
+ * fresh per-clone disposers (the installKeyedReconcile pattern); truthy→falsy removes
+ * the node and runs those disposers. The per-clone disposers cover only non-x-data
+ * teardown (bindTree skips nested x-data); nested x-data dispose/mount is delegated
+ * to the MutationObserver on removal/insert — single-owner discipline. */
+function bindIf(el: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+  const path = el.getAttribute('x-if') ?? ''
+  const parent = el.parentNode
+  if (!parent) return
+  const anchor = el.ownerDocument.createComment('x-if')
+  parent.insertBefore(anchor, el)
+  el.removeAttribute('x-if')
+  const template = el.cloneNode(true) as HTMLElement // capture FIRST (before initial effect)
+  let current: HTMLElement | null = el // the original, adopted if initially truthy
+  let bound = false // original starts unbound; clones are bound at creation
+  const currentDisposers: Array<() => void> = []
+  const teardown = () => {
+    for (const d of currentDisposers.splice(0)) {
+      try {
+        d()
+      } catch {
+        // keep tearing down
+      }
+    }
+    if (current) {
+      current.remove() // nested x-data disposal delegated to the observer's disposeTree
+      current = null
+    }
+  }
+  disposers.push(
+    effect(() => {
+      const truthy = Boolean(read(instance, path))
+      if (!truthy) {
+        teardown()
+        return
+      }
+      if (current) {
+        if (!bound) {
+          // initial truthy: adopt the original in place, no re-clone
+          bindTree(current, instance, currentDisposers)
+          bound = true
+        }
+        return
+      }
+      const clone = template.cloneNode(true) as HTMLElement
+      bindTree(clone, instance, currentDisposers) // bind BEFORE insert (observer mounts nested x-data after)
+      anchor.parentNode?.insertBefore(clone, anchor.nextSibling)
+      current = clone
+      bound = true
+    }),
+  )
+  disposers.push(teardown)
+}
+
+// x-model targets that already warned "not a signal" — warn once per path, then skip.
+const warnedModelPaths = new Set<string>()
+
+/** Write `value` into the signal at `path`, unwrapping intermediate signal/computed
+ * hops like `read()` (resolveRaw does NOT unwrap intermediates and cannot be the base
+ * for multi-hop paths). The LEAF is never called: `isSignal(leaf)` → `.set(value)`,
+ * else warn once and skip. */
+export function writePath(scope: Instance, path: string, value: unknown): void {
+  const parts = path.split('.')
+  let cur: unknown = scope
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur == null) break
+    if (isSignal(cur) || isComputed(cur)) cur = (cur as () => unknown)()
+    cur = (cur as Record<string, unknown>)[parts[i] as string]
+  }
+  let leaf: unknown
+  if (cur != null) {
+    if (isSignal(cur) || isComputed(cur)) cur = (cur as () => unknown)()
+    leaf = (cur as Record<string, unknown>)[parts[parts.length - 1] as string]
+  }
+  if (isSignal(leaf)) {
+    ;(leaf as Signal<unknown>).set(value)
+    return
+  }
+  if (!warnedModelPaths.has(path)) {
+    warnedModelPaths.add(path)
+    console.warn(`[brust] x-model target "${path}" is not a signal — write skipped`)
+  }
+}
+
+/** `x-model="path"` — two-way binding for form controls. Write side: checkbox/radio
+ * on 'change' (checkbox → boolean checked; radio → its value when checked), everything
+ * else (text/textarea/select-single/other inputs) → string value on 'input'. Read side:
+ * one reflect effect per element with an echo guard (`el.value !== v`/`el.checked !== v`)
+ * so a reflected write never loops (signal.set with an equal value is a no-op anyway).
+ * `select[multiple]` is rejected at bind time with one warn — no listener. */
+function bindModel(
+  el: HTMLElement,
+  scope: Instance,
+  path: string,
+  disposers: Array<() => void>,
+): void {
+  if (el.tagName === 'SELECT' && (el as HTMLSelectElement).multiple) {
+    console.warn('[brust] x-model on select[multiple] is not supported — binding skipped')
+    return
+  }
+  const input = el as HTMLInputElement
+  const type = el.tagName === 'INPUT' ? (input.type ?? '').toLowerCase() : ''
+  if (type === 'checkbox') {
+    const onChange = () => writePath(scope, path, input.checked)
+    el.addEventListener('change', onChange)
+    disposers.push(() => el.removeEventListener('change', onChange))
+    disposers.push(
+      effect(() => {
+        const v = Boolean(read(scope, path))
+        if (input.checked !== v) input.checked = v
+      }),
+    )
+    return
+  }
+  if (type === 'radio') {
+    const onChange = () => {
+      if (input.checked) writePath(scope, path, input.value)
+    }
+    el.addEventListener('change', onChange)
+    disposers.push(() => el.removeEventListener('change', onChange))
+    // Per-radio reflect: checked = (signalValue === el.value) — group consistency
+    // falls out naturally, no special-casing.
+    disposers.push(
+      effect(() => {
+        const on = read(scope, path) === input.value
+        if (input.checked !== on) input.checked = on
+      }),
+    )
+    return
+  }
+  // text/textarea/select(single)/other inputs → string value on 'input'
+  const valueEl = el as unknown as { value: string }
+  const onInput = () => writePath(scope, path, valueEl.value)
+  el.addEventListener('input', onInput)
+  disposers.push(() => el.removeEventListener('input', onInput))
+  disposers.push(
+    effect(() => {
+      const v = read(scope, path)
+      const s = v == null ? '' : String(v)
+      if (valueEl.value !== s) valueEl.value = s
+    }),
+  )
+}
+
 function bindAttrs(el: HTMLElement, scope: Instance, disposers: Array<() => void>): void {
   for (const attr of Array.from(el.attributes)) {
     const name = attr.name
     const value = attr.value
     if (name === 'x-data' || name === 'x-props') continue
+    if (name === 'x-model') {
+      bindModel(el, scope, value, disposers)
+      continue
+    }
     if (name === 'x-text') {
       disposers.push(
         effect(() => {
@@ -515,9 +701,20 @@ function bindAttrs(el: HTMLElement, scope: Instance, disposers: Array<() => void
   }
 }
 
-function observe(): void {
-  if (typeof MutationObserver === 'undefined' || typeof document === 'undefined') return
-  if (!document.body) return // nothing to observe yet (called pre-<body>); start() re-runs on DOMContentLoaded
+// Roots that already have a mount/dispose observer attached (document.body +
+// every discovered open shadow root). A WeakSet so a removed shadow root stays
+// GC-collectable — its observer dies with it.
+const observedRoots = new WeakSet<Node>()
+
+/** Attach the mount/dispose MutationObserver to `root` (document.body or an
+ * open ShadowRoot), once per root. Every observer runs the same callback:
+ * dispose removed subtrees, scan added ones — and `scanAndMount`'s recursion
+ * means a subtree added INSIDE a shadow root that itself hosts more shadow
+ * roots gets those scanned and observed too. */
+function observeRoot(root: Node): void {
+  if (typeof MutationObserver === 'undefined') return
+  if (observedRoots.has(root)) return
+  observedRoots.add(root)
   const obs = new MutationObserver((records) => {
     for (const rec of records) {
       for (const node of Array.from(rec.removedNodes)) {
@@ -528,7 +725,7 @@ function observe(): void {
       }
     }
   })
-  obs.observe(document.body, { childList: true, subtree: true })
+  obs.observe(root, { childList: true, subtree: true })
 }
 
 function disposeTree(node: HTMLElement): void {
@@ -536,6 +733,22 @@ function disposeTree(node: HTMLElement): void {
   for (const el of Array.from(node.querySelectorAll<HTMLElement>('[x-data]'))) {
     disposeElement(el)
   }
+  // R10 — a removed HOST's shadow contents never reach any observer: the host's
+  // removal fires on the light tree's observer, and the shadow root's own
+  // observer only sees mutations INSIDE the root. Walk shadow roots explicitly.
+  if (node.shadowRoot) disposeShadowContents(node.shadowRoot)
+  for (const el of Array.from(node.querySelectorAll<HTMLElement>('*'))) {
+    if (el.shadowRoot) disposeShadowContents(el.shadowRoot)
+  }
+}
+
+function disposeShadowContents(root: ShadowRoot): void {
+  for (const el of Array.from(root.querySelectorAll<HTMLElement>('[x-data]'))) {
+    disposeElement(el)
+  }
+  for (const el of Array.from(root.querySelectorAll<HTMLElement>('*'))) {
+    if (el.shadowRoot) disposeShadowContents(el.shadowRoot)
+  }
 }
 
 function disposeElement(el: HTMLElement): void {

package/runtime/render/fragment.ts

@@ -0,0 +1,87 @@
+// Fragment rendering — render a React tree to a single awaited HTML string.
+//
+// Two consumers:
+//  - routes.ts navigationBranch (SPA-nav payloads) — imports renderToAwaitedString.
+//  - the public `renderFragment` API (R4) — render a component to static HTML
+//    with the framework's request/store/loader-cache contexts scoped per call.
+//
+// React 19 split react-dom/server by runtime: under Bun the bare
+// 'react-dom/server' resolves to the web-streams build (server.bun.js), which
+// only exports renderToReadableStream. renderToPipeableStream (Node streams —
+// what our Writable sink + onAllReady/onShellReady path uses) lives in the
+// .node build. Import it explicitly so SSR works on the react@19 we declare as
+// a peer (React 18 shipped renderToPipeableStream in the bun build, which is
+// why this was silently fine).
+import { createElement, type ComponentType, type ReactNode } from 'react'
+import { renderToPipeableStream } from 'react-dom/server.node'
+import { Writable } from 'node:stream'
+import { Buffer } from 'node:buffer'
+import { runInRequestScope } from '../request-context.ts'
+import { runInRequestCache } from '../loader-cache.ts'
+import { runInStoreContext } from '../store/server-context.ts'
+
+/** Render a React element to a single HTML string, awaiting all Suspense
+ * boundaries via onAllReady. Used by navigationBranch — renderToString
+ * would only capture the shell + fallbacks, while renderBranchStreaming
+ * is for the streaming render path. */
+export function renderToAwaitedString(element: ReactNode): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    const sink = new Writable({
+      write(chunk, _enc, cb) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+        cb()
+      },
+    })
+    sink.on('finish', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    sink.on('error', reject)
+
+    let stream: ReturnType<typeof renderToPipeableStream>
+    stream = renderToPipeableStream(element, {
+      onAllReady() {
+        try {
+          stream.pipe(sink)
+        } catch (e) {
+          reject(e)
+        }
+      },
+      onShellError(err) {
+        reject(err)
+      },
+      onError(err) {
+        // Logged at the navigationBranch level; let onAllReady drive completion.
+        console.error('[brust] render onError (navigation/fragment):', err)
+      },
+    })
+  })
+}
+
+export interface RenderFragmentOpts {
+  /** Request cookies visible to cookies()/session helpers inside the tree. */
+  cookies?: Record<string, string>
+}
+
+/** Render a component to an HTML string with framework contexts scoped:
+ * request scope (cookies) ∘ request cache (cachedFetch/dedupe) ∘ store
+ * context (fresh per call — no cross-call leakage; concurrency-safe via
+ * AsyncLocalStorage). Suspense supported — the promise resolves when the
+ * whole tree is ready, never with fallbacks. Static HTML only: no island
+ * hydration markers/scripts (an `<Island>` inside the fragment SSRs its
+ * component but ships no hydration), no head/CSS collection, no streaming.
+ * Native/jinja fragments are served by `templates.render` instead.
+ * Errors reject with the component's error — no error-boundary semantics. */
+export async function renderFragment<P extends object>(
+  Component: ComponentType<P>,
+  props: P,
+  opts?: RenderFragmentOpts,
+): Promise<string> {
+  // Composition mirrors routes.ts runInRequestContext: scope outermost, then
+  // the request-scoped loader cache, then the per-call store context.
+  return runInRequestScope(opts?.cookies ?? {}, () =>
+    runInRequestCache(() =>
+      runInStoreContext(() =>
+        renderToAwaitedString(createElement(Component as ComponentType, props as object)),
+      ),
+    ),
+  )
+}