@userflow-tech/react-native 0.4.5 → 0.6.0

package/src/anchors/elementTargetMatch.ts

@@ -26,19 +26,46 @@ export function anchorIdsAboveTap(tap: ElementTap): ReadonlySet<string> {
   const ids = new Set<string>();
   let current: AnyFiber = tap.targetFiber;
   for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
-    const props = getMemoizedProps(current);
-    if (props) {
-      for (const tier of ANCHOR_PROP_TIERS) {
-        const value = props[tier];
-        if (typeof value === 'string') ids.add(value);
-      }
-    }
+    collectAnchorIds(current, ids);
     current = getReturn(current);
   }
   anchorIdsByTap.set(tap, ids);
   return ids;
 }
 
+/**
+ * The fiber on `start` (or an ancestor) that carries `anchorId`.
+ *
+ * The touch-start fiber is kept after the press navigates away, so a click can
+ * still match when a live scan of the new screen no longer finds the id.
+ */
+export function fiberBearingAnchorId(start: AnyFiber, anchorId: string): AnyFiber | null {
+  let current: AnyFiber = start;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (fiberHasAnchorId(current, anchorId)) return current;
+    current = getReturn(current);
+  }
+  return null;
+}
+
+function fiberHasAnchorId(fiber: AnyFiber, anchorId: string): boolean {
+  const props = getMemoizedProps(fiber);
+  if (!props) return false;
+  for (const tier of ANCHOR_PROP_TIERS) {
+    if (props[tier] === anchorId) return true;
+  }
+  return false;
+}
+
+function collectAnchorIds(fiber: AnyFiber, ids: Set<string>): void {
+  const props = getMemoizedProps(fiber);
+  if (!props) return;
+  for (const tier of ANCHOR_PROP_TIERS) {
+    const value = props[tier];
+    if (typeof value === 'string') ids.add(value);
+  }
+}
+
 export function sameFiber(a: AnyFiber, b: AnyFiber): boolean {
   if (a == null || b == null) return false;
   if (a === b) return true;

package/src/anchors/fiber/FiberScanRootStore.ts

@@ -28,6 +28,14 @@ class FiberScanRootStore {
     return resolveCurrentFiber(fiber);
   }
 
+  /**
+   * Mounted scan-root instance. Font detection caches against this identity
+   * so a remount scans again and an update of the same root does not.
+   */
+  getInstance(): unknown {
+    return this.instance;
+  }
+
   subscribe(listener: Listener): () => void {
     this.listeners.add(listener);
     return () => {

package/src/anchors/fiber/detectAppFontFamily.ts

@@ -0,0 +1,400 @@
+/**
+ * Host-app font used when a theme is still on the default CSS stack.
+ *
+ * React Native does not inherit `fontFamily` from a parent view, so the family
+ * actually in use is the one set on `Text`. The primary font is whichever
+ * family appears on the most visible host text under the scan root (the SDK
+ * overlay is a sibling and is not walked). Embedded banners are inside that
+ * root; their hosts use a `userflow-` testID and are not votes, or the bar's
+ * own text would win. Text with no family counts as the platform font. Icon
+ * faces are not content. Nested text with no family does not vote: the
+ * ancestor text already does, and a child run must not add another vote for
+ * that family or for the platform font.
+ *
+ * A finished walk is cached until the visible screen changes, the reported
+ * screen changes, or `Userflow.reset()`. A walk that hits the node cap is not
+ * cached. Failures return null.
+ */
+import { getCurrentScreenLocation } from '../../screenTracker';
+
+import { fiberScanRoot } from './FiberScanRootStore';
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getHostTypeName,
+  getLiveHostProps,
+  getReturn,
+  getStateNode,
+} from './fiberInternals';
+import { isFiberOnVisibleScreen, isScreenHostFiber } from './visibleScreens';
+import { walkVisibleFibers } from './walkVisibleFibers';
+
+const TEXT_HOST_NAMES = new Set(['Text', 'RCTText', 'RCTVirtualText']);
+
+/** SDK hosts inside the scan root (embedded banners). Not the app's font. */
+const SDK_HOST_TEST_ID_PREFIX = 'userflow-';
+
+/** Cycle guard for nested-text inheritance. Real trees are only a few levels deep. */
+const MAX_FONT_ANCESTORS = 50;
+
+const CSS_GENERIC_FAMILIES = new Set([
+  'sans-serif',
+  'serif',
+  'monospace',
+  'system-ui',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'cursive',
+  'fantasy',
+  'emoji',
+  'math',
+  'fangsong',
+  'inherit',
+  'initial',
+  'unset',
+]);
+
+/** Short vector-icon families. Matched after stripping spaces and punctuation. */
+const ICON_FONT_EXACT = new Set([
+  'feather',
+  'antdesign',
+  'entypo',
+  'fontisto',
+  'simplelineicons',
+  'octicons',
+  'zocial',
+  'foundation',
+  'evilicons',
+]);
+
+interface FontCache {
+  instance: object;
+  /** null: countable text voted for the platform font, or nothing voted. */
+  family: string | null;
+  /** Visible screens this tally belongs to. Empty when the tree has none. */
+  screens: AnyFiber[];
+  /** `updateScreen` / router identity at tally time. Null before the first report. */
+  screenKey: string | null;
+}
+
+let cache: FontCache | null = null;
+
+/** Drop the cached app font. Called from `Userflow.reset()`. */
+export function resetDetectedAppFont(): void {
+  cache = null;
+}
+
+/**
+ * Family to apply, or null when the app font is the platform face or could
+ * not be read. Never throws.
+ */
+export function detectAppFontFamily(): string | null {
+  try {
+    const instance = fiberScanRoot.getInstance();
+    if (!instance || typeof instance !== 'object') return null;
+
+    const root = fiberScanRoot.getFiber();
+    if (!root) return null;
+    if (cache?.instance === instance && cacheStillCurrent(cache, root)) return cache.family;
+
+    const tally = tallyHostText(root);
+    if (tally.truncated) {
+      if (!tally.voted) return null;
+      return pickMajority(tally.counts);
+    }
+
+    const family = tally.voted ? pickMajority(tally.counts) : null;
+    cache = { instance, family, screens: tally.screens, screenKey: reportedScreenKey() };
+    return family;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Faces that appear in the builder's default system stack. A comma-separated
+ * list made only of these and generic keywords is that default, not a custom
+ * font. A single concrete name is still kept, including `Roboto`.
+ */
+const DEFAULT_STACK_FACES = new Set([
+  'blinkmacsystemfont',
+  'segoe ui',
+  'roboto',
+  'helvetica',
+  'arial',
+  'apple color emoji',
+  'segoe ui emoji',
+  'segoe ui symbol',
+]);
+
+/**
+ * A single React Native family name. CSS stacks and generic keywords are not
+ * usable as a host `fontFamily` — RN treats the whole string as one face.
+ * Theme stacks are parsed by {@link themeConcreteFontFamily}.
+ */
+export function concreteFontFamily(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const name = unwrapFontName(value);
+  if (!name || name.includes(',') || name.startsWith('-')) return undefined;
+  if (CSS_GENERIC_FAMILIES.has(name.toLowerCase())) return undefined;
+  return name;
+}
+
+/**
+ * Family a theme author chose. A single concrete name is kept. A comma-separated
+ * list keeps the first family that is not a generic or a default-stack face,
+ * so `"Source Sans Pro", sans-serif` stays Source Sans Pro and the system
+ * stack still resolves to undefined.
+ */
+export function themeConcreteFontFamily(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const parts = splitCssFamilies(value);
+  if (parts.length === 0) return undefined;
+  if (parts.length === 1) return concreteFontFamily(parts[0]);
+  for (const part of parts) {
+    const name = concreteFontFamily(part);
+    if (!name || DEFAULT_STACK_FACES.has(name.toLowerCase())) continue;
+    return name;
+  }
+  return undefined;
+}
+
+/**
+ * Split a CSS `font-family` list. A quote that opens a family is wrapping and
+ * is removed; a quote inside a name stays, so `Foo"Bar` is one family.
+ * Commas inside wrapping quotes are not separators.
+ */
+export function splitCssFamilies(value: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+  for (const char of value) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+      continue;
+    }
+    if ((char === '"' || char === "'") && current.trim() === '') {
+      quote = char;
+      continue;
+    }
+    if (char === ',') {
+      const name = current.trim();
+      if (name) parts.push(name);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  const name = current.trim();
+  if (name) parts.push(name);
+  return parts;
+}
+
+/** Generic keywords and vendor-prefixed faces stay unquoted in CSS. */
+export function isBareCssFamily(name: string): boolean {
+  return name.startsWith('-') || CSS_GENERIC_FAMILIES.has(name.toLowerCase());
+}
+
+export function isIconFontFamily(name: string): boolean {
+  const key = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (ICON_FONT_EXACT.has(key)) return true;
+  return (
+    key.startsWith('fontawesome') ||
+    key.startsWith('ionicons') ||
+    key.startsWith('materialcommunityicons') ||
+    key.startsWith('materialicons') ||
+    key.startsWith('materialsymbols')
+  );
+}
+
+interface Tally {
+  voted: boolean;
+  truncated: boolean;
+  screens: AnyFiber[];
+  counts: Map<string | null, number>;
+}
+
+function tallyHostText(root: AnyFiber): Tally {
+  const counts = new Map<string | null, number>();
+  const screens: AnyFiber[] = [];
+  let voted = false;
+  const { truncated } = walkVisibleFibers(root, (fiber) => {
+    try {
+      if (isScreenHostFiber(fiber)) screens.push(fiber);
+      if (!isTextHost(fiber)) return;
+      const vote = voteFor(fiber, root);
+      if (vote === 'skip') return;
+      voted = true;
+      counts.set(vote, (counts.get(vote) ?? 0) + 1);
+    } catch {
+      // One unreadable node is not a vote.
+    }
+  });
+  return { voted, truncated, screens, counts };
+}
+
+/** Usable family, null for the platform font, or skip for an icon face. */
+function voteFor(fiber: AnyFiber, root: AnyFiber): string | null | 'skip' {
+  if (isUnderSdkHost(fiber, root)) return 'skip';
+  const own = classifyFamily(readFontFamily(fiber));
+  if (own.kind === 'icon') return 'skip';
+  if (own.kind === 'family') return own.name;
+  if (own.kind === 'unusable') return null;
+  // No family of its own. The ancestor text node casts the vote for this run.
+  if (hasAncestorText(fiber, root)) return 'skip';
+  return null;
+}
+
+function hasAncestorText(fiber: AnyFiber, root: AnyFiber): boolean {
+  let parent = getReturn(fiber);
+  for (let depth = 0; parent && parent !== root && depth < MAX_FONT_ANCESTORS; depth += 1) {
+    if (isTextHost(parent)) return true;
+    parent = getReturn(parent);
+  }
+  return false;
+}
+
+function cacheStillCurrent(cached: FontCache, root: AnyFiber): boolean {
+  if (cached.screenKey !== reportedScreenKey()) return false;
+  if (cached.screens.length === 0) return true;
+  return cached.screens.every((screen) => screenStillCurrent(screen, root));
+}
+
+function screenStillCurrent(screen: AnyFiber, root: AnyFiber): boolean {
+  if (!isFiberOnVisibleScreen(screen)) return false;
+  let current: AnyFiber = screen;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (current === root) return true;
+    current = getReturn(current);
+  }
+  return false;
+}
+
+function reportedScreenKey(): string | null {
+  const location = getCurrentScreenLocation();
+  if (!location) return null;
+  const key = 'path' in location ? location.path : location.screen;
+  return key || null;
+}
+
+type Classified =
+  | { kind: 'absent' }
+  | { kind: 'icon' }
+  | { kind: 'family'; name: string }
+  | { kind: 'unusable' };
+
+function classifyFamily(raw: string | undefined): Classified {
+  if (!raw) return { kind: 'absent' };
+  if (isIconFontFamily(raw)) return { kind: 'icon' };
+  const concrete = concreteFontFamily(raw);
+  if (!concrete) return { kind: 'unusable' };
+  return { kind: 'family', name: concrete };
+}
+
+function pickMajority(counts: Map<string | null, number>): string | null {
+  const platform = counts.get(null) ?? 0;
+  let bestName: string | null = null;
+  let bestCount = 0;
+  for (const [name, count] of counts) {
+    if (name == null) continue;
+    if (bestName == null || count > bestCount || (count === bestCount && name < bestName)) {
+      bestName = name;
+      bestCount = count;
+    }
+  }
+  if (bestName == null || platform > bestCount) return null;
+  return bestName;
+}
+
+function isUnderSdkHost(fiber: AnyFiber, root: AnyFiber): boolean {
+  let parent = getReturn(fiber);
+  for (let depth = 0; parent && parent !== root && depth < MAX_FONT_ANCESTORS; depth += 1) {
+    try {
+      const testID = getLiveHostProps(parent)?.testID;
+      if (typeof testID === 'string' && testID.startsWith(SDK_HOST_TEST_ID_PREFIX)) {
+        return true;
+      }
+    } catch {
+      // An unreadable ancestor is not an SDK host.
+    }
+    parent = getReturn(parent);
+  }
+  return false;
+}
+
+function isTextHost(fiber: AnyFiber): boolean {
+  const typeName = getHostTypeName(fiber);
+  if (typeName && TEXT_HOST_NAMES.has(typeName)) return true;
+  const elementType = fiber?.elementType;
+  if (typeof elementType === 'string' && TEXT_HOST_NAMES.has(elementType)) return true;
+  try {
+    const node = getStateNode(fiber) as {
+      viewConfig?: { uiViewClassName?: unknown };
+      __viewConfig?: { uiViewClassName?: unknown };
+    } | null;
+    const className = node?.viewConfig?.uiViewClassName ?? node?.__viewConfig?.uiViewClassName;
+    return typeof className === 'string' && TEXT_HOST_NAMES.has(className);
+  } catch {
+    return false;
+  }
+}
+
+function readFontFamily(fiber: AnyFiber): string | undefined {
+  try {
+    const flat = flattenFontStyle(getLiveHostProps(fiber)?.style);
+    const family = flat?.fontFamily;
+    if (typeof family !== 'string') return undefined;
+    const trimmed = family.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function flattenFontStyle(style: unknown): { fontFamily?: unknown } | null {
+  if (style == null || style === false) return null;
+  if (typeof style === 'number') return flattenRegisteredStyle(style);
+  if (Array.isArray(style)) {
+    let family: unknown;
+    for (const entry of style) {
+      const flat = flattenFontStyle(entry);
+      if (flat && flat.fontFamily != null) family = flat.fontFamily;
+    }
+    return { fontFamily: family };
+  }
+  if (typeof style === 'object') return style as { fontFamily?: unknown };
+  return null;
+}
+
+/**
+ * StyleSheet ids are numbers. Resolve them only when one shows up so tests
+ * that pass plain style objects do not load react-native.
+ */
+function flattenRegisteredStyle(styleId: number): { fontFamily?: unknown } | null {
+  try {
+    // Lazy require so unit tests that pass plain style objects do not load RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const { StyleSheet } = require('react-native') as {
+      StyleSheet?: { flatten?: (style: number) => { fontFamily?: unknown } | null | undefined };
+    };
+    const flat = StyleSheet?.flatten?.(styleId);
+    return flat ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function unwrapFontName(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1).trim();
+    }
+  }
+  return trimmed;
+}

package/src/anchors/fiber/fiberInternals.ts

@@ -319,6 +319,74 @@ export function resolveCurrentFiber(fiber: AnyFiber): AnyFiber {
   return fiber;
 }
 
+/** Where a fiber sits: its tree's current fiber, and whether it is under it. */
+interface TreePlace {
+  current: AnyFiber;
+  inTree: boolean;
+}
+
+/**
+ * {@link resolveCurrentFiber} for many fibers in one synchronous pass. Where
+ * each ancestor sits is remembered, so the pass walks every ancestor once
+ * instead of once per fiber below it. Discard it when the pass ends: a render
+ * moves `return` pointers.
+ */
+export function createCurrentFiberResolver(): (fiber: AnyFiber) => AnyFiber {
+  const placeOf = new Map<object, TreePlace | null>();
+
+  const locate = (fiber: AnyFiber): TreePlace | null => {
+    const path: AnyFiber[] = [];
+    let above: TreePlace | null = null;
+    let cur: AnyFiber = fiber;
+    for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      const known = placeOf.get(cur);
+      if (known !== undefined) {
+        above = known;
+        break;
+      }
+      path.push(cur);
+      // Only a HostRoot (or a detached fiber) has no parent, so the tag is
+      // read once, at the top, not at every step.
+      const parent = getReturn(cur);
+      if (!parent) {
+        const rootState =
+          getFiberTag(cur) === HOST_ROOT_TAG
+            ? (getStateNode(cur) as { current?: AnyFiber } | null)
+            : null;
+        above = rootState?.current ? { current: rootState.current, inTree: false } : null;
+        break;
+      }
+      cur = parent;
+    }
+    // Top down: a fiber is in the current tree when the current fiber is it
+    // or one of its ancestors.
+    let place = above;
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+      if (place && !place.inTree && path[i] === place.current) {
+        place = { current: place.current, inTree: true };
+      }
+      placeOf.set(path[i], place);
+    }
+    return place;
+  };
+
+  return (fiber) => {
+    if (!fiber) return fiber;
+    try {
+      const alternate = getAlternate(fiber);
+      if (!alternate) return fiber;
+      const own = locate(fiber);
+      if (!own || own.inTree) return fiber;
+      const other = locate(alternate);
+      // Two trees for one pair only happens on a corrupt graph.
+      if (!other || other.current !== own.current) return resolveCurrentFiber(fiber);
+      return other.inTree ? alternate : fiber;
+    } catch {
+      return fiber;
+    }
+  };
+}
+
 function isInTree(fiber: AnyFiber, root: AnyFiber): boolean {
   let cur: AnyFiber = fiber;
   for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {

package/src/anchors/fiber/indexHostFibers.ts

@@ -111,13 +111,18 @@ export function createLazyHostFiberIndex(
 
 /**
  * Fiber for a public instance: direct pointer first, then the scan-root index
- * by identity / native tag.
+ * by identity / native tag. Pass a `createCurrentFiberResolver()` resolver when
+ * looking up many instances in one pass.
  */
-export function lookupHostFiber(index: HostFiberIndexSource, instance: unknown): AnyFiber | null {
+export function lookupHostFiber(
+  index: HostFiberIndexSource,
+  instance: unknown,
+  resolveCurrent: (fiber: AnyFiber) => AnyFiber = resolveCurrentFiber,
+): AnyFiber | null {
   const direct = fiberFromPublicInstance(instance);
   if (direct) {
     try {
-      return resolveCurrentFiber(direct);
+      return resolveCurrent(direct);
     } catch {
       return direct;
     }

package/src/anchors/fiber/resolveFiberPath.ts

@@ -31,10 +31,13 @@ import { walkVisibleFibers } from './walkVisibleFibers';
 const MIN_SCORE = 40;
 const UNIQUENESS_MARGIN = 12;
 
+/** Why a fiber path did not resolve. Element conditions map these differently. */
+export type FiberPathMissReason = 'empty' | 'no-root' | 'no-match';
+
 export type FiberPathResolution =
   | { status: 'found'; fiber: AnyFiber; cacheId: string; textDisagreed?: boolean }
   | { status: 'ambiguous' }
-  | { status: 'unknown' };
+  | { status: 'unknown'; reason: FiberPathMissReason };
 
 function stringProp(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined;
@@ -50,18 +53,13 @@ function sameFiber(a: AnyFiber, b: AnyFiber): boolean {
   return alt != null && alt === b;
 }
 
-function liveSegment(fiber: AnyFiber): MobileFiberSegment {
+/** The live segment without its text, which needs a subtree walk. */
+function liveIdentity(fiber: AnyFiber): MobileFiberSegment {
   const props = getLiveHostProps(fiber);
   const role = stringProp(props?.accessibilityRole) ?? stringProp(props?.role);
   const testID = stringProp(props?.testID);
   const accessibilityLabel =
     stringProp(props?.accessibilityLabel) ?? stringProp(props?.['aria-label']);
-  let text: string | undefined;
-  try {
-    text = readHostText(fiber, 1);
-  } catch {
-    text = undefined;
-  }
   const hostKind = getHostTypeName(fiber);
   return {
     displayName: typeof fiber?.type === 'string' ? fiber.type : '',
@@ -69,10 +67,19 @@ function liveSegment(fiber: AnyFiber): MobileFiberSegment {
     ...(role ? { role } : {}),
     ...(testID ? { testID } : {}),
     ...(accessibilityLabel ? { accessibilityLabel } : {}),
-    ...(text ? { text } : {}),
   };
 }
 
+function liveSegment(fiber: AnyFiber): MobileFiberSegment {
+  let text: string | undefined;
+  try {
+    text = readHostText(fiber, 1);
+  } catch {
+    text = undefined;
+  }
+  return { ...liveIdentity(fiber), ...(text ? { text } : {}) };
+}
+
 function ancestorsOf(fiber: AnyFiber): AnyFiber[] {
   const chain: AnyFiber[] = [];
   let current: AnyFiber | null = fiber;
@@ -90,7 +97,8 @@ function scoreAlignment(expected: MobileFiberSegment[], actual: AnyFiber[]): num
   let kindAligned = 0;
   for (let i = 0; i < n; i += 1) {
     const exp = expected[expected.length - 1 - i]!;
-    const live = liveSegment(actual[actual.length - 1 - i]!);
+    // Alignment never compares text, so skip the subtree walk for every ancestor.
+    const live = liveIdentity(actual[actual.length - 1 - i]!);
     const expKind = exp.hostKind ?? exp.displayName;
     const liveKind = live.hostKind ?? live.displayName;
     if (expKind && liveKind && expKind !== liveKind) break;
@@ -107,13 +115,14 @@ function scoreHost(
   path: MobileFiberPath,
   fiber: AnyFiber,
 ): { score: number; textDisagreed: boolean } {
-  const live = liveSegment(fiber);
   const leaf = path.segments[path.segments.length - 1];
   const leafKind = leaf?.hostKind ?? path.leafKind;
-  const liveKind = live.hostKind ?? '';
+  // Kind first: most hosts fail here, before any props or text are read.
+  const liveKind = getHostTypeName(fiber) ?? '';
   if (leafKind && liveKind && leafKind !== liveKind) {
     return { score: -Infinity, textDisagreed: false };
   }
+  const live = liveSegment(fiber);
 
   let score = 20;
   if (leaf?.role && live.role === leaf.role) score += 15;
@@ -151,15 +160,15 @@ function scoreHost(
 
 function resolveScored(path: MobileFiberPath, root: AnyFiber): FiberPathResolution {
   const scored: Array<{ fiber: AnyFiber; score: number; textDisagreed: boolean }> = [];
+  // The walk already skips covered screens, so no per-host visibility walk.
   walkVisibleFibers(root, (fiber) => {
     if (!isHostFiber(fiber)) return;
-    if (!isFiberOnVisibleScreen(fiber)) return;
     const { score, textDisagreed } = scoreHost(path, fiber);
     if (score > -Infinity) scored.push({ fiber, score, textDisagreed });
   });
   scored.sort((a, b) => b.score - a.score);
   const best = scored[0];
-  if (!best || best.score < MIN_SCORE) return { status: 'unknown' };
+  if (!best || best.score < MIN_SCORE) return { status: 'unknown', reason: 'no-match' };
   const second = scored[1];
   if (second && best.score - second.score < UNIQUENESS_MARGIN) return { status: 'ambiguous' };
   return {
@@ -175,7 +184,7 @@ function resolveScored(path: MobileFiberPath, root: AnyFiber): FiberPathResoluti
  * and reuses the manual fiber scan.
  */
 export function resolveFiberPath(path: MobileFiberPath | null | undefined): FiberPathResolution {
-  if (!path || path.segments.length === 0) return { status: 'unknown' };
+  if (!path || path.segments.length === 0) return { status: 'unknown', reason: 'empty' };
 
   const leaf = path.segments[path.segments.length - 1];
   const exactId = leaf?.testID;
@@ -200,7 +209,7 @@ export function resolveFiberPath(path: MobileFiberPath | null | undefined): Fibe
   }
 
   const root = fiberScanRoot.getFiber();
-  if (!root) return { status: 'unknown' };
+  if (!root) return { status: 'unknown', reason: 'no-root' };
 
   const resolved = resolveScored(path, root);
   if (resolved.status === 'found') {

package/src/anchors/fiber/visibleScreens.ts

@@ -64,6 +64,11 @@ function isScreenFiber(fiber: AnyFiber): boolean {
   return type !== undefined && SCREEN_TYPES.has(type);
 }
 
+/** Host screen the walk can key a cache on (`RNSScreen`, `RNSModalScreen`). */
+export function isScreenHostFiber(fiber: AnyFiber): boolean {
+  return isScreenFiber(fiber);
+}
+
 function isStackContainer(fiber: AnyFiber): boolean {
   const type = getHostTypeName(fiber);
   return type !== undefined && STACK_CONTAINER_TYPES.has(type);