@userflow-tech/react-native 0.1.0

package/src/anchors/fiber/fiberInternals.ts

@@ -0,0 +1,181 @@
+/**
+ * Compatibility layer for the React Native / React **internals** that
+ * testID-based anchoring depends on. Every accessor is feature-detected and
+ * **never throws** (returns `undefined`/`false`/`null` on a missing or renamed
+ * field) so an RN shape change degrades to not-found rather than crashing the
+ * host app.
+ *
+ * Explicitly **no** `__REACT_DEVTOOLS_GLOBAL_HOOK__`. Fibers are reached only
+ * through production-present pointers on class instances (`_reactInternals`).
+ */
+
+// The fiber shape we touch is intentionally permissive; we never mutate.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFiber = any;
+
+/** React reconciler `HostComponent` fiber tag. */
+const HOST_COMPONENT_TAG = 5;
+
+/** React reconciler `HostRoot` fiber tag. */
+const HOST_ROOT_TAG = 3;
+
+/**
+ * Bound for `return`-pointer walks. Only a loop guard, not a real limit:
+ * measured fiber depth in a modest Expo Router app is already ~150 from a
+ * tagged view to the provider, and ~80 from the provider to the HostRoot, so a
+ * small cap silently disables the walk instead of protecting anything.
+ */
+export const MAX_ANCESTOR_WALK = 10_000;
+
+/** Keys/methods that mark a `stateNode` as a measurable native view instance. */
+const HOST_STATE_NODE_KEYS = [
+  'viewConfig',
+  '_nativeTag',
+  '__nativeTag',
+  'nativeTag',
+  '_internalInstanceHandle',
+  'node',
+  'canonical',
+] as const;
+
+export function getChild(fiber: AnyFiber): AnyFiber | null {
+  return fiber?.child ?? null;
+}
+
+export function getSibling(fiber: AnyFiber): AnyFiber | null {
+  return fiber?.sibling ?? null;
+}
+
+export function getReturn(fiber: AnyFiber): AnyFiber | null {
+  return fiber?.return ?? null;
+}
+
+export function getAlternate(fiber: AnyFiber): AnyFiber | null {
+  return fiber?.alternate ?? null;
+}
+
+export function getMemoizedProps(fiber: AnyFiber): Record<string, unknown> | undefined {
+  const p = fiber?.memoizedProps;
+  return p && typeof p === 'object' ? (p as Record<string, unknown>) : undefined;
+}
+
+export function getStateNode(fiber: AnyFiber): unknown {
+  return fiber?.stateNode ?? null;
+}
+
+export function getFiberTag(fiber: AnyFiber): number | undefined {
+  const t = fiber?.tag;
+  return typeof t === 'number' ? t : undefined;
+}
+
+/** Native component name for a host fiber (e.g. `RNSScreen`), else undefined. */
+export function getHostTypeName(fiber: AnyFiber): string | undefined {
+  const t = fiber?.type;
+  return typeof t === 'string' ? t : undefined;
+}
+
+/**
+ * True when `fiber` is a host component. Checks both Paper/Fabric stateNode
+ * markers and the HostComponent tag (react-test-renderer host fibers often
+ * have `tag === 5` without native keys).
+ */
+export function isHostFiber(fiber: AnyFiber): boolean {
+  const node = fiber?.stateNode;
+  if (node && typeof node === 'object') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const n = node as any;
+    for (const k of HOST_STATE_NODE_KEYS) {
+      if (k in node) return true;
+    }
+    if (
+      typeof n.measure === 'function' ||
+      typeof n.measureInWindow === 'function' ||
+      typeof n.measureLayout === 'function'
+    ) {
+      return true;
+    }
+  }
+  return getFiberTag(fiber) === HOST_COMPONENT_TAG;
+}
+
+/**
+ * Ordered pointer names a class / public instance uses to reference its fiber.
+ * `_internalFiberInstanceHandleDEV` is intentionally omitted — DEV-only.
+ */
+const INSTANCE_FIBER_KEYS = [
+  '_reactInternals', // class / pre-19 / Fabric & Paper prod
+  '_reactInternalFiber', // legacy
+  '__internalInstanceHandle', // Fabric public instance (RN 0.7x+)
+  '_internalInstanceHandle', // older Fabric / Paper bridge
+] as const;
+
+/** Resolve a fiber from a class or host public instance. Returns null when unavailable. */
+export function fiberFromPublicInstance(instance: unknown): AnyFiber | null {
+  if (!instance || typeof instance !== 'object') return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const inst = instance as any;
+    for (const key of INSTANCE_FIBER_KEYS) {
+      const handle = inst[key];
+      if (handle) return handle;
+    }
+  } catch {
+    // Feature-detection must itself never throw.
+  }
+  return null;
+}
+
+/**
+ * Pick the "current" tree fiber between `fiber` and its alternate by walking
+ * to the HostRoot and comparing against `root.stateNode.current`.
+ *
+ * Returns the input fiber when the root cannot be resolved (best-effort).
+ */
+export function resolveCurrentFiber(fiber: AnyFiber): AnyFiber {
+  if (!fiber) return fiber;
+  try {
+    const alternate = getAlternate(fiber);
+    if (!alternate) return fiber;
+
+    let cur: AnyFiber = fiber;
+    for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      if (getFiberTag(cur) === HOST_ROOT_TAG) {
+        const rootState = getStateNode(cur) as { current?: AnyFiber } | null;
+        const currentRoot = rootState?.current;
+        if (!currentRoot) return fiber;
+        // Walk both candidates upward; whichever lands on currentRoot is live.
+        if (isInTree(fiber, currentRoot)) return fiber;
+        if (isInTree(alternate, currentRoot)) return alternate;
+        return fiber;
+      }
+      cur = getReturn(cur);
+    }
+  } catch {
+    // Best-effort.
+  }
+  return fiber;
+}
+
+function isInTree(fiber: AnyFiber, root: AnyFiber): boolean {
+  let cur: AnyFiber = fiber;
+  for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (cur === root) return true;
+    cur = getReturn(cur);
+  }
+  return false;
+}
+
+/**
+ * True when a previously-resolved fiber is still attached to a live tree
+ * (has a return path, or is itself a HostRoot).
+ */
+export function isFiberMounted(fiber: AnyFiber): boolean {
+  if (!fiber) return false;
+  try {
+    if (getFiberTag(fiber) === HOST_ROOT_TAG) return true;
+    // A fiber with no return is detached (unless HostRoot, handled above).
+    return getReturn(fiber) != null;
+  } catch {
+    return false;
+  }
+}

