@userflow-tech/react-native 0.1.0

package/src/anchors/animationFrame.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared requestAnimationFrame hub so multiple surfaces never stack loops.
+ * Mirrors web userflowjs `util/animation-frame.tsx`.
+ */
+
+type Callback = () => void;
+
+const callbacks: Callback[] = [];
+let rafHandle: number | ReturnType<typeof setTimeout> | null = null;
+let active = false;
+
+/**
+ * `callback` runs on every animation frame. Starts the shared loop when the
+ * first subscriber attaches.
+ */
+export function addAnimationFrameCallback(callback: Callback): void {
+  if (callbacks.includes(callback)) return;
+  callbacks.push(callback);
+  if (callbacks.length === 1) {
+    active = true;
+    requestNext();
+  }
+}
+
+/**
+ * Remove a previously added callback. Stops the loop when the last subscriber
+ * detaches.
+ */
+export function removeAnimationFrameCallback(callback: Callback): void {
+  const idx = callbacks.indexOf(callback);
+  if (idx < 0) return;
+  callbacks.splice(idx, 1);
+  if (callbacks.length === 0) {
+    active = false;
+    cancelPending();
+  }
+}
+
+/** Test helper — drop all subscribers and cancel the pending frame. */
+export function resetAnimationFrameForTests(): void {
+  callbacks.length = 0;
+  active = false;
+  cancelPending();
+}
+
+/** Test helper — number of active subscribers. */
+export function animationFrameSubscriberCount(): number {
+  return callbacks.length;
+}
+
+function onAnimationFrame(): void {
+  rafHandle = null;
+  // Snapshot so a callback that unsubscribes mid-frame is safe.
+  const snapshot = callbacks.slice();
+  for (const callback of snapshot) {
+    try {
+      callback();
+    } catch {
+      // A single subscriber must not tear down the hub.
+    }
+  }
+  requestNext();
+}
+
+function requestNext(): void {
+  if (!active) return;
+  const raf =
+    typeof globalThis.requestAnimationFrame === 'function'
+      ? globalThis.requestAnimationFrame.bind(globalThis)
+      : null;
+  if (raf) {
+    rafHandle = raf(onAnimationFrame);
+  } else {
+    // Jest / environments without rAF — fall back to a short timer so tests
+    // and headless runs still drive the loop.
+    rafHandle = setTimeout(onAnimationFrame, 16);
+  }
+}
+
+function cancelPending(): void {
+  if (rafHandle == null) return;
+  if (typeof globalThis.cancelAnimationFrame === 'function' && typeof rafHandle === 'number') {
+    globalThis.cancelAnimationFrame(rafHandle);
+  } else {
+    clearTimeout(rafHandle as ReturnType<typeof setTimeout>);
+  }
+  rafHandle = null;
+}

package/src/anchors/autoAnchor.ts

