@react-perfscope/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ray
+
+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

@@ -0,0 +1,117 @@
+# @react-perfscope/react
+
+React 18+ adapter for `react-perfscope`. Installs a DevTools global hook to observe commits, walks fiber trees, and exposes a render collector that plugs into `@react-perfscope/core`.
+
+## Status
+
+Phase 3-4 stable. Render collector emits one `RenderSignal` per changed component per commit; `RenderSignal.duration` populated from `fiber.actualDuration` when React is built with Profiling.
+
+## Example
+
+```ts
+import { createRecorder } from '@react-perfscope/core'
+import { createRenderCollector } from '@react-perfscope/react'
+
+const recorder = createRecorder()
+recorder.use(createRenderCollector())
+
+recorder.start()
+// ... interact with the app ...
+const result = recorder.stop()
+
+console.log(result.signals.filter((s) => s.kind === 'render'))
+```
+
+## API
+
+- `createRenderCollector()` — Collector factory. Emits `RenderSignal` per non-host fiber on each React commit.
+- `resolveComponentFromElement(el)` — Given a DOM element, return the nearest React component name (or null if no fiber attached).
+- `installDevToolsHook(listener)` — Low-level DevTools hook installer. Returns an unsubscribe function. Chains with any pre-existing hook (e.g. real React DevTools).
+- `fiberComponentName(fiber)` — Resolve a fiber to its component name. Handles host tags, function/class components, `memo`, `forwardRef`.
+- `walkChangedFibers(root, visit, { stopAt })` — Depth-first traversal of a fiber subtree with an upper bound.
+
+## Hook load-order (IMPORTANT)
+
+`react-dom` reads `globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__` ONCE at module evaluation time. If the hook isn't there at that moment, `react-dom`'s internal `injectedHook` is set to `null` and never updated — our collector will then never receive commits.
+
+**Practical implication:** import `@react-perfscope/react` (or call `createRenderCollector()` / `installDevToolsHook()`) BEFORE you `import 'react-dom/client'` or before any module that does. The simplest pattern:
+
+```ts
+// At the very top of your entry file
+import { createRecorder } from '@react-perfscope/core'
+import { createRenderCollector } from '@react-perfscope/react'
+
+const recorder = createRecorder()
+recorder.use(createRenderCollector())
+
+// Now import React-DOM-touching code
+import './app'
+```
+
+If you're using the `react-perfscope` meta package (or one of the build plugins), this ordering is handled automatically.
+
+## Caveats
+
+- The render collector keeps its DevTools hook listener attached across deactivate cycles (emission is gated by an `active` flag). This mirrors the `web-vitals` collector's lifecycle.
+- `RenderSignal.duration` is `0` for fibers outside a Profiler-enabled root (React's default `createRoot` is Profiler-enabled in development).
+
+---
+
+<a id="한국어"></a>
+
+# 한국어
+
+`react-perfscope`용 React 18+ 어댑터. DevTools 글로벌 훅을 설치해 커밋을 감지하고, fiber 트리를 순회해서 `@react-perfscope/core`에 연결되는 render collector를 제공한다.
+
+## 상태
+
+Phase 3-4 안정화. render collector는 커밋마다 변경된 컴포넌트 하나당 `RenderSignal` 하나를 내보낸다. React가 Profiling 빌드일 경우 `RenderSignal.duration`은 `fiber.actualDuration`으로 채워진다.
+
+## 예제
+
+```ts
+import { createRecorder } from '@react-perfscope/core'
+import { createRenderCollector } from '@react-perfscope/react'
+
+const recorder = createRecorder()
+recorder.use(createRenderCollector())
+
+recorder.start()
+// ... 앱과 상호작용 ...
+const result = recorder.stop()
+
+console.log(result.signals.filter((s) => s.kind === 'render'))
+```
+
+## API
+
+- `createRenderCollector()` — Collector 팩토리. React 커밋마다 non-host fiber에 대해 `RenderSignal`을 내보낸다.
+- `resolveComponentFromElement(el)` — DOM 엘리먼트를 받아 가장 가까운 React 컴포넌트 이름을 반환한다 (fiber가 없으면 null).
+- `installDevToolsHook(listener)` — 저수준 DevTools 훅 설치 함수. unsubscribe 함수를 반환한다. 기존에 있던 훅(예: 실제 React DevTools)이 있으면 체이닝한다.
+- `fiberComponentName(fiber)` — fiber를 컴포넌트 이름으로 해석한다. host 태그, 함수/클래스 컴포넌트, `memo`, `forwardRef`를 모두 처리한다.
+- `walkChangedFibers(root, visit, { stopAt })` — 상한선을 두고 fiber 서브트리를 깊이 우선으로 순회한다.
+
+## 훅 로드 순서 (중요)
+
+`react-dom`은 모듈 평가 시점에 `globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`을 딱 한 번 읽는다. 그 시점에 훅이 없으면 `react-dom` 내부의 `injectedHook`이 `null`로 고정되어 이후에 업데이트되지 않는다 — 그러면 collector가 커밋을 영원히 못 받는다.
+
+**실용적인 의미:** `@react-perfscope/react`를 import하거나 `createRenderCollector()` / `installDevToolsHook()`를 호출하는 건 반드시 `import 'react-dom/client'`보다 먼저, 그리고 그걸 import하는 어떤 모듈보다도 먼저 와야 한다. 가장 간단한 패턴:
+
+```ts
+// entry 파일 맨 위에
+import { createRecorder } from '@react-perfscope/core'
+import { createRenderCollector } from '@react-perfscope/react'
+
+const recorder = createRecorder()
+recorder.use(createRenderCollector())
+
+// 이제 React-DOM을 건드리는 코드를 import
+import './app'
+```
+
+`react-perfscope` 메타 패키지(또는 빌드 플러그인 중 하나)를 쓰면 이 순서가 자동으로 처리된다.
+
+## 주의사항
+
+- render collector는 deactivate 사이클에도 DevTools 훅 리스너를 붙여둔다 (내보내기는 `active` 플래그로 제어된다). 이건 `web-vitals` collector의 생명주기와 같은 방식이다.
+- Profiler가 활성화된 root 바깥에 있는 fiber는 `RenderSignal.duration`이 `0`이다 (개발 모드의 `createRoot`는 기본적으로 Profiler가 켜져 있다).

package/dist/index.cjs

@@ -0,0 +1,297 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRenderCollector: () => createRenderCollector,
+  fiberComponentName: () => fiberComponentName,
+  installDevToolsHook: () => installDevToolsHook,
+  resolveComponentFromElement: () => resolveComponentFromElement,
+  uninstallDevToolsHook: () => uninstallDevToolsHook,
+  walkChangedFibers: () => walkChangedFibers
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/devtools-hook.ts
+var HOOK_KEY = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+var listeners = /* @__PURE__ */ new Set();
+var ourHook = null;
+var chainedOriginal = null;
+function ensureHookInstalled() {
+  const g = globalThis;
+  if (ourHook && g[HOOK_KEY] === ourHook) return;
+  const existing = g[HOOK_KEY];
+  chainedOriginal = existing && existing !== ourHook && typeof existing.onCommitFiberRoot === "function" ? existing.onCommitFiberRoot : null;
+  const hook = existing && existing !== ourHook ? existing : {};
+  if (!hook.supportsFiber) {
+    hook.supportsFiber = true;
+  }
+  if (typeof hook.inject !== "function") {
+    let _nextRendererId = 1;
+    hook.inject = () => _nextRendererId++;
+  }
+  if (!hook.renderers) {
+    ;
+    hook.renderers = /* @__PURE__ */ new Map();
+  }
+  if (typeof hook["on"] !== "function") {
+    ;
+    hook["on"] = () => {
+    };
+  }
+  if (typeof hook["off"] !== "function") {
+    ;
+    hook["off"] = () => {
+    };
+  }
+  if (typeof hook["emit"] !== "function") {
+    ;
+    hook["emit"] = () => {
+    };
+  }
+  if (typeof hook["sub"] !== "function") {
+    ;
+    hook["sub"] = () => () => {
+    };
+  }
+  if (typeof hook["checkDCE"] !== "function") {
+    ;
+    hook["checkDCE"] = () => {
+    };
+  }
+  if (typeof hook["onCommitFiberUnmount"] !== "function") {
+    ;
+    hook["onCommitFiberUnmount"] = () => {
+    };
+  }
+  if (typeof hook["onPostCommitFiberRoot"] !== "function") {
+    ;
+    hook["onPostCommitFiberRoot"] = () => {
+    };
+  }
+  hook.onCommitFiberRoot = (rendererId, root, priorityLevel) => {
+    if (chainedOriginal) {
+      try {
+        chainedOriginal(rendererId, root, priorityLevel);
+      } catch (err) {
+        console.warn("[react-perfscope] chained DevTools hook threw:", err);
+      }
+    }
+    for (const cb of listeners) {
+      try {
+        cb(root, rendererId);
+      } catch (err) {
+        console.warn("[react-perfscope] commit listener threw:", err);
+      }
+    }
+  };
+  g[HOOK_KEY] = hook;
+  ourHook = hook;
+}
+function installDevToolsHook(listener) {
+  ensureHookInstalled();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function uninstallDevToolsHook() {
+  listeners.clear();
+  ourHook = null;
+  chainedOriginal = null;
+}
+
+// src/fiber-walker.ts
+var MEMO_TYPE = /* @__PURE__ */ Symbol.for("react.memo");
+var FORWARD_REF_TYPE = /* @__PURE__ */ Symbol.for("react.forward_ref");
+function namedFunctionName(value) {
+  if (typeof value !== "function") return null;
+  const fn = value;
+  if (typeof fn.displayName === "string" && fn.displayName.length > 0) return fn.displayName;
+  if (typeof fn.name === "string" && fn.name.length > 0) return fn.name;
+  return null;
+}
+function fiberComponentName(fiber) {
+  if (!fiber) return null;
+  const type = fiber.type;
+  if (typeof type === "string") return type;
+  if (typeof type === "function") return namedFunctionName(type);
+  if (type && typeof type === "object") {
+    const wrapper = type;
+    if (wrapper.$$typeof === MEMO_TYPE) {
+      return namedFunctionName(wrapper.type);
+    }
+    if (wrapper.$$typeof === FORWARD_REF_TYPE) {
+      return namedFunctionName(wrapper.render);
+    }
+  }
+  return null;
+}
+function walkChangedFibers(root, visit, opts = {}) {
+  const max = opts.stopAt ?? 1e4;
+  const descend = opts.descend ?? (() => true);
+  let count = 0;
+  let depth = 0;
+  let node = root;
+  while (node) {
+    visit(node, depth);
+    count++;
+    if (count >= max) return;
+    if (node.child && descend(node)) {
+      node = node.child;
+      depth++;
+      continue;
+    }
+    while (node && !node.sibling) {
+      if (node === root) return;
+      node = node.return;
+      depth--;
+    }
+    if (!node || node === root) return;
+    node = node.sibling;
+  }
+}
+
+// src/attribution.ts
+var FIBER_KEY_PATTERNS = ["__reactFiber$", "__reactInternalInstance$"];
+function findFiberOnElement(el) {
+  for (const key of Object.keys(el)) {
+    for (const pattern of FIBER_KEY_PATTERNS) {
+      if (key.startsWith(pattern)) {
+        return el[key] ?? null;
+      }
+    }
+  }
+  return null;
+}
+function resolveComponentFromElement(el) {
+  const start = findFiberOnElement(el);
+  if (!start) return null;
+  let node = start;
+  while (node) {
+    if (typeof node.type === "function" || node.type && typeof node.type === "object") {
+      const name = fiberComponentName(node);
+      if (name) return name;
+    }
+    node = node.return;
+  }
+  return fiberComponentName(start);
+}
+
+// src/render-reason.ts
+var PERFORMED_WORK = 1;
+function didPerformWork(fiber) {
+  if (!fiber || typeof fiber.flags !== "number") return false;
+  return (fiber.flags & PERFORMED_WORK) !== 0;
+}
+function subtreeMightHaveRendered(fiber) {
+  if (typeof fiber.subtreeFlags !== "number") return true;
+  return (fiber.subtreeFlags & PERFORMED_WORK) !== 0;
+}
+function nearestComponentAncestor(fiber) {
+  let p = fiber.return;
+  while (p) {
+    if (typeof p.type === "function") return p;
+    p = p.return;
+  }
+  return null;
+}
+function asObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function changedPropKeys(prev, next) {
+  if (prev === next) return [];
+  const p = asObject(prev);
+  const n = asObject(next);
+  const keys = /* @__PURE__ */ new Set([...Object.keys(p), ...Object.keys(n)]);
+  const changed = [];
+  for (const k of keys) {
+    if (p[k] !== n[k]) changed.push(k);
+  }
+  return changed;
+}
+function classifyRenderReason(fiber) {
+  if (!fiber.alternate) return { reason: "mount" };
+  const changed = changedPropKeys(fiber.alternate.memoizedProps, fiber.memoizedProps);
+  if (changed.length > 0) return { reason: "props", changedProps: changed };
+  if (didPerformWork(nearestComponentAncestor(fiber))) return { reason: "parent" };
+  return { reason: "state" };
+}
+
+// src/render-collector.ts
+function createRenderCollector() {
+  let active = false;
+  let emit = () => {
+  };
+  let unsubscribe = null;
+  let commitId = 0;
+  function onCommit(root) {
+    if (!active) return;
+    const at = performance.now();
+    const id = commitId++;
+    walkChangedFibers(
+      root.current,
+      (fiber, depth) => {
+        if (typeof fiber.type === "string") return;
+        if (!didPerformWork(fiber)) return;
+        const name = fiberComponentName(fiber);
+        if (!name) return;
+        const duration = typeof fiber.actualDuration === "number" ? fiber.actualDuration : 0;
+        const { reason, changedProps } = classifyRenderReason(fiber);
+        emit({
+          kind: "render",
+          at,
+          component: name,
+          reason,
+          duration,
+          commitId: id,
+          depth,
+          ...changedProps ? { changedProps } : {}
+        });
+      },
+      // Prune subtrees that did no work this commit. Without this, a leaf that
+      // mounted long ago keeps its stale PerformedWork flag and gets reported
+      // as a phantom render on every unrelated commit.
+      { descend: subtreeMightHaveRendered }
+    );
+  }
+  return {
+    kind: "render",
+    activate(emitFn) {
+      emit = emitFn;
+      active = true;
+      if (unsubscribe) return;
+      unsubscribe = installDevToolsHook(onCommit);
+    },
+    deactivate() {
+      active = false;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRenderCollector,
+  fiberComponentName,
+  installDevToolsHook,
+  resolveComponentFromElement,
+  uninstallDevToolsHook,
+  walkChangedFibers
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/devtools-hook.ts","../src/fiber-walker.ts","../src/attribution.ts","../src/render-reason.ts","../src/render-collector.ts"],"sourcesContent":["export * from './types'\nexport { installDevToolsHook, uninstallDevToolsHook } from './devtools-hook'\nexport { fiberComponentName, walkChangedFibers } from './fiber-walker'\nexport { resolveComponentFromElement } from './attribution'\nexport { createRenderCollector } from './render-collector'\n","import type { MinimalFiber, ReactDevToolsHook } from './types'\n\ntype CommitListener = (root: { current: MinimalFiber }, rendererId: number) => void\n\nconst HOOK_KEY = '__REACT_DEVTOOLS_GLOBAL_HOOK__'\n\ninterface GlobalWithHook {\n  [HOOK_KEY]?: ReactDevToolsHook\n}\n\nconst listeners = new Set<CommitListener>()\nlet ourHook: ReactDevToolsHook | null = null\nlet chainedOriginal: ReactDevToolsHook['onCommitFiberRoot'] | null = null\n\nfunction ensureHookInstalled(): void {\n  const g = globalThis as GlobalWithHook\n  // Already ours and still installed — nothing to do.\n  if (ourHook && g[HOOK_KEY] === ourHook) return\n\n  const existing = g[HOOK_KEY]\n  chainedOriginal =\n    existing && existing !== ourHook && typeof existing.onCommitFiberRoot === 'function'\n      ? existing.onCommitFiberRoot\n      : null\n\n  const hook: ReactDevToolsHook = existing && existing !== ourHook ? existing : {}\n  // React's injectInternals() checks for supportsFiber and calls inject() to\n  // get a renderer ID. Without these, React stores injectedHook = null and\n  // never calls onCommitFiberRoot on subsequent commits.\n  if (!hook.supportsFiber) {\n    hook.supportsFiber = true\n  }\n  if (typeof hook.inject !== 'function') {\n    let _nextRendererId = 1\n    hook.inject = () => _nextRendererId++\n  }\n  // Additional fields that React Refresh (@vitejs/plugin-react) accesses on\n  // the hook. Without these it throws \"Cannot read properties of undefined\n  // (reading 'forEach')\" at injectIntoGlobalHook. We default each to a safe\n  // empty/noop value; if the real React DevTools extension installs later\n  // it will overwrite these.\n  if (!hook.renderers) {\n    ;(hook as Record<string, unknown>).renderers = new Map()\n  }\n  if (typeof (hook as Record<string, unknown>)['on'] !== 'function') {\n    ;(hook as Record<string, unknown>)['on'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['off'] !== 'function') {\n    ;(hook as Record<string, unknown>)['off'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['emit'] !== 'function') {\n    ;(hook as Record<string, unknown>)['emit'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['sub'] !== 'function') {\n    ;(hook as Record<string, unknown>)['sub'] = () => () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['checkDCE'] !== 'function') {\n    ;(hook as Record<string, unknown>)['checkDCE'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['onCommitFiberUnmount'] !== 'function') {\n    ;(hook as Record<string, unknown>)['onCommitFiberUnmount'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['onPostCommitFiberRoot'] !== 'function') {\n    ;(hook as Record<string, unknown>)['onPostCommitFiberRoot'] = () => {}\n  }\n  hook.onCommitFiberRoot = (rendererId, root, priorityLevel) => {\n    if (chainedOriginal) {\n      try {\n        chainedOriginal(rendererId, root, priorityLevel)\n      } catch (err) {\n        console.warn('[react-perfscope] chained DevTools hook threw:', err)\n      }\n    }\n    for (const cb of listeners) {\n      try {\n        cb(root, rendererId)\n      } catch (err) {\n        console.warn('[react-perfscope] commit listener threw:', err)\n      }\n    }\n  }\n  g[HOOK_KEY] = hook\n  ourHook = hook\n}\n\nexport function installDevToolsHook(listener: CommitListener): () => void {\n  ensureHookInstalled()\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * Clears all listeners and forgets our installed hook reference. Used by\n * tests to fully reset module state. Does NOT remove the hook from\n * globalThis — callers that want a fully clean slate must also\n * `delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`.\n */\nexport function uninstallDevToolsHook(): void {\n  listeners.clear()\n  ourHook = null\n  chainedOriginal = null\n}\n","import type { MinimalFiber } from './types'\n\nconst MEMO_TYPE = Symbol.for('react.memo')\nconst FORWARD_REF_TYPE = Symbol.for('react.forward_ref')\n\ntype WrapperType = {\n  $$typeof: symbol\n  type?: unknown\n  render?: unknown\n}\n\nfunction namedFunctionName(value: unknown): string | null {\n  if (typeof value !== 'function') return null\n  const fn = value as { displayName?: string; name?: string }\n  if (typeof fn.displayName === 'string' && fn.displayName.length > 0) return fn.displayName\n  if (typeof fn.name === 'string' && fn.name.length > 0) return fn.name\n  return null\n}\n\n/**\n * Return the component name for a fiber.\n *\n * Host components (DOM tags) return their tag string. Function and class\n * components return their displayName or name. Memo and forwardRef wrappers\n * are unwrapped to their inner component. Unknown shapes return null.\n */\nexport function fiberComponentName(fiber: MinimalFiber | null): string | null {\n  if (!fiber) return null\n  const type = fiber.type\n  if (typeof type === 'string') return type\n  if (typeof type === 'function') return namedFunctionName(type)\n  if (type && typeof type === 'object') {\n    const wrapper = type as WrapperType\n    if (wrapper.$$typeof === MEMO_TYPE) {\n      return namedFunctionName(wrapper.type)\n    }\n    if (wrapper.$$typeof === FORWARD_REF_TYPE) {\n      return namedFunctionName(wrapper.render)\n    }\n  }\n  return null\n}\n\ninterface WalkOptions {\n  /**\n   * Maximum number of fibers to visit. Prevents runaway traversal on very\n   * deep trees. Default 10_000.\n   */\n  stopAt?: number\n  /**\n   * Predicate deciding whether to descend into a fiber's children. Returning\n   * false prunes the entire subtree (the fiber itself is still visited). Used\n   * to skip subtrees that did no work this commit. Defaults to always descend.\n   */\n  descend?: (fiber: MinimalFiber) => boolean\n}\n\n/**\n * Walk a fiber subtree depth-first, invoking `visit` for every fiber with its\n * depth relative to `root` (root is depth 0). Returns early once `stopAt`\n * fibers have been visited. When `descend` returns false for a fiber, its\n * children are skipped entirely.\n */\nexport function walkChangedFibers(\n  root: MinimalFiber,\n  visit: (fiber: MinimalFiber, depth: number) => void,\n  opts: WalkOptions = {}\n): void {\n  const max = opts.stopAt ?? 10_000\n  const descend = opts.descend ?? (() => true)\n  let count = 0\n  let depth = 0\n  let node: MinimalFiber | null = root\n  while (node) {\n    visit(node, depth)\n    count++\n    if (count >= max) return\n    if (node.child && descend(node)) {\n      node = node.child\n      depth++\n      continue\n    }\n    while (node && !node.sibling) {\n      if (node === root) return\n      node = node.return\n      depth--\n    }\n    if (!node || node === root) return\n    node = node.sibling\n  }\n}\n","import type { MinimalFiber } from './types'\nimport { fiberComponentName } from './fiber-walker'\n\nconst FIBER_KEY_PATTERNS = ['__reactFiber$', '__reactInternalInstance$']\n\nfunction findFiberOnElement(el: HTMLElement): MinimalFiber | null {\n  for (const key of Object.keys(el)) {\n    for (const pattern of FIBER_KEY_PATTERNS) {\n      if (key.startsWith(pattern)) {\n        return (el as HTMLElement & Record<string, MinimalFiber>)[key] ?? null\n      }\n    }\n  }\n  return null\n}\n\n/**\n * Walk up from the fiber attached to `el` until we find one whose `type` is\n * a function or class component (not a host tag string). Returns that\n * component's display name. If no component is found, returns the host\n * tag name of the starting fiber. If no fiber is attached, returns null.\n */\nexport function resolveComponentFromElement(el: HTMLElement): string | null {\n  const start = findFiberOnElement(el)\n  if (!start) return null\n  let node: MinimalFiber | null = start\n  while (node) {\n    if (typeof node.type === 'function' || (node.type && typeof node.type === 'object')) {\n      const name = fiberComponentName(node)\n      if (name) return name\n    }\n    node = node.return\n  }\n  // Nothing but host fibers above — return the host tag name of the starting fiber.\n  return fiberComponentName(start)\n}\n","import type { MinimalFiber } from './types'\n\n/** React's `PerformedWork` flag — set on a fiber whose render actually ran. */\nexport const PERFORMED_WORK = 0b1\n\nexport type RenderReason = 'mount' | 'state' | 'props' | 'parent'\n\nexport interface RenderReasonResult {\n  reason: RenderReason\n  changedProps?: string[]\n}\n\nexport function didPerformWork(fiber: MinimalFiber | null): boolean {\n  if (!fiber || typeof fiber.flags !== 'number') return false\n  return (fiber.flags & PERFORMED_WORK) !== 0\n}\n\n/**\n * Should the walk descend into this fiber's children when hunting for renders?\n *\n * React bubbles the `PerformedWork` bit of every descendant into a fiber's\n * `subtreeFlags`, and (unlike `flags`) resets it whenever the reconciler\n * re-clones the fiber. So a numeric `subtreeFlags` without the bit reliably\n * means \"no descendant rendered this commit\" — we can stop here and avoid\n * stale leaves whose own `flags` never got cleared.\n *\n * When `subtreeFlags` is absent (React < 18) we cannot prune safely, so we\n * descend and fall back to the full-tree walk.\n */\nexport function subtreeMightHaveRendered(fiber: MinimalFiber): boolean {\n  if (typeof fiber.subtreeFlags !== 'number') return true\n  return (fiber.subtreeFlags & PERFORMED_WORK) !== 0\n}\n\n/**\n * Walk up `.return` to the nearest *component* fiber, skipping host (DOM)\n * fibers. A component's immediate `.return` is usually a host fiber (the\n * `<div>` it's nested in), not its parent component — so to ask \"did my\n * parent component render?\" we have to climb past the host nodes first.\n */\nexport function nearestComponentAncestor(fiber: MinimalFiber): MinimalFiber | null {\n  let p = fiber.return\n  while (p) {\n    if (typeof p.type === 'function') return p\n    p = p.return\n  }\n  return null\n}\n\nfunction asObject(value: unknown): Record<string, unknown> {\n  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n}\n\n/** Shallow diff of two prop bags. Returns the keys whose values differ. */\nexport function changedPropKeys(prev: unknown, next: unknown): string[] {\n  if (prev === next) return []\n  const p = asObject(prev)\n  const n = asObject(next)\n  const keys = new Set([...Object.keys(p), ...Object.keys(n)])\n  const changed: string[] = []\n  for (const k of keys) {\n    if (p[k] !== n[k]) changed.push(k)\n  }\n  return changed\n}\n\n/**\n * Classify WHY a fiber that performed work this commit rendered.\n *\n * - `mount`  — first render (no previous fiber).\n * - `props`  — at least one prop changed since the previous render.\n * - `state`  — props are identical AND the parent did not render, so the\n *              update originated here (own state/force update). This is the\n *              root of a render cascade.\n * - `parent` — props are identical but the parent rendered, so this only\n *              re-rendered because of its parent. This is the avoidable\n *              \"wrap me in memo\" case the developer is hunting for.\n *\n * Assumes the caller only invokes this for fibers that actually performed\n * work (see `didPerformWork`).\n */\nexport function classifyRenderReason(fiber: MinimalFiber): RenderReasonResult {\n  if (!fiber.alternate) return { reason: 'mount' }\n  const changed = changedPropKeys(fiber.alternate.memoizedProps, fiber.memoizedProps)\n  if (changed.length > 0) return { reason: 'props', changedProps: changed }\n  if (didPerformWork(nearestComponentAncestor(fiber))) return { reason: 'parent' }\n  return { reason: 'state' }\n}\n","import type { Collector, Signal } from '@react-perfscope/core'\nimport { installDevToolsHook } from './devtools-hook'\nimport { fiberComponentName, walkChangedFibers } from './fiber-walker'\nimport { classifyRenderReason, didPerformWork, subtreeMightHaveRendered } from './render-reason'\nimport type { MinimalFiber } from './types'\n\nexport function createRenderCollector(): Collector {\n  let active = false\n  let emit: (signal: Signal) => void = () => {}\n  let unsubscribe: (() => void) | null = null\n  let commitId = 0\n\n  function onCommit(root: { current: MinimalFiber }) {\n    if (!active) return\n    const at = performance.now()\n    const id = commitId++\n    walkChangedFibers(\n      root.current,\n      (fiber, depth) => {\n        // Skip host (DOM) fibers — we only want function/class components in\n        // render reports.\n        if (typeof fiber.type === 'string') return\n        // Only report fibers that actually re-ran their render this commit.\n        // A bailed-out fiber (e.g. memo with equal props) keeps its place in\n        // the tree but did no work, so reporting it would be noise.\n        if (!didPerformWork(fiber)) return\n        const name = fiberComponentName(fiber)\n        if (!name) return\n        const duration = typeof fiber.actualDuration === 'number' ? fiber.actualDuration : 0\n        const { reason, changedProps } = classifyRenderReason(fiber)\n        emit({\n          kind: 'render',\n          at,\n          component: name,\n          reason,\n          duration,\n          commitId: id,\n          depth,\n          ...(changedProps ? { changedProps } : {}),\n        })\n      },\n      // Prune subtrees that did no work this commit. Without this, a leaf that\n      // mounted long ago keeps its stale PerformedWork flag and gets reported\n      // as a phantom render on every unrelated commit.\n      { descend: subtreeMightHaveRendered }\n    )\n  }\n\n  return {\n    kind: 'render',\n    activate(emitFn) {\n      emit = emitFn\n      active = true\n      if (unsubscribe) return\n      unsubscribe = installDevToolsHook(onCommit)\n    },\n    deactivate() {\n      active = false\n      // Keep the global hook listener attached — installDevToolsHook is\n      // idempotent and removing it on every deactivate would cost us the\n      // ability to re-attach cleanly under the test reset hooks. The\n      // `active` flag gates emission.\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,131 @@
+/// <reference lib="es2015" />
+/// <reference lib="dom" />
+
+import { Collector } from '@react-perfscope/core';
+export { Collector } from '@react-perfscope/core';
+
+/**
+ * Resolves a DOM element back to the nearest React component name in the
+ * fiber tree. Returns null when no React fiber is attached (e.g. host nodes
+ * outside any React root, detached nodes, or before React mounts).
+ */
+interface ReactAdapter {
+    /**
+     * Install the DevTools global hook to observe React commits. Idempotent:
+     * a second install is a no-op (or chains with an existing hook installed
+     * by React DevTools).
+     */
+    install(): void;
+    /**
+     * Look up the component name for a DOM element by walking its fiber.
+     */
+    resolveComponentFromElement(el: HTMLElement): string | null;
+}
+/**
+ * Minimal shape of a React fiber node that we touch. The real fiber has
+ * many more fields; we only declare what we read.
+ */
+interface MinimalFiber {
+    stateNode: unknown;
+    type: unknown;
+    return: MinimalFiber | null;
+    child: MinimalFiber | null;
+    sibling: MinimalFiber | null;
+    alternate: MinimalFiber | null;
+    elementType?: unknown;
+    memoizedProps?: unknown;
+    /** Set by React when the fiber is inside a Profiler-enabled root. */
+    actualDuration?: number;
+    /**
+     * React's effect/work bitmask. The low bit (`PerformedWork`, 0b1) is set
+     * when beginWork actually ran this fiber's render (i.e. it did NOT bail
+     * out). We use it to tell "this rendered" from "this was skipped".
+     *
+     * Caveat: React does NOT clear this on a fiber that bailed out, so a leaf
+     * that rendered in some past commit keeps the bit set forever. Read it only
+     * for fibers the reconciler actually visited this commit (see `subtreeFlags`).
+     */
+    flags?: number;
+    /**
+     * React bubbles every descendant's flags (including `PerformedWork`) into
+     * this field during completeWork. Unlike `flags`, it is reset whenever the
+     * reconciler re-clones a fiber, so `subtreeFlags & PerformedWork === 0`
+     * reliably means "nothing below me rendered this commit" — letting us prune
+     * the walk before reaching stale leaves. Absent on React < 18.
+     */
+    subtreeFlags?: number;
+}
+/**
+ * The DevTools global hook React looks for at module load time. We register
+ * our own listener via `onCommitFiberRoot`.
+ */
+interface ReactDevToolsHook {
+    onCommitFiberRoot?: (rendererId: number, root: {
+        current: MinimalFiber;
+    }, priorityLevel?: unknown) => void;
+    /**
+     * React checks supportsFiber before storing the hook reference in its
+     * internal injectedHook. Must be true for React ≥ 16.4 to recognise the
+     * hook and call onCommitFiberRoot.
+     */
+    supportsFiber?: boolean;
+    /**
+     * React calls inject(internals) and stores the returned renderer ID.
+     * A minimal no-op implementation (return 1) is sufficient for our purposes.
+     */
+    inject?: (internals: unknown) => number;
+    [key: string]: unknown;
+}
+
+type CommitListener = (root: {
+    current: MinimalFiber;
+}, rendererId: number) => void;
+declare function installDevToolsHook(listener: CommitListener): () => void;
+/**
+ * Clears all listeners and forgets our installed hook reference. Used by
+ * tests to fully reset module state. Does NOT remove the hook from
+ * globalThis — callers that want a fully clean slate must also
+ * `delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`.
+ */
+declare function uninstallDevToolsHook(): void;
+
+/**
+ * Return the component name for a fiber.
+ *
+ * Host components (DOM tags) return their tag string. Function and class
+ * components return their displayName or name. Memo and forwardRef wrappers
+ * are unwrapped to their inner component. Unknown shapes return null.
+ */
+declare function fiberComponentName(fiber: MinimalFiber | null): string | null;
+interface WalkOptions {
+    /**
+     * Maximum number of fibers to visit. Prevents runaway traversal on very
+     * deep trees. Default 10_000.
+     */
+    stopAt?: number;
+    /**
+     * Predicate deciding whether to descend into a fiber's children. Returning
+     * false prunes the entire subtree (the fiber itself is still visited). Used
+     * to skip subtrees that did no work this commit. Defaults to always descend.
+     */
+    descend?: (fiber: MinimalFiber) => boolean;
+}
+/**
+ * Walk a fiber subtree depth-first, invoking `visit` for every fiber with its
+ * depth relative to `root` (root is depth 0). Returns early once `stopAt`
+ * fibers have been visited. When `descend` returns false for a fiber, its
+ * children are skipped entirely.
+ */
+declare function walkChangedFibers(root: MinimalFiber, visit: (fiber: MinimalFiber, depth: number) => void, opts?: WalkOptions): void;
+
+/**
+ * Walk up from the fiber attached to `el` until we find one whose `type` is
+ * a function or class component (not a host tag string). Returns that
+ * component's display name. If no component is found, returns the host
+ * tag name of the starting fiber. If no fiber is attached, returns null.
+ */
+declare function resolveComponentFromElement(el: HTMLElement): string | null;
+
+declare function createRenderCollector(): Collector;
+
+export { type MinimalFiber, type ReactAdapter, type ReactDevToolsHook, createRenderCollector, fiberComponentName, installDevToolsHook, resolveComponentFromElement, uninstallDevToolsHook, walkChangedFibers };

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+/// <reference lib="es2015" />
+/// <reference lib="dom" />
+
+import { Collector } from '@react-perfscope/core';
+export { Collector } from '@react-perfscope/core';
+
+/**
+ * Resolves a DOM element back to the nearest React component name in the
+ * fiber tree. Returns null when no React fiber is attached (e.g. host nodes
+ * outside any React root, detached nodes, or before React mounts).
+ */
+interface ReactAdapter {
+    /**
+     * Install the DevTools global hook to observe React commits. Idempotent:
+     * a second install is a no-op (or chains with an existing hook installed
+     * by React DevTools).
+     */
+    install(): void;
+    /**
+     * Look up the component name for a DOM element by walking its fiber.
+     */
+    resolveComponentFromElement(el: HTMLElement): string | null;
+}
+/**
+ * Minimal shape of a React fiber node that we touch. The real fiber has
+ * many more fields; we only declare what we read.
+ */
+interface MinimalFiber {
+    stateNode: unknown;
+    type: unknown;
+    return: MinimalFiber | null;
+    child: MinimalFiber | null;
+    sibling: MinimalFiber | null;
+    alternate: MinimalFiber | null;
+    elementType?: unknown;
+    memoizedProps?: unknown;
+    /** Set by React when the fiber is inside a Profiler-enabled root. */
+    actualDuration?: number;
+    /**
+     * React's effect/work bitmask. The low bit (`PerformedWork`, 0b1) is set
+     * when beginWork actually ran this fiber's render (i.e. it did NOT bail
+     * out). We use it to tell "this rendered" from "this was skipped".
+     *
+     * Caveat: React does NOT clear this on a fiber that bailed out, so a leaf
+     * that rendered in some past commit keeps the bit set forever. Read it only
+     * for fibers the reconciler actually visited this commit (see `subtreeFlags`).
+     */
+    flags?: number;
+    /**
+     * React bubbles every descendant's flags (including `PerformedWork`) into
+     * this field during completeWork. Unlike `flags`, it is reset whenever the
+     * reconciler re-clones a fiber, so `subtreeFlags & PerformedWork === 0`
+     * reliably means "nothing below me rendered this commit" — letting us prune
+     * the walk before reaching stale leaves. Absent on React < 18.
+     */
+    subtreeFlags?: number;
+}
+/**
+ * The DevTools global hook React looks for at module load time. We register
+ * our own listener via `onCommitFiberRoot`.
+ */
+interface ReactDevToolsHook {
+    onCommitFiberRoot?: (rendererId: number, root: {
+        current: MinimalFiber;
+    }, priorityLevel?: unknown) => void;
+    /**
+     * React checks supportsFiber before storing the hook reference in its
+     * internal injectedHook. Must be true for React ≥ 16.4 to recognise the
+     * hook and call onCommitFiberRoot.
+     */
+    supportsFiber?: boolean;
+    /**
+     * React calls inject(internals) and stores the returned renderer ID.
+     * A minimal no-op implementation (return 1) is sufficient for our purposes.
+     */
+    inject?: (internals: unknown) => number;
+    [key: string]: unknown;
+}
+
+type CommitListener = (root: {
+    current: MinimalFiber;
+}, rendererId: number) => void;
+declare function installDevToolsHook(listener: CommitListener): () => void;
+/**
+ * Clears all listeners and forgets our installed hook reference. Used by
+ * tests to fully reset module state. Does NOT remove the hook from
+ * globalThis — callers that want a fully clean slate must also
+ * `delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`.
+ */
+declare function uninstallDevToolsHook(): void;
+
+/**
+ * Return the component name for a fiber.
+ *
+ * Host components (DOM tags) return their tag string. Function and class
+ * components return their displayName or name. Memo and forwardRef wrappers
+ * are unwrapped to their inner component. Unknown shapes return null.
+ */
+declare function fiberComponentName(fiber: MinimalFiber | null): string | null;
+interface WalkOptions {
+    /**
+     * Maximum number of fibers to visit. Prevents runaway traversal on very
+     * deep trees. Default 10_000.
+     */
+    stopAt?: number;
+    /**
+     * Predicate deciding whether to descend into a fiber's children. Returning
+     * false prunes the entire subtree (the fiber itself is still visited). Used
+     * to skip subtrees that did no work this commit. Defaults to always descend.
+     */
+    descend?: (fiber: MinimalFiber) => boolean;
+}
+/**
+ * Walk a fiber subtree depth-first, invoking `visit` for every fiber with its
+ * depth relative to `root` (root is depth 0). Returns early once `stopAt`
+ * fibers have been visited. When `descend` returns false for a fiber, its
+ * children are skipped entirely.
+ */
+declare function walkChangedFibers(root: MinimalFiber, visit: (fiber: MinimalFiber, depth: number) => void, opts?: WalkOptions): void;
+
+/**
+ * Walk up from the fiber attached to `el` until we find one whose `type` is
+ * a function or class component (not a host tag string). Returns that
+ * component's display name. If no component is found, returns the host
+ * tag name of the starting fiber. If no fiber is attached, returns null.
+ */
+declare function resolveComponentFromElement(el: HTMLElement): string | null;
+
+declare function createRenderCollector(): Collector;
+
+export { type MinimalFiber, type ReactAdapter, type ReactDevToolsHook, createRenderCollector, fiberComponentName, installDevToolsHook, resolveComponentFromElement, uninstallDevToolsHook, walkChangedFibers };

package/dist/index.js

@@ -0,0 +1,265 @@
+// src/devtools-hook.ts
+var HOOK_KEY = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+var listeners = /* @__PURE__ */ new Set();
+var ourHook = null;
+var chainedOriginal = null;
+function ensureHookInstalled() {
+  const g = globalThis;
+  if (ourHook && g[HOOK_KEY] === ourHook) return;
+  const existing = g[HOOK_KEY];
+  chainedOriginal = existing && existing !== ourHook && typeof existing.onCommitFiberRoot === "function" ? existing.onCommitFiberRoot : null;
+  const hook = existing && existing !== ourHook ? existing : {};
+  if (!hook.supportsFiber) {
+    hook.supportsFiber = true;
+  }
+  if (typeof hook.inject !== "function") {
+    let _nextRendererId = 1;
+    hook.inject = () => _nextRendererId++;
+  }
+  if (!hook.renderers) {
+    ;
+    hook.renderers = /* @__PURE__ */ new Map();
+  }
+  if (typeof hook["on"] !== "function") {
+    ;
+    hook["on"] = () => {
+    };
+  }
+  if (typeof hook["off"] !== "function") {
+    ;
+    hook["off"] = () => {
+    };
+  }
+  if (typeof hook["emit"] !== "function") {
+    ;
+    hook["emit"] = () => {
+    };
+  }
+  if (typeof hook["sub"] !== "function") {
+    ;
+    hook["sub"] = () => () => {
+    };
+  }
+  if (typeof hook["checkDCE"] !== "function") {
+    ;
+    hook["checkDCE"] = () => {
+    };
+  }
+  if (typeof hook["onCommitFiberUnmount"] !== "function") {
+    ;
+    hook["onCommitFiberUnmount"] = () => {
+    };
+  }
+  if (typeof hook["onPostCommitFiberRoot"] !== "function") {
+    ;
+    hook["onPostCommitFiberRoot"] = () => {
+    };
+  }
+  hook.onCommitFiberRoot = (rendererId, root, priorityLevel) => {
+    if (chainedOriginal) {
+      try {
+        chainedOriginal(rendererId, root, priorityLevel);
+      } catch (err) {
+        console.warn("[react-perfscope] chained DevTools hook threw:", err);
+      }
+    }
+    for (const cb of listeners) {
+      try {
+        cb(root, rendererId);
+      } catch (err) {
+        console.warn("[react-perfscope] commit listener threw:", err);
+      }
+    }
+  };
+  g[HOOK_KEY] = hook;
+  ourHook = hook;
+}
+function installDevToolsHook(listener) {
+  ensureHookInstalled();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function uninstallDevToolsHook() {
+  listeners.clear();
+  ourHook = null;
+  chainedOriginal = null;
+}
+
+// src/fiber-walker.ts
+var MEMO_TYPE = /* @__PURE__ */ Symbol.for("react.memo");
+var FORWARD_REF_TYPE = /* @__PURE__ */ Symbol.for("react.forward_ref");
+function namedFunctionName(value) {
+  if (typeof value !== "function") return null;
+  const fn = value;
+  if (typeof fn.displayName === "string" && fn.displayName.length > 0) return fn.displayName;
+  if (typeof fn.name === "string" && fn.name.length > 0) return fn.name;
+  return null;
+}
+function fiberComponentName(fiber) {
+  if (!fiber) return null;
+  const type = fiber.type;
+  if (typeof type === "string") return type;
+  if (typeof type === "function") return namedFunctionName(type);
+  if (type && typeof type === "object") {
+    const wrapper = type;
+    if (wrapper.$$typeof === MEMO_TYPE) {
+      return namedFunctionName(wrapper.type);
+    }
+    if (wrapper.$$typeof === FORWARD_REF_TYPE) {
+      return namedFunctionName(wrapper.render);
+    }
+  }
+  return null;
+}
+function walkChangedFibers(root, visit, opts = {}) {
+  const max = opts.stopAt ?? 1e4;
+  const descend = opts.descend ?? (() => true);
+  let count = 0;
+  let depth = 0;
+  let node = root;
+  while (node) {
+    visit(node, depth);
+    count++;
+    if (count >= max) return;
+    if (node.child && descend(node)) {
+      node = node.child;
+      depth++;
+      continue;
+    }
+    while (node && !node.sibling) {
+      if (node === root) return;
+      node = node.return;
+      depth--;
+    }
+    if (!node || node === root) return;
+    node = node.sibling;
+  }
+}
+
+// src/attribution.ts
+var FIBER_KEY_PATTERNS = ["__reactFiber$", "__reactInternalInstance$"];
+function findFiberOnElement(el) {
+  for (const key of Object.keys(el)) {
+    for (const pattern of FIBER_KEY_PATTERNS) {
+      if (key.startsWith(pattern)) {
+        return el[key] ?? null;
+      }
+    }
+  }
+  return null;
+}
+function resolveComponentFromElement(el) {
+  const start = findFiberOnElement(el);
+  if (!start) return null;
+  let node = start;
+  while (node) {
+    if (typeof node.type === "function" || node.type && typeof node.type === "object") {
+      const name = fiberComponentName(node);
+      if (name) return name;
+    }
+    node = node.return;
+  }
+  return fiberComponentName(start);
+}
+
+// src/render-reason.ts
+var PERFORMED_WORK = 1;
+function didPerformWork(fiber) {
+  if (!fiber || typeof fiber.flags !== "number") return false;
+  return (fiber.flags & PERFORMED_WORK) !== 0;
+}
+function subtreeMightHaveRendered(fiber) {
+  if (typeof fiber.subtreeFlags !== "number") return true;
+  return (fiber.subtreeFlags & PERFORMED_WORK) !== 0;
+}
+function nearestComponentAncestor(fiber) {
+  let p = fiber.return;
+  while (p) {
+    if (typeof p.type === "function") return p;
+    p = p.return;
+  }
+  return null;
+}
+function asObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function changedPropKeys(prev, next) {
+  if (prev === next) return [];
+  const p = asObject(prev);
+  const n = asObject(next);
+  const keys = /* @__PURE__ */ new Set([...Object.keys(p), ...Object.keys(n)]);
+  const changed = [];
+  for (const k of keys) {
+    if (p[k] !== n[k]) changed.push(k);
+  }
+  return changed;
+}
+function classifyRenderReason(fiber) {
+  if (!fiber.alternate) return { reason: "mount" };
+  const changed = changedPropKeys(fiber.alternate.memoizedProps, fiber.memoizedProps);
+  if (changed.length > 0) return { reason: "props", changedProps: changed };
+  if (didPerformWork(nearestComponentAncestor(fiber))) return { reason: "parent" };
+  return { reason: "state" };
+}
+
+// src/render-collector.ts
+function createRenderCollector() {
+  let active = false;
+  let emit = () => {
+  };
+  let unsubscribe = null;
+  let commitId = 0;
+  function onCommit(root) {
+    if (!active) return;
+    const at = performance.now();
+    const id = commitId++;
+    walkChangedFibers(
+      root.current,
+      (fiber, depth) => {
+        if (typeof fiber.type === "string") return;
+        if (!didPerformWork(fiber)) return;
+        const name = fiberComponentName(fiber);
+        if (!name) return;
+        const duration = typeof fiber.actualDuration === "number" ? fiber.actualDuration : 0;
+        const { reason, changedProps } = classifyRenderReason(fiber);
+        emit({
+          kind: "render",
+          at,
+          component: name,
+          reason,
+          duration,
+          commitId: id,
+          depth,
+          ...changedProps ? { changedProps } : {}
+        });
+      },
+      // Prune subtrees that did no work this commit. Without this, a leaf that
+      // mounted long ago keeps its stale PerformedWork flag and gets reported
+      // as a phantom render on every unrelated commit.
+      { descend: subtreeMightHaveRendered }
+    );
+  }
+  return {
+    kind: "render",
+    activate(emitFn) {
+      emit = emitFn;
+      active = true;
+      if (unsubscribe) return;
+      unsubscribe = installDevToolsHook(onCommit);
+    },
+    deactivate() {
+      active = false;
+    }
+  };
+}
+export {
+  createRenderCollector,
+  fiberComponentName,
+  installDevToolsHook,
+  resolveComponentFromElement,
+  uninstallDevToolsHook,
+  walkChangedFibers
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/devtools-hook.ts","../src/fiber-walker.ts","../src/attribution.ts","../src/render-reason.ts","../src/render-collector.ts"],"sourcesContent":["import type { MinimalFiber, ReactDevToolsHook } from './types'\n\ntype CommitListener = (root: { current: MinimalFiber }, rendererId: number) => void\n\nconst HOOK_KEY = '__REACT_DEVTOOLS_GLOBAL_HOOK__'\n\ninterface GlobalWithHook {\n  [HOOK_KEY]?: ReactDevToolsHook\n}\n\nconst listeners = new Set<CommitListener>()\nlet ourHook: ReactDevToolsHook | null = null\nlet chainedOriginal: ReactDevToolsHook['onCommitFiberRoot'] | null = null\n\nfunction ensureHookInstalled(): void {\n  const g = globalThis as GlobalWithHook\n  // Already ours and still installed — nothing to do.\n  if (ourHook && g[HOOK_KEY] === ourHook) return\n\n  const existing = g[HOOK_KEY]\n  chainedOriginal =\n    existing && existing !== ourHook && typeof existing.onCommitFiberRoot === 'function'\n      ? existing.onCommitFiberRoot\n      : null\n\n  const hook: ReactDevToolsHook = existing && existing !== ourHook ? existing : {}\n  // React's injectInternals() checks for supportsFiber and calls inject() to\n  // get a renderer ID. Without these, React stores injectedHook = null and\n  // never calls onCommitFiberRoot on subsequent commits.\n  if (!hook.supportsFiber) {\n    hook.supportsFiber = true\n  }\n  if (typeof hook.inject !== 'function') {\n    let _nextRendererId = 1\n    hook.inject = () => _nextRendererId++\n  }\n  // Additional fields that React Refresh (@vitejs/plugin-react) accesses on\n  // the hook. Without these it throws \"Cannot read properties of undefined\n  // (reading 'forEach')\" at injectIntoGlobalHook. We default each to a safe\n  // empty/noop value; if the real React DevTools extension installs later\n  // it will overwrite these.\n  if (!hook.renderers) {\n    ;(hook as Record<string, unknown>).renderers = new Map()\n  }\n  if (typeof (hook as Record<string, unknown>)['on'] !== 'function') {\n    ;(hook as Record<string, unknown>)['on'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['off'] !== 'function') {\n    ;(hook as Record<string, unknown>)['off'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['emit'] !== 'function') {\n    ;(hook as Record<string, unknown>)['emit'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['sub'] !== 'function') {\n    ;(hook as Record<string, unknown>)['sub'] = () => () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['checkDCE'] !== 'function') {\n    ;(hook as Record<string, unknown>)['checkDCE'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['onCommitFiberUnmount'] !== 'function') {\n    ;(hook as Record<string, unknown>)['onCommitFiberUnmount'] = () => {}\n  }\n  if (typeof (hook as Record<string, unknown>)['onPostCommitFiberRoot'] !== 'function') {\n    ;(hook as Record<string, unknown>)['onPostCommitFiberRoot'] = () => {}\n  }\n  hook.onCommitFiberRoot = (rendererId, root, priorityLevel) => {\n    if (chainedOriginal) {\n      try {\n        chainedOriginal(rendererId, root, priorityLevel)\n      } catch (err) {\n        console.warn('[react-perfscope] chained DevTools hook threw:', err)\n      }\n    }\n    for (const cb of listeners) {\n      try {\n        cb(root, rendererId)\n      } catch (err) {\n        console.warn('[react-perfscope] commit listener threw:', err)\n      }\n    }\n  }\n  g[HOOK_KEY] = hook\n  ourHook = hook\n}\n\nexport function installDevToolsHook(listener: CommitListener): () => void {\n  ensureHookInstalled()\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * Clears all listeners and forgets our installed hook reference. Used by\n * tests to fully reset module state. Does NOT remove the hook from\n * globalThis — callers that want a fully clean slate must also\n * `delete globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__`.\n */\nexport function uninstallDevToolsHook(): void {\n  listeners.clear()\n  ourHook = null\n  chainedOriginal = null\n}\n","import type { MinimalFiber } from './types'\n\nconst MEMO_TYPE = Symbol.for('react.memo')\nconst FORWARD_REF_TYPE = Symbol.for('react.forward_ref')\n\ntype WrapperType = {\n  $$typeof: symbol\n  type?: unknown\n  render?: unknown\n}\n\nfunction namedFunctionName(value: unknown): string | null {\n  if (typeof value !== 'function') return null\n  const fn = value as { displayName?: string; name?: string }\n  if (typeof fn.displayName === 'string' && fn.displayName.length > 0) return fn.displayName\n  if (typeof fn.name === 'string' && fn.name.length > 0) return fn.name\n  return null\n}\n\n/**\n * Return the component name for a fiber.\n *\n * Host components (DOM tags) return their tag string. Function and class\n * components return their displayName or name. Memo and forwardRef wrappers\n * are unwrapped to their inner component. Unknown shapes return null.\n */\nexport function fiberComponentName(fiber: MinimalFiber | null): string | null {\n  if (!fiber) return null\n  const type = fiber.type\n  if (typeof type === 'string') return type\n  if (typeof type === 'function') return namedFunctionName(type)\n  if (type && typeof type === 'object') {\n    const wrapper = type as WrapperType\n    if (wrapper.$$typeof === MEMO_TYPE) {\n      return namedFunctionName(wrapper.type)\n    }\n    if (wrapper.$$typeof === FORWARD_REF_TYPE) {\n      return namedFunctionName(wrapper.render)\n    }\n  }\n  return null\n}\n\ninterface WalkOptions {\n  /**\n   * Maximum number of fibers to visit. Prevents runaway traversal on very\n   * deep trees. Default 10_000.\n   */\n  stopAt?: number\n  /**\n   * Predicate deciding whether to descend into a fiber's children. Returning\n   * false prunes the entire subtree (the fiber itself is still visited). Used\n   * to skip subtrees that did no work this commit. Defaults to always descend.\n   */\n  descend?: (fiber: MinimalFiber) => boolean\n}\n\n/**\n * Walk a fiber subtree depth-first, invoking `visit` for every fiber with its\n * depth relative to `root` (root is depth 0). Returns early once `stopAt`\n * fibers have been visited. When `descend` returns false for a fiber, its\n * children are skipped entirely.\n */\nexport function walkChangedFibers(\n  root: MinimalFiber,\n  visit: (fiber: MinimalFiber, depth: number) => void,\n  opts: WalkOptions = {}\n): void {\n  const max = opts.stopAt ?? 10_000\n  const descend = opts.descend ?? (() => true)\n  let count = 0\n  let depth = 0\n  let node: MinimalFiber | null = root\n  while (node) {\n    visit(node, depth)\n    count++\n    if (count >= max) return\n    if (node.child && descend(node)) {\n      node = node.child\n      depth++\n      continue\n    }\n    while (node && !node.sibling) {\n      if (node === root) return\n      node = node.return\n      depth--\n    }\n    if (!node || node === root) return\n    node = node.sibling\n  }\n}\n","import type { MinimalFiber } from './types'\nimport { fiberComponentName } from './fiber-walker'\n\nconst FIBER_KEY_PATTERNS = ['__reactFiber$', '__reactInternalInstance$']\n\nfunction findFiberOnElement(el: HTMLElement): MinimalFiber | null {\n  for (const key of Object.keys(el)) {\n    for (const pattern of FIBER_KEY_PATTERNS) {\n      if (key.startsWith(pattern)) {\n        return (el as HTMLElement & Record<string, MinimalFiber>)[key] ?? null\n      }\n    }\n  }\n  return null\n}\n\n/**\n * Walk up from the fiber attached to `el` until we find one whose `type` is\n * a function or class component (not a host tag string). Returns that\n * component's display name. If no component is found, returns the host\n * tag name of the starting fiber. If no fiber is attached, returns null.\n */\nexport function resolveComponentFromElement(el: HTMLElement): string | null {\n  const start = findFiberOnElement(el)\n  if (!start) return null\n  let node: MinimalFiber | null = start\n  while (node) {\n    if (typeof node.type === 'function' || (node.type && typeof node.type === 'object')) {\n      const name = fiberComponentName(node)\n      if (name) return name\n    }\n    node = node.return\n  }\n  // Nothing but host fibers above — return the host tag name of the starting fiber.\n  return fiberComponentName(start)\n}\n","import type { MinimalFiber } from './types'\n\n/** React's `PerformedWork` flag — set on a fiber whose render actually ran. */\nexport const PERFORMED_WORK = 0b1\n\nexport type RenderReason = 'mount' | 'state' | 'props' | 'parent'\n\nexport interface RenderReasonResult {\n  reason: RenderReason\n  changedProps?: string[]\n}\n\nexport function didPerformWork(fiber: MinimalFiber | null): boolean {\n  if (!fiber || typeof fiber.flags !== 'number') return false\n  return (fiber.flags & PERFORMED_WORK) !== 0\n}\n\n/**\n * Should the walk descend into this fiber's children when hunting for renders?\n *\n * React bubbles the `PerformedWork` bit of every descendant into a fiber's\n * `subtreeFlags`, and (unlike `flags`) resets it whenever the reconciler\n * re-clones the fiber. So a numeric `subtreeFlags` without the bit reliably\n * means \"no descendant rendered this commit\" — we can stop here and avoid\n * stale leaves whose own `flags` never got cleared.\n *\n * When `subtreeFlags` is absent (React < 18) we cannot prune safely, so we\n * descend and fall back to the full-tree walk.\n */\nexport function subtreeMightHaveRendered(fiber: MinimalFiber): boolean {\n  if (typeof fiber.subtreeFlags !== 'number') return true\n  return (fiber.subtreeFlags & PERFORMED_WORK) !== 0\n}\n\n/**\n * Walk up `.return` to the nearest *component* fiber, skipping host (DOM)\n * fibers. A component's immediate `.return` is usually a host fiber (the\n * `<div>` it's nested in), not its parent component — so to ask \"did my\n * parent component render?\" we have to climb past the host nodes first.\n */\nexport function nearestComponentAncestor(fiber: MinimalFiber): MinimalFiber | null {\n  let p = fiber.return\n  while (p) {\n    if (typeof p.type === 'function') return p\n    p = p.return\n  }\n  return null\n}\n\nfunction asObject(value: unknown): Record<string, unknown> {\n  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n}\n\n/** Shallow diff of two prop bags. Returns the keys whose values differ. */\nexport function changedPropKeys(prev: unknown, next: unknown): string[] {\n  if (prev === next) return []\n  const p = asObject(prev)\n  const n = asObject(next)\n  const keys = new Set([...Object.keys(p), ...Object.keys(n)])\n  const changed: string[] = []\n  for (const k of keys) {\n    if (p[k] !== n[k]) changed.push(k)\n  }\n  return changed\n}\n\n/**\n * Classify WHY a fiber that performed work this commit rendered.\n *\n * - `mount`  — first render (no previous fiber).\n * - `props`  — at least one prop changed since the previous render.\n * - `state`  — props are identical AND the parent did not render, so the\n *              update originated here (own state/force update). This is the\n *              root of a render cascade.\n * - `parent` — props are identical but the parent rendered, so this only\n *              re-rendered because of its parent. This is the avoidable\n *              \"wrap me in memo\" case the developer is hunting for.\n *\n * Assumes the caller only invokes this for fibers that actually performed\n * work (see `didPerformWork`).\n */\nexport function classifyRenderReason(fiber: MinimalFiber): RenderReasonResult {\n  if (!fiber.alternate) return { reason: 'mount' }\n  const changed = changedPropKeys(fiber.alternate.memoizedProps, fiber.memoizedProps)\n  if (changed.length > 0) return { reason: 'props', changedProps: changed }\n  if (didPerformWork(nearestComponentAncestor(fiber))) return { reason: 'parent' }\n  return { reason: 'state' }\n}\n","import type { Collector, Signal } from '@react-perfscope/core'\nimport { installDevToolsHook } from './devtools-hook'\nimport { fiberComponentName, walkChangedFibers } from './fiber-walker'\nimport { classifyRenderReason, didPerformWork, subtreeMightHaveRendered } from './render-reason'\nimport type { MinimalFiber } from './types'\n\nexport function createRenderCollector(): Collector {\n  let active = false\n  let emit: (signal: Signal) => void = () => {}\n  let unsubscribe: (() => void) | null = null\n  let commitId = 0\n\n  function onCommit(root: { current: MinimalFiber }) {\n    if (!active) return\n    const at = performance.now()\n    const id = commitId++\n    walkChangedFibers(\n      root.current,\n      (fiber, depth) => {\n        // Skip host (DOM) fibers — we only want function/class components in\n        // render reports.\n        if (typeof fiber.type === 'string') return\n        // Only report fibers that actually re-ran their render this commit.\n        // A bailed-out fiber (e.g. memo with equal props) keeps its place in\n        // the tree but did no work, so reporting it would be noise.\n        if (!didPerformWork(fiber)) return\n        const name = fiberComponentName(fiber)\n        if (!name) return\n        const duration = typeof fiber.actualDuration === 'number' ? fiber.actualDuration : 0\n        const { reason, changedProps } = classifyRenderReason(fiber)\n        emit({\n          kind: 'render',\n          at,\n          component: name,\n          reason,\n          duration,\n          commitId: id,\n          depth,\n          ...(changedProps ? { changedProps } : {}),\n        })\n      },\n      // Prune subtrees that did no work this commit. Without this, a leaf that\n      // mounted long ago keeps its stale PerformedWork flag and gets reported\n      // as a phantom render on every unrelated commit.\n      { descend: subtreeMightHaveRendered }\n    )\n  }\n\n  return {\n    kind: 'render',\n    activate(emitFn) {\n      emit = emitFn\n      active = true\n      if (unsubscribe) return\n      unsubscribe = installDevToolsHook(onCommit)\n    },\n    deactivate() {\n      active = false\n      // Keep the global hook listener attached — installDevToolsHook is\n      // idempotent and removing it on every deactivate would cost us the\n      // ability to re-attach cleanly under the test reset hooks. The\n      // `active` flag gates emission.\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@react-perfscope/react",
+  "version": "0.1.0",
+  "description": "React render-cascade collector for react-perfscope: per-commit render reasons with source attribution.",
+  "keywords": [
+    "react",
+    "performance",
+    "profiler",
+    "render",
+    "re-render",
+    "devtools"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@react-perfscope/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@testing-library/react": "^16.0.0"
+  },
+  "license": "MIT",
+  "author": "rayforvideos",
+  "homepage": "https://github.com/rayforvideos/react-perfscope#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayforvideos/react-perfscope.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/rayforvideos/react-perfscope/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/prepend-dts-refs.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}