brustjs 0.1.19-alpha → 0.1.21-alpha

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])
+    }
+  }
+}

package/runtime/store/define-store.ts

@@ -0,0 +1,179 @@
+import { type Computed, type Signal, isComputed, isSignal } from './signal.ts'
+import { parseStoreScript } from './serialize.ts'
+
+// The resolved per-scope store record, shared by the client singleton registry
+// and the server per-request map. `version` bumps on every signal write so
+// `snapshot()` returns a referentially-stable object (useSyncExternalStore
+// contract) until a change; `snap` memoizes it. `handle` is set only on the
+// server record so collectSnapshot() can serialize a touched store.
+export interface StoreInstanceRecord {
+  instance: object
+  subs: Set<() => void>
+  version: { n: number }
+  snap: { value: Record<string, unknown>; version: number } | null
+  handle?: { serialize(): Record<string, unknown> }
+}
+
+// Server per-request resolver, injected by server-context.ts (which imports
+// node:async_hooks) via __setServerResolver. This keeps define-store — reachable
+// from browser/island bundles via brustjs/store and brustjs/client — free of any
+// static Node-builtin import. On the client the resolver stays null and the
+// window-singleton branch is used.
+type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord
+let serverResolver: ServerResolver | null = null
+export function __setServerResolver(fn: ServerResolver): void {
+  serverResolver = fn
+}
+
+// Unwrap a Signal/Computed to its value type; `never` if it is neither. Uses
+// `infer` (not `extends Signal<unknown>`): `Signal<T>.set(next: T)` is
+// contravariant in T, so `Signal<TeamMember[]>` is NOT assignable to
+// `Signal<unknown>` — a concrete-`unknown` check wrongly drops every typed signal
+// key from the snapshot. `infer` sidesteps that.
+type StoreValue<X> = X extends Signal<infer T> ? T : X extends Computed<infer T> ? T : never
+
+// Snapshot = plain-value view of a store: Signal<T>/Computed<T> → T, plain values
+// kept as-is, action functions dropped. The `[…] extends [never]` tuple wrap stops
+// `never` from distributing the conditional to `never`.
+export type Snapshot<S> = {
+  [K in keyof S as [StoreValue<S[K]>] extends [never]
+    ? S[K] extends (...a: never[]) => unknown
+      ? never
+      : K
+    : K]: [StoreValue<S[K]>] extends [never] ? S[K] : StoreValue<S[K]>
+}
+
+// `then` is reserved so a store with a signal named `then` can't make the proxy
+// an accidental thenable (await/Promise.resolve(handle) misbehaving).
+const RESERVED = new Set(['name', 'subscribe', 'snapshot', 'serialize', 'hydrate', 'then'])
+
+export interface StoreHandle<S extends object> {
+  (): S
+  readonly name: string
+  subscribe(cb: () => void): () => void
+  snapshot(): Snapshot<S>
+  serialize(): Record<string, unknown>
+  hydrate(state: Record<string, unknown>): void
+}
+
+interface ClientRegistry {
+  [name: string]: StoreInstanceRecord
+}
+function clientRegistry(): ClientRegistry {
+  const w = window as unknown as { __BRUST_STORES__?: ClientRegistry }
+  if (!w.__BRUST_STORES__) w.__BRUST_STORES__ = {}
+  return w.__BRUST_STORES__
+}
+
+// We need each instance's signals to notify the store's subscriber set on write.
+// signal.ts subscribers are internal; to bridge to React's subscribe, defineStore
+// wraps the instance: after factory(), for every signal property we wrap .set to
+// also bump the version and fire the store-level subscriber set. (computed
+// downstream of those signals recomputes lazily; React re-reads snapshot.)
+function bridgeSubscribers(
+  instance: Record<string, unknown>,
+  subs: Set<() => void>,
+  version: { n: number },
+): void {
+  for (const key of Object.keys(instance)) {
+    const v = instance[key]
+    if (isSignal(v)) {
+      const sig = v as Signal<unknown>
+      const origSet = sig.set.bind(sig)
+      sig.set = (next) => {
+        // origSet is a no-op when Object.is(prev,next). Reading sig() here is
+        // outside any active consumer, so it registers no dependency — we can
+        // compare before/after and only bump+notify on a real change, avoiding
+        // spurious React re-renders.
+        const before = sig()
+        origSet(next as never)
+        const after = sig()
+        if (Object.is(before, after)) return
+        version.n += 1
+        for (const cb of [...subs]) cb()
+      }
+    }
+  }
+}
+
+export function defineStore<S extends object>(name: string, factory: () => S): StoreHandle<S> & S {
+  function createRecord(): StoreInstanceRecord {
+    const instance = factory() as object
+    const subs = new Set<() => void>()
+    const version = { n: 0 }
+    bridgeSubscribers(instance as Record<string, unknown>, subs, version)
+    return { instance, subs, version, snap: null }
+  }
+
+  function resolve(): StoreInstanceRecord {
+    if (typeof window !== 'undefined') {
+      const reg = clientRegistry()
+      if (!reg[name]) {
+        reg[name] = createRecord()
+        // hydrate from server-injected <script> if present (first access only).
+        const el = document.querySelector(`script[data-brust-store="${name}"]`)
+        if (el) hydrateRecord(reg[name], parseStoreScript(el))
+      }
+      return reg[name]
+    }
+    // server: per-request via the resolver injected by server-context.ts.
+    if (!serverResolver) {
+      throw new Error(`store '${name}' accessed on the server without a request scope`)
+    }
+    return serverResolver(name, () => ({
+      ...createRecord(),
+      handle: handle as StoreHandle<object>,
+    }))
+  }
+
+  function hydrateRecord(rec: StoreInstanceRecord, state: Record<string, unknown>): void {
+    const inst = rec.instance as Record<string, unknown>
+    for (const key of Object.keys(state)) {
+      const v = inst[key]
+      if (isSignal(v)) (v as Signal<unknown>).set(state[key])
+    }
+  }
+
+  const handle = (() => resolve().instance) as StoreHandle<S> & S
+  Object.defineProperty(handle, 'name', { value: name })
+  handle.subscribe = (cb) => {
+    const rec = resolve()
+    rec.subs.add(cb)
+    return () => rec.subs.delete(cb)
+  }
+  handle.snapshot = () => {
+    const rec = resolve()
+    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 as object)) {
+      const v = (rec.instance as Record<string, unknown>)[key]
+      if (isSignal(v) || isComputed(v)) out[key] = (v as () => unknown)()
+    }
+    rec.snap = { value: out, version: rec.version.n }
+    return out as Snapshot<S>
+  }
+  handle.serialize = () => {
+    const rec = resolve()
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(rec.instance as object)) {
+      const v = (rec.instance as Record<string, unknown>)[key]
+      if (isSignal(v)) out[key] = (v as () => unknown)()
+    }
+    return out
+  }
+  handle.hydrate = (state) => {
+    hydrateRecord(resolve(), state)
+  }
+
+  return new Proxy(handle, {
+    get(target, prop, recv) {
+      if (typeof prop === 'symbol' || RESERVED.has(prop)) {
+        return Reflect.get(target, prop, recv)
+      }
+      const rec = resolve()
+      return (rec.instance as Record<string | symbol, unknown>)[prop]
+    },
+  }) as StoreHandle<S> & S
+}

