@pyreon/reactivity 0.23.0 → 0.24.0

package/src/lpih.ts

@@ -0,0 +1,227 @@
+/**
+ * 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.
+ */
+
+import { getFireSummaries } from './reactive-devtools'
+
+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.
+ */
+export 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
+ */
+export function getDefaultLpihCachePath(): string | null {
+  if (typeof process === 'undefined') return null
+  // Pyreon's reactivity package narrows `process` to `{ env: ... }`.
+  // Cast through the runtime check so the call site typechecks under
+  // browser-target tsconfig while still working in Node where cwd exists.
+  const proc = process as unknown as { cwd?: () => string }
+  if (typeof proc.cwd !== 'function') return null
+  try {
+    const cwd = proc.cwd()
+    // Use forward-slash join; works on POSIX + Windows (Node accepts both).
+    return `${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.
+ */
+export async function writeLpihCache(path?: string): Promise<number> {
+  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: string): Promise<number> {
+  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 pid =
+    typeof process !== 'undefined' && 'pid' in process
+      ? (process as { pid?: number }).pid ?? 0
+      : 0
+  const tmp = `${path}.tmp.${pid}.${++_seq}`
+  const fs = await import('node:fs/promises')
+  // Single try/catch covering BOTH writeFile AND rename. The previous
+  // shape only guarded the rename — if `fs.writeFile` itself threw (disk
+  // full, EIO, EACCES, transient FS error), the partial tmp file leaked
+  // on disk with a unique PID+seq name. The same bug class lived in the
+  // vite-plugin's `writeLpihCacheFile` (R1); both fixed in lockstep.
+  try {
+    await fs.writeFile(tmp, JSON.stringify(payload), 'utf8')
+    await fs.rename(tmp, path)
+  } catch (err) {
+    // Rename / writeFile failed — clean up the tmp file so we don't leak
+    // it on disk. Covers BOTH paths: writeFile-failed (tmp may not exist
+    // → unlink ENOENT, swallowed) AND rename-failed (tmp exists). Common
+    // rename causes: cross-device link (rare; same dir → same FS), target
+    // is a directory, EACCES. The caller sees the original error; the
+    // cleanup is best-effort and silent (unlink may also fail if the FS
+    // is broken — re-throwing that would mask the real problem).
+    try {
+      await fs.unlink(tmp)
+    } catch {
+      /* swallow — original error is more useful */
+    }
+    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
+ * }
+ */
+export function startLpihPolling(
+  path?: string,
+  intervalMs = 250,
+): () => void {
+  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: string, intervalMs: number): () => void {
+  let active = true
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const tick = async (): Promise<void> => {
+    if (!active) return
+    try {
+      // Skip the default-resolution check on every tick — path is already
+      // resolved at startup.
+      await _writeToPath(path)
+    } catch {
+      // Swallow — polling continues. The LSP degrades gracefully if the
+      // file is missing or stale.
+    }
+    if (active) {
+      timer = setTimeout(tick, intervalMs)
+      // .unref() so a forgotten startLpihPolling() doesn't block process
+      // exit. Node-only; the setTimeout return type in browsers is a
+      // number with no .unref. Type-narrow defensively.
+      if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
+        ;(timer as { unref(): void }).unref()
+      }
+    }
+  }
+  void tick()
+  return () => {
+    active = false
+    if (timer !== null) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+}

package/src/reactive-devtools.ts

@@ -27,6 +27,26 @@
 
 export 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.
+ */
+export 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
+}
+
 export interface ReactiveNode {
   id: number
   kind: ReactiveNodeKind
@@ -40,6 +60,13 @@ export 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
 }
 
 export interface ReactiveEdge {
@@ -60,6 +87,46 @@ export interface ReactiveFire {
   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.
+ */
+export 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
+}
+
+/**
+ * Time constant for the rate1s EWMA (milliseconds). Tuned for the "hot
+ * path debugging" use case: a 1-second time constant means a burst of
+ * fires shows up immediately, then decays to 1/e (~0.37×) after one
+ * second of silence, ~5% after 3 seconds, ~0.7% after 5 seconds.
+ *
+ * @internal — exported for tests + tunability.
+ */
+export const LPIH_RATE_TAU_MS = 1000
+
 // ── Internal node record ─────────────────────────────────────────────────
 
 interface NodeRec {
@@ -72,6 +139,13 @@ interface NodeRec {
   hostRef: WeakRef<{ _s: Set<() => void> | null }> | null
   fires: number
   lastFire: number | null
+  /** Source location captured at registration. Undefined if stack parse failed. */
+  loc?: SourceLocation | undefined
+  /**
+   * EWMA-tracked fire rate (~fires/sec, 1s time constant). Updated on
+   * every fire; decayed to "now" at read time. See `FireSummary.rate1s`.
+   */
+  rate1s: number
 }
 
 let _active = false
@@ -154,6 +228,70 @@ export function isReactiveDevtoolsActive(): boolean {
 // ── Instrumentation entry points (called from the hot paths, but only
 //    after the existing prod gate; each is a no-op until activated) ──────
 
+/**
+ * Parse the user's call site from `new Error().stack`. Returns undefined
+ * when devtools isn't active (zero-cost early-return — no Error allocated)
+ * OR when the stack format isn't recognized.
+ *
+ * `skipFrames` is the number of caller-frames to skip past _captureCallerLocation
+ * itself. The framework's hot-path callers (signal / computedLazy / effect)
+ * pass their own depth so the captured frame is the USER's call to
+ * `signal()` / `computed()` / `effect()`, not the framework's internals.
+ *
+ * Recognized stack formats:
+ *   - V8 (Chrome / Node / Bun):     `    at fn (file:line:col)`
+ *   - V8 (anonymous):               `    at file:line:col`
+ *   - JSC (Safari) + SpiderMonkey:  `fn@file:line:col`
+ *
+ * @internal
+ */
+export function _captureCallerLocation(skipFrames: number): SourceLocation | undefined {
+  if (!_active) return undefined
+  const err = new Error()
+  const raw = err.stack
+  if (!raw) return undefined
+  const lines = raw.split('\n')
+  // V8 prepends "Error\n"; JSC doesn't. Detect and offset.
+  const startIdx = lines[0] && lines[0].trim().startsWith('Error') ? 1 : 0
+  // Skip past _captureCallerLocation's own frame (always +1) + caller's depth.
+  const target = lines[startIdx + 1 + skipFrames]
+  if (!target) return undefined
+  return parseStackLine(target)
+}
+
+/** @internal — exported for unit testing across runtimes. */
+export function _parseStackLine(line: string): SourceLocation | undefined {
+  return parseStackLine(line)
+}
+
+function parseStackLine(line: string): SourceLocation | undefined {
+  // V8 parenthesized form: "    at fnName (file:line:col)"
+  const v8Paren = line.match(/\(([^()]+):(\d+):(\d+)\)\s*$/)
+  if (v8Paren && v8Paren[1] && v8Paren[2] && v8Paren[3]) {
+    const file = v8Paren[1]
+    const lineN = Number.parseInt(v8Paren[2], 10)
+    const col = Number.parseInt(v8Paren[3], 10)
+    if (Number.isFinite(lineN) && Number.isFinite(col)) return { file, line: lineN, col }
+  }
+  // V8 anonymous form: "    at file:line:col"
+  const v8Bare = line.match(/at\s+([^\s()]+):(\d+):(\d+)\s*$/)
+  if (v8Bare && v8Bare[1] && v8Bare[2] && v8Bare[3]) {
+    const file = v8Bare[1]
+    const lineN = Number.parseInt(v8Bare[2], 10)
+    const col = Number.parseInt(v8Bare[3], 10)
+    if (Number.isFinite(lineN) && Number.isFinite(col)) return { file, line: lineN, col }
+  }
+  // JSC / SpiderMonkey form: "fnName@file:line:col"
+  const jsc = line.match(/@([^@\s]+):(\d+):(\d+)\s*$/)
+  if (jsc && jsc[1] && jsc[2] && jsc[3]) {
+    const file = jsc[1]
+    const lineN = Number.parseInt(jsc[2], 10)
+    const col = Number.parseInt(jsc[3], 10)
+    if (Number.isFinite(lineN) && Number.isFinite(col)) return { file, line: lineN, col }
+  }
+  return undefined
+}
+
 /**
  * Register a signal/computed/effect node. `host` is the object carrying
  * the `_s` subscriber Set (the signal read fn itself, or a computed's
@@ -168,6 +306,7 @@ export function _rdRegister(
   host: { _s: Set<() => void> | null } | null,
   sub: object | null,
   label: string | undefined,
+  loc?: SourceLocation,
 ): number | undefined {
   if (!_active) return undefined
   const id = _nextId++
@@ -179,6 +318,8 @@ export function _rdRegister(
     hostRef: host ? new WeakRef(host) : null,
     fires: 0,
     lastFire: null,
+    loc,
+    rate1s: 0,
   })
   if (sub) _subId.set(sub, id)
   _finalizer.register(node, id)
@@ -212,6 +353,20 @@ export function _rdRecordFire(node: object): void {
       : Date.now()
   if (rec) {
     rec.fires++
+    // EWMA rate update — decay the prior estimate by exp(-dt/TAU), then
+    // add 1 for this fire. At steady state of λ fires/sec, rate1s
+    // converges to ≈ λ when λ·TAU ≫ 1. For TAU=1000ms, that means
+    // "fires per second" in the natural sense.
+    if (rec.lastFire !== null) {
+      const dt = ts - rec.lastFire
+      const decay = Math.exp(-dt / LPIH_RATE_TAU_MS)
+      rec.rate1s = rec.rate1s * decay + 1
+    } else {
+      // First-ever fire: a single isolated fire reads as "1 fire/s" until
+      // the decay-at-read brings it down. Caller can interpret 1.0 as
+      // "at least one recent fire."
+      rec.rate1s = 1
+    }
     rec.lastFire = ts
   }
   if (_fireBuf === null) _fireBuf = new Array<ReactiveFire>(FIRE_CAP)
@@ -255,6 +410,7 @@ export function getReactiveGraph(): ReactiveGraph {
       subscribers: subs?.size ?? 0,
       fires: rec.fires,
       lastFire: rec.lastFire,
+      ...(rec.loc ? { loc: rec.loc } : {}),
     })
     if (subs) {
       for (const cb of subs) {
@@ -266,6 +422,63 @@ export function getReactiveGraph(): ReactiveGraph {
   return { nodes, edges }
 }
 
+/**
+ * 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.
+ */
+export function getFireSummaries(): FireSummary[] {
+  const byKey = new Map<string, FireSummary>()
+  // Snapshot "now" once per call — decay-at-read uses a consistent timestamp
+  // for all nodes, so two locations firing at the same rate show the same
+  // rate1s value even if iteration walks them in different orders.
+  const nowTs =
+    typeof performance !== 'undefined' && typeof performance.now === 'function'
+      ? performance.now()
+      : Date.now()
+  for (const rec of _byId.values()) {
+    if (!rec.loc) continue
+    if (!rec.ref.deref()) continue
+    const k = `${rec.loc.file}:${rec.loc.line}:${rec.loc.col}`
+    // Decay rate1s to "now" — a node that hasn't fired in 5×TAU shows
+    // ≈0.7% of its steady-state rate; in 10×TAU, basically 0. This is
+    // what makes "stopped firing" visible in the editor.
+    const decayedRate =
+      rec.lastFire !== null
+        ? rec.rate1s * Math.exp(-(nowTs - rec.lastFire) / LPIH_RATE_TAU_MS)
+        : 0
+    const existing = byKey.get(k)
+    if (existing) {
+      existing.count += rec.fires
+      // Sum rates at same location (e.g. two distinct signals on one
+      // line via destructuring). Latest-fire wins for kind / lastFire.
+      existing.rate1s += decayedRate
+      if (
+        rec.lastFire !== null &&
+        (existing.lastFire === null || rec.lastFire > existing.lastFire)
+      ) {
+        existing.lastFire = rec.lastFire
+        existing.kind = rec.kind
+      }
+    } else {
+      byKey.set(k, {
+        loc: rec.loc,
+        count: rec.fires,
+        lastFire: rec.lastFire,
+        kind: rec.kind,
+        rate1s: decayedRate,
+      })
+    }
+  }
+  return [...byKey.values()]
+}
+
 /** Bounded recent-fire timeline (oldest → newest). Fresh copy. */
 export function getReactiveFires(): ReactiveFire[] {
   if (_fireBuf === null || _fireCount === 0) return []

package/src/signal.ts

@@ -1,6 +1,6 @@
 import { batch, enqueuePendingNotification, isBatching } from './batch'
 import { _notifyTraceListeners, isTracing } from './debug'
-import { _rdRecordFire, _rdRegister } from './reactive-devtools'
+import { _captureCallerLocation, _rdRecordFire, _rdRegister } from './reactive-devtools'
 import { _recordSignalWrite } from './reactive-trace'
 import { notifySubscribers, trackSubscriber } from './tracking'
 
@@ -55,6 +55,17 @@ export interface Signal<T> {
 export 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 }
 }
 
 // Internal shape of a signal function — state stored as properties on the
@@ -234,8 +245,17 @@ export function signal<T>(initialValue: T, options?: SignalOptions): Signal<T> {
   read.debug = _debug as () => SignalDebugInfo<T>
   read.label = options?.name
 
-  if (process.env.NODE_ENV !== 'production')
-    _rdRegister(read, 'signal', read, null, read.label)
+  if (process.env.NODE_ENV !== 'production') {
+    // Prefer build-time-injected location (zero runtime cost) over the
+    // ~2.2µs stack-capture fallback. @pyreon/vite-plugin's
+    // `injectSignalLocations` rewrites `signal(0)` to
+    // `signal(0, { __sourceLocation: {...} })` at transform time so most
+    // dev-mode signals never pay the stack-capture cost.
+    const loc = options?.__sourceLocation
+      ? options.__sourceLocation
+      : _captureCallerLocation(1)
+    _rdRegister(read, 'signal', read, null, read.label, loc)
+  }
 
   return read as unknown as Signal<T>
 }