@pyreon/reactivity 0.22.0 → 0.24.0

package/lib/index.js

@@ -1,3 +1,5 @@
+import { a as deactivateReactiveDevtools, c as getReactiveGraph, i as activateReactiveDevtools, l as isReactiveDevtoolsActive, n as _rdRecordFire, o as getFireSummaries, r as _rdRegister, s as getReactiveFires, t as _captureCallerLocation } from "./_chunks/reactive-devtools-BCpGoGZ5.js";
+
 //#region src/batch.ts
 const __DEV__ = process.env.NODE_ENV !== "production";
 let batchDepth = 0;
@@ -149,169 +151,6 @@ function cell(value) {
 	return new Cell(value);
 }
 
-//#endregion
-//#region src/reactive-devtools.ts
-let _active = false;
-let _nextId = 1;
-const _byId = /* @__PURE__ */ new Map();
-const _subId = /* @__PURE__ */ new WeakMap();
-/** @internal — finalizer callback; prunes the record when a node is GC'd. */
-function _rdPrune(id) {
-	_byId.delete(id);
-}
-const _finalizer = new FinalizationRegistry(_rdPrune);
-const FIRE_CAP = 512;
-let _fireBuf = null;
-let _fireCount = 0;
-const PREVIEW_MAX$1 = 60;
-function preview$1(v) {
-	let s;
-	try {
-		if (v === null) return "null";
-		if (v === void 0) return "undefined";
-		const t = typeof v;
-		if (t === "string") s = JSON.stringify(v);
-		else if (t === "number" || t === "boolean" || t === "bigint") s = String(v);
-		else if (t === "function") s = `[Function ${v.name || "anonymous"}]`;
-		else if (t === "symbol") s = v.toString();
-		else if (Array.isArray(v)) s = `Array(${v.length})`;
-		else {
-			const ctor = v.constructor?.name;
-			let keys = [];
-			try {
-				keys = Object.keys(v).slice(0, 3);
-			} catch {
-				keys = [];
-			}
-			s = `${ctor && ctor !== "Object" ? `${ctor} ` : ""}{${keys.join(", ")}${keys.length === 3 ? ", …" : ""}}`;
-		}
-	} catch {
-		s = "[unstringifiable]";
-	}
-	return s.length > PREVIEW_MAX$1 ? `${s.slice(0, PREVIEW_MAX$1)}…` : s;
-}
-/** Activate the bridge. Idempotent. Called when a devtools client attaches. */
-function activateReactiveDevtools() {
-	_active = true;
-}
-/**
-* Deactivate + drop all retained state. Called when the devtools client
-* disconnects so a closed panel leaves zero residue.
-*/
-function deactivateReactiveDevtools() {
-	_active = false;
-	_byId.clear();
-	_fireBuf = null;
-	_fireCount = 0;
-}
-function isReactiveDevtoolsActive() {
-	return _active;
-}
-/**
-* Register a signal/computed/effect node. `host` is the object carrying
-* the `_s` subscriber Set (the signal read fn itself, or a computed's
-* internal host). `sub` is the notify closure (`recompute`/`run`) whose
-* identity appears in upstream `_s` Sets — used to resolve edges.
-*
-* @internal
-*/
-function _rdRegister(node, kind, host, sub, label) {
-	if (!_active) return void 0;
-	const id = _nextId++;
-	_byId.set(id, {
-		id,
-		kind,
-		name: label ?? `${kind === "signal" ? "signal" : kind}#${id}`,
-		ref: new WeakRef(node),
-		hostRef: host ? new WeakRef(host) : null,
-		fires: 0,
-		lastFire: null
-	});
-	if (sub) _subId.set(sub, id);
-	_finalizer.register(node, id);
-	Object.defineProperty(node, "__pxRdId", {
-		value: id,
-		enumerable: false,
-		configurable: true
-	});
-	return id;
-}
-/**
-* Record that a node fired (signal write / computed recompute / effect
-* run). Bumps counters + appends to the bounded fire buffer.
-*
-* @internal
-*/
-function _rdRecordFire(node) {
-	if (!_active) return;
-	const id = node.__pxRdId;
-	if (id === void 0) return;
-	const rec = _byId.get(id);
-	const ts = typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
-	if (rec) {
-		rec.fires++;
-		rec.lastFire = ts;
-	}
-	if (_fireBuf === null) _fireBuf = new Array(FIRE_CAP);
-	_fireBuf[_fireCount % FIRE_CAP] = {
-		id,
-		ts
-	};
-	_fireCount++;
-}
-function resolveSubId(sub) {
-	const direct = sub.__pxRdId;
-	if (direct !== void 0) return direct;
-	return _subId.get(sub);
-}
-/**
-* 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.
-*/
-function getReactiveGraph() {
-	const nodes = [];
-	const edges = [];
-	for (const rec of _byId.values()) {
-		const node = rec.ref.deref();
-		if (!node) continue;
-		const subs = (rec.hostRef?.deref() ?? null)?._s ?? null;
-		const valueStr = rec.kind === "effect" ? "" : preview$1(node._v);
-		nodes.push({
-			id: rec.id,
-			kind: rec.kind,
-			name: rec.name,
-			value: valueStr,
-			subscribers: subs?.size ?? 0,
-			fires: rec.fires,
-			lastFire: rec.lastFire
-		});
-		if (subs) for (const cb of subs) {
-			const to = resolveSubId(cb);
-			if (to !== void 0) edges.push({
-				from: rec.id,
-				to
-			});
-		}
-	}
-	return {
-		nodes,
-		edges
-	};
-}
-/** Bounded recent-fire timeline (oldest → newest). Fresh copy. */
-function getReactiveFires() {
-	if (_fireBuf === null || _fireCount === 0) return [];
-	if (_fireCount <= FIRE_CAP) return _fireBuf.slice(0, _fireCount);
-	const start = _fireCount % FIRE_CAP;
-	const out = [];
-	for (let i = 0; i < FIRE_CAP; i++) {
-		const e = _fireBuf[(start + i) % FIRE_CAP];
-		if (e) out.push(e);
-	}
-	return out;
-}
-
 //#endregion
 //#region src/scope.ts
 var EffectScope = class {
@@ -560,7 +399,7 @@ function cleanupLocalDeps$1(deps, fn) {
 		deps.length = 0;
 	}
 }
