brustjs 0.1.20-alpha → 0.1.22-alpha

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)

package/runtime/store/signal.ts

@@ -0,0 +1,170 @@
+// Minimal pull-based reactive core: push-on-write, pull-on-read, synchronous notify.
+// Framework-agnostic — no react, no dom. Foundation for defineStore (Spec A) and
+// the Alpine-style client runtime (Spec B).
+
+// Symbol.for (GLOBAL registry), NOT Symbol(): every island is a SEPARATE Bun.build
+// chunk that inlines its own copy of this module, so a plain `Symbol()` brand would
+// be a DIFFERENT value per chunk — `isSignal` from chunk B then fails to recognize a
+// signal created in chunk A. That poisons the shared store snapshot (a cross-chunk
+// reader computes `{}` and caches it), so e.g. the team dock reads empty after a SPA
+// nav loads a new island chunk. A global registry symbol is identical across chunks.
+const SIGNAL = Symbol.for('brust.signal')
+const COMPUTED = Symbol.for('brust.computed')
+
+export interface Signal<T> {
+  (): T
+  set(next: T | ((prev: T) => T)): void
+  readonly [SIGNAL]: true
+}
+export interface Computed<T> {
+  (): T
+  readonly [COMPUTED]: true
+}
+
+export function isSignal(v: unknown): v is Signal<unknown> {
+  return typeof v === 'function' && (v as { [SIGNAL]?: true })[SIGNAL] === true
+}
+export function isComputed(v: unknown): v is Computed<unknown> {
+  return typeof v === 'function' && (v as { [COMPUTED]?: true })[COMPUTED] === true
+}
+
+// A reactive consumer (effect or computed) tracking its dependencies.
+interface Consumer {
+  run(): void
+  deps: Set<Set<Consumer>>
+  running: boolean
+}
+
+// The dependency-tracking state (the "currently running consumer", the batch
+// depth, the pending-notify queue) MUST be shared across chunks, for the SAME
+// reason the brands use Symbol.for: every island / the directive runtime is a
+// SEPARATE Bun.build that inlines its own copy of THIS module. If `activeConsumer`
+// were a module-local `let`, each chunk would have its own — so an `effect` in
+// chunk B reading a `signal` created in chunk A would register against chunk A's
+// (always-null) activeConsumer and never subscribe. Concretely: a native directive
+// button's effect (its own chunk) would never re-run when a React island (another
+// chunk) mutated the shared store, even though the store value changed. Holding the
+// context on `globalThis` under a Symbol.for key makes all chunks share ONE tracker.
+interface ReactiveCtx {
+  activeConsumer: Consumer | null
+  batchDepth: number
+  pendingNotify: Set<Consumer>
+}
+const CTX_KEY = Symbol.for('brust.reactive.ctx')
+const ctxHolder = globalThis as { [CTX_KEY]?: ReactiveCtx }
+if (!ctxHolder[CTX_KEY]) {
+  ctxHolder[CTX_KEY] = { activeConsumer: null, batchDepth: 0, pendingNotify: new Set<Consumer>() }
+}
+const ctx: ReactiveCtx = ctxHolder[CTX_KEY]
+
+function track(subscribers: Set<Consumer>): void {
+  if (ctx.activeConsumer) {
+    subscribers.add(ctx.activeConsumer)
+    ctx.activeConsumer.deps.add(subscribers)
+  }
+}
+
+function notify(subscribers: Set<Consumer>): void {
+  // Snapshot — a consumer re-running mutates the set.
+  for (const c of [...subscribers]) {
+    if (ctx.batchDepth > 0) ctx.pendingNotify.add(c)
+    else c.run()
+  }
+}
+
+function flush(): void {
+  const queued = [...ctx.pendingNotify]
+  ctx.pendingNotify.clear()
+  for (const c of queued) c.run()
+}
+
+export function batch(fn: () => void): void {
+  ctx.batchDepth++
+  try {
+    fn()
+  } finally {
+    ctx.batchDepth--
+    if (ctx.batchDepth === 0) flush()
+  }
+}
+
+export function signal<T>(initial: T): Signal<T> {
+  let value = initial
+  const subscribers = new Set<Consumer>()
+  const read = (() => {
+    track(subscribers)
+    return value
+  }) as Signal<T>
+  read.set = (next: T | ((prev: T) => T)) => {
+    const v = typeof next === 'function' ? (next as (p: T) => T)(value) : next
+    if (Object.is(v, value)) return
+    value = v
+    notify(subscribers)
+  }
+  Object.defineProperty(read, SIGNAL, { value: true })
+  return read
+}
+
+function clearDeps(c: Consumer): void {
+  for (const dep of c.deps) dep.delete(c)
+  c.deps.clear()
+}
+
+export function computed<T>(fn: () => T): Computed<T> {
+  let cached: T
+  let dirty = true
+  const subscribers = new Set<Consumer>()
+  const self: Consumer = {
+    deps: new Set(),
+    running: false,
+    run() {
+      if (self.running) return
+      self.running = true
+      try {
+        dirty = true
+        notify(subscribers) // downstream recomputes lazily on next read
+      } finally {
+        self.running = false
+      }
+    },
+  }
+  const read = (() => {
+    track(subscribers)
+    if (dirty) {
+      clearDeps(self)
+      const prev = ctx.activeConsumer
+      ctx.activeConsumer = self
+      try {
+        cached = fn()
+        dirty = false
+      } finally {
+        ctx.activeConsumer = prev
+      }
+    }
+    return cached
+  }) as Computed<T>
+  Object.defineProperty(read, COMPUTED, { value: true })
+  return read
+}
+
+export function effect(fn: () => void): () => void {
+  const self: Consumer = {
+    deps: new Set(),
+    running: false,
+    run() {
+      if (self.running) return
+      self.running = true
+      clearDeps(self)
+      const prev = ctx.activeConsumer
+      ctx.activeConsumer = self
+      try {
+        fn()
+      } finally {
+        ctx.activeConsumer = prev
+        self.running = false
+      }
+    },
+  }
+  self.run()
+  return () => clearDeps(self)
+}

package/example/pokedex/components/team-bus.ts

@@ -1,25 +0,0 @@
-// Cross-island sync bus.
-//
-// GAP S4: brust has no cross-island shared-state primitive. AddToTeamButton and
-// TeamBuilder are two SEPARATE island chunks (each its own Bun.build bundle), so
-// a module-scope store imported by both would be DUPLICATED — two instances that
-// never see each other. The one thing both chunks genuinely share is the
-// `window` object, so we coordinate through a window CustomEvent. This works,
-// but it's a hand-rolled workaround for a pattern (cart / team / selection) that
-// most apps need. See ../FRAMEWORK-GAPS.md S4.
-
-import type { TeamMember } from '../lib/types'
-
-export const TEAM_EVENT = 'brust-pokedex:team'
-
-export function emitTeam(team: TeamMember[]): void {
-  if (typeof window === 'undefined') return
-  window.dispatchEvent(new CustomEvent<TeamMember[]>(TEAM_EVENT, { detail: team }))
-}
-
-export function onTeam(fn: (team: TeamMember[]) => void): () => void {
-  if (typeof window === 'undefined') return () => {}
-  const handler = (e: Event) => fn((e as CustomEvent<TeamMember[]>).detail)
-  window.addEventListener(TEAM_EVENT, handler)
-  return () => window.removeEventListener(TEAM_EVENT, handler)
-}