@pyreon/reactivity 0.22.0 → 0.24.0

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.22.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 {

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
+    }
+  }
+}