brustjs 0.1.20-alpha → 0.1.22-alpha

package/runtime/native/runtime.ts

@@ -0,0 +1,324 @@
+// Directive runtime — react-free, dom-only. Scans the DOM for x-* directives and
+// binds them to per-element component instances via brustjs/store's `effect`.
+import { effect, isComputed, isSignal } from '../store/index.ts'
+
+export type Instance = Record<string, unknown>
+export type Behavior = (ctx: { el: HTMLElement; props: unknown }) => Instance
+
+interface Mounted {
+  disposers: Array<() => void>
+}
+
+const registry = new Map<string, Behavior>()
+const mounted = new WeakMap<HTMLElement, Mounted>()
+const loading = new Map<string, Promise<unknown>>()
+let started = false
+
+/** Per-component behavior chunk URL. Each native interactive component is built to
+ * its OWN `<name>.directive.js` chunk (served from the islands static route) and
+ * loaded ON DEMAND — only when an `x-data="<name>"` for it actually appears (initial
+ * render OR after an SPA-nav swap). The chunk self-registers via the global below. */
+const CHUNK_BASE = '/_brust/islands/'
+
+/** Register a component behavior under `name`. Called by `<name>.directive.js` chunks
+ * via the global handle below (they do NOT import this module — keeps each chunk to
+ * just its behavior, with the runtime shared as the single `_directives.js` copy). */
+export function register(name: string, behavior: Behavior): void {
+  registry.set(name, behavior)
+}
+// Expose `register` on a global so dynamically-imported behavior chunks self-register
+// into THIS runtime's registry without importing/duplicating the runtime. Symbol.for
+// → shared across chunks (same rationale as the store's brands/reactive ctx).
+;(globalThis as { [k: symbol]: unknown })[Symbol.for('brust.directive.register')] = register
+
+/** 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). */
+export function start(root?: ParentNode): void {
+  const scope: ParentNode | undefined =
+    root ?? (typeof document !== 'undefined' ? document : undefined)
+  if (!scope) return
+  const run = () => {
+    scanAndMount(scope)
+    if (!started) {
+      started = true
+      observe()
+    }
+  }
+  if (typeof document !== 'undefined' && document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', run, { once: true })
+  } else {
+    run()
+  }
+}
+
+function scanAndMount(scope: ParentNode): void {
+  if (scope instanceof HTMLElement && scope.hasAttribute('x-data')) mountElement(scope)
+  for (const el of Array.from(scope.querySelectorAll<HTMLElement>('[x-data]'))) {
+    mountElement(el)
+  }
+}
+
+function mountElement(el: HTMLElement): void {
+  if (mounted.has(el)) return
+  const name = el.getAttribute('x-data') ?? ''
+  const behavior = registry.get(name)
+  if (!behavior) {
+    // Behavior chunk not loaded yet → fetch it on demand, then mount this name.
+    loadBehavior(name)
+    return
+  }
+  let props: unknown = {}
+  const rawProps = el.getAttribute('x-props')
+  if (rawProps) {
+    try {
+      props = JSON.parse(rawProps)
+    } catch {
+      console.warn(`[brust] x-props on "${name}" is not valid JSON`)
+    }
+  }
+  const instance = behavior({ el, props })
+  const m: Mounted = { disposers: [] }
+  mounted.set(el, m)
+  bindTree(el, instance, m.disposers)
+  if (typeof instance.init === 'function') {
+    try {
+      Promise.resolve((instance.init as () => unknown)()).catch((e) =>
+        console.error('[brust] x-data init() failed:', e),
+      )
+    } catch (e) {
+      console.error('[brust] x-data init() threw:', e)
+    }
+  }
+}
+
+// Dynamically import a component's behavior chunk (once), then mount every pending
+// element for that name. The chunk self-registers via the global register handle.
+function loadBehavior(name: string): void {
+  if (registry.has(name) || loading.has(name)) return
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+    console.warn(`[brust] unsafe x-data component name "${name}" — not loaded`)
+    return
+  }
+  // Promise.resolve().then(...) so a synchronous import() throw (e.g. happy-dom in
+  // unit tests, or a bad specifier) becomes a rejection the .catch() handles.
+  const p = Promise.resolve()
+    .then(() => import(/* @vite-ignore */ `${CHUNK_BASE}${name}.directive.js`))
+    .then(() => {
+      if (!registry.has(name)) {
+        console.warn(`[brust] "${name}.directive.js" loaded but did not register "${name}"`)
+        return
+      }
+      // Mount every element waiting on this name (initial + swapped-in).
+      if (typeof document !== 'undefined') {
+        for (const el of Array.from(document.querySelectorAll<HTMLElement>(`[x-data="${name}"]`))) {
+          mountElement(el)
+        }
+      }
+    })
+    .catch((e) => console.error(`[brust] failed to load directive component "${name}":`, e))
+  loading.set(name, p)
+}
+
+// Bind this element's directives, then recurse — but never descend into a nested
+// [x-data] (it owns its own subtree and is mounted independently).
+function bindTree(el: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+  if (el.hasAttribute('x-for')) {
+    bindFor(el, instance, disposers)
+    return
+  }
+  bindAttrs(el, instance, disposers)
+  for (const child of Array.from(el.children)) {
+    if (!(child instanceof HTMLElement)) continue
+    if (child.hasAttribute('x-data')) continue
+    bindTree(child, instance, disposers)
+  }
+}
+
+const FOR_RE = /^\s*(\w+)\s+in\s+([\w.]+)\s*$/
+
+// `x-for="item in member"` — the element is the template. Replace it with a comment
+// anchor; on each change of `member`, clear previous clones and render one per item,
+// binding each clone with a child scope { [item]: value } prototype-linked to the
+// instance (so instance members + methods stay visible). v1 = full re-render.
+function bindFor(tplEl: HTMLElement, instance: Instance, disposers: Array<() => void>): void {
+  const raw = tplEl.getAttribute('x-for') ?? ''
+  const m = FOR_RE.exec(raw)
+  if (!m) {
+    console.warn(`[brust] malformed x-for expression: "${raw}"`)
+    return
+  }
+  const itemName = m[1] as string
+  const listPath = m[2] as string
+  const parent = tplEl.parentNode
+  if (!parent) return
+  const anchor = tplEl.ownerDocument.createComment(`x-for:${itemName}`)
+  parent.insertBefore(anchor, tplEl)
+  tplEl.removeAttribute('x-for')
+  const template = tplEl.cloneNode(true) as HTMLElement
+  tplEl.remove()
+
+  const rendered: HTMLElement[] = []
+  const childDisposers: Array<() => void> = []
+
+  const clear = () => {
+    for (const d of childDisposers.splice(0)) {
+      try {
+        d()
+      } catch {
+        /* keep clearing */
+      }
+    }
+    for (const node of rendered.splice(0)) node.remove()
+  }
+
+  disposers.push(
+    effect(() => {
+      clear()
+      const list = read(instance, listPath)
+      if (!Array.isArray(list)) return
+      for (const item of list) {
+        const clone = template.cloneNode(true) as HTMLElement
+        const childScope: Instance = Object.create(instance)
+        childScope[itemName] = item
+        bindTree(clone, childScope, childDisposers)
+        parent.insertBefore(clone, anchor) // before anchor → preserves order
+        rendered.push(clone)
+      }
+    }),
+  )
+  disposers.push(clear)
+}
+
+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-text') {
+      disposers.push(
+        effect(() => {
+          const v = read(scope, value)
+          el.textContent = v == null ? '' : String(v)
+        }),
+      )
+      continue
+    }
+    if (name === 'x-show') {
+      disposers.push(
+        effect(() => {
+          el.style.display = read(scope, value) ? '' : 'none'
+        }),
+      )
+      continue
+    }
+    if (name.startsWith('x-bind-')) {
+      const target = name.slice('x-bind-'.length)
+      disposers.push(
+        effect(() => {
+          setBound(el, target, read(scope, value))
+        }),
+      )
+      continue
+    }
+    if (name.startsWith('x-on-')) {
+      const eventName = name.slice('x-on-'.length)
+      const handler = (e: Event) => callMethod(scope, value, e)
+      el.addEventListener(eventName, handler)
+      disposers.push(() => el.removeEventListener(eventName, handler))
+    }
+  }
+}
+
+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
+  const obs = new MutationObserver((records) => {
+    for (const rec of records) {
+      for (const node of Array.from(rec.removedNodes)) {
+        if (node instanceof HTMLElement) disposeTree(node)
+      }
+      for (const node of Array.from(rec.addedNodes)) {
+        if (node instanceof HTMLElement) scanAndMount(node)
+      }
+    }
+  })
+  obs.observe(document.body, { childList: true, subtree: true })
+}
+
+function disposeTree(node: HTMLElement): void {
+  if (mounted.has(node)) disposeElement(node)
+  for (const el of Array.from(node.querySelectorAll<HTMLElement>('[x-data]'))) {
+    disposeElement(el)
+  }
+}
+
+function disposeElement(el: HTMLElement): void {
+  const m = mounted.get(el)
+  if (!m) return
+  for (const d of m.disposers.splice(0)) {
+    try {
+      d()
+    } catch {
+      // disposer must not break sibling disposal
+    }
+  }
+  mounted.delete(el)
+}
+
+const BOOL_PROPS = new Set(['disabled', 'checked', 'hidden', 'readonly', 'required', 'selected'])
+
+/** Apply a bound value to a DOM attr/property. class → className; boolean props →
+ * property (when present) + attribute presence; value → property; else attribute. */
+export function setBound(el: HTMLElement, attr: string, value: unknown): void {
+  if (attr === 'class') {
+    el.className = value == null ? '' : String(value)
+    return
+  }
+  if (attr === 'value') {
+    ;(el as unknown as { value: unknown }).value = value == null ? '' : value
+    return
+  }
+  if (BOOL_PROPS.has(attr)) {
+    const on = Boolean(value)
+    if (attr in el) (el as unknown as Record<string, unknown>)[attr] = on
+    if (on) el.setAttribute(attr, '')
+    else el.removeAttribute(attr)
+    return
+  }
+  if (value == null || value === false) el.removeAttribute(attr)
+  else el.setAttribute(attr, String(value))
+}
+
+// --- reactive read helpers (used by later tasks) -------------------------------
+
+/** Walk a dotted member path against `scope`; at the LEAF, call signals/computeds/
+ * functions to obtain the reactive value (this read is what `effect` tracks). */
+export function read(scope: Instance, path: string): unknown {
+  let cur: unknown = scope
+  for (const part of path.split('.')) {
+    if (cur == null) return undefined
+    cur = (cur as Record<string, unknown>)[part]
+  }
+  if (isSignal(cur) || isComputed(cur)) return (cur as () => unknown)()
+  if (typeof cur === 'function') return (cur as () => unknown)()
+  return cur
+}
+
+/** Resolve a dotted path WITHOUT calling the leaf (for x-on handlers). */
+export function resolveRaw(scope: Instance, path: string): unknown {
+  let cur: unknown = scope
+  for (const part of path.split('.')) {
+    if (cur == null) return undefined
+    cur = (cur as Record<string, unknown>)[part]
+  }
+  return cur
+}
+
+/** Resolve `path` on `scope` and, if a function, call it with the event. */
+export function callMethod(scope: Instance, path: string, event: Event): void {
+  const fn = resolveRaw(scope, path)
+  if (typeof fn === 'function') (fn as (e: Event) => unknown)(event)
+  else console.warn(`[brust] x-on target "${path}" is not a function`)
+}

