@flotrace/runtime-core 2.2.2 → 2.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Sitre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,6 +11,33 @@ Platform-agnostic core for [FloTrace](https://flotrace.dev) — fiber walker, ho
 
 `runtime-core` is published publicly so adapters can pin a compatible version and so users can audit the open-source half of FloTrace. It has zero runtime dependency on `window` / `document` / `XMLHttpRequest` — all platform-specific features live in the adapters.
 
+---
+
+## About FloTrace Desktop
+
+[**FloTrace Desktop**](https://flotrace.dev) is a free Electron app (macOS / Windows / Linux) that visualizes a running React app's component hierarchy in real time. It pairs with this runtime over a local WebSocket on port `3457` — the runtime sits inside your app and emits metadata; the desktop app renders the live tree, props, hooks, effects, and state. **Source code never leaves your machine.**
+
+What you get when this runtime is paired with the desktop:
+
+- **Live component tree** — React Flow graph, render-flash animation, frequency-based heatmap, breadcrumb navigation.
+- **Per-node inspection** — props (with diff history), hooks (14 classified types + dep diffs), effects (willRun + dep diffs), component timeline.
+- **State tracking** — Zustand (per-store), Redux (with change highlighting), Router, TanStack Query (with health warnings + wasted-refetch detection), Context.
+- **Render cascade tracing** — trigger log, cascade tree, flame chart, cascade compare modal.
+- **Prop drilling detection** — chain detection (≥3 levels deep), severity badges, heatmap overlay, refactor recommendations.
+- **Network health** — fetch / XHR tracking, method badges, status dots, duplicate detection, API → store causal correlation.
+- **Watch expressions** — pin values from 8 sources (Zustand / Redux / Router / Context / Props / Hooks / TanStack Query / API).
+- **AI Code Review Dashboard** — 6-tab review (Re-renders, Memo, Drilling, Effects, Compiler, Network) with Lighthouse-style scores.
+- **Copy-as-Prompt** — turn any panel into an AI-ready prompt for Cursor / Claude / ChatGPT in one click.
+
+How it fits together:
+
+```
+your React app  ←→  @flotrace/runtime[-native]  ←→  ws://localhost:3457  ←→  FloTrace Desktop
+                       (this stack — open source, MIT)         (closed-source commercial)
+```
+
+[**Download FloTrace Desktop →**](https://flotrace.dev) · [Docs](https://flotrace.dev/docs) · [Security model](https://flotrace.dev/security)
+
 ## What's inside
 
 | Module | Purpose |
@@ -38,8 +65,12 @@ The runtime is what lives inside your app. Open-source means you can read every
 
 ## Contributing
 
-Issues and PRs welcome at [github.com/flotrace](https://github.com/flotrace). The runtime packages target Hermes, V8 (Chromium), and JavaScriptCore — please test against all three when changing fiber-walker or serializer code.
+Issues and PRs welcome at [github.com/sameersitre/runtime-core](https://github.com/sameersitre/runtime-core). The runtime packages target Hermes, V8 (Chromium), and JavaScriptCore — please test against all three when changing fiber-walker or serializer code.
 
 ## License
 
-MIT.
+MIT — see [LICENSE](./LICENSE).
+
+---
+
+> **Mirrored from the [flotrace-desktop](https://github.com/sameersitre/flotrace-desktop) monorepo.** This repo is read-only — every release is regenerated by the lockstep publisher in the desktop monorepo. Issues filed here are tracked, but PRs are best opened against the upstream monorepo where the canonical source lives.

package/dist/index.d.mts

@@ -708,15 +708,12 @@ interface ValueTrace {
     steps: TraceStep[];
     /** Wall-clock time the resolver completed. */
     resolvedAtMs: number;
-    /** True when the 50ms budget tripped and the chain is partial. */
-    truncated?: boolean;
     /**
      * Optional error hint for friendly empty states.
      * - `value-not-found`: target path doesn't exist on the current fiber.
      * - `no-fiber`: nodeId no longer present in fiberRefMap (component unmounted).
-     * - `budget-exceeded`: bailed before finding origin.
      */
-    error?: 'value-not-found' | 'no-fiber' | 'budget-exceeded';
+    error?: 'value-not-found' | 'no-fiber';
 }
 interface RuntimeValueTraceMessage {
     type: 'runtime:valueTrace';
@@ -898,7 +895,8 @@ declare const DEFAULT_CONFIG: ResolvedFloTraceConfig;
  *   2. Store match    — scan Zustand / Redux / TanStack Query live snapshots
  *   3. API match      — feed matched reference into fetchOriginRegistry WeakMap
  *
- * On-demand only — never runs per-render. Hard 50 ms wall-clock budget.
+ * On-demand only — never runs per-render. Bounded by MAX_PROP_CHAIN_DEPTH and
+ * SCAN_DEPTH structural limits; no wall-clock budget so every trace runs to origin.
  * Uses reference identity (`===`) before fingerprinting to keep common cases fast.
  *
  * See docs/PRD-VALUE-LINEAGE.md §6 and docs/IMPLEMENTATION-PLAN-VALUE-LINEAGE.md Phase 2.

package/dist/index.d.ts

@@ -708,15 +708,12 @@ interface ValueTrace {
     steps: TraceStep[];
     /** Wall-clock time the resolver completed. */
     resolvedAtMs: number;
-    /** True when the 50ms budget tripped and the chain is partial. */
-    truncated?: boolean;
     /**
      * Optional error hint for friendly empty states.
      * - `value-not-found`: target path doesn't exist on the current fiber.
      * - `no-fiber`: nodeId no longer present in fiberRefMap (component unmounted).
-     * - `budget-exceeded`: bailed before finding origin.
      */
-    error?: 'value-not-found' | 'no-fiber' | 'budget-exceeded';
+    error?: 'value-not-found' | 'no-fiber';
 }
 interface RuntimeValueTraceMessage {
     type: 'runtime:valueTrace';
@@ -898,7 +895,8 @@ declare const DEFAULT_CONFIG: ResolvedFloTraceConfig;
  *   2. Store match    — scan Zustand / Redux / TanStack Query live snapshots
  *   3. API match      — feed matched reference into fetchOriginRegistry WeakMap
  *
- * On-demand only — never runs per-render. Hard 50 ms wall-clock budget.
+ * On-demand only — never runs per-render. Bounded by MAX_PROP_CHAIN_DEPTH and
+ * SCAN_DEPTH structural limits; no wall-clock budget so every trace runs to origin.
  * Uses reference identity (`===`) before fingerprinting to keep common cases fast.
  *
  * See docs/PRD-VALUE-LINEAGE.md §6 and docs/IMPLEMENTATION-PLAN-VALUE-LINEAGE.md Phase 2.

package/dist/index.js

@@ -1847,20 +1847,23 @@ function extractRoute(url) {
 var originalFetch = null;
 var interceptorClient = null;
 var isInstalled2 = false;
+var patchedFetchRef = null;
 function installRscPayloadInterceptor(client2) {
   if (isInstalled2 || typeof globalThis.fetch !== "function") return;
   isInstalled2 = true;
   interceptorClient = client2;
   originalFetch = globalThis.fetch;
-  globalThis.fetch = async function patchedFetch(input, init) {
+  const capturedOriginalFetch = originalFetch;
+  const capturedClient = client2;
+  const patchedFetch = async function patchedFetch2(input, init) {
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     const isRscRequest = RSC_URL_PATTERNS.some((p) => p.test(url));
-    const response = await originalFetch.call(globalThis, input, init);
-    if (isRscRequest && interceptorClient?.connected) {
+    const response = await capturedOriginalFetch.call(globalThis, input, init);
+    if (isRscRequest && interceptorClient === capturedClient && capturedClient.connected) {
       try {
         const sizeHeader = response.headers.get("content-length");
         const payloadSizeBytes = sizeHeader ? parseInt(sizeHeader, 10) : 0;
-        interceptorClient.send({
+        capturedClient.send({
           type: "runtime:rscPayload",
           route: extractRoute(url),
           payloadSizeBytes: isNaN(payloadSizeBytes) ? 0 : payloadSizeBytes,
@@ -1872,11 +1875,16 @@ function installRscPayloadInterceptor(client2) {
     }
     return response;
   };
+  patchedFetchRef = patchedFetch;
+  globalThis.fetch = patchedFetch;
 }
 function uninstallRscPayloadInterceptor() {
   if (!isInstalled2 || !originalFetch) return;
-  globalThis.fetch = originalFetch;
+  if (globalThis.fetch === patchedFetchRef) {
+    globalThis.fetch = originalFetch;
+  }
   originalFetch = null;
+  patchedFetchRef = null;
   interceptorClient = null;
   isInstalled2 = false;
 }
@@ -3722,7 +3730,6 @@ function safeCall(fn, fallback) {
 
 // src/valueTraceResolver.ts
 var FIBER_TAG_CONTEXT_PROVIDER = 10;
-var BUDGET_MS = 100;
 var SCAN_DEPTH = 3;
 var MAX_PROP_CHAIN_DEPTH = 30;
 function now() {
@@ -3769,8 +3776,7 @@ function findReferenceMatchAtTopLevel(target, container) {
   }
   return null;
 }
-function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline, cache) {
-  if (now() > deadline) return null;
+function findMatchingPathInObject(target, targetFp, container, currentPath, depth, cache) {
   if (depth > SCAN_DEPTH) return null;
   if (container === null || typeof container !== "object") return null;
   const selfMatch = valuesMatch(target, targetFp, container, cache);
@@ -3780,7 +3786,7 @@ function findMatchingPathInObject(target, targetFp, container, currentPath, dept
       const child = container[i];
       const directMatch = valuesMatch(target, targetFp, child, cache);
       if (directMatch) return { path: [...currentPath, String(i)], confidence: directMatch };
-      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, deadline, cache);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, cache);
       if (nested) return nested;
     }
   } else {
@@ -3788,7 +3794,7 @@ function findMatchingPathInObject(target, targetFp, container, currentPath, dept
       const child = container[key];
       const directMatch = valuesMatch(target, targetFp, child, cache);
       if (directMatch) return { path: [...currentPath, key], confidence: directMatch };
-      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, deadline, cache);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, cache);
       if (nested) return nested;
     }
   }
@@ -3855,8 +3861,6 @@ function resolveOriginViaTagOrKeyPath(matchedValue, stateRoot, keyPath) {
   return findFetchOrigin(matchedValue, { ignoreTTL: true }) ?? findFetchOriginUpKeyPath(stateRoot, keyPath);
 }
 function resolveValueTrace(input) {
-  const startedAt = now();
-  const deadline = startedAt + BUDGET_MS;
   const steps = [];
   const base = {
     rootNodeId: input.nodeId,
@@ -3913,7 +3917,6 @@ function resolveValueTrace(input) {
     let current = fiber.return;
     let hops = 0;
     while (current && hops < MAX_PROP_CHAIN_DEPTH) {
-      if (now() > deadline) return { ...base, steps, truncated: true, resolvedAtMs: now() };
       if (current.tag !== FIBER_TAG_CONTEXT_PROVIDER) {
         const props = current.memoizedProps;
         if (props) {
@@ -3921,7 +3924,7 @@ function resolveValueTrace(input) {
           let matchPath = refKey !== null ? [refKey] : null;
           let matchConfidence = "exact";
           if (matchPath === null) {
-            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline, fpCache);
+            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, fpCache);
             if (match) {
               matchPath = match.path;
               matchConfidence = match.confidence;
@@ -3985,7 +3988,7 @@ function resolveValueTrace(input) {
   const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId, fpCache);
   if (contextMatch) {
     steps.push(contextMatch.step);
-    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), deadline, fpCache);
+    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), fpCache);
     if (providerStoreMatch) {
       steps.push({
         kind: "store",
@@ -4010,7 +4013,7 @@ function resolveValueTrace(input) {
     }
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const storeMatch = findStoreMatch(rootValue, rootFp, deadline, fpCache);
+  const storeMatch = findStoreMatch(rootValue, rootFp, fpCache);
   if (storeMatch) {
     steps.push({
       kind: "store",
@@ -4115,10 +4118,9 @@ function findNearestProvider(consumer, contextObj) {
   }
   return null;
 }
-function findStoreMatch(target, targetFp, deadline, cache) {
+function findStoreMatch(target, targetFp, cache) {
   for (const [storeName, state] of getZustandSnapshot()) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, cache);
     if (hit) {
       return {
         source: "zustand",
@@ -4132,8 +4134,7 @@ function findStoreMatch(target, targetFp, deadline, cache) {
   }
   const redux = getReduxSnapshot();
   if (redux) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, cache);
     if (hit) {
       return {
         source: "redux",
@@ -4146,8 +4147,7 @@ function findStoreMatch(target, targetFp, deadline, cache) {
     }
   }
   for (const [queryHash, entry] of getTanstackSnapshot()) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, cache);
     if (hit) {
       return {
         source: "tanstack-query",

package/dist/index.mjs

@@ -1765,20 +1765,23 @@ function extractRoute(url) {
 var originalFetch = null;
 var interceptorClient = null;
 var isInstalled2 = false;
+var patchedFetchRef = null;
 function installRscPayloadInterceptor(client2) {
   if (isInstalled2 || typeof globalThis.fetch !== "function") return;
   isInstalled2 = true;
   interceptorClient = client2;
   originalFetch = globalThis.fetch;
-  globalThis.fetch = async function patchedFetch(input, init) {
+  const capturedOriginalFetch = originalFetch;
+  const capturedClient = client2;
+  const patchedFetch = async function patchedFetch2(input, init) {
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     const isRscRequest = RSC_URL_PATTERNS.some((p) => p.test(url));
-    const response = await originalFetch.call(globalThis, input, init);
-    if (isRscRequest && interceptorClient?.connected) {
+    const response = await capturedOriginalFetch.call(globalThis, input, init);
+    if (isRscRequest && interceptorClient === capturedClient && capturedClient.connected) {
       try {
         const sizeHeader = response.headers.get("content-length");
         const payloadSizeBytes = sizeHeader ? parseInt(sizeHeader, 10) : 0;
-        interceptorClient.send({
+        capturedClient.send({
           type: "runtime:rscPayload",
           route: extractRoute(url),
           payloadSizeBytes: isNaN(payloadSizeBytes) ? 0 : payloadSizeBytes,
@@ -1790,11 +1793,16 @@ function installRscPayloadInterceptor(client2) {
     }
     return response;
   };
+  patchedFetchRef = patchedFetch;
+  globalThis.fetch = patchedFetch;
 }
 function uninstallRscPayloadInterceptor() {
   if (!isInstalled2 || !originalFetch) return;
-  globalThis.fetch = originalFetch;
+  if (globalThis.fetch === patchedFetchRef) {
+    globalThis.fetch = originalFetch;
+  }
   originalFetch = null;
+  patchedFetchRef = null;
   interceptorClient = null;
   isInstalled2 = false;
 }
@@ -3640,7 +3648,6 @@ function safeCall(fn, fallback) {
 
 // src/valueTraceResolver.ts
 var FIBER_TAG_CONTEXT_PROVIDER = 10;
-var BUDGET_MS = 100;
 var SCAN_DEPTH = 3;
 var MAX_PROP_CHAIN_DEPTH = 30;
 function now() {
@@ -3687,8 +3694,7 @@ function findReferenceMatchAtTopLevel(target, container) {
   }
   return null;
 }
-function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline, cache) {
-  if (now() > deadline) return null;
+function findMatchingPathInObject(target, targetFp, container, currentPath, depth, cache) {
   if (depth > SCAN_DEPTH) return null;
   if (container === null || typeof container !== "object") return null;
   const selfMatch = valuesMatch(target, targetFp, container, cache);
@@ -3698,7 +3704,7 @@ function findMatchingPathInObject(target, targetFp, container, currentPath, dept
       const child = container[i];
       const directMatch = valuesMatch(target, targetFp, child, cache);
       if (directMatch) return { path: [...currentPath, String(i)], confidence: directMatch };
-      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, deadline, cache);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, cache);
       if (nested) return nested;
     }
   } else {
@@ -3706,7 +3712,7 @@ function findMatchingPathInObject(target, targetFp, container, currentPath, dept
       const child = container[key];
       const directMatch = valuesMatch(target, targetFp, child, cache);
       if (directMatch) return { path: [...currentPath, key], confidence: directMatch };
-      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, deadline, cache);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, cache);
       if (nested) return nested;
     }
   }
@@ -3773,8 +3779,6 @@ function resolveOriginViaTagOrKeyPath(matchedValue, stateRoot, keyPath) {
   return findFetchOrigin(matchedValue, { ignoreTTL: true }) ?? findFetchOriginUpKeyPath(stateRoot, keyPath);
 }
 function resolveValueTrace(input) {
-  const startedAt = now();
-  const deadline = startedAt + BUDGET_MS;
   const steps = [];
   const base = {
     rootNodeId: input.nodeId,
@@ -3831,7 +3835,6 @@ function resolveValueTrace(input) {
     let current = fiber.return;
     let hops = 0;
     while (current && hops < MAX_PROP_CHAIN_DEPTH) {
-      if (now() > deadline) return { ...base, steps, truncated: true, resolvedAtMs: now() };
       if (current.tag !== FIBER_TAG_CONTEXT_PROVIDER) {
         const props = current.memoizedProps;
         if (props) {
@@ -3839,7 +3842,7 @@ function resolveValueTrace(input) {
           let matchPath = refKey !== null ? [refKey] : null;
           let matchConfidence = "exact";
           if (matchPath === null) {
-            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline, fpCache);
+            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, fpCache);
             if (match) {
               matchPath = match.path;
               matchConfidence = match.confidence;
@@ -3903,7 +3906,7 @@ function resolveValueTrace(input) {
   const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId, fpCache);
   if (contextMatch) {
     steps.push(contextMatch.step);
-    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), deadline, fpCache);
+    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), fpCache);
     if (providerStoreMatch) {
       steps.push({
         kind: "store",
@@ -3928,7 +3931,7 @@ function resolveValueTrace(input) {
     }
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const storeMatch = findStoreMatch(rootValue, rootFp, deadline, fpCache);
+  const storeMatch = findStoreMatch(rootValue, rootFp, fpCache);
   if (storeMatch) {
     steps.push({
       kind: "store",
@@ -4033,10 +4036,9 @@ function findNearestProvider(consumer, contextObj) {
   }
   return null;
 }
-function findStoreMatch(target, targetFp, deadline, cache) {
+function findStoreMatch(target, targetFp, cache) {
   for (const [storeName, state] of getZustandSnapshot()) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, cache);
     if (hit) {
       return {
         source: "zustand",
@@ -4050,8 +4052,7 @@ function findStoreMatch(target, targetFp, deadline, cache) {
   }
   const redux = getReduxSnapshot();
   if (redux) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, cache);
     if (hit) {
       return {
         source: "redux",
@@ -4064,8 +4065,7 @@ function findStoreMatch(target, targetFp, deadline, cache) {
     }
   }
   for (const [queryHash, entry] of getTanstackSnapshot()) {
-    if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline, cache);
+    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, cache);
     if (hit) {
       return {
         source: "tanstack-query",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flotrace/runtime-core",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Platform-agnostic core for FloTrace runtime — fiber walker, analyzers, trackers. Shared by @flotrace/runtime (web) and @flotrace/runtime-native (React Native).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,7 +13,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -46,10 +48,13 @@
     "flotrace"
   ],
   "license": "MIT",
+  "homepage": "https://flotrace.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/flotrace/flotrace.git",
-    "directory": "packages/runtime-core"
+    "url": "https://github.com/sameersitre/runtime-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sameersitre/runtime-core/issues"
   },
   "publishConfig": {
     "access": "public"