@buoy-gg/focus-inspector 7.0.36 → 7.0.38

package/README.md

@@ -1,136 +1,61 @@
 # @buoy-gg/focus-inspector
 
-[![npm version](https://img.shields.io/npm/v/@buoy-gg/focus-inspector?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/focus-inspector) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/focus-inspector?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@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.
 
-**See what holds D-pad focus in your Apple TV / Android TV app from Buoy Desktop — every focus move with the direction that caused it, the full focusable inventory, and automatic flags for focus that gets stuck, vanishes, or never arrives.**
+## Install
+
+```bash
+npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/focus-inspector
+```
 
-Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside your React Native app. Install it and the Focus panel lights up in Buoy Desktop for that device.
+## Account setup
 
-## Install
+Start in a development build with a Free or Pro Buoy account key. From the app directory:
 
 ```bash
-npm install @buoy-gg/core @buoy-gg/focus-inspector
+npx --package=@buoy-gg/core buoy login
+```
+
+For Expo, initialize Buoy with the key written to `.env.local`:
+
+```tsx
+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](https://buoy.gg/buoy/latest/docs/quick-start) for the complete root component.
+
+## Connect a TV app
+
+Use a compatible react-native-tvos app and follow the [TV installation guide](https://buoy.gg/buoy/latest/docs/tv/installation). Mount the core integration after account initialization:
+
 ```tsx
 import { FloatingDevTools } from "@buoy-gg/core";
 
-export default function App() {
-  return (
-    <>
-      {/* your app */}
-      <FloatingDevTools headless />  {/* TV apps run headless — no bubble */}
-    </>
-  );
-}
+<FloatingDevTools headless />;
 ```
 
-Requires `react-native-tvos` (the TV fork) and the New Architecture. On a phone build the
-adapter reports `supported: false` and attaches nothing.
-
-The focus listeners attach when the package loads, not when the panel opens: focus can only be
-observed arriving, never queried, so a tool that started listening on demand would know nothing
-until focus next moved — and would be blind exactly when focus is stuck. The fiber scan, which is
-the part with real cost, stays gated on a dashboard actually watching.
-
-## What it shows
-
-- **Now** — the element that currently holds focus: its `testID`, component, native tag, frame
-  and dwell time, plus a warning when focus has parked somewhere invisible or left the tree.
-- **Observed exits** — a D-pad compass of where each direction has actually been seen to lead
-  from the focused element. A direction reads **unknown** until it has been pressed from there.
-- **Transitions** — a newest-first timeline of every focus move, with the direction credited to
-  it and the dwell time it ended.
-- **Focusables** — every element the focus engine could land on, including the ones below the
-  fold and the invisible `TVFocusGuideView` stops, with a visited/unvisited marker and coverage.
-- **Flags** — dead ends, focus traps, invisible stops, focus loss, and suspected-unreachable
-  elements.
-
-Actions: `rescan`, `clearHistory`, `setTracking`, and `focusElement({ nativeTag })` — put focus
-somewhere and watch what the D-pad does from there.
-
-## What this package does — and deliberately does not
-
-It **renders nothing**, 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
-(`pointerEvents="box-none"` gates touch, not focus), so an on-device panel would change the focus
-order it is measuring. Buoy Desktop is the surface.
-
-It ships **no native code** — no podspec, no gradle. The focus stream is JS-only.
-
-It is **inert**. The only thing it ever writes is `focusElement`, which you have to click. The
-inventory is a read-only fiber walk (`memoizedProps` + `measureInWindow`); nothing is mounted and
-no prop is set. Verified empirically: the same 12-press script over the TV example produces a
-byte-identical focus sequence with the tool active and with it disabled (see the matrix below).
-
-## How it knows
-
-**Focus** comes from `react-native/Libraries/Core/RawEventEmitter`, which mirrors every
-Fabric-dispatched event before React's plugins see it. On both platforms every focus change
-arrives there as `topFocus` / `topBlur` carrying the focused view's native tag — no native code,
-no app instrumentation, and crucially it sees focus landing on views with **no** `onFocus`
-handler. That last part is the whole point: a `TVFocusGuideView` with `destinations` is a real
-focus stop with no highlight, and a per-component observer would report "focus is nowhere" for
-exactly the bug you are chasing. The deep import is guarded; if React Native ever moves it, the
-snapshot degrades to `observer: "unavailable"` and the panel says so.
-
-`TVEventHandler`'s `focus`/`blur` HWEvents are *not* the source: 0.85 deleted the Fabric calls
-that emitted them ([fork #1037](https://github.com/react-native-tvos/react-native-tvos/issues/1037)).
-The 0.83 line still sends them with a tag, and they are folded in as optional enrichment only.
-
-**Direction** comes from `TVEventHandler`'s D-pad events, which carry no tag — so the two streams
-are joined on time, in both directions, because their delivery order is not deterministic. Key
-down is ignored, never key up (tvOS emits only key-up for button presses).
-
-**Nothing is computed.** 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, and tvOS's UIKit
-engine decides at runtime and answers nothing. So every edge in this tool is one your app
-actually took. Geometry is used only to *downgrade* a flag ("nothing exists past this, so the
-screen just ends here") or to raise a *suspicion*, never to assert where the engine would go. The
-panel says "unvisited" and "suspected unreachable", never "unreachable".
-
-## Detectors
-
-| Flag | Rule |
-|---|---|
-| **Dead end** | 3+ presses of one direction in a row from the same element moved nothing, and the inventory knows of something focusable further along in that direction. One successful move clears the run. |
-| **Trap** | A region — an element, or everything inside one `TVFocusGuideView` — that focus was never observed escaping in *any* direction where something focusable exists outside it. Annotated when the enclosing guide sets `trapFocus*`, which suggests it was asked for. |
-| **Invisible stop** | Focus landed on a `TVFocusGuideView` (a stop with no highlight) or on a tag the inventory has never seen. This is what "focus vanished" looks like. |
-| **Focus lost** | A view blurred and nothing took focus within 400ms — focus left the React Native tree. |
-| **Coverage** | Visited vs. inventory, with *suspected unreachable* for elements that are unvisited, have no observed edge pointing at them, and sit right beside a visited neighbour. |
-
-Flags are judged per screen: anything recorded before the current scan belonged to a screen that
-no longer exists and is not judged at all.
-
-## Platform notes
-
-- **`trapFocus*` holds on tvOS and silently does not hold on Android TV.** An observed trap on
-  Android is therefore always a real bug, whatever the props say. Do not "fix" the detector to
-  make the platforms agree.
-- **Focus/blur ordering differs by platform.** tvOS Fabric delivers `topFocus(new)` and *then*
-  `topBlur(old)`; Android delivers blur first. Both are handled — a blur for an element that no
-  longer holds focus is a late echo, not the start of a loss.
-- `Platform.isTVOS` is `undefined` on Android TV. Only ever test `=== true`.
-
-## Verified on device
-
-Apple TV 4K simulator (tvOS 26.2) and Android TV emulator (API 34), both Fabric,
-react-native-tvos 0.85.3-3, driven with `idb ui key` / `adb shell input keyevent` over the TV
-example app's focus fixtures.
-
-| Case | Apple TV | Android TV |
-|---|---|---|
-| Observer + D-pad stream attach; inventory scans | ✅ 63 focusables on the home screen | ✅ 63 focusables |
-| Clean traversal: correct `from → direction → to`, coverage climbs, no false flags | ✅ | ✅ |
-| Direction credited in both delivery orders (key before / after the focus pair) | ✅ | ✅ |
-| Screen edge downgraded, not flagged (LEFT from the leftmost card) | ✅ | ✅ |
-| Armed 4-way `trapFocus` guide → trap flagged, annotated "guide asked for this" | ✅ | ✅ correctly **not** flagged — `trapFocus` does not hold there, and focus escaped |
-| Trap released → flag clears on the next traversal | ✅ | n/a |
-| Focus parked on a `destinations` guide → invisible-stop flag | ✅ | not reproduced — the engine returned a real dead end instead, which was flagged as one |
-| `focusElement` moves focus (`requestTVFocus`) | ✅ | ✅ |
-| Inertness: identical focus sequence with the tool active vs. disabled | ✅ | — |
-
-## License
-
-Proprietary. See the [Buoy](https://github.com/Buoy-gg/buoy) repository.
+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](https://buoy.gg/buoy/latest/docs/tools/focus-inspector)
+
+## Desktop and MCP
+
+React Native connections require `@buoy-gg/external-sync`. Follow the [Desktop connection guide](https://buoy.gg/buoy/latest/docs/desktop), sign in to Desktop separately, and confirm the selected device. [MCP](https://buoy.gg/buoy/latest/docs/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](https://buoy.gg/buoy/latest/docs/telemetry) for data-flow details.

package/lib/commonjs/detect/detectors.js

@@ -1,351 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.DIRECTIONS = exports.DEAD_END_ATTEMPTS = exports.COVERAGE_MIN_PROBES = void 0;
-exports.computeCoverage = computeCoverage;
-exports.detectDeadEnds = detectDeadEnds;
-exports.detectFlags = detectFlags;
-exports.detectInvisibleStops = detectInvisibleStops;
-exports.detectTraps = detectTraps;
-exports.observedEdges = observedEdges;
-/**
- * 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.
- */
-
-const DIRECTIONS = exports.DIRECTIONS = ["up", "down", "left", "right"];
-
-/** Consecutive failed presses in one direction before it counts as a dead end. */
-const DEAD_END_ATTEMPTS = exports.DEAD_END_ATTEMPTS = 3;
-
-/** Presses before "unvisited" is worth reporting at all — below this it's noise. */
-const COVERAGE_MIN_PROBES = exports.COVERAGE_MIN_PROBES = 12;
-function keyOf(tag, direction) {
-  return `${tag}:${direction}`;
-}
-
-/**
- * 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.
- */
-function detectDeadEnds(probes, nodes, minAttempts = DEAD_END_ATTEMPTS, since = 0) {
-  const trailing = new Map();
-  for (const probe of probes) {
-    if (!probe.resolved || probe.tag === null) continue;
-    if (probe.at < since) continue;
-    const key = keyOf(probe.tag, probe.direction);
-    if (probe.movedTo === null) trailing.set(key, (trailing.get(key) ?? 0) + 1);else trailing.set(key, 0);
-  }
-  const byTag = new Map();
-  for (const node of nodes) byTag.set(node.nativeTag, node);
-  const flags = [];
-  trailing.forEach((attempts, key) => {
-    if (attempts < minAttempts) return;
-    const [tagPart, directionPart] = key.split(":");
-    const tag = Number(tagPart);
-    const direction = directionPart;
-    flags.push({
-      tag,
-      direction,
-      attempts,
-      atEdge: isAtEdge(byTag.get(tag), direction, nodes)
-    });
-  });
-  return flags.sort((a, b) => b.attempts - a.attempts);
-}
-
-/**
- * "The screen ends here" — the one honest reason a direction can legitimately
- * move nothing.
- *
- * This is NOT the viewport test it started as. Abutting the bottom of the
- * WINDOW says nothing inside a ScrollView: the armed focus trap in the TV
- * example sits flush with the viewport bottom at its scroll position, so a
- * geometric edge test excused a real four-way trap as "expected". What actually
- * matters is whether the inventory knows of a focusable further along in that
- * direction — if it does, focus refusing to move is a dead end no matter where
- * the element is drawn.
- *
- * Geometry still only ever DOWNGRADES a flag here, which is the rule for the
- * whole detector layer: it never claims to know where the engine would go.
- */
-function isAtEdge(node, direction, nodes) {
-  const frame = node?.frame;
-  if (!frame) return false;
-  const centerX = frame.x + frame.width / 2;
-  const centerY = frame.y + frame.height / 2;
-  for (const other of nodes) {
-    if (other.nativeTag === node.nativeTag) continue;
-    // Guides are stops, but an invisible one is never the reason a user thinks
-    // "there is more over there" — judge the edge on real content.
-    if (other.guide) continue;
-    const otherFrame = other.frame;
-    if (!otherFrame) continue;
-    const otherX = otherFrame.x + otherFrame.width / 2;
-    const otherY = otherFrame.y + otherFrame.height / 2;
-    switch (direction) {
-      case "up":
-        if (otherY < frame.y) return false;
-        break;
-      case "down":
-        if (otherY > frame.y + frame.height) return false;
-        break;
-      case "left":
-        if (otherX < frame.x) return false;
-        break;
-      case "right":
-        if (otherX > frame.x + frame.width) return false;
-        break;
-    }
-  }
-  return true;
-}
-function unionBox(frames) {
-  if (frames.length === 0) return null;
-  let left = Infinity;
-  let top = Infinity;
-  let right = -Infinity;
-  let bottom = -Infinity;
-  for (const frame of frames) {
-    left = Math.min(left, frame.x);
-    top = Math.min(top, frame.y);
-    right = Math.max(right, frame.x + frame.width);
-    bottom = Math.max(bottom, frame.y + frame.height);
-  }
-  return {
-    x: left,
-    y: top,
-    width: right - left,
-    height: bottom - top
-  };
-}
-function isBeyond(box, point, direction) {
-  switch (direction) {
-    case "up":
-      return point.y < box.y;
-    case "down":
-      return point.y > box.y + box.height;
-    case "left":
-      return point.x < box.x;
-    case "right":
-      return point.x > box.x + box.width;
-    default:
-      return false;
-  }
-}
-
-/** Blocked in at least this many directions before "trap" is the right word. */
-const TRAP_MIN_BLOCKED = 2;
-
-/**
- * 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.
- */
-function detectTraps(deadEnds, nodes) {
-  const byTag = new Map();
-  for (const node of nodes) byTag.set(node.nativeTag, node);
-  const groups = new Map();
-  for (const flag of deadEnds) {
-    const node = byTag.get(flag.tag);
-    const containerTag = node?.guideAncestorTag ?? flag.tag;
-    const group = groups.get(containerTag) ?? {
-      containerTag,
-      tags: new Set(),
-      directions: new Set()
-    };
-    group.tags.add(flag.tag);
-    group.directions.add(flag.direction);
-    groups.set(containerTag, group);
-  }
-  const traps = [];
-  groups.forEach(group => {
-    if (group.directions.size < TRAP_MIN_BLOCKED) return;
-
-    // Everything the container holds, not just the elements we have evidence
-    // about — the box focus is stuck inside is the container's, not the probes'.
-    const members = new Set(group.tags);
-    for (const node of nodes) {
-      if (node.guideAncestorTag === group.containerTag) members.add(node.nativeTag);
-    }
-    members.add(group.containerTag);
-    const container = byTag.get(group.containerTag);
-    const box = container?.guide && container.frame ? container.frame : unionBox(Array.from(members).map(tag => byTag.get(tag)?.frame).filter(frame => !!frame));
-    if (!box) return;
-    let escapable = 0;
-    let reachableOutside = 0;
-    for (const direction of DIRECTIONS) {
-      const hasOutside = nodes.some(node => {
-        if (node.guide || members.has(node.nativeTag) || !node.frame) return false;
-        const center = {
-          x: node.frame.x + node.frame.width / 2,
-          y: node.frame.y + node.frame.height / 2
-        };
-        return isBeyond(box, center, direction);
-      });
-      if (!hasOutside) continue;
-      reachableOutside += 1;
-      if (!group.directions.has(direction)) escapable += 1;
-    }
-    // Nothing outside at all means the container IS the screen.
-    if (reachableOutside === 0 || escapable > 0) return;
-    const guide = container?.guide;
-    const trapped = guide !== undefined && (guide.trap.up || guide.trap.down || guide.trap.left || guide.trap.right);
-    traps.push({
-      tags: Array.from(group.tags).sort((a, b) => a - b),
-      containerTag: group.containerTag,
-      directions: DIRECTIONS.filter(d => group.directions.has(d)),
-      guideTrapTag: trapped ? group.containerTag : undefined
-    });
-  });
-  return traps;
-}
-
-/**
- * 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).
- */
-function detectInvisibleStops(transitions, nodes, since = 0) {
-  const byTag = new Map();
-  for (const node of nodes) byTag.set(node.nativeTag, node);
-  const flags = new Map();
-  for (const transition of transitions) {
-    const tag = transition.toTag;
-    if (tag === null) continue;
-    // A move made before the current scan cannot be judged against the current
-    // inventory: after any navigation EVERY tag from the old screen looks like
-    // a mystery stop, which buried the real flags under a wall of noise on the
-    // first device run. Focus flags are per-screen, and `since` is that screen.
-    if (transition.at < since) continue;
-    const node = byTag.get(tag);
-    const reason = !node ?
-    // Nothing in the inventory: only meaningful once a scan has run at all,
-    // otherwise every transition would be "invisible".
-    nodes.length > 0 ? "unknown" : null : node.guide ? "guide" : null;
-    if (!reason) continue;
-    const existing = flags.get(tag);
-    if (existing) {
-      existing.count += 1;
-      existing.at = transition.at;
-    } else {
-      flags.set(tag, {
-        tag,
-        reason,
-        at: transition.at,
-        count: 1
-      });
-    }
-  }
-  return Array.from(flags.values()).sort((a, b) => b.at - a.at);
-}
-
-/**
- * `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.
- */
-function detectFlags(transitions, probes, nodes, lostCount, since = 0) {
-  const deadEnds = detectDeadEnds(probes, nodes, DEAD_END_ATTEMPTS, since);
-  return {
-    deadEnds,
-    traps: detectTraps(deadEnds, nodes),
-    invisibleStops: detectInvisibleStops(transitions, nodes, since),
-    lostCount
-  };
-}
-
-/**
- * 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.
- */
-function computeCoverage(nodes, visited, transitions, probes) {
-  const visitedSet = new Set(visited);
-  // Guides are counted as focusables (they really are stops), but an unvisited
-  // guide is not a bug — it is the normal case for one that only redirects.
-  const reachableCandidates = nodes.filter(node => !node.guide);
-  const unvisited = reachableCandidates.filter(node => !visitedSet.has(node.nativeTag)).map(node => node.nativeTag);
-  const meaningful = probes.length >= COVERAGE_MIN_PROBES;
-  const edgeTargets = new Set();
-  for (const transition of transitions) {
-    if (transition.toTag !== null) edgeTargets.add(transition.toTag);
-  }
-  const byTag = new Map();
-  for (const node of nodes) byTag.set(node.nativeTag, node);
-  const suspectedUnreachable = meaningful ? unvisited.filter(tag => {
-    if (edgeTargets.has(tag)) return false;
-    const node = byTag.get(tag);
-    if (!node?.frame) return false;
-    // A visited neighbour sitting right next to it means the traversal DID
-    // pass by — so focus skipping it is worth suspecting.
-    return reachableCandidates.some(other => other.nativeTag !== tag && visitedSet.has(other.nativeTag) && isAdjacent(node, other));
-  }) : [];
-  return {
-    focusables: reachableCandidates.length,
-    visited: reachableCandidates.filter(node => visitedSet.has(node.nativeTag)).length,
-    unvisited,
-    suspectedUnreachable,
-    meaningful
-  };
-}
-
-/** Normalized-frame gap within which two elements are plausibly D-pad neighbours. */
-const ADJACENCY_GAP = 0.12;
-function isAdjacent(a, b) {
-  const fa = a.frame;
-  const fb = b.frame;
-  if (!fa || !fb) return false;
-  const horizontalOverlap = fa.x < fb.x + fb.width && fb.x < fa.x + fa.width;
-  const verticalOverlap = fa.y < fb.y + fb.height && fb.y < fa.y + fa.height;
-  if (horizontalOverlap) {
-    const gap = Math.max(fa.y - (fb.y + fb.height), fb.y - (fa.y + fa.height));
-    if (gap <= ADJACENCY_GAP) return true;
-  }
-  if (verticalOverlap) {
-    const gap = Math.max(fa.x - (fb.x + fb.width), fb.x - (fa.x + fa.width));
-    if (gap <= ADJACENCY_GAP) return true;
-  }
-  return false;
-}
-
-/**
- * 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).
- */
-function observedEdges(tag, transitions) {
-  const edges = {};
-  for (const transition of transitions) {
-    if (transition.fromTag !== tag || transition.direction === null) continue;
-    edges[transition.direction] = transition.toTag;
-  }
-  return edges;
-}
-//# sourceMappingURL=detectors.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.DIRECTIONS=exports.DEAD_END_ATTEMPTS=exports.COVERAGE_MIN_PROBES=void 0,exports.computeCoverage=computeCoverage,exports.detectDeadEnds=detectDeadEnds,exports.detectFlags=detectFlags,exports.detectInvisibleStops=detectInvisibleStops,exports.detectTraps=detectTraps,exports.observedEdges=observedEdges;const DIRECTIONS=exports.DIRECTIONS=["up","down","left","right"],DEAD_END_ATTEMPTS=exports.DEAD_END_ATTEMPTS=3,COVERAGE_MIN_PROBES=exports.COVERAGE_MIN_PROBES=12;function keyOf(t,e){return`${t}:${e}`}function detectDeadEnds(t,e,n=DEAD_END_ATTEMPTS,o=0){const r=new Map;for(const e of t){if(!e.resolved||null===e.tag)continue;if(e.at<o)continue;const t=keyOf(e.tag,e.direction);null===e.movedTo?r.set(t,(r.get(t)??0)+1):r.set(t,0)}const a=new Map;for(const t of e)a.set(t.nativeTag,t);const i=[];return r.forEach((t,o)=>{if(t<n)return;const[r,s]=o.split(":"),c=Number(r),d=s;i.push({tag:c,direction:d,attempts:t,atEdge:isAtEdge(a.get(c),d,e)})}),i.sort((t,e)=>e.attempts-t.attempts)}function isAtEdge(t,e,n){const o=t?.frame;if(!o)return!1;o.x,o.width,o.y,o.height;for(const r of n){if(r.nativeTag===t.nativeTag)continue;if(r.guide)continue;const n=r.frame;if(!n)continue;const a=n.x+n.width/2,i=n.y+n.height/2;switch(e){case"up":if(i<o.y)return!1;break;case"down":if(i>o.y+o.height)return!1;break;case"left":if(a<o.x)return!1;break;case"right":if(a>o.x+o.width)return!1}}return!0}function unionBox(t){if(0===t.length)return null;let e=1/0,n=1/0,o=-1/0,r=-1/0;for(const a of t)e=Math.min(e,a.x),n=Math.min(n,a.y),o=Math.max(o,a.x+a.width),r=Math.max(r,a.y+a.height);return{x:e,y:n,width:o-e,height:r-n}}function isBeyond(t,e,n){switch(n){case"up":return e.y<t.y;case"down":return e.y>t.y+t.height;case"left":return e.x<t.x;case"right":return e.x>t.x+t.width;default:return!1}}const TRAP_MIN_BLOCKED=2;function detectTraps(t,e){const n=new Map;for(const t of e)n.set(t.nativeTag,t);const o=new Map;for(const e of t){const t=n.get(e.tag),r=t?.guideAncestorTag??e.tag,a=o.get(r)??{containerTag:r,tags:new Set,directions:new Set};a.tags.add(e.tag),a.directions.add(e.direction),o.set(r,a)}const r=[];return o.forEach(t=>{if(t.directions.size<TRAP_MIN_BLOCKED)return;const o=new Set(t.tags);for(const n of e)n.guideAncestorTag===t.containerTag&&o.add(n.nativeTag);o.add(t.containerTag);const a=n.get(t.containerTag),i=a?.guide&&a.frame?a.frame:unionBox(Array.from(o).map(t=>n.get(t)?.frame).filter(t=>!!t));if(!i)return;let s=0,c=0;for(const n of DIRECTIONS)e.some(t=>{if(t.guide||o.has(t.nativeTag)||!t.frame)return!1;const e={x:t.frame.x+t.frame.width/2,y:t.frame.y+t.frame.height/2};return isBeyond(i,e,n)})&&(c+=1,t.directions.has(n)||(s+=1));if(0===c||s>0)return;const d=a?.guide,f=void 0!==d&&(d.trap.up||d.trap.down||d.trap.left||d.trap.right);r.push({tags:Array.from(t.tags).sort((t,e)=>t-e),containerTag:t.containerTag,directions:DIRECTIONS.filter(e=>t.directions.has(e)),guideTrapTag:f?t.containerTag:void 0})}),r}function detectInvisibleStops(t,e,n=0){const o=new Map;for(const t of e)o.set(t.nativeTag,t);const r=new Map;for(const a of t){const t=a.toTag;if(null===t)continue;if(a.at<n)continue;const i=o.get(t),s=i?i.guide?"guide":null:e.length>0?"unknown":null;if(!s)continue;const c=r.get(t);c?(c.count+=1,c.at=a.at):r.set(t,{tag:t,reason:s,at:a.at,count:1})}return Array.from(r.values()).sort((t,e)=>e.at-t.at)}function detectFlags(t,e,n,o,r=0){const a=detectDeadEnds(e,n,DEAD_END_ATTEMPTS,r);return{deadEnds:a,traps:detectTraps(a,n),invisibleStops:detectInvisibleStops(t,n,r),lostCount:o}}function computeCoverage(t,e,n,o){const r=new Set(e),a=t.filter(t=>!t.guide),i=a.filter(t=>!r.has(t.nativeTag)).map(t=>t.nativeTag),s=o.length>=COVERAGE_MIN_PROBES,c=new Set;for(const t of n)null!==t.toTag&&c.add(t.toTag);const d=new Map;for(const e of t)d.set(e.nativeTag,e);const f=s?i.filter(t=>{if(c.has(t))return!1;const e=d.get(t);return!!e?.frame&&a.some(n=>n.nativeTag!==t&&r.has(n.nativeTag)&&isAdjacent(e,n))}):[];return{focusables:a.length,visited:a.filter(t=>r.has(t.nativeTag)).length,unvisited:i,suspectedUnreachable:f,meaningful:s}}const ADJACENCY_GAP=.12;function isAdjacent(t,e){const n=t.frame,o=e.frame;if(!n||!o)return!1;const r=n.x<o.x+o.width&&o.x<n.x+n.width,a=n.y<o.y+o.height&&o.y<n.y+n.height;return!!(r&&Math.max(n.y-(o.y+o.height),o.y-(n.y+n.height))<=ADJACENCY_GAP)||!!(a&&Math.max(n.x-(o.x+o.width),o.x-(n.x+n.width))<=ADJACENCY_GAP)}function observedEdges(t,e){const n={};for(const o of e)o.fromTag===t&&null!==o.direction&&(n[o.direction]=o.toTag);return n}

package/lib/commonjs/index.js

@@ -1,106 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "clearHistory", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.clearHistory;
-  }
-});
-Object.defineProperty(exports, "computeCoverage", {
-  enumerable: true,
-  get: function () {
-    return _detectors.computeCoverage;
-  }
-});
-Object.defineProperty(exports, "detectDeadEnds", {
-  enumerable: true,
-  get: function () {
-    return _detectors.detectDeadEnds;
-  }
-});
-Object.defineProperty(exports, "detectFlags", {
-  enumerable: true,
-  get: function () {
-    return _detectors.detectFlags;
-  }
-});
-Object.defineProperty(exports, "detectInvisibleStops", {
-  enumerable: true,
-  get: function () {
-    return _detectors.detectInvisibleStops;
-  }
-});
-Object.defineProperty(exports, "detectTraps", {
-  enumerable: true,
-  get: function () {
-    return _detectors.detectTraps;
-  }
-});
-Object.defineProperty(exports, "focusInspectorSyncAdapter", {
-  enumerable: true,
-  get: function () {
-    return _focusInspectorSyncAdapter.focusInspectorSyncAdapter;
-  }
-});
-Object.defineProperty(exports, "getState", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.getState;
-  }
-});
-Object.defineProperty(exports, "observedEdges", {
-  enumerable: true,
-  get: function () {
-    return _detectors.observedEdges;
-  }
-});
-Object.defineProperty(exports, "recordBlur", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.recordBlur;
-  }
-});
-Object.defineProperty(exports, "recordFocus", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.recordFocus;
-  }
-});
-Object.defineProperty(exports, "recordKey", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.recordKey;
-  }
-});
-Object.defineProperty(exports, "resetStore", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.resetStore;
-  }
-});
-Object.defineProperty(exports, "scanFocusables", {
-  enumerable: true,
-  get: function () {
-    return _focusableScanner.scanFocusables;
-  }
-});
-Object.defineProperty(exports, "setTracking", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.setTracking;
-  }
-});
-Object.defineProperty(exports, "subscribe", {
-  enumerable: true,
-  get: function () {
-    return _focusStore.subscribe;
-  }
-});
-var _focusInspectorSyncAdapter = require("./sync/focusInspectorSyncAdapter");
-var _focusStore = require("./store/focusStore");
-var _focusableScanner = require("./scan/focusableScanner");
-var _detectors = require("./detect/detectors");
-//# sourceMappingURL=index.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"clearHistory",{enumerable:!0,get:function(){return _focusStore.clearHistory}}),Object.defineProperty(exports,"computeCoverage",{enumerable:!0,get:function(){return _detectors.computeCoverage}}),Object.defineProperty(exports,"detectDeadEnds",{enumerable:!0,get:function(){return _detectors.detectDeadEnds}}),Object.defineProperty(exports,"detectFlags",{enumerable:!0,get:function(){return _detectors.detectFlags}}),Object.defineProperty(exports,"detectInvisibleStops",{enumerable:!0,get:function(){return _detectors.detectInvisibleStops}}),Object.defineProperty(exports,"detectTraps",{enumerable:!0,get:function(){return _detectors.detectTraps}}),Object.defineProperty(exports,"focusInspectorSyncAdapter",{enumerable:!0,get:function(){return _focusInspectorSyncAdapter.focusInspectorSyncAdapter}}),Object.defineProperty(exports,"getState",{enumerable:!0,get:function(){return _focusStore.getState}}),Object.defineProperty(exports,"observedEdges",{enumerable:!0,get:function(){return _detectors.observedEdges}}),Object.defineProperty(exports,"recordBlur",{enumerable:!0,get:function(){return _focusStore.recordBlur}}),Object.defineProperty(exports,"recordFocus",{enumerable:!0,get:function(){return _focusStore.recordFocus}}),Object.defineProperty(exports,"recordKey",{enumerable:!0,get:function(){return _focusStore.recordKey}}),Object.defineProperty(exports,"resetStore",{enumerable:!0,get:function(){return _focusStore.resetStore}}),Object.defineProperty(exports,"scanFocusables",{enumerable:!0,get:function(){return _focusableScanner.scanFocusables}}),Object.defineProperty(exports,"setTracking",{enumerable:!0,get:function(){return _focusStore.setTracking}}),Object.defineProperty(exports,"subscribe",{enumerable:!0,get:function(){return _focusStore.subscribe}});var _focusInspectorSyncAdapter=require("./sync/focusInspectorSyncAdapter"),_focusStore=require("./store/focusStore"),_focusableScanner=require("./scan/focusableScanner"),_detectors=require("./detect/detectors");