@buoy-gg/highlight-updates 7.0.35 → 7.0.38

package/README.md

@@ -2,9 +2,9 @@
 
 [![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)
 
-**See exactly WHY your React Native components re-render — every render gets an overlay tagged with its cause: mount, state, props, or parent.**
+Highlight observed React component updates in development builds and inspect the available render details.
 
-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).
+Part of [Buoy](https://github.com/Buoy-gg/buoy). Install the package, complete account setup, and follow the integration steps below.
 
 ## Install
 
@@ -12,6 +12,24 @@ Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside yo
 npm install @buoy-gg/core @buoy-gg/highlight-updates
 ```
 
+## Before you start
+
+Use a development build with `@buoy-gg/core` and a Free or Pro Buoy account key. From your app’s directory, sign in:
+
+```bash
+npx --package=@buoy-gg/core buoy login
+```
+
+For Expo, initialize Buoy before rendering the menu:
+
+```tsx
+import { Buoy } from "@buoy-gg/core";
+
+Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
+```
+
+The login command writes the Expo key to `.env.local`. For React Native CLI, pass the key from your app’s environment configuration; React Native does not load `.env.local` automatically. Mount `FloatingDevTools` inside the same providers as your screens and restart the development server after installation. The [Quick Start](https://buoy.gg/buoy/latest/docs/quick-start) shows the complete root component setup.
+
 ## Quick start
 
 ```tsx
@@ -37,9 +55,13 @@ import { HighlightUpdatesController } from "@buoy-gg/highlight-updates";
 HighlightUpdatesController.toggle();
 ```
 
+## Check the integration
+
+In a development build, open the tool and update a visible component’s state. Confirm that an update is highlighted. Capture depends on React’s development hooks; Pro does not make those hooks available in a release build.
+
 ## What you get
 
-- **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.
+- **Render overlays with the cause** — observed updates flash a bounding box with the available mount, state, props, or parent-update classification.
 - **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.
@@ -48,11 +70,11 @@ HighlightUpdatesController.toggle();
 
 ## Desktop & AI
 
-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).
+To connect a React Native app to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) or MCP, install `@buoy-gg/external-sync` and follow the [Desktop connection guide](https://buoy.gg/buoy/latest/docs/desktop). Sign in to Desktop separately. [MCP setup](https://buoy.gg/buoy/latest/docs/mcp) also requires a process account and Pro access. Available remote actions depend on the tool and app integration.
 
-## Free vs Pro
+## Account and plan requirements
 
-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 anyone holding a key — including a free one (`npx buoy login`).
+Use a Free or Pro Buoy account. History limits and paid features vary by tool; see [pricing](https://buoy.gg/pricing). Production access requires Pro where supported. Development-only hooks and actions remain unavailable in release builds.
 
 ---
 

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

@@ -1,281 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.HighlightUpdatesOverlay = HighlightUpdatesOverlay;
-exports.default = void 0;
-var _react = _interopRequireWildcard(require("react"));
-var _reactNative = require("react-native");
-var _sharedUi = require("@buoy-gg/shared-ui");
-var _HighlightUpdatesController = _interopRequireDefault(require("./utils/HighlightUpdatesController"));
-var _PerformanceLogger = require("./utils/PerformanceLogger");
-var _RenderTracker = require("./utils/RenderTracker");
-var _jsxRuntime = require("react/jsx-runtime");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-/**
- * HighlightUpdatesOverlay
- *
- * Renders colored highlight rectangles for components that have updated.
- * Uses View-based rendering (similar to debug-borders) instead of the
- * native DebuggingOverlay component for better compatibility.
- */
-
-// Declare performance API available in React Native's JavaScript environment
-
-// How long highlights stay visible (ms)
-const HIGHLIGHT_DURATION = 1000;
-function HighlightUpdatesOverlay({
-  onBadgePress
-} = {}) {
-  const [highlights, setHighlights] = (0, _react.useState)([]);
-  const [isFrozen, setIsFrozen] = (0, _react.useState)(() => _HighlightUpdatesController.default.getFrozen());
-  const [spotlightTag, setSpotlightTag] = (0, _react.useState)(null);
-  const cleanupTimerRef = (0, _react.useRef)(null);
-  const renderStartTimeRef = (0, _react.useRef)(0);
-  const highlightCountRef = (0, _react.useRef)(0);
-  const frozenRef = (0, _react.useRef)(isFrozen);
-
-  // Keep ref in sync with state for use in interval callback
-  frozenRef.current = isFrozen;
-
-  // Track render start time
-  if (_PerformanceLogger.PerformanceLogger.isEnabled()) {
-    renderStartTimeRef.current = performance.now();
-    highlightCountRef.current = highlights.length;
-  }
-
-  // Measure render completion time using useLayoutEffect (runs after DOM mutations)
-  (0, _react.useLayoutEffect)(() => {
-    if (_PerformanceLogger.PerformanceLogger.isEnabled() && renderStartTimeRef.current > 0 && highlightCountRef.current > 0) {
-      const renderTime = performance.now() - renderStartTimeRef.current;
-      // Mark end-to-end timing (for benchmark recording only - no console logs)
-      (0, _PerformanceLogger.markOverlayRendered)(highlightCountRef.current, renderTime);
-    }
-  });
-
-  // Subscribe to freeze state changes
-  (0, _react.useEffect)(() => {
-    const unsubscribe = _HighlightUpdatesController.default.subscribeToFreeze(frozen => {
-      setIsFrozen(frozen);
-    });
-    return unsubscribe;
-  }, []);
-
-  // Subscribe to filter changes - refresh frozen highlights when filters change
-  (0, _react.useEffect)(() => {
-    const unsubscribe = _RenderTracker.RenderTracker.subscribeToFilters(() => {
-      // When filters change, filter out highlights that no longer match
-      setHighlights(prev => {
-        return prev.filter(highlight => {
-          // Look up the render by nativeTag
-          const render = _RenderTracker.RenderTracker.getRender(String(highlight.id));
-          if (!render) {
-            // If render not found, keep the highlight (it might be from a different source)
-            return true;
-          }
-          // Check if the render should still be shown based on new filters
-          return _RenderTracker.RenderTracker.shouldShowRender(render);
-        });
-      });
-    });
-    return unsubscribe;
-  }, []);
-
-  // Subscribe to spotlight changes - show which component is being viewed in detail
-  (0, _react.useEffect)(() => {
-    _HighlightUpdatesController.default.setSpotlightCallback(tag => {
-      setSpotlightTag(tag);
-    });
-    return () => {
-      _HighlightUpdatesController.default.setSpotlightCallback(null);
-    };
-  }, []);
-
-  // Callback to add new highlights
-  const addHighlights = (0, _react.useCallback)(newRects => {
-    const now = Date.now();
-    const timestampedRects = newRects.map(rect => ({
-      ...rect,
-      timestamp: now
-    }));
-    setHighlights(prev => {
-      // Merge new highlights, replacing any with same id
-      const updated = [...prev];
-      for (const newRect of timestampedRects) {
-        const existingIndex = updated.findIndex(r => r.id === newRect.id);
-        if (existingIndex >= 0) {
-          updated[existingIndex] = newRect;
-        } else {
-          updated.push(newRect);
-        }
-      }
-      return updated;
-    });
-  }, []);
-
-  // Register the callback with the controller
-  (0, _react.useEffect)(() => {
-    _HighlightUpdatesController.default.setHighlightCallback(addHighlights);
-
-    // Cleanup timer to remove old highlights
-    // When frozen, skip cleanup to keep highlights visible indefinitely
-    cleanupTimerRef.current = setInterval(() => {
-      // Check frozen state via ref (doesn't cause re-subscription)
-      if (frozenRef.current) {
-        return; // Skip cleanup when frozen
-      }
-      const now = Date.now();
-      setHighlights(prev => prev.filter(rect => now - rect.timestamp < HIGHLIGHT_DURATION));
-    }, 50);
-    return () => {
-      _HighlightUpdatesController.default.setHighlightCallback(null);
-      if (cleanupTimerRef.current) {
-        clearInterval(cleanupTimerRef.current);
-      }
-    };
-  }, [addHighlights]);
-
-  // Check if badge press handling is enabled (via props or controller)
-  const hasBadgePressHandler = onBadgePress || _HighlightUpdatesController.default.getBadgePressCallback();
-
-  // Handle badge press - navigate to detail view for this component
-  const handleBadgePress = (0, _react.useCallback)(nativeTag => {
-    // First try the prop callback
-    if (onBadgePress) {
-      onBadgePress(nativeTag);
-    } else {
-      // Fall back to controller callback
-      _HighlightUpdatesController.default.handleBadgePress(nativeTag);
-    }
-  }, [onBadgePress]);
-
-  // Get spotlight render info if we have a spotlight active
-  const spotlightRender = spotlightTag ? _RenderTracker.RenderTracker.getRender(String(spotlightTag)) : null;
-
-  // Render nothing if no highlights and no spotlight
-  if (highlights.length === 0 && !spotlightRender?.measurements) {
-    return null;
-  }
-  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-    style: styles.overlay,
-    pointerEvents: "box-none",
-    nativeID: "highlight-updates-overlay",
-    children: [spotlightRender?.measurements && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        pointerEvents: "none",
-        nativeID: "__spotlight_highlight__",
-        style: [styles.spotlightHighlight, {
-          // Offset by border width so border renders outside the component bounds
-          left: spotlightRender.measurements.x - 3,
-          top: spotlightRender.measurements.y - 3,
-          width: spotlightRender.measurements.width + 6,
-          height: spotlightRender.measurements.height + 6
-        }]
-      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        pointerEvents: "none",
-        style: [styles.spotlightLabel, {
-          left: spotlightRender.measurements.x,
-          top: spotlightRender.measurements.y + spotlightRender.measurements.height + 4
-        }],
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-          style: styles.spotlightLabelText,
-          children: spotlightRender.componentName || spotlightRender.displayName || spotlightRender.viewType
-        })
-      })]
-    }), highlights.map(rect => /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-      pointerEvents: "box-none",
-      nativeID: `__highlight_rect_${rect.id}__`,
-      style: [styles.highlight, {
-        left: rect.x,
-        top: rect.y,
-        width: rect.width,
-        height: rect.height,
-        borderColor: rect.color
-      }],
-      children: rect.count > 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        style: [styles.badge, {
-          backgroundColor: rect.color
-        }],
-        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
-        })
-      })
-    }, `highlight-${rect.id}`))]
-  });
-}
-const styles = _reactNative.StyleSheet.create({
-  overlay: {
-    position: "absolute",
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-    zIndex: 999999,
-    elevation: 999999,
-    borderWidth: 0
-  },
-  highlight: {
-    position: "absolute",
-    borderWidth: 2,
-    borderStyle: "solid",
-    backgroundColor: "transparent"
-  },
-  badge: {
-    position: "absolute",
-    top: 0,
-    right: 0,
-    height: 14,
-    borderRadius: 0,
-    justifyContent: "center",
-    alignItems: "center",
-    paddingHorizontal: 2
-  },
-  badgeText: {
-    color: "#000",
-    fontSize: 9,
-    fontWeight: "bold"
-  },
-  // Spotlight highlight styles
-  spotlightHighlight: {
-    position: "absolute",
-    borderWidth: 2,
-    borderStyle: "dashed",
-    borderColor: _sharedUi.night.color.accent,
-    backgroundColor: "transparent"
-  },
-  spotlightLabel: {
-    position: "absolute",
-    backgroundColor: _sharedUi.night.color.surface,
-    borderWidth: 1,
-    borderColor: _sharedUi.night.color.accent,
-    paddingHorizontal: 8,
-    paddingVertical: 3,
-    borderRadius: 4
-  },
-  spotlightLabelText: {
-    color: _sharedUi.night.color.accent,
-    fontSize: 11,
-    fontWeight: "600",
-    fontFamily: _sharedUi.monoFont
-  }
-});
-var _default = exports.default = HighlightUpdatesOverlay;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.HighlightUpdatesOverlay=HighlightUpdatesOverlay,exports.default=void 0;var _react=_interopRequireWildcard(require("react")),_reactNative=require("react-native"),_sharedUi=require("@buoy-gg/shared-ui"),_HighlightUpdatesController=_interopRequireDefault(require("./utils/HighlightUpdatesController")),_PerformanceLogger=require("./utils/PerformanceLogger"),_RenderTracker=require("./utils/RenderTracker"),_jsxRuntime=require("react/jsx-runtime");function _interopRequireDefault(e){return e&&e.__esModule?e:{default:e}}function _interopRequireWildcard(e,t){if("function"==typeof WeakMap)var r=new WeakMap,i=new WeakMap;return(_interopRequireWildcard=function(e,t){if(!t&&e&&e.__esModule)return e;var n,o,a={__proto__:null,default:e};if(null===e||"object"!=typeof e&&"function"!=typeof e)return a;if(n=t?i:r){if(n.has(e))return n.get(e);n.set(e,a)}for(const t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((o=(n=Object.defineProperty)&&Object.getOwnPropertyDescriptor(e,t))&&(o.get||o.set)?n(a,t,o):a[t]=e[t]);return a})(e,t)}const HIGHLIGHT_DURATION=1e3;function HighlightUpdatesOverlay({onBadgePress:e}={}){const[t,r]=(0,_react.useState)([]),[i,n]=(0,_react.useState)(()=>_HighlightUpdatesController.default.getFrozen()),[o,a]=(0,_react.useState)(null),l=(0,_react.useRef)(null),s=(0,_react.useRef)(0),c=(0,_react.useRef)(0),d=(0,_react.useRef)(i);d.current=i,_PerformanceLogger.PerformanceLogger.isEnabled()&&(s.current=performance.now(),c.current=t.length),(0,_react.useLayoutEffect)(()=>{if(_PerformanceLogger.PerformanceLogger.isEnabled()&&s.current>0&&c.current>0){const e=performance.now()-s.current;(0,_PerformanceLogger.markOverlayRendered)(c.current,e)}}),(0,_react.useEffect)(()=>_HighlightUpdatesController.default.subscribeToFreeze(e=>{n(e)}),[]),(0,_react.useEffect)(()=>_RenderTracker.RenderTracker.subscribeToFilters(()=>{r(e=>e.filter(e=>{const t=_RenderTracker.RenderTracker.getRender(String(e.id));return!t||_RenderTracker.RenderTracker.shouldShowRender(t)}))}),[]),(0,_react.useEffect)(()=>(_HighlightUpdatesController.default.setSpotlightCallback(e=>{a(e)}),()=>{_HighlightUpdatesController.default.setSpotlightCallback(null)}),[]);const u=(0,_react.useCallback)(e=>{const t=Date.now(),i=e.map(e=>({...e,timestamp:t}));r(e=>{const t=[...e];for(const e of i){const r=t.findIndex(t=>t.id===e.id);r>=0?t[r]=e:t.push(e)}return t})},[]);(0,_react.useEffect)(()=>(_HighlightUpdatesController.default.setHighlightCallback(u),l.current=setInterval(()=>{if(d.current)return;const e=Date.now();r(t=>t.filter(t=>e-t.timestamp<HIGHLIGHT_DURATION))},50),()=>{_HighlightUpdatesController.default.setHighlightCallback(null),l.current&&clearInterval(l.current)}),[u]);const h=e||_HighlightUpdatesController.default.getBadgePressCallback(),g=(0,_react.useCallback)(t=>{e?e(t):_HighlightUpdatesController.default.handleBadgePress(t)},[e]),_=o?_RenderTracker.RenderTracker.getRender(String(o)):null;return 0!==t.length||_?.measurements?(0,_jsxRuntime.jsxs)(_reactNative.View,{style:styles.overlay,pointerEvents:"box-none",nativeID:"highlight-updates-overlay",children:[_?.measurements&&(0,_jsxRuntime.jsxs)(_jsxRuntime.Fragment,{children:[(0,_jsxRuntime.jsx)(_reactNative.View,{pointerEvents:"none",nativeID:"__spotlight_highlight__",style:[styles.spotlightHighlight,{left:_.measurements.x-3,top:_.measurements.y-3,width:_.measurements.width+6,height:_.measurements.height+6}]}),(0,_jsxRuntime.jsx)(_reactNative.View,{pointerEvents:"none",style:[styles.spotlightLabel,{left:_.measurements.x,top:_.measurements.y+_.measurements.height+4}],children:(0,_jsxRuntime.jsx)(_reactNative.Text,{style:styles.spotlightLabelText,children:_.componentName||_.displayName||_.viewType})})]}),t.map(e=>(0,_jsxRuntime.jsx)(_reactNative.View,{pointerEvents:"box-none",nativeID:`__highlight_rect_${e.id}__`,style:[styles.highlight,{left:e.x,top:e.y,width:e.width,height:e.height,borderColor:e.color}],children:e.count>0&&(0,_jsxRuntime.jsx)(_reactNative.View,{style:[styles.badge,{backgroundColor:e.color}],nativeID:`__highlight_badge_${e.id}__`,pointerEvents:h?"auto":"none",hitSlop:{top:8,bottom:8,left:8,right:8},onStartShouldSetResponder:()=>!!h,onResponderGrant:()=>g(e.id),children:(0,_jsxRuntime.jsx)(_reactNative.Text,{style:styles.badgeText,nativeID:`__highlight_text_${e.id}__`,children:e.count})})},`highlight-${e.id}`))]}):null}const styles=_reactNative.StyleSheet.create({overlay:{position:"absolute",top:0,left:0,right:0,bottom:0,zIndex:999999,elevation:999999,borderWidth:0},highlight:{position:"absolute",borderWidth:2,borderStyle:"solid",backgroundColor:"transparent"},badge:{position:"absolute",top:0,right:0,height:14,borderRadius:0,justifyContent:"center",alignItems:"center",paddingHorizontal:2},badgeText:{color:"#000",fontSize:9,fontWeight:"bold"},spotlightHighlight:{position:"absolute",borderWidth:2,borderStyle:"dashed",borderColor:_sharedUi.night.color.accent,backgroundColor:"transparent"},spotlightLabel:{position:"absolute",backgroundColor:_sharedUi.night.color.surface,borderWidth:1,borderColor:_sharedUi.night.color.accent,paddingHorizontal:8,paddingVertical:3,borderRadius:4},spotlightLabelText:{color:_sharedUi.night.color.accent,fontSize:11,fontWeight:"600",fontFamily:_sharedUi.monoFont}});var _default=exports.default=HighlightUpdatesOverlay;