@userflow-tech/react-native 0.4.4 → 0.5.0

package/src/anchors/gestureHandlerHandoff.ts

@@ -0,0 +1,356 @@
+/**
+ * Taps that react-native-gesture-handler takes away from React Native.
+ *
+ * When a gesture-handler control activates, it cancels RN's touch stream, so
+ * the bridge sees `touchcancel` instead of `touchend`. The handler tag is read
+ * off the touched fiber (no import of gesture-handler), and the touch counts
+ * as a tap only if that handler later ends from ACTIVE on
+ * `onGestureHandlerStateChange`. Apps that never hit this path never subscribe.
+ *
+ * State numbers are gesture-handler's `State` enum. A future major that
+ * renumbers them degrades to "no tap", which is today's behavior.
+ */
+import type { AnyFiber } from './fiber/fiberInternals';
+import {
+  getMemoizedProps,
+  getReturn,
+  getStateNode,
+  MAX_ANCESTOR_WALK,
+} from './fiber/fiberInternals';
+import { type TouchPoint, withinTapSlop } from './tapSlop';
+
+/** gesture-handler `State` values this hand-off acts on. */
+export const GESTURE_HANDLER_STATE = {
+  FAILED: 1,
+  CANCELLED: 3,
+  ACTIVE: 4,
+  END: 5,
+} as const;
+
+/** Drop a handed-off touch that never reaches a terminal state. */
+export const GESTURE_HANDLER_HANDOFF_TIMEOUT_MS = 10_000;
+
+const STATE_CHANGE_EVENT = 'onGestureHandlerStateChange';
+
+export interface HandedOffTouch {
+  identifier: number | string;
+  pageX: number;
+  pageY: number;
+  handlerTags: readonly number[];
+  /**
+   * The gesture completed as a tap. `end` is set when the payload carried
+   * window coordinates; otherwise only the start point is known.
+   */
+  onResolve: (end: TouchPoint | null) => void;
+}
+
+interface DeviceEventSubscription {
+  remove: () => void;
+}
+
+interface DeviceEventEmitterLike {
+  addListener(event: string, listener: (payload: unknown) => void): DeviceEventSubscription;
+}
+
+interface GestureStatePayload {
+  handlerTag: number;
+  state: number;
+  oldState?: number;
+  pointerInside?: boolean;
+  translationX?: number;
+  translationY?: number;
+  absoluteX?: number;
+  absoluteY?: number;
+  /** Present only so a long-press payload can be told apart from a tap. */
+  hasDuration: boolean;
+}
+
+interface PendingTouch extends HandedOffTouch {
+  id: number;
+  settled: boolean;
+  /** Tags that already reached a terminal state without counting as a tap. */
+  finishedTags: Set<number>;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Handler tags for the control under `fiber`.
+ *
+ * Old-API buttons keep `handlerTag` on the class instance. `GestureDetector`
+ * keeps a `gesture` prop whose `toGestureArray()` entries each have one.
+ * Negative tags (gesture-handler's own root helper) are ignored.
+ *
+ * The walk stops at the nearest fiber that has a tag. A native handler with
+ * `disallowInterruption` (gesture-handler `ScrollView`, `FlatList`,
+ * `RefreshControl`) is a container, not a tap, so a scroll that starts inside
+ * it is dropped instead of latching the row. Never throws.
+ */
+export function collectGestureHandlerTags(fiber: AnyFiber | null): number[] {
+  if (fiber == null) return [];
+  try {
+    let current: AnyFiber | null = fiber;
+    let steps = 0;
+    while (current && steps < MAX_ANCESTOR_WALK) {
+      steps += 1;
+      const found = tagsOnFiber(current);
+      if (found.pressable.length > 0) return found.pressable;
+      // The nearest handler is a scroll container. An outer control did not
+      // receive this touch.
+      if (found.container) return [];
+      current = getReturn(current);
+    }
+  } catch {
+    return [];
+  }
+  return [];
+}
+
+export class GestureHandlerHandoff {
+  private readonly pending = new Map<number, PendingTouch>();
+  private nextId = 1;
+  private subscription: DeviceEventSubscription | null = null;
+
+  /**
+   * Keep `touch` until its handler finishes or it expires.
+   * Returns a stop function; calling it drops the touch without a tap.
+   */
+  track(touch: HandedOffTouch): () => void {
+    if (touch.handlerTags.length === 0) return () => {};
+    const id = this.nextId;
+    this.nextId += 1;
+    const pending: PendingTouch = {
+      ...touch,
+      id,
+      settled: false,
+      finishedTags: new Set(),
+      timer: setTimeout(() => {
+        this.drop(id);
+      }, GESTURE_HANDLER_HANDOFF_TIMEOUT_MS),
+    };
+    this.pending.set(id, pending);
+    this.ensureListening();
+    return () => this.drop(id);
+  }
+
+  /** Test helper. Drops every pending touch and unsubscribes. */
+  resetForTests(): void {
+    for (const touch of this.pending.values()) {
+      touch.settled = true;
+      clearTimeout(touch.timer);
+    }
+    this.pending.clear();
+    this.stopListeningIfIdle();
+  }
+
+  /** @internal Test hook: how many touches are still waiting. */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  private ensureListening(): void {
+    if (this.subscription || this.pending.size === 0) return;
+    const emitter = deviceEventEmitter();
+    if (!emitter) return;
+    this.subscription = emitter.addListener(STATE_CHANGE_EVENT, (payload: unknown) => {
+      try {
+        this.handleStateChange(payload);
+      } catch {
+        // A bad payload must not break the next gesture.
+      }
+    });
+  }
+
+  private stopListeningIfIdle(): void {
+    if (this.pending.size > 0 || !this.subscription) return;
+    this.subscription.remove();
+    this.subscription = null;
+  }
+
+  private handleStateChange(event: unknown): void {
+    const payload = asPayload(event);
+    if (!payload) return;
+    const matching = [...this.pending.values()].filter(
+      (touch) => !touch.settled && touch.handlerTags.includes(payload.handlerTag),
+    );
+    for (const touch of matching) {
+      this.apply(touch, payload);
+    }
+  }
+
+  private apply(touch: PendingTouch, payload: GestureStatePayload): void {
+    if (touch.settled || !isTerminal(payload.state)) return;
+    if (isCompletedTap(touch, payload)) {
+      this.resolve(touch, endPoint(payload));
+      return;
+    }
+    touch.finishedTags.add(payload.handlerTag);
+    const allDone = touch.handlerTags.every((tag) => touch.finishedTags.has(tag));
+    if (allDone) this.drop(touch.id);
+  }
+
+  private resolve(touch: PendingTouch, end: TouchPoint | null): void {
+    const notify = touch.onResolve;
+    this.drop(touch.id);
+    try {
+      notify(end);
+    } catch {
+      // One monitor's failure must not skip the other touch on this event.
+    }
+  }
+
+  private drop(id: number): void {
+    const touch = this.pending.get(id);
+    if (!touch || touch.settled) return;
+    touch.settled = true;
+    clearTimeout(touch.timer);
+    this.pending.delete(id);
+    this.stopListeningIfIdle();
+  }
+}
+
+/** Shared singleton used by the tap monitors. */
+export const gestureHandlerHandoff = new GestureHandlerHandoff();
+
+interface FiberTags {
+  /** Tags that can count as a tap. */
+  pressable: number[];
+  /** The fiber has a container handler and no pressable tag. */
+  container: boolean;
+}
+
+function tagsOnFiber(fiber: AnyFiber): FiberTags {
+  try {
+    const pressable: number[] = [];
+    const seen = new Set<number>();
+    let container = false;
+    const add = (tag: number | undefined, isContainer: boolean): void => {
+      if (tag === undefined) return;
+      if (isContainer) {
+        container = true;
+        return;
+      }
+      if (seen.has(tag)) return;
+      seen.add(tag);
+      pressable.push(tag);
+    };
+
+    const props = getMemoizedProps(fiber);
+    add(handlerTagOf(getStateNode(fiber)), props?.disallowInterruption === true);
+
+    const gesture = props?.gesture;
+    if (gesture && typeof gesture === 'object' && 'toGestureArray' in gesture) {
+      const toArray = (gesture as { toGestureArray?: unknown }).toGestureArray;
+      if (typeof toArray === 'function') {
+        const list = (toArray as () => unknown).call(gesture);
+        if (Array.isArray(list)) {
+          for (const item of list) {
+            const tag = handlerTagOf(item) ?? handlerTagOf(readHandlers(item));
+            add(tag, disallowsInterruption(item));
+          }
+        }
+      }
+    }
+    return { pressable, container: container && pressable.length === 0 };
+  } catch {
+    return { pressable: [], container: false };
+  }
+}
+
+/** Gesture-handler scroll containers set this so a drag is not stolen. */
+function disallowsInterruption(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || !('config' in value)) return false;
+  const config = (value as { config?: unknown }).config;
+  if (!config || typeof config !== 'object' || !('disallowInterruption' in config)) return false;
+  return (config as { disallowInterruption?: unknown }).disallowInterruption === true;
+}
+
+function readHandlers(value: unknown): unknown {
+  if (!value || typeof value !== 'object' || !('handlers' in value)) return undefined;
+  return (value as { handlers?: unknown }).handlers;
+}
+
+/** A mounted gesture-handler tag. `-1` means "not attached yet". */
+function handlerTagOf(value: unknown): number | undefined {
+  if (!value || typeof value !== 'object' || !('handlerTag' in value)) return undefined;
+  const tag = (value as { handlerTag?: unknown }).handlerTag;
+  if (typeof tag !== 'number' || !Number.isFinite(tag) || tag < 0) return undefined;
+  return tag;
+}
+
+function deviceEventEmitter(): DeviceEventEmitterLike | null {
+  try {
+    // Lazy so a tap that is never cancelled does not load React Native's emitter
+    // into unit tests that only exercise the monitors.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const reactNative = require('react-native') as {
+      DeviceEventEmitter?: DeviceEventEmitterLike;
+    };
+    const emitter = reactNative.DeviceEventEmitter;
+    if (!emitter || typeof emitter.addListener !== 'function') return null;
+    return emitter;
+  } catch {
+    return null;
+  }
+}
+
+function asPayload(event: unknown): GestureStatePayload | null {
+  if (!event || typeof event !== 'object') return null;
+  const raw = event as Record<string, unknown>;
+  const body =
+    raw.nativeEvent && typeof raw.nativeEvent === 'object'
+      ? (raw.nativeEvent as Record<string, unknown>)
+      : raw;
+  if (typeof body.handlerTag !== 'number' || typeof body.state !== 'number') return null;
+  return {
+    handlerTag: body.handlerTag,
+    state: body.state,
+    ...(typeof body.oldState === 'number' ? { oldState: body.oldState } : {}),
+    ...(typeof body.pointerInside === 'boolean' ? { pointerInside: body.pointerInside } : {}),
+    ...(typeof body.translationX === 'number' ? { translationX: body.translationX } : {}),
+    ...(typeof body.translationY === 'number' ? { translationY: body.translationY } : {}),
+    ...(typeof body.absoluteX === 'number' ? { absoluteX: body.absoluteX } : {}),
+    ...(typeof body.absoluteY === 'number' ? { absoluteY: body.absoluteY } : {}),
+    hasDuration: 'duration' in body && body.duration != null,
+  };
+}
+
+function isTerminal(state: number): boolean {
+  return (
+    state === GESTURE_HANDLER_STATE.FAILED ||
+    state === GESTURE_HANDLER_STATE.CANCELLED ||
+    state === GESTURE_HANDLER_STATE.END
+  );
+}
+
+function isCompletedTap(touch: PendingTouch, payload: GestureStatePayload): boolean {
+  if (payload.state !== GESTURE_HANDLER_STATE.END) return false;
+  if (payload.oldState !== GESTURE_HANDLER_STATE.ACTIVE) return false;
+  if (payload.pointerInside === false) return false;
+  if (payload.hasDuration) return false;
+  if (
+    payload.translationX !== undefined &&
+    payload.translationY !== undefined &&
+    !withinTapSlop(
+      { pageX: 0, pageY: 0 },
+      { pageX: payload.translationX, pageY: payload.translationY },
+    )
+  ) {
+    return false;
+  }
+  if (payload.absoluteX !== undefined && payload.absoluteY !== undefined) {
+    if (
+      !withinTapSlop(
+        { pageX: touch.pageX, pageY: touch.pageY },
+        { pageX: payload.absoluteX, pageY: payload.absoluteY },
+      )
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function endPoint(payload: GestureStatePayload): TouchPoint | null {
+  if (payload.absoluteX === undefined || payload.absoluteY === undefined) return null;
+  return { pageX: payload.absoluteX, pageY: payload.absoluteY };
+}

package/src/anchors/resolveAnchorHost.ts

@@ -15,6 +15,8 @@ import {
   setCachedFiberAnchor,
 } from './fiberAnchorCache';
 
+export { subscribeAnchorScreenChange } from './fiberAnchorCache';
+
 export type AnchorResolution =
   | { status: 'found'; host: AnchorHost; fiber?: AnyFiber }
   | { status: 'ambiguous' }

package/src/anchors/resolveAutoAnchorHost.ts

@@ -9,7 +9,7 @@ import type { AutoAnchorInstance } from './AutoAnchorRegistry';
 import type { AnyFiber } from './fiber/fiberInternals';
 import { fiberFromPublicInstance } from './fiber/fiberInternals';
 import { createFiberMeasureInWindow } from './fiber/measureHostFiber';
-import { resolveFiberPath } from './fiber/resolveFiberPath';
+import { resolveFiberPath, type FiberPathMissReason } from './fiber/resolveFiberPath';
 import { createVisibleInstanceFilter } from './isInstanceOnVisibleScreen';
 import { resolveAnchorHost } from './resolveAnchorHost';
 import { matchFingerprint, type MatchResult } from './semanticMatcher';
@@ -28,7 +28,15 @@ export type AutoAnchorResolution =
     }
   | { status: 'ambiguous'; match?: MatchResult }
   | { status: 'absent'; match?: MatchResult }
-  | { status: 'unknown'; match?: MatchResult };
+  | {
+      status: 'unknown';
+      match?: MatchResult;
+      /**
+       * Set when a fiber path did not resolve. Element conditions treat
+       * `no-match` as absent and `no-root` / `empty` as unknown.
+       */
+      fiberMiss?: FiberPathMissReason;
+    };
 
 type MeasureInWindowCallback = (x: number, y: number, width: number, height: number) => void;
 
@@ -121,7 +129,8 @@ export function resolveScoredAutoAnchor(fp: MobileFingerprint): AutoAnchorResolu
   if (visible.instance) return mapMatch(visible);
 
   if (visible.reason === 'no-candidates') {
-    const any = matchFingerprint(fp);
+    // Nothing can commit between the two matches, so the first read stands.
+    const any = matchFingerprint(fp, { liveContentFresh: true });
     if (any.instance) return { status: 'absent', match: any };
     if (any.reason === 'all-contradicted') return mapMatch(any);
   }
@@ -136,10 +145,11 @@ export function resolveScoredAutoAnchor(fp: MobileFingerprint): AutoAnchorResolu
  * carries a real `testID` / `userflowId` / non-`uf_` `nativeID` still resolves
  * under Babel `stampOnly: true` (no auto-registry population).
  *
- * Scored matches run over `autoAnchorRegistry` and fail closed: weak or
- * non-unique evidence is `unknown`, not `absent`, so ELEMENT gates stay blocked
- * rather than inventing a truth value. Hosts on a covered navigator screen
- * are skipped the same way the fiber scan skips them.
+ * Scored matches run over `autoAnchorRegistry`. A covered screen and a
+ * contradicted fingerprint are `absent`. Weak, missing, or tied evidence stays
+ * `unknown` here; element conditions decide which of those count as absent.
+ * Hosts on a covered navigator screen are skipped the same way the fiber scan
+ * skips them.
  */
 export function resolveAutoAnchorHost(
   autoData: string | MobileAutoData | null | undefined,
@@ -159,7 +169,7 @@ export function resolveAutoAnchorHost(
       };
     }
     if (fiberHit.status === 'ambiguous') return { status: 'ambiguous' };
-    return { status: 'unknown' };
+    return { status: 'unknown', fiberMiss: fiberHit.reason };
   }
 
   const exactId = exactIdFromFingerprint(fp);

package/src/anchors/resolveElementTargets.ts

@@ -6,9 +6,16 @@
  * `testID`, then a real `nativeID`) use that same multi-host lookup, and fall
  * through to scoring only when nothing matched.
  */
