@userflow-tech/react-native 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userflow-tech/react-native",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Userflow SDK for React Native — onboarding flows, tooltips, and modals.",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./lib/commonjs/index.js",
@@ -10,6 +10,10 @@
   "source": "src/index.ts",
   "exports": {
     ".": {
+      "types": {
+        "import": "./lib/typescript/module/src/index.d.ts",
+        "require": "./lib/typescript/commonjs/src/index.d.ts"
+      },
       "react-native": "./src/index.ts",
       "import": {
         "types": "./lib/typescript/module/src/index.d.ts",
@@ -21,6 +25,10 @@
       }
     },
     "./navigation": {
+      "types": {
+        "import": "./lib/typescript/module/src/navigation/index.d.ts",
+        "require": "./lib/typescript/commonjs/src/navigation/index.d.ts"
+      },
       "react-native": "./src/navigation/index.ts",
       "import": {
         "types": "./lib/typescript/module/src/navigation/index.d.ts",
@@ -32,6 +40,10 @@
       }
     },
     "./expo-router": {
+      "types": {
+        "import": "./lib/typescript/module/src/expo-router/index.d.ts",
+        "require": "./lib/typescript/commonjs/src/expo-router/index.d.ts"
+      },
       "react-native": "./src/expo-router/index.ts",
       "import": {
         "types": "./lib/typescript/module/src/expo-router/index.d.ts",
@@ -74,15 +86,16 @@
     "clean": "rimraf lib vendor expo-plugin babel-plugin"
   },
   "peerDependencies": {
-    "@react-native-community/netinfo": ">=11.0.0",
+    "@react-native-community/netinfo": ">=11.0.0 <13.0.0",
     "@react-navigation/native": ">=6.0.0",
     "expo-router": ">=3.0.0",
     "expo-secure-store": ">=13.0.0",
     "react": ">=18.2.0",
-    "react-native": ">=0.74.0",
-    "react-native-safe-area-context": ">=4.0.0",
-    "react-native-view-shot": ">=5.0.0",
-    "react-native-webview": ">=13.8.0"
+    "react-native": ">=0.76.0",
+    "react-native-device-info": ">=11.0.0 <16.0.0",
+    "react-native-safe-area-context": ">=4.0.0 <6.0.0",
+    "react-native-view-shot": "^5.0.0",
+    "react-native-webview": ">=13.8.0 <14.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-community/netinfo": {
@@ -97,12 +110,15 @@
     "expo-secure-store": {
       "optional": true
     },
+    "react-native-device-info": {
+      "optional": true
+    },
     "react-native-safe-area-context": {
       "optional": true
     }
   },
   "dependencies": {
-    "@react-native-async-storage/async-storage": ">=1.23.0",
+    "@react-native-async-storage/async-storage": ">=1.23.0 <3.0.0",
     "@userflow-tech/core": "file:./vendor/core",
     "@userflow-tech/protocol": "file:./vendor/protocol"
   },
@@ -122,6 +138,7 @@
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-builder-bob": "^0.30.0",
+    "react-native-device-info": "15.0.2",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-view-shot": "^5.1.1",
     "react-native-webview": "13.16.1",
@@ -154,6 +171,6 @@
     ]
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   }
 }

package/src/anchors/AnchorRegistry.ts

@@ -8,6 +8,11 @@ export interface AnchorHost {
    * Called when the measured rect is not fully visible (bounded retries per step).
    */
   scrollIntoView?: () => void;
+  /**
+   * Public instance this host was registered from, when known. Element click
+   * conditions use it to match a tap to this anchor.
+   */
+  node?: object | null;
 }
 
 type Listener = () => void;
@@ -52,6 +57,13 @@ export class AnchorRegistry {
     return last;
   }
 
