@flotrace/runtime-core 2.2.3 → 2.3.0

package/README.md

@@ -50,6 +50,100 @@ your React app  ←→  @flotrace/runtime[-native]  ←→  ws://localhost:3457
 | `serializer` | Safe JSON serialization (depth 5, circular-ref guard, truncation). |
 | `websocketClient` | Singleton WS client with exponential backoff reconnect, message batching, optional auth token. |
 
+## Optional: JSX runtime opt-in (source attribution upgrade)
+
+`runtime-core` ships two additional subpath entries — `./jsx-runtime` and `./jsx-dev-runtime` — that you can opt into via a one-line `tsconfig.json` change. Doing so lets FloTrace attribute every JSX call site to its exact `file:line:column` with 100% confidence, even on stacks where React no longer carries that signal (Next.js 15 + SWC, React 19 with `_debugSource` removed).
+
+**The opt-in is free, additive, and reverts cleanly** — your app continues to work in production unchanged, and the existing heuristic ladder still runs when the opt-in is off.
+
+### Setup
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@flotrace/runtime-core"
+  }
+}
+```
+
+Restart your dev server. That's it.
+
+### What you get
+
+- **Click any node in FloTrace → IDE jumps to the exact JSX line** (column included).
+- **Per-call-site render metrics** instead of per-component-type. `<Button/>` at `Header.tsx:23` and `<Button/>` at `Footer.tsx:7` are now separate rows in the Hot Call Sites tab — only the actually-hot one is flagged.
+- **Inline-literal detection** — the runtime sees props *before* React processes them and tags fresh-each-render `onClick={() => ...}`, `style={{}}`, `items={[...]}` at the call site that created them. This signal is impossible to recover after React commits.
+- **Conditional-render visibility** — a callsite nested in `{cond && <X/>}` gets a `~N%` chip showing how often it actually renders.
+- **Duplicate-key warnings** with exact source location instead of grep-the-codebase.
+- **Privacy-safe Copy-as-Prompt** — every component reference cites `(src/components/Header.tsx:42)`, project-relative, never `/Users/foo/...`.
+- **Watches, Resolution Tracker, Value Lineage, Cascade, Prop Drilling** all gain `(file:line)` annotations and HMR-stable call-site identity.
+
+### Bundler matrix
+
+| Bundler | Zero-config? | Notes |
+|---|---|---|
+| **Vite (+ SWC or Babel)** | ✅ | Honors `jsxImportSource` from tsconfig out of the box. |
+| **Next.js 15 (Webpack)** | ✅ | SWC reads tsconfig. |
+| **Next.js 15 (Turbopack)** | ✅ | Same. |
+| **Remix / Vinxi** | ✅ | Same. |
+| **Expo SDK 50+ (Metro + Babel)** | ✅ | Metro's Babel preset honors `jsxImportSource`. |
+| **Bun** | ✅ | Built-in JSX transformer reads tsconfig. |
+| **Create React App** | ⚠ Needs Babel snippet | CRA's locked Babel config doesn't honor `jsxImportSource` from tsconfig. Use CRACO (or `react-app-rewired`) to inject a Babel preset override. See snippet below. |
+
+For CRA via CRACO, add to `craco.config.js`:
+
+```js
+module.exports = {
+  babel: {
+    presets: [
+      ['@babel/preset-react', {
+        runtime: 'automatic',
+        importSource: '@flotrace/runtime-core',
+        development: true, // emits jsxDEV instead of jsx in dev builds
+      }],
+    ],
+  },
+};
+```
+
+### How to verify it's working
+
+1. **Run your app in dev mode**, open browser DevTools → Console.
+2. Paste: `globalThis[Symbol.for('flotrace.jsx-runtime-active')]` → should return `true`.
+3. **Open React DevTools → Components tab**, select any user component, then click the wrench icon to view its props in the Console. Run:
+   ```js
+   $r.memoizedProps[Symbol.for('flotrace.source')]
+   ```
+   You should see `{ fileName, lineNumber, columnNumber, callSiteId }`.
+
+If step 2 returns `undefined`, your bundler isn't picking up the tsconfig setting — see the bundler matrix above. The connection-status tooltip inside the FloTrace desktop app also shows **"JSX runtime: active ✓"** once the opt-in is wired up correctly.
+
+If step 2 returns `true` but step 3 returns `undefined` on a specific component, that fiber was created via a path that bypasses `jsxDEV` (e.g. `React.createElement` direct call inside a vendored dependency, or a server-rendered component hydrated client-side). User-authored Client Components in `.tsx` / `.jsx` files always pass through.
+
+### Performance budget
+
+| Cost | Target | Notes |
+|---|---|---|
+| Per-`jsxDEV` call overhead | **<10µs median** | Microbenchmark on V8. Path normalization + hash + inline detection + symbol-prop allocation. |
+| Per-commit cumulative overhead | **<55ms** | For a 5000-element user-component tree. Well below React's own commit cost. |
+| Symbol-prop memory | ~200 bytes per user-component fiber | ~1 MB for 5000 fibers. GC'd with the fiber on unmount. |
+| Ring buffer memory | 60 timestamps × callSiteId count | ~2.4 MB worst case for 5000 distinct callsites. Cleared on walker uninstall. |
+
+### Privacy
+
+The runtime captures **absolute paths** (needed so click-to-IDE can resolve files reliably across symlinks and workspaces). Absolute paths NEVER leave your machine via:
+
+- **WebSocket** → bound to `127.0.0.1` only; the desktop app is also local.
+- **Copy-as-Prompt** → the prompt builder calls `relativizePath(absPath, projectRoot)` before serialization. Output cites `src/Header.tsx:42`, never `/Users/foo/proj/src/Header.tsx:42`.
+
+The opt-in is **dev-only** by design. The production entry (`@flotrace/runtime-core/jsx-runtime`) is a pure passthrough to `react/jsx-runtime` — zero runtime overhead, no symbol injection, no metadata captured.
+
+### Reverting
+
+Delete the `jsxImportSource` line from `tsconfig.json` and restart your dev server. FloTrace falls back to its existing heuristic ladder (`_debugSource` → `_debugOwner` → `_debugStack`). No code changes needed in your app.
+
 ## Version compatibility
 
 `@flotrace/runtime-core@2.x` is the companion release for:

package/dist/chunk-QLOJU5F2.mjs

@@ -0,0 +1,181 @@
+// src/jsxRuntimeUtils.ts
+var FLOTRACE_SOURCE = /* @__PURE__ */ Symbol.for("flotrace.source");
+var JSX_RUNTIME_ACTIVE_KEY = /* @__PURE__ */ Symbol.for("flotrace.jsx-runtime-active");
+function normalizeJsxSourcePath(fileName) {
+  let p = fileName;
+  if (p.startsWith("file://")) p = p.slice("file://".length);
+  if (p.startsWith("webpack-internal:///./")) p = p.slice("webpack-internal:///./".length);
+  if (p.startsWith("[project]/")) p = p.slice("[project]/".length);
+  if (p.startsWith("./")) p = p.slice(2);
+  if (/^\/[a-zA-Z]:[\\/]/.test(p)) p = p.slice(1);
+  if (/^[a-zA-Z]:[\\/]/.test(p)) p = p[0].toLowerCase() + p.slice(1);
+  return p;
+}
+function computeCallSiteId(source) {
+  const normPath = normalizeJsxSourcePath(source.fileName);
+  const key = `${normPath}:${source.lineNumber}:${source.columnNumber}`;
+  let hash = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    hash ^= key.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function readJsxSourceFromFiber(fiber) {
+  const props = fiber.memoizedProps;
+  if (!props) return void 0;
+  const raw = props[FLOTRACE_SOURCE];
+  if (!raw || typeof raw !== "object") return void 0;
+  const obj = raw;
+  if (typeof obj.fileName !== "string" || typeof obj.lineNumber !== "number" || typeof obj.columnNumber !== "number" || typeof obj.callSiteId !== "string") {
+    return void 0;
+  }
+  return raw;
+}
+var callSiteRenders = /* @__PURE__ */ new Map();
+var RING_BUFFER_MAX = 60;
+function recordCallSiteRender(callSiteId, now = performance.now()) {
+  const arr = callSiteRenders.get(callSiteId);
+  if (arr === void 0) {
+    callSiteRenders.set(callSiteId, [now]);
+    return;
+  }
+  arr.push(now);
+  if (arr.length > RING_BUFFER_MAX) arr.shift();
+}
+function getCallSiteRenders(callSiteId) {
+  return callSiteRenders.get(callSiteId) ?? [];
+}
+function getCallSiteRenderRate(callSiteId, windowMs = 5e3, now = performance.now()) {
+  const arr = callSiteRenders.get(callSiteId);
+  if (!arr || arr.length === 0) return 0;
+  const cutoff = now - windowMs;
+  let count = 0;
+  for (let i = arr.length - 1; i >= 0; i--) {
+    if (arr[i] >= cutoff) count++;
+    else break;
+  }
+  return count / windowMs * 1e3;
+}
+function clearCallSiteRenders() {
+  callSiteRenders.clear();
+}
+function computeCallSiteMetricsPayload(windowMs = 5e3, now = performance.now()) {
+  let out = null;
+  const cutoff = now - windowMs;
+  for (const [callSiteId, arr] of callSiteRenders) {
+    if (arr.length === 0) continue;
+    let count = 0;
+    for (let i = arr.length - 1; i >= 0; i--) {
+      if (arr[i] >= cutoff) count++;
+      else break;
+    }
+    if (count > 0) {
+      (out ?? (out = {}))[callSiteId] = count / windowMs * 1e3;
+    }
+  }
+  return out;
+}
+var duplicateKeyEmitter = null;
+function setDuplicateKeyEmitter(emitter) {
+  duplicateKeyEmitter = emitter;
+}
+var currentKeyBatch = /* @__PURE__ */ new Map();
+var keyBatchFlushScheduled = false;
+function recordJsxKey(source, key) {
+  const keyType = typeof key;
+  if (keyType !== "string" && keyType !== "number" && keyType !== "boolean") return;
+  const keyStr = String(key);
+  const batchKey = `${source.callSiteId}|${keyStr}`;
+  const entry = currentKeyBatch.get(batchKey);
+  if (entry !== void 0) {
+    entry.count++;
+  } else {
+    currentKeyBatch.set(batchKey, { count: 1, source });
+  }
+  if (!keyBatchFlushScheduled) {
+    keyBatchFlushScheduled = true;
+    queueMicrotask(flushDuplicateKeys);
+  }
+}
+function flushDuplicateKeys() {
+  keyBatchFlushScheduled = false;
+  const emitter = duplicateKeyEmitter;
+  if (emitter === null) {
+    currentKeyBatch.clear();
+    return;
+  }
+  for (const [batchKey, { count, source }] of currentKeyBatch) {
+    if (count < 2) continue;
+    const sep = batchKey.indexOf("|");
+    const duplicateKey = batchKey.slice(sep + 1);
+    emitter({
+      callSiteId: source.callSiteId,
+      fileName: source.fileName,
+      lineNumber: source.lineNumber,
+      columnNumber: source.columnNumber,
+      duplicateKey,
+      occurrences: count
+    });
+  }
+  currentKeyBatch.clear();
+}
+function markJsxRuntimeActive() {
+  globalThis[JSX_RUNTIME_ACTIVE_KEY] = true;
+}
+function isJsxRuntimeActive() {
+  return globalThis[JSX_RUNTIME_ACTIVE_KEY] === true;
+}
+var KNOWN_REACT_PROPS = /* @__PURE__ */ new Set(["key", "ref", "children", "className"]);
+var REACT_ELEMENT_TYPEOF_LEGACY = /* @__PURE__ */ Symbol.for("react.element");
+var REACT_ELEMENT_TYPEOF_R19 = /* @__PURE__ */ Symbol.for("react.transitional.element");
+function isReactElement(v) {
+  const typeOf = v.$$typeof;
+  return typeOf === REACT_ELEMENT_TYPEOF_LEGACY || typeOf === REACT_ELEMENT_TYPEOF_R19;
+}
+function detectInlineLiterals(props) {
+  let out;
+  for (const k in props) {
+    if (KNOWN_REACT_PROPS.has(k)) continue;
+    const v = props[k];
+    if (typeof v === "function") {
+      if (!v.name) {
+        (out ?? (out = {}))[k] = "fn";
+      }
+    } else if (Array.isArray(v)) {
+      if (v.length > 0) {
+        (out ?? (out = {}))[k] = "arr";
+      }
+    } else if (v !== null && typeof v === "object" && // Skip elements processed by our own runtime (marker present).
+    !(FLOTRACE_SOURCE in v) && // Skip React elements processed by ANY runtime — `$$typeof` is set on
+    // every element regardless of which jsx-runtime created it, so this
+    // catches mixed-runtime codebases. Without this guard, an inline
+    // `<Outer child={<Inner/>} />` would false-positive on `child` when
+    // Inner went through a different jsxImportSource.
+    !isReactElement(v)) {
+      const proto = Object.getPrototypeOf(v);
+      if (proto === Object.prototype || proto === null) {
+        (out ?? (out = {}))[k] = "obj";
+      }
+    }
+  }
+  return out;
+}
+
+export {
+  FLOTRACE_SOURCE,
+  JSX_RUNTIME_ACTIVE_KEY,
+  normalizeJsxSourcePath,
+  computeCallSiteId,
+  readJsxSourceFromFiber,
+  recordCallSiteRender,
+  getCallSiteRenders,
+  getCallSiteRenderRate,
+  clearCallSiteRenders,
+  computeCallSiteMetricsPayload,
+  setDuplicateKeyEmitter,
+  recordJsxKey,
+  markJsxRuntimeActive,
+  isJsxRuntimeActive,
+  detectInlineLiterals
+};