@pyreon/reactivity 0.23.0 → 0.24.0

package/lib/lpih.js

@@ -0,0 +1,177 @@
+import { o as getFireSummaries } from "./_chunks/reactive-devtools-BCpGoGZ5.js";
+
+//#region src/lpih.ts
+/**
+* Live Program Inlay Hints — runtime bridge.
+*
+* Writes the current `getFireSummaries()` snapshot to a JSON file that
+* the LSP server reads via the `PYREON_LPIH_CACHE` env var. This is the
+* file-cache bridge mechanism — chosen over IPC/WebSocket because:
+*
+*   1. LSP servers are stdio-only — they can't easily talk to a browser.
+*   2. Filesystem is a universal lowest-common-denominator transport.
+*   3. The runtime side writes (atomic rename); the LSP side reads.
+*   4. The LSP re-reads the file on every inlay-hint request, so live
+*      edits land immediately without coordination.
+*
+* Two consumer modes:
+*
+*   **Dev-server polled mode**: a dev-server hook calls
+*   `writeLpihCache(path)` on every signal write or at a regular interval
+*   (e.g. 250ms throttle). The LSP picks it up on next inlay-hint request.
+*
+*   **On-demand mode**: a test harness or devtools UI calls
+*   `writeLpihCache(path)` explicitly when it wants the LSP to see the
+*   current state.
+*
+* Atomic write semantics: writes to `<path>.tmp.<pid>.<seq>` then renames
+* to `<path>`. Readers (the LSP server) never see a half-written file.
+*
+* Zero-cost when devtools is inactive: `getFireSummaries()` returns []
+* unless `activateReactiveDevtools()` has been called. So calling
+* `writeLpihCache()` against an inactive registry writes an empty
+* `{ fires: [] }` — cheap, correct.
+*/
+let _seq = 0;
+/**
+* Canonical filename for the LPIH cache file. Co-located with the
+* project — convention: `<cwd>/.pyreon-lpih.json`. The dot-prefix marks
+* it as a hidden / generated file by filesystem convention; the
+* extension makes its contents grep-able as JSON.
+*
+* @internal — exported for tests + symmetry with the LSP-side default.
+*/
+const LPIH_DEFAULT_FILENAME = ".pyreon-lpih.json";
+/**
+* Resolve the default LPIH cache path for the current process. The path
+* is **`<cwd>/.pyreon-lpih.json`** — co-located with the project so the
+* LSP can auto-discover it by walking up from any source file.
+*
+* Returns null in environments without `process.cwd()` (e.g. a fresh
+* web worker without polyfills) — callers should fall back to an
+* explicit path argument.
+*
+* @example
+* import { startLpihPolling, getDefaultLpihCachePath } from '@pyreon/reactivity/lpih'
+* console.log(getDefaultLpihCachePath()) // → '/Users/me/proj/.pyreon-lpih.json'
+* startLpihPolling() // writes to that path
+*/
+function getDefaultLpihCachePath() {
+	if (typeof process === "undefined") return null;
+	const proc = process;
+	if (typeof proc.cwd !== "function") return null;
+	try {
+		return `${proc.cwd().replace(/[/\\]+$/, "")}/${LPIH_DEFAULT_FILENAME}`;
+	} catch {
+		return null;
+	}
+}
+/**
+* Snapshot `getFireSummaries()` and write it to `path` atomically.
+* Returns the number of fires written.
+*
+* **Path resolution**: when `path` is omitted, defaults to
+* `<cwd>/.pyreon-lpih.json` (`getDefaultLpihCachePath()`). The LSP
+* auto-discovers this convention by walking up from any source file to
+* the nearest `package.json` — so projects that use the default need
+* zero env-var configuration.
+*
+* Errors (filesystem permission, EACCES, etc.) are caught and re-thrown
+* — the caller decides whether to swallow them. The runtime side wraps
+* this in a try/catch when called from hot paths.
+*
+* Throws if `path` is omitted AND no default can be resolved (e.g.
+* a web worker without `process.cwd()`).
+*
+* @example
+* import { activateReactiveDevtools } from '@pyreon/reactivity'
+* import { writeLpihCache } from '@pyreon/reactivity/lpih'
+*
+* activateReactiveDevtools()
+* await writeLpihCache() // → writes to <cwd>/.pyreon-lpih.json
+* // The LSP server auto-discovers this path; no env var needed.
+*/
+async function writeLpihCache(path) {
+	const resolvedPath = path ?? getDefaultLpihCachePath();
+	if (resolvedPath === null) throw new Error("[lpih] writeLpihCache: no path provided and no default could be resolved (process.cwd() unavailable). Pass an explicit path.");
+	return await _writeToPath(resolvedPath);
+}
+async function _writeToPath(path) {
+	const summaries = getFireSummaries();
+	const payload = { fires: summaries.map((s) => ({
+		file: s.loc.file,
+		line: s.loc.line,
+		count: s.count,
+		kind: s.kind,
+		lastFire: s.lastFire,
+		rate1s: s.rate1s
+	})) };
+	const tmp = `${path}.tmp.${typeof process !== "undefined" && "pid" in process ? process.pid ?? 0 : 0}.${++_seq}`;
+	const fs = await import("node:fs/promises");
+	try {
+		await fs.writeFile(tmp, JSON.stringify(payload), "utf8");
+		await fs.rename(tmp, path);
+	} catch (err) {
+		try {
+			await fs.unlink(tmp);
+		} catch {}
+		throw err;
+	}
+	return summaries.length;
+}
+/**
+* Polling helper: call `writeLpihCache(path)` every `intervalMs`. Returns
+* a disposer that stops the timer.
+*
+* **Path resolution**: same as `writeLpihCache` — `path` defaults to
+* `<cwd>/.pyreon-lpih.json` when omitted. The LSP auto-discovers this
+* convention so projects need zero configuration.
+*
+* Useful for dev servers that want the LSP to see live updates. The
+* interval is throttled (not debounced); a fast-firing signal won't
+* generate one write per fire. 250-500ms is the recommended range.
+*
+* Throws synchronously if `path` is omitted AND no default can be
+* resolved — the caller catches this once at startup rather than
+* silently never writing.
+*
+* @example
+* import { activateReactiveDevtools } from '@pyreon/reactivity'
+* import { startLpihPolling } from '@pyreon/reactivity/lpih'
+*
+* if (import.meta.env.DEV) {
+*   activateReactiveDevtools()
+*   startLpihPolling() // writes to <cwd>/.pyreon-lpih.json every 250ms
+* }
+*/
+function startLpihPolling(path, intervalMs = 250) {
+	const resolvedPath = path ?? getDefaultLpihCachePath();
+	if (resolvedPath === null) throw new Error("[lpih] startLpihPolling: no path provided and no default could be resolved (process.cwd() unavailable). Pass an explicit path.");
+	return _startPollingAt(resolvedPath, intervalMs);
+}
+function _startPollingAt(path, intervalMs) {
+	let active = true;
+	let timer = null;
+	const tick = async () => {
+		if (!active) return;
+		try {
+			await _writeToPath(path);
+		} catch {}
+		if (active) {
+			timer = setTimeout(tick, intervalMs);
+			if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref();
+		}
+	};
+	tick();
+	return () => {
+		active = false;
+		if (timer !== null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+}
+
+//#endregion
+export { LPIH_DEFAULT_FILENAME, getDefaultLpihCachePath, startLpihPolling, writeLpihCache };
+//# sourceMappingURL=lpih.js.map

package/lib/types/index.d.ts

@@ -67,6 +67,21 @@ interface ComputedOptions<T> {
    * })
    */
   equals?: (prev: T, next: T) => boolean;
+  /**
+   * @internal — source location injected by `@pyreon/vite-plugin` at build
+   * time. When present, the runtime skips the `new Error().stack` capture
+   * in `_rdRegister` — saves ~2.2µs per computed creation when devtools is
+   * active. Plain user code should NOT set this; the field is opaque
+   * (no public type) so it's not part of the public API surface.
+   *
+   * Shape: `{ file: string; line: number; col: number }` matching
+   * `@pyreon/reactivity`'s `SourceLocation`.
+   */
+  __sourceLocation?: {
+    file: string;
+    line: number;
+    col: number;
+  };
 }
 declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed<T>;
 //#endregion
