@buoy-gg/focus-inspector
Inspect observed focus transitions and the discovered focusable inventory in a React Native TV app. Buoy Desktop shows current observations, directional history, and possible focus problems.
Install
npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/focus-inspector
Account setup
Start in a development build. You need a Free or Pro Buoy account. Sign in from your app's folder:
npx --package=@buoy-gg/core buoy login
Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token. It works in dev builds for 30 days.
On Expo, the token goes in .env.development.local. Buoy reads it by itself in dev builds. You can also pass it in yourself:
import { Buoy } from "@buoy-gg/core";
Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
On React Native CLI, the token goes in .env.local as BUOY_KEY. React Native does not load that file by itself. Pass the token in with your app's own env setup. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the Quick Start for the complete root component.
Connect a TV app
Use a compatible react-native-tvos app and follow the TV installation guide. Mount the core integration after account initialization:
import { FloatingDevTools } from "@buoy-gg/core";
<FloatingDevTools headless />;
Keep the TV app headless so a focusable developer overlay does not interfere with its navigation. Open Desktop, sign in, select the device, and open the tool's panel. A phone build is not a substitute for testing TV behavior.
Observe a known focus path
Focus Inspector requires the TV fork and New Architecture event support. Move through a short known path and compare the highlighted element with the panel's transitions. A direction remains unknown until it has been observed. Scan the screen and inspect discovered elements that remain unvisited.
Listeners observe focus events; inventory scanning depends on dashboard watch state. Internal React Native event APIs may change between versions. If the observer is unavailable, the panel should report that state rather than claim complete capture.
Interpret findings
Flags identify possible dead ends, traps, invisible stops, focus loss, and unvisited elements. They are diagnostic heuristics, not proof that an element is unreachable. Intentional focus guides can constrain navigation on both tvOS and Android TV; evaluate trapFocus behavior against the TV fork version your app uses.
Actions include rescan, clearHistory, setTracking, and focusElement({ nativeTag }). The last action changes focus; it is not equivalent to traversing the same route with D-pad presses.
Verify your routes, layouts, and TV fork version, including a comparison with capture disabled if you suspect measurement interference.
Desktop and MCP
React Native connections require @buoy-gg/external-sync. Follow the Desktop connection guide, sign in to Desktop separately, and confirm the selected device. MCP uses the sign-in from buoy login on your computer. Free has the basic MCP. Reading this tool from the MCP needs Pro.
Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.
Web support (unreleased)
Browser capture measures DOM focusable elements and observes real focus and keyboard events. It uses the existing sync adapter for remote inspection. The browser build is available in this checkout and has not been published yet. See the web setup guide for registration, dependencies, and browser boundaries.