-import { decodeMobileAutoData, type FlowSelectorFragment } from '@userflow-tech/protocol';
+import {
+  decodeMobileAutoData,
+  type FlowSelectorFragment,
+  type MobileAutoData,
+} from '@userflow-tech/protocol';
+
+import { screenIdFromLocation, getCurrentScreenLocation } from '../screenTracker';
 
 import { type AnchorHost, anchorRegistry } from './AnchorRegistry';
+import { autoAnchorRegistry } from './AutoAnchorRegistry';
 import type { ElementTap } from './elementTapMonitor';
 import { anchorIdsAboveTap } from './elementTargetMatch';
 import { fiberScanRoot } from './fiber/FiberScanRoot';
@@ -85,21 +92,38 @@ function resolveAutoTargets(autoData: string | null): ElementTargetResolution {
   if (!decoded || !fingerprint) return { status: 'unknown' };
 
   if (decoded.resolver === 'fiber' && decoded.fiberPath) {
-    return fromAutoResolution(resolveAutoAnchorHost(decoded));
+    return conditionVerdict(resolveAutoAnchorHost(decoded), decoded);
   }
 
   const exactId = exactIdFromFingerprint(fingerprint);
+  let exactIdAbsent = false;
   if (exactId) {
     const manual = resolveManualTargets(exactId);
     if (manual.status === 'found') return manual;
+    // "Absent" before a scan root exists only means we have not looked yet.
+    exactIdAbsent = fiberScanRoot.getFiber() != null;
   }
 
   // The exact id already missed above, so go straight to scoring rather than
   // letting resolveAutoAnchorHost scan for it again.
-  return fromAutoResolution(resolveScoredAutoAnchor(fingerprint));
+  return conditionVerdict(resolveScoredAutoAnchor(fingerprint), decoded, exactIdAbsent);
 }
 