@@ -150,6 +165,21 @@ interface Signal<T> {
 interface SignalOptions {
   /** Debug name for this signal — shows up in devtools and debug() output. */
   name?: string;
+  /**
+   * @internal — source location injected by `@pyreon/vite-plugin` at build
+   * time. When present, the runtime skips the `new Error().stack` capture
+   * in `_rdRegister` — saves ~2.2µs per signal creation when devtools is
+   * active. Plain user code should NOT set this; the field is opaque
+   * (no public type) so it's not part of the public API surface.
+   *
+   * Shape: `{ file: string; line: number; col: number }` matching
+   * `@pyreon/reactivity`'s `SourceLocation`.
+   */
+  __sourceLocation?: {
+    file: string;
+    line: number;
+    col: number;
+  };
 }
 /**
  * Create a reactive signal.
@@ -237,6 +267,25 @@ declare function inspectSignal<T>(sig: Signal<T>): SignalDebugInfo<T>;
  * they get a stable synthetic label (`derived#12` / `effect#7`).
  */
 type ReactiveNodeKind = 'signal' | 'derived' | 'effect';
+/**
+ * Source location of a reactive node's creation — captured at registration
+ * time from the user's call stack. Powers "Live Program Inlay Hints" — the
+ * editor surfaces fire counts at the source line where the node was created.
+ *
+ * Captured ONLY when devtools is active (`_active === true`). Stack parsing
+ * is best-effort across V8 / JSC / SpiderMonkey; returns undefined when the
+ * stack format isn't recognized (older runtimes, minified prod, web workers
+ * without source maps). Dev gate is the existing `process.env.NODE_ENV` at
+ * each caller — production paths never run the capture.
+ */
+interface SourceLocation {
+  /** Absolute path or file URL parsed from the stack frame. */
+  file: string;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column number. */
+  col: number;
+}
 interface ReactiveNode {
   id: number;
   kind: ReactiveNodeKind;
@@ -250,6 +299,13 @@ interface ReactiveNode {
   fires: number;
   /** `performance.now()` of the most recent fire, or null. */
   lastFire: number | null;
+  /**
+   * Source location of the creation call (`signal(0)` / `computed(...)` /
+   * `effect(...)`). Undefined when devtools wasn't active at creation
+   * time OR the stack format wasn't parseable. Editor inlay-hint surfaces
+   * consume this to merge live fire counts onto static spans.
+   */
+  loc?: SourceLocation;
 }
 interface ReactiveEdge {
   /** Source node id (the reactive value being read). */
@@ -266,6 +322,35 @@ interface ReactiveFire {
   /** `performance.now()` at fire time. */
   ts: number;
 }
+/**
+ * Per-source-location fire-count summary. Aggregated from the fire ring
+ * buffer + node registry. The shape an editor / LSP inlay-hint consumer
+ * needs to merge "this signal at line N fires K times" onto static
+ * Reactivity-Lens spans. Pure data, JSON-serializable, no node refs.
+ */
+interface FireSummary {
+  loc: SourceLocation;
+  /** Total fires in the visible ring buffer at this location. */
+  count: number;
+  /** Most recent fire `performance.now()` at this location, or null. */
+  lastFire: number | null;
+  /** Node kind that fired most recently at this location. */
+  kind: ReactiveNodeKind;
+  /**
+   * Exponentially-weighted moving average of the fire rate at this
+   * location, in fires per second. Decayed to "now" at read time so a
+   * node that stopped firing N seconds ago shows a rate that's
+   * exponentially smaller than its steady-state value.
+   *
+   * Calculation uses a 1-second time constant (`LPIH_RATE_TAU_MS`):
+   * - On each fire: `r = r * exp(-dt/TAU) + 1`
+   *   - Steady state at λ fires/sec converges to ≈ λ (when λ × TAU ≫ 1)
+   * - On read: `r_now = r * exp(-dt_since_last/TAU)`
+   *
+   * 0 when there have been no fires (or all fires were >>TAU ago).
+   */
+  rate1s: number;
+}
 /** Activate the bridge. Idempotent. Called when a devtools client attaches. */
 declare function activateReactiveDevtools(): void;
 /**
@@ -280,6 +365,18 @@ declare function isReactiveDevtoolsActive(): boolean;
  * framework's real subscription state, no incremental drift.
  */
 declare function getReactiveGraph(): ReactiveGraph;
+/**
+ * Aggregate fire counts by source-location — powers Live Program Inlay
+ * Hints. Walks the live node registry, keys each node by its captured
+ * `loc`, and returns one summary per unique `file:line:col`. Nodes
+ * without a captured location are skipped (their fires are still
+ * visible via `getReactiveGraph()` and `getReactiveFires()` for the
+ * existing graph / timeline surfaces).
+ *
+ * Returns a fresh array, JSON-serializable, safe to ship across the
+ * devtools-host bridge or to write into an LSP cache file.
+ */
+declare function getFireSummaries(): FireSummary[];
 /** Bounded recent-fire timeline (oldest → newest). Fresh copy. */
 declare function getReactiveFires(): ReactiveFire[];
 //#endregion
@@ -337,6 +434,23 @@ declare function clearReactiveTrace(): void;
 interface Effect {
   dispose(): void;
 }
+interface EffectOptions {
+  /**
+   * @internal — source location injected by `@pyreon/vite-plugin` at build
+   * time. When present, the runtime skips the `new Error().stack` capture
+   * in `_rdRegister` — saves ~2.2µs per effect creation when devtools is
+   * active. Plain user code should NOT set this; the field is opaque
+   * (no public type) so it's not part of the public API surface.
+   *
+   * Shape: `{ file: string; line: number; col: number }` matching
+   * `@pyreon/reactivity`'s `SourceLocation`.
+   */
+  __sourceLocation?: {
+    file: string;
+    line: number;
+    col: number;
+  };
+}
 interface ReactiveSnapshotCapture {
   capture: () => unknown;
   /** Run `fn` with the previously-captured snapshot active. */
@@ -369,7 +483,7 @@ declare function setSnapshotCapture(hook: ReactiveSnapshotCapture | null): void;
  */
 declare function onCleanup(fn: () => void): void;
 declare function setErrorHandler(fn: (err: unknown) => void): void;
-declare function effect(fn: () => (() => void) | void): Effect;
+declare function effect(fn: () => (() => void) | void, options?: EffectOptions): Effect;
 /**
  * Lightweight effect for DOM render bindings.
  *
@@ -589,5 +703,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 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 };
+export { Cell, type Computed, type ComputedOptions, type Effect, EffectScope, type FireSummary, 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 SourceLocation, type WatchOptions, _bind, activateReactiveDevtools, batch, cell, clearReactiveTrace, computed, createResource, createSelector, createStore, deactivateReactiveDevtools, effect, effectScope, getCurrentScope, getFireSummaries, 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/lib/types/lpih.d.ts

@@ -0,0 +1,111 @@
+//#region src/lpih.d.ts
+/**
+ * Live Program Inlay Hints — runtime bridge.
+ *
+ * Writes the current `getFireSummaries()` snapshot to a JSON file that
+ * the LSP server reads via the `PYREON_LPIH_CACHE` env var. This is the
+ * file-cache bridge mechanism — chosen over IPC/WebSocket because:
+ *
+ *   1. LSP servers are stdio-only — they can't easily talk to a browser.
+ *   2. Filesystem is a universal lowest-common-denominator transport.
+ *   3. The runtime side writes (atomic rename); the LSP side reads.
+ *   4. The LSP re-reads the file on every inlay-hint request, so live
+ *      edits land immediately without coordination.
+ *
+ * Two consumer modes:
+ *
+ *   **Dev-server polled mode**: a dev-server hook calls
+ *   `writeLpihCache(path)` on every signal write or at a regular interval
+ *   (e.g. 250ms throttle). The LSP picks it up on next inlay-hint request.
+ *
+ *   **On-demand mode**: a test harness or devtools UI calls
+ *   `writeLpihCache(path)` explicitly when it wants the LSP to see the
+ *   current state.
+ *
+ * Atomic write semantics: writes to `<path>.tmp.<pid>.<seq>` then renames
+ * to `<path>`. Readers (the LSP server) never see a half-written file.
+ *
+ * Zero-cost when devtools is inactive: `getFireSummaries()` returns []
+ * unless `activateReactiveDevtools()` has been called. So calling
+ * `writeLpihCache()` against an inactive registry writes an empty
+ * `{ fires: [] }` — cheap, correct.
+ */
+/**
+ * Canonical filename for the LPIH cache file. Co-located with the
+ * project — convention: `<cwd>/.pyreon-lpih.json`. The dot-prefix marks
+ * it as a hidden / generated file by filesystem convention; the
+ * extension makes its contents grep-able as JSON.
+ *
+ * @internal — exported for tests + symmetry with the LSP-side default.
+ */
+declare const LPIH_DEFAULT_FILENAME = ".pyreon-lpih.json";
+/**
+ * Resolve the default LPIH cache path for the current process. The path
+ * is **`<cwd>/.pyreon-lpih.json`** — co-located with the project so the
+ * LSP can auto-discover it by walking up from any source file.
+ *
+ * Returns null in environments without `process.cwd()` (e.g. a fresh
+ * web worker without polyfills) — callers should fall back to an
+ * explicit path argument.
+ *
+ * @example
+ * import { startLpihPolling, getDefaultLpihCachePath } from '@pyreon/reactivity/lpih'
+ * console.log(getDefaultLpihCachePath()) // → '/Users/me/proj/.pyreon-lpih.json'
+ * startLpihPolling() // writes to that path
+ */
+declare function getDefaultLpihCachePath(): string | null;
+/**
+ * Snapshot `getFireSummaries()` and write it to `path` atomically.
+ * Returns the number of fires written.
+ *
+ * **Path resolution**: when `path` is omitted, defaults to
+ * `<cwd>/.pyreon-lpih.json` (`getDefaultLpihCachePath()`). The LSP
+ * auto-discovers this convention by walking up from any source file to
+ * the nearest `package.json` — so projects that use the default need
+ * zero env-var configuration.
+ *
+ * Errors (filesystem permission, EACCES, etc.) are caught and re-thrown
+ * — the caller decides whether to swallow them. The runtime side wraps
+ * this in a try/catch when called from hot paths.
+ *
+ * Throws if `path` is omitted AND no default can be resolved (e.g.
+ * a web worker without `process.cwd()`).
+ *
+ * @example
+ * import { activateReactiveDevtools } from '@pyreon/reactivity'
+ * import { writeLpihCache } from '@pyreon/reactivity/lpih'
+ *
+ * activateReactiveDevtools()
+ * await writeLpihCache() // → writes to <cwd>/.pyreon-lpih.json
+ * // The LSP server auto-discovers this path; no env var needed.
+ */
+declare function writeLpihCache(path?: string): Promise<number>;
+/**
+ * Polling helper: call `writeLpihCache(path)` every `intervalMs`. Returns
+ * a disposer that stops the timer.
+ *
+ * **Path resolution**: same as `writeLpihCache` — `path` defaults to
+ * `<cwd>/.pyreon-lpih.json` when omitted. The LSP auto-discovers this
+ * convention so projects need zero configuration.
+ *
+ * Useful for dev servers that want the LSP to see live updates. The
+ * interval is throttled (not debounced); a fast-firing signal won't
+ * generate one write per fire. 250-500ms is the recommended range.
+ *
+ * Throws synchronously if `path` is omitted AND no default can be
+ * resolved — the caller catches this once at startup rather than
+ * silently never writing.
+ *
+ * @example
+ * import { activateReactiveDevtools } from '@pyreon/reactivity'
+ * import { startLpihPolling } from '@pyreon/reactivity/lpih'
+ *
+ * if (import.meta.env.DEV) {
+ *   activateReactiveDevtools()
+ *   startLpihPolling() // writes to <cwd>/.pyreon-lpih.json every 250ms
+ * }
+ */
+declare function startLpihPolling(path?: string, intervalMs?: number): () => void;
+//#endregion
+export { LPIH_DEFAULT_FILENAME, getDefaultLpihCachePath, startLpihPolling, writeLpihCache };
+//# sourceMappingURL=lpih2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/reactivity",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Signals-based reactivity system for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/reactivity#readme",
   "bugs": {
@@ -29,6 +29,11 @@
       "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
+    },
+    "./lpih": {
+      "bun": "./src/lpih.ts",
+      "import": "./lib/lpih.js",
+      "types": "./lib/types/lpih.d.ts"
     }
   },
   "publishConfig": {

package/src/computed.ts

@@ -1,6 +1,6 @@
 import { _markRecompute } from './batch'
 import { _errorHandler } from './effect'
-import { _rdRecordFire, _rdRegister } from './reactive-devtools'
+import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
 import { getCurrentScope } from './scope'
 import {
   cleanupEffect,
@@ -36,6 +36,17 @@ export interface ComputedOptions<T> {
    * })
    */
   equals?: (prev: T, next: T) => boolean
+  /**
+   * @internal — source location injected by `@pyreon/vite-plugin` at build
+   * time. When present, the runtime skips the `new Error().stack` capture
+   * in `_rdRegister` — saves ~2.2µs per computed creation when devtools is
+   * active. Plain user code should NOT set this; the field is opaque
+   * (no public type) so it's not part of the public API surface.
+   *
+   * Shape: `{ file: string; line: number; col: number }` matching
+   * `@pyreon/reactivity`'s `SourceLocation`.
+   */
+  __sourceLocation?: { file: string; line: number; col: number }
 }
 
 /** Remove a computed from all dependency subscriber sets (local deps array). */
@@ -68,7 +79,14 @@ export function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed
       )
     }
   }
