@flotrace/runtime-core 2.2.1 → 2.2.3

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

@@ -1,33 +1,76 @@
 # @flotrace/runtime-core
 
-Platform-agnostic core for the FloTrace runtime — fiber walker, hook/effect inspectors, state-store trackers, serializer, and WebSocket client. Shared by [`@flotrace/runtime`](https://www.npmjs.com/package/@flotrace/runtime) (web) and [`@flotrace/runtime-native`](https://www.npmjs.com/package/@flotrace/runtime-native) (React Native).
+Platform-agnostic core for [FloTrace](https://flotrace.dev) — fiber walker, hook/effect inspectors, state-store trackers (Zustand / Redux / TanStack Query), serializer, and WebSocket client. Shared between [`@flotrace/runtime`](https://www.npmjs.com/package/@flotrace/runtime) (web) and [`@flotrace/runtime-native`](https://www.npmjs.com/package/@flotrace/runtime-native) (React Native).
 
-> **You probably don't want this package directly.**
-> Install `@flotrace/runtime` for a web React app or `@flotrace/runtime-native` for React Native. Those adapters depend on `runtime-core` and provide the wiring (provider, network tracker, platform-specific hooks) you need.
+> **You almost certainly want one of the adapter packages instead.**
+>
+> - **Web React app?** → [`@flotrace/runtime`](https://www.npmjs.com/package/@flotrace/runtime)
+> - **React Native (Expo / bare)?** → [`@flotrace/runtime-native`](https://www.npmjs.com/package/@flotrace/runtime-native)
+>
+> The adapters depend on `runtime-core` and provide the wiring (provider component, network tracker, platform-specific hooks) you actually need. This package on its own does nothing useful at runtime.
 
-`runtime-core` is published as a public package so adapters can pin a compatible version. It has no runtime dependency on `window` / `document` / `XMLHttpRequest` — all platform-specific features live in the adapters.
+`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 |
 |---|---|
-| `fiberTreeWalker` | Incremental fiber walk, diffed tree emission, pluggable `pruneSubtree` / `frameworkComponentNames` / `hostComponentSkipPrefixes` options for platform adapters. |
-| `hookInspector` / `effectInspector` | Classify hooks and effects from a fiber; diff deps between commits. |
-| `zustandTracker` / `reduxTracker` / `tanstackQueryTracker` | Duck-typed subscribers for the major state libraries. |
-| `timelineTracker` | Per-component lifecycle events. |
-| `cascadeAnalyzer` / `propDrillingAnalyzer` | Render-cascade tracing + prop-drilling chain detection. |
-| `serializer` | Safe JSON serialization (depth 5, circular refs, truncation). |
-| `websocketClient` | Singleton WS client with reconnect, batching, auth-token support. |
+| `fiberTreeWalker` | Incremental fiber walk, diffed tree emission. Pluggable `pruneSubtree` / `frameworkComponentNames` / `hostComponentSkipPrefixes` for platform adapters. |
+| `hookInspector` / `effectInspector` | Classify hooks (14 types) and effects from a fiber; diff deps between commits. |
+| `zustandTracker` / `reduxTracker` / `tanstackQueryTracker` | Duck-typed subscribers for the major state libraries — no peer-dep bloat. |
+| `timelineTracker` | Per-component lifecycle events (mount, unmount, update, prop diff). |
+| `cascadeAnalyzer` / `propDrillingAnalyzer` | Render-cascade tracing + prop-drilling DFS chain detection with severity scoring. |
+| `serializer` | Safe JSON serialization (depth 5, circular-ref guard, truncation). |
+| `websocketClient` | Singleton WS client with exponential backoff reconnect, message batching, optional auth token. |
 
 ## Version compatibility
 
-`@flotrace/runtime-core@0.1.x` is the companion release for:
+`@flotrace/runtime-core@2.x` is the companion release for:
+
+- `@flotrace/runtime@2.x`
+- `@flotrace/runtime-native@2.x`
+
+All three are released in lockstep — pin the same major.minor across the trio. The desktop app and runtime versions are independent (the WebSocket protocol is versioned).
+
+## Why open?
 
-- `@flotrace/runtime@0.2.x`
-- `@flotrace/runtime-native@0.1.x`
+The runtime is what lives inside your app. Open-source means you can read every byte of the code that touches your fibers, audit the WebSocket payloads, and fork if FloTrace ever disappears. The desktop app is closed-source commercial — that's the bit we charge for. See [flotrace.dev/security](https://flotrace.dev/security) for the full threat model.
 
-Use matching minor versions when pinning across all three.
+## Contributing
+
+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

@@ -48,6 +48,13 @@ interface RuntimeReadyMessage {
     /** React Native version from `Platform.constants.reactNativeVersion`, formatted
      *  as "major.minor.patch". Native-only; web adapter leaves this undefined. */
     reactNativeVersion?: string;
+    /** Version of the @flotrace/runtime or @flotrace/runtime-native package the
+     *  user installed in their app. Lets the desktop diagnose runtime/desktop
+     *  drift (e.g., user pinned an older runtime that lacks a new feature).
+     *  Read from the adapter's own package.json at build time. The lockstep
+     *  release script keeps runtime-core pinned identically, so a separate
+     *  core-version field would be redundant. */
+    runtimeVersion?: string;
 }
 interface RuntimeRenderMessage {
     type: 'runtime:render';
@@ -867,10 +874,14 @@ interface FloTraceConfig {
     /** React Native version from `Platform.constants.reactNativeVersion`, formatted
      *  "major.minor.patch". Native adapter only. */
     reactNativeVersion?: string;
+    /** Version of the active runtime adapter (`@flotrace/runtime` on web,
+     *  `@flotrace/runtime-native` on RN). Adapters auto-populate from their
+     *  own package.json. Surfaced on `runtime:ready` for diagnostics. */
+    runtimeVersion?: string;
 }
 /** Keys that stay optional in DEFAULT_CONFIG. These are populated by adapters (web/native)
  *  at call-time — the default object should not pretend to know a platform or LAN token. */
-type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion';
+type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion' | 'runtimeVersion';
 type ResolvedFloTraceConfig = Required<Omit<FloTraceConfig, OptionalConfigKeys>> & Pick<FloTraceConfig, OptionalConfigKeys>;
 /**
  * Default configuration
@@ -1589,7 +1600,7 @@ declare function getChangedKeys(prev: Record<string, unknown> | undefined, next:
  * State lives here — in platform-agnostic core — so both the web and native
  * network trackers can write to the same registry that the analyzers read.
  */
-/** Tag an object and its nested children (depth ≤ 2) with the requestId. */
+/** Tag an object and its nested children (depth ≤ FETCH_ORIGIN_SCAN_DEPTH) with the requestId. */
 declare function tagFetchData(obj: unknown, requestId: string, depth?: number): void;
 /** Returns true if any API request's response data is currently tagged (within TTL window). */
 declare function hasActiveTags(): boolean;
@@ -1600,13 +1611,23 @@ declare function hasActiveTags(): boolean;
  */
 declare function clearFetchOriginTags(): void;
 /**
- * Scan an object (and nested children up to depth 2) for a WeakMap-tagged fetch origin.
- * Called by Zustand/Redux trackers synchronously in their subscribe callbacks.
- * Returns the requestId if this object was the result of a tracked fetch within the TTL
- * window, else undefined. TTL prevents stale entries from matching on later store updates
- * that reuse the same object references (immutable store pattern).
+ * Scan an object (and nested children up to FETCH_ORIGIN_SCAN_DEPTH) for a
+ * WeakMap-tagged fetch origin. Returns the requestId if this object was the
+ * result of a tracked fetch, else undefined.
+ *
+ * By default the result must be within FETCH_ORIGIN_TTL_MS of the original
+ * fetch. Network-panel features (live API → Store correlation in
+ * `storeUtils.buildCorrelatedRequests`, `tanstackQueryTracker.updateQueryTracking`,
+ * `fiberTreeWalker.scanFiberStateForOrigin`) rely on this gate to avoid
+ * mis-attributing later mutations.
+ *
+ * Pass `{ ignoreTTL: true }` to bypass the gate. Used by the value-lineage
+ * resolver, which wants the *causal* origin regardless of how long ago the
+ * fetch resolved (the trace UI displays an "expired" hint for old origins).
  */
-declare function findFetchOrigin(obj: unknown, depth?: number): string | undefined;
+declare function findFetchOrigin(obj: unknown, options?: {
+    ignoreTTL?: boolean;
+}): string | undefined;
 
 /**
  * Next.js App Router client-side detection.

package/dist/index.d.ts

@@ -48,6 +48,13 @@ interface RuntimeReadyMessage {
     /** React Native version from `Platform.constants.reactNativeVersion`, formatted
      *  as "major.minor.patch". Native-only; web adapter leaves this undefined. */
     reactNativeVersion?: string;
+    /** Version of the @flotrace/runtime or @flotrace/runtime-native package the
+     *  user installed in their app. Lets the desktop diagnose runtime/desktop
+     *  drift (e.g., user pinned an older runtime that lacks a new feature).
+     *  Read from the adapter's own package.json at build time. The lockstep
+     *  release script keeps runtime-core pinned identically, so a separate
+     *  core-version field would be redundant. */
+    runtimeVersion?: string;
 }
 interface RuntimeRenderMessage {
     type: 'runtime:render';
@@ -867,10 +874,14 @@ interface FloTraceConfig {
     /** React Native version from `Platform.constants.reactNativeVersion`, formatted
      *  "major.minor.patch". Native adapter only. */
     reactNativeVersion?: string;
+    /** Version of the active runtime adapter (`@flotrace/runtime` on web,
+     *  `@flotrace/runtime-native` on RN). Adapters auto-populate from their
+     *  own package.json. Surfaced on `runtime:ready` for diagnostics. */
+    runtimeVersion?: string;
 }
 /** Keys that stay optional in DEFAULT_CONFIG. These are populated by adapters (web/native)
  *  at call-time — the default object should not pretend to know a platform or LAN token. */
-type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion';
+type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion' | 'runtimeVersion';
 type ResolvedFloTraceConfig = Required<Omit<FloTraceConfig, OptionalConfigKeys>> & Pick<FloTraceConfig, OptionalConfigKeys>;
 /**
  * Default configuration
@@ -1589,7 +1600,7 @@ declare function getChangedKeys(prev: Record<string, unknown> | undefined, next:
  * State lives here — in platform-agnostic core — so both the web and native
  * network trackers can write to the same registry that the analyzers read.
  */
-/** Tag an object and its nested children (depth ≤ 2) with the requestId. */
+/** Tag an object and its nested children (depth ≤ FETCH_ORIGIN_SCAN_DEPTH) with the requestId. */
 declare function tagFetchData(obj: unknown, requestId: string, depth?: number): void;
 /** Returns true if any API request's response data is currently tagged (within TTL window). */
 declare function hasActiveTags(): boolean;
@@ -1600,13 +1611,23 @@ declare function hasActiveTags(): boolean;
  */
 declare function clearFetchOriginTags(): void;
 /**
- * Scan an object (and nested children up to depth 2) for a WeakMap-tagged fetch origin.
- * Called by Zustand/Redux trackers synchronously in their subscribe callbacks.
- * Returns the requestId if this object was the result of a tracked fetch within the TTL
- * window, else undefined. TTL prevents stale entries from matching on later store updates
- * that reuse the same object references (immutable store pattern).
+ * Scan an object (and nested children up to FETCH_ORIGIN_SCAN_DEPTH) for a
+ * WeakMap-tagged fetch origin. Returns the requestId if this object was the
+ * result of a tracked fetch, else undefined.
+ *
+ * By default the result must be within FETCH_ORIGIN_TTL_MS of the original
+ * fetch. Network-panel features (live API → Store correlation in
+ * `storeUtils.buildCorrelatedRequests`, `tanstackQueryTracker.updateQueryTracking`,
+ * `fiberTreeWalker.scanFiberStateForOrigin`) rely on this gate to avoid
+ * mis-attributing later mutations.
+ *
+ * Pass `{ ignoreTTL: true }` to bypass the gate. Used by the value-lineage
+ * resolver, which wants the *causal* origin regardless of how long ago the
+ * fetch resolved (the trace UI displays an "expired" hint for old origins).
  */
-declare function findFetchOrigin(obj: unknown, depth?: number): string | undefined;
+declare function findFetchOrigin(obj: unknown, options?: {
+    ignoreTTL?: boolean;
+}): string | undefined;
 
 /**
  * Next.js App Router client-side detection.

package/dist/index.js

@@ -84,7 +84,13 @@ module.exports = __toCommonJS(index_exports);
 var DEFAULT_CONFIG = {
   port: 3457,
   appName: "React App",
-  enabled: globalThis.process?.env?.NODE_ENV === "development",
+  // Default-on unless an explicit `process.env.NODE_ENV === 'production'` is
+  // detected. The previous heuristic (`=== 'development'`) silently disabled
+  // the runtime in any browser context that doesn't shim `process` (e.g. Vite,
+  // Webpack 5 with `node: false`, Rsbuild) — making the README quickstart fail
+  // for everyone. Production safety is handled by users gating the import via
+  // the dynamic-import pattern documented in the runtime READMEs.
+  enabled: globalThis.process?.env?.NODE_ENV !== "production",
   autoReconnect: true,
   reconnectInterval: 2e3,
   trackAllRenders: true,
@@ -309,7 +315,8 @@ var _FloTraceWebSocketClient = class _FloTraceWebSocketClient {
           appVersion: this.config.appVersion,
           frameworkName: this.config.frameworkName,
           frameworkVersion: this.config.frameworkVersion,
-          reactNativeVersion: this.config.reactNativeVersion
+          reactNativeVersion: this.config.reactNativeVersion,
+          runtimeVersion: this.config.runtimeVersion
         });
         this.flush();
       };
@@ -1840,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,
@@ -1865,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;
 }
@@ -1878,12 +1893,16 @@ function uninstallRscPayloadInterceptor() {
 var fetchDataOrigin = /* @__PURE__ */ new WeakMap();
 var requestTagTimestamps = /* @__PURE__ */ new Map();
 var FETCH_ORIGIN_TTL_MS = 3e3;
+var FETCH_ORIGIN_SCAN_DEPTH = 4;
+var FETCH_ORIGIN_TAG_ARRAY_LIMIT = 50;
+var FETCH_ORIGIN_SCAN_ARRAY_LIMIT = 20;
 function tagFetchData(obj, requestId, depth = 0) {
-  if (depth > 2 || obj === null || typeof obj !== "object") return;
+  if (depth > FETCH_ORIGIN_SCAN_DEPTH || obj === null || typeof obj !== "object") return;
   fetchDataOrigin.set(obj, requestId);
   if (depth === 0) requestTagTimestamps.set(requestId, Date.now());
   if (Array.isArray(obj)) {
-    for (let i = 0; i < Math.min(obj.length, 50); i++) tagFetchData(obj[i], requestId, depth + 1);
+    const limit = Math.min(obj.length, FETCH_ORIGIN_TAG_ARRAY_LIMIT);
+    for (let i = 0; i < limit; i++) tagFetchData(obj[i], requestId, depth + 1);
   } else {
     for (const val of Object.values(obj)) tagFetchData(val, requestId, depth + 1);
   }
@@ -1894,24 +1913,29 @@ function hasActiveTags() {
 function clearFetchOriginTags() {
   requestTagTimestamps.clear();
 }
-function findFetchOrigin(obj, depth = 0) {
-  if (depth > 2 || obj === null || typeof obj !== "object") return void 0;
+function findFetchOrigin(obj, options) {
+  return scanForOrigin(obj, 0, options?.ignoreTTL === true);
+}
+function scanForOrigin(obj, depth, ignoreTTL) {
+  if (depth > FETCH_ORIGIN_SCAN_DEPTH || obj === null || typeof obj !== "object") return void 0;
   const rid = fetchDataOrigin.get(obj);
   if (rid) {
+    if (ignoreTTL) return rid;
     const tagTime = requestTagTimestamps.get(rid);
     if (tagTime && Date.now() - tagTime <= FETCH_ORIGIN_TTL_MS) return rid;
     requestTagTimestamps.delete(rid);
   }
   if (Array.isArray(obj)) {
-    for (let i = 0; i < Math.min(obj.length, 20); i++) {
-      const found = findFetchOrigin(obj[i], depth + 1);
-      if (found) return found;
-    }
-  } else {
-    for (const val of Object.values(obj)) {
-      const found = findFetchOrigin(val, depth + 1);
+    const limit = Math.min(obj.length, FETCH_ORIGIN_SCAN_ARRAY_LIMIT);
+    for (let i = 0; i < limit; i++) {
+      const found = scanForOrigin(obj[i], depth + 1, ignoreTTL);
       if (found) return found;
     }
+    return void 0;
+  }
+  for (const val of Object.values(obj)) {
+    const found = scanForOrigin(val, depth + 1, ignoreTTL);
+    if (found) return found;
   }
   return void 0;
 }
@@ -3706,7 +3730,7 @@ function safeCall(fn, fallback) {
 
 // src/valueTraceResolver.ts
 var FIBER_TAG_CONTEXT_PROVIDER = 10;
-var BUDGET_MS = 50;
+var BUDGET_MS = 100;
 var SCAN_DEPTH = 3;
 var MAX_PROP_CHAIN_DEPTH = 30;
 function now() {
@@ -3730,34 +3754,49 @@ function getHookValueAt(fiber, hookIndex) {
   if (!hook) return void 0;
   return hook.memoizedState;
 }
-function valuesMatch(target, targetFp, candidate) {
+function cachedFp(value, cache) {
+  if (value === null || typeof value !== "object") return valueFingerprint(value);
+  const cached = cache.get(value);
+  if (cached !== void 0) return cached;
+  const fp = valueFingerprint(value);
+  cache.set(value, fp);
+  return fp;
+}
+function valuesMatch(target, targetFp, candidate, cache) {
   const targetIsObject = target !== null && typeof target === "object";
   const candidateIsObject = candidate !== null && typeof candidate === "object";
   if (targetIsObject && candidateIsObject && target === candidate) return "exact";
   if (!shouldFlagRename(target) || !shouldFlagRename(candidate)) return null;
-  if (valueFingerprint(candidate) === targetFp) return "fingerprint-match";
+  if (cachedFp(candidate, cache) === targetFp) return "fingerprint-match";
   return null;
 }
-function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline) {
+function findReferenceMatchAtTopLevel(target, container) {
+  if (target === null || typeof target !== "object") return null;
+  for (const key of Object.keys(container)) {
+    if (container[key] === target) return key;
+  }
+  return null;
+}
+function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline, cache) {
   if (now() > deadline) return null;
   if (depth > SCAN_DEPTH) return null;
   if (container === null || typeof container !== "object") return null;
-  const selfMatch = valuesMatch(target, targetFp, container);
+  const selfMatch = valuesMatch(target, targetFp, container, cache);
   if (selfMatch) return { path: [...currentPath], confidence: selfMatch };
   if (Array.isArray(container)) {
     for (let i = 0; i < Math.min(container.length, 50); i++) {
       const child = container[i];
-      const directMatch = valuesMatch(target, targetFp, child);
+      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);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, deadline, cache);
       if (nested) return nested;
     }
   } else {
     for (const key of Object.keys(container)) {
       const child = container[key];
-      const directMatch = valuesMatch(target, targetFp, child);
+      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);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, deadline, cache);
       if (nested) return nested;
     }
   }
@@ -3770,6 +3809,59 @@ function buildFiberToNodeIdMap() {
   }
   return reverse;
 }
+function retreatToEnclosingObject(fiber, propPath, rootValue) {
+  const isObject = rootValue !== null && typeof rootValue === "object";
+  if (isObject || propPath.length <= 1 || !fiber.memoizedProps) {
+    return { rootValue, trailingSubPath: [] };
+  }
+  let path = propPath.slice();
+  let value = rootValue;
+  const trail = [];
+  while (path.length > 1 && (value === null || typeof value !== "object")) {
+    trail.unshift(path[path.length - 1]);
+    path = path.slice(0, -1);
+    value = walkPath(fiber.memoizedProps, path);
+  }
+  if (value === null || typeof value !== "object") {
+    return { rootValue, trailingSubPath: [] };
+  }
+  return { rootValue: value, trailingSubPath: trail };
+}
+function isDebugEnabled() {
+  try {
+    return !!globalThis.__FLOTRACE_DEBUG__;
+  } catch {
+    return false;
+  }
+}
+function findFetchOriginUpKeyPath(stateRoot, keyPath) {
+  const ancestors = [stateRoot];
+  let cursor = stateRoot;
+  for (const segment of keyPath) {
+    if (cursor === null || typeof cursor !== "object") break;
+    cursor = cursor[segment];
+    ancestors.push(cursor);
+  }
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const value = ancestors[i];
+    if (value === null || typeof value !== "object") continue;
+    const rid = findFetchOrigin(value, { ignoreTTL: true });
+    if (rid) {
+      if (isDebugEnabled()) {
+        console.debug("[FloTrace] origin via keyPath retreat", {
+          keyPath,
+          depthHit: i,
+          requestId: rid
+        });
+      }
+      return rid;
+    }
+  }
+  return void 0;
+}
+function resolveOriginViaTagOrKeyPath(matchedValue, stateRoot, keyPath) {
+  return findFetchOrigin(matchedValue, { ignoreTTL: true }) ?? findFetchOriginUpKeyPath(stateRoot, keyPath);
+}
 function resolveValueTrace(input) {
   const startedAt = now();
   const deadline = startedAt + BUDGET_MS;
@@ -3798,9 +3890,13 @@ function resolveValueTrace(input) {
   if (rootValue === void 0) {
     return { ...base, error: "value-not-found", resolvedAtMs: now() };
   }
+  const retreated = input.propPath ? retreatToEnclosingObject(fiber, input.propPath, rootValue) : { rootValue, trailingSubPath: [] };
+  rootValue = retreated.rootValue;
+  const trailingSubPath = retreated.trailingSubPath;
   const rootFp = valueFingerprint(rootValue);
   const fiberToNodeId = buildFiberToNodeIdMap();
   const rootComponentName = getComponentNameFromFiber(fiber) ?? "Unknown";
+  const fpCache = /* @__PURE__ */ new WeakMap();
   if (input.propPath) {
     steps.push({
       kind: "prop",
@@ -3829,8 +3925,17 @@ function resolveValueTrace(input) {
       if (current.tag !== FIBER_TAG_CONTEXT_PROVIDER) {
         const props = current.memoizedProps;
         if (props) {
-          const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline);
-          if (match) {
+          const refKey = findReferenceMatchAtTopLevel(rootValue, props);
+          let matchPath = refKey !== null ? [refKey] : null;
+          let matchConfidence = "exact";
+          if (matchPath === null) {
+            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline, fpCache);
+            if (match) {
+              matchPath = match.path;
+              matchConfidence = match.confidence;
+            }
+          }
+          if (matchPath !== null) {
             const ancestorNodeId = fiberToNodeId.get(current);
             const ancestorName = getComponentNameFromFiber(current) ?? "Unknown";
             if (ancestorNodeId) {
@@ -3838,10 +3943,28 @@ function resolveValueTrace(input) {
                 kind: "prop",
                 nodeId: ancestorNodeId,
                 componentName: ancestorName,
-                propPath: match.path,
-                confidence: match.confidence
+                propPath: trailingSubPath.length > 0 ? [...matchPath, ...trailingSubPath] : matchPath,
+                confidence: matchConfidence
               });
             }
+          } else {
+            const hookMatch = findMatchingHookState(current, rootValue, rootFp, fpCache);
+            if (hookMatch) {
+              const ancestorNodeId = fiberToNodeId.get(current);
+              const ancestorName = getComponentNameFromFiber(current) ?? "Unknown";
+              if (ancestorNodeId) {
+                steps.push({
+                  kind: "hook-state",
+                  nodeId: ancestorNodeId,
+                  componentName: ancestorName,
+                  hookIndex: hookMatch.hookIndex,
+                  hookType: hookMatch.hookType,
+                  subPath: trailingSubPath.length > 0 ? trailingSubPath : void 0,
+                  confidence: hookMatch.confidence
+                });
+                return { ...base, steps, resolvedAtMs: now() };
+              }
+            }
           }
         }
       }
@@ -3850,7 +3973,7 @@ function resolveValueTrace(input) {
     }
   }
   if (input.hookPath) {
-    const origin = findFetchOrigin(rootValue);
+    const origin = findFetchOrigin(rootValue, { ignoreTTL: true });
     if (origin) {
       steps.push({
         kind: "api",
@@ -3862,15 +3985,15 @@ function resolveValueTrace(input) {
       return { ...base, steps, resolvedAtMs: now() };
     }
   }
-  const derivedMatch = findDerivationMatch(fiber, rootValue, rootFp, rootComponentName);
+  const derivedMatch = findDerivationMatch(fiber, rootValue, rootFp, rootComponentName, fpCache);
   if (derivedMatch) {
     steps.push({ ...derivedMatch, nodeId: input.nodeId });
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId);
+  const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId, fpCache);
   if (contextMatch) {
     steps.push(contextMatch.step);
-    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, valueFingerprint(contextMatch.providerValue), deadline);
+    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), deadline, fpCache);
     if (providerStoreMatch) {
       steps.push({
         kind: "store",
@@ -3879,19 +4002,23 @@ function resolveValueTrace(input) {
         keyPath: providerStoreMatch.keyPath,
         confidence: providerStoreMatch.confidence
       });
-      const origin = findFetchOrigin(providerStoreMatch.matchedValue);
+      const origin = resolveOriginViaTagOrKeyPath(
+        providerStoreMatch.matchedValue,
+        providerStoreMatch.stateRoot,
+        providerStoreMatch.keyPath
+      );
       if (origin) {
         steps.push({ kind: "api", requestId: origin, method: "UNKNOWN", urlPath: "", ageMs: 0 });
       }
     } else {
-      const origin = findFetchOrigin(contextMatch.providerValue);
+      const origin = findFetchOrigin(contextMatch.providerValue, { ignoreTTL: true });
       if (origin) {
         steps.push({ kind: "api", requestId: origin, method: "UNKNOWN", urlPath: "", ageMs: 0 });
       }
     }
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const storeMatch = findStoreMatch(rootValue, rootFp, deadline);
+  const storeMatch = findStoreMatch(rootValue, rootFp, deadline, fpCache);
   if (storeMatch) {
     steps.push({
       kind: "store",
@@ -3900,7 +4027,11 @@ function resolveValueTrace(input) {
       keyPath: storeMatch.keyPath,
       confidence: storeMatch.confidence
     });
-    const origin = findFetchOrigin(storeMatch.matchedValue);
+    const origin = resolveOriginViaTagOrKeyPath(
+      storeMatch.matchedValue,
+      storeMatch.stateRoot,
+      storeMatch.keyPath
+    );
     if (origin) {
       steps.push({
         kind: "api",
@@ -3913,12 +4044,12 @@ function resolveValueTrace(input) {
   }
   return { ...base, steps, resolvedAtMs: now() };
 }
-function findContextMatch(consumer, target, targetFp, fiberToNodeId) {
+function findContextMatch(consumer, target, targetFp, fiberToNodeId, cache) {
   const deps = consumer.dependencies?.firstContext;
   if (!deps) return null;
   let dep = deps;
   while (dep) {
-    const match = valuesMatch(target, targetFp, dep.memoizedValue);
+    const match = valuesMatch(target, targetFp, dep.memoizedValue, cache);
     if (match) {
       const provider = findNearestProvider(consumer, dep.context);
       const step = {
@@ -3934,14 +4065,14 @@ function findContextMatch(consumer, target, targetFp, fiberToNodeId) {
   }
   return null;
 }
-function findDerivationMatch(fiber, target, targetFp, componentName) {
+function findDerivationMatch(fiber, target, targetFp, componentName, cache) {
   let hook = fiber.memoizedState;
   let index = 0;
   while (hook) {
     const ms = hook.memoizedState;
     if (Array.isArray(ms) && ms.length === 2 && Array.isArray(ms[1])) {
       const [computed, deps] = ms;
-      const match = valuesMatch(target, targetFp, computed);
+      const match = valuesMatch(target, targetFp, computed, cache);
       if (match) {
         const hookType = typeof computed === "function" ? "useCallback" : "useMemo";
         return {
@@ -3960,6 +4091,25 @@ function findDerivationMatch(fiber, target, targetFp, componentName) {
   }
   return null;
 }
+function findMatchingHookState(fiber, target, targetFp, cache) {
+  let hook = fiber.memoizedState;
+  let index = 0;
+  while (hook) {
+    const ms = hook.memoizedState;
+    const isMemoTuple = Array.isArray(ms) && ms.length === 2 && Array.isArray(ms[1]);
+    const isEffectShape2 = ms !== null && typeof ms === "object" && "create" in ms && "deps" in ms;
+    const isRefShape = ms !== null && typeof ms === "object" && Object.keys(ms).length === 1 && "current" in ms;
+    if (!isMemoTuple && !isEffectShape2 && !isRefShape) {
+      const match = valuesMatch(target, targetFp, ms, cache);
+      if (match) {
+        return { hookIndex: index, hookType: "useState", confidence: match };
+      }
+    }
+    hook = hook.next;
+    index++;
+  }
+  return null;
+}
 function findNearestProvider(consumer, contextObj) {
   let current = consumer.return;
   let hops = 0;
@@ -3973,44 +4123,47 @@ function findNearestProvider(consumer, contextObj) {
   }
   return null;
 }
-function findStoreMatch(target, targetFp, deadline) {
+function findStoreMatch(target, targetFp, deadline, cache) {
   for (const [storeName, state] of getZustandSnapshot()) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "zustand",
         storeName,
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(state, hit.path)
+        matchedValue: walkPath(state, hit.path),
+        stateRoot: state
       };
     }
   }
   const redux = getReduxSnapshot();
   if (redux) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "redux",
         storeName: "redux",
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(redux, hit.path)
+        matchedValue: walkPath(redux, hit.path),
+        stateRoot: redux
       };
     }
   }
   for (const [queryHash, entry] of getTanstackSnapshot()) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "tanstack-query",
         storeName: queryHash,
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(entry.data, hit.path)
+        matchedValue: walkPath(entry.data, hit.path),
+        stateRoot: entry.data
       };
     }
   }

package/dist/index.mjs

@@ -2,7 +2,13 @@
 var DEFAULT_CONFIG = {
   port: 3457,
   appName: "React App",
-  enabled: globalThis.process?.env?.NODE_ENV === "development",
+  // Default-on unless an explicit `process.env.NODE_ENV === 'production'` is
+  // detected. The previous heuristic (`=== 'development'`) silently disabled
+  // the runtime in any browser context that doesn't shim `process` (e.g. Vite,
+  // Webpack 5 with `node: false`, Rsbuild) — making the README quickstart fail
+  // for everyone. Production safety is handled by users gating the import via
+  // the dynamic-import pattern documented in the runtime READMEs.
+  enabled: globalThis.process?.env?.NODE_ENV !== "production",
   autoReconnect: true,
   reconnectInterval: 2e3,
   trackAllRenders: true,
@@ -227,7 +233,8 @@ var _FloTraceWebSocketClient = class _FloTraceWebSocketClient {
           appVersion: this.config.appVersion,
           frameworkName: this.config.frameworkName,
           frameworkVersion: this.config.frameworkVersion,
-          reactNativeVersion: this.config.reactNativeVersion
+          reactNativeVersion: this.config.reactNativeVersion,
+          runtimeVersion: this.config.runtimeVersion
         });
         this.flush();
       };
@@ -1758,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,
@@ -1783,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;
 }
@@ -1796,12 +1811,16 @@ function uninstallRscPayloadInterceptor() {
 var fetchDataOrigin = /* @__PURE__ */ new WeakMap();
 var requestTagTimestamps = /* @__PURE__ */ new Map();
 var FETCH_ORIGIN_TTL_MS = 3e3;
+var FETCH_ORIGIN_SCAN_DEPTH = 4;
+var FETCH_ORIGIN_TAG_ARRAY_LIMIT = 50;
+var FETCH_ORIGIN_SCAN_ARRAY_LIMIT = 20;
 function tagFetchData(obj, requestId, depth = 0) {
-  if (depth > 2 || obj === null || typeof obj !== "object") return;
+  if (depth > FETCH_ORIGIN_SCAN_DEPTH || obj === null || typeof obj !== "object") return;
   fetchDataOrigin.set(obj, requestId);
   if (depth === 0) requestTagTimestamps.set(requestId, Date.now());
   if (Array.isArray(obj)) {
-    for (let i = 0; i < Math.min(obj.length, 50); i++) tagFetchData(obj[i], requestId, depth + 1);
+    const limit = Math.min(obj.length, FETCH_ORIGIN_TAG_ARRAY_LIMIT);
+    for (let i = 0; i < limit; i++) tagFetchData(obj[i], requestId, depth + 1);
   } else {
     for (const val of Object.values(obj)) tagFetchData(val, requestId, depth + 1);
   }
@@ -1812,24 +1831,29 @@ function hasActiveTags() {
 function clearFetchOriginTags() {
   requestTagTimestamps.clear();
 }
-function findFetchOrigin(obj, depth = 0) {
-  if (depth > 2 || obj === null || typeof obj !== "object") return void 0;
+function findFetchOrigin(obj, options) {
+  return scanForOrigin(obj, 0, options?.ignoreTTL === true);
+}
+function scanForOrigin(obj, depth, ignoreTTL) {
+  if (depth > FETCH_ORIGIN_SCAN_DEPTH || obj === null || typeof obj !== "object") return void 0;
   const rid = fetchDataOrigin.get(obj);
   if (rid) {
+    if (ignoreTTL) return rid;
     const tagTime = requestTagTimestamps.get(rid);
     if (tagTime && Date.now() - tagTime <= FETCH_ORIGIN_TTL_MS) return rid;
     requestTagTimestamps.delete(rid);
   }
   if (Array.isArray(obj)) {
-    for (let i = 0; i < Math.min(obj.length, 20); i++) {
-      const found = findFetchOrigin(obj[i], depth + 1);
-      if (found) return found;
-    }
-  } else {
-    for (const val of Object.values(obj)) {
-      const found = findFetchOrigin(val, depth + 1);
+    const limit = Math.min(obj.length, FETCH_ORIGIN_SCAN_ARRAY_LIMIT);
+    for (let i = 0; i < limit; i++) {
+      const found = scanForOrigin(obj[i], depth + 1, ignoreTTL);
       if (found) return found;
     }
+    return void 0;
+  }
+  for (const val of Object.values(obj)) {
+    const found = scanForOrigin(val, depth + 1, ignoreTTL);
+    if (found) return found;
   }
   return void 0;
 }
@@ -3624,7 +3648,7 @@ function safeCall(fn, fallback) {
 
 // src/valueTraceResolver.ts
 var FIBER_TAG_CONTEXT_PROVIDER = 10;
-var BUDGET_MS = 50;
+var BUDGET_MS = 100;
 var SCAN_DEPTH = 3;
 var MAX_PROP_CHAIN_DEPTH = 30;
 function now() {
@@ -3648,34 +3672,49 @@ function getHookValueAt(fiber, hookIndex) {
   if (!hook) return void 0;
   return hook.memoizedState;
 }
-function valuesMatch(target, targetFp, candidate) {
+function cachedFp(value, cache) {
+  if (value === null || typeof value !== "object") return valueFingerprint(value);
+  const cached = cache.get(value);
+  if (cached !== void 0) return cached;
+  const fp = valueFingerprint(value);
+  cache.set(value, fp);
+  return fp;
+}
+function valuesMatch(target, targetFp, candidate, cache) {
   const targetIsObject = target !== null && typeof target === "object";
   const candidateIsObject = candidate !== null && typeof candidate === "object";
   if (targetIsObject && candidateIsObject && target === candidate) return "exact";
   if (!shouldFlagRename(target) || !shouldFlagRename(candidate)) return null;
-  if (valueFingerprint(candidate) === targetFp) return "fingerprint-match";
+  if (cachedFp(candidate, cache) === targetFp) return "fingerprint-match";
   return null;
 }
-function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline) {
+function findReferenceMatchAtTopLevel(target, container) {
+  if (target === null || typeof target !== "object") return null;
+  for (const key of Object.keys(container)) {
+    if (container[key] === target) return key;
+  }
+  return null;
+}
+function findMatchingPathInObject(target, targetFp, container, currentPath, depth, deadline, cache) {
   if (now() > deadline) return null;
   if (depth > SCAN_DEPTH) return null;
   if (container === null || typeof container !== "object") return null;
-  const selfMatch = valuesMatch(target, targetFp, container);
+  const selfMatch = valuesMatch(target, targetFp, container, cache);
   if (selfMatch) return { path: [...currentPath], confidence: selfMatch };
   if (Array.isArray(container)) {
     for (let i = 0; i < Math.min(container.length, 50); i++) {
       const child = container[i];
-      const directMatch = valuesMatch(target, targetFp, child);
+      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);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, String(i)], depth + 1, deadline, cache);
       if (nested) return nested;
     }
   } else {
     for (const key of Object.keys(container)) {
       const child = container[key];
-      const directMatch = valuesMatch(target, targetFp, child);
+      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);
+      const nested = findMatchingPathInObject(target, targetFp, child, [...currentPath, key], depth + 1, deadline, cache);
       if (nested) return nested;
     }
   }
@@ -3688,6 +3727,59 @@ function buildFiberToNodeIdMap() {
   }
   return reverse;
 }
+function retreatToEnclosingObject(fiber, propPath, rootValue) {
+  const isObject = rootValue !== null && typeof rootValue === "object";
+  if (isObject || propPath.length <= 1 || !fiber.memoizedProps) {
+    return { rootValue, trailingSubPath: [] };
+  }
+  let path = propPath.slice();
+  let value = rootValue;
+  const trail = [];
+  while (path.length > 1 && (value === null || typeof value !== "object")) {
+    trail.unshift(path[path.length - 1]);
+    path = path.slice(0, -1);
+    value = walkPath(fiber.memoizedProps, path);
+  }
+  if (value === null || typeof value !== "object") {
+    return { rootValue, trailingSubPath: [] };
+  }
+  return { rootValue: value, trailingSubPath: trail };
+}
+function isDebugEnabled() {
+  try {
+    return !!globalThis.__FLOTRACE_DEBUG__;
+  } catch {
+    return false;
+  }
+}
+function findFetchOriginUpKeyPath(stateRoot, keyPath) {
+  const ancestors = [stateRoot];
+  let cursor = stateRoot;
+  for (const segment of keyPath) {
+    if (cursor === null || typeof cursor !== "object") break;
+    cursor = cursor[segment];
+    ancestors.push(cursor);
+  }
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const value = ancestors[i];
+    if (value === null || typeof value !== "object") continue;
+    const rid = findFetchOrigin(value, { ignoreTTL: true });
+    if (rid) {
+      if (isDebugEnabled()) {
+        console.debug("[FloTrace] origin via keyPath retreat", {
+          keyPath,
+          depthHit: i,
+          requestId: rid
+        });
+      }
+      return rid;
+    }
+  }
+  return void 0;
+}
+function resolveOriginViaTagOrKeyPath(matchedValue, stateRoot, keyPath) {
+  return findFetchOrigin(matchedValue, { ignoreTTL: true }) ?? findFetchOriginUpKeyPath(stateRoot, keyPath);
+}
 function resolveValueTrace(input) {
   const startedAt = now();
   const deadline = startedAt + BUDGET_MS;
@@ -3716,9 +3808,13 @@ function resolveValueTrace(input) {
   if (rootValue === void 0) {
     return { ...base, error: "value-not-found", resolvedAtMs: now() };
   }
+  const retreated = input.propPath ? retreatToEnclosingObject(fiber, input.propPath, rootValue) : { rootValue, trailingSubPath: [] };
+  rootValue = retreated.rootValue;
+  const trailingSubPath = retreated.trailingSubPath;
   const rootFp = valueFingerprint(rootValue);
   const fiberToNodeId = buildFiberToNodeIdMap();
   const rootComponentName = getComponentNameFromFiber(fiber) ?? "Unknown";
+  const fpCache = /* @__PURE__ */ new WeakMap();
   if (input.propPath) {
     steps.push({
       kind: "prop",
@@ -3747,8 +3843,17 @@ function resolveValueTrace(input) {
       if (current.tag !== FIBER_TAG_CONTEXT_PROVIDER) {
         const props = current.memoizedProps;
         if (props) {
-          const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline);
-          if (match) {
+          const refKey = findReferenceMatchAtTopLevel(rootValue, props);
+          let matchPath = refKey !== null ? [refKey] : null;
+          let matchConfidence = "exact";
+          if (matchPath === null) {
+            const match = findMatchingPathInObject(rootValue, rootFp, props, [], 0, deadline, fpCache);
+            if (match) {
+              matchPath = match.path;
+              matchConfidence = match.confidence;
+            }
+          }
+          if (matchPath !== null) {
             const ancestorNodeId = fiberToNodeId.get(current);
             const ancestorName = getComponentNameFromFiber(current) ?? "Unknown";
             if (ancestorNodeId) {
@@ -3756,10 +3861,28 @@ function resolveValueTrace(input) {
                 kind: "prop",
                 nodeId: ancestorNodeId,
                 componentName: ancestorName,
-                propPath: match.path,
-                confidence: match.confidence
+                propPath: trailingSubPath.length > 0 ? [...matchPath, ...trailingSubPath] : matchPath,
+                confidence: matchConfidence
               });
             }
+          } else {
+            const hookMatch = findMatchingHookState(current, rootValue, rootFp, fpCache);
+            if (hookMatch) {
+              const ancestorNodeId = fiberToNodeId.get(current);
+              const ancestorName = getComponentNameFromFiber(current) ?? "Unknown";
+              if (ancestorNodeId) {
+                steps.push({
+                  kind: "hook-state",
+                  nodeId: ancestorNodeId,
+                  componentName: ancestorName,
+                  hookIndex: hookMatch.hookIndex,
+                  hookType: hookMatch.hookType,
+                  subPath: trailingSubPath.length > 0 ? trailingSubPath : void 0,
+                  confidence: hookMatch.confidence
+                });
+                return { ...base, steps, resolvedAtMs: now() };
+              }
+            }
           }
         }
       }
@@ -3768,7 +3891,7 @@ function resolveValueTrace(input) {
     }
   }
   if (input.hookPath) {
-    const origin = findFetchOrigin(rootValue);
+    const origin = findFetchOrigin(rootValue, { ignoreTTL: true });
     if (origin) {
       steps.push({
         kind: "api",
@@ -3780,15 +3903,15 @@ function resolveValueTrace(input) {
       return { ...base, steps, resolvedAtMs: now() };
     }
   }
-  const derivedMatch = findDerivationMatch(fiber, rootValue, rootFp, rootComponentName);
+  const derivedMatch = findDerivationMatch(fiber, rootValue, rootFp, rootComponentName, fpCache);
   if (derivedMatch) {
     steps.push({ ...derivedMatch, nodeId: input.nodeId });
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId);
+  const contextMatch = findContextMatch(fiber, rootValue, rootFp, fiberToNodeId, fpCache);
   if (contextMatch) {
     steps.push(contextMatch.step);
-    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, valueFingerprint(contextMatch.providerValue), deadline);
+    const providerStoreMatch = findStoreMatch(contextMatch.providerValue, cachedFp(contextMatch.providerValue, fpCache), deadline, fpCache);
     if (providerStoreMatch) {
       steps.push({
         kind: "store",
@@ -3797,19 +3920,23 @@ function resolveValueTrace(input) {
         keyPath: providerStoreMatch.keyPath,
         confidence: providerStoreMatch.confidence
       });
-      const origin = findFetchOrigin(providerStoreMatch.matchedValue);
+      const origin = resolveOriginViaTagOrKeyPath(
+        providerStoreMatch.matchedValue,
+        providerStoreMatch.stateRoot,
+        providerStoreMatch.keyPath
+      );
       if (origin) {
         steps.push({ kind: "api", requestId: origin, method: "UNKNOWN", urlPath: "", ageMs: 0 });
       }
     } else {
-      const origin = findFetchOrigin(contextMatch.providerValue);
+      const origin = findFetchOrigin(contextMatch.providerValue, { ignoreTTL: true });
       if (origin) {
         steps.push({ kind: "api", requestId: origin, method: "UNKNOWN", urlPath: "", ageMs: 0 });
       }
     }
     return { ...base, steps, resolvedAtMs: now() };
   }
-  const storeMatch = findStoreMatch(rootValue, rootFp, deadline);
+  const storeMatch = findStoreMatch(rootValue, rootFp, deadline, fpCache);
   if (storeMatch) {
     steps.push({
       kind: "store",
@@ -3818,7 +3945,11 @@ function resolveValueTrace(input) {
       keyPath: storeMatch.keyPath,
       confidence: storeMatch.confidence
     });
-    const origin = findFetchOrigin(storeMatch.matchedValue);
+    const origin = resolveOriginViaTagOrKeyPath(
+      storeMatch.matchedValue,
+      storeMatch.stateRoot,
+      storeMatch.keyPath
+    );
     if (origin) {
       steps.push({
         kind: "api",
@@ -3831,12 +3962,12 @@ function resolveValueTrace(input) {
   }
   return { ...base, steps, resolvedAtMs: now() };
 }
-function findContextMatch(consumer, target, targetFp, fiberToNodeId) {
+function findContextMatch(consumer, target, targetFp, fiberToNodeId, cache) {
   const deps = consumer.dependencies?.firstContext;
   if (!deps) return null;
   let dep = deps;
   while (dep) {
-    const match = valuesMatch(target, targetFp, dep.memoizedValue);
+    const match = valuesMatch(target, targetFp, dep.memoizedValue, cache);
     if (match) {
       const provider = findNearestProvider(consumer, dep.context);
       const step = {
@@ -3852,14 +3983,14 @@ function findContextMatch(consumer, target, targetFp, fiberToNodeId) {
   }
   return null;
 }
-function findDerivationMatch(fiber, target, targetFp, componentName) {
+function findDerivationMatch(fiber, target, targetFp, componentName, cache) {
   let hook = fiber.memoizedState;
   let index = 0;
   while (hook) {
     const ms = hook.memoizedState;
     if (Array.isArray(ms) && ms.length === 2 && Array.isArray(ms[1])) {
       const [computed, deps] = ms;
-      const match = valuesMatch(target, targetFp, computed);
+      const match = valuesMatch(target, targetFp, computed, cache);
       if (match) {
         const hookType = typeof computed === "function" ? "useCallback" : "useMemo";
         return {
@@ -3878,6 +4009,25 @@ function findDerivationMatch(fiber, target, targetFp, componentName) {
   }
   return null;
 }
+function findMatchingHookState(fiber, target, targetFp, cache) {
+  let hook = fiber.memoizedState;
+  let index = 0;
+  while (hook) {
+    const ms = hook.memoizedState;
+    const isMemoTuple = Array.isArray(ms) && ms.length === 2 && Array.isArray(ms[1]);
+    const isEffectShape2 = ms !== null && typeof ms === "object" && "create" in ms && "deps" in ms;
+    const isRefShape = ms !== null && typeof ms === "object" && Object.keys(ms).length === 1 && "current" in ms;
+    if (!isMemoTuple && !isEffectShape2 && !isRefShape) {
+      const match = valuesMatch(target, targetFp, ms, cache);
+      if (match) {
+        return { hookIndex: index, hookType: "useState", confidence: match };
+      }
+    }
+    hook = hook.next;
+    index++;
+  }
+  return null;
+}
 function findNearestProvider(consumer, contextObj) {
   let current = consumer.return;
   let hops = 0;
@@ -3891,44 +4041,47 @@ function findNearestProvider(consumer, contextObj) {
   }
   return null;
 }
-function findStoreMatch(target, targetFp, deadline) {
+function findStoreMatch(target, targetFp, deadline, cache) {
   for (const [storeName, state] of getZustandSnapshot()) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, state, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "zustand",
         storeName,
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(state, hit.path)
+        matchedValue: walkPath(state, hit.path),
+        stateRoot: state
       };
     }
   }
   const redux = getReduxSnapshot();
   if (redux) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, redux, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "redux",
         storeName: "redux",
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(redux, hit.path)
+        matchedValue: walkPath(redux, hit.path),
+        stateRoot: redux
       };
     }
   }
   for (const [queryHash, entry] of getTanstackSnapshot()) {
     if (now() > deadline) return null;
-    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline);
+    const hit = findMatchingPathInObject(target, targetFp, entry.data, [], 0, deadline, cache);
     if (hit) {
       return {
         source: "tanstack-query",
         storeName: queryHash,
         keyPath: hit.path,
         confidence: hit.confidence,
-        matchedValue: walkPath(entry.data, hit.path)
+        matchedValue: walkPath(entry.data, hit.path),
+        stateRoot: entry.data
       };
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flotrace/runtime-core",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "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"