react-debug-updates 0.1.6 → 0.1.9

package/README.md

@@ -1,17 +1,23 @@
 # react-debug-updates
 
-Visual debugging overlays and console logging for React re-renders. See exactly which components re-render, how often, how long they take, and *why* they re-rendered — all without modifying your components.
+See exactly which React components re-render, how often, how long they take, and *why* — all without modifying your components.
 
 ![highlight overlays](https://img.shields.io/badge/overlays-visual%20highlights-61dafb) ![zero config](https://img.shields.io/badge/setup-zero%20config-green)
 
 <img src="demo.gif" alt="demo" width="852" height="476" />
 
+## Why?
+
+I was working on an Electron app and spent hours trying to get the official React DevTools to work with it. DevTools' Electron integration is fragile, poorly documented, and breaks between versions. I just needed to see which components were re-rendering so I could fix performance issues.
+
+So I wrote this — a plug-and-play one-liner that gives you visual highlight overlays and console logging for React re-renders. No browser extension, no Electron hacks, no configuration. Works in any React web environment — browsers, Electron, iframes.
+
 ## How it works
 
-Hooks into `__REACT_DEVTOOLS_GLOBAL_HOOK__` to intercept every React commit. Works in any React web environment — browsers, Electron, iframes — no React DevTools extension required. No wrappers, no HOCs, no code changes — just call `attachRenderLogger()` and you get:
+Hooks into `__REACT_DEVTOOLS_GLOBAL_HOOK__` to intercept every React commit. Uses the same fiber tree diffing approach as React DevTools to detect which components actually re-rendered. No React DevTools extension required. No wrappers, no HOCs, no code changes — just call `monitor()` and you get:
 
-- **Console logging** — grouped, color-coded re-render reports with component tree paths and render durations
 - **Visual overlays** — highlight boxes on re-rendered DOM nodes with a heat-map color scale (blue → red as render count increases)
+- **Console logging** — grouped, color-coded re-render reports with component tree paths and render durations
 - **Cause detection** — pinpoint *which* `useState`, `useReducer`, `useSyncExternalStore`, or `useContext` hook triggered each re-render, with previous→next values
 
 ## Install
@@ -26,30 +32,38 @@ pnpm add react-debug-updates
 
 ## Quick start
 
-Import and call `attachRenderLogger` **before** React renders anything — ideally at the very top of your entry point. This ensures the hook is in place before the first commit.
+Import and call `monitor` **before** React renders anything — ideally at the very top of your entry point. This ensures the hook is in place before the first commit.
 
 ```ts
-import { attachRenderLogger } from "react-debug-updates";
+import { monitor } from "react-debug-updates";
 
-// Call before React renders — top of your entry point
-const logger = attachRenderLogger({
-  highlight: true,
-  showCauses: true,
-});
+// One-liner — overlays + console logging out of the box
+const updates = monitor();
 
 // Later, to clean up:
-logger?.disconnect();
+updates?.stop();
 ```
 
 ### Dev-only guard
 
 ```ts
 if (process.env.NODE_ENV === "development") {
-  const { attachRenderLogger } = await import("react-debug-updates");
-  attachRenderLogger({ highlight: true, showCauses: true });
+  const { monitor } = await import("react-debug-updates");
+  monitor();
 }
 ```
 
+### With options
+
+```ts
+monitor({
+  showCauses: true,
+  opacity: 0.5,
+  showLabels: false,
+  silent: true, // overlays only, no console output
+});
+```
+
 ## Requirements
 
 - A **React dev build** (which automatically creates `__REACT_DEVTOOLS_GLOBAL_HOOK__`) — no browser extension needed
@@ -57,36 +71,31 @@ if (process.env.NODE_ENV === "development") {
 
 ## API
 
-### `attachRenderLogger(options?): RenderLogger | null`
+### `monitor(options?): UpdateMonitor | null`
 
-Returns a `RenderLogger` handle, or `null` if the DevTools hook is not available.
+Returns an `UpdateMonitor` handle, or `null` if the DevTools hook is not available.
 
 #### Options
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `silent` | `boolean` | `false` | Suppress console output |
 | `mode` | `"self-triggered" \| "all"` | `"self-triggered"` | `"self-triggered"` tracks only components whose own state changed. `"all"` includes children swept by parent updates |
-| `bufferSize` | `number` | `500` | Max entries kept in the ring buffer |
-| `filter` | `(entry: RenderEntry) => boolean` | — | Return `false` to skip an entry |
-| `highlight` | `boolean \| HighlightOptions` | `false` | Enable visual overlay highlights |
 | `showCauses` | `boolean` | `false` | Detect and display why each component re-rendered |
-
-#### `HighlightOptions`
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `flushInterval` | `number` | `250` | Milliseconds between overlay flush cycles |
-| `animationDuration` | `number` | `1200` | Overlay fade-out animation duration (ms) |
+| `silent` | `boolean` | `false` | Suppress console output |
+| `overlay` | `boolean` | `true` | Enable visual highlight overlays |
 | `showLabels` | `boolean` | `true` | Show text labels (name, count, duration, cause) above overlays |
 | `opacity` | `number` | `0.3` | Peak opacity of overlay highlights (0–1) |
+| `flushInterval` | `number` | `250` | Milliseconds between overlay flush cycles |
+| `animationDuration` | `number` | `1200` | Overlay fade-out animation duration (ms) |
+| `bufferSize` | `number` | `500` | Max entries kept in the ring buffer |
+| `filter` | `(entry: RenderEntry) => boolean` | — | Return `false` to skip an entry |
 
-### `RenderLogger`
+### `UpdateMonitor`
 
 | Property | Type | Description |
 | --- | --- | --- |
 | `entries` | `RenderEntry[]` | Ring buffer of recorded re-render entries |
-| `disconnect` | `() => void` | Unhook from React and remove all overlays |
+| `stop` | `() => void` | Unhook from React and remove all overlays |
 
 ### `RenderEntry`
 

package/dist/fiber.d.ts

@@ -1,4 +1,4 @@
-import type { Fiber, PendingEntry } from "./types.js";
+import type { Fiber, DetectedRender } from "./types.js";
 export declare const FiberTag: {
     readonly FunctionComponent: 0;
     readonly ClassComponent: 1;
@@ -10,4 +10,4 @@ export declare const FiberTag: {
 export declare function getComponentName(fiber: Fiber): string | null;
 export declare function findNearestDOMNode(fiber: Fiber): HTMLElement | null;
 export declare function getFiberPath(fiber: Fiber, maxDepth?: number): string;
-export declare function collectPending(root: Fiber, mode: "self-triggered" | "all", trackCauses: boolean): PendingEntry[];
+export declare function detectRenders(root: Fiber, mode: "self-triggered" | "all"): DetectedRender[];

package/dist/format.d.ts

@@ -1,6 +1,8 @@
-import type { UpdateCause } from "./types.js";
+import type { HighlightEntry, UpdateCause } from "./types.js";
 export declare function formatValue(value: unknown, maxLength?: number): string;
 /** Compact summary for overlay labels. */
 export declare function formatCausesShort(causes: UpdateCause[]): string;
 /** Detailed lines for console output. */
 export declare function formatCausesConsole(causes: UpdateCause[]): string[];
+/** Log re-renders as a collapsed console group. */
+export declare function logRerendersToConsole(entries: HighlightEntry[], showCauses: boolean): void;

package/dist/highlights.d.ts

@@ -0,0 +1,5 @@
+import type { OverlayConfig, HighlightEntry } from "./types.js";
+export declare function createHighlighter(config: OverlayConfig): {
+    push: (entry: HighlightEntry) => void;
+    dispose: () => void;
+};

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { attachRenderLogger } from "./logger.js";
-export type { LoggerOptions, RenderLogger, RenderEntry, HighlightOptions, UpdateCause, } from "./types.js";
+export { monitor } from "./monitor.js";
+export type { MonitorOptions, UpdateMonitor, RenderEntry, UpdateCause, } from "./types.js";

package/dist/monitor.d.ts

@@ -0,0 +1,14 @@
+import type { MonitorOptions, UpdateMonitor } from "./types.js";
+/**
+ * Start monitoring React re-renders.
+ *
+ * Hooks into `__REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberRoot` to intercept
+ * every React commit. Records re-render entries, optionally logs them to the
+ * console, and optionally shows visual highlight overlays on re-rendered DOM nodes.
+ *
+ * Call this **before** React renders anything — ideally at the very top of
+ * your entry point.
+ *
+ * Returns an `UpdateMonitor` handle, or `null` if the DevTools hook is not found.
+ */
+export declare function monitor(options?: MonitorOptions): UpdateMonitor | null;

package/dist/react-debug-updates.cjs

@@ -1,64 +1,5 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const STATE_HOOKS = /* @__PURE__ */ new Set([
-  "useState",
-  "useReducer",
-  "useSyncExternalStore"
-]);
-const HOOKS_WITHOUT_NODE = /* @__PURE__ */ new Set(["useContext"]);
-function detectCauses(fiber) {
-  const alternate = fiber.alternate;
-  if (!alternate) return [];
-  const causes = [];
-  if (fiber.memoizedProps !== alternate.memoizedProps) {
-    causes.push({ kind: "props" });
-  }
-  if (fiber.tag === FiberTag.ClassComponent) {
-    if (fiber.memoizedState !== alternate.memoizedState) {
-      causes.push({ kind: "class-state" });
-    }
-    return causes;
-  }
-  const hookTypes = fiber._debugHookTypes;
-  if (!hookTypes) {
-    if (fiber.memoizedState !== alternate.memoizedState) {
-      causes.push({ kind: "unknown" });
-    }
-    return causes;
-  }
-  let currentNode = fiber.memoizedState;
-  let previousNode = alternate.memoizedState;
-  let hasContextHook = false;
-  let anyStateHookChanged = false;
-  for (let i = 0; i < hookTypes.length; i++) {
-    const type = hookTypes[i];
-    if (HOOKS_WITHOUT_NODE.has(type)) {
-      if (type === "useContext") hasContextHook = true;
-      continue;
-    }
-    if (STATE_HOOKS.has(type) && currentNode && previousNode) {
-      if (!Object.is(currentNode.memoizedState, previousNode.memoizedState)) {
-        anyStateHookChanged = true;
-        causes.push({
-          kind: "hook",
-          hookIndex: i,
-          hookType: type,
-          previousValue: previousNode.memoizedState,
-          nextValue: currentNode.memoizedState
-        });
-      }
-    }
-    currentNode = (currentNode == null ? void 0 : currentNode.next) ?? null;
-    previousNode = (previousNode == null ? void 0 : previousNode.next) ?? null;
-  }
-  if (hasContextHook && !anyStateHookChanged && fiber.memoizedProps === alternate.memoizedProps) {
-    causes.push({ kind: "hook", hookType: "useContext" });
-  }
-  if (causes.length === 0 && fiber.memoizedProps === alternate.memoizedProps) {
-    causes.push({ kind: "unknown" });
-  }
-  return causes;
-}
 const FiberTag = {
   FunctionComponent: 0,
   ClassComponent: 1,
@@ -113,25 +54,15 @@ function isSelfTriggered(fiber) {
 function didFiberRender(nextFiber) {
   return (nextFiber.flags & PerformedWork) === PerformedWork;
 }
-function collectPending(root, mode, trackCauses) {
-  const entries = [];
+function detectRenders(root, mode) {
+  const results = [];
   const selfTriggeredOnly = mode === "self-triggered";
   const previousRoot = root.alternate;
-  if (!previousRoot) return entries;
+  if (!previousRoot) return results;
   function walk(nextFiber, previousFiber, depth) {
     if (COMPONENT_TAGS.has(nextFiber.tag) && previousFiber !== null && previousFiber !== nextFiber && // same object → bailed-out subtree
     didFiberRender(nextFiber) && (!selfTriggeredOnly || isSelfTriggered(nextFiber))) {
-      const name = getComponentName(nextFiber);
-      if (name) {
-        entries.push({
-          component: name,
-          path: getFiberPath(nextFiber),
-          duration: nextFiber.actualDuration ?? 0,
-          depth,
-          domNode: findNearestDOMNode(nextFiber),
-          causes: trackCauses ? detectCauses(nextFiber) : []
-        });
-      }
+      results.push({ fiber: nextFiber, depth });
     }
     let nextChild = nextFiber.child;
     let previousChildAtSameIndex = (previousFiber == null ? void 0 : previousFiber.child) ?? null;
@@ -148,7 +79,66 @@ function collectPending(root, mode, trackCauses) {
     }
   }
   walk(root, previousRoot, 0);
-  return entries;
+  return results;
+}
+const STATE_HOOKS = /* @__PURE__ */ new Set([
+  "useState",
+  "useReducer",
+  "useSyncExternalStore"
+]);
+const HOOKS_WITHOUT_NODE = /* @__PURE__ */ new Set(["useContext"]);
+function detectCauses(fiber) {
+  const alternate = fiber.alternate;
+  if (!alternate) return [];
+  const causes = [];
+  if (fiber.memoizedProps !== alternate.memoizedProps) {
+    causes.push({ kind: "props" });
+  }
+  if (fiber.tag === FiberTag.ClassComponent) {
+    if (fiber.memoizedState !== alternate.memoizedState) {
+      causes.push({ kind: "class-state" });
+    }
+    return causes;
+  }
+  const hookTypes = fiber._debugHookTypes;
+  if (!hookTypes) {
+    if (fiber.memoizedState !== alternate.memoizedState) {
+      causes.push({ kind: "unknown" });
+    }
+    return causes;
+  }
+  let currentNode = fiber.memoizedState;
+  let previousNode = alternate.memoizedState;
+  let hasContextHook = false;
+  let anyStateHookChanged = false;
+  for (let i = 0; i < hookTypes.length; i++) {
+    const type = hookTypes[i];
+    if (HOOKS_WITHOUT_NODE.has(type)) {
+      if (type === "useContext") hasContextHook = true;
+      continue;
+    }
+    if (STATE_HOOKS.has(type) && currentNode && previousNode) {
+      if (!Object.is(currentNode.memoizedState, previousNode.memoizedState)) {
+        anyStateHookChanged = true;
+        causes.push({
+          kind: "hook",
+          hookIndex: i,
+          hookType: type,
+          previousValue: previousNode.memoizedState,
+          nextValue: currentNode.memoizedState
+        });
+      }
+    }
+    currentNode = (currentNode == null ? void 0 : currentNode.next) ?? null;
+    previousNode = (previousNode == null ? void 0 : previousNode.next) ?? null;
+  }
+  if (hasContextHook && !anyStateHookChanged && fiber.memoizedProps === alternate.memoizedProps) {
+    causes.push({ kind: "hook", hookType: "useContext" });
+  }
+  if (causes.length === 0 && fiber.memoizedProps === alternate.memoizedProps) {
+    causes.push({ kind: "unknown" });
+  }
+  return causes;
 }
 function formatValue(value, maxLength = 50) {
   var _a;
@@ -212,6 +202,29 @@ function formatCausesConsole(causes) {
   }
   return lines;
 }
+function logRerendersToConsole(entries, showCauses) {
+  if (entries.length === 0) return;
+  console.groupCollapsed(
+    `%c⚛ ${entries.length} re-render${entries.length > 1 ? "s" : ""}`,
+    "color: #61dafb; font-weight: bold"
+  );
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const durationText = entry.duration > 0 ? ` (${entry.duration.toFixed(2)}ms)` : "";
+    console.log(
+      `%c${entry.component}%c ${entry.path}${durationText}`,
+      "color: #e8e82e; font-weight: bold",
+      "color: #888"
+    );
+    if (showCauses && entry.causes.length > 0) {
+      const lines = formatCausesConsole(entry.causes);
+      for (const line of lines) {
+        console.log(`%c${line}`, "color: #aaa");
+      }
+    }
+  }
+  console.groupEnd();
+}
 const ANIMATION_NAME = "__rdu-fade";
 const injectedWindows = /* @__PURE__ */ new WeakSet();
 function ensureStylesheet(win) {
@@ -309,13 +322,7 @@ function heatColor(count, alpha) {
   const lightness = 55 - normalizedCount * 10;
   return `hsla(${hue}, ${saturation}%, ${lightness}%, ${alpha})`;
 }
-const HIGHLIGHT_DEFAULTS = {
-  flushInterval: 250,
-  animationDuration: 1200,
-  showLabels: true,
-  opacity: 0.3
-};
-function createBatcher(options) {
+function createHighlighter(config) {
   let pending = [];
   let timer = null;
   function flush() {
@@ -368,10 +375,10 @@ function createBatcher(options) {
       style.height = `${rect.height}px`;
       style.backgroundColor = fillColor;
       style.border = `1.5px solid ${borderColor}`;
-      style.setProperty("--rdu-opacity", String(options.opacity));
-      style.animation = `${OVERLAY_ANIMATION_NAME} ${options.animationDuration}ms ease-out forwards`;
+      style.setProperty("--rdu-opacity", String(config.opacity));
+      style.animation = `${OVERLAY_ANIMATION_NAME} ${config.animationDuration}ms ease-out forwards`;
       const label = element.firstElementChild;
-      if (options.showLabels) {
+      if (config.showLabels) {
         const countText = coalesced.count > 1 ? ` ×${coalesced.count}` : "";
         const durationText = coalesced.totalDuration > 0 ? ` ${coalesced.totalDuration.toFixed(1)}ms` : "";
         const causeText = coalesced.causeSummary ? ` (${coalesced.causeSummary})` : "";
@@ -386,7 +393,7 @@ function createBatcher(options) {
   function push(entry) {
     pending.push(entry);
     if (!timer) {
-      timer = setInterval(flush, options.flushInterval);
+      timer = setInterval(flush, config.flushInterval);
     }
   }
   function dispose() {
@@ -398,14 +405,18 @@ function createBatcher(options) {
   }
   return { push, dispose };
 }
-function attachRenderLogger(options = {}) {
+function monitor(options = {}) {
   const {
     silent = false,
     bufferSize = 500,
     filter,
-    highlight = false,
+    overlay = true,
     mode = "self-triggered",
-    showCauses = false
+    showCauses = false,
+    flushInterval = 250,
+    animationDuration = 1200,
+    showLabels = true,
+    opacity = 0.3
   } = options;
   const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
   if (!hook) {
@@ -414,56 +425,46 @@ function attachRenderLogger(options = {}) {
     );
     return null;
   }
-  const highlightOptions = highlight ? {
-    ...HIGHLIGHT_DEFAULTS,
-    ...typeof highlight === "object" ? highlight : {}
-  } : null;
-  const batcher = highlightOptions ? createBatcher(highlightOptions) : null;
+  const highlighter = overlay ? createHighlighter({ flushInterval, animationDuration, showLabels, opacity }) : null;
   const entries = [];
   const previousOnCommit = hook.onCommitFiberRoot.bind(hook);
   hook.onCommitFiberRoot = (rendererID, root, priorityLevel) => {
     previousOnCommit(rendererID, root, priorityLevel);
-    const pendingEntries = collectPending(root.current, mode, showCauses);
-    for (let i = 0; i < pendingEntries.length; i++) {
-      const pendingEntry = pendingEntries[i];
-      const entry = {
-        component: pendingEntry.component,
-        path: pendingEntry.path,
-        duration: pendingEntry.duration,
+    const detectedRenders = detectRenders(root.current, mode);
+    if (detectedRenders.length === 0) return;
+    const highlightEntries = [];
+    for (let i = 0; i < detectedRenders.length; i++) {
+      const { fiber, depth } = detectedRenders[i];
+      const name = getComponentName(fiber);
+      if (!name) continue;
+      const highlightEntry = {
+        component: name,
+        path: getFiberPath(fiber),
+        duration: fiber.actualDuration ?? 0,
+        depth,
+        domNode: findNearestDOMNode(fiber),
+        causes: showCauses ? detectCauses(fiber) : []
+      };
+      const renderEntry = {
+        component: highlightEntry.component,
+        path: highlightEntry.path,
+        duration: highlightEntry.duration,
         timestamp: performance.now(),
-        causes: pendingEntry.causes
+        causes: highlightEntry.causes
       };
-      if (filter && !filter(entry)) continue;
+      if (filter && !filter(renderEntry)) continue;
       if (entries.length >= bufferSize) entries.shift();
-      entries.push(entry);
-      batcher == null ? void 0 : batcher.push(pendingEntry);
+      entries.push(renderEntry);
+      highlightEntries.push(highlightEntry);
+      highlighter == null ? void 0 : highlighter.push(highlightEntry);
     }
-    if (!silent && pendingEntries.length > 0) {
-      console.groupCollapsed(
-        `%c⚛ ${pendingEntries.length} re-render${pendingEntries.length > 1 ? "s" : ""}`,
-        "color: #61dafb; font-weight: bold"
-      );
-      for (let i = 0; i < pendingEntries.length; i++) {
-        const pendingEntry = pendingEntries[i];
-        const durationText = pendingEntry.duration > 0 ? ` (${pendingEntry.duration.toFixed(2)}ms)` : "";
-        console.log(
-          `%c${pendingEntry.component}%c ${pendingEntry.path}${durationText}`,
-          "color: #e8e82e; font-weight: bold",
-          "color: #888"
-        );
-        if (showCauses && pendingEntry.causes.length > 0) {
-          const lines = formatCausesConsole(pendingEntry.causes);
-          for (const line of lines) {
-            console.log(`%c${line}`, "color: #aaa");
-          }
-        }
-      }
-      console.groupEnd();
+    if (!silent) {
+      logRerendersToConsole(highlightEntries, showCauses);
     }
   };
-  const disconnect = () => {
+  const stop = () => {
     hook.onCommitFiberRoot = previousOnCommit;
-    batcher == null ? void 0 : batcher.dispose();
+    highlighter == null ? void 0 : highlighter.dispose();
     disposeAllOverlays();
   };
   if (!silent) {
@@ -472,7 +473,7 @@ function attachRenderLogger(options = {}) {
       "color: #61dafb; font-weight: bold"
     );
   }
-  return { entries, disconnect };
+  return { entries, stop };
 }
-exports.attachRenderLogger = attachRenderLogger;
+exports.monitor = monitor;
 //# sourceMappingURL=react-debug-updates.cjs.map