@userflow-tech/react-native 0.4.4 → 0.5.0

package/lib/typescript/module/src/surfaces/resolveBannerTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveBannerTheme.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveBannerTheme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,yGAAyG;AACzG,eAAO,MAAM,+BAA+B,YAAY,CAAC;AACzD,eAAO,MAAM,+BAA+B,YAAY,CAAC;AAOzD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzE;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzE"}
+{"version":3,"file":"resolveBannerTheme.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveBannerTheme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,+BAA+B,YAAY,CAAC;AACzD,eAAO,MAAM,+BAA+B,YAAY,CAAC;AAOzD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAMzE;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAMzE"}

package/lib/typescript/module/src/surfaces/tooltip/TooltipBubble.d.ts

@@ -15,6 +15,12 @@ export interface TooltipBubbleProps {
      * target. Defaults to true so isolated chrome tests keep the diamond.
      */
     showNotch?: boolean;
+    /**
+     * iOS: confine VoiceOver to this card. VoiceOver then skips the host app,
+     * including the target, so set it only while the host is hidden from
+     * accessibility anyway. Defaults to false.
+     */
+    accessibilityViewIsModal?: boolean;
 }
 /**
  * Tooltip chrome shell: diamond notch + card fill sharing one shadow family.
@@ -34,5 +40,5 @@ export interface TooltipBubbleProps {
  * iOS gets `shadow*` on the notch (`elevation` is inert there); Android gets
  * `elevation`, which is the only shadow it honors on a rotated view.
  */
-export declare function TooltipBubble({ chrome, notchPosition, style, onLayout, children, maxHeight, showNotch: showNotchProp, }: TooltipBubbleProps): React.ReactElement;
+export declare function TooltipBubble({ chrome, notchPosition, style, onLayout, children, maxHeight, showNotch: showNotchProp, accessibilityViewIsModal, }: TooltipBubbleProps): React.ReactElement;
 //# sourceMappingURL=TooltipBubble.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/TooltipBubble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipBubble.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipBubble.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC9C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,aAAa,EACb,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,SAAS,EAAE,aAAoB,GAChC,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAgIzC"}
+{"version":3,"file":"TooltipBubble.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipBubble.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC9C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,aAAa,EACb,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,SAAS,EAAE,aAAoB,EAC/B,wBAAgC,GACjC,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAgIzC"}

package/lib/typescript/module/src/surfaces/tooltip/targetSearchSchedule.d.ts

@@ -0,0 +1,60 @@
+/**
+ * When TooltipSurface looks for its target.
+ *
+ * - Anchored: a steady poll, so a covered or remounted host is noticed quickly.
+ *   Each search is a cache hit for the resolved host.
+ * - Missing: exponential backoff. A miss walks the tree and scores registered
+ *   hosts, so a target on another screen must not cost a full search every
+ *   second for as long as the flow stays open.
+ * - Registry churn (list rows mounting while the user scrolls) pulls the next
+ *   missing search forward, never closer than {@link MISSING_TRIGGER_GAP_MS}
+ *   to the previous one.
+ * - A screen change or a return to the foreground starts the backoff over.
+ * - Nothing runs while paused (app not active).
+ */
+/** Poll while the target is anchored. */
+export declare const ANCHORED_POLL_MS = 250;
+/** First retry after a miss; doubles per consecutive miss. */
+export declare const MISSING_BACKOFF_BASE_MS = 250;
+/** Ceiling for the missing-target backoff. */
+export declare const MISSING_BACKOFF_MAX_MS = 4000;
+/** Closest a registry change can pull a missing search to the previous one. */
+export declare const MISSING_TRIGGER_GAP_MS = 500;
+export type TargetSearchMode = 'anchored' | 'missing';
+export interface TargetSearchClock {
+    now(): number;
+    setTimeout(handler: () => void, ms: number): ReturnType<typeof setTimeout>;
+    clearTimeout(handle: ReturnType<typeof setTimeout>): void;
+}
+/** Delay before the next search after `misses` consecutive missing searches. */
+export declare function missingBackoffDelay(misses: number): number;
+export declare class TargetSearchSchedule {
+    private readonly search;
+    private readonly clock;
+    private mode;
+    /** Searches run since the target was last anchored (or the backoff restarted). */
+    private misses;
+    private lastRunAt;
+    private handle;
+    private dueAt;
+    private paused;
+    private disposed;
+    constructor(search: () => void, clock?: TargetSearchClock);
+    /** Search now and schedule the next one. No-op while paused. */
+    runNow(): void;
+    /** The target was found or lost. Starts the matching cadence from now. */
+    setMode(mode: TargetSearchMode): void;
+    /** Something the target may depend on changed (a registry mount / unmount). */
+    trigger(): void;
+    /** Restart the backoff and search now (screen change, foreground). */
+    rearm(): void;
+    /** Stop searching until {@link resume}. */
+    pause(): void;
+    /** Leave the paused state and search right away. */
+    resume(): void;
+    dispose(): void;
+    private nextDelay;
+    private scheduleIn;
+    private cancel;
+}
+//# sourceMappingURL=targetSearchSchedule.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/targetSearchSchedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targetSearchSchedule.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/targetSearchSchedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,GAAG,IAAI,MAAM,CAAC;IACd,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAC3E,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAC;CAC3D;AAQD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,qBAAa,oBAAoB;IAW7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXxB,OAAO,CAAC,IAAI,CAA+B;IAC3C,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,MAAM,CAA8C;IAC5D,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;gBAGN,MAAM,EAAE,MAAM,IAAI,EAClB,KAAK,GAAE,iBAAgC;IAG1D,gEAAgE;IAChE,MAAM,IAAI,IAAI;IAcd,0EAA0E;IAC1E,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAQrC,+EAA+E;IAC/E,OAAO,IAAI,IAAI;IAQf,sEAAsE;IACtE,KAAK,IAAI,IAAI;IAMb,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAMb,oDAAoD;IACpD,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,MAAM;CAOf"}

