@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/anchors/fiber/fiberPath.ts

@@ -0,0 +1,117 @@
+/**
+ * Capture a release-stable fiber path for a host the Babel plugin never
+ * registered. `hostKind` and ids survive minification; `displayName` is only
+ * a tiebreaker at resolve time.
+ */
+import type { MobileFiberPath, MobileFiberSegment } from '@userflow-tech/protocol';
+
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getHostTypeName,
+  getLiveHostProps,
+  getReturn,
+  getSibling,
+  isHostFiber,
+} from './fiberInternals';
+import { readHostText } from './readHostContent';
+
+const SCREEN_TYPES = new Set(['RNSScreen', 'RNSModalScreen']);
+
+function stringProp(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function displayNameOf(fiber: AnyFiber): string {
+  const type = fiber?.type;
+  if (typeof type === 'string') return type;
+  if (type && typeof type === 'object') {
+    const named = type as { displayName?: unknown; name?: unknown };
+    if (typeof named.displayName === 'string' && named.displayName) return named.displayName;
+    if (typeof named.name === 'string' && named.name) return named.name;
+  }
+  if (typeof type === 'function') {
+    const named = type as { displayName?: string; name?: string };
+    return named.displayName || named.name || 'Component';
+  }
+  return 'Unknown';
+}
+
+function hostSiblingIndex(fiber: AnyFiber): number {
+  const parent = getReturn(fiber);
+  if (!parent) return 0;
+  let index = 0;
+  let child = parent.child as AnyFiber | null;
+  let guard = 0;
+  while (child && guard < 500) {
+    if (child === fiber) return index;
+    if (isHostFiber(child)) index += 1;
+    child = getSibling(child);
+    guard += 1;
+  }
+  return 0;
+}
+
+function segmentFor(fiber: AnyFiber): MobileFiberSegment {
+  const hostKind = getHostTypeName(fiber);
+  const props = getLiveHostProps(fiber);
+  const testID = stringProp(props?.testID);
+  const accessibilityLabel =
+    stringProp(props?.accessibilityLabel) ?? stringProp(props?.['aria-label']);
+  const role = stringProp(props?.accessibilityRole) ?? stringProp(props?.role);
+  const key = stringProp(fiber?.key);
+  let text: string | undefined;
+  try {
+    text = readHostText(fiber, 1);
+  } catch {
+    text = undefined;
+  }
+  return {
+    displayName: displayNameOf(fiber),
+    ...(hostKind ? { hostKind } : {}),
+    ...(role ? { role } : {}),
+    siblingIndex: hostSiblingIndex(fiber),
+    ...(key ? { key } : {}),
+    ...(text ? { text } : {}),
+    ...(testID ? { testID } : {}),
+    ...(accessibilityLabel ? { accessibilityLabel } : {}),
+  };
+}
+
+/**
+ * Root → leaf path from the enclosing screen (or the walk root) down to `host`.
+ */
+export function fiberPathFromHost(host: AnyFiber): MobileFiberPath | null {
+  if (!host || !isHostFiber(host)) return null;
+
+  const hosts: AnyFiber[] = [];
+  let screen: AnyFiber | null = null;
+  let current: AnyFiber | null = host;
+  for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+    if (isHostFiber(current)) hosts.push(current);
+    const type = getHostTypeName(current);
+    if (type && SCREEN_TYPES.has(type)) {
+      screen = current;
+      break;
+    }
+    current = getReturn(current);
+  }
+
+  hosts.reverse();
+  if (hosts.length === 0) return null;
+
+  const leaf = hosts[hosts.length - 1]!;
+  let leafText: string | undefined;
+  try {
+    leafText = readHostText(leaf);
+  } catch {
+    leafText = undefined;
+  }
+  const root = screen ?? hosts[0]!;
+  return {
+    ...(displayNameOf(root) ? { rootDisplayName: displayNameOf(root) } : {}),
+    ...(leafText ? { leafText } : {}),
+    leafKind: getHostTypeName(leaf) ?? 'View',
+    segments: hosts.map(segmentFor),
+  };
+}

package/src/anchors/fiber/findAnchorFiber.ts

@@ -7,7 +7,7 @@ import {
   getSibling,
   isHostFiber,
 } from './fiberInternals';
