@flotrace/runtime 2.0.2 → 2.2.2

package/README.md

@@ -1,24 +1,31 @@
 # @flotrace/runtime
 
-Runtime package for FloTrace — enables real-time React component tree visualization, render tracking, state management monitoring, and network health analysis in the FloTrace desktop app.
+**Stop guessing why your React app re-renders.**
 
-> **Using React Native?** Install [`@flotrace/runtime-native`](https://www.npmjs.com/package/@flotrace/runtime-native) instead. It's the dedicated adapter for iOS / Android — `@flotrace/runtime` patches `fetch`, `XMLHttpRequest`, `JSON.parse`, and `Response.prototype.json` in ways that crash the React Native JS bridge. See the [migration guide](../../docs/migration-runtime-native.md) if you're switching a shared codebase.
+FloTrace is a desktop app that shows you, live, what your React tree is doing — every render, every prop change, every state mutation, every cascade — without leaving your editor and without uploading your source code anywhere.
 
-## Installation
+This package is the runtime that wires your app into the desktop. Drop it in once and you get:
 
-```bash
-npm install -D @flotrace/runtime
-# or
-yarn add -D @flotrace/runtime
-# or
-pnpm add -D @flotrace/runtime
-```
+- **A live component tree graph** — not a flat fiber list. See parent/child structure as it changes in real time.
+- **Render reasons that actually answer "why?"** — props/state/context diffs, render frequency coloring, render-cascade tracing across files.
+- **All your state in one panel** — Zustand, Redux, TanStack Query, Context, Router. No four browser extensions, no console.log.
+- **Hooks + effects, classified and diffed** — 14 hook types, effect dep diffing, "did this effect re-run because X changed."
+- **Network → state correlation** — every fetch/XHR mapped to the store update it caused.
+- **Copy-as-Prompt** — turn any panel into an AI-ready prompt for Cursor/Claude/ChatGPT in one click.
+
+Source code never leaves your machine. The runtime sends only metadata over `ws://localhost:3457` to the desktop app.
 
-**Peer dependencies:** React >= 16.9.0 (requires `<Profiler>` API)
+> **Using React Native?** Install [`@flotrace/runtime-native`](https://www.npmjs.com/package/@flotrace/runtime-native) instead. This package patches `fetch`/`XMLHttpRequest` in ways that crash the RN bridge.
 
-## Quick Start
+[**Download the desktop app →**](https://flotrace.dev/download) · [Docs](https://flotrace.dev/docs) · [Compare to React DevTools](https://flotrace.dev/compare/react-devtools)
 
-Wrap your app with `<FloTraceProvider>`:
+---
+
+## 30-second setup
+
+```bash
+npm install -D @flotrace/runtime
+```
 
 ```tsx
 import { FloTraceProvider } from '@flotrace/runtime';
@@ -32,75 +39,29 @@ createRoot(document.getElementById('root')!).render(
 );
 ```
 
-Then launch the FloTrace desktop app — your component tree will appear automatically.
+Launch the FloTrace desktop app. Reload your dev server. Done — your tree appears.
 
-## Configuration
+**Peer dependencies:** React >= 16.9.0 (uses `<Profiler>` API). Auto-disables in production via `process.env.NODE_ENV`.
 
-All config options are optional. Pass them via the `config` prop:
+---
 
-```tsx
-<FloTraceProvider config={{ port: 3457, appName: 'My App' }}>
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `port` | `number` | `3457` | WebSocket server port |
-| `appName` | `string` | `'React App'` | App name displayed in FloTrace |
-| `enabled` | `boolean` | `true` in dev | Enable/disable tracking |
-| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
-| `reconnectInterval` | `number` | `2000` | Reconnect interval (ms) |
-| `trackAllRenders` | `boolean` | `true` | Track all component renders |
-| `includeProps` | `boolean` | `true` | Include props in render events |
-| `trackZustand` | `boolean` | `true` | Enable Zustand state tracking |
-| `trackRedux` | `boolean` | `true` | Enable Redux state tracking |
-| `trackRouter` | `boolean` | `true` | Enable URL navigation tracking |
-| `trackContext` | `boolean` | `true` | Enable React Context tracking |
-| `trackTanstackQuery` | `boolean` | `true` | Enable TanStack Query tracking |
-
-## Framework Setup
-
-### Vite + React
-
-```tsx
-// src/main.tsx
-import { FloTraceProvider } from '@flotrace/runtime';
-import { createRoot } from 'react-dom/client';
-import App from './App';
-
-createRoot(document.getElementById('root')!).render(
-  <FloTraceProvider config={{ appName: 'My Vite App' }}>
-    <App />
-  </FloTraceProvider>
-);
-```
+## Framework recipes
 
 ### Next.js (App Router)
 
 ```tsx
 // app/providers.tsx
 'use client';
-
 import { FloTraceProvider } from '@flotrace/runtime';
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <FloTraceProvider config={{ appName: 'My Next.js App' }}>
-      {children}
-    </FloTraceProvider>
-  );
+  return <FloTraceProvider config={{ appName: 'My Next.js App' }}>{children}</FloTraceProvider>;
 }
 
 // app/layout.tsx
 import { Providers } from './providers';
-
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html>
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
+  return <html><body><Providers>{children}</Providers></body></html>;
 }
 ```
 
@@ -120,272 +81,119 @@ export default function App({ Component, pageProps }: AppProps) {
 }
 ```
 