package/runtime/render/inject-store.ts

@@ -0,0 +1,63 @@
+import { storeScriptTag } from '../store/serialize.ts'
+
+const ENC = new TextEncoder()
+let warned = false
+
+/** @internal — used by tests to reset the warn-once flag. */
+export function _resetWarnedForTests(): void {
+  warned = false
+}
+
+/** Build the combined `<script type="application/json">` blob for every touched
+ * store. Returns '' when the snapshot is null/empty. */
+export function buildStoreScripts(snap: Record<string, Record<string, unknown>> | null): string {
+  if (!snap) return ''
+  let out = ''
+  for (const [name, state] of Object.entries(snap)) out += storeScriptTag(name, state)
+  return out
+}
+
+/** Splice the store snapshot `<script>`(s) into `body` immediately before the
+ * first `</head>`. Returns the original body untouched if the snapshot is
+ * null/empty or if `</head>` is absent. */
+export function injectBrustStore(
+  body: Uint8Array,
+  snap: Record<string, Record<string, unknown>> | null,
+): Uint8Array {
+  const scripts = buildStoreScripts(snap)
+  if (!scripts) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) {
+    if (!warned) {
+      console.warn('[brust] store: no </head> in first chunk; snapshot not injected')
+      warned = true
+    }
+    return body
+  }
+  const tagBytes = ENC.encode(scripts)
+  const out = new Uint8Array(body.length + tagBytes.length)
+  out.set(body.subarray(0, pos), 0)
+  out.set(tagBytes, pos)
+  out.set(body.subarray(pos), pos + tagBytes.length)
+  return out
+}
+
+function findHeadCloseTag(body: Uint8Array): number {
+  const LT = 0x3c,
+    SL = 0x2f,
+    GT = 0x3e
+  for (let i = 0, max = body.length - 6; i < max; i++) {
+    if (body[i] !== LT || body[i + 1] !== SL) continue
+    if (!isLetter(body[i + 2], 0x48)) continue // H
+    if (!isLetter(body[i + 3], 0x45)) continue // E
+    if (!isLetter(body[i + 4], 0x41)) continue // A
+    if (!isLetter(body[i + 5], 0x44)) continue // D
+    if (body[i + 6] !== GT) continue
+    return i
+  }
+  return -1
+}
+
+function isLetter(b: number, u: number): boolean {
+  return b === u || b === (u | 0x20)
+}

