@userflow-tech/react-native 0.2.0 → 0.3.1

package/src/anchors/fiber/findAnchorFiber.ts

@@ -7,7 +7,7 @@ import {
   getSibling,
   isHostFiber,
 } from './fiberInternals';
-import { coveredScreenBranches, isScreenContainerFiber } from './visibleScreens';
+import { walkVisibleFibers } from './walkVisibleFibers';
 
 /**
  * Soft cap so a dense screen cannot stall the JS thread. One modest Expo Router
@@ -19,60 +19,78 @@ const MAX_NODES = 60_000;
 /** One production warning per process — truncation must not look like "missing". */
 let maxNodesWarned = false;
 
-export type AnchorPropTier = 'testID' | 'nativeID' | 'accessibilityLabel';
+export type AnchorPropTier = 'userflowId' | 'testID' | 'nativeID' | 'accessibilityLabel';
 
-const TIER_ORDER: AnchorPropTier[] = ['testID', 'nativeID', 'accessibilityLabel'];
+/** Props an anchor id can sit on, strongest first. */
+export const ANCHOR_PROP_TIERS: readonly AnchorPropTier[] = [
+  'userflowId',
+  'testID',
+  'nativeID',
+  'accessibilityLabel',
+];
 
 export type FindAnchorFiberResult =
   | { status: 'found'; fiber: AnyFiber; tier: AnchorPropTier }
   | { status: 'ambiguous'; tier: AnchorPropTier }
   | { status: 'missing' };
 
+/** Every collapsed host of the winning tier. Duplicates stay in the list. */
+export type FindAnchorFibersResult =
+  | { status: 'found'; fibers: AnyFiber[]; tier: AnchorPropTier }
+  | { status: 'missing' };
+
 /**
  * Bounded DFS under `rootFiber` looking for fibers whose memoizedProps match
- * `id` on testID, then nativeID, then accessibilityLabel. Uses the highest
- * tier that has any match so a testID hit is never made ambiguous by an
- * unrelated accessibilityLabel.
+ * `id` on userflowId, then testID, then nativeID, then accessibilityLabel.
+ * Uses the highest tier that has any match so a testID hit is never made
+ * ambiguous by an unrelated accessibilityLabel.
  *
- * Composite matches descend to the shallowest host descendant. Multiple
- * matches on a single root-to-leaf chain (e.g. Pressable forwarding testID to
- * its inner View) collapse to the outermost host. Disjoint matches fail closed
- * as ambiguous.
+ * A composite match resolves to the host beneath it that carries the same id
+ * (e.g. a tab item that wraps its button in a View and forwards testID to the
+ * button), else to its shallowest host descendant. Multiple matches on a single
+ * root-to-leaf chain (e.g. Pressable forwarding testID to its inner View)
+ * collapse to the outermost host. Disjoint matches stay in the list returned by
+ * {@link findAnchorFibers}; {@link findAnchorFiber} fails closed on those.
  *
  * The walk never follows `rootFiber.sibling` so the Userflow overlay (a sibling
  * of {@link FiberScanRoot} in UserflowProvider) cannot self-match SDK testIDs.
  */
