@buoy-gg/focus-inspector 7.0.35 → 7.0.38

package/lib/module/detect/detectors.js

@@ -1,341 +1 @@
-"use strict";
-
-/**
- * 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.
- */
-
-export const DIRECTIONS = ["up", "down", "left", "right"];
-
-/** Consecutive failed presses in one direction before it counts as a dead end. */
-export const DEAD_END_ATTEMPTS = 3;
-
-/** Presses before "unvisited" is worth reporting at all — below this it's noise. */
-export const 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.
- */
-export 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.
- */
-export 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).
- */
-export 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.
- */
-export 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.
- */
-export 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).
- */
-export 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";export const DIRECTIONS=["up","down","left","right"];export const DEAD_END_ATTEMPTS=3;export const COVERAGE_MIN_PROBES=12;function keyOf(t,e){return`${t}:${e}`}export function detectDeadEnds(t,e,n=3,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),f=s;i.push({tag:c,direction:f,attempts:t,atEdge:isAtEdge(a.get(c),f,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;export 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<2)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 f=a?.guide,u=void 0!==f&&(f.trap.up||f.trap.down||f.trap.left||f.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:u?t.containerTag:void 0})}),r}export 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)}export function detectFlags(t,e,n,o,r=0){const a=detectDeadEnds(e,n,3,r);return{deadEnds:a,traps:detectTraps(a,n),invisibleStops:detectInvisibleStops(t,n,r),lostCount:o}}export 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>=12,c=new Set;for(const t of n)null!==t.toTag&&c.add(t.toTag);const f=new Map;for(const e of t)f.set(e.nativeTag,e);const u=s?i.filter(t=>{if(c.has(t))return!1;const e=f.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:u,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)}export 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/module/index.js

@@ -1,36 +1 @@
-"use strict";
-
-/**
- * @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.
- */
-
-// =============================================================================
-// EXTERNAL SYNC (device → desktop dashboard)
-// =============================================================================
-export { focusInspectorSyncAdapter } from "./sync/focusInspectorSyncAdapter";
-// =============================================================================
-// STORE (the recorded stream + its types)
-// =============================================================================
-export { clearHistory, getState, recordBlur, recordFocus, recordKey, resetStore, setTracking, subscribe } from "./store/focusStore";
-// =============================================================================
-// SCAN + DETECT (exported so the desktop panel shares one set of types)
-// =============================================================================
-export { scanFocusables } from "./scan/focusableScanner";
-export { computeCoverage, detectDeadEnds, detectFlags, detectInvisibleStops, detectTraps, observedEdges } from "./detect/detectors";
-//# sourceMappingURL=index.js.map
+"use strict";export{focusInspectorSyncAdapter}from"./sync/focusInspectorSyncAdapter";export{clearHistory,getState,recordBlur,recordFocus,recordKey,resetStore,setTracking,subscribe}from"./store/focusStore";export{scanFocusables}from"./scan/focusableScanner";export{computeCoverage,detectDeadEnds,detectFlags,detectInvisibleStops,detectTraps,observedEdges}from"./detect/detectors";

package/lib/module/observe/focusEventObserver.js

