@brust/runtime-dom 0.0.0-stage → 2.0.0-alpha.10

package/src/store/registry.ts

@@ -0,0 +1,103 @@
+// Browser store registry + the server-resolver hook (M3-F D3/D6/C7).
+// The registry lives on globalThis (C7) so two copies of this module share one instance per name.
+import { isComputed, isSignal, untracked } from '../core-api'
+import { parseStoreScript } from './serialize'
+
+// The resolved per-scope store record, shared by the browser 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
+// records created for a resolver, 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
+  /** Browser only: the snapshot the SSR HTML was rendered from (script seed applied, nothing written since). Islands hydrate against it (G13). */
+  ssr?: Record<string, unknown>
+  handle?: { serialize(): Record<string, unknown> }
+}
+
+/** Plain-value view of a record (signals and computeds read, actions dropped), memoized in `rec.snap` per version. */
+export function computeSnapshot(rec: StoreInstanceRecord): Record<string, unknown> {
+  if (rec.snap && rec.snap.version === rec.version.n) return rec.snap.value
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(rec.instance)) {
+    const v = (rec.instance as Record<string, unknown>)[key]
+    if (isSignal(v) || isComputed(v)) out[key] = v()
+  }
+  rec.snap = { value: out, version: rec.version.n }
+  return out
+}
+
+export type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord
+
+const STORES = Symbol.for('brust.stores') // C7
+type Registry = Record<string, StoreInstanceRecord>
+
+// Module-local on purpose (as in 0.1.x): a second runtime-dom copy on the SERVER has no resolver
+// and throws loudly instead of leaking request state into a shared registry.
+let serverResolver: ServerResolver | null = null
+
+/** Installed once at worker boot by packages/brust/src/store/server-context.ts; null uninstalls (tests). */
+export function __setServerResolver(fn: ServerResolver | null): void {
+  serverResolver = fn
+}
+
+function browserRegistry(): Registry {
+  const g = globalThis as { [STORES]?: Registry }
+  return (g[STORES] ??= Object.create(null) as Registry)
+}
+
+// Attribute comparison, never a built selector: the name is not escaped for CSS.
+function seedScript(name: string): Element | null {
+  for (const el of Array.from(document.querySelectorAll('script[data-brust-store]'))) {
+    if (el.getAttribute('data-brust-store') === name) return el
+  }
+  return null
+}
+
+/**
+ * Resolution order (ruling R4): an installed resolver takes EVERY access; otherwise the browser
+ * registry when `document` exists (created, then lazily seeded from the page's script tag on the
+ * first access per name, D6); otherwise throw.
+ */
+export function resolveRecord(
+  name: string,
+  create: (server: boolean) => StoreInstanceRecord,
+  seed: (rec: StoreInstanceRecord, state: Record<string, unknown>) => void,
+): StoreInstanceRecord {
+  if (serverResolver) return serverResolver(name, () => create(true))
+  if (typeof document === 'undefined') {
+    throw new Error(`store '${name}' accessed on the server without a request scope`)
+  }
+  const reg = browserRegistry()
+  let rec = reg[name]
+  if (!rec) {
+    const made = (rec = reg[name] = create(false))
+    const el = seedScript(name)
+    if (el) seed(rec, parseStoreScript(el))
+    // Identity-stable: the same object stays `rec.snap` until the first write.
+    rec.ssr = untracked(() => computeSnapshot(made)) // a first access inside an effect must not subscribe it
+  }
+  return rec
+}
+
+/** Apply a navigation-payload snapshot to live client stores. Reserved for the SPA wave (D9): no callers yet. */
+export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>): void {
+  const reg = (globalThis as { [STORES]?: Registry })[STORES]
+  if (!reg) return
+  for (const [name, state] of Object.entries(snap)) {
+    const entry = reg[name]
+    if (!entry) continue // not defined on the client yet: the initial-load <script> covers it
+    const inst = entry.instance as Record<string, { set?: (x: unknown) => void } | undefined>
+    for (const key of Object.keys(state)) {
+      const v = inst[key]
+      if (v && typeof v.set === 'function') v.set(state[key])
+    }
+    entry.ssr = untracked(() => computeSnapshot(entry)) // R11.1: the payload is the new server truth for islands hydrating later
+  }
+}
+
+export function _resetStores(): void {
+  delete (globalThis as { [STORES]?: unknown })[STORES]
+}

package/src/store/serialize.ts

@@ -0,0 +1,33 @@
+// Snapshot serialization for the store (M3-F D6). 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. C4: the Rust emitter (render.rs::inject_assets_into)
+// mirrors these bytes; test 'C4 golden bytes' is the shared contract.
+
+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/src/value.ts

@@ -0,0 +1,47 @@
+import { isReactive } from './signal'
+export interface ParsedValue { path: string[]; bindings: string[] }
+const IDENT = /^[A-Za-z_$][\w$]*$/
+
+export function parseValue(raw: string): ParsedValue | null {
+  const [pathPart, bindPart, ...rest] = raw.trim().split(':')
+  if (rest.length || !pathPart) return null
+  const path = pathPart.split('.')
+  if (!path.every((p) => IDENT.test(p))) return null
+  const bindings = bindPart === undefined ? [] : bindPart.split(',').map((b) => b.trim())
+  if (!bindings.every((b) => IDENT.test(b))) return null
+  return { path, bindings }
+}
+
+export type Scope = Record<string, unknown>
+
+/** Resolve a parsed directive value against instance members. Reads signals (tracked). */
+export function resolve(members: Record<string, unknown>, v: ParsedValue, scope: Scope): { ok: true; value: unknown } | { ok: false } {
+  // x-for rows expose a tick that changes when the row's item/index is refreshed; reading it subscribes.
+  const tick = scope.__tick
+  if (typeof tick === 'function') tick()
+  let cur: unknown = members
+  for (const key of v.path) {
+    if (isReactive(cur)) cur = cur()
+    if (cur === null || typeof cur !== 'object') return { ok: false }
+    if (!(key in (cur as object))) return { ok: false }
+    cur = (cur as Record<string, unknown>)[key]
+  }
+  if (v.bindings.length) {
+    if (typeof cur !== 'function') return { ok: false }
+    const args = v.bindings.map((b) => scope[b])
+    return { ok: true, value: (cur as (...a: unknown[]) => unknown)(...args) }
+  }
+  if (isReactive(cur)) cur = cur()
+  return { ok: true, value: cur }
+}
+
+/** Like resolve but returns the member itself (for handlers and x-model signals). */
+export function resolveMember(members: Record<string, unknown>, v: ParsedValue): unknown {
+  let cur: unknown = members
+  for (const key of v.path) {
+    if (isReactive(cur)) cur = cur()
+    if (cur === null || typeof cur !== 'object' || !(key in (cur as object))) return undefined
+    cur = (cur as Record<string, unknown>)[key]
+  }
+  return cur
+}

package/src/warn.ts

@@ -0,0 +1,9 @@
+const seen = new Set<string>()
+export function warnOnce(key: string, message: string): void {
+  if (seen.has(key)) return
+  seen.add(key)
+  console.warn(`[brust] ${message}`)
+}
+
+/** test-only; the browser harness calls it between cases */
+export function __resetWarnOnce(): void { seen.clear() }