package/src/anchors/fiber/findAnchorFiber.ts

@@ -0,0 +1,225 @@
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getChild,
+  getMemoizedProps,
+  getReturn,
+  getSibling,
+  isHostFiber,
+} from './fiberInternals';
+import { coveredScreenBranches, isScreenContainerFiber } from './visibleScreens';
+
+/**
+ * Soft cap so a dense screen cannot stall the JS thread. One modest Expo Router
+ * screen measures ~2,700 fibers, and a navigation stack keeps earlier screens
+ * mounted, so this has to allow for several screens at once.
+ */
+const MAX_NODES = 60_000;
+
+/** One production warning per process — truncation must not look like "missing". */
+let maxNodesWarned = false;
+
+export type AnchorPropTier = 'testID' | 'nativeID' | 'accessibilityLabel';
+
+const TIER_ORDER: AnchorPropTier[] = ['testID', 'nativeID', 'accessibilityLabel'];
+
+export type FindAnchorFiberResult =
+  | { status: 'found'; fiber: AnyFiber; tier: AnchorPropTier }
+  | { status: 'ambiguous'; tier: AnchorPropTier }
+  | { status: 'missing' };
+
+/**
+ * Bounded DFS under `rootFiber` looking for fibers whose memoizedProps match
+ * `id` on testID, then nativeID, then accessibilityLabel. Uses the highest
+ * tier that has any match so a testID hit is never made ambiguous by an
+ * unrelated accessibilityLabel.
+ *
+ * Composite matches descend to the shallowest host descendant. Multiple
+ * matches on a single root-to-leaf chain (e.g. Pressable forwarding testID to
+ * its inner View) collapse to the outermost host. Disjoint matches fail closed
+ * as ambiguous.
+ *
+ * The walk never follows `rootFiber.sibling` so the Userflow overlay (a sibling
+ * of {@link FiberScanRoot} in UserflowProvider) cannot self-match SDK testIDs.
+ */
+export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFiberResult {
+  if (!rootFiber || !id) return { status: 'missing' };
+
+  try {
+    const byTier: Record<AnchorPropTier, AnyFiber[]> = {
+      testID: [],
+      nativeID: [],
+      accessibilityLabel: [],
+    };
+
+    const stack: AnyFiber[] = [rootFiber];
+    // Branches belonging to screens the user cannot see. Their siblings are
+    // still walked, so only the covered subtree is skipped.
+    const covered = new Set<AnyFiber>();
+    let visited = 0;
+    while (stack.length > 0 && visited < MAX_NODES) {
+      const fiber = stack.pop();
+      if (!fiber) continue;
+      visited += 1;
+
+      if (covered.has(fiber)) {
+        // Keep following the chain, but do not match or descend here.
+        if (fiber !== rootFiber) {
+          const sibling = getSibling(fiber);
+          if (sibling) stack.push(sibling);
+        }
+        continue;
+      }
+
+      const props = getMemoizedProps(fiber);
+      if (props) {
+        if (typeof props.testID === 'string' && props.testID === id) {
+          byTier.testID.push(fiber);
+        }
+        if (typeof props.nativeID === 'string' && props.nativeID === id) {
+          byTier.nativeID.push(fiber);
+        }
+        if (typeof props.accessibilityLabel === 'string' && props.accessibilityLabel === id) {
+          byTier.accessibilityLabel.push(fiber);
+        }
+      }
+
+      // Descend into children. Do NOT follow the seed root's sibling — in
+      // UserflowProvider the overlay (with SDK testIDs) is a sibling of
+      // FiberScanRoot and must stay outside the scan.
+      if (fiber !== rootFiber) {
+        const sibling = getSibling(fiber);
+        if (sibling) stack.push(sibling);
+      }
+      if (isScreenContainerFiber(fiber)) {
+        for (const branch of coveredScreenBranches(fiber)) {
+          covered.add(branch);
+        }
+      }
+      const child = getChild(fiber);
+      if (child) stack.push(child);
+    }
+
+    if (visited >= MAX_NODES) {
+      // Truncation would otherwise look exactly like "the anchor isn't there".
+      // eslint-disable-next-line no-console -- actionable: the anchor may exist but was not reached
+      const warn = (message: string): void => console.warn(message);
+      if (__DEV__) {
+        warn(
+          `[Userflow] Anchor scan for "${id}" stopped after ${MAX_NODES} nodes. ` +
+            `The element may exist but was not reached. Register it explicitly with ` +
+            `useUserflowAnchor("${id}") to skip the scan.`,
+        );
+      } else if (!maxNodesWarned) {
+        maxNodesWarned = true;
+        warn(
+          `[Userflow] Anchor scan stopped after ${MAX_NODES} nodes; some anchors may ` +
+            `be missed. Prefer useUserflowAnchor for deep or dense trees.`,
+        );
+      }
+    }
+
+    for (const tier of TIER_ORDER) {
+      const matches = byTier[tier];
+      if (matches.length === 0) continue;
+
+      const hosts = uniqueHosts(matches);
+      if (hosts.length === 0) continue;
+      if (hosts.length === 1) {
+        return { status: 'found', fiber: hosts[0]!, tier };
+      }
+
+      const collapsed = collapseToChains(hosts);
+      if (collapsed.length === 1) {
+        return { status: 'found', fiber: collapsed[0]!, tier };
+      }
+      return { status: 'ambiguous', tier };
+    }
+
+    return { status: 'missing' };
+  } catch {
+    return { status: 'missing' };
+  }
+}
+
+/**
+ * For each matched fiber, resolve the shallowest host descendant (or itself
+ * when already a host). Deduplicate by identity / alternate.
+ */
+function uniqueHosts(matches: AnyFiber[]): AnyFiber[] {
+  const seen = new Set<AnyFiber>();
+  const out: AnyFiber[] = [];
+  for (const match of matches) {
+    const host = nearestHostDescendant(match) ?? (isHostFiber(match) ? match : null);
+    if (!host) continue;
+    const identity = host.alternate ?? host;
+    if (seen.has(host) || seen.has(identity)) continue;
+    seen.add(host);
+    seen.add(identity);
+    if (host.alternate) seen.add(host.alternate);
+    out.push(host);
+  }
+  return out;
+}
+
+/**
+ * BFS under `fiber` for the shallowest host descendant. Returns `fiber` itself
+ * when it is already a host.
+ */
+export function nearestHostDescendant(fiber: AnyFiber, maxNodes = 2_000): AnyFiber | null {
+  if (!fiber) return null;
+  if (isHostFiber(fiber)) return fiber;
+
+  const queue: AnyFiber[] = [fiber];
+  let visited = 0;
+  while (queue.length > 0 && visited < maxNodes) {
+    const f = queue.shift();
+    if (!f) continue;
+    visited += 1;
+    if (f !== fiber && isHostFiber(f)) return f;
+    let child = getChild(f);
+    while (child) {
+      queue.push(child);
+      child = getSibling(child);
+    }
+  }
+  return null;
+}
+
+/**
+ * Collapse hosts that all lie on one ancestor chain into the outermost
+ * (closest to the root). Disjoint subtrees remain as separate entries.
+ */
+function collapseToChains(hosts: AnyFiber[]): AnyFiber[] {
+  if (hosts.length <= 1) return hosts;
+
+  // Prefer the outermost host when A is an ancestor of B.
+  const survivors: AnyFiber[] = [];
+  for (const candidate of hosts) {
+    let dominated = false;
+    for (let i = survivors.length - 1; i >= 0; i -= 1) {
+      const other = survivors[i]!;
+      if (isAncestorOf(other, candidate)) {
+        // other is outer — drop candidate
+        dominated = true;
+        break;
+      }
+      if (isAncestorOf(candidate, other)) {
+        // candidate is outer — replace other
+        survivors.splice(i, 1);
+      }
+    }
+    if (!dominated) survivors.push(candidate);
+  }
+  return survivors;
+}
+
+function isAncestorOf(ancestor: AnyFiber, descendant: AnyFiber): boolean {
+  let cur: AnyFiber = descendant;
+  for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (cur === ancestor) return true;
+    if (ancestor.alternate && cur === ancestor.alternate) return true;
+    cur = getReturn(cur);
+  }
+  return false;
+}