-function fromAutoResolution(resolution: AutoAnchorResolution): ElementTargetResolution {
+/**
+ * Turn an AUTO resolution into the value an element condition can report.
+ *
+ * A miss (nothing scored, or an exact id that a scan did not find) is absent,
+ * matching web. A tie stays unknown on the screen where the element was picked,
+ * because the target may be one of the look-alikes, and is absent on any other
+ * screen. An empty registry with no exact id, a missing scan root, and a
+ * missing fingerprint stay unknown so `stampOnly` cannot open a "not present"
+ * gate.
+ */
+function conditionVerdict(
+  resolution: AutoAnchorResolution,
+  decoded: MobileAutoData,
+  exactIdAbsent = false,
+): ElementTargetResolution {
   if (resolution.status === 'found') {
     // Scored matches only try the direct ref pointer, which Paper release
     // builds null out. Without the index fallback a tap could never match.
@@ -112,12 +136,45 @@ function fromAutoResolution(resolution: AutoAnchorResolution): ElementTargetReso
     };
   }
   if (resolution.status === 'absent') return { status: 'absent' };
-  // Ambiguous and unknown both fail closed. Ambiguous is a real tie, not a
-  // broken selector, so it does not warn.
-  if (resolution.status === 'ambiguous') return { status: 'unknown', silent: true };
+
+  if (resolution.status === 'unknown') {
+    if (resolution.fiberMiss === 'no-root' || resolution.fiberMiss === 'empty') {
+      return { status: 'unknown' };
+    }
+    if (resolution.fiberMiss === 'no-match') return { status: 'absent' };
+  }
+
+  const reason = resolution.match?.reason;
+  const tie =
+    resolution.status === 'ambiguous' ||
+    reason === 'not-unique' ||
+    reason === 'ambiguous-explicit-id';
+  if (tie) {
+    if (offPickedScreen(decoded.screenId)) return { status: 'absent' };
+    // A real tie is not a broken selector, so it does not warn. A weak
+    // not-unique miss still does, matching the previous unknown report.
+    return reason === 'not-unique' ? { status: 'unknown' } : { status: 'unknown', silent: true };
+  }
+
+  if (reason === 'below-threshold') return { status: 'absent' };
+
+  if (reason === 'no-candidates') {
+    const nothingToMatch = autoAnchorRegistry.allInstances().length === 0 && !exactIdAbsent;
+    if (nothingToMatch) return { status: 'unknown' };
+    return { status: 'absent' };
+  }
+
   return { status: 'unknown' };
 }
 