package/lib/typescript/module/src/version.d.ts

@@ -1,3 +1,3 @@
 /** Generated by scripts/write-version.mjs — do not edit. */
-export declare const SDK_VERSION = "0.4.4";
+export declare const SDK_VERSION = "0.5.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userflow-tech/react-native",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Userflow SDK for React Native — onboarding flows, tooltips, and modals.",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./lib/commonjs/index.js",

package/src/anchors/AutoAnchorRegistry.ts

@@ -1,7 +1,11 @@
 import type { SemanticRole, SemanticSegment, SiblingDescriptor } from '@userflow-tech/protocol';
 import type { MutableRefObject, RefObject } from 'react';
 
-import { getLiveHostProps, type AnyFiber } from './fiber/fiberInternals';
+import {
+  createCurrentFiberResolver,
+  getLiveHostProps,
+  type AnyFiber,
+} from './fiber/fiberInternals';
 import {
   createLazyHostFiberIndex,
   lookupHostFiber,
@@ -134,10 +138,20 @@ function contentSignature(inst: AutoAnchorInstance): string | undefined {
 }
 
 interface LiveContentCache {
+  /** The fiber of the pair that was committed when read. */
   fiber: AnyFiber;
-  /** Props object identity — React replaces it on every render. */
+  /** That fiber's props object. */
   props: Record<string, unknown> | undefined;
-  childText: string;
+  /** Undefined when the host shows no readable text (the hint stays). */
+  childText: string | undefined;
+}
+
+/** Twin evidence for one registry group, computed once per settle. */
+interface TwinGroup {
+  /** More than one member and none carries a manual id. */
+  unlabelled: boolean;
+  /** How many members show each content signature. */
+  signatures: Map<string, number>;
 }
 
 export class AutoAnchorRegistry {
@@ -148,6 +162,22 @@ export class AutoAnchorRegistry {
   private readonly liveContent = new Map<string, LiveContentCache>();
   private readonly listeners = new Set<AutoAnchorListener>();
   private notifyScheduled = false;
+  /** Settled {@link AutoAnchorInstance.ambiguous} verdicts by instance id. */
+  private readonly ambiguity = new Map<string, boolean>();
+  /**
+   * Groups whose verdicts are out of date: `r:` registry key, `t:` template
+   * path, `m:` manual id. Mounting a list or reading changed row labels marks
+   * a group once; it is settled once, on the next read of a verdict, instead
+   * of being recomputed for every member that changed.
+   */
+  private readonly staleGroups = new Set<string>();
+  /**
+   * Set instead of {@link staleGroups} once that outgrows the registry: with
+   * no flow or element condition reading verdicts, marks from list mounts
+   * would otherwise pile up for the whole session.
+   */
+  private allStale = false;
+  private settling = false;
 
   registerInstance(input: RegisterInstanceInput): { instanceId: string; dispose: () => void } {
     const instanceId = mintInstanceId();
@@ -200,6 +230,7 @@ export class AutoAnchorRegistry {
       childInstanceIds: [],
       ambiguous: false,
     };
+    this.defineAmbiguity(instance);
 
     this.instances.set(instanceId, instance);
     this.addIndex(this.byRegistryKey, input.registryKey, instanceId);
@@ -213,7 +244,7 @@ export class AutoAnchorRegistry {
       if (parent) parent.childInstanceIds.push(instanceId);
     }
 
-    this.recomputeAmbiguity(input.registryKey, templatePath, manualId);
+    this.markStale(instance);
     this.notify();
 
     return {
@@ -272,7 +303,7 @@ export class AutoAnchorRegistry {
       else delete inst.manualId;
     }
     this.refreshManualIndexes(inst, prevIds);
-    this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
+    this.markStale(inst, prevIds.manualId, prevIds.userflowId, prevIds.testID);
     this.notify();
   }
 
@@ -339,25 +370,32 @@ export class AutoAnchorRegistry {
    *
    * Direct fiber pointers are preferred; the scan-root index is built lazily
    * and only if some instance cannot reach its fiber that way (Paper release
-   * builds, mainly), then reused for the rest of the pass.
+   * builds, mainly), then reused for the rest of the pass. Finding which fiber
+   * of each pair is committed walks to the root; the pass shares one walk per
+   * ancestor across every instance.
    *
    * Silent — does not notify listeners.
    */
   refreshLiveContent(instances?: AutoAnchorInstance[]): void {
     const list = instances ?? this.allInstances();
     const getIndex = createLazyHostFiberIndex();
+    const resolveCurrent = createCurrentFiberResolver();
     const seen = new Set<string>();
     for (const inst of list) {
       if (seen.has(inst.instanceId)) continue;
       seen.add(inst.instanceId);
-      this.refreshOneLiveContent(inst, getIndex);
+      this.refreshOneLiveContent(inst, getIndex, resolveCurrent);
     }
   }
 
-  private refreshOneLiveContent(inst: AutoAnchorInstance, getIndex: () => HostFiberIndex): void {
+  private refreshOneLiveContent(
+    inst: AutoAnchorInstance,
+    getIndex: () => HostFiberIndex,
+    resolveCurrent: (fiber: AnyFiber) => AnyFiber,
+  ): void {
     let fiber: AnyFiber | null = null;
     try {
-      fiber = lookupHostFiber(getIndex, inst.ref.current);
+      fiber = lookupHostFiber(getIndex, inst.ref.current, resolveCurrent);
     } catch {
       fiber = null;
     }
@@ -370,12 +408,17 @@ export class AutoAnchorRegistry {
       props = undefined;
     }
 
+    // Same committed fiber and same props object means nothing was committed
+    // here since the last read, so the subtree walk would return what we
+    // already have. A commit that re-renders this host or anything inside it
+    // makes the other fiber of the pair current, even when the host keeps its
+    // props object. Both only change at commit, unlike Fabric's
+    // `canonical.currentProps`, which is written during render and stays the
+    // same object when only a child changed. Matters because resolution polls
+    // this for every registered instance.
     const cached = this.liveContent.get(inst.instanceId);
-    // Same fiber and same props object means no re-render since the last read,
-    // so the subtree walk would return what we already have. Matters because
-    // resolution polls this for every registered instance.
     if (cached && cached.fiber === fiber && props !== undefined && cached.props === props) {
-      inst.childText = cached.childText;
+      if (cached.childText !== undefined) inst.childText = cached.childText;
       return;
     }
 
@@ -391,17 +434,14 @@ export class AutoAnchorRegistry {
       live = undefined;
     }
 
-    if (live) {
-      const changed = inst.childText !== live;
+    // A host with no readable text is cached too, so it is not walked again
+    // until it re-renders; its build-time hint stays.
+    this.liveContent.set(inst.instanceId, { fiber, props, childText: live });
+    if (live && inst.childText !== live) {
       inst.childText = live;
-      this.liveContent.set(inst.instanceId, { fiber, props, childText: live });
       // Text is what separates helper-rendered twins, so the group's ambiguity
       // verdict is only trustworthy once it has been read.
-      if (changed) this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
-      return;
-    }
-    if (cached && cached.fiber !== fiber) {
-      this.liveContent.delete(inst.instanceId);
+      this.markStale(inst);
     }
   }
 
@@ -421,7 +461,7 @@ export class AutoAnchorRegistry {
       inst.manualId = liveTestID;
     }
     this.refreshManualIndexes(inst, prev);
-    this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
+    this.markStale(inst, prev.manualId, prev.userflowId, prev.testID);
   }
 
   subscribe(listener: AutoAnchorListener): () => void {
@@ -462,6 +502,9 @@ export class AutoAnchorRegistry {
     this.byManualId.clear();
     this.byTemplatePath.clear();
     this.liveContent.clear();
+    this.ambiguity.clear();
+    this.staleGroups.clear();
+    this.allStale = false;
     this.notifyScheduled = false;
     nextInstanceSeq = 1;
   }
@@ -483,13 +526,14 @@ export class AutoAnchorRegistry {
 
     this.instances.delete(instanceId);
     this.liveContent.delete(instanceId);
+    this.ambiguity.delete(instanceId);
     this.removeIndex(this.byRegistryKey, inst.registryKey, instanceId);
     this.removeIndex(this.byTemplatePath, inst.templatePath, instanceId);
     if (inst.manualId) this.removeIndex(this.byManualId, inst.manualId, instanceId);
     if (inst.userflowId) this.removeIndex(this.byManualId, inst.userflowId, instanceId);
     if (inst.testID) this.removeIndex(this.byManualId, inst.testID, instanceId);
 
-    this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
+    this.markStale(inst);
     this.notify();
   }
 
@@ -533,29 +577,116 @@ export class AutoAnchorRegistry {
     return false;
   }
 
+  /**
+   * Back {@link AutoAnchorInstance.ambiguous} with a verdict that is settled on
+   * read, so callers holding an instance always see the current value.
+   */
+  private defineAmbiguity(inst: AutoAnchorInstance): void {
+    const id = inst.instanceId;
+    Object.defineProperty(inst, 'ambiguous', {
+      configurable: true,
+      enumerable: true,
+      get: () => {
+        this.settleAmbiguity();
+        return this.ambiguity.get(id) ?? false;
+      },
+      set: (value: boolean) => {
+        this.ambiguity.set(id, value);
+      },
+    });
+  }
+
+  /** Every group `inst` belongs to, plus ids it was indexed under before a change. */
+  private markStale(inst: AutoAnchorInstance, ...previousIds: Array<string | undefined>): void {
+    if (this.allStale) return;
+    this.staleGroups.add(`r:${inst.registryKey}`);
+    this.staleGroups.add(`t:${inst.templatePath}`);
+    for (const id of [inst.manualId, inst.userflowId, inst.testID, ...previousIds]) {
+      if (id) this.staleGroups.add(`m:${id}`);
+    }
+    // Settling every instance is linear in the registry, so past this size
+    // tracking groups no longer saves work.
+    if (this.staleGroups.size > this.instances.size) {
+      this.allStale = true;
+      this.staleGroups.clear();
+    }
+  }
+
+  private groupIds(groupKey: string): Set<string> | undefined {
+    const value = groupKey.slice(2);
+    if (groupKey.startsWith('r:')) return this.byRegistryKey.get(value);
+    if (groupKey.startsWith('t:')) return this.byTemplatePath.get(value);
+    return this.byManualId.get(value);
+  }
+
   /**
    * Instances sharing a template path are only twins while they look alike.
    * Four rows from one `field()` helper are indistinguishable at register time
    * and separate once their labels are read, so ambiguity is decided on
    * content, not on the shared path alone. An instance stays ambiguous when it
    * carries no content of its own, or when a peer carries the same content.
+   * An instance with a manual id is ambiguous only when another shares the id.
+   *
+   * Each stale group is settled once, in time linear in its size: recomputing
+   * a whole group for every member that changed made a list whose labels all
+   * changed cost the cube of its length.
    */
-  private recomputeAmbiguity(registryKey: string, templatePath: string, manualId?: string): void {
-    const mark = (list: AutoAnchorInstance[]) => {
-      for (const i of list) {
-        i.ambiguous =
-          this.isTwinWithin(i, list) ||
-          (i.manualId ? this.getInstancesByManualId(i.manualId).length > 1 : false);
+  private settleAmbiguity(): void {
+    if ((this.staleGroups.size === 0 && !this.allStale) || this.settling) return;
+    this.settling = true;
+    try {
+      const affected = new Set<string>(this.allStale ? this.instances.keys() : []);
+      for (const groupKey of this.staleGroups) {
+        const ids = this.groupIds(groupKey);
+        if (ids) for (const id of ids) affected.add(id);
       }
-    };
-    mark(this.getInstancesByRegistryKey(registryKey));
-    mark(this.getInstancesByTemplatePath(templatePath));
-    if (manualId) {
-      const list = this.getInstancesByManualId(manualId);
-      for (const i of list) i.ambiguous = list.length > 1;
+      this.staleGroups.clear();
+      this.allStale = false;
+
+      const twinGroups = new Map<string, TwinGroup>();
+      for (const id of affected) {
+        const inst = this.instances.get(id);
+        if (!inst) continue;
+        this.ambiguity.set(id, this.computeAmbiguous(inst, twinGroups));
+      }
+    } finally {
+      this.settling = false;
     }
   }
 
+  private computeAmbiguous(inst: AutoAnchorInstance, twinGroups: Map<string, TwinGroup>): boolean {
+    if (inst.manualId) return (this.byManualId.get(inst.manualId)?.size ?? 0) > 1;
+    return (
+      this.isTwinInGroup(inst, `r:${inst.registryKey}`, twinGroups) ||
+      this.isTwinInGroup(inst, `t:${inst.templatePath}`, twinGroups)
+    );
+  }
+
+  /** {@link isTwinWithin} against a whole registry group, with the group's evidence memoized. */
+  private isTwinInGroup(
+    inst: AutoAnchorInstance,
+    groupKey: string,
+    twinGroups: Map<string, TwinGroup>,
+  ): boolean {
+    let group = twinGroups.get(groupKey);
+    if (!group) {
+      const members = this.idsToInstances(this.groupIds(groupKey));
+      const signatures = new Map<string, number>();
+      for (const member of members) {
+        const sig = contentSignature(member);
+        if (sig) signatures.set(sig, (signatures.get(sig) ?? 0) + 1);
+      }
+      group = {
+        unlabelled: members.length > 1 && members.every((member) => !member.manualId),
+        signatures,
+      };
+      twinGroups.set(groupKey, group);
+    }
+    if (!group.unlabelled) return false;
+    const sig = contentSignature(inst);
+    return !sig || (group.signatures.get(sig) ?? 0) > 1;
+  }
+
   private addIndex(map: Map<string, Set<string>>, key: string, instanceId: string): void {
     let set = map.get(key);
     if (!set) {

package/src/anchors/animationFrame.ts

@@ -1,13 +1,21 @@
 /**
  * Shared requestAnimationFrame hub so multiple surfaces never stack loops.
  * Mirrors web userflowjs `util/animation-frame.tsx`.
+ *
+ * Paused while the app is not active. In bridgeless React Native,
+ * `requestAnimationFrame` is a 0 ms timer, and once the app is backgrounded
+ * iOS fires timers from an NSTimer instead of the display link, so a loop that
+ * kept going would spin as fast as the JS thread allows.
  */
+import { isAppActive, subscribeAppActive } from './appActive';
 
 type Callback = () => void;
 
 const callbacks: Callback[] = [];
 let rafHandle: number | ReturnType<typeof setTimeout> | null = null;
 let active = false;
+let appActive = true;
+let unsubscribeAppActive: (() => void) | null = null;
 
 /**
  * `callback` runs on every animation frame. Starts the shared loop when the
@@ -18,6 +26,7 @@ export function addAnimationFrameCallback(callback: Callback): void {
   callbacks.push(callback);
   if (callbacks.length === 1) {
     active = true;
+    watchAppState();
     requestNext();
   }
 }
@@ -33,6 +42,7 @@ export function removeAnimationFrameCallback(callback: Callback): void {
   if (callbacks.length === 0) {
     active = false;
     cancelPending();
+    unwatchAppState();
   }
 }
 
@@ -41,6 +51,7 @@ export function resetAnimationFrameForTests(): void {
   callbacks.length = 0;
   active = false;
   cancelPending();
+  unwatchAppState();
 }
 
 /** Test helper — number of active subscribers. */
@@ -62,8 +73,27 @@ function onAnimationFrame(): void {
   requestNext();
 }
 
+function watchAppState(): void {
+  if (unsubscribeAppActive) return;
+  appActive = isAppActive();
+  unsubscribeAppActive = subscribeAppActive((next) => {
+    appActive = next;
+    if (!next) {
+      cancelPending();
+    } else if (rafHandle == null) {
+      requestNext();
+    }
+  });
+}
+
+function unwatchAppState(): void {
+  unsubscribeAppActive?.();
+  unsubscribeAppActive = null;
+  appActive = true;
+}
+
 function requestNext(): void {
-  if (!active) return;
+  if (!active || !appActive) return;
   const raf =
     typeof globalThis.requestAnimationFrame === 'function'
       ? globalThis.requestAnimationFrame.bind(globalThis)

package/src/anchors/appActive.ts

@@ -0,0 +1,63 @@
+import { AppState } from 'react-native';
+
+/**
+ * Foreground signal for the anchoring loops (animation-frame tracking and the
+ * tooltip target search).
+ *
+ * Anything other than `background` / `inactive` counts as active, including
+ * `unknown` before the first native report. Hosts or test doubles without
+ * `AppState` always read as active and never notify.
+ */
+
+type AppStateLike = {
+  currentState?: unknown;
+  addEventListener?: (
+    type: 'change',
+    handler: (state: unknown) => void,
+  ) => { remove: () => void } | undefined;
+};
+
+function appState(): AppStateLike | null {
+  const candidate = AppState as AppStateLike | undefined;
+  return candidate && typeof candidate === 'object' ? candidate : null;
+}
+
+function isActiveState(state: unknown): boolean {
+  return state !== 'background' && state !== 'inactive';
+}
+
+/** Whether the app is in the foreground right now. */
+export function isAppActive(): boolean {
+  try {
+    return isActiveState(appState()?.currentState);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * `listener(active)` runs when the app moves between foreground and anything
+ * else. Repeated reports of the same side are dropped. Returns an unsubscribe.
+ */
+export function subscribeAppActive(listener: (active: boolean) => void): () => void {
+  const state = appState();
+  if (!state || typeof state.addEventListener !== 'function') return () => {};
+  let active = isAppActive();
+  try {
+    const subscription = state.addEventListener('change', (next) => {
+      const nextActive = isActiveState(next);
+      if (nextActive === active) return;
+      active = nextActive;
+      listener(nextActive);
+    });
+    return () => {
+      try {
+        subscription?.remove();
+      } catch {
+        // Teardown is best-effort.
+      }
+    };
+  } catch {
+    return () => {};
+  }
+}

package/src/anchors/elementConditionEvaluator.ts

@@ -7,7 +7,7 @@ import { decodeMobileAutoData, type FlowConditionFragment } from '@userflow-tech
 
 import { anchorChangeTicker } from './anchorChangeTicker';
 import { elementTapMonitor } from './elementTapMonitor';
-import { fiberIsUnder, tapPathDisabled } from './elementTargetMatch';
+import { fiberBearingAnchorId, fiberIsUnder, tapPathDisabled } from './elementTargetMatch';
 import {
   resolveElementTargets,
   tapMayHitSelector,
@@ -188,22 +188,39 @@ function trackClick(
   const subscription = {
     unsubscribe: (): void => {},
   };
+  const latch = (): void => {
+    latched = true;
+    report(valueWhenOccurred, { immediate: true });
+    subscription.unsubscribe();
+    stopWatchingResolution();
+  };
+
   subscription.unsubscribe = elementTapMonitor.subscribe((tap) => {
     if (latched) return;
     if (!tapMayHitSelector(condition.selector, tap)) return;
-    const resolution = resolveElementTargets(condition.selector);
-    if (resolution.status !== 'found') return;
 
-    const matched = resolution.targets.find(
-      (target) => target.fiber != null && fiberIsUnder(tap.targetFiber, target.fiber),
-    );
-    if (!matched?.fiber) return;
-    if (tapPathDisabled(tap.targetFiber, matched.fiber)) return;
+    const resolution = resolveElementTargets(condition.selector);
+    if (resolution.status === 'found') {
+      const matched = resolution.targets.find(
+        (target) => target.fiber != null && fiberIsUnder(tap.targetFiber, target.fiber),
+      );
+      if (!matched?.fiber) return;
+      if (tapPathDisabled(tap.targetFiber, matched.fiber)) return;
+      latch();
+      return;
+    }
 
-    latched = true;
-    report(valueWhenOccurred, { immediate: true });
-    subscription.unsubscribe();
-    stopWatchingResolution();
+    // The press may already have navigated away, so the live scan is absent.
+    // The fiber captured at touch start still carries the manual id. This is
+    // only the fallback: a target that is still on screen keeps the registry
+    // and prop-tier precedence of the live scan.
+    if (resolution.status !== 'absent') return;
+    if ((condition.selector?.type as string | null) === 'AUTO') return;
+    const anchorId = resolveManualAnchorId(condition.selector?.css);
+    const capturedHost = anchorId ? fiberBearingAnchorId(tap.targetFiber, anchorId) : null;
+    if (!capturedHost) return;
+    if (tapPathDisabled(tap.targetFiber, capturedHost)) return;
+    latch();
   });
 
   return () => {