@@ -1,99 +1 @@
-"use strict";
-
-/**
- * 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.
- */
-
-import { recordBlur, recordFocus } from "../store/focusStore";
-import { resolveRawEventEmitter } from "./rawEventEmitter";
-let emitter = null;
-let emitterResolved = false;
-let subscriptions = [];
-let status = "idle";
-let unavailableReason = null;
-function getEmitter() {
-  if (emitterResolved) return emitter;
-  emitterResolved = true;
-  const resolution = resolveRawEventEmitter();
-  emitter = resolution.emitter;
-  unavailableReason = resolution.reason;
-  return emitter;
-}
-
-/**
- * Pull the native tag out of a raw event. Fabric puts it on `nativeEvent.target`
- * on both platforms (probe-verified); `nativeEvent.tag` is the older shape and
- * costs nothing to accept.
- */
-function tagOf(event) {
-  const native = event?.nativeEvent;
-  if (!native) return null;
-  const target = native.target ?? native.tag;
-  return typeof target === "number" && Number.isFinite(target) ? target : null;
-}
-export function attachFocusObserver() {
-  if (subscriptions.length > 0) return;
-  const raw = getEmitter();
-  if (!raw) {
-    status = "unavailable";
-    return;
-  }
-  try {
-    // Two named listeners rather than the `*` wildcard channel: the wildcard
-    // exists, but its payload contract was never runtime-verified, and named
-    // channels sidestep the question entirely.
-    subscriptions = [raw.addListener("topFocus", event => {
-      const tag = tagOf(event);
-      if (tag !== null) recordFocus(tag);
-    }), raw.addListener("topBlur", event => {
-      const tag = tagOf(event);
-      if (tag !== null) recordBlur(tag);
-    })];
-    status = "listening";
-  } catch (e) {
-    subscriptions = [];
-    status = "unavailable";
-    unavailableReason = e?.message ?? "addListener failed";
-  }
-}
-export function detachFocusObserver() {
-  subscriptions.forEach(subscription => {
-    try {
-      subscription.remove();
-    } catch {
-      /* a listener that's already gone is fine */
-    }
-  });
-  subscriptions = [];
-  if (status === "listening") status = "idle";
-}
-export function getFocusObserverStatus() {
-  return {
-    status,
-    reason: status === "unavailable" ? unavailableReason : null
-  };
-}
-//# sourceMappingURL=focusEventObserver.js.map
+"use strict";import{recordBlur,recordFocus}from"../store/focusStore";import{resolveRawEventEmitter}from"./rawEventEmitter";let emitter=null,emitterResolved=!1,subscriptions=[],status="idle",unavailableReason=null;function getEmitter(){if(emitterResolved)return emitter;emitterResolved=!0;const t=resolveRawEventEmitter();return emitter=t.emitter,unavailableReason=t.reason,emitter}function tagOf(t){const e=t?.nativeEvent;if(!e)return null;const s=e.target??e.tag;return"number"==typeof s&&Number.isFinite(s)?s:null}export function attachFocusObserver(){if(subscriptions.length>0)return;const t=getEmitter();if(t)try{subscriptions=[t.addListener("topFocus",t=>{const e=tagOf(t);null!==e&&recordFocus(e)}),t.addListener("topBlur",t=>{const e=tagOf(t);null!==e&&recordBlur(e)})],status="listening"}catch(t){subscriptions=[],status="unavailable",unavailableReason=t?.message??"addListener failed"}else status="unavailable"}export function detachFocusObserver(){subscriptions.forEach(t=>{try{t.remove()}catch{}}),subscriptions=[],"listening"===status&&(status="idle")}export function getFocusObserverStatus(){return{status:status,reason:"unavailable"===status?unavailableReason:null}}

package/lib/module/observe/keyEventObserver.js