@@ -0,0 +1,310 @@
+import * as ReactNS from 'react';
+import type { Ref } from 'react';
+
+import {
+  autoAnchorRegistry,
+  roleForKind,
+  type AutoAnchorRef,
+  type BuildTimeHints,
+} from './AutoAnchorRegistry';
+import { expandBuildTimeHints, isHintsInput, type HintsInput } from './hintsCodec';
+
+/**
+ * Runtime half of build-time auto-anchoring (see `@userflow-tech/babel-plugin`).
+ *
+ * Each mount creates a distinct AutoAnchorRegistry instance. Shared templates
+ * (design-system / list rows) register separately and are marked ambiguous
+ * when they lack a unique manual id or call-site scope.
+ *
+ * Canonical signature (what Babel emits via `__ufRef`):
+ *   __userflowAutoAnchor(id, hints, userRef, kind, runtime?)
+ */
+
+type HostInstance = unknown;
+
+type UserRef = Ref<HostInstance> | string | null | undefined;
+
+export interface AutoAnchorRuntime {
+  userflowId?: string;
+  testID?: string;
+  nativeID?: string;
+  childText?: string;
+  accessibilityLabel?: string;
+  iconName?: string;
+  imageSrc?: string;
+  scope?: string;
+  reactKey?: string;
+  manualId?: string;
+}
+
+interface AnchorRegistration {
+  holder: { current: HostInstance };
+  instanceId: string;
+  dispose: () => void;
+  userRefCleanup: (() => void) | null;
+}
+
+interface AnchorEntry {
+  callback: (instance: HostInstance) => void | (() => void);
+  userRef: UserRef;
+  hints: BuildTimeHints | null | undefined;
+  kind: string | undefined;
+  runtime: AutoAnchorRuntime | undefined;
+  registrations: Map<HostInstance, AnchorRegistration>;
+}
+
+function cacheKey(id: string, scope?: string): string {
+  return scope ? `${id}@@${scope}` : id;
+}
+
+const cache = new Map<string, AnchorEntry>();
+
+/**
+ * Legacy string refs (`ref="foo"`) assigned `owner.refs.foo` via React internals.
+ * Best-effort: modern React may not expose an owner; never throws into app code.
+ */
+function assignLegacyStringRef(name: string, instance: HostInstance): void {
+  try {
+    const React = ReactNS as typeof ReactNS & {
+      __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED?: {
+        ReactCurrentOwner?: { current?: { refs?: Record<string, unknown> | null } };
+      };
+      __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE?: {
+        ReactCurrentOwner?: { current?: { refs?: Record<string, unknown> | null } };
+      };
+    };
+    const internals =
+      React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ??
+      React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+    const owner = internals?.ReactCurrentOwner?.current;
+    if (!owner) return;
+    if (owner.refs == null) {
+      owner.refs = {};
+    }
+    if (instance) {
+      owner.refs[name] = instance;
+    } else {
+      delete owner.refs[name];
+    }
+  } catch {
+    // String-ref owner unavailable — ignore rather than break the host.
+  }
+}
+
+function attachUserRef(userRef: UserRef, instance: HostInstance): void | (() => void) {
+  if (userRef == null || userRef === '') return;
+
+  if (typeof userRef === 'string') {
+    assignLegacyStringRef(userRef, instance);
+    return;
+  }
+
+  if (typeof userRef === 'function') {
+    const result = (userRef as (instance: HostInstance) => unknown)(instance);
+    if (typeof result === 'function') {
+      return result as () => void;
+    }
+    return;
+  }
+
+  try {
+    (userRef as { current: HostInstance }).current = instance;
+  } catch {
+    // Read-only ref object — nothing to do.
+  }
+}
+
+function detachUserRef(userRef: UserRef, reg: AnchorRegistration): void {
+  if (reg.userRefCleanup) {
+    try {
+      reg.userRefCleanup();
+    } catch {
+      // App cleanup must not break unmount.
+    }
+    reg.userRefCleanup = null;
+    return;
+  }
+  attachUserRef(userRef, null);
+}
+
+function teardownRegistration(entry: AnchorEntry, reg: AnchorRegistration): void {
+  detachUserRef(entry.userRef, reg);
+  reg.dispose();
+}
+
+function isRefLike(value: unknown): value is Ref<HostInstance> {
+  return (
+    typeof value === 'function' ||
+    (typeof value === 'object' && value !== null && 'current' in value)
+  );
+}
+
+function isUserRef(value: unknown): value is Ref<HostInstance> | string {
+  if (typeof value === 'string') return value.length > 0;
+  return isRefLike(value);
+}
+
+function isRuntime(value: unknown): value is AutoAnchorRuntime {
+  return typeof value === 'object' && value !== null && !isRefLike(value) && !isHintsInput(value);
+}
+
+function resolveHints(
+  raw: HintsInput | null | undefined,
+  kind: string | undefined,
+): BuildTimeHints | null | undefined {
+  if (raw == null) return raw;
+  return expandBuildTimeHints(raw, kind);
+}
+
+export function __userflowAutoAnchor(
+  id: string,
+  hintsOrUserRef?: HintsInput | Ref<HostInstance> | null,
+  userRefOrKind?: UserRef | string,
+  kindOrRuntime?: string | AutoAnchorRuntime,
+  maybeRuntime?: AutoAnchorRuntime,
+): (instance: HostInstance) => void | (() => void) {
+  let hints: BuildTimeHints | null | undefined;
+  let userRef: UserRef;
+  let elementKind: string | undefined;
+  let runtime: AutoAnchorRuntime | undefined;
+
+  if (isHintsInput(hintsOrUserRef)) {
+    userRef = isUserRef(userRefOrKind) ? userRefOrKind : null;
+    if (typeof kindOrRuntime === 'string') {
+      elementKind = kindOrRuntime;
+      runtime = maybeRuntime;
+    } else if (isRuntime(kindOrRuntime)) {
+      runtime = kindOrRuntime;
+    }
+    hints = resolveHints(hintsOrUserRef, elementKind);
+  } else {
+    hints = undefined;
+    userRef = isUserRef(hintsOrUserRef) ? hintsOrUserRef : null;
+    elementKind = typeof userRefOrKind === 'string' ? userRefOrKind : undefined;
+    if (isRuntime(kindOrRuntime)) runtime = kindOrRuntime;
+    else if (maybeRuntime) runtime = maybeRuntime;
+  }
+
+  const resolvedId =
+    typeof id === 'string' && id.length > 0 ? id : (hints?.nativeId ?? hints?.ufid ?? 'uf_unknown');
+
+  const scope = runtime?.scope;
+  const key = cacheKey(resolvedId, scope);
+  const existing = cache.get(key);
+  if (existing) {
+    existing.userRef = userRef;
+    existing.hints = hints;
+    existing.kind = elementKind ?? existing.kind;
+    existing.runtime = runtime ?? existing.runtime;
+    if (existing.registrations.size === 1 && (hints || runtime)) {
+      const [reg] = existing.registrations.values();
+      const patch: Parameters<(typeof autoAnchorRegistry)['updateInstance']>[1] = {};
+      if (runtime?.childText !== undefined) patch.childText = runtime.childText;
+      if (runtime?.accessibilityLabel !== undefined) {
+        patch.accessibilityLabel = runtime.accessibilityLabel;
+      }
+      if (runtime?.scope) patch.instanceScope = runtime.scope;
+      if (runtime?.userflowId) patch.userflowId = runtime.userflowId;
+      if (runtime?.testID) patch.testID = runtime.testID;
+      if (runtime?.nativeID) patch.nativeID = runtime.nativeID;
+      if (runtime?.manualId || runtime?.userflowId || runtime?.testID) {
+        const mid =
+          runtime.manualId ?? runtime.userflowId ?? runtime.testID ?? existing.runtime?.manualId;
+        if (mid) patch.manualId = mid;
+      }
+      autoAnchorRegistry.updateInstance(reg!.instanceId, patch);
+    }
+    return existing.callback;
+  }
+
+  const entry: AnchorEntry = {
+    userRef,
+    hints,
+    kind: elementKind,
+    runtime,
+    registrations: new Map(),
+    callback: (instance: HostInstance) => {
+      if (instance) {
+        if (entry.registrations.has(instance)) return undefined;
+
+        const cleanup = attachUserRef(entry.userRef, instance);
+        const holder: { current: HostInstance } = { current: instance };
+        const kind = entry.kind ?? 'View';
+        const rt = entry.runtime;
+        const composedPath =
+          rt?.scope && entry.hints?.templatePath
+            ? `${rt.scope} :: ${entry.hints.templatePath}`
+            : (entry.hints?.structuralPath ?? entry.hints?.ufid);
+
+        const hintsForReg: BuildTimeHints | undefined = entry.hints
+          ? {
+              ...entry.hints,
+              ...(composedPath ? { structuralPath: composedPath, ufid: composedPath } : {}),
+              role: entry.hints.role ?? roleForKind(kind),
+            }
+          : {
+              ufid: resolvedId,
+              nativeId: resolvedId,
+              role: roleForKind(kind),
+            };
+
+        const { instanceId, dispose } = autoAnchorRegistry.registerInstance({
+          registryKey: resolvedId,
+          ref: holder as AutoAnchorRef,
+          kind,
+          hints: hintsForReg,
+          ...(rt?.scope ? { instanceScope: rt.scope } : {}),
+          runtime: {
+            ...(rt?.manualId ? { manualId: rt.manualId } : {}),
+            ...(rt?.userflowId ? { userflowId: rt.userflowId } : {}),
+            ...(rt?.testID ? { testID: rt.testID } : {}),
+            ...(rt?.nativeID ? { nativeID: rt.nativeID } : {}),
+            ...(rt?.childText ? { childText: rt.childText } : {}),
+            ...(rt?.accessibilityLabel ? { accessibilityLabel: rt.accessibilityLabel } : {}),
+            ...(rt?.iconName ? { iconName: rt.iconName } : {}),
+            ...(rt?.imageSrc ? { imageSrc: rt.imageSrc } : {}),
+            ...(rt?.reactKey ? { reactKey: rt.reactKey } : {}),
+            ...(!rt?.manualId && !rt?.userflowId && !rt?.testID && !resolvedId.startsWith('uf_')
+              ? { manualId: resolvedId }
+              : {}),
+          },
+        });
+
+        const reg: AnchorRegistration = {
+          holder,
+          instanceId,
+          dispose,
+          userRefCleanup: typeof cleanup === 'function' ? cleanup : null,
+        };
+        entry.registrations.set(instance, reg);
+
+        return () => {
+          const r = entry.registrations.get(instance);
+          if (!r) return;
+          entry.registrations.delete(instance);
+          teardownRegistration(entry, r);
+        };
+      }
+
+      const first = entry.registrations.keys().next();
+      if (!first.done) {
+        const inst = first.value;
+        const r = entry.registrations.get(inst)!;
+        entry.registrations.delete(inst);
+        teardownRegistration(entry, r);
+      }
+      return undefined;
+    },
+  };
+  cache.set(key, entry);
+  return entry.callback;
+}
+
+/** Test helper — drop factory cache and registry instances. */
+export function __resetAutoAnchorForTests(): void {
+  cache.clear();
+  autoAnchorRegistry.clear();
+}
+
+(globalThis as { __userflowAutoAnchor?: typeof __userflowAutoAnchor }).__userflowAutoAnchor =
+  __userflowAutoAnchor;