package/src/anchors/fiber/findScrollAncestors.ts

@@ -0,0 +1,229 @@
+/**
+ * Walk the fiber `return` chain from an anchor host upward and collect
+ * scrollable ancestors (innermost first). Used to scroll tooltip targets into
+ * view without requiring the host app to register ScrollViews.
+ *
+ * Detection is duck-typed on `stateNode` (ScrollView → `scrollTo`,
+ * FlatList/VirtualizedList → `scrollToOffset`, SectionList → `scrollToLocation`)
+ * so an RN rename degrades to "no scroll ancestor" rather than crashing.
+ */
+
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getChild,
+  getHostTypeName,
+  getMemoizedProps,
+  getReturn,
+  getSibling,
+  getStateNode,
+  isHostFiber,
+} from './fiberInternals';
+import { nearestHostDescendant } from './findAnchorFiber';
+
+const SCROLL_METHODS = ['scrollTo', 'scrollToOffset', 'scrollToLocation'] as const;
+
+/** Native host types that own the scroll viewport. */
+const SCROLL_HOST_TYPES = new Set(['RCTScrollView', 'AndroidHorizontalScrollView']);
+
+/** Native host type for the scroll content (moves with contentOffset). */
+const SCROLL_CONTENT_TYPES = new Set([
+  'RCTScrollContentView',
+  'AndroidHorizontalScrollContentView',
+]);
+
+export interface ScrollAncestor {
+  /** Class / composite instance that exposes scrollTo / scrollToOffset / … */
+  instance: ScrollableInstance;
+  /** Host fiber for the scroll viewport (RCTScrollView), when resolvable. */
+  containerFiber: AnyFiber | null;
+  /** Host fiber for the content view that translates with scroll, when resolvable. */
+  contentFiber: AnyFiber | null;
+  /** True when the scroller scrolls on the horizontal axis. */
+  horizontal: boolean;
+}
+
+export type ScrollableInstance = {
+  scrollTo?: (options: { x?: number; y?: number; animated?: boolean }) => void;
+  scrollToOffset?: (options: { offset: number; animated?: boolean }) => void;
+  scrollToLocation?: (options: {
+    sectionIndex: number;
+    itemIndex: number;
+    animated?: boolean;
+    viewOffset?: number;
+  }) => void;
+  getNativeScrollRef?: () => unknown;
+  getInnerViewRef?: () => unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _listRef?: any;
+};
+
+/**
+ * Collect scrollable ancestors of `fiber`, innermost first.
+ * Never throws — missing / renamed internals simply yield an empty list.
+ */
+export function findScrollAncestors(fiber: AnyFiber): ScrollAncestor[] {
+  const out: ScrollAncestor[] = [];
+  if (!fiber) return out;
+
+  try {
+    let current: AnyFiber = fiber;
+    for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      const instance = asScrollableInstance(getStateNode(current));
+      if (instance) {
+        const { containerFiber, contentFiber } = resolveScrollGeometry(current, instance);
+        out.push({
+          instance,
+          containerFiber,
+          contentFiber,
+          horizontal: isHorizontal(instance, current),
+        });
+      }
+      current = getReturn(current);
+    }
+  } catch {
+    // Feature-detection must itself never throw.
+  }
+
+  return out;
+}
+
+function asScrollableInstance(node: unknown): ScrollableInstance | null {
+  if (!node || typeof node !== 'object') return null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const n = node as any;
+  for (const method of SCROLL_METHODS) {
+    if (typeof n[method] === 'function') {
+      return n as ScrollableInstance;
+    }
+  }
+  // FlatList/SectionList often expose the list via `_listRef`.
+  if (n._listRef && typeof n._listRef === 'object') {
+    return asScrollableInstance(n._listRef);
+  }
+  return null;
+}
+
+function isHorizontal(instance: ScrollableInstance, fiber: AnyFiber): boolean {
+  try {
+    if (instance.props && typeof instance.props.horizontal === 'boolean') {
+      return instance.props.horizontal;
+    }
+    const props = getMemoizedProps(fiber);
+    if (props && typeof props.horizontal === 'boolean') {
+      return props.horizontal;
+    }
+  } catch {
+    // Best-effort.
+  }
+  return false;
+}
+
+/**
+ * Resolve the viewport host + content host for offset-from-measure.
+ *
+ * Prefers imperative refs on the ScrollView instance when present; otherwise
+ * walks descendants looking for RCTScrollView / RCTScrollContentView.
+ */
+function resolveScrollGeometry(
+  scrollFiber: AnyFiber,
+  instance: ScrollableInstance,
+): { containerFiber: AnyFiber | null; contentFiber: AnyFiber | null } {
+  // Prefer live refs when the instance is a ScrollView (bind `this`).
+  const nativeRef = safeCall(instance, instance.getNativeScrollRef);
+  const innerRef = safeCall(instance, instance.getInnerViewRef);
+
+  let containerFiber =
+    fiberFromMaybeInstance(nativeRef) ?? findDescendantByHostType(scrollFiber, SCROLL_HOST_TYPES);
+  let contentFiber =
+    fiberFromMaybeInstance(innerRef) ??
+    (containerFiber
+      ? findDescendantByHostType(containerFiber, SCROLL_CONTENT_TYPES)
+      : findDescendantByHostType(scrollFiber, SCROLL_CONTENT_TYPES));
+
+  // Fall back: nearest host under the scroll composite = viewport; its first
+  // host child is typically the content wrapper.
+  if (!containerFiber) {
+    containerFiber = nearestHostDescendant(scrollFiber);
+  }
+  if (!contentFiber && containerFiber) {
+    contentFiber = firstHostChild(containerFiber);
+  }
+
+  return { containerFiber, contentFiber };
+}
+
+function fiberFromMaybeInstance(instance: unknown): AnyFiber | null {
+  if (!instance || typeof instance === 'number') return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const inst = instance as any;
+    const handle =
+      inst._reactInternals ??
+      inst._reactInternalFiber ??
+      inst.__internalInstanceHandle ??
+      inst._internalInstanceHandle;
+    if (handle) return handle;
+    // Fabric public instance may itself be a host stateNode with a fiber link.
+    if (isHostFiber({ stateNode: instance, tag: 5 })) {
+      // No fiber pointer — caller will measure via stateNode directly if needed.
+      return null;
+    }
+  } catch {
+    // Best-effort.
+  }
+  return null;
+}
+
+function findDescendantByHostType(
+  fiber: AnyFiber,
+  types: Set<string>,
+  maxNodes = 2_000,
+): AnyFiber | null {
+  if (!fiber) return null;
+  const queue: AnyFiber[] = [fiber];
+  let visited = 0;
+  while (queue.length > 0 && visited < maxNodes) {
+    const f = queue.shift();
+    if (!f) continue;
+    visited += 1;
+    if (f !== fiber && isHostFiber(f)) {
+      const name = getHostTypeName(f);
+      if (name && types.has(name)) return f;
+    }
+    let child = getChild(f);
+    while (child) {
+      queue.push(child);
+      child = getSibling(child);
+    }
+  }
+  return null;
+}
+
+function firstHostChild(fiber: AnyFiber): AnyFiber | null {
+  let child = getChild(fiber);
+  let guard = 0;
+  while (child && guard < 200) {
+    if (isHostFiber(child)) return child;
+    // Prefer descending into the first child before siblings.
+    const grandchild = getChild(child);
+    if (grandchild) {
+      child = grandchild;
+    } else {
+      child = getSibling(child);
+    }
+    guard += 1;
+  }
+  return null;
+}
+
+function safeCall(self: ScrollableInstance, fn: (() => unknown) | undefined): unknown {
+  if (typeof fn !== 'function') return null;
+  try {
+    return fn.call(self);
+  } catch {
+    return null;
+  }
+}