@pyreon/reactivity 0.14.0 → 0.15.0

package/src/effect.ts

@@ -2,15 +2,47 @@ import { getCurrentScope } from './scope'
 import { _restoreActiveEffect, _setActiveEffect, setDepsCollector, withTracking } from './tracking'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
-interface ViteMeta {
-  readonly env?: { readonly DEV?: boolean }
-}
 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().
@@ -47,12 +79,45 @@ 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). */
@@ -67,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
@@ -115,7 +206,7 @@ export function effect(fn: () => (() => void) | void): Effect {
 
   const run = () => {
     if (disposed) return
-    if ((import.meta as ViteMeta).env?.DEV === true)
+    if (process.env.NODE_ENV !== 'production')
       _countSink.__pyreon_count__?.('reactivity.effectRun')
     // Run previous cleanup before re-running
     runCleanup()
@@ -131,7 +222,16 @@ export function effect(fn: () => (() => void) | void): Effect {
       // 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)
@@ -201,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)
@@ -244,28 +358,49 @@ 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
-    // After first run, if deps haven't changed structure, we can skip
-    // the full cleanup+retrack path. However, renderEffect deps CAN
-    // change (unlike _bind), so we always do the full track.
-    // Optimization: skip cleanup on first run (deps are empty).
     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, fn)
+      renderEffectFullTrack(deps, run, trackedFn)
     }
   }
 

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/signal.ts

@@ -1,15 +1,8 @@
-declare const process: { env: { NODE_ENV?: string } } | undefined
-
-const __DEV__ = typeof process !== 'undefined' && process?.env?.NODE_ENV !== 'production'
-
 import { batch, enqueuePendingNotification, isBatching } from './batch'
 import { _notifyTraceListeners, isTracing } from './debug'
 import { notifySubscribers, trackSubscriber } from './tracking'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
-interface ViteMeta {
-  readonly env?: { readonly DEV?: boolean }
-}
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
 
 export interface SignalDebugInfo<T> {
@@ -86,7 +79,7 @@ function _peek(this: SignalFn<unknown>) {
 
 function _set(this: SignalFn<unknown>, newValue: unknown) {
   if (Object.is(this._v, newValue)) return
-  if ((import.meta as ViteMeta).env?.DEV === true)
+  if (process.env.NODE_ENV !== 'production')
     _countSink.__pyreon_count__?.('reactivity.signalWrite')
   const prev = this._v
   this._v = newValue
@@ -173,12 +166,12 @@ function _debug(this: SignalFn<unknown>): SignalDebugInfo<unknown> {
  * update, subscribe) are shared across all signals — not per-signal closures.
  */
 export function signal<T>(initialValue: T, options?: SignalOptions): Signal<T> {
-  if ((import.meta as ViteMeta).env?.DEV === true)
+  if (process.env.NODE_ENV !== 'production')
     _countSink.__pyreon_count__?.('reactivity.signalCreate')
   // The read function is the only per-signal closure.
   // It doubles as the SubscriberHost (_s property) for trackSubscriber.
   const read = ((...args: unknown[]) => {
-    if (__DEV__ && args.length > 0) {
+    if (process.env.NODE_ENV !== 'production' && args.length > 0) {
       // oxlint-disable-next-line no-console
       console.warn(
         '[Pyreon] signal() was called with an argument. ' +