package/runtime/store/index.ts

@@ -0,0 +1,8 @@
+// runtime/store/index.ts — brustjs/store. Isomorphic, framework-free, dom-free.
+// No UI-framework adapter is re-exported here (the view-layer binding lives
+// separately and is reachable only from the brustjs main entry).
+export { signal, computed, effect, batch, isSignal, isComputed } from './signal.ts'
+export type { Signal, Computed } from './signal.ts'
+export { defineStore } from './define-store.ts'
+export type { StoreHandle, Snapshot } from './define-store.ts'
+export { toScriptJson, parseStoreScript, storeScriptTag } from './serialize.ts'

package/runtime/store/react.ts

@@ -0,0 +1,23 @@
+// runtime/store/react.ts — React adapter. Exported from the brustjs MAIN entry,
+// never from ./store (which must stay react-free).
+import { useSyncExternalStore } from 'react'
+import type { Snapshot, StoreHandle } from './define-store.ts'
+
+export function useStore<S extends object>(store: StoreHandle<S> & S): Snapshot<S> {
+  // An `ssr` island can render (renderToString) on the server OUTSIDE a request
+  // store scope — e.g. an ssr island on a native-jinja page, whose SSR runs after
+  // the loader's `runInStoreContext` scope has closed. `store.snapshot()` throws
+  // there (the S6 out-of-scope guard). Degrade to an empty snapshot for the
+  // server render so the island SSRs its factory-default markup; the client
+  // resolves the real window singleton and hydrates. Components that need a
+  // specific initial on first paint should drive it from props until mounted
+  // (Spec A does not server-seed native client state — that is Spec B).
+  const serverSnapshot = (): Snapshot<S> => {
+    try {
+      return store.snapshot()
+    } catch {
+      return {} as Snapshot<S>
+    }
+  }
+  return useSyncExternalStore(store.subscribe, store.snapshot, serverSnapshot)
+}