package/runtime/render/stream.ts

@@ -10,6 +10,7 @@ import { injectCssLink } from './inject-css-link.ts'
 import { getCssHrefs, getCssHrefsForRoute } from '../css.ts'
 import { injectDevClient } from './inject-dev-client.ts'
 import { injectActionPrefix, getActionPrefixSnippet } from './inject-action-prefix.ts'
+import { injectBrustStore, buildStoreScripts } from './inject-store.ts'
 import { getDevClientSnippet } from '../dev/inject.ts'
 
 export interface RenderBranchStreamingArgs {
@@ -31,6 +32,10 @@ export interface RenderBranchStreamingArgs {
   /** The matched route's fullPath (e.g. '/' or '/blog/{slug}'). Used to
    * combine global CSS hrefs with per-route CSS hrefs before injection. */
   routePath?: string
+  /** Per-request store snapshot collected after loaders run. Injected as a
+   * `<script data-brust-store="…">` blob before `</head>` (buffering) or into
+   * the streaming first-chunk prepend. Null/undefined → no injection. */
+  storeSnapshot?: Record<string, Record<string, unknown>> | null
 }
 
 const encoder = new TextEncoder()
@@ -150,6 +155,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             body = injectCssLink(body, [...getCssHrefs(), ...perRouteHrefs])
             body = injectDevClient(body, getDevClientSnippet())
             body = injectActionPrefix(body, getActionPrefixSnippet())
+            body = injectBrustStore(body, args.storeSnapshot ?? null)
             const meta = makeMeta({
               status: successStatus,
               streaming: false,
@@ -211,8 +217,14 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               .join('')
             const devTag = getDevClientSnippet() ?? ''
             const prefixTag = getActionPrefixSnippet() ?? ''
-            if (linkTagsStr.length > 0 || devTag.length > 0 || prefixTag.length > 0) {
-              const prepend = encoder.encode(linkTagsStr + prefixTag + devTag)
+            const storeTag = buildStoreScripts(args.storeSnapshot ?? null)
+            if (
+              linkTagsStr.length > 0 ||
+              devTag.length > 0 ||
+              prefixTag.length > 0 ||
+              storeTag.length > 0
+            ) {
+              const prepend = encoder.encode(linkTagsStr + prefixTag + devTag + storeTag)
               const out = new Uint8Array(flushed.length + prepend.length)
               out.set(flushed, 0)
               out.set(prepend, flushed.length)

package/runtime/routes.ts

@@ -10,6 +10,7 @@ import { Writable } from 'node:stream'
 import { Buffer } from 'node:buffer'
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
+import { runInStoreContext, collectSnapshot } from './store/server-context.ts'
 import {
   loadIslandManifest,
   resolveIslandContext,
@@ -636,7 +637,11 @@ export function makeRenderer(
         if (leaf.loader) {
           const ctx = { params: call.params, path: call.path, req: call.req }
           try {
-            data = await leaf.loader(ctx as any)
+            // Native loaders may write to a defineStore; run them in a per-request
+            // store scope so those writes are isolated per request. No snapshot is
+            // collected and no <script> is injected on native paths — Spec B owns
+            // native store delivery (hard non-goal here).
+            data = await runInStoreContext(() => leaf.loader!(ctx as any))
           } catch (err) {
             console.error(`[brust] loader failed for native route ${flat.fullPath}:`, err)
             // FAST LANE: native routes take dispatch_single_chunk (no chunk
@@ -745,36 +750,45 @@ export function makeRenderer(
         }
       }
 
-      let element: ReactNode
-      let errorBoundary: ComponentType<{ error: Error }>
-      try {
-        element = await buildRenderElement(call, flat, opts.getWorkerId)
-        errorBoundary =
-          flat.errorBoundary ??
-          (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
-      } catch (err) {
-        // Setup failure BEFORE renderToPipeableStream — loader throw, params
-        // bind throw. Shape matches the legacy "internal error" path so
-        // existing integration tests stay green.
-        console.error(`[brust] render setup failed:`, err)
-        return await emitSingleChunkResponse(view, napi, workerId, encoder, {
-          status: 500,
-          contentType: 'text/html; charset=utf-8',
-          body: 'internal error',
+      // Wrap the loader run (inside buildRenderElement) AND the React render in
+      // one AsyncLocalStorage store scope so any defineStore read during loaders
+      // or render resolves the same per-request instance. Snapshot is collected
+      // after loaders (buildRenderElement resolved) — that's where Spec A stores
+      // are seeded — and threaded into the render for <script> injection.
+      return await runInStoreContext(async () => {
+        let element: ReactNode
+        let errorBoundary: ComponentType<{ error: Error }>
+        try {
+          element = await buildRenderElement(call, flat, opts.getWorkerId)
+          errorBoundary =
+            flat.errorBoundary ??
+            (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
+        } catch (err) {
+          // Setup failure BEFORE renderToPipeableStream — loader throw, params
+          // bind throw. Shape matches the legacy "internal error" path so
+          // existing integration tests stay green.
+          console.error(`[brust] render setup failed:`, err)
+          return await emitSingleChunkResponse(view, napi, workerId, encoder, {
+            status: 500,
+            contentType: 'text/html; charset=utf-8',
+            body: 'internal error',
+          })
+        }
+        const storeSnapshot = collectSnapshot()
+        await renderBranchStreaming({
+          element,
+          view,
+          workerId,
+          napi,
+          errorBoundary,
+          status: verdict.status,
+          headers: verdict.headers,
+          routePath: flat.fullPath,
+          storeSnapshot,
         })
-      }
-      await renderBranchStreaming({
-        element,
-        view,
-        workerId,
-        napi,
-        errorBoundary,
-        status: verdict.status,
-        headers: verdict.headers,
-        routePath: flat.fullPath,
+        // renderBranchStreaming wrote via the chunk channel.
+        return 0
       })
-      // renderBranchStreaming wrote via the chunk channel.
-      return 0
     }
     if (call.kind === 'navigation') {
       await navigationBranch(call, byRouteId, view, encoder, opts.getWorkerId)
@@ -942,16 +956,26 @@ async function navigationBranch(
     // whose loader fields arrive undefined → throws → 500 → full-reload fallback
     // on every internal link.
     let fullHtml: string
+    // React nav: snapshot of stores seeded during loader+render, shipped in the
+    // nav payload so the client can apply it to its live stores. Native nav
+    // collects no snapshot (Spec B owns native store delivery).
+    let store: Record<string, Record<string, unknown>> | null = null
     if (flat.nativeTemplate !== undefined) {
       fullHtml = await renderNativeRouteToHtml(call, flat, view, encoder, workerId)
     } else {
-      const element = await buildRenderElement(call as any, flat, getWorkerId)
-      if (!element) throw new Error('render setup failed')
-      // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
-      // their RESOLVED markup, not the fallback. renderToString would only
-      // capture the shell — navigating SPA-style to a Suspense-using route
-      // would otherwise ship "loading…" and never recover.
-      fullHtml = await renderToAwaitedString(element)
+      // Wrap loader run (inside buildRenderElement) + render in one store scope so
+      // store reads resolve the per-request instance; collect after render.
+      fullHtml = await runInStoreContext(async () => {
+        const element = await buildRenderElement(call as any, flat, getWorkerId)
+        if (!element) throw new Error('render setup failed')
+        // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
+        // their RESOLVED markup, not the fallback. renderToString would only
+        // capture the shell — navigating SPA-style to a Suspense-using route
+        // would otherwise ship "loading…" and never recover.
+        const html = await renderToAwaitedString(element)
+        store = collectSnapshot()
+        return html
+      })
     }
 
     // Extract <main> inner content. If the page didn't render a <main>,
@@ -971,7 +995,7 @@ async function navigationBranch(
     const titleMatch = fullHtml.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
     const title = titleMatch ? titleMatch[1].replace(/<!--.*?-->/g, '').trim() : ''
 
-    const body = JSON.stringify({ html: innerHtml, title })
+    const body = JSON.stringify({ html: innerHtml, title, store })
     await emitSingleChunkResponse(view, napi, workerId, encoder, {
       status: 200,
       contentType: 'application/json; charset=utf-8',
@@ -1010,7 +1034,11 @@ async function renderNativeRouteToHtml(
 
   let data: unknown = {}
   if (leaf.loader) {
-    data = await leaf.loader({ params: call.params, path: call.path, req: call.req } as any)
+    // Per-request store scope for native loader writes (isolation only). No
+    // snapshot collected / no <script> injected — Spec B owns native delivery.
+    data = await runInStoreContext(() =>
+      leaf.loader!({ params: call.params, path: call.path, req: call.req } as any),
+    )
   }
 
   if (isNativeVerdict(data)) {

package/runtime/store/client-hydrate.ts

@@ -0,0 +1,16 @@
+// runtime/store/client-hydrate.ts — apply a nav-payload snapshot to live client stores.
+export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>): void {
+  const w = window as unknown as {
+    __BRUST_STORES__?: Record<string, { instance: Record<string, unknown> }>
+  }
+  const reg = w.__BRUST_STORES__
+  if (!reg) return
+  for (const [name, state] of Object.entries(snap)) {
+    const entry = reg[name]
+    if (!entry) continue // handle not defined yet on client → skip (initial-load <script> covers it)
+    for (const key of Object.keys(state)) {
+      const v = entry.instance[key] as { set?: (x: unknown) => void } | undefined
+      if (v && typeof v.set === 'function') v.set(state[key])
+    }
+  }
+}