package/src/anchors/elementConditionEvaluator.ts

@@ -0,0 +1,108 @@
+import type { ConditionEvaluator } from '@userflow-tech/core';
+import type { FlowConditionFragment } from '@userflow-tech/protocol';
+
+import { anchorChangeTicker } from './anchorChangeTicker';
+import { resolveAnchorHost } from './resolveAnchorHost';
+import { resolveManualAnchorId } from './resolveManualAnchorId';
+
+/** ELEMENT states the mobile SDK can evaluate today. */
+const SUPPORTED_ELEMENT_STATES = new Set(['PRESENT', 'NOT_PRESENT']);
+
+/**
+ * Evaluate ELEMENT client conditions against manual anchors and fiber-resolved
+ * `testID` / `nativeID` / `accessibilityLabel` targets.
+ *
+ * Supports PRESENT / NOT_PRESENT for MANUAL selectors (`css` → anchor id).
+ * AUTO / codeless selectors and web-interaction states (CLICK, DISABLED, …)
+ * report unknown (`null`) so gated flows stay blocked rather than inventing
+ * a truth value.
+ *
+ * "Present" means `resolveAnchorHost` finds a unique host. That already skips
+ * 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.
+ *
+ * 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`.
+ */
+export function createElementConditionEvaluator(
+  warn: (message: string) => void = (message) => {
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional development diagnostic
+      console.warn(message);
+    }
+  },
+): ConditionEvaluator {
+  const warnedConditionIds = new Set<string>();
+
+  const warnOnce = (conditionId: string, message: string): void => {
+    if (warnedConditionIds.has(conditionId)) return;
+    warnedConditionIds.add(conditionId);
+    warn(message);
+  };
+
+  return (condition, report) => {
+    const evaluate = (): void => {
+      const result = evaluateElementCondition(condition, warnOnce);
+      report(result);
+    };
+
+    evaluate();
+    return anchorChangeTicker.subscribe(evaluate);
+  };
+}
+
+function evaluateElementCondition(
+  condition: FlowConditionFragment,
+  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',
+    );
+    return null;
+  }
+
+  const selector = condition.selector;
+  if (selector == null) {
+    warnOnce(
+      condition.id,
+      `[Userflow] ELEMENT condition ${condition.id} has no selector; leaving unknown`,
+    );
+    return null;
+  }
+
+  if ((selector.type as string | null) === 'AUTO') {
+    warnOnce(
+      condition.id,
+      `[Userflow] ELEMENT condition ${condition.id} uses an AUTO (codeless) selector; ` +
+        'manual anchors only are supported today — leaving unknown',
+    );
+    return null;
+  }
+
+  const anchorId = resolveManualAnchorId(selector.css);
+  if (anchorId == null) {
+    warnOnce(
+      condition.id,
+      `[Userflow] ELEMENT condition ${condition.id} has no resolvable manual anchor id; ` +
+        'leaving unknown',
+    );
+    return null;
+  }
+
+  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;
+  }
+  const present = resolution.status === 'found';
+  return elementState === 'PRESENT' ? present : !present;
+}

