@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/anchors/fiber/resolveFiberPath.ts

@@ -0,0 +1,215 @@
+/**
+ * Re-resolve a fiber path captured from library UI the Babel plugin never
+ * stamped. Explicit leaf ids win. Otherwise score host kind, label, role, and
+ * path alignment, and fail closed when the best hit is weak or tied.
+ */
+import type { MobileFiberPath, MobileFiberSegment } from '@userflow-tech/protocol';
+
+import {
+  getCachedFiberAnchor,
+  getFiberAnchorScreenKey,
+  setCachedFiberAnchor,
+} from '../fiberAnchorCache';
+import { resolveAnchorHost } from '../resolveAnchorHost';
+import { textsAgree } from '../semanticMatcher';
+
+import { fiberScanRoot } from './FiberScanRoot';
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getAlternate,
+  getHostTypeName,
+  getLiveHostProps,
+  getReturn,
+  isFiberMounted,
+  isHostFiber,
+} from './fiberInternals';
+import { readHostText } from './readHostContent';
+import { isFiberOnVisibleScreen } from './visibleScreens';
+import { walkVisibleFibers } from './walkVisibleFibers';
+
+const MIN_SCORE = 40;
+const UNIQUENESS_MARGIN = 12;
+
+export type FiberPathResolution =
+  | { status: 'found'; fiber: AnyFiber; cacheId: string; textDisagreed?: boolean }
+  | { status: 'ambiguous' }
+  | { status: 'unknown' };
+
+function stringProp(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function cacheKey(path: MobileFiberPath): string {
+  return `fiber:${JSON.stringify(path)}`;
+}
+
+function sameFiber(a: AnyFiber, b: AnyFiber): boolean {
+  if (a === b) return true;
+  const alt = getAlternate(a);
+  return alt != null && alt === b;
+}
+
+function liveSegment(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 : '',
+    ...(hostKind ? { hostKind } : {}),
+    ...(role ? { role } : {}),
+    ...(testID ? { testID } : {}),
+    ...(accessibilityLabel ? { accessibilityLabel } : {}),
+    ...(text ? { text } : {}),
+  };
+}
+
+function ancestorsOf(fiber: AnyFiber): AnyFiber[] {
+  const chain: AnyFiber[] = [];
+  let current: AnyFiber | null = fiber;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (isHostFiber(current)) chain.push(current);
+    current = getReturn(current);
+  }
+  chain.reverse();
+  return chain;
+}
+
+function scoreAlignment(expected: MobileFiberSegment[], actual: AnyFiber[]): number {
+  const n = Math.min(expected.length, actual.length);
+  let score = 0;
+  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]!);
+    const expKind = exp.hostKind ?? exp.displayName;
+    const liveKind = live.hostKind ?? live.displayName;
+    if (expKind && liveKind && expKind !== liveKind) break;
+    kindAligned += 1;
+    if (exp.testID && live.testID === exp.testID) score += 20;
+    if (exp.role && live.role && exp.role === live.role) score += 8;
+    if (exp.siblingIndex !== undefined && exp.siblingIndex === live.siblingIndex) score += 2;
+    if (exp.displayName && live.displayName && exp.displayName === live.displayName) score += 1;
+  }
+  return score + kindAligned * 6;
+}
+
+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 ?? '';
+  if (leafKind && liveKind && leafKind !== liveKind) {
+    return { score: -Infinity, textDisagreed: false };
+  }
+
+  let score = 20;
+  if (leaf?.role && live.role === leaf.role) score += 15;
+  if (leaf?.testID && live.testID === leaf.testID) score += 90;
+
+  const expectedText = leaf?.text ?? path.leafText;
+  const expectedLabel = leaf?.accessibilityLabel;
+  const textDisagreed = !!expectedText && !!live.text && expectedText !== live.text;
+  const labelDisagreed =
+    !!expectedLabel && !!live.accessibilityLabel && expectedLabel !== live.accessibilityLabel;
+
+  if (expectedText && textsAgree(expectedText, live.text)) score += 40;
+  if (expectedLabel && textsAgree(expectedLabel, live.accessibilityLabel)) score += 35;
+
+  const ancestors = ancestorsOf(fiber);
+  score += scoreAlignment(path.segments, ancestors);
+
+  const fatalText = textDisagreed && !textsAgree(expectedText, live.text);
+  const fatalLabel = labelDisagreed && !textsAgree(expectedLabel, live.accessibilityLabel);
+  // A full host-kind alignment vouches for a renamed or translated label the
+  // way an icon vouches in the registry matcher. Twins still fail uniqueness.
+  const offset = ancestors.length - path.segments.length;
+  const kindsAlign =
+    offset >= 0 &&
+    path.segments.every((segment, index) => {
+      const actualKind = getHostTypeName(ancestors[offset + index]!);
+      return !segment.hostKind || actualKind === segment.hostKind;
+    });
+  if ((fatalText || fatalLabel) && !leaf?.testID && !kindsAlign) {
+    return { score: -Infinity, textDisagreed: true };
+  }
+
+  return { score, textDisagreed: textDisagreed || labelDisagreed };
+}
+
+function resolveScored(path: MobileFiberPath, root: AnyFiber): FiberPathResolution {
+  const scored: Array<{ fiber: AnyFiber; score: number; textDisagreed: boolean }> = [];
+  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' };
+  const second = scored[1];
+  if (second && best.score - second.score < UNIQUENESS_MARGIN) return { status: 'ambiguous' };
+  return {
+    status: 'found',
+    fiber: best.fiber,
+    cacheId: '',
+    ...(best.textDisagreed ? { textDisagreed: true } : {}),
+  };
+}
+
+/**
+ * Resolve `path` to the live host it describes. A leaf `testID` is authoritative
+ * and reuses the manual fiber scan.
+ */
+export function resolveFiberPath(path: MobileFiberPath | null | undefined): FiberPathResolution {
+  if (!path || path.segments.length === 0) return { status: 'unknown' };
+
+  const leaf = path.segments[path.segments.length - 1];
+  const exactId = leaf?.testID;
+  if (exactId) {
+    const exact = resolveAnchorHost(exactId);
+    if (exact.status === 'found' && exact.fiber) {
+      return { status: 'found', fiber: exact.fiber, cacheId: exactId };
+    }
+    if (exact.status === 'ambiguous') return { status: 'ambiguous' };
+  }
+
+  const key = cacheKey(path);
+  const cached = getCachedFiberAnchor(key);
+  const screenKey = getFiberAnchorScreenKey();
+  if (
+    cached &&
+    cached.screenKey === screenKey &&
+    isFiberMounted(cached.fiber) &&
+    isFiberOnVisibleScreen(cached.fiber)
+  ) {
+    return { status: 'found', fiber: cached.fiber, cacheId: key };
+  }
+
+  const root = fiberScanRoot.getFiber();
+  if (!root) return { status: 'unknown' };
+
+  const resolved = resolveScored(path, root);
+  if (resolved.status === 'found') {
+    setCachedFiberAnchor(key, resolved.fiber);
+    return { ...resolved, cacheId: key };
+  }
+  return resolved;
+}
+
+export function fibersMatch(a: AnyFiber, b: AnyFiber): boolean {
+  return sameFiber(a, b) || sameFiber(b, a);
+}

