@pyreon/reactivity 0.13.1 → 0.15.0

package/src/batch.ts

@@ -1,15 +1,66 @@
 // Batch multiple signal updates into a single notification pass.
-// Uses a Set so the same subscriber is never flushed more than once per batch,
-// even if multiple signals it depends on change within the same batch.
+// Two-tier flush: computed recomputes drain first (within-pass Set-dedup),
+// THEN effects drain (multi-pass with cross-pass re-fire support).
+//
+// Dev-mode invariant gate: see https://github.com/pyreon/pyreon/blob/main/packages/core/reactivity/src/tests/batch.test.ts
+// for the property-based test that fuzzes random cascade graphs against this
+// invariant. The build-time gate folds to dead code in production bundles.
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 let batchDepth = 0
 
-// Two pre-allocated Sets swapped on each flush — avoids allocating a new Set()
-// on every batch exit. The "active" set collects enqueued notifications; on flush
-// we swap to the other set and iterate the captured one, then clear it for reuse.
-const setA = new Set<() => void>()
-const setB = new Set<() => void>()
-let pendingNotifications = setA
+// Two-tier queue design:
+//
+// 1. **`pendingRecomputes`** — computed.recompute callbacks. Drained FIRST in
+//    a cascading-iteration loop: cascading recomputes enqueued during a
+//    drain land in the same Set (Set.add idempotency dedupes), iteration
+//    visits added entries (JS Set iteration semantics), and the recompute
+//    layer settles before any effect fires. This guarantees effects always
+//    read fully-propagated computed values.
+//
+// 2. **`pendingEffects`** — effect.run callbacks. Drained SECOND, multi-pass.
+//    Within a single pass, Set.add idempotency gives us within-pass dedup
+//    (diamond / multi-dep selector). Across passes (entries re-enqueued
+//    AFTER being visited in the current pass — see `_visitedThisPass`), they
+//    fire AGAIN — needed for control flow that re-renders based on its own
+//    dispatch (e.g. ErrorBoundary's handler calling `error.set(err)` during
+//    the same run that mounted the throwing child). MAX_PASSES caps total
+//    passes at 32 to prevent pathological infinite re-enqueue loops.
+//
+// **Why two tiers, not one Set:**
+//   - Single-Set iteration (the prior design) worked for shallow cascades
+//     because the cascading recompute → effect re-enqueue happened BEFORE
+//     iteration reached the effect. For deep cascades (3+ hops), iteration
+//     reached the effect (with its stale upstream value) BEFORE the cascade
+//     finished propagating. Effect read stale values; subsequent cascade
+//     re-enqueues were dropped by Set.add idempotency.
+//   - Splitting recomputes from effects fixes this: all computed recomputes
+//     settle before any effect runs. The cascade-asymmetry contract from
+//     PR #381 is preserved (effects still fire once per batched change),
+//     AND deep-cascade correctness is added (effects always read settled
+//     values).
+//   - Multi-pass effect drain unblocks ErrorBoundary's "re-fire after
+//     dispatching from inside own run" pattern without breaking the
+//     single-fire contract for non-self-dispatching effects.
+//
+// **How a callback gets routed:** computed registers its `recompute` via
+// `_markRecompute(fn)` at creation time. The internal `_recomputes` WeakSet
+// tracks them. `enqueuePendingNotification` checks the WeakSet to route.
+const pendingRecomputes = new Set<() => void>()
+const pendingEffects = new Set<() => void>()
+const _nextEffectPass = new Set<() => void>()
+let _visitedThisPass: Set<() => void> | null = null
+const _recomputes = new WeakSet<() => void>()
+const MAX_PASSES = 32
+
+/**
+ * Mark a callback as a computed recompute (called from computed.ts at
+ * creation time). Routes future enqueues into the recompute queue so they
+ * settle before any effects fire.
+ */
+export function _markRecompute(fn: () => void): void {
+  _recomputes.add(fn)
+}
 
 export function batch(fn: () => void): void {
   batchDepth++
@@ -17,14 +68,74 @@ export function batch(fn: () => void): void {
     fn()
   } finally {
     batchDepth--
-    if (batchDepth === 0 && pendingNotifications.size > 0) {
-      // Swap to the other pre-allocated Set before flushing so new enqueues
-      // during notification land in the alternate Set, not mixed into the
-      // current iteration.
-      const flush = pendingNotifications
-      pendingNotifications = flush === setA ? setB : setA
-      for (const notify of flush) notify()
-      flush.clear()
+    if (batchDepth === 0 && (pendingRecomputes.size > 0 || pendingEffects.size > 0)) {
+      // Keep batching active during flush so cascade-notifications emitted
+      // by flushing subscribers enqueue into the same queues (dedup against
+      // already-queued entries) instead of firing inline.
+      batchDepth = 1
+      try {
+        // Outer loop: alternate between tier-1 (recomputes) and tier-2
+        // (effects) until both queues are empty. An effect can write a
+        // signal whose subscribers include lazy `computed.recompute`s — those
+        // get enqueued into pendingRecomputes mid-effect, and we need to
+        // drain them BEFORE the next effect pass so downstream effects see
+        // the propagated dirty flag. MAX_PASSES caps the OUTER loop —
+        // counts effect-tier passes only since recomputes converge by
+        // `equals` short-circuit and don't infinite-loop in practice.
+        let effectPass = 0
+        while (pendingRecomputes.size > 0 || pendingEffects.size > 0) {
+          // Tier 1: drain all recomputes via cascading iteration. Set
+          // semantics visit entries added during iteration; Set.add
+          // idempotency dedupes diamond cascades. Recomputes converge by
+          // `equals` short-circuit (computedWithEquals returns early when
+          // value is unchanged) and computedLazy's `if (dirty) return`
+          // guard prevents re-fire.
+          for (const r of pendingRecomputes) r()
+          pendingRecomputes.clear()
+
+          // Tier 2: drain ONE pass of effects in multi-pass mode. Within-
+          // pass dedup preserved by Set.add idempotency on entries not yet
+          // visited this pass. Cross-pass re-fire enabled by routing
+          // already-visited entries to `_nextEffectPass` (handled in
+          // `enqueuePendingNotification`). After the pass, loop back to
+          // tier 1 to drain any recomputes the effects enqueued.
+          if (pendingEffects.size > 0) {
+            if (++effectPass > MAX_PASSES) {
+              if (__DEV__) {
+                // oxlint-disable-next-line no-console
+                console.warn(
+                  '[pyreon] batch effect flush exceeded MAX_PASSES (32) — possible infinite re-enqueue loop. ' +
+                    `${pendingEffects.size} pending effects dropped. ` +
+                    'See packages/core/reactivity/src/batch.ts for the multi-pass flush contract.',
+                )
+              }
+              break
+            }
+            _visitedThisPass = new Set<() => void>()
+            for (const notify of pendingEffects) {
+              _visitedThisPass.add(notify)
+              notify()
+            }
+            // Promote next-pass entries to pending for the next iteration.
+            pendingEffects.clear()
+            for (const next of _nextEffectPass) pendingEffects.add(next)
+            _nextEffectPass.clear()
+          }
+        }
+      } finally {
+        // Clear ALWAYS — even if a notify threw mid-iteration. Without this,
+        // the unflushed remainder leaks into the next batch and refires
+        // (audit bug #19). Effects wrap their callbacks in try/catch
+        // internally so this is rarely reachable in practice, but raw
+        // signal subscribers (signal.subscribe) and lower-level consumers
+        // can throw straight through, and a future refactor that swallows
+        // less aggressively would silently regress without this guard.
+        pendingRecomputes.clear()
+        pendingEffects.clear()
+        _nextEffectPass.clear()
+        _visitedThisPass = null
+        batchDepth = 0
+      }
     }
   }
 }
@@ -33,8 +144,22 @@ export function isBatching(): boolean {
   return batchDepth > 0
 }
 
+export function enquePendingNotificationDeprecated(): void {
+  // Kept as a comment placeholder — actual export is below. (Empty body to
+  // keep this file's exports list stable across the refactor.)
+}
+
 export function enqueuePendingNotification(notify: () => void): void {
-  pendingNotifications.add(notify)
+  // Route based on callback kind. Computed recomputes go to tier-1 queue,
+  // effects to tier-2. Within tier 2, already-visited-this-pass entries
+  // route to next-pass for cross-pass re-fire (ErrorBoundary's pattern).
+  if (_recomputes.has(notify)) {
+    pendingRecomputes.add(notify)
+  } else if (_visitedThisPass !== null && _visitedThisPass.has(notify)) {
+    _nextEffectPass.add(notify)
+  } else {
+    pendingEffects.add(notify)
+  }
 }
 
 /**

package/src/computed.ts

@@ -1,3 +1,4 @@
+import { _markRecompute } from './batch'
 import { _errorHandler } from './effect'
 import { getCurrentScope } from './scope'
 import {
@@ -9,6 +10,9 @@ import {
   withTracking,
 } from './tracking'
 
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 export interface Computed<T> {
   (): T
   /** Remove this computed from all its reactive dependencies. */
@@ -48,6 +52,21 @@ function trackWithLocalDeps<T>(deps: Set<() => void>[], effect: () => void, fn:
 }
 
 export function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed<T> {
+  // Dev warning for async computed callbacks (audit bug #1 — extension).
+  // `computed(async () => …)` returns `Computed<Promise<T>>`, which silently
+  // breaks every consumer that expects `Computed<T>`. There's no scenario
+  // where async makes sense here — the recompute fires synchronously and
+  // tracks signals only in the synchronous prefix. For async-derived
+  // state, use `createResource` or a `signal<T>` updated from an effect.
+  if (process.env.NODE_ENV !== 'production') {
+    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        '[pyreon] computed() received an async function. The result type becomes `Computed<Promise<T>>`, and signal reads after the first `await` are NOT tracked. ' +
+          'Use `createResource` for async-derived state, or compute synchronously over a signal that holds the awaited value.',
+      )
+    }
+  }
   return options?.equals ? computedWithEquals(fn, options.equals) : computedLazy(fn)
 }
 