-### Create React App
-
-```tsx
-// src/index.tsx
-import { FloTraceProvider } from '@flotrace/runtime';
-import { createRoot } from 'react-dom/client';
-import App from './App';
+### Vite / Create React App
 
-createRoot(document.getElementById('root')!).render(
-  <FloTraceProvider config={{ appName: 'My CRA App' }}>
-    <App />
-  </FloTraceProvider>
-);
-```
+Same as the 30-second setup above — wrap `<App />` at the root.
 
-## State Management Integration
+---
 
-### Zustand
+## Wire up your state stores
 
-Pass Zustand stores via the `stores` prop. Keys become store names in FloTrace:
+State tracking is the killer feature. Pass your stores to the provider and they show up in the desktop's State panel with live diffs:
 
 ```tsx
 import { FloTraceProvider } from '@flotrace/runtime';
-import { useBearStore } from './store/bearStore';
-import { useUserStore } from './store/userStore';
+import { useBearStore } from './zustandStore';
+import { store as reduxStore } from './reduxStore';
+import { queryClient } from './queryClient';
 
 <FloTraceProvider
-  stores={{ bearStore: useBearStore, userStore: useUserStore }}
   config={{ appName: 'My App' }}
+  stores={{ bearStore: useBearStore }}     // Zustand — keys become store names
+  reduxStore={reduxStore}                   // Redux — pass your store directly
+  queryClient={queryClient}                 // TanStack Query — pass your client
 >
   <App />
 </FloTraceProvider>
 ```
 
-### Redux
-
-Pass your Redux store via the `reduxStore` prop:
-
-```tsx
-import { FloTraceProvider } from '@flotrace/runtime';
-import { store } from './store';
+Router tracking is automatic — it patches the History API and works with React Router, TanStack Router, Next.js, etc.
 
-<FloTraceProvider
-  reduxStore={store}
-  config={{ appName: 'My App' }}
->
-  <App />
-</FloTraceProvider>
-```
+---
 
-### TanStack Query
+## Configuration
 
-Pass your TanStack Query client via the `queryClient` prop:
+All options optional. Sensible defaults for development.
 