package/src/anchors/fiber/visibleRect.ts

@@ -0,0 +1,153 @@
+/**
+ * Geometry helpers for "what the user can actually see".
+ *
+ * `measureInWindow` reports a view's full layout rect, including the part
+ * scrolled under a tab bar or clipped by a ScrollView. Native hit-testing
+ * already accounts for that; the JS fallback and the tooltip tap rect do not,
+ * so they clip against scroll viewports and the topmost modal.
+ */
+import {
+  type AnyFiber,
+  getChild,
+  getHostTypeName,
+  getMemoizedProps,
+  getReturn,
+  getSibling,
+  isHostFiber,
+} from './fiberInternals';
+import { findScrollAncestors } from './findScrollAncestors';
+import { measureHostFiber } from './measureHostFiber';
+
+export interface VisibleRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+const MEASURE_TIMEOUT_MS = 400;
+
+/** Paper and Fabric names for React Native's `<Modal>`. */
+const MODAL_HOST_TYPES = new Set(['RCTModalHostView', 'ModalHostView']);
+
+type MeasureCallback = (x: number, y: number, width: number, height: number) => void;
+
+function measureFiberRect(fiber: AnyFiber): Promise<VisibleRect | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(null);
+    }, MEASURE_TIMEOUT_MS);
+    try {
+      measureHostFiber(fiber, (x, y, width, height) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (width <= 0 || height <= 0) {
+          resolve(null);
+          return;
+        }
+        resolve({ x, y, width, height });
+      });
+    } catch {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(null);
+    }
+  });
+}
+
+export function intersectRects(a: VisibleRect, b: VisibleRect): VisibleRect | null {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  const width = right - x;
+  const height = bottom - y;
+  if (width <= 0 || height <= 0) return null;
+  return { x, y, width, height };
+}
+
+/**
+ * Intersect `rect` with every scroll viewport above `fiber` (innermost first).
+ * Returns null when the rect is entirely outside a viewport. No scroll ancestor
+ * leaves `rect` unchanged.
+ */
+export async function clipToScrollViewports(
+  fiber: AnyFiber | null,
+  rect: VisibleRect,
+): Promise<VisibleRect | null> {
+  if (!fiber) return rect;
+  let ancestors;
+  try {
+    ancestors = findScrollAncestors(fiber);
+  } catch {
+    return rect;
+  }
+  let clipped: VisibleRect | null = rect;
+  for (const ancestor of ancestors) {
+    if (!clipped || !ancestor.containerFiber) continue;
+    const viewport = await measureFiberRect(ancestor.containerFiber);
+    if (!viewport) continue;
+    clipped = intersectRects(clipped, viewport);
+  }
+  return clipped;
+}
+
+function isModalHost(fiber: AnyFiber): boolean {
+  const type = getHostTypeName(fiber);
+  return type !== undefined && MODAL_HOST_TYPES.has(type);
+}
+
+function isModalVisible(fiber: AnyFiber): boolean {
+  const props = getMemoizedProps(fiber);
+  if (!props) return true;
+  if (props.visible === false) return false;
+  return true;
+}
+
+/**
+ * The visible modal host drawn on top, or null. Later siblings win: React
+ * Native mounts a newer `<Modal>` after the previous one.
+ */
+export function topmostVisibleModalHost(root: AnyFiber | null, maxNodes = 8_000): AnyFiber | null {
+  if (!root) return null;
+  const stack: AnyFiber[] = [root];
+  let topmost: AnyFiber | null = null;
+  let visited = 0;
+  try {
+    while (stack.length > 0 && visited < maxNodes) {
+      const fiber = stack.pop();
+      if (!fiber) continue;
+      visited += 1;
+      if (fiber !== root && isHostFiber(fiber) && isModalHost(fiber) && isModalVisible(fiber)) {
+        topmost = fiber;
+      }
+      if (fiber !== root) {
+        const sibling = getSibling(fiber);
+        if (sibling) stack.push(sibling);
+      }
+      const child = getChild(fiber);
+      if (child) stack.push(child);
+    }
+  } catch {
+    return topmost;
+  }
+  return topmost;
+}
+
+/** True when `fiber` is `ancestor` or sits under it. */
+export function fiberIsUnder(fiber: AnyFiber, ancestor: AnyFiber, maxDepth = 10_000): boolean {
+  let current: AnyFiber | null = fiber;
+  for (let depth = 0; current && depth < maxDepth; depth += 1) {
+    if (current === ancestor) return true;
+    if (ancestor.alternate && current === ancestor.alternate) return true;
+    current = getReturn(current);
+  }
+  return false;
+}
+
+export type { MeasureCallback };

