@pyreon/reactivity 0.18.0 → 0.20.0

package/lib/types/index.d.ts

@@ -133,9 +133,9 @@ 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;
   /**
@@ -209,6 +209,130 @@ declare function why(): void;
  */
 declare function inspectSignal<T>(sig: Signal<T>): SignalDebugInfo<T>;
 //#endregion
+//#region src/reactive-devtools.d.ts
+/**
+ * Reactive devtools bridge — an OPT-IN, leak-free introspection layer
+ * over the live signal / computed / effect graph.
+ *
+ * Powers the `@pyreon/devtools` Signals / Graph / Effects / Console
+ * surfaces. Design constraints (mirroring `reactive-trace.ts`):
+ *
+ *   - **Zero cost until attached.** Every instrumentation entry point
+ *     early-returns on `!_active`. The registry is empty and no work
+ *     happens until a devtools client calls `activateReactiveDevtools()`.
+ *     The single call site per creation/track sits inside the existing
+ *     `process.env.NODE_ENV !== 'production'` gate (tree-shaken in prod)
+ *     and is structurally identical to the perf-harness counter calls
+ *     and `_recordSignalWrite` already on those paths.
+ *   - **No retention / no leak.** Nodes are held via `WeakRef` and
+ *     pruned by a `FinalizationRegistry`. The registry never pins a
+ *     signal/computed/effect alive. Edges + the fire ring buffer hold
+ *     only numeric ids and primitives, never node references or values.
+ *   - **Snapshot on demand.** `getReactiveGraph()` recomputes the edge
+ *     set fresh from the live subscriber Sets — no incremental
+ *     bookkeeping to drift out of sync with `cleanupEffect`.
+ *
+ * Names: signals carry `.label` (set explicitly or by the vite plugin's
+ * dev auto-naming). Computeds/effects have no name in the framework, so
+ * they get a stable synthetic label (`derived#12` / `effect#7`).
+ */
+type ReactiveNodeKind = 'signal' | 'derived' | 'effect';
+interface ReactiveNode {
+  id: number;
+  kind: ReactiveNodeKind;
+  /** Explicit `.label` for signals; synthetic (`derived#id`) otherwise. */
+  name: string;
+  /** Bounded string preview of the current value (signals/derived only). */
+  value: string;
+  /** Live downstream subscriber count. */
+  subscribers: number;
+  /** Total times this node has fired/recomputed since activation. */
+  fires: number;
+  /** `performance.now()` of the most recent fire, or null. */
+  lastFire: number | null;
+}
+interface ReactiveEdge {
+  /** Source node id (the reactive value being read). */
+  from: number;
+  /** Subscriber node id (the computed/effect that read it). */
+  to: number;
+}
+interface ReactiveGraph {
+  nodes: ReactiveNode[];
+  edges: ReactiveEdge[];
+}
+interface ReactiveFire {
+  id: number;
+  /** `performance.now()` at fire time. */
+  ts: number;
+}
+/** Activate the bridge. Idempotent. Called when a devtools client attaches. */
+declare function activateReactiveDevtools(): void;
+/**
+ * Deactivate + drop all retained state. Called when the devtools client
+ * disconnects so a closed panel leaves zero residue.
+ */
+declare function deactivateReactiveDevtools(): void;
+declare function isReactiveDevtoolsActive(): boolean;
+/**
+ * Fresh snapshot of the live reactive graph. Edges are recomputed from
+ * each live node's current subscriber Set — always consistent with the
+ * framework's real subscription state, no incremental drift.
+ */
+declare function getReactiveGraph(): ReactiveGraph;
+/** Bounded recent-fire timeline (oldest → newest). Fresh copy. */
+declare function getReactiveFires(): ReactiveFire[];
+//#endregion
+//#region src/reactive-trace.d.ts
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+declare function getReactiveTrace(): ReactiveTraceEntry[];
+/** Clears the buffer. For test isolation; not part of the app-facing API. */
+declare function clearReactiveTrace(): void;
+//#endregion
 //#region src/effect.d.ts
 interface Effect {
   dispose(): void;
@@ -465,5 +589,5 @@ interface WatchOptions {
  */
 declare function watch<T>(source: () => T, callback: (newVal: T, oldVal: T | undefined) => void | (() => void), opts?: WatchOptions): () => void;
 //#endregion
-export { Cell, type Computed, type ComputedOptions, type Effect, EffectScope, type ReactiveSnapshotCapture, type ReadonlySignal, type Resource, type Signal, type SignalDebugInfo, type SignalOptions, type WatchOptions, _bind, batch, cell, computed, createResource, createSelector, createStore, effect, effectScope, getCurrentScope, inspectSignal, isStore, markRaw, nextTick, onCleanup, onScopeDispose, onSignalUpdate, reconcile, renderEffect, runUntracked, runUntracked as untrack, setCurrentScope, setErrorHandler, setSnapshotCapture, shallowReactive, signal, watch, why };
+export { Cell, type Computed, type ComputedOptions, type Effect, EffectScope, type ReactiveEdge, type ReactiveFire, type ReactiveGraph, type ReactiveNode, type ReactiveNodeKind, type ReactiveSnapshotCapture, type ReactiveTraceEntry, type ReadonlySignal, type Resource, type Signal, type SignalDebugInfo, type SignalOptions, type WatchOptions, _bind, activateReactiveDevtools, batch, cell, clearReactiveTrace, computed, createResource, createSelector, createStore, deactivateReactiveDevtools, effect, effectScope, getCurrentScope, getReactiveFires, getReactiveGraph, getReactiveTrace, inspectSignal, isReactiveDevtoolsActive, isStore, markRaw, nextTick, onCleanup, onScopeDispose, onSignalUpdate, reconcile, renderEffect, runUntracked, runUntracked as untrack, setCurrentScope, setErrorHandler, setSnapshotCapture, shallowReactive, signal, watch, why };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/reactivity",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Signals-based reactivity system for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/reactivity#readme",
   "bugs": {

package/src/computed.ts

@@ -1,5 +1,6 @@
 import { _markRecompute } from './batch'
 import { _errorHandler } from './effect'
+import { _rdRecordFire, _rdRegister } from './reactive-devtools'
 import { getCurrentScope } from './scope'
 import {
   cleanupEffect,
@@ -87,21 +88,31 @@ function computedLazy<T>(fn: () => T): Computed<T> {
   let tracked = false
   const deps: Set<() => void>[] = []
   const host: { _s: Set<() => void> | null } = { _s: null }
-  let directFns: ((() => void) | null)[] | null = null
+  // Set, not a never-compacted flat array. The array form's disposal
+  // only nulled the slot (`arr[idx] = null`) and never shrank, so a
+  // long-lived computed (a derived theme/locale/auth value, or one read
+  // inside churning `<For>` rows) bound by mount/unmount churn grew one
+  // permanent dead slot per ever-registered binding — app-lifetime
+  // memory growth AND `recompute` iterating O(total-ever) instead of
+  // O(live). Identical bug class already fixed for `signal._d`
+  // (signal.ts `_directFn`); `computed` was left on the broken pattern.
+  let directFns: Set<() => void> | null = null
 
   const recompute = () => {
     if (disposed || dirty) return
     dirty = true
     if (host._s) notifySubscribers(host._s)
-    if (directFns) for (const f of directFns) f?.()
+    if (directFns) for (const f of directFns) f()
   }
   _markRecompute(recompute)
 
   const read = (): T => {
     trackSubscriber(host)
     if (dirty) {
-      if (process.env.NODE_ENV !== 'production')
+      if (process.env.NODE_ENV !== 'production') {
         _countSink.__pyreon_count__?.('reactivity.computedRecompute')
+        _rdRecordFire(read)
+      }
       try {
         if (tracked) {
           // Deps already established from first run — skip adding to
@@ -136,16 +147,26 @@ function computedLazy<T>(fn: () => T): Computed<T> {
     enumerable: false,
   })
 
+  // @internal — mirrors `signal._d`. Lets tests deterministically assert
+  // the live direct-updater set stays BOUNDED under register/dispose
+  // churn (the never-compacted-array leak this fix removes).
+  Object.defineProperty(read, '_d', {
+    get: () => directFns,
+    enumerable: false,
+  })
+
   read.direct = (updater: () => void): (() => void) => {
-    if (!directFns) directFns = []
-    const arr = directFns
-    const idx = arr.length
-    arr.push(updater)
+    if (!directFns) directFns = new Set()
+    const set = directFns
+    set.add(updater)
     return () => {
-      arr[idx] = null
+      set.delete(updater)
     }
   }
 
+  if (process.env.NODE_ENV !== 'production')
+    _rdRegister(read, 'derived', host, recompute, undefined)
+
   getCurrentScope()?.add({ dispose: read.dispose })
   return read as Computed<T>
 }
@@ -163,12 +184,22 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
   let disposed = false
   const deps: Set<() => void>[] = []
   const host: { _s: Set<() => void> | null } = { _s: null }
-  let directFns: ((() => void) | null)[] | null = null
+  // Set, not a never-compacted flat array. The array form's disposal
+  // only nulled the slot (`arr[idx] = null`) and never shrank, so a
+  // long-lived computed (a derived theme/locale/auth value, or one read
+  // inside churning `<For>` rows) bound by mount/unmount churn grew one
+  // permanent dead slot per ever-registered binding — app-lifetime
+  // memory growth AND `recompute` iterating O(total-ever) instead of
+  // O(live). Identical bug class already fixed for `signal._d`
+  // (signal.ts `_directFn`); `computed` was left on the broken pattern.
+  let directFns: Set<() => void> | null = null
 
   const recompute = () => {
     if (disposed) return
-    if (process.env.NODE_ENV !== 'production')
+    if (process.env.NODE_ENV !== 'production') {
       _countSink.__pyreon_count__?.('reactivity.computedRecompute')
+      _rdRecordFire(read)
+    }
     cleanupLocalDeps(deps, recompute)
     try {
       const next = trackWithLocalDeps(deps, recompute, fn)
@@ -181,7 +212,7 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
       return
     }
     if (host._s) notifySubscribers(host._s)
-    if (directFns) for (const f of directFns) f?.()
+    if (directFns) for (const f of directFns) f()
   }
   _markRecompute(recompute)
 
@@ -216,16 +247,26 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
     enumerable: false,
   })
 
+  // @internal — mirrors `signal._d`. Lets tests deterministically assert
+  // the live direct-updater set stays BOUNDED under register/dispose
+  // churn (the never-compacted-array leak this fix removes).
+  Object.defineProperty(read, '_d', {
+    get: () => directFns,
+    enumerable: false,
+  })
+
   read.direct = (updater: () => void): (() => void) => {
-    if (!directFns) directFns = []
-    const arr = directFns
-    const idx = arr.length
-    arr.push(updater)
+    if (!directFns) directFns = new Set()
+    const set = directFns
+    set.add(updater)
     return () => {
-      arr[idx] = null
+      set.delete(updater)
     }
   }
 
+  if (process.env.NODE_ENV !== 'production')
+    _rdRegister(read, 'derived', host, recompute, undefined)
+
   getCurrentScope()?.add({ dispose: read.dispose })
   return read as Computed<T>
 }

package/src/effect.ts

@@ -1,3 +1,4 @@
+import { _rdRecordFire, _rdRegister } from './reactive-devtools'
 import { getCurrentScope } from './scope'
 import { _restoreActiveEffect, _setActiveEffect, setDepsCollector, withTracking } from './tracking'
 
@@ -102,6 +103,11 @@ interface PyreonErrorBridge {
 const _errorBridge = globalThis as PyreonErrorBridge
 
 function _defaultErrorHandler(err: unknown): void {
+  // Last-resort unhandled-effect-error reporter — MUST fire in
+  // production (silently swallowing uncaught effect errors is a
+  // serious bug; React/Vue/Solid all log uncaught errors in prod).
+  // Deliberately not __DEV__-gated.
+  // pyreon-lint-disable-next-line pyreon/dev-guard-warnings
   console.error('[pyreon] Unhandled effect error:', err)
 }
 
@@ -206,8 +212,10 @@ export function effect(fn: () => (() => void) | void): Effect {
 
   const run = () => {
     if (disposed) return
-    if (process.env.NODE_ENV !== 'production')
+    if (process.env.NODE_ENV !== 'production') {
       _countSink.__pyreon_count__?.('reactivity.effectRun')
+      _rdRecordFire(run)
+    }
     // Run previous cleanup before re-running
     runCleanup()
     // Start a new inner-effect collection window. Effects created during
@@ -249,6 +257,9 @@ export function effect(fn: () => (() => void) | void): Effect {
     isFirstRun = false
   }
 
+  if (process.env.NODE_ENV !== 'production')
+    _rdRegister(run, 'effect', null, run, undefined)
+
   run()
 
   const e: Effect = {
@@ -404,6 +415,9 @@ export function renderEffect(fn: () => void): () => void {
     }
   }
 
+  if (process.env.NODE_ENV !== 'production')
+    _rdRegister(run, 'effect', null, run, undefined)
+
   run()
 
   const dispose = () => {

package/src/index.ts

@@ -5,6 +5,22 @@ export { Cell, cell } from './cell'
 export { type Computed, type ComputedOptions, computed } from './computed'
 export { createSelector } from './createSelector'
 export { inspectSignal, onSignalUpdate, why } from './debug'
+export type {
+  ReactiveEdge,
+  ReactiveFire,
+  ReactiveGraph,
+  ReactiveNode,
+  ReactiveNodeKind,
+} from './reactive-devtools'
+export {
+  activateReactiveDevtools,
+  deactivateReactiveDevtools,
+  getReactiveFires,
+  getReactiveGraph,
+  isReactiveDevtoolsActive,
+} from './reactive-devtools'
+export type { ReactiveTraceEntry } from './reactive-trace'
+export { clearReactiveTrace, getReactiveTrace } from './reactive-trace'
 export {
   _bind,
   type Effect,

package/src/manifest.ts

@@ -58,7 +58,7 @@ effect(() => {
     'createStore() / reconcile() / isStore() — deeply reactive proxy stores + structural diff',
     'effectScope() / getCurrentScope() — scope-based lifecycle management',
     'untrack() — read without subscribing',
-    'onSignalUpdate() / inspectSignal() / why() — debug instrumentation',
+    'onSignalUpdate() / inspectSignal() / why() / getReactiveTrace() — debug instrumentation',
     'setErrorHandler() — global hook for unhandled effect errors',
     'Standalone — zero DOM, zero JSX, zero framework dependency',
   ],
@@ -553,6 +553,27 @@ why()         // disarm + dump transcript:
       ],
       seeAlso: ['onSignalUpdate', 'inspectSignal'],
     },
+    {
+      name: 'getReactiveTrace',
+      kind: 'function',
+      signature:
+        '() => Array<{ name: string | undefined; prev: string; next: string; timestamp: number }>',
+      summary:
+        'Returns the last ~50 signal writes (chronological, oldest → newest) from a bounded dev-only ring buffer — the causal SEQUENCE of reactive state changes, not a point-in-time snapshot. `@pyreon/core` attaches this to `ErrorContext.reactiveTrace` automatically so error reports carry "what changed in the run-up to the crash". Entries hold bounded string previews of values (never raw refs — no memory pinning, always serializable). **Dev-only**: the recorder feeding the buffer is behind the production dead-code gate and tree-shakes out, so this returns `[]` in prod builds. Distinct from `onSignalUpdate` — that is opt-in and captures stacks; this is always-on, deliberately cheap, and exists to enrich error reports. `clearReactiveTrace()` resets it (test isolation).',
+      example: `import { getReactiveTrace, clearReactiveTrace, signal } from '@pyreon/reactivity'
+
+const status = signal('idle', { name: 'status' })
+status.set('submitting')
+getReactiveTrace()
+// [{ name: 'status', prev: '"idle"', next: '"submitting"', timestamp: 1234.5 }]
+clearReactiveTrace()  // → []`,
+      mistakes: [
+        'Expecting it to return signal VALUES — it returns string PREVIEWS (truncated, safely stringified). For live values inspect the signal directly',
+        'Relying on it in production — returns `[]` (the recorder is dev-gated and tree-shaken). Use it for dev tooling / error-report enrichment, not runtime logic',
+        'Treating it as a snapshot of all signals — it is a bounded ring of recent WRITES; signals never written (or written before the ~50-entry window) are absent',
+      ],
+      seeAlso: ['onSignalUpdate', 'inspectSignal'],
+    },
     {
       name: 'setErrorHandler',
       kind: 'function',
@@ -575,6 +596,52 @@ count.set(101)  // logs/reports via handler instead of crashing`,
       ],
       seeAlso: ['effect', 'renderEffect'],
     },
+    {
+      name: 'activateReactiveDevtools',
+      kind: 'function',
+      signature:
+        'activateReactiveDevtools(): void  ·  deactivateReactiveDevtools(): void  ·  isReactiveDevtoolsActive(): boolean',
+      summary:
+        'Opt-in lifecycle for the reactive-devtools bridge — the live signal/computed/effect graph the `@pyreon/devtools` Signals/Graph/Effects/Profiler tabs consume (surfaced on the browser hook as `window.__PYREON_DEVTOOLS__.reactive`). **Zero cost until activated**: every per-primitive instrumentation point early-returns on the inactive flag and sits inside the production dead-code gate, so it tree-shakes out of prod builds entirely (locked by a minified-bundle test) and, in dev, costs one predicted-false branch until a devtools client calls `activate()` — the same risk profile as the adjacent reactive-trace / perf-harness calls. `deactivate()` drops all retained registry + fire-buffer state (a closed panel leaves zero residue). Leak-free by construction: nodes are held via `WeakRef` + `FinalizationRegistry`, never pinned.',
+      example: `import { activateReactiveDevtools, getReactiveGraph } from '@pyreon/reactivity'
+
+// Only AFTER activation are subsequently-created signals tracked.
+activateReactiveDevtools()
+const price = signal(10, { name: '$price' })
+const total = computed(() => price() * 2)
+effect(() => total())
+getReactiveGraph().nodes // → [$price (signal), derived, effect]
+deactivateReactiveDevtools() // → registry cleared`,
+      mistakes: [
+        'Expecting nodes created BEFORE `activate()` to appear — registration is gated on the active flag (mirrors a devtools panel attaching). Activate first, then build/observe the graph',
+        'Calling it in production for app logic — the whole bridge is dev-gated and tree-shaken; `getReactiveGraph()` returns an empty graph in prod builds',
+        'Assuming it tracks compiler-emitted DOM bindings — only user `signal()` / `computed()` / `effect()` are registered; `renderEffect` / `_bind` plumbing is intentionally excluded (it would flood the graph and tax the hottest path)',
+      ],
+      seeAlso: ['getReactiveGraph', 'onSignalUpdate', 'getReactiveTrace'],
+    },
+    {
+      name: 'getReactiveGraph',
+      kind: 'function',
+      signature:
+        'getReactiveGraph(): { nodes: ReactiveNode[]; edges: { from: number; to: number }[] }  ·  getReactiveFires(): { id: number; ts: number }[]',
+      summary:
+        'Fresh snapshot of the live reactive graph + a bounded recent-fire timeline, for the reactive-devtools tabs. `getReactiveGraph()` returns every tracked node (`{ id, kind: "signal"|"derived"|"effect", name, value, subscribers, fires, lastFire }`) plus dependency edges recomputed on demand from the real subscriber `_s` Sets (source → subscriber: signal→derived, derived→effect) — always consistent with the framework’s actual subscription state, no incremental drift. `getReactiveFires()` returns a fixed-size ring buffer of recent fires (`{ id, ts }`, oldest → newest) powering the Effects/Profiler tabs. Both require `activateReactiveDevtools()` first and return empty otherwise. Names come from `signal(v, { name })` / the vite-plugin dev auto-naming; anonymous computeds/effects get a synthetic `derived#id` / `effect#id`.',
+      example: `activateReactiveDevtools()
+const a = signal(1, { name: '$a' })
+const b = computed(() => a() + 1)
+effect(() => b())
+a.set(2)
+getReactiveGraph()
+// nodes: [{ name:'$a', kind:'signal', value:'2', … }, { kind:'derived', … }, { kind:'effect', … }]
+// edges: [{ from:$a, to:derived }, { from:derived, to:effect }]
+getReactiveFires() // → [{ id, ts }, …]  (bounded, chronological)`,
+      mistakes: [
+        'Holding the returned arrays expecting them to update — they are point-in-time snapshots; call again (the devtools panel polls)',
+        'Reading `node.value` for non-string state as the real value — it is a bounded, safely-stringified PREVIEW (never a raw ref — no pinning). Inspect the signal directly for the live value',
+        'Expecting fires for every write in a long-running app — `getReactiveFires()` is a fixed-size ring; older entries roll off',
+      ],
+      seeAlso: ['activateReactiveDevtools', 'getReactiveTrace', 'onSignalUpdate'],
+    },
   ],
   gotchas: [
     {