+  /** Every host registered for `id`, in registration order. */
+  getAll(id: string): AnchorHost[] {
+    const set = this.anchors.get(id);
+    if (!set || set.size === 0) return [];
+    return [...set];
+  }
+
   /** True when more than one host is registered for the same id. */
   isAmbiguous(id: string): boolean {
     return (this.anchors.get(id)?.size ?? 0) > 1;

package/src/anchors/elementConditionEvaluator.ts

@@ -1,35 +1,43 @@
-import type { ConditionEvaluator } from '@userflow-tech/core';
-import type { FlowConditionFragment } from '@userflow-tech/protocol';
+import type {
+  ConditionEvaluator,
+  ConditionEvaluatorContext,
+  ConditionReport,
+} from '@userflow-tech/core';
+import { decodeMobileAutoData, type FlowConditionFragment } from '@userflow-tech/protocol';
 
 import { anchorChangeTicker } from './anchorChangeTicker';
-import { resolveAnchorHost } from './resolveAnchorHost';
-import { resolveAutoAnchorHost } from './resolveAutoAnchorHost';
+import { elementTapMonitor } from './elementTapMonitor';
+import { fiberIsUnder, tapPathDisabled } from './elementTargetMatch';
+import {
+  resolveElementTargets,
+  tapMayHitSelector,
+  type ElementTarget,
+} from './resolveElementTargets';
 import { resolveManualAnchorId } from './resolveManualAnchorId';
 
-/** ELEMENT states the mobile SDK can evaluate today. */
-const SUPPORTED_ELEMENT_STATES = new Set(['PRESENT', 'NOT_PRESENT']);
+/** How many hosts to measure before giving up on a crowded duplicate id. */
+const MAX_MEASURED_HOSTS = 8;
+
+/** Same bound tooltip measurement uses. A host that never calls back is unknown. */
+const MEASURE_TIMEOUT_MS = 400;
 
 /**
  * Evaluate ELEMENT client conditions against manual anchors, fiber-resolved
- * `testID` / `nativeID` / `accessibilityLabel` targets, and AUTO (codeless)
- * selectors.
+ * `userflowId` / `testID` / `nativeID` / `accessibilityLabel` targets, and AUTO
+ * (codeless) selectors.
  *
- * Supports PRESENT / NOT_PRESENT for MANUAL selectors (`css` → anchor id) and
- * AUTO selectors (`autoData` → {@link resolveAutoAnchorHost}). AUTO fails
- * closed: `unknown` / `ambiguous` stay `null` so a gated flow never starts
- * just because the auto-anchor registry is empty. Web-interaction states
- * (CLICK, DISABLED, …) still report unknown.
+ * PRESENT / NOT_PRESENT: any uniquely-or-not host on a visible navigator screen
+ * counts (web parity — duplicates are present). A measured 0×0 host counts as
+ * absent. AUTO `unknown` / `ambiguous` stay `null`.
  *
- * "Present" means a unique host on a **visible** navigator screen. MANUAL
- * goes through `resolveAnchorHost`; AUTO through `resolveAutoAnchorHost`.
- * Both skip screens covered by another navigator screen, so an id on a
- * pushed-under screen counts as absent. Pixel visibility (off-screen inside a
- * ScrollView, opacity 0, etc.) would need async `measureInWindow` and is out
- * of scope.
+ * CLICK / NOT_CLICK: latch from the first matching tap, including a tap on a
+ * descendant. The latch survives re-attach via `previousIsTrue` and is cleared
+ * when the server untracks. Disabled hosts are ignored. Until it latches, an
+ * AUTO selector that does not resolve reports `null`, like presence.
  *
- * Note: compares string literals rather than importing protocol enums so Jest
- * (which cannot resolve the ESM-only `@userflow-tech/protocol` package) stays
- * hermetic. Wire values match `FlowConditionElementState` / `FlowSelectorType`.
+ * Element states are compared as string literals rather than protocol enums so
+ * the wire values stay obvious next to the branches. They match
+ * `FlowConditionElementState`.
  */
 export function createElementConditionEvaluator(
   warn: (message: string) => void = (message) => {
@@ -47,75 +55,232 @@ export function createElementConditionEvaluator(
     warn(message);
   };
 
-  return (condition, report) => {
-    const evaluate = (): void => {
-      const result = evaluateElementCondition(condition, warnOnce);
-      report(result);
-    };
+  return (condition, report, context) => {
+    const elementState = condition.elementState as string | null;
+    if (elementState === 'PRESENT' || elementState === 'NOT_PRESENT') {
+      return trackPresence(condition, elementState, report, warnOnce);
+    }
+    if (elementState === 'CLICK' || elementState === 'NOT_CLICK') {
+      return trackClick(condition, elementState, report, context, warnOnce);
+    }
 
-    evaluate();
-    return anchorChangeTicker.subscribe(evaluate);
+    warnOnce(
+      condition.id,
+      `[Userflow] ELEMENT condition ${condition.id} uses unsupported elementState ` +
+        `"${elementState ?? 'null'}" (supported: PRESENT, NOT_PRESENT, CLICK, NOT_CLICK); ` +
+        'leaving unknown',
+    );
+    report(null);
+    return () => {};
   };
 }
 
-function evaluateElementCondition(
+function trackPresence(
   condition: FlowConditionFragment,
+  elementState: 'PRESENT' | 'NOT_PRESENT',
+  report: ConditionReport,
   warnOnce: (conditionId: string, message: string) => void,
-): boolean | null {
-  const elementState = condition.elementState as string | null;
-  if (elementState == null || !SUPPORTED_ELEMENT_STATES.has(elementState)) {
-    warnOnce(
-      condition.id,
-      `[Userflow] ELEMENT condition ${condition.id} uses unsupported elementState ` +
-        `"${elementState ?? 'null'}" (only PRESENT / NOT_PRESENT are supported); ` +
-        'leaving unknown',
+): () => void {
+  // A synchronous result supersedes any older measurement. Only one
+  // measurement runs at a time, and a change during it re-runs once it settles
+  // instead of discarding it, so steady anchor churn cannot hold the condition
+  // at unknown.
+  let generation = 0;
+  let reportedGeneration = 0;
+  let measuring = false;
+  let changedWhileMeasuring = false;
+  let disposed = false;
+
+  const evaluate = (): void => {
+    if (disposed) return;
+    const gen = ++generation;
+    const resolution = resolveElementTargets(condition.selector);
+
+    if (resolution.status === 'unknown') {
+      if (!resolution.silent) warnUnknown(condition, warnOnce);
+      reportedGeneration = gen;
+      report(null);
+      return;
+    }
+    if (resolution.status === 'absent') {
+      reportedGeneration = gen;
+      report(elementState === 'PRESENT' ? false : true);
+      return;
+    }
+    if (measuring) {
+      changedWhileMeasuring = true;
+      return;
+    }
+
+    measuring = true;
+    void measureVisibility(resolution.targets)
+      .catch((): HostVisibility => 'unknown')
+      .then((visibility) => {
+        measuring = false;
+        if (disposed) return;
+        if (gen > reportedGeneration) {
+          reportedGeneration = gen;
+          if (visibility === 'unknown') {
+            report(null);
+          } else {
+            const present = visibility === 'present';
+            report(elementState === 'PRESENT' ? present : !present);
+          }
+        }
+        if (changedWhileMeasuring) {
+          changedWhileMeasuring = false;
+          evaluate();
+        }
+      });
+  };
+
+  evaluate();
+  const unsubscribe = anchorChangeTicker.subscribe(evaluate);
+  return () => {
+    disposed = true;
+    unsubscribe();
+  };
+}
+
+function trackClick(
+  condition: FlowConditionFragment,
+  elementState: 'CLICK' | 'NOT_CLICK',
+  report: ConditionReport,
+  context: ConditionEvaluatorContext | undefined,
+  warnOnce: (conditionId: string, message: string) => void,
+): () => void {
+  if (!clickSelectorUsable(condition)) {
+    warnUnknown(condition, warnOnce);
+    report(null);
+    return () => {};
+  }
+
+  // CLICK starts false and latches true. NOT_CLICK starts true and latches false.
+  const valueWhenOccurred = elementState === 'CLICK';
+  if (context?.previousIsTrue === valueWhenOccurred) {
+    report(valueWhenOccurred);
+    return () => {};
+  }
+
+  let latched = false;
+  let stopWatchingResolution = (): void => {};
+  if ((condition.selector?.type as string | null) === 'AUTO') {
+    // An AUTO selector can stay unresolvable (empty auto-anchor registry, a
+    // tie between look-alikes), and then no tap can latch. Report unknown
+    // until it resolves, as presence does, rather than an unclicked value
+    // nothing could clear.
+    const reportUnclickedOnceResolvable = (): void => {
+      if (latched) return;
+      const resolution = resolveElementTargets(condition.selector);
+      if (resolution.status === 'unknown') {
+        if (!resolution.silent) warnUnknown(condition, warnOnce);
+        report(null);
+        return;
+      }
+      report(!valueWhenOccurred);
+    };
+    reportUnclickedOnceResolvable();
+    stopWatchingResolution = anchorChangeTicker.subscribe(reportUnclickedOnceResolvable);
+  } else {
+    report(!valueWhenOccurred);
+  }
+
+  const subscription = {
+    unsubscribe: (): void => {},
+  };
+  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),
     );
-    return null;
+    if (!matched?.fiber) return;
+    if (tapPathDisabled(tap.targetFiber, matched.fiber)) return;
+
+    latched = true;
+    report(valueWhenOccurred, { immediate: true });
+    subscription.unsubscribe();
+    stopWatchingResolution();
+  });
+
+  return () => {
+    subscription.unsubscribe();
+    stopWatchingResolution();
+  };
+}
+
+function clickSelectorUsable(condition: FlowConditionFragment): boolean {
+  const selector = condition.selector;
+  if (selector == null) return false;
+  if ((selector.type as string | null) === 'AUTO') {
+    // Without a fingerprint the selector can never resolve, so a definite
+    // NOT_CLICK true would start the flow on a target nobody can tap.
+    return decodeMobileAutoData(selector.autoData)?.fingerprint != null;
   }
+  return resolveManualAnchorId(selector.css) != null;
+}
 
+function warnUnknown(
+  condition: FlowConditionFragment,
+  warnOnce: (conditionId: string, message: string) => void,
+): void {
   const selector = condition.selector;
   if (selector == null) {
     warnOnce(
       condition.id,
       `[Userflow] ELEMENT condition ${condition.id} has no selector; leaving unknown`,
     );
-    return null;
+    return;
   }
-
   if ((selector.type as string | null) === 'AUTO') {
-    const resolution = resolveAutoAnchorHost(selector.autoData);
-    if (resolution.status === 'unknown') {
-      warnOnce(
-        condition.id,
-        `[Userflow] ELEMENT condition ${condition.id} uses an AUTO (codeless) selector ` +
-          'that could not be resolved; leaving unknown',
-      );
-      return null;
-    }
-    if (resolution.status === 'ambiguous') {
-      return null;
-    }
-    const present = resolution.status === 'found';
-    return elementState === 'PRESENT' ? present : !present;
-  }
-
-  const anchorId = resolveManualAnchorId(selector.css);
-  if (anchorId == null) {
     warnOnce(
       condition.id,
-      `[Userflow] ELEMENT condition ${condition.id} has no resolvable manual anchor id; ` +
-        'leaving unknown',
+      `[Userflow] ELEMENT condition ${condition.id} uses an AUTO (codeless) selector ` +
+        'that could not be resolved; leaving unknown',
     );
-    return null;
+    return;
   }
+  warnOnce(
+    condition.id,
+    `[Userflow] ELEMENT condition ${condition.id} has no resolvable manual anchor id; ` +
+      'leaving unknown',
+  );
+}
 
-  const resolution = resolveAnchorHost(anchorId);
-  // Ambiguous counts as not present for PRESENT (fail closed) and as "present"
-  // for NOT_PRESENT would be wrong — treat ambiguous as unknown so gated flows
-  // stay blocked rather than inventing a truth value.
-  if (resolution.status === 'ambiguous') {
-    return null;
+type HostVisibility = 'present' | 'absent' | 'unknown';
+
+/** Measures hosts in parallel so duplicates cost one timeout, not one each. */
+async function measureVisibility(targets: ElementTarget[]): Promise<HostVisibility> {
+  const slice = targets.slice(0, MAX_MEASURED_HOSTS);
+  const measured = await Promise.all(slice.map(measureHost));
+  if (measured.some((size) => size !== 'timeout' && size.width > 0 && size.height > 0)) {
+    return 'present';
   }
-  const present = resolution.status === 'found';
-  return elementState === 'PRESENT' ? present : !present;
+  if (measured.includes('timeout') || targets.length > slice.length) return 'unknown';
+  return 'absent';
+}
+
+function measureHost(
+  target: ElementTarget,
+): Promise<{ width: number; height: number } | 'timeout'> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value: { width: number; height: number } | 'timeout'): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish('timeout'), MEASURE_TIMEOUT_MS);
+    try {
+      target.host.measureInWindow((_x, _y, width, height) => {
+        finish({ width, height });
+      });
+    } catch {
+      finish('timeout');
+    }
+  });
 }