-export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFiberResult {
+export function findAnchorFibers(rootFiber: AnyFiber, id: string): FindAnchorFibersResult {
   if (!rootFiber || !id) return { status: 'missing' };
+  const won = winningTier(rootFiber, id);
+  if (!won) return { status: 'missing' };
+  return { status: 'found', fibers: won.hosts, tier: won.tier };
+}
 
+export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFiberResult {
+  const many = findAnchorFibers(rootFiber, id);
+  if (many.status === 'missing') return { status: 'missing' };
+  if (many.fibers.length === 1) {
+    return { status: 'found', fiber: many.fibers[0]!, tier: many.tier };
+  }
+  return { status: 'ambiguous', tier: many.tier };
+}
+
+function winningTier(
+  rootFiber: AnyFiber,
+  id: string,
+): { tier: AnchorPropTier; hosts: AnyFiber[] } | null {
   try {
     const byTier: Record<AnchorPropTier, AnyFiber[]> = {
+      userflowId: [],
       testID: [],
       nativeID: [],
       accessibilityLabel: [],
     };
 
-    const stack: AnyFiber[] = [rootFiber];
-    // Branches belonging to screens the user cannot see. Their siblings are
-    // still walked, so only the covered subtree is skipped.
-    const covered = new Set<AnyFiber>();
-    let visited = 0;
-    while (stack.length > 0 && visited < MAX_NODES) {
-      const fiber = stack.pop();
-      if (!fiber) continue;
-      visited += 1;
-
-      if (covered.has(fiber)) {
-        // Keep following the chain, but do not match or descend here.
-        if (fiber !== rootFiber) {
-          const sibling = getSibling(fiber);
-          if (sibling) stack.push(sibling);
+    const { visited, truncated } = walkVisibleFibers(
+      rootFiber,
+      (fiber) => {
+        const props = getMemoizedProps(fiber);
+        if (!props) return;
+        if (typeof props.userflowId === 'string' && props.userflowId === id) {
+          byTier.userflowId.push(fiber);
         }
-        continue;
-      }
-
-      const props = getMemoizedProps(fiber);
-      if (props) {
         if (typeof props.testID === 'string' && props.testID === id) {
           byTier.testID.push(fiber);
         }
@@ -82,75 +100,60 @@ export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFibe
         if (typeof props.accessibilityLabel === 'string' && props.accessibilityLabel === id) {
           byTier.accessibilityLabel.push(fiber);
         }
-      }
+      },
+      MAX_NODES,
+    );
 
-      // Descend into children. Do NOT follow the seed root's sibling — in
-      // UserflowProvider the overlay (with SDK testIDs) is a sibling of
-      // FiberScanRoot and must stay outside the scan.
-      if (fiber !== rootFiber) {
-        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);
+    if (truncated || visited >= MAX_NODES) {
+      warnScanTruncated(id);
     }
 
-    if (visited >= MAX_NODES) {
-      // Truncation would otherwise look exactly like "the anchor isn't there".
-      // eslint-disable-next-line no-console -- actionable: the anchor may exist but was not reached
-      const warn = (message: string): void => console.warn(message);
-      if (__DEV__) {
-        warn(
-          `[Userflow] Anchor scan for "${id}" stopped after ${MAX_NODES} nodes. ` +
-            `The element may exist but was not reached. Register it explicitly with ` +
-            `useUserflowAnchor("${id}") to skip the scan.`,
-        );
-      } else if (!maxNodesWarned) {
-        maxNodesWarned = true;
-        warn(
-          `[Userflow] Anchor scan stopped after ${MAX_NODES} nodes; some anchors may ` +
-            `be missed. Prefer useUserflowAnchor for deep or dense trees.`,
-        );
-      }
-    }
-
-    for (const tier of TIER_ORDER) {
+    for (const tier of ANCHOR_PROP_TIERS) {
       const matches = byTier[tier];
       if (matches.length === 0) continue;
 
       const hosts = uniqueHosts(matches);
       if (hosts.length === 0) continue;
-      if (hosts.length === 1) {
-        return { status: 'found', fiber: hosts[0]!, tier };
-      }
-
-      const collapsed = collapseToChains(hosts);
-      if (collapsed.length === 1) {
-        return { status: 'found', fiber: collapsed[0]!, tier };
-      }
-      return { status: 'ambiguous', tier };
+      return { tier, hosts: collapseToChains(hosts) };
     }
 
-    return { status: 'missing' };
+    return null;
   } catch {
-    return { status: 'missing' };
+    return null;
+  }
+}
+
+function warnScanTruncated(id: string): void {
+  // Truncation would otherwise look exactly like "the anchor isn't there".
+  // eslint-disable-next-line no-console -- actionable: the anchor may exist but was not reached
+  const warn = (message: string): void => console.warn(message);
+  if (__DEV__) {
+    warn(
+      `[Userflow] Anchor scan for "${id}" stopped after ${MAX_NODES} nodes. ` +
+        `The element may exist but was not reached. Register it explicitly with ` +
+        `useUserflowAnchor("${id}") to skip the scan.`,
+    );
+    return;
+  }
+  if (!maxNodesWarned) {
+    maxNodesWarned = true;
+    warn(
+      `[Userflow] Anchor scan stopped after ${MAX_NODES} nodes; some anchors may ` +
+        `be missed. Prefer useUserflowAnchor for deep or dense trees.`,
+    );
   }
 }
 
 /**
- * For each matched fiber, resolve the shallowest host descendant (or itself
- * when already a host). Deduplicate by identity / alternate.
+ * Resolve each matched fiber to the host that represents it. Deduplicate by
+ * identity / alternate.
  */
 function uniqueHosts(matches: AnyFiber[]): AnyFiber[] {
+  const forwarded = forwardedHostMatches(matches);
   const seen = new Set<AnyFiber>();
   const out: AnyFiber[] = [];
   for (const match of matches) {
-    const host = nearestHostDescendant(match) ?? (isHostFiber(match) ? match : null);
+    const host = isHostFiber(match) ? match : compositeHost(match, forwarded.get(match));
     if (!host) continue;
     const identity = host.alternate ?? host;
     if (seen.has(host) || seen.has(identity)) continue;
@@ -162,6 +165,44 @@ function uniqueHosts(matches: AnyFiber[]): AnyFiber[] {
   return out;
 }
 
+/**
+ * The host carrying a composite's id when the composite forwards it down one
+ * chain, else the composite's shallowest host. Carriers on disjoint chains keep
+ * the shallowest host, so a component repeating its id on two children still
+ * resolves to the component.
+ */
+function compositeHost(composite: AnyFiber, carriers: AnyFiber[] | undefined): AnyFiber | null {
+  const chains = carriers ? collapseToChains(carriers) : [];
+  if (chains.length === 1) return chains[0]!;
+  return nearestHostDescendant(composite);
+}
+
+/** Host matches grouped under each composite match they descend from. */
+function forwardedHostMatches(matches: AnyFiber[]): Map<AnyFiber, AnyFiber[]> {
+  const composites = new Map<AnyFiber, AnyFiber>();
+  for (const match of matches) {
+    if (isHostFiber(match)) continue;
+    composites.set(match, match);
+    if (match.alternate) composites.set(match.alternate, match);
+  }
+  const out = new Map<AnyFiber, AnyFiber[]>();
+  if (composites.size === 0) return out;
+  for (const host of matches) {
+    if (!isHostFiber(host)) continue;
+    let cur = getReturn(host);
+    for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      const composite = composites.get(cur);
+      if (composite) {
+        const carriers = out.get(composite);
+        if (carriers) carriers.push(host);
+        else out.set(composite, [host]);
+      }
+      cur = getReturn(cur);
+    }
+  }
+  return out;
+}
+
 /**
  * BFS under `fiber` for the shallowest host descendant. Returns `fiber` itself
  * when it is already a host.

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/touchTargetFiber.ts

@@ -0,0 +1,125 @@
+/**
+ * Host fiber under a touch, resolved synchronously from the responder event.
+ *
+ * Feature-detected and never throws. A renderer that does not expose any of
+ * these pointers degrades to "no target", so a click condition simply does not
+ * latch.
+ *
+ * Order:
+ * 1. `event._targetInst` (React's fiber for the touched component)
+ * 2. `event.target` public instance via {@link lookupHostFiber}
+ * 3. The touch's native tag (`changedTouches[].target`, else `nativeEvent.target`)
+ *    via the scan-root host index
+ */
+import type { GestureResponderEvent } from 'react-native';
+
+import {
+  type AnyFiber,
+  isHostFiber,
+  isReactFiber,
+  nativeTagFromHostFiber,
+  resolveCurrentFiber,
+} from './fiberInternals';
+import { nearestHostDescendant } from './findAnchorFiber';
+import { createLazyHostFiberIndex, lookupHostFiber } from './indexHostFibers';
+
+export function touchTargetFiber(
+  event: GestureResponderEvent,
+  identifier?: number | string,
+): AnyFiber | null {
+  try {
+    const tag = nativeTagForTouch(event, identifier);
+
+    const fromInst = hostFromFiber(readTargetInst(event));
+    if (fromInst && tagMatches(fromInst, tag)) return fromInst;
+
+    const fromInstance = hostFromInstance(event.target);
+    if (fromInstance && tagMatches(fromInstance, tag)) return fromInstance;
+
+    if (tag === undefined) return null;
+    // The event-level fibers belong to another finger's view, so only the
+    // index can name this one. A miss must not fall back to theirs.
+    return createLazyHostFiberIndex()().byNativeTag.get(tag) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fabric sends one touch event per touched view, and each lists every finger
+ * that changed. True when `identifier`'s finger is on this event's own view,
+ * so a caller can record each finger once, from its own event, instead of
+ * overwriting it from another finger's. Unreadable tags count as this event's.
+ */
+export function touchBelongsToEvent(
+  event: GestureResponderEvent,
+  identifier: number | string,
+): boolean {
+  try {
+    const tag = nativeTagForTouch(event, identifier);
+    if (tag === undefined) return true;
+    const own = hostFromFiber(readTargetInst(event)) ?? hostFromInstance(event.target);
+    return own == null || tagMatches(own, tag);
+  } catch {
+    return true;
+  }
+}
+
+function readTargetInst(event: GestureResponderEvent): unknown {
+  return (event as { _targetInst?: unknown })._targetInst;
+}
+
+function nativeTagForTouch(
+  event: GestureResponderEvent,
+  identifier: number | string | undefined,
+): number | undefined {
+  const native = event.nativeEvent as {
+    target?: unknown;
+    changedTouches?: Array<{ identifier?: number | string; target?: unknown }>;
+  };
+  if (identifier != null && native.changedTouches) {
+    const touch = native.changedTouches.find((entry) => entry.identifier === identifier);
+    const touchTag = asTag(touch?.target);
+    if (touchTag !== undefined) return touchTag;
+  }
+  return asTag(native.target);
+}
+
+function asTag(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Accept a host whose tag we cannot read (test renderer, older Paper). Reject
+ * only when both sides have a tag and they differ — that event-level fiber
+ * belongs to a different finger.
+ */
+function tagMatches(fiber: AnyFiber, tag: number | undefined): boolean {
+  if (tag === undefined) return true;
+  const fiberTag = nativeTagFromHostFiber(fiber);
+  if (fiberTag === undefined) return true;
+  return fiberTag === tag;
+}
+
+function hostFromFiber(value: unknown): AnyFiber | null {
+  if (!isReactFiber(value)) return null;
+  try {
+    const current = resolveCurrentFiber(value);
+    if (isHostFiber(current)) return current;
+    return nearestHostDescendant(current);
+  } catch {
+    return null;
+  }
+}
+
+function hostFromInstance(value: unknown): AnyFiber | null {
+  if (!value || typeof value !== 'object') return null;
+  try {
+    const fiber = lookupHostFiber(createLazyHostFiberIndex(), value);
+    if (!fiber) return null;
+    if (isHostFiber(fiber)) return fiber;
+    return nearestHostDescendant(fiber);
+  } catch {
+    return null;
+  }
+}