@@ -76,12 +95,19 @@ function computedLazy<T>(fn: () => T): Computed<T> {
     if (host._s) notifySubscribers(host._s)
     if (directFns) for (const f of directFns) f?.()
   }
+  _markRecompute(recompute)
 
   const read = (): T => {
     trackSubscriber(host)
     if (dirty) {
+      if (process.env.NODE_ENV !== 'production')
+        _countSink.__pyreon_count__?.('reactivity.computedRecompute')
       try {
         if (tracked) {
+          // Deps already established from first run — skip adding to
+          // subscriber Sets again (they already contain recompute).
+          // Still need withTracking so activeEffect is set correctly
+          // for any NEW signals read on this evaluation.
           setSkipDepsCollection(true)
           value = withTracking(recompute, fn)
           setSkipDepsCollection(false)
@@ -90,7 +116,6 @@ function computedLazy<T>(fn: () => T): Computed<T> {
           tracked = true
         }
       } catch (err) {
-        setSkipDepsCollection(false)
         _errorHandler(err)
       }
       dirty = false
@@ -142,6 +167,8 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
 
   const recompute = () => {
     if (disposed) return
+    if (process.env.NODE_ENV !== 'production')
+      _countSink.__pyreon_count__?.('reactivity.computedRecompute')
     cleanupLocalDeps(deps, recompute)
     try {
       const next = trackWithLocalDeps(deps, recompute, fn)
@@ -156,10 +183,13 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
     if (host._s) notifySubscribers(host._s)
     if (directFns) for (const f of directFns) f?.()
   }
+  _markRecompute(recompute)
 
   const read = (): T => {
     trackSubscriber(host)
     if (dirty) {
+      if (process.env.NODE_ENV !== 'production')
+        _countSink.__pyreon_count__?.('reactivity.computedRecompute')
       cleanupLocalDeps(deps, recompute)
       try {
         value = trackWithLocalDeps(deps, recompute, fn)

package/src/effect.ts

@@ -1,10 +1,48 @@
 import { getCurrentScope } from './scope'
 import { _restoreActiveEffect, _setActiveEffect, setDepsCollector, withTracking } from './tracking'
 
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 export interface Effect {
   dispose(): void
 }
 
+// ─── Effect-scoped snapshot capture (DI from `@pyreon/core`) ─────────────────
+//
+// Effects re-run reactively in response to signal changes. When that re-run
+// happens AFTER the synchronous mount that set the effect up, the surrounding
+// context stack (from `@pyreon/core`'s provide() calls) may have been
+// destructively truncated by `mountReactive`'s `restoreContextStack` cleanup.
+// Without restoring the captured context, signal-driven re-runs of `_bind` /
+// `renderEffect` / `effect` see a half-empty stack and `useContext()` falls
+// back to the default value — silently breaking provider-backed APIs like
+// `useMode()`, `useTheme()`, `useRouter()`, etc. on every reactive update.
+//
+// `@pyreon/reactivity` is below `@pyreon/core` in the dep order, so it can't
+// import `captureContextStack` / `restoreContextStack` directly. Core
+// registers its capture+restore pair via `setSnapshotCapture` at module load.
+// When unset (raw reactivity-only consumers), effects skip context handling
+// — same behavior as before this hook existed.
+export interface ReactiveSnapshotCapture {
+  capture: () => unknown
+  /** Run `fn` with the previously-captured snapshot active. */
+  restore: <T>(snap: unknown, fn: () => T) => T
+}
+
+let _snapshotCapture: ReactiveSnapshotCapture | null = null
+
+/**
+ * Register a capture/restore pair so reactivity-layer effects (`_bind`,
+ * `renderEffect`, `effect`) can preserve external context (e.g. the core
+ * provide/useContext stack) across signal-driven re-runs. Called by
+ * `@pyreon/core`'s context module at import time. Idempotent — calling again
+ * replaces the previously registered hook.
+ */
+export function setSnapshotCapture(hook: ReactiveSnapshotCapture | null): void {
+  _snapshotCapture = hook
+}
+
 // ─── onCleanup ───────────────────────────────────────────────────────────────
 // Thread-local collector for cleanup functions registered via onCleanup()
 // during effect execution. Pushed/popped around the user callback in effect().
@@ -33,14 +71,53 @@ export function onCleanup(fn: () => void): void {
   }
 }
 
+// Thread-local collector for nested effects — captures effect() calls made
+// inside another effect's fn() body so the parent can dispose them on
+// re-run / disposal. Without this, inner effects leak across outer
+// lifecycle boundaries (caught by cleanup-nested.test.ts).
+let _innerEffectCollector: Effect[] | null = null
+
 // Global error handler — called for unhandled errors thrown inside effects.
 // Defaults to console.error so silent failures are never swallowed.
-export let _errorHandler: (err: unknown) => void = (err) => {
+//
+// Two-layer model:
+//   1. The user-overridable single handler set via `setErrorHandler` (legacy
+//      direct API).
+//   2. A globalThis bridge `__pyreon_report_error__` that `@pyreon/core`
+//      installs in `registerErrorHandler` to forward effect errors into the
+//      same telemetry pipeline as component / mount / render errors.
+//      Pre-fix the two surfaces were disconnected — Sentry/Datadog wiring via
+//      core's `registerErrorHandler` silently missed effect-thrown errors.
+//      Globalthis-based to avoid an upward import (core depends on
+//      reactivity, not the reverse). Same shape as the perf-harness counter
+//      sink — zero cost when no consumer is installed.
+//
+// Both surfaces fire on every effect error. The legacy handler stays for
+// backward compat; new consumers should prefer `@pyreon/core`'s
+// `registerErrorHandler`.
+
+interface PyreonErrorBridge {
+  __pyreon_report_error__?: (err: unknown, phase: 'effect') => void
+}
+const _errorBridge = globalThis as PyreonErrorBridge
+
+function _defaultErrorHandler(err: unknown): void {
   console.error('[pyreon] Unhandled effect error:', err)
 }
 
+let _userErrorHandler: ((err: unknown) => void) | undefined
+
+export const _errorHandler: (err: unknown) => void = (err) => {
+  // 1. User-set or default direct handler.
+  ;(_userErrorHandler ?? _defaultErrorHandler)(err)
+  // 2. Global telemetry bridge (installed by @pyreon/core's
+  //    registerErrorHandler). Forwards effect errors into reportError so
+  //    Sentry/Datadog wiring captures them alongside component errors.
+  _errorBridge.__pyreon_report_error__?.(err, 'effect')
+}
+
 export function setErrorHandler(fn: (err: unknown) => void): void {
-  _errorHandler = fn
+  _userErrorHandler = fn
 }
 
 /** Remove an effect from all dependency subscriber sets (local deps array). */
@@ -55,9 +132,35 @@ function cleanupLocalDeps(deps: Set<() => void>[], fn: () => void): void {
 }
 
 export function effect(fn: () => (() => void) | void): Effect {
+  // Dev-mode warning for async effect callbacks (audit bug #1). The
+  // tracking context is the synchronous frame around `fn()`'s top half;
+  // anything after the first `await` runs detached, so signal reads on
+  // the back side aren't tracked and the effect won't re-run when those
+  // signals change. The fix at the call site is either to read all
+  // tracked signals BEFORE the first await, or split the work into two
+  // effects (or use `watch` for async-in-callback). Surfacing the warn
+  // at registration is the cheapest catch we can offer: an
+  // `AsyncFunction.prototype.constructor.name === 'AsyncFunction'`
+  // check is true at function-definition time without invoking anything.
+  if (process.env.NODE_ENV !== 'production') {
+    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        '[pyreon] effect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. ' +
+          'Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.',
+      )
+    }
+  }
+
   // Capture the scope at creation time — remains correct during future re-runs
   // even after setCurrentScope(null) has been called post-setup.
   const scope = getCurrentScope()
+  // Capture the external (core-context) snapshot at SETUP time. Reactive
+  // re-runs restore it before invoking fn, so provider lookups stay correct
+  // even when the global context stack has been destructively truncated by
+  // mountReactive's restoreContextStack cleanup. See `_bind` for the full
+  // rationale.
+  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
   let disposed = false
   let isFirstRun = true
   let cleanup: (() => void) | undefined
@@ -65,8 +168,22 @@ export function effect(fn: () => (() => void) | void): Effect {
   const deps: Set<() => void>[] = []
 
   let cleanups: (() => void)[] | undefined
+  // Inner effects created during this effect's fn() body. Disposed on
+  // outer re-run (before the next fn()) and on outer dispose(). Without
+  // this, nested effects leak across outer lifecycle boundaries.
+  let innerEffects: Effect[] | null = null
 
   const runCleanup = () => {
+    if (innerEffects) {
+      for (const ie of innerEffects) {
+        try {
+          ie.dispose()
+        } catch (err) {
+          _errorHandler(err)
+        }
+      }
+      innerEffects = null
+    }
     if (cleanups) {
       for (const c of cleanups) {
         try {
@@ -89,15 +206,32 @@ export function effect(fn: () => (() => void) | void): Effect {
 
   const run = () => {
     if (disposed) return
+    if (process.env.NODE_ENV !== 'production')
+      _countSink.__pyreon_count__?.('reactivity.effectRun')
     // Run previous cleanup before re-running
     runCleanup()
+    // Start a new inner-effect collection window. Effects created during
+    // fn() will push themselves into this array and be disposed on the
+    // next re-run or on dispose.
+    const outerCollector = _innerEffectCollector
+    const myInners: Effect[] = []
+    _innerEffectCollector = myInners
     try {
       cleanupLocalDeps(deps, run)
       setDepsCollector(deps)
       // Collect onCleanup() registrations during execution
       const collected: (() => void)[] = []
       _cleanupCollector = collected
-      cleanup = withTracking(run, fn) || undefined
+      // First run executes inside the synchronous mount where the context
+      // stack is still intact — call fn directly to avoid pushing the
+      // captured snapshot a redundant second time. Subsequent re-runs
+      // happen AFTER mountReactive's cleanup has truncated the stack, so
+      // they need the snapshot restored to find provider frames.
+      const fnToRun =
+        isFirstRun || snapshot === null || _snapshotCapture === null
+          ? fn
+          : () => (_snapshotCapture as ReactiveSnapshotCapture).restore(snapshot, fn)
+      cleanup = withTracking(run, fnToRun) || undefined
       _cleanupCollector = null
       if (collected.length > 0) cleanups = collected
       setDepsCollector(null)
@@ -105,7 +239,10 @@ export function effect(fn: () => (() => void) | void): Effect {
       _cleanupCollector = null
       setDepsCollector(null)
       _errorHandler(err)
+    } finally {
+      _innerEffectCollector = outerCollector
     }
+    if (myInners.length > 0) innerEffects = myInners
     // Notify scope after each reactive re-run (not the initial synchronous run)
     // so onUpdate hooks fire after the DOM has settled.
     if (!isFirstRun) scope?.notifyEffectRan()
@@ -122,8 +259,14 @@ export function effect(fn: () => (() => void) | void): Effect {
     },
   }
 
-  // Auto-register with the active EffectScope (if any)
-  getCurrentScope()?.add(e)
+  // If we're inside another effect's run, register with it so the outer
+  // disposes this inner automatically.
+  if (_innerEffectCollector !== null) {
+    _innerEffectCollector.push(e)
+  } else {
+    // Otherwise auto-register with the active EffectScope (if any)
+    getCurrentScope()?.add(e)
+  }
 
   return e
 }
@@ -158,12 +301,26 @@ export function _bind(fn: () => void): () => void {
   const deps: Set<() => void>[] = []
   let disposed = false
 
+  // Capture external (core-context) snapshot at SETUP time. Re-runs restore
+  // it before invoking fn, so signal-driven re-runs see the same provider
+  // chain that was active when the binding was first set up — even if the
+  // global context stack has been destructively truncated by mountReactive's
+  // restoreContextStack cleanup in the meantime.
+  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
+
   const run = () => {
     if (disposed) return
-    fn()
+    if (snapshot !== null && _snapshotCapture) {
+      _snapshotCapture.restore(snapshot, fn)
+    } else {
+      fn()
+    }
   }
 
-  // First run: track deps so we know what to unsubscribe on dispose
+  // First run: track deps so we know what to unsubscribe on dispose. We
+  // intentionally call `fn` directly (not `run`) here — the synchronous
+  // mount stack is already intact at this point, so restoring the captured
+  // snapshot would just push the same frames again redundantly.
   setDepsCollector(deps)
   withTracking(run, fn)
   setDepsCollector(null)
@@ -201,12 +358,50 @@ function renderEffectFullTrack(deps: Set<() => void>[], run: () => void, fn: ()
 }
 
 export function renderEffect(fn: () => void): () => void {
+  // Same dev warning as `effect()` — signal reads after the first
+  // await aren't tracked. See effect()'s docstring for full reasoning.
+  if (process.env.NODE_ENV !== 'production') {
+    if (fn.constructor && fn.constructor.name === 'AsyncFunction') {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        '[pyreon] renderEffect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. ' +
+          'Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.',
+      )
+    }
+  }
+
   const deps: Set<() => void>[] = []
   let disposed = false
+  let isFirstRun = true
+
+  // Same rationale as `_bind`: capture the external context snapshot at
+  // SETUP and restore it on signal-driven re-runs so provider lookups stay
+  // correct even after `mountReactive`'s cleanup truncates the global stack.
+  const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null
+
+  const trackedFn =
+    snapshot !== null && _snapshotCapture
+      ? () => (_snapshotCapture as ReactiveSnapshotCapture).restore(snapshot, fn)
+      : fn
 
   const run = () => {
     if (disposed) return
-    renderEffectFullTrack(deps, run, fn)
+    if (isFirstRun) {
+      isFirstRun = false
+      setDepsCollector(deps)
+      _setActiveEffect(run)
+      try {
+        // First run: stack is still intact (we're inside the synchronous
+        // mount), so call fn directly to avoid pushing the snapshot frames
+        // a second time.
+        fn()
+      } finally {
+        _restoreActiveEffect()
+        setDepsCollector(null)
+      }
+    } else {
+      renderEffectFullTrack(deps, run, trackedFn)
+    }
   }
 
   run()

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal process type — just enough for `process.env.NODE_ENV` checks.
+ * Avoids requiring @types/node in consumers that import pyreon source
+ * via the `"bun"` export condition.
+ */
+declare var process: { env: { NODE_ENV?: string } }

package/src/index.ts

@@ -5,7 +5,16 @@ export { Cell, cell } from './cell'
 export { type Computed, type ComputedOptions, computed } from './computed'
 export { createSelector } from './createSelector'
 export { inspectSignal, onSignalUpdate, why } from './debug'
-export { _bind, type Effect, effect, onCleanup, renderEffect, setErrorHandler } from './effect'
+export {
+  _bind,
+  type Effect,
+  effect,
+  onCleanup,
+  type ReactiveSnapshotCapture,
+  renderEffect,
+  setErrorHandler,
+  setSnapshotCapture,
+} from './effect'
 export { reconcile } from './reconcile'
 export { createResource, type Resource } from './resource'
 export { EffectScope, effectScope, getCurrentScope, setCurrentScope } from './scope'

package/src/scope.ts

@@ -2,14 +2,16 @@
 // and disposes them all at once when the component unmounts.
 
 export class EffectScope {
-  private _effects: { dispose(): void }[] = []
+  private _effects: { dispose(): void }[] | null = null
   private _active = true
-  private _updateHooks: (() => void)[] = []
+  private _updateHooks: (() => void)[] | null = null
   private _updatePending = false
 
   /** Register an effect/computed to be disposed when this scope stops. */
   add(e: { dispose(): void }): void {
-    if (this._active) this._effects.push(e)
+    if (!this._active) return
+    if (this._effects === null) this._effects = []
+    this._effects.push(e)
   }
 
   /**
@@ -30,6 +32,7 @@ export class EffectScope {
 
   /** Register a callback to run after any reactive update in this scope. */
   addUpdateHook(fn: () => void): void {
+    if (this._updateHooks === null) this._updateHooks = []
     this._updateHooks.push(fn)
   }
 
@@ -38,11 +41,11 @@ export class EffectScope {
    * Schedules onUpdate hooks via microtask so all synchronous effects settle first.
    */
   notifyEffectRan(): void {
-    if (!this._active || this._updateHooks.length === 0 || this._updatePending) return
+    if (!this._active || !this._updateHooks || this._updateHooks.length === 0 || this._updatePending) return
     this._updatePending = true
     queueMicrotask(() => {
       this._updatePending = false
-      if (!this._active) return
+      if (!this._active || !this._updateHooks) return
       for (const fn of this._updateHooks) {
         try {
           fn()
@@ -56,9 +59,11 @@ export class EffectScope {
   /** Dispose all tracked effects. */
   stop(): void {
     if (!this._active) return
-    for (const e of this._effects) e.dispose()
-    this._effects = []
-    this._updateHooks = []
+    if (this._effects) {
+      for (const e of this._effects) e.dispose()
+    }
+    this._effects = null
+    this._updateHooks = null
     this._updatePending = false
     this._active = false
   }