@buoy-gg/focus-inspector 7.0.31

package/lib/typescript/detect/detectors.d.ts

@@ -0,0 +1,122 @@
+/**
+ * detectors — pure functions from the recorded stream to the three TV focus bug
+ * classes. No timers, no RN, no fiber access, so every rule below is a unit
+ * test rather than a device session.
+ *
+ * The honesty rule that shapes all of this: focus can only be OBSERVED from JS,
+ * never computed. There is no "where would RIGHT take me" API on either
+ * platform, and a JS re-implementation of Android's FocusFinder geometry would
+ * lie in exactly the cases this tool exists for (guides, traps, nextFocus*
+ * overrides). So geometry is only ever used to *downgrade* a flag ("that's the
+ * screen edge, not a dead end") or to *suspect* one — never to assert what the
+ * engine would do.
+ */
+import type { FocusDirection, FocusProbe, FocusTransition } from "../store/focusStore";
+import type { FocusableNode } from "../scan/focusableScanner";
+export declare const DIRECTIONS: FocusDirection[];
+/** Consecutive failed presses in one direction before it counts as a dead end. */
+export declare const DEAD_END_ATTEMPTS = 3;
+/** Presses before "unvisited" is worth reporting at all — below this it's noise. */
+export declare const COVERAGE_MIN_PROBES = 12;
+export interface DeadEndFlag {
+    tag: number;
+    direction: FocusDirection;
+    /** Consecutive presses in this direction that moved nothing. */
+    attempts: number;
+    /**
+     * The element's frame abuts the viewport edge in this direction, so "focus
+     * didn't move" is the expected behavior, not a bug.
+     */
+    atEdge: boolean;
+}
+export interface TrapFlag {
+    /** The element(s) focus cannot escape from, as a group. */
+    tags: number[];
+    /** What holds them: the enclosing guide's tag, or the single element's own. */
+    containerTag: number;
+    directions: FocusDirection[];
+    /**
+     * A `trapFocus*` prop on the enclosing guide explains the trap — probably
+     * intentional. NOTE: trapFocus does NOT hold on Android TV, so an OBSERVED
+     * trap there is always a real bug regardless of this hint.
+     */
+    guideTrapTag?: number;
+}
+export interface InvisibleStopFlag {
+    tag: number;
+    /** "guide" = a TVFocusGuideView (a stop with no highlight). */
+    reason: "guide" | "unknown";
+    at: number;
+    /** How many times focus has landed here. */
+    count: number;
+}
+export interface CoverageResult {
+    focusables: number;
+    visited: number;
+    unvisited: number[];
+    /**
+     * Unvisited AND no observed edge points at it AND a visited neighbour sits
+     * next to it geometrically. A SUSPICION, never a proof — say "suspected
+     * unreachable" in the UI, never "unreachable".
+     */
+    suspectedUnreachable: number[];
+    /** False until enough traversal has happened for absence to mean anything. */
+    meaningful: boolean;
+}
+export interface FocusFlags {
+    deadEnds: DeadEndFlag[];
+    traps: TrapFlag[];
+    invisibleStops: InvisibleStopFlag[];
+    lostCount: number;
+}
+/**
+ * A direction can legitimately move focus sometimes and not others (a rail
+ * scrolls, then hits its end), so a dead end is the *trailing run* of failures,
+ * not a lifetime tally. One successful move clears it.
+ */
+export declare function detectDeadEnds(probes: FocusProbe[], nodes: FocusableNode[], minAttempts?: number, since?: number): DeadEndFlag[];
+/**
+ * A trap is a REGION focus cannot get OUT of, which is usually not one element
+ * and is not "all four directions are dead".
+ *
+ * Both of the obvious rules were tried against the armed trap in the TV example
+ * (a row of three tiles in one `TVFocusGuideView`) and both missed it. Per
+ * element: left/right move freely between the tiles, so no single tile
+ * dead-ends four ways. All-four-directions on the group: the box is
+ * left-aligned with everything else on the screen, so LEFT is a legitimate
+ * screen edge and the union never reaches four.
+ *
+ * What actually defines the bug is escape: for every direction in which
+ * something focusable EXISTS outside the container, focus has to have been
+ * observed failing to get there. A direction with nothing beyond it is not
+ * evidence either way, and a container with nothing outside it at all is the
+ * whole screen, not a trap.
+ */
+export declare function detectTraps(deadEnds: DeadEndFlag[], nodes: FocusableNode[]): TrapFlag[];
+/**
+ * Focus that parked somewhere with no visible highlight — the "focus vanished"
+ * symptom. Two shapes: it landed on a TVFocusGuideView (a real focus stop the
+ * user cannot see), or on a tag the inventory has never heard of (a view
+ * outside the walked tree, or one that unmounted since the last scan).
+ */
+export declare function detectInvisibleStops(transitions: FocusTransition[], nodes: FocusableNode[], since?: number): InvisibleStopFlag[];
+/**
+ * `since` is the timestamp of the inventory these flags are judged against —
+ * normally the last scan. Everything older belonged to a screen that no longer
+ * exists, and judging it here produces confident nonsense.
+ */
+export declare function detectFlags(transitions: FocusTransition[], probes: FocusProbe[], nodes: FocusableNode[], lostCount: number, since?: number): FocusFlags;
+/**
+ * Coverage. Observed absence is EVIDENCE, not proof: focus is nondeterministic
+ * enough on tvOS that "never visited" cannot be promoted to "unreachable"
+ * without native support that does not exist. So the strong word is reserved
+ * for the case where geometry AND the observed graph agree.
+ */
+export declare function computeCoverage(nodes: FocusableNode[], visited: number[], transitions: FocusTransition[], probes: FocusProbe[]): CoverageResult;
+/**
+ * The observed out-edges of one element — what the desktop's D-pad compass
+ * renders. A direction with no entry is UNKNOWN (dim), which is a different
+ * statement from a dead end (pressed, went nowhere).
+ */
+export declare function observedEdges(tag: number, transitions: FocusTransition[]): Partial<Record<FocusDirection, number | null>>;
+//# sourceMappingURL=detectors.d.ts.map