package/src/anchors/elementTapMonitor.ts

@@ -0,0 +1,95 @@
+/**
+ * Pass-through tap observation for ELEMENT CLICK / NOT_CLICK conditions.
+ *
+ * Many conditions can subscribe at once. Touch start/end are paired per finger
+ * and a tap is emitted only when movement stays within the same slop the
+ * tooltip target-press monitor uses. The host fiber is the one captured at
+ * touch start, before the press's setState commits a new tree.
+ *
+ * With no subscribers the monitor stores nothing, so the bridge can skip the
+ * fiber lookup entirely.
+ */
+import type { AnyFiber } from './fiber/fiberInternals';
+import { type TouchIdentifier, type TouchPoint, withinTapSlop } from './targetPressMonitor';
+
+export interface ElementTap {
+  targetFiber: AnyFiber;
+}
+
+export type ElementTapListener = (tap: ElementTap) => void;
+
+interface TouchStart extends TouchPoint {
+  targetFiber: AnyFiber | null;
+}
+
+export class ElementTapMonitor {
+  private readonly listeners = new Set<ElementTapListener>();
+  private readonly touchStarts = new Map<TouchIdentifier, TouchStart>();
+
+  get subscriberCount(): number {
+    return this.listeners.size;
+  }
+
+  subscribe(listener: ElementTapListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) {
+        this.touchStarts.clear();
+      }
+    };
+  }
+
+  handleTouchStart(
+    identifier: TouchIdentifier,
+    pageX: number,
+    pageY: number,
+    targetFiber: AnyFiber | null,
+  ): void {
+    if (this.listeners.size === 0) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.set(identifier, { pageX, pageY, targetFiber });
+  }
+
+  /**
+   * Emit a tap when this finger started and ended within slop on a resolved
+   * host. Never claims the responder.
+   */
+  handleTouchEnd(identifier: TouchIdentifier, pageX: number, pageY: number): void {
+    const start = this.touchStarts.get(identifier) ?? null;
+    this.touchStarts.delete(identifier);
+    if (!start || this.listeners.size === 0 || !start.targetFiber) return;
+    if (!withinTapSlop(start, { pageX, pageY })) return;
+
+    const tap: ElementTap = { targetFiber: start.targetFiber };
+    for (const listener of this.listeners) {
+      // One condition's failure must not cost the others this tap, or abort
+      // the bridge's handling of the event's remaining touches.
+      try {
+        listener(tap);
+      } catch {
+        // The condition stays at its current value.
+      }
+    }
+  }
+
+  /** Drop in-progress gesture(s). Omit `identifier` to clear every finger. */
+  cancelTouch(identifier?: TouchIdentifier): void {
+    if (identifier == null) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.delete(identifier);
+  }
+
+  /** Test helper. */
+  resetForTests(): void {
+    this.listeners.clear();
+    this.touchStarts.clear();
+  }
+}
+
+/** Shared singleton used by TargetPressBridge and the element-condition evaluator. */
+export const elementTapMonitor = new ElementTapMonitor();