+/** True when the picked screen is known and the app is on a different one. */
+function offPickedScreen(pickedScreenId: string | undefined): boolean {
+  if (!pickedScreenId || pickedScreenId === 'unknown') return false;
+  const current = screenIdFromLocation(getCurrentScreenLocation());
+  if (current === 'unknown') return false;
+  return current !== pickedScreenId;
+}
+
 function resolveManualTargets(id: string): ElementTargetResolution {
   const registered = anchorRegistry.getAll(id);
   if (registered.length > 0) {

package/src/anchors/semanticMatcher.ts

@@ -190,18 +190,21 @@ function intrinsicNonTextAgrees(fp: MobileFingerprint, inst: AutoAnchorInstance)
   );
 }
 
+/**
+ * An id or kind conflict, or a childText disagreement no text-independent
+ * identity (authoritative id, matching icon/image) vouches for.
+ */
+function isContradicted(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  if (contradictsStrong(fp, inst)) return true;
+  return childTextDisagrees(fp, inst) && !idAgrees(fp, inst) && !intrinsicNonTextAgrees(fp, inst);
+}
+
 function scoreInstance(
   fp: MobileFingerprint,
   inst: AutoAnchorInstance,
   ambiguous: boolean,
 ): number {
-  if (contradictsStrong(fp, inst)) return -Infinity;
-
-  // A childText disagreement is disqualifying unless a text-independent identity
-  // vouches for the element (authoritative id, or matching icon/image).
-  if (childTextDisagrees(fp, inst) && !idAgrees(fp, inst) && !intrinsicNonTextAgrees(fp, inst)) {
-    return -Infinity;
-  }
+  if (isContradicted(fp, inst)) return -Infinity;
 
   let score = 0;
 
@@ -231,11 +234,14 @@ function scoreInstance(
 
   score += scoreAncestors(fp.ancestors ?? [], inst.ancestors ?? []);
 
-  const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
-  score += scoreSiblingWindow(fp.previousSiblings ?? [], window.previous);
-  // Score next siblings once. The POC added a reversed pass *and* a direct pass,
-  // which double-counted the next window.
-  score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
+  // The window scans the registry, so skip it when there is nothing to compare.
+  if (fp.previousSiblings?.length || fp.nextSiblings?.length) {
+    const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
+    score += scoreSiblingWindow(fp.previousSiblings ?? [], window.previous);
+    // Score next siblings once. The POC added a reversed pass *and* a direct pass,
+    // which double-counted the next window.
+    score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
+  }
 
   if (ambiguous && !inst.manualId) score -= 40;
 
@@ -246,6 +252,8 @@ type InstanceFilter = (inst: AutoAnchorInstance) => boolean;
 
 interface MatchOptions {
   instanceFilter?: InstanceFilter;
+  /** The caller refreshed live content earlier in this same synchronous call. */
+  liveContentFresh?: boolean;
 }
 
 /** Each instance's visibility is computed once per match. */
@@ -260,10 +268,7 @@ function memoizeFilter(filter: InstanceFilter): InstanceFilter {
   };
 }
 
-function candidatePool(
-  fp: MobileFingerprint,
-  instanceFilter?: InstanceFilter,
-): AutoAnchorInstance[] {
+function candidatePool(fp: MobileFingerprint): AutoAnchorInstance[] {
   // Explicit ids are authoritative: a miss is no-candidates, not a full-registry search.
   let pool: AutoAnchorInstance[];
   if (fp.manualId) {
@@ -286,29 +291,45 @@ function candidatePool(
       if (filtered.length > 0) pool = filtered;
     }
   }
-  return instanceFilter ? pool.filter(instanceFilter) : pool;
+  return pool;
 }
 
 function miss(reason: MatchMissReason, score = 0, secondScore = 0): MatchResult {
   return { instance: null, score, secondScore, reason };
 }
 
-function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFilter): MatchResult {
+function matchFingerprintCore(
+  fp: MobileFingerprint,
+  instanceFilter?: InstanceFilter,
+  liveContentFresh = false,
+): MatchResult {
   // Live text / testID must be applied *before* pooling. A shared Babel helper
   // (`const field = () => <TextInput testID={id} />`) reuses one auto-anchor
   // callback, so the runtime bag is last-writer-wins until we read the host.
+  // An unchanged host is a fiber and props-identity check after one shared
+  // ancestor walk per pass, so refreshing every instance stays cheap; the
+  // per-instance screen walk is what is not, and it only runs for the pool
+  // below.
+  const all = autoAnchorRegistry.allInstances();
+  if (all.length > 0 && !liveContentFresh) {
+    autoAnchorRegistry.refreshLiveContent(all);
+  }
+
   // A filter's verdict is memoized so covered-screen checks run once per instance.
   const filter = instanceFilter ? memoizeFilter(instanceFilter) : undefined;
-  const broad = filter
-    ? autoAnchorRegistry.allInstances().filter(filter)
-    : autoAnchorRegistry.allInstances();
-  if (broad.length > 0) {
-    autoAnchorRegistry.refreshLiveContent(broad);
+  const candidates = candidatePool(fp);
+  // A contradiction does not depend on visibility, so settle it before the
+  // covered-screen check. Visibility of contradicted instances only matters to
+  // tell `all-contradicted` from `no-candidates` when nothing else is left.
+  const viable: AutoAnchorInstance[] = [];
+  const contradicted: AutoAnchorInstance[] = [];
+  for (const inst of candidates) {
+    (isContradicted(fp, inst) ? contradicted : viable).push(inst);
   }
-
-  const pool = candidatePool(fp, filter);
+  const pool = filter ? viable.filter(filter) : viable;
   if (pool.length === 0) {
-    return miss('no-candidates');
+    const anyContradictedCandidate = filter ? contradicted.some(filter) : contradicted.length > 0;
+    return miss(anyContradictedCandidate ? 'all-contradicted' : 'no-candidates');
   }
 
   // Visibility can clear a registry-wide ambiguous flag (a covered twin) but
@@ -367,7 +388,7 @@ function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFi
  * can flag weak (`structural`) targets.
  */
 export function matchFingerprint(fp: MobileFingerprint, opts?: MatchOptions): MatchResult {
-  const result = matchFingerprintCore(fp, opts?.instanceFilter);
+  const result = matchFingerprintCore(fp, opts?.instanceFilter, opts?.liveContentFresh);
   if (fp.identityStrength) result.identityStrength = fp.identityStrength;
   return result;
 }

package/src/anchors/tapSlop.ts

@@ -0,0 +1,18 @@
+/** Max finger travel (px) between start and end to count as a tap, not a scroll. */
+export const TARGET_PRESS_TAP_SLOP = 10;
+
+export interface TouchPoint {
+  pageX: number;
+  pageY: number;
+}
+
+/** True when the finger moved no more than `slop` between start and end. */
+export function withinTapSlop(
+  start: TouchPoint,
+  end: TouchPoint,
+  slop: number = TARGET_PRESS_TAP_SLOP,
+): boolean {
+  const dx = end.pageX - start.pageX;
+  const dy = end.pageY - start.pageY;
+  return dx * dx + dy * dy <= slop * slop;
+}