-  return options?.equals ? computedWithEquals(fn, options.equals) : computedLazy(fn)
+  // Prefer build-time-injected location (zero runtime cost) over the
+  // ~2.2µs stack-capture fallback. @pyreon/vite-plugin's `injectSignalNames`
+  // rewrites `computed(() => …)` to `computed(() => …, { __sourceLocation: {…} })`
+  // at transform time so most dev-mode computeds never pay the stack-capture cost.
+  const loc = options?.__sourceLocation
+  return options?.equals
+    ? computedWithEquals(fn, options.equals, loc)
+    : computedLazy(fn, loc)
 }
 
 /**
@@ -81,7 +99,10 @@ export function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed
  * in diamond patterns (a→b,c→d: b notifies d, c tries to notify d again —
  * skipped because d is already dirty).
  */
-function computedLazy<T>(fn: () => T): Computed<T> {
+function computedLazy<T>(
+  fn: () => T,
+  injectedLoc?: { file: string; line: number; col: number },
+): Computed<T> {
   let value: T
   let dirty = true
   let disposed = false
@@ -165,7 +186,15 @@ function computedLazy<T>(fn: () => T): Computed<T> {
   }
 
   if (process.env.NODE_ENV !== 'production')
-    _rdRegister(read, 'derived', host, recompute, undefined)
+    // skipFrames=2: skip computedLazy/computedWithEquals + computed, capture user's call site.
+    _rdRegister(
+      read,
+      'derived',
+      host,
+      recompute,
+      undefined,
+      injectedLoc ?? _captureCallerLocation(2),
+    )
 
   getCurrentScope()?.add({ dispose: read.dispose })
   return read as Computed<T>
@@ -177,7 +206,11 @@ function computedLazy<T>(fn: () => T): Computed<T> {
  * Re-evaluates immediately when deps change and only notifies downstream
  * if `equals(prev, next)` returns false.
  */
-function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolean): Computed<T> {
+function computedWithEquals<T>(
+  fn: () => T,
+  equals: (prev: T, next: T) => boolean,
+  injectedLoc?: { file: string; line: number; col: number },
+): Computed<T> {
   let value: T
   let dirty = true
   let initialized = false
@@ -265,7 +298,15 @@ function computedWithEquals<T>(fn: () => T, equals: (prev: T, next: T) => boolea
   }
 
   if (process.env.NODE_ENV !== 'production')
-    _rdRegister(read, 'derived', host, recompute, undefined)
+    // skipFrames=2: skip computedLazy/computedWithEquals + computed, capture user's call site.
+    _rdRegister(
+      read,
+      'derived',
+      host,
+      recompute,
+      undefined,
+      injectedLoc ?? _captureCallerLocation(2),
+    )
 
   getCurrentScope()?.add({ dispose: read.dispose })
   return read as Computed<T>

package/src/effect.ts

@@ -1,4 +1,4 @@
-import { _rdRecordFire, _rdRegister } from './reactive-devtools'
+import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
 import { getCurrentScope } from './scope'
 import { _restoreActiveEffect, _setActiveEffect, setDepsCollector, withTracking } from './tracking'
 
@@ -9,6 +9,20 @@ export interface Effect {
   dispose(): void
 }
 
+export interface EffectOptions {
+  /**
+   * @internal — source location injected by `@pyreon/vite-plugin` at build
+   * time. When present, the runtime skips the `new Error().stack` capture
+   * in `_rdRegister` — saves ~2.2µs per effect creation when devtools is
+   * active. Plain user code should NOT set this; the field is opaque
+   * (no public type) so it's not part of the public API surface.
+   *
+   * Shape: `{ file: string; line: number; col: number }` matching
+   * `@pyreon/reactivity`'s `SourceLocation`.
+   */
+  __sourceLocation?: { file: string; line: number; col: number }
+}
+
 // ─── Effect-scoped snapshot capture (DI from `@pyreon/core`) ─────────────────
 //
 // Effects re-run reactively in response to signal changes. When that re-run
@@ -137,7 +151,10 @@ function cleanupLocalDeps(deps: Set<() => void>[], fn: () => void): void {
   }
 }
 
-export function effect(fn: () => (() => void) | void): Effect {
+export function effect(
+  fn: () => (() => void) | void,
+  options?: EffectOptions,
+): 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
@@ -258,7 +275,18 @@ export function effect(fn: () => (() => void) | void): Effect {
   }
 
   if (process.env.NODE_ENV !== 'production')
-    _rdRegister(run, 'effect', null, run, undefined)
+    // skipFrames=1: skip the `effect()` / `renderEffect()` frame, capture the user's call site.
+    // Prefer build-time-injected location over the ~2.2µs stack-capture
+    // fallback. @pyreon/vite-plugin's `injectSignalNames` rewrites
+    // `effect(() => …)` to `effect(() => …, { __sourceLocation: {…} })`.
+    _rdRegister(
+      run,
+      'effect',
+      null,
+      run,
+      undefined,
+      options?.__sourceLocation ?? _captureCallerLocation(1),
+    )
 
   run()
 
@@ -416,7 +444,8 @@ export function renderEffect(fn: () => void): () => void {
   }
 
   if (process.env.NODE_ENV !== 'production')
-    _rdRegister(run, 'effect', null, run, undefined)
+    // skipFrames=1: skip the `effect()` / `renderEffect()` frame, capture the user's call site.
+    _rdRegister(run, 'effect', null, run, undefined, _captureCallerLocation(1))
 
   run()
 

package/src/index.ts

@@ -6,19 +6,27 @@ export { type Computed, type ComputedOptions, computed } from './computed'
 export { createSelector } from './createSelector'
 export { inspectSignal, onSignalUpdate, why } from './debug'
 export type {
+  FireSummary,
   ReactiveEdge,
   ReactiveFire,
   ReactiveGraph,
   ReactiveNode,
   ReactiveNodeKind,
+  SourceLocation,
 } from './reactive-devtools'
 export {
   activateReactiveDevtools,
   deactivateReactiveDevtools,
+  getFireSummaries,
   getReactiveFires,
   getReactiveGraph,
   isReactiveDevtoolsActive,
 } from './reactive-devtools'
+// `writeLpihCache` + `startLpihPolling` ship at the `@pyreon/reactivity/lpih`
+// subpath. They depend on `node:fs/promises` (Node-only) and are dev-mode
+// integration utilities — separating them keeps the core main-entry bundle
+// smaller AND clarifies that LPIH writes are an opt-in side-channel, not a
+// core reactivity primitive. See `./lpih.ts` and `docs/docs/lpih.md`.
 export type { ReactiveTraceEntry } from './reactive-trace'
 export { clearReactiveTrace, getReactiveTrace } from './reactive-trace'
 export {