@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 with a Free or Pro Buoy account key. From the app directory:

npx --package=@buoy-gg/core buoy login

For Expo, initialize Buoy with the key written to .env.local:

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

For React Native CLI, pass the key through your app's environment configuration; .env.local is not loaded automatically. 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.

Full Focus Inspector guide

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 also needs a process account and Pro access.

Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.