package/lib/typescript/detect/detectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.d.ts","sourceRoot":"","sources":["../../../src/detect/detectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,eAAO,MAAM,UAAU,EAAE,cAAc,EAAoC,CAAC;AAE5E,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,cAAc,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,GAAE,MAA0B,EACvC,KAAK,SAAI,GACR,WAAW,EAAE,CA2Bf;AA8FD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,QAAQ,EAAE,CA6EvF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,eAAe,EAAE,EAC9B,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,SAAI,GACR,iBAAiB,EAAE,CAiCrB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,eAAe,EAAE,EAC9B,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,aAAa,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,SAAI,GACR,UAAU,CAQZ;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EAAE,EACtB,OAAO,EAAE,MAAM,EAAE,EACjB,WAAW,EAAE,eAAe,EAAE,EAC9B,MAAM,EAAE,UAAU,EAAE,GACnB,cAAc,CAuChB;AAsBD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,eAAe,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAOhD"}

package/lib/typescript/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @buoy-gg/focus-inspector
+ *
+ * TV focus debugging for React Native TV apps, from Buoy Desktop: what holds
+ * D-pad focus right now, every focus transition with the direction that caused
+ * it, the inventory of focusable elements, and automatic flags for the three
+ * big TV focus bug classes — focus gets STUCK (dead end / trap), focus
+ * DISAPPEARS (parks on an invisible stop or leaves the RN tree), and an element
+ * is never REACHED.
+ *
+ * This package renders NOTHING on the device, and that is a hard constraint
+ * rather than a preference: on Android TV any focusable view in an overlay
+ * becomes a D-pad stop in the host app's focus order, so an on-device panel
+ * would change the navigation it is measuring. See the README.
+ *
+ * It also ships no native code — the focus stream comes from a JS-only global
+ * observer (`RawEventEmitter`'s `topFocus`/`topBlur`), which is why Buoy stays
+ * podspec-free.
+ */
+export { focusInspectorSyncAdapter } from "./sync/focusInspectorSyncAdapter";
+export type { FocusInspectorSnapshot } from "./sync/focusInspectorSyncAdapter";
+export { clearHistory, getState, recordBlur, recordFocus, recordKey, resetStore, setTracking, subscribe, } from "./store/focusStore";
+export type { FocusDirection, FocusProbe, FocusStoreState, FocusTransition, } from "./store/focusStore";
+export { scanFocusables } from "./scan/focusableScanner";
+export type { FocusableNode, FocusFrame, FocusGuideInfo, FocusScanResult, } from "./scan/focusableScanner";
+export { computeCoverage, detectDeadEnds, detectFlags, detectInvisibleStops, detectTraps, observedEdges, } from "./detect/detectors";
+export type { CoverageResult, DeadEndFlag, FocusFlags, InvisibleStopFlag, TrapFlag, } from "./detect/detectors";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAK/E,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,cAAc,EACd,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,eAAe,GAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,QAAQ,GACT,MAAM,oBAAoB,CAAC"}

package/lib/typescript/observe/focusEventObserver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * focusEventObserver — the global, zero-instrumentation focus source.
+ *
+ * `react-native/Libraries/Core/RawEventEmitter` mirrors every Fabric-dispatched
+ * event BEFORE React's plugins or components see it, and on both tvOS and
+ * Android TV every focus change arrives there as `topFocus` / `topBlur` with
+ * the focused view's native tag. Its own source comment blesses exactly this
+ * use ("app-specific perf monitoring … and maybe debugging").
+ *
+ * Why not the obvious alternatives:
+ * - `onFocus`/`onBlur` props would require instrumenting the app's components,
+ *   and would MISS the interesting cases: focus really does park on views with
+ *   no handler (a TVFocusGuideView with `destinations` is an invisible focus
+ *   stop). A per-component observer reports "focus is nowhere" for the exact
+ *   bug this tool exists to catch.
+ * - `TVEventHandler`'s `focus`/`blur` HWEvents are deprecated and 0.85 deleted
+ *   the Fabric calls that emitted them (fork issue #1037). They still fire on
+ *   the 0.83 line, so they're folded in as optional enrichment below — never
+ *   required, or the tool would work on one app and not the other.
+ * - There is no root-level capture View to wrap the app in: Buoy mounts as a
+ *   SIBLING of the app tree, not a parent.
+ *
+ * The deep import is guarded. If it ever moves, the snapshot degrades to
+ * `observer: "unavailable"` and the panel says so, rather than the tool taking
+ * the app's bundle down.
+ */
+export type ObserverStatus = "idle" | "listening" | "unavailable";
+export declare function attachFocusObserver(): void;
+export declare function detachFocusObserver(): void;
+export declare function getFocusObserverStatus(): {
+    status: ObserverStatus;
+    reason: string | null;
+};
+//# sourceMappingURL=focusEventObserver.d.ts.map

package/lib/typescript/observe/focusEventObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusEventObserver.d.ts","sourceRoot":"","sources":["../../../src/observe/focusEventObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,aAAa,CAAC;AA6BlE,wBAAgB,mBAAmB,IAAI,IAAI,CA2B1C;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAU1C;AAED,wBAAgB,sBAAsB,IAAI;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAE1F"}

package/lib/typescript/observe/keyEventObserver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * keyEventObserver — the direction half of the stream.
+ *
+ * D-pad HWEvents carry NO tag on either platform (an Android payload is exactly
+ * `{"eventKeyAction":1,"eventType":"right"}`), and focus events carry no
+ * direction. So key events tell you *which way the user pushed* and focus
+ * events tell you *where focus went*; the store joins them on time.
+ *
+ * `TVEventHandler.addListener` (not the `useTVEventHandler` hook) because sync
+ * adapters are not React components — nothing here mounts.
+ *
+ * On the 0.83 fork line iOS Fabric ALSO still emits tagged `focus`/`blur`
+ * HWEvents here. Those are folded into the same store as enrichment so the
+ * older line gets a focus source even if the RawEventEmitter path ever fails —
+ * never depended on, because 0.85 deleted them.
+ */
+export declare const isTV: boolean;
+export declare const platformOS: string;
+export declare function attachKeyObserver(): void;
+export declare function detachKeyObserver(): void;
+export declare function isKeyObserverListening(): boolean;
+//# sourceMappingURL=keyEventObserver.d.ts.map

package/lib/typescript/observe/keyEventObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyEventObserver.d.ts","sourceRoot":"","sources":["../../../src/observe/keyEventObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH,eAAO,MAAM,IAAI,SAA6B,CAAC;AAC/C,eAAO,MAAM,UAAU,QAA+B,CAAC;AAiDvD,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAQxC;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD"}

package/lib/typescript/observe/rawEventEmitter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The one guarded require for React Native's RawEventEmitter, kept in its own
+ * module for two reasons.
+ *
+ * 1. `react-native/Libraries/Core/RawEventEmitter` is a DEEP import. It warns
+ *    under 0.85's export map and could move in any release, so the failure has
+ *    to degrade to "observer unavailable" in the snapshot rather than taking
+ *    the host app's bundle down. Metro only treats a require as optional when
+ *    it sits LEXICALLY inside a try statement — wrapping it in a helper or an
+ *    arrow makes Metro hard-fail the bundle instead.
+ * 2. It gives the unit suite a seam. Node's `require` resolves through the
+ *    filesystem and ignores Vitest's module mocks, so the emitter can only be
+ *    faked by mocking a module that is reached with a real `import`.
+ */
+export interface RawEventSubscription {
+    remove: () => void;
+}
+export interface RawEventEmitterLike {
+    addListener: (eventType: string, listener: (event: {
+        eventName?: string;
+        nativeEvent?: Record<string, unknown>;
+    }) => void) => RawEventSubscription;
+}
+export interface RawEmitterResolution {
+    emitter: RawEventEmitterLike | null;
+    reason: string | null;
+}
+export declare function resolveRawEventEmitter(): RawEmitterResolution;
+//# sourceMappingURL=rawEventEmitter.d.ts.map

package/lib/typescript/observe/rawEventEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rawEventEmitter.d.ts","sourceRoot":"","sources":["../../../src/observe/rawEventEmitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,CACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,IAAI,KACrF,oBAAoB,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,wBAAgB,sBAAsB,IAAI,oBAAoB,CAc7D"}

package/lib/typescript/scan/focusableScanner.d.ts

@@ -0,0 +1,95 @@
+/**
+ * focusableScanner — a read-only fiber walk that inventories everything on
+ * screen the TV focus engine could land on.
+ *
+ * Provably inert: it reads `memoizedProps` and calls `measureInWindow`. It adds
+ * no views, sets no props, and calls no focus command — which matters more here
+ * than anywhere else in Buoy, because on Android TV a single focusable view we
+ * rendered would insert itself into the host app's focus order and change the
+ * very navigation this tool measures.
+ *
+ * Traversal (multi-renderer roots, the Fabric/Paper/CLI-dev instance triad,
+ * Offscreen + inactive-`react-native-screens` pruning, measure-with-a-hang-
+ * guard) follows the house pattern from
+ * `packages/highlight-updates/src/highlight-updates/utils/screenElements.ts`.
+ * The repo convention is a per-package copy trimmed to the tool's needs rather
+ * than a shared walker library — see packages/CLAUDE.md.
+ *
+ * There is no JS API for "which view has focus" and none for "if focus is here
+ * and the user presses RIGHT, where does it go" (Android has
+ * `FabricUIManager.findNextFocusableElement` natively but never exposes it to
+ * JS; tvOS's UIKit engine decides at runtime and answers nothing). So this
+ * inventory is the *candidate set* — the observed transition stream is what
+ * says which of them focus actually reaches.
+ */
+export interface FocusFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FocusGuideInfo {
+    autoFocus: boolean;
+    /** `destinations` is applied via a native command, so only presence is known. */
+    hasDestinations: boolean;
+    enabled: boolean;
+    trap: {
+        up: boolean;
+        down: boolean;
+        left: boolean;
+        right: boolean;
+    };
+}
+export interface FocusableNode {
+    nativeTag: number;
+    name: string;
+    owner?: string;
+    testID?: string;
+    label?: string;
+    text?: string;
+    /** Normalized [0,1] rect. Absent when the node could not be measured. */
+    frame?: FocusFrame;
+    focusProps: {
+        focusable?: boolean;
+        hasTVPreferredFocus?: boolean;
+        /** Which `nextFocus*` overrides are set — the values are native tags. */
+        nextFocus?: {
+            up?: boolean;
+            down?: boolean;
+            left?: boolean;
+            right?: boolean;
+        };
+    };
+    /** Present when this node IS a TVFocusGuideView (an invisible focus stop). */
+    guide?: FocusGuideInfo;
+    /** Native tag of the nearest enclosing guide, for the "intentional trap?" hint. */
+    guideAncestorTag?: number;
+    /** True when a press handler is reachable — a Pressable/Touchable stop. */
+    pressable?: boolean;
+    /**
+     * False when the element's box sits outside the window right now — below the
+     * fold of a ScrollView, typically. Still a real D-pad target (the engine
+     * scrolls to it), so it stays in the inventory and in the coverage
+     * denominator; it is only marked so the panel can say why it is unvisited.
+     */
+    onScreen?: boolean;
+}
+export interface FocusScanResult {
+    screen: {
+        width: number;
+        height: number;
+    };
+    nodes: FocusableNode[];
+    scannedAt: number;
+}
+export declare function scanFocusables(): Promise<FocusScanResult>;
+/**
+ * Move focus to a native tag. Source-verified only until this runs on a device:
+ * `Commands.requestTVFocus` takes an instance ref, never a tag, so the last
+ * scan's instance table is the only way to get from one to the other.
+ */
+export declare function requestFocusForTag(nativeTag: number): {
+    ok: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=focusableScanner.d.ts.map

package/lib/typescript/scan/focusableScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusableScanner.d.ts","sourceRoot":"","sources":["../../../src/scan/focusableScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8BH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE;QACV,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,yEAAyE;QACzE,SAAS,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,OAAO,CAAC;YAAC,IAAI,CAAC,EAAE,OAAO,CAAC;YAAC,IAAI,CAAC,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;KAC/E,CAAC;IACF,8EAA8E;IAC9E,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AA6XD,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CA0D/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAgBtF"}

package/lib/typescript/store/focusStore.d.ts

@@ -0,0 +1,135 @@
+/**
+ * focusStore — the device-side memory of the TV focus inspector.
+ *
+ * CONTRACT: this store only ever OBSERVES. It never adds a view, never sets a
+ * prop, never calls a focus command on its own. On Android TV any focusable
+ * view we rendered would become a D-pad stop in the host app's focus order, so
+ * a tool that measures focus by participating in it would measure itself. The
+ * only thing that ever moves focus is the explicit `focusElement` action a
+ * human triggers from the dashboard.
+ *
+ * It is deliberately react-native-free: observers push events in, so every rule
+ * below (transition pairing, direction attribution, dead-end probes) is a pure
+ * function of a timestamped event stream and is unit-testable without a device.
+ */
+/** The four D-pad directions. Select/menu never move focus, so they're dropped. */
+export type FocusDirection = "up" | "down" | "left" | "right";
+export interface FocusTransition {
+    /** Monotonic counter — survives ring-buffer trimming, so it's a stable key. */
+    seq: number;
+    /** Where focus was. `null` at boot (first focus) or after focus was lost. */
+    fromTag: number | null;
+    /** Where focus went. `null` means focus LEFT the RN tree (the "vanished" bug). */
+    toTag: number | null;
+    /** D-pad direction credited to this move, when one could be attributed. */
+    direction: FocusDirection | null;
+    at: number;
+    /** How long focus sat on `fromTag` before this move. */
+    dwellMs?: number;
+}
+/**
+ * One D-pad press, recorded against the element that held focus when it
+ * happened, plus what it did. A probe with `movedTo: null` is one piece of
+ * dead-end evidence; N consecutive ones in the same direction is a flag.
+ */
+export interface FocusProbe {
+    seq: number;
+    /** Focused element at press time. `null` = nothing had focus (already lost). */
+    tag: number | null;
+    direction: FocusDirection;
+    at: number;
+    /** False while we're still inside the attribution window. */
+    resolved: boolean;
+    /** Where focus went, or `null` for "focus did not move". */
+    movedTo: number | null;
+}
+/**
+ * Why nothing is reported as focused. These are NOT the same thing and must
+ * never be rendered the same way:
+ *
+ * - "never-observed": we have not seen a single focus event yet. Focus is
+ *   almost certainly fine — there is no API for "which view has focus", so the
+ *   tool learns the answer only when focus MOVES. Attaching to an app that is
+ *   sitting still looks exactly like this until the first press.
+ * - "lost": we WATCHED a view blur with nothing taking over. That is the real
+ *   "focus vanished" bug.
+ */
+export type FocusPresence = "focused" | "never-observed" | "lost";
+export interface FocusStoreState {
+    currentTag: number | null;
+    presence: FocusPresence;
+    /** When focus arrived at `currentTag` (for the dwell timer on the Now card). */
+    currentSince: number | null;
+    transitions: FocusTransition[];
+    probes: FocusProbe[];
+    /** Every tag focus has ever landed on this session. */
+    visited: number[];
+    /** Transitions whose `toTag` was null — focus left the tree. */
+    lostCount: number;
+    /** Total transitions recorded, including ones trimmed out of the buffer. */
+    transitionCount: number;
+    tracking: boolean;
+}
+/**
+ * A D-pad press and the focus pair it caused arrive in EITHER order, a few ms
+ * apart — both `HWEvent → blur → focus` and `blur → focus → HWEvent` were
+ * observed live on the same session. So direction attribution is a time-window
+ * join in both directions, never a sequence assumption.
+ */
+export declare const DIRECTION_WINDOW_MS = 250;
+/**
+ * The window for crediting a press to a move that was ALREADY recorded — the
+ * `blur → focus → HWEvent` ordering. Much tighter than the forward window on
+ * purpose: forward attribution is waiting for a consequence, but backward
+ * attribution is claiming a cause, and a press 200ms after a move is far more
+ * likely to be the NEXT press than a late-delivered echo of the last one.
+ * Delivery races were observed at a few ms.
+ */
+export declare const BACKFILL_WINDOW_MS = 60;
+/**
+ * How long a blur waits for its matching focus before we call it a loss. Focus
+ * pairs land within a frame or two; anything past this really has left the RN
+ * tree (system alert, another window, an unmounted subtree).
+ */
+export declare const FOCUS_LOST_MS = 400;
+/** A view took focus. `tag` is the native tag from the raw event's target. */
+export declare function recordFocus(tag: number, at?: number): void;
+/**
+ * A view lost focus. Held rather than recorded: the matching focus lands within
+ * a frame or two and turns this into a normal transition. Only a blur with NO
+ * follow-up is the "focus vanished" bug, and that is worth reporting.
+ *
+ * THE ORDERING TRAP: blur does NOT reliably precede its focus. On tvOS Fabric
+ * 0.85 the emitter delivers `topFocus(new)` and only THEN `topBlur(old)`, ~1ms
+ * apart (verified on the Apple TV simulator). A blur for a tag that no longer
+ * holds focus is therefore a late echo of a move already recorded — swallowing
+ * it is what keeps the tool from arming a loss timer for an element that was
+ * never actually orphaned, and then reporting a phantom "focus lost" plus a
+ * wrong `fromTag` on the next real move. Only a blur for the CURRENT holder can
+ * mean focus is leaving, and that test is order-agnostic on both platforms.
+ */
+export declare function recordBlur(tag: number, at?: number): void;
+/**
+ * A D-pad direction was pressed. Opens a probe against whatever holds focus,
+ * which resolves either to the element focus moved to or to `null` — "this
+ * direction did nothing from here", the raw material of every dead-end flag.
+ */
+export declare function recordKey(direction: FocusDirection, at?: number): void;
+export declare function getState(): FocusStoreState;
+/**
+ * Wipe the history but KEEP where focus currently is — clearing is how a user
+ * starts a clean traversal run, and forgetting the current element would blank
+ * the Now card until the next press.
+ */
+export declare function clearHistory(): void;
+/**
+ * Pause/resume recording without detaching the native listeners. Useful when a
+ * user is driving the app by hand and doesn't want that traversal scored.
+ */
+export declare function setTracking(enabled: boolean): void;
+/** Full reset, including timers — the observers' detach path and tests. */
+export declare function resetStore(): void;
+export declare function subscribe(listener: () => void): () => void;
+/** Exposed so the scanner can nudge a rescan when focus lands on a stranger. */
+export declare function notifyChange(): void;
+//# sourceMappingURL=focusStore.d.ts.map

package/lib/typescript/store/focusStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusStore.d.ts","sourceRoot":"","sources":["../../../src/store/focusStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kFAAkF;IAClF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,cAAc,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,gFAAgF;IAChF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AA+EjC,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,IAAI,CAoBtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,IAAI,CAerE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,cAAc,EAAE,EAAE,GAAE,MAAmB,GAAG,IAAI,CAsDlF;AAED,wBAAgB,QAAQ,IAAI,eAAe,CAc1C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAQnC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQlD;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,IAAI,CAiBjC;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK1D;AAED,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/lib/typescript/sync/focusInspectorSyncAdapter.d.ts

@@ -0,0 +1,107 @@
+/**
+ * focusInspectorSyncAdapter — streams the focus picture to Buoy Desktop.
+ *
+ * Structurally matches external-sync's `ToolSyncAdapter` WITHOUT importing the
+ * package (the house rule every tool's adapter follows). Auto-discovery in
+ * @buoy-gg/core picks it up by export name and announces the "focus-inspector"
+ * capability.
+ *
+ * There is NO on-device UI and there never will be: on Android TV a focusable
+ * view in an overlay becomes a D-pad stop in the host app's focus order
+ * (`pointerEvents="box-none"` gates touch, not focus), so an on-device panel
+ * would corrupt the measurement. Everything device-side therefore lives in
+ * module scope and in this adapter's `subscribe` — headless FloatingDevTools
+ * mounts the adapters and NONE of the overlay components, so instrumentation
+ * inside a component would simply never run on TV.
+ *
+ * WORK SPLIT: the two event listeners attach at module load and stay attached;
+ * the fiber scan only runs while a dashboard is watching.
+ *
+ * That asymmetry is deliberate and was learned the hard way. Focus cannot be
+ * QUERIED on either platform — the tool only ever learns where focus is by
+ * watching it arrive. So an observer that attached on first `subscribe` knows
+ * nothing until focus next MOVES, which means opening the panel on a running
+ * app shows nothing, and, far worse, the tool is blind in precisely the case it
+ * exists for: focus is stuck, you press a direction, nothing moves, and so
+ * nothing is ever learned. Listening from the start is what makes "what holds
+ * focus right now" answerable at all.
+ *
+ * The cost is two event-emitter listeners and a bounded ring-buffer append per
+ * focus change — nothing next to the fiber walk, which stays gated on a
+ * dashboard actually watching. `setTracking(false)` is the off switch.
+ */
+import { type FocusDirection, type FocusPresence, type FocusTransition } from "../store/focusStore";
+import { type ObserverStatus } from "../observe/focusEventObserver";
+import { type FocusableNode } from "../scan/focusableScanner";
+import { computeCoverage, type FocusFlags } from "../detect/detectors";
+export interface FocusInspectorSnapshot {
+    /** False on phones/tablets/web — the panel renders an "not a TV build" state. */
+    supported: boolean;
+    platform: string;
+    /** "unavailable" means the RawEventEmitter deep import moved; nothing is being observed. */
+    observer: ObserverStatus;
+    observerReason: string | null;
+    /** Whether the D-pad direction stream is attached (0.85 TVEventHandler). */
+    keysListening: boolean;
+    tracking: boolean;
+    /**
+     * Why `current` is null, when it is. "never-observed" is the ordinary
+     * cold-start case and must NOT be reported as a bug: focus cannot be queried,
+     * only watched arriving, so an app sitting still looks identical to one with
+     * no focus until something moves.
+     */
+    presence: FocusPresence;
+    current: {
+        tag: number;
+        node: FocusableNode | null;
+        since: number;
+        /** Where each direction has been OBSERVED to lead from here. */
+        edges: Partial<Record<FocusDirection, number | null>>;
+    } | null;
+    transitions: FocusTransition[];
+    focusables: FocusableNode[];
+    screen: {
+        width: number;
+        height: number;
+    } | null;
+    scannedAt: number | null;
+    flags: FocusFlags;
+    coverage: ReturnType<typeof computeCoverage>;
+    stats: {
+        focusables: number;
+        visited: number;
+        transitions: number;
+        flagged: number;
+    };
+    capturedAt: number;
+}
+export declare const focusInspectorSyncAdapter: {
+    version: number;
+    getSnapshot(): FocusInspectorSnapshot;
+    subscribe(onChange: () => void): () => void;
+    actions: {
+        rescan(): Promise<{
+            ok: true;
+            focusables: number;
+        }>;
+        clearHistory(): {
+            ok: true;
+        };
+        setTracking(params?: {
+            enabled?: boolean;
+        }): {
+            tracking: boolean;
+        };
+        /**
+         * Put focus on an element and watch what the D-pad does from there — the
+         * only write this tool ever performs, and only when a human asks for it.
+         */
+        focusElement(params?: {
+            nativeTag?: number;
+        }): {
+            ok: boolean;
+            reason?: string;
+        };
+    };
+};
+//# sourceMappingURL=focusInspectorSyncAdapter.d.ts.map

package/lib/typescript/sync/focusInspectorSyncAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusInspectorSyncAdapter.d.ts","sourceRoot":"","sources":["../../../src/sync/focusInspectorSyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAA8B,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAYnG,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,gEAAgE;QAChE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;KACvD,GAAG,IAAI,CAAC;IACT,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;IAC7C,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;CACpB;AAoID,eAAO,MAAM,yBAAyB;;mBAGrB,sBAAsB;wBAIjB,MAAM,IAAI,GAAG,MAAM,IAAI;;kBA6CzB,OAAO,CAAC;YAAE,EAAE,EAAE,IAAI,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;wBAKzC;YAAE,EAAE,EAAE,IAAI,CAAA;SAAE;6BAKP;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG;YAAE,QAAQ,EAAE,OAAO,CAAA;SAAE;QAKlE;;;WAGG;8BACmB;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG;YAAE,EAAE,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE;;CAOlF,CAAC"}