package/src/anchors/fiber/visibleScreens.ts

@@ -32,6 +32,7 @@ import {
   getMemoizedProps,
   getReturn,
   getSibling,
+  resolveCurrentFiber,
 } from './fiberInternals';
 
 /** Host screen types (push screens and iOS modal presentations). */
@@ -98,13 +99,17 @@ function isActive(screen: AnyFiber): boolean {
   return getMemoizedProps(screen)?.activityState === ACTIVITY_STATE_ACTIVE;
 }
 
-/**
- * Branches of `container` that are covered by another screen and so must not be
- * scanned. Empty when there is nothing to prune. Alternates are included so a
- * fiber captured on a previous render still matches.
- */
-export function coveredScreenBranches(container: AnyFiber): Set<AnyFiber> {
-  const branches: Array<{ branch: AnyFiber; screen: AnyFiber }> = [];
+interface ScreenBranch {
+  branch: AnyFiber;
+  screen: AnyFiber;
+}
+
+/** Every branch of `container` that owns a screen, and the ones currently visible. */
+function screenBranches(container: AnyFiber): {
+  branches: ScreenBranch[];
+  visible: ScreenBranch[];
+} {
+  const branches: ScreenBranch[] = [];
   let child = getChild(container);
   let guard = 0;
   while (child && guard < 200) {
@@ -114,21 +119,30 @@ export function coveredScreenBranches(container: AnyFiber): Set<AnyFiber> {
     guard += 1;
   }
 
-  const covered = new Set<AnyFiber>();
-  if (branches.length <= 1) return covered;
+  if (branches.length <= 1) return { branches, visible: branches };
 
-  let visible: Array<{ branch: AnyFiber; screen: AnyFiber }>;
   if (isStackContainer(container)) {
     // Native stack: activityState is always 2 for mounted screens; last branch
     // owns the top of the stack (including an iOS RNSModalScreen presentation).
-    visible = [branches[branches.length - 1]!];
-  } else {
-    const active = branches.filter((entry) => isActive(entry.screen));
-    // Keep every active pane (tabs + multi-visible). If none report active
-    // (transition), fall back to last sibling rather than pruning everything.
-    visible = active.length > 0 ? active : [branches[branches.length - 1]!];
+    return { branches, visible: [branches[branches.length - 1]!] };
   }
+  const active = branches.filter((entry) => isActive(entry.screen));
+  // Keep every active pane (tabs + multi-visible). If none report active
+  // (transition), fall back to last sibling rather than pruning everything.
+  return {
+    branches,
+    visible: active.length > 0 ? active : [branches[branches.length - 1]!],
+  };
+}
 
+/**
+ * Branches of `container` that are covered by another screen and so must not be
+ * scanned. Empty when there is nothing to prune. Alternates are included so a
+ * fiber captured on a previous render still matches.
+ */
+export function coveredScreenBranches(container: AnyFiber): Set<AnyFiber> {
+  const { branches, visible } = screenBranches(container);
+  const covered = new Set<AnyFiber>();
   for (const entry of branches) {
     if (visible.includes(entry)) continue;
     covered.add(entry.branch);
@@ -138,36 +152,60 @@ export function coveredScreenBranches(container: AnyFiber): Set<AnyFiber> {
   return covered;
 }
 
+/**
+ * The innermost container that hides the branch holding `fiber`, or null when
+ * `fiber` is on a visible screen. Walks outward so nested navigators are handled.
+ */
+function coveringContainer(fiber: AnyFiber): AnyFiber | null {
+  let previous: AnyFiber | null = null;
+  let current: AnyFiber = fiber;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (previous && isScreenContainerFiber(current)) {
+      // A cached fiber's `return` chain can point at the previous render, whose
+      // branches still carry the old activityState. Only the committed
+      // container says which screen is visible now.
+      const container = resolveCurrentFiber(current);
+      const covered = coveredScreenBranches(container);
+      if (covered.has(previous)) return container;
+      const previousAlternate = getAlternate(previous);
+      if (previousAlternate && covered.has(previousAlternate)) return container;
+    }
+    previous = current;
+    current = getReturn(current);
+  }
+  return null;
+}
+
 /**
  * Whether `fiber` lives on a screen the user can currently see.
  *
  * Needed in addition to scan-time pruning: a resolved anchor is cached, and the
  * cache would otherwise keep serving a host after its screen was covered by a
- * newly pushed one. Walks outward so nested navigators are handled.
+ * newly pushed one.
  */
 export function isFiberOnVisibleScreen(fiber: AnyFiber): boolean {
   if (!fiber) return false;
   try {
-    let previous: AnyFiber | null = null;
-    let current: AnyFiber = fiber;
-    for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
-      if (previous) {
-        // A cached fiber's `return` chain can point at the previous render, whose
-        // container still lists the old branches — so consult both alternates.
-        for (const container of [current, getAlternate(current)]) {
-          if (!container || !isScreenContainerFiber(container)) continue;
-          const covered = coveredScreenBranches(container);
-          if (covered.size === 0) continue;
-          if (covered.has(previous)) return false;
-          const previousAlternate = getAlternate(previous);
-          if (previousAlternate && covered.has(previousAlternate)) return false;
-        }
-      }
-      previous = current;
-      current = getReturn(current);
-    }
+    return coveringContainer(fiber) === null;
   } catch {
     // Visibility is a refinement; never let it break resolution.
+    return true;
+  }
+}
+
+/**
+ * When `fiber` is on a covered screen, the visible screens of the navigator
+ * that covers it, topmost first. Empty when `fiber` is visible.
+ */
+export function screensCoveringFiber(fiber: AnyFiber): AnyFiber[] {
+  if (!fiber) return [];
+  try {
+    const container = coveringContainer(fiber);
+    if (!container) return [];
+    return screenBranches(container)
+      .visible.map((entry) => entry.screen)
+      .reverse();
+  } catch {
+    return [];
   }
-  return true;
 }

package/src/anchors/fiber/walkVisibleFibers.ts

@@ -0,0 +1,65 @@
+/**
+ * Bounded DFS under a fiber that skips screens the user cannot see.
+ *
+ * Same pruning as {@link findAnchorFiber}: covered navigator branches are not
+ * visited, but their siblings still are. The walk never follows `root.sibling`,
+ * so the Userflow overlay (a sibling of FiberScanRoot) stays out of the scan.
+ */
+import { type AnyFiber, getChild, getSibling } from './fiberInternals';
+import { coveredScreenBranches, isScreenContainerFiber } from './visibleScreens';
+
+/** Same cap as the anchor scan: several mounted screens of a modest app. */
+export const WALK_VISIBLE_MAX_NODES = 60_000;
+
+export interface WalkVisibleFibersResult {
+  visited: number;
+  truncated: boolean;
+}
+
+/**
+ * Visit fibers under `root`, skipping covered screen branches.
+ * `visit` returning `false` stops the walk early.
+ */
+export function walkVisibleFibers(
+  root: AnyFiber,
+  visit: (fiber: AnyFiber) => void | false,
+  maxNodes = WALK_VISIBLE_MAX_NODES,
+): WalkVisibleFibersResult {
+  if (!root) return { visited: 0, truncated: false };
+
+  const stack: AnyFiber[] = [root];
+  const covered = new Set<AnyFiber>();
+  let visited = 0;
+
+  while (stack.length > 0 && visited < maxNodes) {
+    const fiber = stack.pop();
+    if (!fiber) continue;
+    visited += 1;
+
+    if (covered.has(fiber)) {
+      if (fiber !== root) {
+        const sibling = getSibling(fiber);
+        if (sibling) stack.push(sibling);
+      }
+      continue;
+    }
+
+    if (visit(fiber) === false) {
+      return { visited, truncated: false };
+    }
+
+    if (fiber !== root) {
+      const sibling = getSibling(fiber);
+      if (sibling) stack.push(sibling);
+    }
+    if (isScreenContainerFiber(fiber)) {
+      for (const branch of coveredScreenBranches(fiber)) {
+        covered.add(branch);
+      }
+    }
+    const child = getChild(fiber);
+    if (child) stack.push(child);
+  }
+
+  return { visited, truncated: visited >= maxNodes };
+}

package/src/anchors/isInstanceOnVisibleScreen.ts

@@ -0,0 +1,55 @@
+import type { AutoAnchorInstance } from './AutoAnchorRegistry';
+import type { AnyFiber } from './fiber/fiberInternals';
+import {
+  createLazyHostFiberIndex,
+  lookupHostFiber,
+  type HostFiberIndex,
+} from './fiber/indexHostFibers';
+import { isFiberOnVisibleScreen } from './fiber/visibleScreens';
+
+type HostFiberIndexGetter = () => HostFiberIndex;
+
+function fiberForInstance(
+  inst: AutoAnchorInstance,
+  getIndex: HostFiberIndexGetter,
+): AnyFiber | null {
+  try {
+    return lookupHostFiber(getIndex, inst.ref.current);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a scored instance is on a screen the user can see.
+ *
+ * No fiber pointer means we cannot prove the host is covered (tests, and hosts
+ * whose public instance has no internals link) — same fail-open as apps without
+ * react-native-screens.
+ */
+export function isInstanceOnVisibleScreen(inst: AutoAnchorInstance): boolean {
+  const fiber = fiberForInstance(inst, createLazyHostFiberIndex());
+  if (!fiber) return true;
+  return isFiberOnVisibleScreen(fiber);
+}
+
+/**
+ * One lazy host-fiber index and one verdict per instance, for a single pass.
+ *
+ * A factory rather than an extra argument: `Array.filter` passes the index as
+ * the second parameter. Sharing the index matters on Paper release builds,
+ * where a host ref cannot reach its fiber and each lookup would otherwise walk
+ * the tree.
+ */
+export function createVisibleInstanceFilter(): (inst: AutoAnchorInstance) => boolean {
+  const getIndex = createLazyHostFiberIndex();
+  const memo = new Map<string, boolean>();
+  return (inst) => {
+    const cached = memo.get(inst.instanceId);
+    if (cached !== undefined) return cached;
+    const fiber = fiberForInstance(inst, getIndex);
+    const visible = !fiber || isFiberOnVisibleScreen(fiber);
+    memo.set(inst.instanceId, visible);
+    return visible;
+  };
+}