-```tsx
-import { FloTraceProvider } from '@flotrace/runtime';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appName` | `string` | `'React App'` | Shown in the FloTrace connection pill |
+| `port` | `number` | `3457` | WebSocket server port |
+| `enabled` | `boolean` | dev only | `false` to hard-disable |
+| `autoReconnect` | `boolean` | `true` | Reconnect on disconnect |
+| `reconnectInterval` | `number` | `2000` | Base reconnect delay (ms, exponential backoff) |
+| `trackAllRenders` | `boolean` | `true` | Track every commit via `<Profiler>` |
+| `includeProps` | `boolean` | `true` | Include prop values in render events |
+| `trackZustand` / `trackRedux` / `trackRouter` / `trackContext` / `trackTanstackQuery` | `boolean` | `true` | Per-tracker toggles |
 
-const queryClient = new QueryClient();
+---
 
-<QueryClientProvider client={queryClient}>
-  <FloTraceProvider
-    queryClient={queryClient}
-    config={{ appName: 'My App' }}
-  >
-    <App />
-  </FloTraceProvider>
-</QueryClientProvider>
-```
+## Production safety
 
-### Combined (Zustand + Redux + TanStack Query + Router)
+FloTrace is **disabled in production** by default (`enabled` defaults to `process.env.NODE_ENV === 'development'`). For belt-and-braces tree-shaking, dynamic-import in dev only:
 
 ```tsx
-import { FloTraceProvider } from '@flotrace/runtime';
-import { store } from './reduxStore';
-import { useBearStore } from './zustandStore';
-import { queryClient } from './queryClient';
-
-<FloTraceProvider
-  config={{ appName: 'My App' }}
-  stores={{ bearStore: useBearStore }}
-  reduxStore={store}
-  queryClient={queryClient}
->
-  <App />
-</FloTraceProvider>
+const FloTraceProvider = process.env.NODE_ENV === 'development'
+  ? (await import('@flotrace/runtime')).FloTraceProvider
+  : ({ children }: { children: React.ReactNode }) => <>{children}</>;
 ```
 
-Router tracking is automatic — no configuration needed. It works with any SPA router (React Router, TanStack Router, Next.js, etc.) by patching the browser's History API.
+---
 
-## Advanced Usage
+## Targeted profiling
 
-### `withFloTrace()` — HOC for targeted profiling
-
-Wrap specific components to track their renders and props individually:
+For one-off component tracking without the full provider:
 
 ```tsx