package/src/anchors/elementTargetMatch.ts

@@ -0,0 +1,90 @@
+/**
+ * Compare a touch-start fiber with a host resolved later, tolerating the
+ * alternate swap a Pressable `pressed` re-render does mid-gesture.
+ */
+import type { ElementTap } from './elementTapMonitor';
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getAlternate,
+  getLiveHostProps,
+  getMemoizedProps,
+  getReturn,
+} from './fiber/fiberInternals';
+import { ANCHOR_PROP_TIERS } from './fiber/findAnchorFiber';
+
+const anchorIdsByTap = new WeakMap<ElementTap, ReadonlySet<string>>();
+
+/**
+ * Anchor ids on the tapped fiber and its ancestors, built once per tap and
+ * shared by every click condition it is delivered to.
+ */
+export function anchorIdsAboveTap(tap: ElementTap): ReadonlySet<string> {
+  const cached = anchorIdsByTap.get(tap);
+  if (cached) return cached;
+
+  const ids = new Set<string>();
+  let current: AnyFiber = tap.targetFiber;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    const props = getMemoizedProps(current);
+    if (props) {
+      for (const tier of ANCHOR_PROP_TIERS) {
+        const value = props[tier];
+        if (typeof value === 'string') ids.add(value);
+      }
+    }
+    current = getReturn(current);
+  }
+  anchorIdsByTap.set(tap, ids);
+  return ids;
+}
+
+export function sameFiber(a: AnyFiber, b: AnyFiber): boolean {
+  if (a == null || b == null) return false;
+  if (a === b) return true;
+  const aAlt = getAlternate(a);
+  const bAlt = getAlternate(b);
+  return a === bAlt || aAlt === b || (aAlt != null && aAlt === bAlt);
+}
+
+/** True when `node` is `host` or a descendant of it. */
+export function fiberIsUnder(node: AnyFiber, host: AnyFiber): boolean {
+  let current: AnyFiber = node;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (sameFiber(current, host)) return true;
+    current = getReturn(current);
+  }
+  return false;
+}
+
+function fiberDisabled(fiber: AnyFiber): boolean {
+  let props: Record<string, unknown> | undefined;
+  try {
+    props = getLiveHostProps(fiber);
+  } catch {
+    return false;
+  }
+  if (!props) return false;
+  if (props.disabled === true) return true;
+  if (props['aria-disabled'] === true) return true;
+  const state = props.accessibilityState;
+  return (
+    typeof state === 'object' &&
+    state !== null &&
+    (state as { disabled?: unknown }).disabled === true
+  );
+}
+
+/**
+ * True when the tapped fiber, the matched host, or a fiber between them is
+ * disabled. Browsers do not fire `click` on a disabled control.
+ */
+export function tapPathDisabled(tapped: AnyFiber, host: AnyFiber): boolean {
+  let current: AnyFiber = tapped;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (fiberDisabled(current)) return true;
+    if (sameFiber(current, host)) return false;
+    current = getReturn(current);
+  }
+  return fiberDisabled(host);
+}