@pyreon/reactivity 0.18.0 → 0.19.0

package/src/reactive-trace.ts

@@ -0,0 +1,142 @@
+/**
+ * Reactive trace — a bounded, dev-only ring buffer of recent signal
+ * writes. When a signal-based UI throws, the single most useful
+ * debugging question is "what reactive state changed in the run-up to
+ * the crash" — a point-in-time snapshot of every signal value can't
+ * answer that (it shows the end state, not the causal sequence). The
+ * ring buffer records the last N writes so an error report can attach
+ * the sequence that led into the bad state.
+ *
+ * Design constraints:
+ *
+ *   - **Bounded memory.** Fixed-size circular buffer (`CAP` entries).
+ *     Never grows. Old entries overwrite oldest-first.
+ *   - **No value retention.** Stores a TRUNCATED STRING preview of
+ *     prev / next, never the raw value. Holding raw references would
+ *     retain large arrays / detached DOM / closures in the buffer and
+ *     leak them for the buffer's lifetime. The preview is also what
+ *     makes the trace safely serializable into an error report.
+ *   - **Cheap.** No stack capture (that's the expensive part of the
+ *     `onSignalUpdate` debug path — this is deliberately lighter so it
+ *     can record every write in dev without a perf cost). One object
+ *     literal + one array slot write per signal write.
+ *   - **Zero production cost.** The single call site in `signal.ts`
+ *     is inside the existing `process.env.NODE_ENV !== 'production'`
+ *     gate, so the whole module tree-shakes out of prod bundles.
+ */
+
+export interface ReactiveTraceEntry {
+  /** Signal `label` (set via `signal(v, { name })` or the vite plugin's dev auto-naming). `undefined` for anonymous signals. */
+  name: string | undefined
+  /** Bounded string preview of the value before the write. */
+  prev: string
+  /** Bounded string preview of the value after the write. */
+  next: string
+  /** `performance.now()` at write time (monotonic; survives clock changes). */
+  timestamp: number
+}
+
+/**
+ * Ring-buffer capacity. 50 entries is enough to see the causal chain
+ * for a crash (the writes in the few ticks before the throw) without
+ * the buffer itself becoming a memory concern — each entry is a small
+ * object with two short strings.
+ */
+const CAP = 50
+
+// Lazily allocated — apps that never write a signal in dev (rare) pay
+// nothing until the first write. `_count` is the monotonic total write
+// count; `_count % CAP` is the next slot. Reading reconstructs
+// chronological order from the wrapped buffer.
+let _buf: (ReactiveTraceEntry | undefined)[] | null = null
+let _count = 0
+
+/** Max characters of a value preview before truncation. Keeps the buffer + serialized report small. */
+const PREVIEW_MAX = 80
+
+/**
+ * Safe, bounded stringification. Never throws (a getter or `toJSON`
+ * that throws must not break the trace recorder), never returns more
+ * than `PREVIEW_MAX` chars + an ellipsis marker.
+ */
+function preview(v: unknown): string {
+  let s: string
+  try {
+    if (v === null) return 'null'
+    if (v === undefined) return 'undefined'
+    const t = typeof v
+    if (t === 'string') s = JSON.stringify(v) as string
+    else if (t === 'number' || t === 'boolean' || t === 'bigint') s = String(v)
+    else if (t === 'function') s = `[Function ${(v as { name?: string }).name || 'anonymous'}]`
+    else if (t === 'symbol') s = (v as symbol).toString()
+    else if (Array.isArray(v)) s = `Array(${(v as unknown[]).length})`
+    else {
+      // Plain-ish object: show the constructor name + a shallow key
+      // hint. Avoid full JSON.stringify — it can be huge or throw on
+      // cycles / BigInt / getters.
+      const ctor = (v as { constructor?: { name?: string } }).constructor?.name
+      const keys = (() => {
+        try {
+          return Object.keys(v as object).slice(0, 4)
+        } catch {
+          return []
+        }
+      })()
+      s = `${ctor && ctor !== 'Object' ? ctor + ' ' : ''}{${keys.join(', ')}${keys.length === 4 ? ', …' : ''}}`
+    }
+  } catch {
+    s = '[unstringifiable]'
+  }
+  return s.length > PREVIEW_MAX ? s.slice(0, PREVIEW_MAX) + '…' : s
+}
+
+/**
+ * Record one signal write. Called from `signal.ts` `_set`, already
+ * inside the prod-gate, so this never runs in production builds.
+ *
+ * @internal
+ */
+export function _recordSignalWrite(name: string | undefined, prev: unknown, next: unknown): void {
+  if (_buf === null) _buf = new Array(CAP)
+  _buf[_count % CAP] = {
+    name,
+    prev: preview(prev),
+    next: preview(next),
+    timestamp:
+      typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now(),
+  }
+  _count++
+}
+
+/**
+ * Returns the recorded writes in chronological order (oldest → newest),
+ * at most `CAP` entries. Empty array when nothing has been recorded.
+ * The returned array is a fresh copy — safe to retain / serialize
+ * without pinning the ring buffer.
+ *
+ * Consumed by `@pyreon/core`'s `reportError` to attach `reactiveTrace`
+ * to the error context.
+ */
+export function getReactiveTrace(): ReactiveTraceEntry[] {
+  if (_buf === null || _count === 0) return []
+  if (_count <= CAP) {
+    // Buffer not yet wrapped — entries 0.._count-1 are in order.
+    return _buf.slice(0, _count) as ReactiveTraceEntry[]
+  }
+  // Wrapped: oldest entry is at `_count % CAP`, walk forward CAP slots.
+  const start = _count % CAP
+  const out: ReactiveTraceEntry[] = []
+  for (let i = 0; i < CAP; i++) {
+    const e = _buf[(start + i) % CAP]
+    if (e) out.push(e)
+  }
+  return out
+}
+
+/** Clears the buffer. For test isolation; not part of the app-facing API. */
+export function clearReactiveTrace(): void {
+  _buf = null
+  _count = 0
+}