-import { withFloTrace } from '@flotrace/runtime';
-
-const ProfiledComponent = withFloTrace(MyComponent, 'MyComponent');
-```
-
-### `useTrackProps()` — Track prop changes
+import { withFloTrace, useTrackProps } from '@flotrace/runtime';
 
-Call at the top of a component to track its prop changes:
-
-```tsx
-import { useTrackProps } from '@flotrace/runtime';
+const Profiled = withFloTrace(MyComponent, 'MyComponent');
 
 function MyComponent(props: MyProps) {
   useTrackProps('MyComponent', props);
-  // ... rest of component
-}
-```
-
-### `useFloTrace()` — Access runtime context
-
-```tsx
-import { useFloTrace } from '@flotrace/runtime';
-
-function DebugInfo() {
-  const floTrace = useFloTrace();
-  return <div>Connected: {floTrace?.connected ? 'Yes' : 'No'}</div>;
+  // ...
 }
 ```
 
-## Production Safety
+---
 
-By default, FloTrace is **disabled in production** (`enabled` defaults to `process.env.NODE_ENV === 'development'`).
+## Privacy & security
 
-For explicit control, use a conditional import pattern:
+- Source code never leaves your machine. The runtime sends only metadata (component names, prop types, render counts) over `ws://localhost:3457`.
+- Desktop app binds to `127.0.0.1` only. LAN connections (physical devices) require an opt-in auth token.
+- The desktop is closed-source commercial; this runtime package is **MIT-licensed** and open at [github.com/flotrace](https://github.com/flotrace).
 
-```tsx
-// src/main.tsx
-const FloTraceProvider = process.env.NODE_ENV === 'development'
-  ? (await import('@flotrace/runtime')).FloTraceProvider
-  : ({ children }: { children: React.ReactNode }) => <>{children}</>;
-```
+---
 
 ## Troubleshooting
 
-### "Not connected"
-
-1. Ensure the FloTrace desktop app is running
-2. Check the port matches (default: 3457)
-3. Verify `config.enabled` is `true`
-4. Check browser console for `[FloTrace]` logs
-
-### Zustand stores not appearing
-
-- Stores must be passed explicitly via the `stores` prop
-- Each value must be a Zustand hook (function with `.getState()` and `.subscribe()` methods)
-- Check console for `[FloTrace] Skipping "..." — not a valid Zustand store` warnings
-
-### Component tree is missing or incomplete
+**"Not connected"** — Is the desktop app running? Is `enabled: true`? Check browser console for `[FloTrace]` logs.
 
-- The fiber tree walker needs React DevTools hook or DOM-based fiber access
-- React DevTools browser extension improves reliability
-- Tree depth is capped at 100 levels, children at 300 per node
-- Reload the page if the tree appears empty
+**Zustand stores missing** — Stores must be passed via the `stores` prop, and each value must be a Zustand hook (has `.getState()` and `.subscribe()`).
 
-### WebSocket keeps reconnecting
+**Tree empty or partial** — Reload the page. The walker uses React DevTools hook or DOM-based fiber access; depth is capped at 100, children at 300/node.
 
-- FloTrace uses exponential backoff (2s → 4s → 8s... up to 30s) with a 10-attempt budget
-- After 10 failed attempts, reload the page or restart FloTrace to retry
-- Check that no firewall or proxy is blocking `ws://localhost:3457`
+**WebSocket reconnecting** — Exponential backoff (2s → 30s, 10 attempts). After that, reload the page or restart the desktop.
 
-## API Reference
+---
 
-### Components
+## API reference
 
-| Export | Description |
-|--------|-------------|
-| `FloTraceProvider` | Main provider — wraps your app, manages WebSocket connection |
-| `withFloTrace(Component, name?)` | HOC for targeted component profiling |
-
-### Hooks
-
-| Export | Description |
-|--------|-------------|
-| `useFloTrace()` | Access connection state and config |
-| `useTrackProps(name, props)` | Track prop changes for a component |
-
-### Types
-
-| Export | Description |
-|--------|-------------|
-| `FloTraceConfig` | Configuration options interface |
-| `FloTraceProviderProps` | Props for FloTraceProvider |
-| `SerializedValue` | Serialized value type for safe WebSocket transmission |
-| `LiveTreeNode` | Node in the live component tree |
-| `ReduxStoreApi` | Minimal Redux store interface |
-| `TanStackQueryClientApi` | Duck-typed TanStack Query client interface |
-| `TrackingOptions` | Tracking options from extension |
-| `DEFAULT_CONFIG` | Default configuration values |
-| `DetailedRenderReason` | Detailed render reason with prop/state/context diffs |
-| `HookType`, `HookInfo` | Hook type classification and inspection data |
-| `EffectInfo` | Effect info with willRun and dep diffs |
-| `TimelineEvent`, `TimelineEventType` | Component lifecycle events |
-| `TanStackQueryInfo`, `TanStackMutationInfo` | Query and mutation tracking data |
-| `NetworkRequestEntry` | Network request metadata (method, status, timing, correlation) |
-| `Fiber`, `FiberHookState`, `FiberEffect` | React fiber type definitions |
-
-### Advanced Exports
+See [flotrace.dev/docs/runtime](https://flotrace.dev/docs/runtime) for the full export surface (40+ hooks, trackers, and types). Quick index:
 
 | Export | Description |
-|--------|-------------|
-| `getWebSocketClient(config?)` | Get singleton WebSocket client |
-| `disposeWebSocketClient()` | Dispose the WebSocket client |
-| `FloTraceWebSocketClient` | WebSocket client class |
-| `installFiberTreeWalker()` | Manually install fiber tree walker |
-| `uninstallFiberTreeWalker()` | Uninstall fiber tree walker |
-| `requestTreeSnapshot()` | Request a tree snapshot (DOM fallback) |
-| `getNodeHooks(nodeId)` | Inspect hooks for a specific component |
-| `getNodeEffects(nodeId)` | Inspect effects for a specific component |
-| `getDetailedRenderReason(nodeId)` | Get detailed render reason (prop/state/context diffs) |
-| `getFiberRefMap()` | Get map of all tracked fiber refs |
-| `inspectHooks(fiber)` | Classify and inspect hooks from fiber |
-| `inspectEffects(fiber)` | Inspect effects from fiber updateQueue |
-| `installZustandTracker()` / `uninstall...` | Zustand per-store subscription tracking |
-| `installReduxTracker()` / `uninstall...` | Redux store subscription tracking |
-| `installRouterTracker()` / `uninstall...` | History API patching for route tracking |
-| `installTanStackQueryTracker()` / `uninstall...` | TanStack Query cache subscriber (duck-typed) |
-| `installNetworkTracker()` / `uninstall...` | Fetch/XHR patching for network monitoring |
-| `prewarmNetworkTracker()` | Pre-install patches to capture page-load requests |
-| `installTimelineTracker()` / `uninstall...` | Component lifecycle event tracking |
-| `recordTimelineEvent()` | Manually record a timeline event |
-| `getTimeline(componentId)` | Get timeline events for a component |
-| `serializeValue(value)` | Serialize a value for WebSocket |
-| `serializeProps(props)` | Serialize props object |
-| `isReduxStore(obj)` | Type guard for Redux store |
-| `isTanStackQueryClient(obj)` | Type guard for TanStack Query client |
-
-## Publishing
-
-### Prerequisites
-
-```bash
-npm login
-```
-
-### Release Scripts
-
-| Script | Version Change | When to Use |
-|--------|---------------|-------------|
-| `npm run release:patch` | `0.1.0` → `0.1.1` | Bug fixes, small tweaks |
-| `npm run release:minor` | `0.1.0` → `0.2.0` | New features, non-breaking changes |
-| `npm run release:major` | `0.1.0` → `1.0.0` | Breaking API changes |
-
-Each release script automatically:
-1. Bumps the version in `package.json`
-2. Creates a git commit and tag (e.g. `v0.1.1`)
-3. Cleans `dist/`, rebuilds, and typechecks (`prepublishOnly`)
-4. Publishes to npm under `@flotrace` scope
-
-### From the monorepo root
+|---|---|
+| `FloTraceProvider` | Main provider component |
+| `withFloTrace(Component, name?)` | HOC for targeted profiling |
+| `useFloTrace()` | Connection state + config |
+| `useTrackProps(name, props)` | Track prop changes |
+| `installXxxTracker()` / `uninstallXxxTracker()` | Manual tracker control (Zustand, Redux, Router, TanStack Query, Network, Timeline) |
+| `getNodeHooks(nodeId)` / `getNodeEffects(nodeId)` / `getDetailedRenderReason(nodeId)` | Inspector accessors |
 
-| Script | Action |
-|--------|--------|
-| `npm run runtime:release:patch` | Bump patch + build + publish (e.g. `0.1.0` → `0.1.1`) |
-| `npm run runtime:release:minor` | Bump minor + build + publish (e.g. `0.1.0` → `0.2.0`) |
-| `npm run runtime:release:major` | Bump major + build + publish (e.g. `0.1.0` → `1.0.0`) |
-| `npm run runtime:publish` | Publish current version as-is (no version bump) |
+Type exports: `FloTraceConfig`, `LiveTreeNode`, `SerializedValue`, `HookInfo`, `EffectInfo`, `TimelineEvent`, `NetworkRequestEntry`, `Fiber`, etc.
 
-> **Note:** `runtime:publish` publishes whatever version is currently in `package.json`. Use this for the first publish or to re-publish a fixed build without bumping the version. The `release:*` scripts auto-increment the version, create a git commit + tag, then publish.
+---
 
 ## License
 
-MIT
+MIT. Issues and PRs welcome at [github.com/flotrace](https://github.com/flotrace).

package/dist/index.js

@@ -47,6 +47,69 @@ __reExport(index_exports, require("@flotrace/runtime-core"), module.exports);
 var import_react = __toESM(require("react"));
 var import_runtime_core3 = require("@flotrace/runtime-core");
 
+// package.json
+var package_default = {
+  name: "@flotrace/runtime",
+  version: "2.2.2",
+  description: "Runtime package for FloTrace - enables real-time render tracking in your React app",
+  main: "./dist/index.js",
+  module: "./dist/index.mjs",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    typecheck: "tsc --noEmit",
+    clean: "rm -rf dist",
+    prepublishOnly: "npm run -w @flotrace/runtime-core build && npm run clean && npm run build && npm run typecheck",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  dependencies: {
+    "@flotrace/runtime-core": "2.2.2"
+  },
+  peerDependencies: {
+    react: ">=16.9.0",
+    "@types/react": ">=16.9.0"
+  },
+  peerDependenciesMeta: {
+    "@types/react": {
+      optional: true
+    }
+  },
+  devDependencies: {
+    tsup: "^8.0.0",
+    typescript: "^5.3.0"
+  },
+  keywords: [
+    "react",
+    "devtools",
+    "profiler",
+    "render",
+    "performance",
+    "flotrace"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/flotrace/flotrace.git",
+    directory: "packages/runtime"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
 // src/routerTracker.ts
 var isInstalled = false;
 var debounceTimer = null;
@@ -571,6 +634,7 @@ function flushBuffer() {
 
 // src/FloTraceProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
+var RUNTIME_VERSION = package_default.version;
 var pendingCleanupTimer = null;
 function safeTrackerOp(name, op) {
   try {
@@ -616,7 +680,8 @@ function FloTraceProvider({ children, config = {}, stores, reduxStore, queryClie
     appName: config.appName ?? deriveWebAppName(),
     appId: config.appId ?? deriveWebAppId(),
     frameworkName: config.frameworkName ?? framework.frameworkName,
-    frameworkVersion: config.frameworkVersion ?? framework.frameworkVersion
+    frameworkVersion: config.frameworkVersion ?? framework.frameworkVersion,
+    runtimeVersion: config.runtimeVersion ?? RUNTIME_VERSION
   };
   const [connected, setConnected] = import_react.default.useState(false);
   const trackingOptionsRef = (0, import_react.useRef)({});
@@ -754,6 +819,37 @@ function FloTraceProvider({ children, config = {}, stores, reduxStore, queryClie
             }
             break;
           }
+          // Value Lineage — resolve the origin chain for a prop or hook value.
+          case "ext:traceValue": {
+            try {
+              const trace = (0, import_runtime_core3.resolveValueTrace)({
+                nodeId: message.nodeId,
+                propPath: message.propPath,
+                hookPath: message.hookPath
+              });
+              client3.sendImmediate({
+                type: "runtime:valueTrace",
+                trace: { requestId: message.requestId, ...trace },
+                timestamp: Date.now()
+              });
+            } catch (error) {
+              console.error("[FloTrace] resolveValueTrace threw:", error);
+              client3.sendImmediate({
+                type: "runtime:valueTrace",
+                trace: {
+                  requestId: message.requestId,
+                  rootNodeId: message.nodeId,
+                  rootPropPath: message.propPath,
+                  rootHookPath: message.hookPath,
+                  steps: [],
+                  resolvedAtMs: Date.now(),
+                  error: "value-not-found"
+                },
+                timestamp: Date.now()
+              });
+            }
+            break;
+          }
           case "ext:startNetworkCapture":
             safeTrackerOp("Network capture start", () => installNetworkTracker(client3));
             break;

package/dist/index.mjs

@@ -26,9 +26,73 @@ import {
   installTimelineTracker,
   uninstallTimelineTracker,
   getTimeline,
-  detectWebFramework
+  detectWebFramework,
+  resolveValueTrace
 } from "@flotrace/runtime-core";
 
+// package.json
+var package_default = {
+  name: "@flotrace/runtime",
+  version: "2.2.2",
+  description: "Runtime package for FloTrace - enables real-time render tracking in your React app",
+  main: "./dist/index.js",
+  module: "./dist/index.mjs",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    typecheck: "tsc --noEmit",
+    clean: "rm -rf dist",
+    prepublishOnly: "npm run -w @flotrace/runtime-core build && npm run clean && npm run build && npm run typecheck",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  dependencies: {
+    "@flotrace/runtime-core": "2.2.2"
+  },
+  peerDependencies: {
+    react: ">=16.9.0",
+    "@types/react": ">=16.9.0"
+  },
+  peerDependenciesMeta: {
+    "@types/react": {
+      optional: true
+    }
+  },
+  devDependencies: {
+    tsup: "^8.0.0",
+    typescript: "^5.3.0"
+  },
+  keywords: [
+    "react",
+    "devtools",
+    "profiler",
+    "render",
+    "performance",
+    "flotrace"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/flotrace/flotrace.git",
+    directory: "packages/runtime"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
 // src/routerTracker.ts
 var isInstalled = false;
 var debounceTimer = null;
@@ -559,6 +623,7 @@ function flushBuffer() {
 
 // src/FloTraceProvider.tsx
 import { Fragment, jsx } from "react/jsx-runtime";
+var RUNTIME_VERSION = package_default.version;
 var pendingCleanupTimer = null;
 function safeTrackerOp(name, op) {
   try {
@@ -604,7 +669,8 @@ function FloTraceProvider({ children, config = {}, stores, reduxStore, queryClie
     appName: config.appName ?? deriveWebAppName(),
     appId: config.appId ?? deriveWebAppId(),
     frameworkName: config.frameworkName ?? framework.frameworkName,
-    frameworkVersion: config.frameworkVersion ?? framework.frameworkVersion
+    frameworkVersion: config.frameworkVersion ?? framework.frameworkVersion,
+    runtimeVersion: config.runtimeVersion ?? RUNTIME_VERSION
   };
   const [connected, setConnected] = React.useState(false);
   const trackingOptionsRef = useRef({});
@@ -742,6 +808,37 @@ function FloTraceProvider({ children, config = {}, stores, reduxStore, queryClie
             }
             break;
           }
+          // Value Lineage — resolve the origin chain for a prop or hook value.
+          case "ext:traceValue": {
+            try {
+              const trace = resolveValueTrace({
+                nodeId: message.nodeId,
+                propPath: message.propPath,
+                hookPath: message.hookPath
+              });
+              client3.sendImmediate({
+                type: "runtime:valueTrace",
+                trace: { requestId: message.requestId, ...trace },
+                timestamp: Date.now()
+              });
+            } catch (error) {
+              console.error("[FloTrace] resolveValueTrace threw:", error);
+              client3.sendImmediate({
+                type: "runtime:valueTrace",
+                trace: {
+                  requestId: message.requestId,
+                  rootNodeId: message.nodeId,
+                  rootPropPath: message.propPath,
+                  rootHookPath: message.hookPath,
+                  steps: [],
+                  resolvedAtMs: Date.now(),
+                  error: "value-not-found"
+                },
+                timestamp: Date.now()
+              });
+            }
+            break;
+          }
           case "ext:startNetworkCapture":
             safeTrackerOp("Network capture start", () => installNetworkTracker(client3));
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flotrace/runtime",
-  "version": "2.0.2",
+  "version": "2.2.2",
   "description": "Runtime package for FloTrace - enables real-time render tracking in your React app",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -26,7 +26,7 @@
     "release:major": "npm version major && npm publish"
   },
   "dependencies": {
-    "@flotrace/runtime-core": "2.0.1"
+    "@flotrace/runtime-core": "2.2.2"
   },
   "peerDependencies": {
     "react": ">=16.9.0",