@buoy-gg/highlight-updates 5.0.0 → 6.0.1

package/README.md

@@ -1,210 +1,61 @@
-# @buoy/highlight-updates
+# @buoy-gg/highlight-updates
 
-Control React DevTools' "Highlight updates when components render" feature directly from your React Native app.
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/highlight-updates?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/highlight-updates) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/highlight-updates?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/highlight-updates)
 
-## Overview
+**See exactly WHY your React Native components re-render — every render gets an overlay tagged with its cause: mount, state, props, or parent.**
 
-This tool intercepts the React DevTools agent's `drawTraceUpdates` event to provide programmatic control over component render highlighting. When DevTools has "Highlight updates when components render" enabled, this tool lets you toggle the highlighting on/off without navigating to DevTools settings.
+Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside your React Native app. Install it and it auto-appears in the floating menu from [`@buoy-gg/core`](https://www.npmjs.com/package/@buoy-gg/core).
 
-## Installation
+## Install
 
 ```bash
-npm install @buoy/highlight-updates
-# or
-yarn add @buoy/highlight-updates
-# or
-pnpm add @buoy/highlight-updates
+npm install @buoy-gg/core @buoy-gg/highlight-updates
 ```
 
-## Usage
-
-### With FloatingDevTools (Recommended)
-
-The easiest way to use this tool is with the FloatingDevTools menu:
-
-```tsx
-import { FloatingDevTools, autoDiscoverPresets } from '@buoy/core';
-
-// The highlight updates tool is automatically discovered if installed
-const apps = autoDiscoverPresets();
-
-function App() {
-  return (
-    <FloatingDevTools apps={apps}>
-      <YourApp />
-    </FloatingDevTools>
-  );
-}
-```
-
-Or explicitly add the preset:
+## Quick start
 
 ```tsx
-import { FloatingDevTools } from '@buoy/core';
-import { highlightUpdatesPreset } from '@buoy/highlight-updates';
+import { FloatingDevTools } from "@buoy-gg/core";
 
-function App() {
+export default function App() {
   return (
-    <FloatingDevTools apps={[highlightUpdatesPreset]}>
+    <>
       <YourApp />
-    </FloatingDevTools>
+      <FloatingDevTools />
+    </>
   );
 }
 ```
 
-### Standalone Controller
+That's it — the Render Highlighter appears in the floating menu. It's a standalone implementation: no React DevTools connection, no Chrome tab, no Flipper required.
 
-You can also use the controller directly without the FloatingDevTools menu:
+Prefer to drive it yourself?
 
 ```tsx
-import { HighlightUpdatesController } from '@buoy/highlight-updates';
-
-// Initialize when DevTools is connected
-HighlightUpdatesController.initialize();
+import { HighlightUpdatesController } from "@buoy-gg/highlight-updates";
 
-// Toggle highlights
 HighlightUpdatesController.toggle();
-
-// Enable/disable directly
-HighlightUpdatesController.enable();
-HighlightUpdatesController.disable();
-
-// Check state
-const isEnabled = HighlightUpdatesController.isEnabled();
-
-// Subscribe to state changes
-const unsubscribe = HighlightUpdatesController.subscribe((enabled) => {
-  console.log('Highlights enabled:', enabled);
-});
-
-// Cleanup when done
-HighlightUpdatesController.destroy();
 ```
 
-### Custom Configuration
-
-Create a customized version of the tool:
-
-```tsx
-import { createHighlightUpdatesTool } from '@buoy/highlight-updates';
-
-const myHighlightTool = createHighlightUpdatesTool({
-  name: 'RENDERS',
-  enabledColor: '#ec4899', // Pink when enabled
-  disabledColor: '#9ca3af', // Gray when disabled
-  autoInitialize: true, // Initialize automatically
-});
-```
+## What you get
 
-## Requirements
+- **Render overlays with the cause** — every render flashes a bounding box tagged mount / state change / prop change / parent re-render. No more guessing why a component updated.
+- **Hook value tracking** — when state caused the render, see the before → after values of the exact `useState` or `useReducer` that changed.
+- **Overlay mode** — lightweight real-time highlights while you interact with the app; perfect for spotting unnecessary re-renders.
+- **Modal mode** — full inspector with render history, filtering, and detailed per-render cause breakdowns for deep debugging sessions.
+- **Powers Bench's render capture** — with [`@buoy-gg/perf-monitor`](https://www.npmjs.com/package/@buoy-gg/perf-monitor) installed, benchmark recordings capture per-component render counts and durations.
+- **Filters out the framework noise** — you see your components, not `View`/`Text` internals.
 
-For this tool to work:
+## Desktop & AI
 
-1. **React DevTools must be connected** (Chrome DevTools or Flipper)
-2. **"Highlight updates when components render" must be enabled** in DevTools Profiler settings
-
-This tool then allows you to temporarily disable the highlighting without going back to DevTools settings.
-
-## How It Works
-
-The tool intercepts the DevTools agent's `drawTraceUpdates` event listener. When disabled, it simply doesn't forward the event to the original handler, effectively blocking the highlight rendering.
-
-```
-React DevTools Frontend (Chrome/Flipper)
-    | (sends drawTraceUpdates event)
-    v
-React DevTools Agent
-    | (event intercepted by HighlightUpdatesController)
-    v
-HighlightUpdatesController.controlledListener
-    | (if enabled, forwards to original)
-    v
-DebuggingOverlayRegistry (original listener)
-    | (processes component bounds)
-    v
-DebuggingOverlay (native component)
-    | (renders highlights on screen)
-```
+The same live session streams to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) (free, macOS/Windows/Linux) and to Claude Code or Cursor via the [Buoy MCP server](https://buoy.gg/buoy/latest/docs/mcp).
 
-## API Reference
+## Free vs Pro
 
-### `highlightUpdatesPreset`
+Every tool is free. [Pro](https://buoy.gg/pricing) unlocks production builds, the MCP server, and unlimited capture. Every weekend, Pro features unlock free for everyone.
 
-Pre-configured preset for use with FloatingDevTools.
-
-### `createHighlightUpdatesTool(options?)`
-
-Factory function to create a customized tool.
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | `"UPDATES"` | Display name in the menu |
-| `description` | `string` | `"Toggle component render highlights"` | Tool description |
-| `enabledColor` | `string` | `"#10b981"` | Icon color when enabled (green) |
-| `disabledColor` | `string` | `"#6b7280"` | Icon color when disabled (gray) |
-| `id` | `string` | `"highlight-updates"` | Unique tool identifier |
-| `autoInitialize` | `boolean` | `false` | Initialize automatically on load |
-
-### `HighlightUpdatesController`
-
-Standalone controller for programmatic use.
-
-| Method | Description |
-|--------|-------------|
-| `initialize()` | Initialize the controller. Returns `true` on success. |
-| `enable()` | Enable highlight rendering |
-| `disable()` | Disable highlight rendering |
-| `toggle()` | Toggle the enabled state |
-| `isEnabled()` | Get current enabled state |
-| `setEnabled(enabled)` | Set enabled state |
-| `isInitialized()` | Check if controller is initialized |
-| `subscribe(callback)` | Subscribe to state changes. Returns unsubscribe function. |
-| `destroy()` | Cleanup and restore original listener |
-
-## Console Access
-
-When in development mode, the controller is exposed globally:
-
-```javascript
-// In Chrome DevTools console
-window.__HIGHLIGHT_UPDATES_CONTROLLER__.toggle();
-window.__HIGHLIGHT_UPDATES_CONTROLLER__.isEnabled();
-```
-
-## Troubleshooting
-
-### Controller Not Initializing
-
-**Problem:** `initialize()` returns false
-
-**Solutions:**
-1. Check DevTools is connected: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__.reactDevtoolsAgent`
-2. Add initialization delay: Wait 1-2 seconds after app launch
-3. Ensure "Highlight updates" is enabled in DevTools first
-
-### Highlights Still Showing After Disable
-
-**Problem:** Highlights appear even when disabled
-
-**Solutions:**
-1. Verify controller is initialized: `HighlightUpdatesController.isInitialized()`
-2. Check enabled state: `HighlightUpdatesController.isEnabled()`
-3. Ensure listener was properly intercepted (check console logs)
-
-## Development
-
-### Building
-
-```bash
-pnpm build
-```
-
-### Type Checking
-
-```bash
-pnpm typecheck
-```
+---
 
-## License
+📚 [Full docs](https://buoy.gg/buoy/latest/docs/tools/highlight-updates) · [All Buoy tools](https://github.com/Buoy-gg/buoy)
 
-MIT
+Proprietary software. © Buoy LLC. [Terms](https://buoy.gg/terms)

package/lib/commonjs/highlight-updates/HighlightUpdatesOverlay.js

@@ -194,35 +194,31 @@ function HighlightUpdatesOverlay({
         height: rect.height,
         borderColor: rect.color
       }],
-      children: rect.count > 0 && (hasBadgePressHandler ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
-        onPress: () => handleBadgePress(rect.id),
+      children: rect.count > 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
         style: [styles.badge, {
           backgroundColor: rect.color
         }],
-        activeOpacity: 0.7,
+        nativeID: `__highlight_badge_${rect.id}__`,
+        pointerEvents: hasBadgePressHandler ? "auto" : "none",
         hitSlop: {
           top: 8,
           bottom: 8,
           left: 8,
           right: 8
         },
+        onStartShouldSetResponder: () => !!hasBadgePressHandler
+        // Fire on touch-DOWN: on churning screens the badge views are
+        // torn down and recreated between finger-down and finger-up
+        // (every highlight event rebuilds the boxes), which kills the
+        // responder before a release can fire. Grant fires immediately.
+        ,
+        onResponderGrant: () => handleBadgePress(rect.id),
         children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
           style: styles.badgeText,
           nativeID: `__highlight_text_${rect.id}__`,
           children: rect.count
         })
-      }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        style: [styles.badge, {
-          backgroundColor: rect.color
-        }],
-        nativeID: `__highlight_badge_${rect.id}__`,
-        pointerEvents: "none",
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-          style: styles.badgeText,
-          nativeID: `__highlight_text_${rect.id}__`,
-          children: rect.count
-        })
-      }))
+      })
     }, `highlight-${rect.id}`))]
   });
 }

package/lib/commonjs/highlight-updates/utils/CommitProfiler.js

@@ -0,0 +1,279 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CommitProfiler = void 0;
+var _devtoolsComponentNames = require("./devtoolsComponentNames");
+/**
+ * CommitProfiler — per-component render counts + durations across a capture
+ * window, React-DevTools-profiler style, without React DevTools attached.
+ *
+ * Wraps `__REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberRoot` (the callback React
+ * invokes after every commit) and, while a capture is active, walks the
+ * committed fiber tree collecting composite fibers that performed work this
+ * commit. Self duration follows React's convention: `actualDuration` minus the
+ * sum of direct children's `actualDuration` (profiling timers are enabled in
+ * dev builds, where Buoy runs).
+ *
+ * This is intentionally separate from the traceUpdates flow the highlight
+ * overlay uses — traceUpdates emits host views with no timing data.
+ *
+ * Consumed by perf-monitor benchmarks via the shared-ui render-capture
+ * registry (see the registration in this package's index.tsx).
+ */
+
+// React work tags for components that render user code.
+const FunctionComponent = 0;
+const ClassComponent = 1;
+const ForwardRef = 11;
+const MemoComponent = 14;
+const SimpleMemoComponent = 15;
+
+// React fiber flag: this fiber rendered (performed work) in the last commit.
+// Stable value 0b1 across React 16-19 (effectTag pre-18, flags after).
+const PerformedWork = 0b1;
+
+/** Overhead guardrail: stop walking a commit past this many visited fibers. */
+const MAX_FIBERS_PER_COMMIT = 10_000;
+
+/** Bound on distinct component names tracked; overflow still counts in totals. */
+const MAX_TRACKED_NAMES = 300;
+
+/** Components returned in the summary. */
+const TOP_COMPONENTS_CAP = 20;
+let hookInstalled = false;
+let active = false;
+let sawDurations = false;
+let totalCommits = 0;
+let totalRenders = 0;
+let totalRenderMs = 0;
+let buckets = new Map();
+function getHook() {
+  if (typeof global === "undefined") return null;
+  return global.__REACT_DEVTOOLS_GLOBAL_HOOK__ ?? null;
+}
+function getFlags(fiber) {
+  const f = fiber.flags ?? fiber.effectTag;
+  return typeof f === "number" ? f : 0;
+}
+function isCompositeTag(tag) {
+  return tag === FunctionComponent || tag === ClassComponent || tag === ForwardRef || tag === MemoComponent || tag === SimpleMemoComponent;
+}
+
+/** Resolve a composite fiber's display name (DevTools conventions). */
+function getComponentName(fiber) {
+  const type = fiber.type;
+  try {
+    switch (fiber.tag) {
+      case FunctionComponent:
+      case ClassComponent:
+        return type?.displayName || type?.name || "Anonymous";
+      case ForwardRef:
+        return type?.displayName || type?.render?.displayName || type?.render?.name || "ForwardRef";
+      case MemoComponent:
+      case SimpleMemoComponent:
+        {
+          const inner = type?.type ?? fiber.elementType?.type;
+          return type?.displayName || inner?.displayName || inner?.name || "Memo";
+        }
+      default:
+        return "Anonymous";
+    }
+  } catch {
+    return "Anonymous";
+  }
+}
+
+/**
+ * Self duration = own actualDuration minus direct children's. React's
+ * bubbleProperties adds every direct child's actualDuration into the parent,
+ * so subtracting them all back out is symmetric and exact.
+ */
+function computeSelfMs(fiber) {
+  const actual = fiber.actualDuration;
+  if (typeof actual !== "number") return null;
+  let self = actual;
+  for (let child = fiber.child; child != null; child = child.sibling) {
+    if (typeof child.actualDuration === "number") self -= child.actualDuration;
+  }
+  return self > 0 ? self : 0;
+}
+
+// React Native framework wrapper components. Their renders are real work
+// but the actionable signal lives on the OWNING component (a Touchable
+// re-rendering is already visible as its parent re-rendering), so they're
+// folded into the capture totals and kept OUT of the per-component list.
+// This is a report-level filter only — unlike isDevToolsComponentName it
+// must NOT prune subtrees (their children are user components).
+const FRAMEWORK_WRAPPER_NAMES = new Set(["View", "Text", "Image", "ImageBackground", "ScrollView", "FlatList", "SectionList", "SafeAreaView", "KeyboardAvoidingView", "StatusBar", "ActivityIndicator", "RefreshControl", "Modal", "Switch", "Pressable", "PlatformPressable", "TouchableOpacity", "TouchableHighlight", "TouchableWithoutFeedback", "TouchableNativeFeedback", "PressabilityDebugView", "AnimatedComponent", "Wrapper"]);
+const FRAMEWORK_WRAPPER_PREFIXES = ["Animated(",
+// Animated(View), Animated(Text), Animated(FlatList), …
+"Pressability", "Virtualized",
+// VirtualizedList + its context providers
+"CellRenderer"];
+function isFrameworkWrapperName(name) {
+  if (FRAMEWORK_WRAPPER_NAMES.has(name)) return true;
+  for (let i = 0; i < FRAMEWORK_WRAPPER_PREFIXES.length; i++) {
+    if (name.startsWith(FRAMEWORK_WRAPPER_PREFIXES[i])) return true;
+  }
+  return false;
+}
+function recordRender(fiber) {
+  const name = getComponentName(fiber);
+  const selfMs = computeSelfMs(fiber);
+  if (selfMs !== null) sawDurations = true;
+  const ms = selfMs ?? 0;
+  totalRenders += 1;
+  totalRenderMs += ms;
+
+  // Framework wrappers count toward totals but never surface as a row.
+  if (isFrameworkWrapperName(name)) return;
+  let bucket = buckets.get(name);
+  if (!bucket) {
+    // Bounded map: overflow renders still count toward the totals above.
+    if (buckets.size >= MAX_TRACKED_NAMES) return;
+    bucket = {
+      renders: 0,
+      totalSelfMs: 0,
+      maxSelfMs: 0
+    };
+    buckets.set(name, bucket);
+  }
+  bucket.renders += 1;
+  bucket.totalSelfMs += ms;
+  if (ms > bucket.maxSelfMs) bucket.maxSelfMs = ms;
+}
+
+/**
+ * Iterative walk (child → sibling → return) of the committed tree. Never
+ * throws upward — a broken walk must not break React's commit.
+ */
+function handleCommit(root) {
+  const start = root?.current;
+  if (!start) return;
+  const rendersBefore = totalRenders;
+  let visited = 0;
+  let fiber = start;
+  while (fiber != null) {
+    visited += 1;
+    if (visited > MAX_FIBERS_PER_COMMIT) break;
+    let skipSubtree = false;
+    const composite = isCompositeTag(fiber.tag);
+    if (composite) {
+      // Prune Buoy's own devtools UI wholesale.
+      if ((0, _devtoolsComponentNames.isDevToolsComponentName)(getComponentName(fiber))) {
+        skipSubtree = true;
+      } else if ((getFlags(fiber) & PerformedWork) !== 0) {
+        // PerformedWork is the only trustworthy "rendered this commit"
+        // signal — actualDuration is stale on bailed-out fibers.
+        recordRender(fiber);
+      }
+    }
+    if (!skipSubtree) {
+      // Prune subtrees with no work. subtreeFlags only exists on React 18+;
+      // when absent, always descend.
+      const subtreeFlags = fiber.subtreeFlags;
+      const noSubtreeWork = typeof subtreeFlags === "number" && (subtreeFlags & PerformedWork) === 0 && (getFlags(fiber) & PerformedWork) === 0;
+      if (!noSubtreeWork && fiber.child != null) {
+        fiber = fiber.child;
+        continue;
+      }
+    }
+
+    // No descend: advance to sibling, climbing up as needed.
+    while (fiber != null) {
+      if (fiber === start) return finalizeCommit(rendersBefore);
+      if (fiber.sibling != null) {
+        fiber = fiber.sibling;
+        break;
+      }
+      fiber = fiber.return;
+    }
+  }
+  finalizeCommit(rendersBefore);
+}
+function finalizeCommit(rendersBefore) {
+  if (totalRenders > rendersBefore) totalCommits += 1;
+}
+
+/**
+ * Install the onCommitFiberRoot wrapper once and never restore it — the
+ * `active` flag gates all work, and never restoring avoids clobber races if
+ * something else (e.g. React DevTools attaching mid-session) wraps the hook
+ * after us. The wrapper dies with the JS realm on reload.
+ */
+function ensureHookInstalled() {
+  if (hookInstalled) return true;
+  const hook = getHook();
+  if (!hook) return false;
+  const original = hook.onCommitFiberRoot;
+  hook.onCommitFiberRoot = function (rendererID, root, ...rest) {
+    if (active) {
+      try {
+        handleCommit(root);
+      } catch {
+        // Capture must never break React's commit path.
+      }
+    }
+    return typeof original === "function" ? original.call(hook, rendererID, root, ...rest) : undefined;
+  };
+  hookInstalled = true;
+  return true;
+}
+function isSupported() {
+  if (typeof __DEV__ !== "undefined" && !__DEV__) return false;
+  const hook = getHook();
+  return Boolean(hook && hook.renderers && hook.renderers.size > 0);
+}
+function isCapturing() {
+  return active;
+}
+
+/** Begin a capture window, discarding any previous unclaimed data. */
+function startCapture() {
+  if (!ensureHookInstalled()) return;
+  buckets = new Map();
+  sawDurations = false;
+  totalCommits = 0;
+  totalRenders = 0;
+  totalRenderMs = 0;
+  active = true;
+}
+
+/** End the window and return the aggregate (null if never started). */
+function stopCapture() {
+  if (!active && totalRenders === 0 && buckets.size === 0) return null;
+  active = false;
+  const topComponents = Array.from(buckets.entries()).sort((a, b) => {
+    const byMs = b[1].totalSelfMs - a[1].totalSelfMs;
+    return byMs !== 0 ? byMs : b[1].renders - a[1].renders;
+  }).slice(0, TOP_COMPONENTS_CAP).map(([name, b]) => ({
+    name,
+    renders: b.renders,
+    totalMs: round2(b.totalSelfMs),
+    maxMs: round2(b.maxSelfMs),
+    avgMs: b.renders > 0 ? round2(b.totalSelfMs / b.renders) : 0
+  }));
+  const summary = {
+    totalCommits,
+    totalRenders,
+    capturedDurations: sawDurations,
+    totalRenderMs: round2(totalRenderMs),
+    topComponents
+  };
+  buckets = new Map();
+  totalCommits = 0;
+  totalRenders = 0;
+  totalRenderMs = 0;
+  return summary;
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+const CommitProfiler = exports.CommitProfiler = {
+  isSupported,
+  isCapturing,
+  startCapture,
+  stopCapture
+};