@userflow-tech/react-native 0.1.1 → 0.2.0

package/src/anchors/fiber/fiberInternals.ts

@@ -59,6 +59,163 @@ export function getMemoizedProps(fiber: AnyFiber): Record<string, unknown> | und
   return p && typeof p === 'object' ? (p as Record<string, unknown>) : undefined;
 }
 
+/**
+ * React fiber `tag` values are a small enum (ClassComponent = 1,
+ * HostComponent = 5, HostText = 6, …). Generous ceiling so a future React tag
+ * is not rejected; note this bound alone proves nothing, because Fabric native
+ * view tags also start small (2, 4, 6, …). The structural and negative checks
+ * below are what actually discriminate.
+ */
+const MAX_REACT_FIBER_TAG = 60;
+
+/** Fields only a fiber carries. */
+const FIBER_STRUCTURAL_KEYS = [
+  'child',
+  'return',
+  'sibling',
+  'stateNode',
+  'memoizedProps',
+  'alternate',
+] as const;
+
+/** Fields that mark a host node / public instance rather than a fiber. */
+function looksLikeHostNode(value: object): boolean {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const v = value as any;
+  return (
+    typeof v.__nativeTag === 'number' ||
+    typeof v._nativeTag === 'number' ||
+    '__viewConfig' in value ||
+    'viewConfig' in value ||
+    ('node' in value && 'canonical' in value)
+  );
+}
+
+/**
+ * True when `value` looks like a JS React fiber, and not a Fabric shadow node,
+ * `stateNode`, or public instance. Never throws.
+ *
+ * Fabric on current RN stores the real fiber on `__internalInstanceHandle`, so
+ * this normally passes on the first try. It exists so a renderer that stores
+ * something else there degrades to the native-tag lookup instead of silently
+ * walking a non-fiber object and reading nothing.
+ */
+export function isReactFiber(value: unknown): value is AnyFiber {
+  if (!value || typeof value !== 'object') return false;
+  try {
+    const tag = (value as { tag?: unknown }).tag;
+    if (typeof tag !== 'number' || !Number.isInteger(tag) || tag < 0 || tag > MAX_REACT_FIBER_TAG) {
+      return false;
+    }
+    if (looksLikeHostNode(value)) return false;
+    return FIBER_STRUCTURAL_KEYS.some((key) => key in value);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * If `value` is a fiber, return it. If it is a host `stateNode` that carries a
+ * fiber (Fabric `{ node, canonical: { internalInstanceHandle } }`, or the older
+ * `canonical._internalInstanceHandle`), unwrap to the fiber.
+ */
+export function coerceToFiber(value: unknown): AnyFiber | null {
+  if (isReactFiber(value)) return value;
+  if (!value || typeof value !== 'object') return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const v = value as any;
+    const candidates = [
+      v.canonical?.internalInstanceHandle,
+      v.canonical?._internalInstanceHandle,
+      v.internalInstanceHandle,
+    ];
+    for (const candidate of candidates) {
+      if (isReactFiber(candidate)) return candidate;
+    }
+  } catch {
+    // Feature-detection must itself never throw.
+  }
+  return null;
+}
+
+/**
+ * Native view tag on a public instance or host `stateNode`, across renderers:
+ *
+ * - `__nativeTag` — Fabric `ReactNativeElement` (RN 0.74+)
+ * - `_nativeTag` — Paper `ReactNativeFiberHostComponent`, older Fabric canonical
+ * - `canonical.nativeTag` / `canonical._nativeTag` — Fabric `stateNode`
+ */
+export function nativeTagFromNode(value: unknown): number | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const v = value as any;
+    const tag =
+      v.__nativeTag ??
+      v._nativeTag ??
+      v.nativeTag ??
+      v.canonical?.nativeTag ??
+      v.canonical?._nativeTag;
+    if (typeof tag === 'number' && Number.isFinite(tag)) return tag;
+  } catch {
+    // Best-effort.
+  }
+  return undefined;
+}
+
+export function nativeTagFromHostFiber(fiber: AnyFiber): number | undefined {
+  return nativeTagFromNode(getStateNode(fiber)) ?? nativeTagFromNode(fiber);
+}
+
+/**
+ * Public host instance for a host fiber, if one exists. Covers, in order:
+ * materialized Fabric `canonical.publicInstance`, the older Fabric
+ * `canonical` host component, and the Paper `stateNode` itself (which *is*
+ * the object an app `ref` receives).
+ */
+export function publicInstanceFromHostFiber(fiber: AnyFiber): object | null {
+  try {
+    const node = getStateNode(fiber);
+    if (!node || typeof node !== 'object') return null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const n = node as any;
+    const pub = n.canonical?.publicInstance;
+    if (pub && typeof pub === 'object') return pub as object;
+    const canonical = n.canonical;
+    if (canonical && typeof canonical === 'object' && nativeTagFromNode(canonical) !== undefined) {
+      return canonical as object;
+    }
+    if (
+      typeof n.measureInWindow === 'function' ||
+      typeof n.measure === 'function' ||
+      nativeTagFromNode(n) !== undefined
+    ) {
+      return n as object;
+    }
+  } catch {
+    // Best-effort.
+  }
+  return null;
+}
+
+/**
+ * Host props for content reads. Prefers `memoizedProps`; Fabric also keeps the
+ * last committed props on `stateNode.canonical.currentProps`.
+ */
+export function getLiveHostProps(fiber: AnyFiber): Record<string, unknown> | undefined {
+  const memo = getMemoizedProps(fiber);
+  if (memo) return memo;
+  try {
+    const node = getStateNode(fiber) as { canonical?: { currentProps?: unknown } } | null;
+    const current = node?.canonical?.currentProps;
+    if (current && typeof current === 'object') return current as Record<string, unknown>;
+  } catch {
+    // Best-effort.
+  }
+  return undefined;
+}
+
 export function getStateNode(fiber: AnyFiber): unknown {
   return fiber?.stateNode ?? null;
 }