package/src/reconcile.ts

@@ -23,6 +23,16 @@ import { isStore } from './store'
 
 type AnyObject = Record<PropertyKey, unknown>
 
+// Keys that, written through the bracket-assignment paths below, would
+// mutate Object.prototype (or a constructor's prototype) instead of the
+// store. `reconcile` is explicitly documented for applying API responses
+// directly (`reconcile(JSON.parse(body), store)`), and
+// `JSON.parse('{"__proto__":{…}}')` yields an OWN enumerable `__proto__`
+// key that `Object.keys` returns — the canonical prototype-pollution
+// merge vector. Skip these unconditionally on both the write and the
+// stale-key-removal pass.
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
 export function reconcile<T extends object>(source: T, target: T): void {
   _reconcileInner(source, target, new WeakSet())
 }
@@ -80,6 +90,7 @@ function _reconcileObject(source: AnyObject, target: AnyObject, seen: WeakSet<ob
   const targetKeys = new Set(Object.keys(target))
 
   for (const key of sourceKeys) {
+    if (DANGEROUS_KEYS.has(key)) continue
     const sv = source[key]
     const tv = target[key]
 
@@ -101,6 +112,7 @@ function _reconcileObject(source: AnyObject, target: AnyObject, seen: WeakSet<ob
 
   // Remove keys that no longer exist in source
   for (const key of targetKeys) {
+    if (DANGEROUS_KEYS.has(key)) continue
     delete target[key]
   }
 }

package/src/signal.ts

@@ -1,5 +1,6 @@
 import { batch, enqueuePendingNotification, isBatching } from './batch'
 import { _notifyTraceListeners, isTracing } from './debug'
+import { _recordSignalWrite } from './reactive-trace'
 import { notifySubscribers, trackSubscriber } from './tracking'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
@@ -35,9 +36,9 @@ export interface Signal<T> {
   subscribe(listener: () => void): () => void
   /**
    * Register a direct updater — even lighter than subscribe().
-   * Uses a flat array instead of Set. Disposal nulls the slot (no Set.delete).
    * Intended for compiler-emitted DOM bindings (_bindText, _bindDirect).
-   * Returns a disposer that nulls the slot.
+   * Returns a disposer that removes the updater (O(1)); the live set
+   * stays bounded under register/dispose churn.
    */
   direct(updater: () => void): () => void
   /**
@@ -63,13 +64,13 @@ interface SignalFn<T> {
   _v: T
   /** @internal subscriber set (lazily allocated by trackSubscriber) */
   _s: Set<() => void> | null
-  /** @internal direct updaters array — compiler-emitted DOM updaters (lazily allocated) */
-  _d: ((() => void) | null)[] | null
+  /** @internal direct updater set — compiler-emitted DOM updaters (lazily allocated) */
+  _d: Set<() => void> | null
   peek(): T
   set(value: T): void
   update(fn: (current: T) => T): void
   subscribe(listener: () => void): () => void
-  /** Register a direct updater — lighter than subscribe, uses array index disposal. */
+  /** Register a direct updater — lighter than subscribe; O(1) set-based disposal. */
   direct(updater: () => void): () => void
   label: string | undefined
   debug(): SignalDebugInfo<T>
@@ -87,6 +88,15 @@ function _set(this: SignalFn<unknown>, newValue: unknown) {
     _countSink.__pyreon_count__?.('reactivity.signalWrite')
   const prev = this._v
   this._v = newValue
+  // Dev-only bounded ring buffer of recent writes — attached to error
+  // reports so a crash carries the causal sequence of signal changes,
+  // not just the thrown value. Tree-shaken in prod via the gate.
+  // Deliberately separate from the `isTracing()` path below: that one
+  // is opt-in (requires an onSignalUpdate listener) and captures a
+  // stack (expensive); this is always-on in dev and intentionally
+  // cheap (string preview, no stack).
+  if (process.env.NODE_ENV !== 'production')
+    _recordSignalWrite(this.label, prev, newValue)
   if (isTracing()) {
     // Trace listeners are user-supplied debug code that fires on every
     // signal write. A throwing listener here would leave `_v` updated but
@@ -144,33 +154,36 @@ function _subscribe(this: SignalFn<unknown>, listener: () => void): () => void {
 
 /**
  * Register a direct updater — lighter than subscribe().
- * Uses a flat array instead of Set. Disposal nulls the slot (no Set.delete overhead).
  * Used by compiler-emitted _bindText/_bindDirect for zero-overhead DOM bindings.
+ *
+ * Backed by a `Set` (same as `_s`), NOT a flat array. The array form
+ * disposed by nulling the slot (`arr[idx] = null`) but never compacted —
+ * so a long-lived signal (theme/locale/auth, or a signal read inside
+ * `<For>` rows) bound by churning components accumulated one permanent
+ * dead slot per ever-mounted binding. That is an app-lifetime memory
+ * leak AND degrades the signal-write hot path: `notifyDirect` iterated
+ * O(total-ever-registered), not O(live). A Set bounds growth to the live
+ * set and keeps disposal + iteration O(live); the "Set.delete overhead"
+ * the array form optimised for is negligible against an unbounded array.
  */
 function _directFn(this: SignalFn<unknown>, updater: () => void): () => void {
-  if (!this._d) this._d = []
-  const arr = this._d
-  const idx = arr.length
-  arr.push(updater)
+  if (!this._d) this._d = new Set()
+  const set = this._d
+  set.add(updater)
   return () => {
-    arr[idx] = null
+    set.delete(updater)
   }
 }
 
 /**
- * Notify direct updaters — flat array iteration, batch-aware.
- * Null slots (from disposed updaters) are skipped.
+ * Notify direct updaters — set iteration, batch-aware. Disposed updaters
+ * are already absent from the set (O(1) delete on disposal).
  */
-function notifyDirect(updaters: ((() => void) | null)[]): void {
+function notifyDirect(updaters: Set<() => void>): void {
   if (isBatching()) {
-    for (let i = 0; i < updaters.length; i++) {
-      const fn = updaters[i]
-      if (fn) enqueuePendingNotification(fn)
-    }
+    for (const fn of updaters) enqueuePendingNotification(fn)
   } else {
-    for (let i = 0; i < updaters.length; i++) {
-      updaters[i]?.()
-    }
+    for (const fn of updaters) fn()
   }
 }
 

package/src/store.ts

@@ -179,6 +179,17 @@ function wrap(raw: object, shallow: boolean): object {
         return true
       }
 
+      // Defense-in-depth against prototype pollution: a bare
+      // `target.__proto__ = obj` here would mutate the store object's
+      // prototype rather than set a property. `reconcile()` already
+      // filters these, but the proxy is the public write surface
+      // (`store.__proto__ = …`, spread of untrusted data) so guard here
+      // too. Silently ignore — assigning these through a store is never
+      // a legitimate operation.
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        return true
+      }
+
       const prevLength = isArray ? (target as unknown[]).length : 0
       ;(target as Record<PropertyKey, unknown>)[key] = value
 

package/src/tests/computed.test.ts

@@ -198,6 +198,37 @@ describe('computed', () => {
     expect(called).toBe(2) // equals suppresses
   })
 
+  test('.direct() registrations do not accumulate under churn (bounded, like signal._d)', () => {
+    // Regression for the never-compacted-array leak: a long-lived
+    // computed whose direct updaters register+dispose repeatedly (e.g.
+    // <For> rows re-mounting) must keep its live set bounded to LIVE
+    // registrations, not grow one permanent dead slot per ever-
+    // registered binding (which also made `recompute` O(total-ever)).
+    const s = signal(0)
+    const c = computed(() => s() * 2)
+    c() // initialize
+    const internal = c as unknown as { _d: Set<() => void> | null }
+
+    for (let i = 0; i < 10_000; i++) {
+      const dispose = c.direct(() => {})
+      dispose()
+    }
+    expect(internal._d!.size).toBe(0)
+
+    // One live binding survives → notify/iterate cost is O(live), not 10k.
+    let fired = 0
+    const dispose = c.direct(() => {
+      fired++
+    })
+    expect(internal._d!.size).toBe(1)
+    s.set(1)
+    expect(fired).toBe(1)
+    dispose()
+    expect(internal._d!.size).toBe(0)
+    s.set(2)
+    expect(fired).toBe(1) // disposed updater not invoked
+  })
+
   describe('_v with equals after disposal', () => {
     test('_v returns last cached value after dispose()', () => {
       const s = signal(5)