-import { coveredScreenBranches, isScreenContainerFiber } from './visibleScreens';
+import { walkVisibleFibers } from './walkVisibleFibers';
 
 /**
  * Soft cap so a dense screen cannot stall the JS thread. One modest Expo Router
@@ -34,10 +34,11 @@ export type FindAnchorFiberResult =
  * 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.
+ * A composite match resolves to the host beneath it that carries the same id
+ * (e.g. a tab item that wraps its button in a View and forwards testID to the
+ * button), else to its 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.
@@ -52,27 +53,11 @@ export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFibe
       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) {
+    const { visited, truncated } = walkVisibleFibers(
+      rootFiber,
+      (fiber) => {
+        const props = getMemoizedProps(fiber);
+        if (!props) return;
         if (typeof props.testID === 'string' && props.testID === id) {
           byTier.testID.push(fiber);
         }
@@ -82,25 +67,11 @@ export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFibe
         if (typeof props.accessibilityLabel === 'string' && props.accessibilityLabel === id) {
           byTier.accessibilityLabel.push(fiber);
         }
-      }
+      },
+      MAX_NODES,
+    );
 
-      // 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) {
+    if (truncated || 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);
@@ -143,14 +114,15 @@ export function findAnchorFiber(rootFiber: AnyFiber, id: string): FindAnchorFibe
 }
 
 /**
- * For each matched fiber, resolve the shallowest host descendant (or itself
- * when already a host). Deduplicate by identity / alternate.
+ * Resolve each matched fiber to the host that represents it. Deduplicate by
+ * identity / alternate.
  */
 function uniqueHosts(matches: AnyFiber[]): AnyFiber[] {
+  const forwarded = forwardedHostMatches(matches);
   const seen = new Set<AnyFiber>();
   const out: AnyFiber[] = [];
   for (const match of matches) {
-    const host = nearestHostDescendant(match) ?? (isHostFiber(match) ? match : null);
+    const host = isHostFiber(match) ? match : compositeHost(match, forwarded.get(match));
     if (!host) continue;
     const identity = host.alternate ?? host;
     if (seen.has(host) || seen.has(identity)) continue;
@@ -162,6 +134,44 @@ function uniqueHosts(matches: AnyFiber[]): AnyFiber[] {
   return out;
 }
 
+/**
+ * The host carrying a composite's id when the composite forwards it down one
+ * chain, else the composite's shallowest host. Carriers on disjoint chains keep
+ * the shallowest host, so a component repeating its id on two children still
+ * resolves to the component.
+ */
+function compositeHost(composite: AnyFiber, carriers: AnyFiber[] | undefined): AnyFiber | null {
+  const chains = carriers ? collapseToChains(carriers) : [];
+  if (chains.length === 1) return chains[0]!;
+  return nearestHostDescendant(composite);
+}
+
+/** Host matches grouped under each composite match they descend from. */
+function forwardedHostMatches(matches: AnyFiber[]): Map<AnyFiber, AnyFiber[]> {
+  const composites = new Map<AnyFiber, AnyFiber>();
+  for (const match of matches) {
+    if (isHostFiber(match)) continue;
+    composites.set(match, match);
+    if (match.alternate) composites.set(match.alternate, match);
+  }
+  const out = new Map<AnyFiber, AnyFiber[]>();
+  if (composites.size === 0) return out;
+  for (const host of matches) {
+    if (!isHostFiber(host)) continue;
+    let cur = getReturn(host);
+    for (let depth = 0; cur && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      const composite = composites.get(cur);
+      if (composite) {
+        const carriers = out.get(composite);
+        if (carriers) carriers.push(host);
+        else out.set(composite, [host]);
+      }
+      cur = getReturn(cur);
+    }
+  }
+  return out;
+}
+
 /**
  * BFS under `fiber` for the shallowest host descendant. Returns `fiber` itself
  * when it is already a host.

package/src/anchors/fiber/indexHostFibers.ts

@@ -0,0 +1,136 @@
+/**
+ * Reverse index: public instance / native tag → host fiber.
+ *
+ * Renderers disagree on whether a host ref can reach its fiber at all:
+ *
+ * - Fabric (RN 0.74+) stores the fiber on `__internalInstanceHandle`, and
+ *   older Fabric on `_internalInstanceHandle` — the direct pointer works.
+ * - Paper **release** builds null out `_internalFiberInstanceHandleDEV`, so a
+ *   host ref has no route to its fiber at all.
+ *
+ * The index closes that gap: `FiberScanRoot` is a class component, and
+ * `_reactInternals` is present on class instances in every renderer and build
+ * type, so we can always walk down from there and match on native tag or
+ * instance identity. This is the version-independent path; the direct pointer
+ * is the fast path.
+ */
+
+import { fiberScanRoot } from './FiberScanRootStore';
+import {
+  type AnyFiber,
+  fiberFromPublicInstance,
+  getChild,
+  getSibling,
+  isHostFiber,
+  nativeTagFromHostFiber,
+  nativeTagFromNode,
+  publicInstanceFromHostFiber,
+  resolveCurrentFiber,
+} from './fiberInternals';
+
+/** Same bound as {@link findAnchorFiber} so a dense tree is fully indexed. */
+const MAX_INDEX_NODES = 60_000;
+
+export interface HostFiberIndex {
+  byNativeTag: Map<number, AnyFiber>;
+  byInstance: WeakMap<object, AnyFiber>;
+}
+
+export function emptyHostFiberIndex(): HostFiberIndex {
+  return { byNativeTag: new Map(), byInstance: new WeakMap() };
+}
+
+/**
+ * Walk `root`'s descendants (not `root.sibling`, so the Userflow overlay stays
+ * out of the index). First host fiber per native tag wins.
+ */
+export function createHostFiberIndex(root: AnyFiber | null | undefined): HostFiberIndex {
+  const index = emptyHostFiberIndex();
+  if (!root) return index;
+  try {
+    const stack: AnyFiber[] = [root];
+    let visited = 0;
+    while (stack.length > 0 && visited < MAX_INDEX_NODES) {
+      const fiber = stack.pop();
+      if (!fiber) continue;
+      visited += 1;
+      if (isHostFiber(fiber)) {
+        const tag = nativeTagFromHostFiber(fiber);
+        if (tag !== undefined && !index.byNativeTag.has(tag)) {
+          index.byNativeTag.set(tag, fiber);
+        }
+        const pub = publicInstanceFromHostFiber(fiber);
+        if (pub) {
+          try {
+            index.byInstance.set(pub, fiber);
+          } catch {
+            // WeakMap rejects non-objects; ignore.
+          }
+        }
+      }
+      if (fiber !== root) {
+        const sibling = getSibling(fiber);
+        if (sibling) stack.push(sibling);
+      }
+      const child = getChild(fiber);
+      if (child) stack.push(child);
+    }
+  } catch {
+    // Best-effort — a partial index is still useful.
+  }
+  return index;
+}
+
+export function indexLiveHostFibers(): HostFiberIndex {
+  return createHostFiberIndex(fiberScanRoot.getFiber());
+}
+
+/** An index, or a thunk that builds one on first use. */
+export type HostFiberIndexSource = HostFiberIndex | (() => HostFiberIndex);
+
+/**
+ * Defers the tree walk until something actually misses the direct pointer, and
+ * reuses the result for the rest of the pass. On renderers where refs reach
+ * their fiber (Fabric, Paper DEV) the walk never happens.
+ */
+export function createLazyHostFiberIndex(
+  build: () => HostFiberIndex = indexLiveHostFibers,
+): () => HostFiberIndex {
+  let cached: HostFiberIndex | null = null;
+  return () => {
+    if (!cached) {
+      try {
+        cached = build();
+      } catch {
+        cached = emptyHostFiberIndex();
+      }
+    }
+    return cached;
+  };
+}
+
+/**
+ * Fiber for a public instance: direct pointer first, then the scan-root index
+ * by identity / native tag.
+ */
+export function lookupHostFiber(index: HostFiberIndexSource, instance: unknown): AnyFiber | null {
+  const direct = fiberFromPublicInstance(instance);
+  if (direct) {
+    try {
+      return resolveCurrentFiber(direct);
+    } catch {
+      return direct;
+    }
+  }
+  if (!instance || typeof instance !== 'object') return null;
+  try {
+    const resolved = typeof index === 'function' ? index() : index;
+    const fromMap = resolved.byInstance.get(instance);
+    if (fromMap) return fromMap;
+    const tag = nativeTagFromNode(instance);
+    if (tag !== undefined) return resolved.byNativeTag.get(tag) ?? null;
+  } catch {
+    // Best-effort.
+  }
+  return null;
+}

package/src/anchors/fiber/readHostContent.ts

@@ -0,0 +1,146 @@
+/**
+ * Live host-content reads from a public instance's fiber. Used at AUTO capture
+ * and match time so dynamic `{label}` / `{t(...)}` / `placeholder={…}` show up
+ * as `childText` even though Babel only stamps static literals.
+ *
+ * Same never-throws contract as the rest of the fiber layer.
+ */
+
+import {
+  type AnyFiber,
+  getChild,
+  getFiberTag,
+  getLiveHostProps,
+  getMemoizedProps,
+  getSibling,
+  isHostFiber,
+} from './fiberInternals';
+
+/** React reconciler `HostComponent` / `HostText` fiber tags. */
+const HOST_COMPONENT_TAG = 5;
+const HOST_TEXT_TAG = 6;
+
+/**
+ * Mirrors Babel `childTextFromJsx` depth — but counted in **host** levels, not
+ * fibers. See {@link isHostLevel}.
+ */
+const DEFAULT_MAX_DEPTH = 4;
+
+/** Soft cap so a dense subtree cannot stall the JS thread. */
+const DEFAULT_MAX_NODES = 2_000;
+
+function coerceText(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+}
+
+/**
+ * Concatenate the string/number fragments of a split label, in order.
+ *
+ * `<Text>{count} items</Text>` reaches us as `[3, ' items']`. Keeping only the
+ * first fragment would record `3`, which digit-normalization then collapses to
+ * `#` — agreeing with every other numeric label and costing the fail-closed
+ * guarantee. Joining keeps `3 items`, which normalizes to `# items`. Fragments
+ * are concatenated raw so `['Hello, ', name, '!']` stays `Hello, Dan!`; only
+ * the result is trimmed. Non-text children (nested elements) are skipped.
+ */
+function joinTextFragments(children: unknown[]): string | undefined {
+  let joined = '';
+  for (const child of children) {
+    if (typeof child === 'string') joined += child;
+    else if (typeof child === 'number' && Number.isFinite(child)) joined += String(child);
+  }
+  return coerceText(joined);
+}
+
+function textFromMemoizedProps(fiber: AnyFiber): string | undefined {
+  // A HostText fiber (`tag === 6`) carries the string itself as its props.
+  const fromRaw = coerceText(fiber?.memoizedProps);
+  if (fromRaw) return fromRaw;
+
+  const props = getLiveHostProps(fiber) ?? getMemoizedProps(fiber);
+  if (!props) return undefined;
+
+  const fromChildren = coerceText(props.children);
+  if (fromChildren) return fromChildren;
+
+  if (Array.isArray(props.children)) {
+    const joined = joinTextFragments(props.children);
+    if (joined) return joined;
+  }
+
+  const fromText = coerceText(props.text);
+  if (fromText) return fromText;
+
+  return undefined;
+}
+
+/**
+ * First visible text under `fiber`, bounded by depth and node count. Reads a
+ * string/number `children` prop, the joined fragments of a split label, a
+ * native `text` prop, or the string a HostText fiber holds as its props.
+ */
+export function readHostText(fiber: AnyFiber, maxDepth = DEFAULT_MAX_DEPTH): string | undefined {
+  try {
+    const budget = { remaining: DEFAULT_MAX_NODES };
+    return walkText(fiber, 0, maxDepth, budget);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Only host fibers count toward depth.
+ *
+ * The JSX `<View><Text>{label}</Text></View>` that Babel sees as two levels is
+ * many more fibers at runtime: the composite, its `forwardRef` inner, context
+ * providers, then the native host and its text child. How many wrappers sit in
+ * between is an RN implementation detail that changes between versions, so
+ * counting fibers would make the depth limit mean something different on every
+ * release — and would cut the walk short before reaching the text. Counting
+ * host levels matches what Babel counted, on any RN version. The node budget,
+ * not the depth, is what bounds cost.
+ */
+function isHostLevel(fiber: AnyFiber): boolean {
+  const tag = getFiberTag(fiber);
+  if (tag === HOST_COMPONENT_TAG || tag === HOST_TEXT_TAG) return true;
+  return isHostFiber(fiber);
+}
+
+function walkText(
+  fiber: AnyFiber,
+  depth: number,
+  maxDepth: number,
+  budget: { remaining: number },
+): string | undefined {
+  if (!fiber || depth > maxDepth || budget.remaining <= 0) return undefined;
+  budget.remaining -= 1;
+
+  const own = textFromMemoizedProps(fiber);
+  if (own) return own;
+
+  let child = getChild(fiber);
+  while (child) {
+    const nextDepth = isHostLevel(child) ? depth + 1 : depth;
+    const found = walkText(child, nextDepth, maxDepth, budget);
+    if (found) return found;
+    child = getSibling(child);
+  }
+  return undefined;
+}
+
+/** `placeholder` on this fiber (TextInput). Does not walk descendants. */
+export function readHostPlaceholder(fiber: AnyFiber): string | undefined {
+  try {
+    const props = getLiveHostProps(fiber) ?? getMemoizedProps(fiber);
+    return coerceText(props?.placeholder);
+  } catch {
+    return undefined;
+  }
+}