@@ -109,16 +266,22 @@ const INSTANCE_FIBER_KEYS = [
   '_internalInstanceHandle', // older Fabric / Paper bridge
 ] as const;
 
-/** Resolve a fiber from a class or host public instance. Returns null when unavailable. */
+/**
+ * Resolve a fiber from a class or host public instance. Returns null when
+ * unavailable, and also when the stored handle is a Fabric shadow node rather
+ * than a JS fiber (callers then look up by native tag under FiberScanRoot).
+ */
 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;
+      const fiber = coerceToFiber(inst[key]);
+      if (fiber) return fiber;
     }
+    const fromCanonical = coerceToFiber(inst.canonical?.internalInstanceHandle);
+    if (fromCanonical) return fromCanonical;
   } catch {
     // Feature-detection must itself never throw.
   }

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;
+  }
+}

package/src/anchors/fiberAnchorCache.ts

@@ -0,0 +1,45 @@
+import type { AnyFiber } from './fiber/fiberInternals';
+
+interface FiberCacheEntry {
+  fiber: AnyFiber;
+  screenKey: string | null;
+}
+
+const fiberCache = new Map<string, FiberCacheEntry>();
+let currentScreenKey: string | null = null;
+
+export function getFiberAnchorScreenKey(): string | null {
+  return currentScreenKey;
+}
+
+/** Invalidate fiber-resolved anchors when the active screen changes. */
+export function notifyAnchorScreenChange(screenKey: string | null): void {
+  if (screenKey === currentScreenKey) return;
+  currentScreenKey = screenKey;
+  fiberCache.clear();
+}
+
+/** Drop the fiber cache (preview restart / tests). */
+export function clearFiberAnchorCache(): void {
+  fiberCache.clear();
+}
+
+export function getCachedFiberAnchor(id: string): FiberCacheEntry | undefined {
+  return fiberCache.get(id);
+}
+
+export function setCachedFiberAnchor(id: string, fiber: AnyFiber): void {
+  fiberCache.set(id, { fiber, screenKey: currentScreenKey });
+}
+
+export function deleteCachedFiberAnchor(id: string): void {
+  fiberCache.delete(id);
+}
+
+/**
+ * Drop a cached fiber entry after a zero-size measure so the next resolve
+ * re-scans (the host may have remounted under a new fiber).
+ */
+export function invalidateFiberAnchor(id: string): void {
+  fiberCache.delete(id);
+}