@@ -1,86 +1 @@
-"use strict";
-
-/**
- * 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.
- */
-
-import * as ReactNative from "react-native";
-import { recordBlur, recordFocus, recordKey } from "../store/focusStore";
-/**
- * `TVEventHandler` only exists on the react-native-tvos fork. A namespace read
- * (rather than a named import) keeps this module importable on stock RN.
- */
-const RN = ReactNative;
-export const isTV = RN.Platform?.isTV === true;
-export const platformOS = RN.Platform?.OS ?? "unknown";
-
-/**
- * Long-press variants move focus the same way a tap does, so they map to the
- * same direction. Everything else (select, menu, playPause, pans, swipes) never
- * moves focus and is dropped rather than logged as a probe that can't resolve.
- */
-const DIRECTION_BY_EVENT_TYPE = {
-  up: "up",
-  down: "down",
-  left: "left",
-  right: "right",
-  longUp: "up",
-  longDown: "down",
-  longLeft: "left",
-  longRight: "right"
-};
-let subscription = null;
-function handleEvent(raw) {
-  const event = raw;
-  const eventType = event?.eventType;
-  if (typeof eventType !== "string") return;
-
-  /**
-   * Dedupe by ignoring key DOWN, never key UP. tvOS emits keyAction 1 (up)
-   * ONLY for button presses — filtering to "down" would swallow every tvOS
-   * event — while Android's key-down dispatch sits behind a feature flag that
-   * is off by default. One press must open exactly one probe.
-   */
-  if (event?.eventKeyAction === 0) return;
-
-  // 0.83-line iOS bonus: tagged focus/blur HWEvents. Guarded on the tag being
-  // present so 0.85's tag-less variants (if any ever return) can't record a
-  // transition to nowhere.
-  if (eventType === "focus" || eventType === "blur") {
-    if (typeof event?.tag !== "number") return;
-    if (eventType === "focus") recordFocus(event.tag);else recordBlur(event.tag);
-    return;
-  }
-  const direction = DIRECTION_BY_EVENT_TYPE[eventType];
-  if (direction) recordKey(direction);
-}
-export function attachKeyObserver() {
-  if (subscription || !isTV || !RN.TVEventHandler) return;
-  subscription = RN.TVEventHandler.addListener(handleEvent);
-}
-export function detachKeyObserver() {
-  if (!subscription) return;
-  try {
-    subscription.remove();
-  } catch {
-    /* already gone */
-  }
-  subscription = null;
-}
-export function isKeyObserverListening() {
-  return subscription !== null;
-}
-//# sourceMappingURL=keyEventObserver.js.map
+"use strict";import*as ReactNative from"react-native";import{recordBlur,recordFocus,recordKey}from"../store/focusStore";const RN=ReactNative;export const isTV=!0===RN.Platform?.isTV;export const platformOS=RN.Platform?.OS??"unknown";const DIRECTION_BY_EVENT_TYPE={up:"up",down:"down",left:"left",right:"right",longUp:"up",longDown:"down",longLeft:"left",longRight:"right"};let subscription=null;function handleEvent(t){const e=t,r=e?.eventType;if("string"!=typeof r)return;if(0===e?.eventKeyAction)return;if("focus"===r||"blur"===r){if("number"!=typeof e?.tag)return;return void("focus"===r?recordFocus(e.tag):recordBlur(e.tag))}const n=DIRECTION_BY_EVENT_TYPE[r];n&&recordKey(n)}export function attachKeyObserver(){!subscription&&isTV&&RN.TVEventHandler&&(subscription=RN.TVEventHandler.addListener(handleEvent))}export function detachKeyObserver(){if(subscription){try{subscription.remove()}catch{}subscription=null}}export function isKeyObserverListening(){return null!==subscription}

package/lib/module/observe/rawEventEmitter.js

@@ -1,40 +1 @@
-"use strict";
-
-/**
- * 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 function resolveRawEventEmitter() {
-  let mod;
-  try {
-    mod = require("react-native/Libraries/Core/RawEventEmitter");
-  } catch (e) {
-    return {
-      emitter: null,
-      reason: e?.message ?? "RawEventEmitter is unavailable"
-    };
-  }
-  const candidate = mod?.default ?? mod;
-  if (typeof candidate?.addListener !== "function") {
-    return {
-      emitter: null,
-      reason: "RawEventEmitter has no addListener"
-    };
-  }
-  return {
-    emitter: candidate,
-    reason: null
-  };
-}
-//# sourceMappingURL=rawEventEmitter.js.map
+"use strict";export function resolveRawEventEmitter(){let e;try{e=require("react-native/Libraries/Core/RawEventEmitter")}catch(e){return{emitter:null,reason:e?.message??"RawEventEmitter is unavailable"}}const t=e?.default??e;return"function"!=typeof t?.addListener?{emitter:null,reason:"RawEventEmitter has no addListener"}:{emitter:t,reason:null}}