-function effect(fn) {
+function effect(fn, options) {
 	if (process.env.NODE_ENV !== "production") {
 		if (fn.constructor && fn.constructor.name === "AsyncFunction") 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.");
 	}
@@ -628,7 +467,7 @@ function effect(fn) {
 		if (!isFirstRun) scope?.notifyEffectRan();
 		isFirstRun = false;
 	};
-	if (process.env.NODE_ENV !== "production") _rdRegister(run, "effect", null, run, void 0);
+	if (process.env.NODE_ENV !== "production") _rdRegister(run, "effect", null, run, void 0, options?.__sourceLocation ?? _captureCallerLocation(1));
 	run();
 	const e = { dispose() {
 		runCleanup();
@@ -727,7 +566,7 @@ function renderEffect(fn) {
 			}
 		} else renderEffectFullTrack(deps, run, trackedFn);
 	};
-	if (process.env.NODE_ENV !== "production") _rdRegister(run, "effect", null, run, void 0);
+	if (process.env.NODE_ENV !== "production") _rdRegister(run, "effect", null, run, void 0, _captureCallerLocation(1));
 	run();
 	const dispose = () => {
 		if (disposed) return;
@@ -759,7 +598,8 @@ function computed(fn, options) {
 	if (process.env.NODE_ENV !== "production") {
 		if (fn.constructor && fn.constructor.name === "AsyncFunction") 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);
+	const loc = options?.__sourceLocation;
+	return options?.equals ? computedWithEquals(fn, options.equals, loc) : computedLazy(fn, loc);
 }
 /**
 * Default computed — lazy evaluation with deferred cleanup.
@@ -771,7 +611,7 @@ function computed(fn, options) {
 * in diamond patterns (a→b,c→d: b notifies d, c tries to notify d again —
 * skipped because d is already dirty).
 */
-function computedLazy(fn) {
+function computedLazy(fn, injectedLoc) {
 	let value;
 	let dirty = true;
 	let disposed = false;
@@ -832,7 +672,7 @@ function computedLazy(fn) {
 			set.delete(updater);
 		};
 	};
-	if (process.env.NODE_ENV !== "production") _rdRegister(read, "derived", host, recompute, void 0);
+	if (process.env.NODE_ENV !== "production") _rdRegister(read, "derived", host, recompute, void 0, injectedLoc ?? _captureCallerLocation(2));
 	getCurrentScope()?.add({ dispose: read.dispose });
 	return read;
 }
@@ -842,7 +682,7 @@ function computedLazy(fn) {
 * Re-evaluates immediately when deps change and only notifies downstream
 * if `equals(prev, next)` returns false.
 */
-function computedWithEquals(fn, equals) {
+function computedWithEquals(fn, equals, injectedLoc) {
 	let value;
 	let dirty = true;
 	let initialized = false;
@@ -910,7 +750,7 @@ function computedWithEquals(fn, equals) {
 			set.delete(updater);
 		};
 	};
-	if (process.env.NODE_ENV !== "production") _rdRegister(read, "derived", host, recompute, void 0);
+	if (process.env.NODE_ENV !== "production") _rdRegister(read, "derived", host, recompute, void 0, injectedLoc ?? _captureCallerLocation(2));
 	getCurrentScope()?.add({ dispose: read.dispose });
 	return read;
 }
@@ -1275,7 +1115,10 @@ function signal(initialValue, options) {
 	read.direct = _directFn;
 	read.debug = _debug;
 	read.label = options?.name;
-	if (process.env.NODE_ENV !== "production") _rdRegister(read, "signal", read, null, read.label);
+	if (process.env.NODE_ENV !== "production") {
+		const loc = options?.__sourceLocation ? options.__sourceLocation : _captureCallerLocation(1);
+		_rdRegister(read, "signal", read, null, read.label, loc);
+	}
 	return read;
 }
 
@@ -1596,5 +1439,5 @@ function watch(source, callback, opts = {}) {
 }
 
 //#endregion
-export { Cell, EffectScope, _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, EffectScope, _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=index.js.map

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