package/src/anchors/resolveAnchorHost.ts

@@ -5,30 +5,37 @@ import { isFiberMounted } from './fiber/fiberInternals';
 import { findAnchorFiber } from './fiber/findAnchorFiber';
 import { createFiberMeasureInWindow } from './fiber/measureHostFiber';
 import { isFiberOnVisibleScreen } from './fiber/visibleScreens';
+import {
+  clearFiberAnchorCache as clearCache,
+  deleteCachedFiberAnchor,
+  getCachedFiberAnchor,
+  getFiberAnchorScreenKey,
+  invalidateFiberAnchor as dropCachedFiberAnchor,
+  notifyAnchorScreenChange as onAnchorScreenChange,
+  setCachedFiberAnchor,
+} from './fiberAnchorCache';
 
 export type AnchorResolution =
   | { status: 'found'; host: AnchorHost; fiber?: AnyFiber }
   | { status: 'ambiguous' }
   | { status: 'missing' };
 
-interface FiberCacheEntry {
-  fiber: AnyFiber;
-  screenKey: string | null;
-}
-
-const fiberCache = new Map<string, FiberCacheEntry>();
-let currentScreenKey: string | null = null;
-
 /** Invalidate fiber-resolved anchors when the active screen changes. */
 export function notifyAnchorScreenChange(screenKey: string | null): void {
-  if (screenKey === currentScreenKey) return;
-  currentScreenKey = screenKey;
-  fiberCache.clear();
+  onAnchorScreenChange(screenKey);
 }
 
 /** Test helper — drop the fiber cache. */
 export function clearFiberAnchorCache(): void {
-  fiberCache.clear();
+  clearCache();
+}
+
+/**
+ * Drop a cached fiber entry after a zero-size measure so the next resolve
+ * re-scans (the host may have remounted under a new fiber).
+ */
+export function invalidateFiberAnchor(id: string): void {
+  dropCachedFiberAnchor(id);
 }
 
 /**
@@ -55,7 +62,8 @@ export function resolveAnchorHost(id: string): AnchorResolution {
 
   // Cached fiber still mounted, on the same screen, and not covered by a screen
   // pushed on top since it was cached?
-  const cached = fiberCache.get(id);
+  const cached = getCachedFiberAnchor(id);
+  const currentScreenKey = getFiberAnchorScreenKey();
   if (
     cached &&
     cached.screenKey === currentScreenKey &&
@@ -69,7 +77,7 @@ export function resolveAnchorHost(id: string): AnchorResolution {
     };
   }
   if (cached) {
-    fiberCache.delete(id);
+    deleteCachedFiberAnchor(id);
   }
 
   const root = fiberScanRoot.getFiber();
@@ -85,18 +93,10 @@ export function resolveAnchorHost(id: string): AnchorResolution {
     return { status: 'missing' };
   }
 
-  fiberCache.set(id, { fiber: result.fiber, screenKey: currentScreenKey });
+  setCachedFiberAnchor(id, result.fiber);
   return {
     status: 'found',
     host: { measureInWindow: createFiberMeasureInWindow(result.fiber) },
     fiber: result.fiber,
   };
 }
-
-/**
- * Drop a cached fiber entry after a zero-size measure so the next resolve
- * re-scans (the host may have remounted under a new fiber).
- */
-export function invalidateFiberAnchor(id: string): void {
-  fiberCache.delete(id);
-}