package/runtime/store/serialize.ts

@@ -0,0 +1,32 @@
+// JSON for embedding in a <script> TEXT node (not an attribute). brust runs
+// AutoEscape::None and a request-derived value can reach a serialized signal, so
+// escape against </script> / <!-- breakout. See memory brust-jinja-autoescape-none.
+
+const ESC: Record<string, string> = {
+  '<': '\\u003c',
+  '>': '\\u003e',
+  '&': '\\u0026',
+  '\u2028': '\\u2028',
+  '\u2029': '\\u2029',
+}
+
+export function toScriptJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (c) => ESC[c])
+}
+
+export function storeScriptTag(name: string, state: unknown): string {
+  // name comes from defineStore (developer literal), not request data; still
+  // guard the attribute against quote breakout by rejecting unexpected chars.
+  const safeName = String(name).replace(/[^a-zA-Z0-9_.:-]/g, '')
+  return `<script type="application/json" data-brust-store="${safeName}">${toScriptJson(state)}</script>`
+}
+
+export function parseStoreScript(el: { textContent: string | null }): Record<string, unknown> {
+  const text = el.textContent ?? '{}'
+  try {
+    return JSON.parse(text) as Record<string, unknown>
+  } catch (e) {
+    console.warn('[brust] store: invalid snapshot JSON', e)
+    return {}
+  }
+}

package/runtime/store/server-context.ts

@@ -0,0 +1,43 @@
+// This module is the ONLY one in runtime/store that imports a Node builtin
+// (node:async_hooks). define-store.ts must NOT import it statically — it is
+// reachable from browser/island bundles (brustjs/store, brustjs/client). Instead
+// we register the per-request resolver into define-store via __setServerResolver
+// at module load; the server pulls this module in via routes.ts (runInStoreContext
+// / collectSnapshot), so the resolver is installed before any request runs.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { __setServerResolver, type StoreInstanceRecord } from './define-store.ts'
+
+const storeContext = new AsyncLocalStorage<Map<string, StoreInstanceRecord>>()
+
+export function runInStoreContext<T>(fn: () => T): T {
+  return storeContext.run(new Map(), fn)
+}
+
+// Resolve (create-once) the per-request instance for `name` in the active scope.
+// Exported for direct unit testing; production code reaches it via the resolver
+// registered into define-store.ts below.
+export function getServerInstance(
+  name: string,
+  create: () => StoreInstanceRecord,
+): StoreInstanceRecord {
+  const map = storeContext.getStore()
+  if (!map) {
+    throw new Error(`store '${name}' accessed outside a request scope`)
+  }
+  let rec = map.get(name)
+  if (!rec) {
+    rec = create()
+    map.set(name, rec)
+  }
+  return rec
+}
+
+export function collectSnapshot(): Record<string, Record<string, unknown>> | null {
+  const map = storeContext.getStore()
+  if (!map || map.size === 0) return null
+  const out: Record<string, Record<string, unknown>> = {}
+  for (const [name, rec] of map) out[name] = rec.handle ? rec.handle.serialize() : {}
+  return out
+}
+
+__setServerResolver(getServerInstance)