@flotrace/runtime-core 2.0.0 → 2.2.0

package/dist/index.d.mts

@@ -26,7 +26,7 @@ type SerializedValue = null | boolean | number | string | SerializedValue[] | {
 /**
  * Messages sent from runtime to extension
  */
-type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimePongMessage;
+type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimeValueTraceMessage | RuntimePongMessage;
 interface RuntimeReadyMessage {
     type: 'runtime:ready';
     appName?: string;
@@ -39,6 +39,15 @@ interface RuntimeReadyMessage {
     appId?: string;
     /** App version — shown in the desktop connection panel for diagnostic purposes. */
     appVersion?: string;
+    /** Auto-detected framework family. Adapters populate this from runtime probes
+     *  (DOM signals on web, optional-require on native). */
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    /** Framework version when the adapter can resolve it (e.g. Next.js via
+     *  `require('next/package.json').version`). Missing when unavailable. */
+    frameworkVersion?: string;
+    /** React Native version from `Platform.constants.reactNativeVersion`, formatted
+     *  as "major.minor.patch". Native-only; web adapter leaves this undefined. */
+    reactNativeVersion?: string;
 }
 interface RuntimeRenderMessage {
     type: 'runtime:render';
@@ -610,6 +619,103 @@ interface RuntimeLocalStateCorrelationMessage {
     hookIndex: number;
     timestamp: number;
 }
+/**
+ * Confidence of a single trace step boundary.
+ * - `exact`: reference identity (`===`) preserved across the step.
+ * - `fingerprint-match`: only structural match via valueFingerprint(). Primitive
+ *   collisions are possible here (e.g., `count: 5` at multiple call sites).
+ */
+type TraceConfidence = 'exact' | 'fingerprint-match';
+/**
+ * A single step in a value-origin chain.
+ * Chain ordering: consumer first, origin last.
+ */
+type TraceStep = {
+    kind: 'prop';
+    nodeId: string;
+    componentName: string;
+    /** Dot-path into the component's props (e.g., ['user', 'profile', 'avatarUrl']). */
+    propPath: string[];
+    /** If this step came via a rename edge in the drilling graph. */
+    renamedFrom?: string;
+    confidence: TraceConfidence;
+} | {
+    kind: 'hook-state';
+    nodeId: string;
+    componentName: string;
+    hookIndex: number;
+    hookType: HookType;
+    /** Sub-path into the hook's current value, when the traced leaf is nested. */
+    subPath?: string[];
+    confidence: TraceConfidence;
+} | {
+    kind: 'store';
+    source: 'zustand' | 'redux' | 'tanstack-query';
+    storeName: string;
+    /** Key path into the store state where the matching value lives. */
+    keyPath: string[];
+    confidence: TraceConfidence;
+} | {
+    kind: 'api';
+    requestId: string;
+    method: string;
+    /** URL path only — query params stripped for privacy. */
+    urlPath: string;
+    status?: number;
+    /** Age of the fetch at trace resolution time. */
+    ageMs: number;
+    /** True when the 3s FETCH_ORIGIN_TTL_MS window has lapsed. */
+    expired?: boolean;
+} | {
+    kind: 'context';
+    contextName: string;
+    providerNodeId?: string;
+    confidence: TraceConfidence;
+} | {
+    /** Value is the cached result of a useMemo/useCallback on the same fiber.
+     *  `depCount` tells the UI how many upstream inputs the memo depends on
+     *  (one of which the user may want to click-trace next). */
+    kind: 'derived';
+    nodeId: string;
+    componentName: string;
+    hookIndex: number;
+    hookType: 'useMemo' | 'useCallback';
+    depCount: number;
+    confidence: TraceConfidence;
+};
+/**
+ * Result of a single value-trace request.
+ */
+interface ValueTrace {
+    /** Round-trip ID — mirrors the requestId from ext:traceValue. */
+    requestId: string;
+    rootNodeId: string;
+    /** Dot-path from the component when tracing a prop (e.g., ['user','profile','avatarUrl']). */
+    rootPropPath?: string[];
+    /** When tracing a hook value, addresses hook index + optional sub-path inside its value. */
+    rootHookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
+    /** Ordered steps — index 0 is the consumer, last index is the origin. */
+    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';
+}
+interface RuntimeValueTraceMessage {
+    type: 'runtime:valueTrace';
+    trace: ValueTrace;
+    timestamp: number;
+}
 /**
  * Messages received from extension
  */
@@ -664,6 +770,23 @@ type ExtensionToRuntimeMessage = {
     type: 'ext:startTanstackTracking';
 } | {
     type: 'ext:stopTanstackTracking';
+}
+/**
+ * Value Lineage — resolve the origin of a specific prop or hook value.
+ * Either `propPath` or `hookPath` must be set (exactly one).
+ */
+ | {
+    type: 'ext:traceValue';
+    /** Round-trip ID — echoed back in runtime:valueTrace. */
+    requestId: string;
+    nodeId: string;
+    /** When tracing a prop: dot-path like ['user','profile','avatarUrl']. Index 0 is the top-level prop key. */
+    propPath?: string[];
+    /** When tracing a hook value: hook index + optional nested sub-path inside its value. */
+    hookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
 };
 interface TrackingOptions {
     trackAllRenders?: boolean;
@@ -736,16 +859,54 @@ interface FloTraceConfig {
      *  be hidden by strict mode (e.g. monorepo packages resolved into
      *  `node_modules/@workspace/ui`). Only consulted when `userOnlyStrict` is on. */
     userAllowPatterns?: RegExp[];
+    /** Auto-detected framework family. Adapters set this via platform-specific probes
+     *  (DOM signals on web; optional-require on native). Not a user-facing knob. */
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    /** Framework version when the adapter can resolve it. Not a user-facing knob. */
+    frameworkVersion?: string;
+    /** React Native version from `Platform.constants.reactNativeVersion`, formatted
+     *  "major.minor.patch". Native adapter only. */
+    reactNativeVersion?: 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';
+type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion';
 type ResolvedFloTraceConfig = Required<Omit<FloTraceConfig, OptionalConfigKeys>> & Pick<FloTraceConfig, OptionalConfigKeys>;
 /**
  * Default configuration
  */
 declare const DEFAULT_CONFIG: ResolvedFloTraceConfig;
 
+/**
+ * Value Lineage — origin tracing resolver.
+ *
+ * Given a component's prop-path or hook-path, walk upward through three layers
+ * to find where the value originated:
+ *
+ *   1. Prop chain     — walk fiber.return upward, match fingerprint at each level
+ *   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.
+ * 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.
+ */
+
+interface ValueTraceInput {
+    nodeId: string;
+    propPath?: string[];
+    hookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
+}
+/**
+ * Resolve the origin chain for a specific prop or hook value on a component.
+ * Returns `{requestId}`-less trace — caller adds the round-trip id.
+ */
+declare function resolveValueTrace(input: ValueTraceInput): Omit<ValueTrace, 'requestId'>;
+
 /**
  * Fiber Tree Walker for @flotrace/runtime
  *
@@ -1157,7 +1318,13 @@ declare class FloTraceWebSocketClient {
      */
     get connected(): boolean;
     /**
-     * Get React version if available
+     * Get React version if available.
+     *
+     * Historical note: an earlier implementation read `globalThis.React?.version` —
+     * but React is an ES-module import in modern bundles (Vite/webpack/Next.js) and
+     * is never placed on `globalThis`, so the probe returned undefined for every
+     * typical bundled app. Reading `React.version` via a direct import is
+     * authoritative across web (both CJS and ESM bundles), React Native, and SSR.
      */
     private getReactVersion;
 }
@@ -1200,6 +1367,16 @@ declare function installZustandTracker(stores: Record<string, ZustandStoreApi>,
  * Uninstall Zustand store tracking, unsubscribing from all stores.
  */
 declare function uninstallZustandTracker(): void;
+/**
+ * Snapshot of every tracked Zustand store's current **raw** state (not
+ * serialized). Used by the Value Lineage resolver to match component values
+ * against store keys via reference identity + structural fingerprint, and to
+ * pass raw object references into `findFetchOrigin()` for API correlation.
+ *
+ * Returns a fresh map on each call — does not cache. Cheap because `.getState()`
+ * is O(1) on Zustand.
+ */
+declare function getZustandSnapshot(): Map<string, Record<string, unknown>>;
 
 /**
  * Redux Store Tracker for @flotrace/runtime
@@ -1235,6 +1412,11 @@ declare function installReduxTracker(store: ReduxStoreApi, client: FloTraceWebSo
  * Uninstall Redux store tracking.
  */
 declare function uninstallReduxTracker(): void;
+/**
+ * Current raw Redux state, or null when the tracker isn't installed. Used by
+ * the Value Lineage resolver.
+ */
+declare function getReduxSnapshot(): Record<string, unknown> | null;
 
 /**
  * TanStack Query Tracker for @flotrace/runtime
@@ -1333,6 +1515,18 @@ declare function installTanStackQueryTracker(queryClient: TanStackQueryClientApi
  * Uninstall TanStack Query tracking.
  */
 declare function uninstallTanStackQueryTracker(): void;
+/**
+ * Snapshot of every cached query's **raw** data (not serialized) keyed by
+ * queryHash. Used by the Value Lineage resolver to match component values
+ * against TanStack Query cache via reference identity + structural fingerprint,
+ * and to pass raw references into `findFetchOrigin()`.
+ *
+ * Returns an empty map when the tracker isn't installed.
+ */
+declare function getTanstackSnapshot(): Map<string, {
+    queryKey: unknown[];
+    data: unknown;
+}>;
 
 /**
  * Component Event Timeline for @flotrace/runtime
@@ -1445,6 +1639,45 @@ declare function detectServerComponent(fiber: Fiber): boolean;
 /** Reset detection state (useful for tests / hot-reload) */
 declare function resetNextjsDetection(): void;
 
+/**
+ * Framework + framework-version detection (web adapter).
+ *
+ * Detects whether the running page is Next.js vs plain React and attempts to
+ * resolve the Next.js version via the package's own `package.json`. All signals
+ * are probed at runtime; absence is non-fatal and simply returns `undefined`.
+ *
+ * Node version of the project is intentionally NOT captured — `process.version`
+ * is unavailable in browsers, and surfacing it would require user bundler
+ * config (Vite `define`, Next.js `env`), which breaks the zero-config contract.
+ */
+interface FrameworkInfo {
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    frameworkVersion?: string;
+}
+/**
+ * Detect the web framework hosting this page and, when possible, its version.
+ *
+ * - Next.js: presence detected via `window.__NEXT_DATA__` (App Router + Pages
+ *   Router both set it) or the `<script id="__NEXT_DATA__">` element.
+ * - Otherwise: reports `plain-react` (covers Vite, CRA, Remix, and anything else
+ *   not positively identified as Next.js).
+ *
+ * Returns `{}` in non-DOM contexts (SSR on Node, first render of a Client
+ * Component). `FloTraceProvider` only creates the WebSocket singleton on the
+ * client, so the empty-object branch is harmless — detection re-runs after
+ * hydration with a DOM available.
+ *
+ * **About `frameworkVersion`**: in a Next.js *client* bundle, `globalThis.require`
+ * is normally not defined — so the version probe below usually no-ops and we
+ * report `frameworkName: 'next'` with `frameworkVersion: undefined`. This is
+ * by design: version detection is best-effort, the name alone is enough for
+ * admin-side categorization, and the string-concat require trick exists
+ * primarily to keep non-Next bundlers from failing the build on a static
+ * `require('next/package.json')` they can't resolve. Framework *detection*
+ * works reliably via `__NEXT_DATA__` regardless.
+ */
+declare function detectWebFramework(): FrameworkInfo;
+
 /**
  * RSC payload fetch interceptor for Next.js App Router.
  * Patches globalThis.fetch to detect Next.js data / RSC fetch requests,
@@ -1462,4 +1695,4 @@ declare function installRscPayloadInterceptor(client: FloTraceWebSocketClient):
 /** Remove the RSC payload interceptor and restore original fetch */
 declare function uninstallRscPayloadInterceptor(): void;
 
-export { DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type EffectInfo, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type HookInfo, type HookType, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RuntimeTreeDiffMessage, type SerializedValue, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TrackingOptions, type ZustandStoreApi, buildAncestorChain, clearFetchOriginTags, detectServerComponent, disposeWebSocketClient, findFetchOrigin, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getTimeline, getWebSocketClient, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isReduxStore, isTanStackQueryClient, maybeEmitNextjsContext, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, serializeProps, serializeValue, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };
+export { DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type EffectInfo, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type FrameworkInfo, type HookInfo, type HookType, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RuntimeTreeDiffMessage, type RuntimeValueTraceMessage, type SerializedValue, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TraceConfidence, type TraceStep, type TrackingOptions, type ValueTrace, type ValueTraceInput, type ZustandStoreApi, buildAncestorChain, clearFetchOriginTags, detectServerComponent, detectWebFramework, disposeWebSocketClient, findFetchOrigin, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getReduxSnapshot, getTanstackSnapshot, getTimeline, getWebSocketClient, getZustandSnapshot, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isReduxStore, isTanStackQueryClient, maybeEmitNextjsContext, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, resolveValueTrace, serializeProps, serializeValue, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };

package/dist/index.d.ts

@@ -26,7 +26,7 @@ type SerializedValue = null | boolean | number | string | SerializedValue[] | {
 /**
  * Messages sent from runtime to extension
  */
-type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimePongMessage;
+type RuntimeMessage = RuntimeReadyMessage | RuntimeRenderMessage | RuntimePropsUpdateMessage | RuntimeNodePropsMessage | RuntimeZustandUpdateMessage | RuntimeReduxUpdateMessage | RuntimeRouterUpdateMessage | RuntimeContextUpdateMessage | RuntimeDisconnectMessage | RuntimeTreeSnapshotMessage | RuntimeTreeDiffMessage | RuntimeNodeHooksMessage | RuntimeNodeEffectsMessage | RuntimeDetailedRenderReasonMessage | RuntimeTimelineEventMessage | RuntimeTanStackQueryUpdateMessage | RuntimeRenderTriggerMessage | RuntimeRenderCascadeMessage | RuntimePropDrillingMessage | RuntimeActionStateMessage | RuntimeOptimisticDiffMessage | RuntimeNextjsContextMessage | RuntimeRscPayloadMessage | RuntimeHydrationEventMessage | RuntimeNetworkRequestMessage | RuntimeLocalStateCorrelationMessage | RuntimeValueTraceMessage | RuntimePongMessage;
 interface RuntimeReadyMessage {
     type: 'runtime:ready';
     appName?: string;
@@ -39,6 +39,15 @@ interface RuntimeReadyMessage {
     appId?: string;
     /** App version — shown in the desktop connection panel for diagnostic purposes. */
     appVersion?: string;
+    /** Auto-detected framework family. Adapters populate this from runtime probes
+     *  (DOM signals on web, optional-require on native). */
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    /** Framework version when the adapter can resolve it (e.g. Next.js via
+     *  `require('next/package.json').version`). Missing when unavailable. */
+    frameworkVersion?: string;
+    /** React Native version from `Platform.constants.reactNativeVersion`, formatted
+     *  as "major.minor.patch". Native-only; web adapter leaves this undefined. */
+    reactNativeVersion?: string;
 }
 interface RuntimeRenderMessage {
     type: 'runtime:render';
@@ -610,6 +619,103 @@ interface RuntimeLocalStateCorrelationMessage {
     hookIndex: number;
     timestamp: number;
 }
+/**
+ * Confidence of a single trace step boundary.
+ * - `exact`: reference identity (`===`) preserved across the step.
+ * - `fingerprint-match`: only structural match via valueFingerprint(). Primitive
+ *   collisions are possible here (e.g., `count: 5` at multiple call sites).
+ */
+type TraceConfidence = 'exact' | 'fingerprint-match';
+/**
+ * A single step in a value-origin chain.
+ * Chain ordering: consumer first, origin last.
+ */
+type TraceStep = {
+    kind: 'prop';
+    nodeId: string;
+    componentName: string;
+    /** Dot-path into the component's props (e.g., ['user', 'profile', 'avatarUrl']). */
+    propPath: string[];
+    /** If this step came via a rename edge in the drilling graph. */
+    renamedFrom?: string;
+    confidence: TraceConfidence;
+} | {
+    kind: 'hook-state';
+    nodeId: string;
+    componentName: string;
+    hookIndex: number;
+    hookType: HookType;
+    /** Sub-path into the hook's current value, when the traced leaf is nested. */
+    subPath?: string[];
+    confidence: TraceConfidence;
+} | {
+    kind: 'store';
+    source: 'zustand' | 'redux' | 'tanstack-query';
+    storeName: string;
+    /** Key path into the store state where the matching value lives. */
+    keyPath: string[];
+    confidence: TraceConfidence;
+} | {
+    kind: 'api';
+    requestId: string;
+    method: string;
+    /** URL path only — query params stripped for privacy. */
+    urlPath: string;
+    status?: number;
+    /** Age of the fetch at trace resolution time. */
+    ageMs: number;
+    /** True when the 3s FETCH_ORIGIN_TTL_MS window has lapsed. */
+    expired?: boolean;
+} | {
+    kind: 'context';
+    contextName: string;
+    providerNodeId?: string;
+    confidence: TraceConfidence;
+} | {
+    /** Value is the cached result of a useMemo/useCallback on the same fiber.
+     *  `depCount` tells the UI how many upstream inputs the memo depends on
+     *  (one of which the user may want to click-trace next). */
+    kind: 'derived';
+    nodeId: string;
+    componentName: string;
+    hookIndex: number;
+    hookType: 'useMemo' | 'useCallback';
+    depCount: number;
+    confidence: TraceConfidence;
+};
+/**
+ * Result of a single value-trace request.
+ */
+interface ValueTrace {
+    /** Round-trip ID — mirrors the requestId from ext:traceValue. */
+    requestId: string;
+    rootNodeId: string;
+    /** Dot-path from the component when tracing a prop (e.g., ['user','profile','avatarUrl']). */
+    rootPropPath?: string[];
+    /** When tracing a hook value, addresses hook index + optional sub-path inside its value. */
+    rootHookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
+    /** Ordered steps — index 0 is the consumer, last index is the origin. */
+    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';
+}
+interface RuntimeValueTraceMessage {
+    type: 'runtime:valueTrace';
+    trace: ValueTrace;
+    timestamp: number;
+}
 /**
  * Messages received from extension
  */
@@ -664,6 +770,23 @@ type ExtensionToRuntimeMessage = {
     type: 'ext:startTanstackTracking';
 } | {
     type: 'ext:stopTanstackTracking';
+}
+/**
+ * Value Lineage — resolve the origin of a specific prop or hook value.
+ * Either `propPath` or `hookPath` must be set (exactly one).
+ */
+ | {
+    type: 'ext:traceValue';
+    /** Round-trip ID — echoed back in runtime:valueTrace. */
+    requestId: string;
+    nodeId: string;
+    /** When tracing a prop: dot-path like ['user','profile','avatarUrl']. Index 0 is the top-level prop key. */
+    propPath?: string[];
+    /** When tracing a hook value: hook index + optional nested sub-path inside its value. */
+    hookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
 };
 interface TrackingOptions {
     trackAllRenders?: boolean;
@@ -736,16 +859,54 @@ interface FloTraceConfig {
      *  be hidden by strict mode (e.g. monorepo packages resolved into
      *  `node_modules/@workspace/ui`). Only consulted when `userOnlyStrict` is on. */
     userAllowPatterns?: RegExp[];
+    /** Auto-detected framework family. Adapters set this via platform-specific probes
+     *  (DOM signals on web; optional-require on native). Not a user-facing knob. */
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    /** Framework version when the adapter can resolve it. Not a user-facing knob. */
+    frameworkVersion?: string;
+    /** React Native version from `Platform.constants.reactNativeVersion`, formatted
+     *  "major.minor.patch". Native adapter only. */
+    reactNativeVersion?: 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';
+type OptionalConfigKeys = 'getAppUrl' | 'platform' | 'appId' | 'appVersion' | 'host' | 'authToken' | 'userOnlyStrict' | 'userAllowPatterns' | 'frameworkName' | 'frameworkVersion' | 'reactNativeVersion';
 type ResolvedFloTraceConfig = Required<Omit<FloTraceConfig, OptionalConfigKeys>> & Pick<FloTraceConfig, OptionalConfigKeys>;
 /**
  * Default configuration
  */
 declare const DEFAULT_CONFIG: ResolvedFloTraceConfig;
 
+/**
+ * Value Lineage — origin tracing resolver.
+ *
+ * Given a component's prop-path or hook-path, walk upward through three layers
+ * to find where the value originated:
+ *
+ *   1. Prop chain     — walk fiber.return upward, match fingerprint at each level
+ *   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.
+ * 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.
+ */
+
+interface ValueTraceInput {
+    nodeId: string;
+    propPath?: string[];
+    hookPath?: {
+        hookIndex: number;
+        subPath?: string[];
+    };
+}
+/**
+ * Resolve the origin chain for a specific prop or hook value on a component.
+ * Returns `{requestId}`-less trace — caller adds the round-trip id.
+ */
+declare function resolveValueTrace(input: ValueTraceInput): Omit<ValueTrace, 'requestId'>;
+
 /**
  * Fiber Tree Walker for @flotrace/runtime
  *
@@ -1157,7 +1318,13 @@ declare class FloTraceWebSocketClient {
      */
     get connected(): boolean;
     /**
-     * Get React version if available
+     * Get React version if available.
+     *
+     * Historical note: an earlier implementation read `globalThis.React?.version` —
+     * but React is an ES-module import in modern bundles (Vite/webpack/Next.js) and
+     * is never placed on `globalThis`, so the probe returned undefined for every
+     * typical bundled app. Reading `React.version` via a direct import is
+     * authoritative across web (both CJS and ESM bundles), React Native, and SSR.
      */
     private getReactVersion;
 }
@@ -1200,6 +1367,16 @@ declare function installZustandTracker(stores: Record<string, ZustandStoreApi>,
  * Uninstall Zustand store tracking, unsubscribing from all stores.
  */
 declare function uninstallZustandTracker(): void;
+/**
+ * Snapshot of every tracked Zustand store's current **raw** state (not
+ * serialized). Used by the Value Lineage resolver to match component values
+ * against store keys via reference identity + structural fingerprint, and to
+ * pass raw object references into `findFetchOrigin()` for API correlation.
+ *
+ * Returns a fresh map on each call — does not cache. Cheap because `.getState()`
+ * is O(1) on Zustand.
+ */
+declare function getZustandSnapshot(): Map<string, Record<string, unknown>>;
 
 /**
  * Redux Store Tracker for @flotrace/runtime
@@ -1235,6 +1412,11 @@ declare function installReduxTracker(store: ReduxStoreApi, client: FloTraceWebSo
  * Uninstall Redux store tracking.
  */
 declare function uninstallReduxTracker(): void;
+/**
+ * Current raw Redux state, or null when the tracker isn't installed. Used by
+ * the Value Lineage resolver.
+ */
+declare function getReduxSnapshot(): Record<string, unknown> | null;
 
 /**
  * TanStack Query Tracker for @flotrace/runtime
@@ -1333,6 +1515,18 @@ declare function installTanStackQueryTracker(queryClient: TanStackQueryClientApi
  * Uninstall TanStack Query tracking.
  */
 declare function uninstallTanStackQueryTracker(): void;
+/**
+ * Snapshot of every cached query's **raw** data (not serialized) keyed by
+ * queryHash. Used by the Value Lineage resolver to match component values
+ * against TanStack Query cache via reference identity + structural fingerprint,
+ * and to pass raw references into `findFetchOrigin()`.
+ *
+ * Returns an empty map when the tracker isn't installed.
+ */
+declare function getTanstackSnapshot(): Map<string, {
+    queryKey: unknown[];
+    data: unknown;
+}>;
 
 /**
  * Component Event Timeline for @flotrace/runtime
@@ -1445,6 +1639,45 @@ declare function detectServerComponent(fiber: Fiber): boolean;
 /** Reset detection state (useful for tests / hot-reload) */
 declare function resetNextjsDetection(): void;
 
+/**
+ * Framework + framework-version detection (web adapter).
+ *
+ * Detects whether the running page is Next.js vs plain React and attempts to
+ * resolve the Next.js version via the package's own `package.json`. All signals
+ * are probed at runtime; absence is non-fatal and simply returns `undefined`.
+ *
+ * Node version of the project is intentionally NOT captured — `process.version`
+ * is unavailable in browsers, and surfacing it would require user bundler
+ * config (Vite `define`, Next.js `env`), which breaks the zero-config contract.
+ */
+interface FrameworkInfo {
+    frameworkName?: 'next' | 'expo' | 'rn-cli' | 'plain-react';
+    frameworkVersion?: string;
+}
+/**
+ * Detect the web framework hosting this page and, when possible, its version.
+ *
+ * - Next.js: presence detected via `window.__NEXT_DATA__` (App Router + Pages
+ *   Router both set it) or the `<script id="__NEXT_DATA__">` element.
+ * - Otherwise: reports `plain-react` (covers Vite, CRA, Remix, and anything else
+ *   not positively identified as Next.js).
+ *
+ * Returns `{}` in non-DOM contexts (SSR on Node, first render of a Client
+ * Component). `FloTraceProvider` only creates the WebSocket singleton on the
+ * client, so the empty-object branch is harmless — detection re-runs after
+ * hydration with a DOM available.
+ *
+ * **About `frameworkVersion`**: in a Next.js *client* bundle, `globalThis.require`
+ * is normally not defined — so the version probe below usually no-ops and we
+ * report `frameworkName: 'next'` with `frameworkVersion: undefined`. This is
+ * by design: version detection is best-effort, the name alone is enough for
+ * admin-side categorization, and the string-concat require trick exists
+ * primarily to keep non-Next bundlers from failing the build on a static
+ * `require('next/package.json')` they can't resolve. Framework *detection*
+ * works reliably via `__NEXT_DATA__` regardless.
+ */
+declare function detectWebFramework(): FrameworkInfo;
+
 /**
  * RSC payload fetch interceptor for Next.js App Router.
  * Patches globalThis.fetch to detect Next.js data / RSC fetch requests,
@@ -1462,4 +1695,4 @@ declare function installRscPayloadInterceptor(client: FloTraceWebSocketClient):
 /** Remove the RSC payload interceptor and restore original fetch */
 declare function uninstallRscPayloadInterceptor(): void;
 
-export { DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type EffectInfo, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type HookInfo, type HookType, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RuntimeTreeDiffMessage, type SerializedValue, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TrackingOptions, type ZustandStoreApi, buildAncestorChain, clearFetchOriginTags, detectServerComponent, disposeWebSocketClient, findFetchOrigin, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getTimeline, getWebSocketClient, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isReduxStore, isTanStackQueryClient, maybeEmitNextjsContext, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, serializeProps, serializeValue, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };
+export { DEFAULT_CONFIG, type DetailedRenderReason, type DetailedRenderReasonType, type EffectInfo, type Fiber$1 as Fiber, type FiberEffect, type FiberHookState, type FiberTreeWalkerOptions, type FloTraceConfig, FloTraceWebSocketClient, type FrameworkInfo, type HookInfo, type HookType, type LiveTreeNode, type MutationCorrelation, type NetworkRequestEntry, type PropChange, type ReduxStoreApi, type ResolvedFloTraceConfig, type RuntimeTreeDiffMessage, type RuntimeValueTraceMessage, type SerializedValue, type TanStackMutationInfo, type TanStackQueryClientApi, type TanStackQueryEvent, type TanStackQueryInfo, type TimelineEvent, type TimelineEventType, type TraceConfidence, type TraceStep, type TrackingOptions, type ValueTrace, type ValueTraceInput, type ZustandStoreApi, buildAncestorChain, clearFetchOriginTags, detectServerComponent, detectWebFramework, disposeWebSocketClient, findFetchOrigin, getChangedKeys, getComponentNameFromFiber, getCurrentRenderingFiber, getDetailedRenderReason, getFiberRefMap, getNodeEffects, getNodeHooks, getNodeProps, getReduxSnapshot, getTanstackSnapshot, getTimeline, getWebSocketClient, getZustandSnapshot, hasActiveTags, inspectEffects, inspectHooks, installFiberTreeWalker, installReduxTracker, installRscPayloadInterceptor, installTanStackQueryTracker, installTimelineTracker, installZustandTracker, isReduxStore, isTanStackQueryClient, maybeEmitNextjsContext, recordTimelineEvent, requestFullSnapshot, requestTreeSnapshot, resetNextjsDetection, resolveValueTrace, serializeProps, serializeValue, tagFetchData, uninstallFiberTreeWalker, uninstallReduxTracker, uninstallRscPayloadInterceptor, uninstallTanStackQueryTracker, uninstallTimelineTracker, uninstallZustandTracker };