package/src/anchors/fiber/FiberScanRoot.tsx

@@ -0,0 +1,98 @@
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { type AnyFiber, fiberFromPublicInstance, resolveCurrentFiber } from './fiberInternals';
+
+type Listener = () => void;
+
+/**
+ * Module singleton holding the fiber under which testID / nativeID /
+ * accessibilityLabel scans run. Seeded by {@link FiberScanRoot}.
+ */
+class FiberScanRootStore {
+  private instance: unknown = null;
+  private readonly listeners = new Set<Listener>();
+
+  set(instance: unknown): void {
+    this.instance = instance;
+    this.emit();
+  }
+
+  clear(): void {
+    this.instance = null;
+    this.emit();
+  }
+
+  /** Current (resolved) fiber under the scan root, or null when unmounted. */
+  getFiber(): AnyFiber | null {
+    if (!this.instance) return null;
+    const fiber = fiberFromPublicInstance(this.instance);
+    if (!fiber) return null;
+    return resolveCurrentFiber(fiber);
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Test helper. */
+  resetForTests(): void {
+    this.instance = null;
+    this.listeners.clear();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+export const fiberScanRoot = new FiberScanRootStore();
+
+export interface FiberScanRootProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Class component that publishes its own `_reactInternals` fiber as the scan
+ * root for testID-based anchoring. Class instances expose `_reactInternals` in
+ * both Paper and Fabric production builds (unlike host refs, which null out
+ * `_internalFiberInstanceHandleDEV` on Paper release).
+ *
+ * Renders the same content-root `View` that {@link UserflowProvider} previously
+ * owned so the layout tree is unchanged. The Userflow overlay sits as a
+ * *sibling*, so SDK-owned `testID`s never self-match.
+ */
+export class FiberScanRoot extends React.Component<FiberScanRootProps> {
+  override componentDidMount(): void {
+    fiberScanRoot.set(this);
+  }
+
+  override componentDidUpdate(): void {
+    // Re-publish after updates so a remount-without-unmount still has a live
+    // pointer (defensive; normally the instance identity is stable).
+    fiberScanRoot.set(this);
+  }
+
+  override componentWillUnmount(): void {
+    fiberScanRoot.clear();
+  }
+
+  override render(): React.ReactElement {
+    return (
+      <View style={styles.contentRoot} collapsable={false}>
+        {this.props.children}
+      </View>
+    );
+  }
+}
+
+const styles = StyleSheet.create({
+  contentRoot: {
+    flex: 1,
+  },
+});