@userflow-tech/react-native 0.1.0

package/src/anchors/fiber/measureHostFiber.ts

@@ -0,0 +1,85 @@
+import { UIManager } from 'react-native';
+
+import type { AnyFiber } from './fiberInternals';
+import { getStateNode } from './fiberInternals';
+
+type MeasureInWindowCallback = (x: number, y: number, width: number, height: number) => void;
+
+/**
+ * Feature-detected `measureInWindow` for a host fiber. Tries, in order:
+ *
+ * 1. `stateNode.measureInWindow` — Paper host, or materialized Fabric public instance
+ * 2. `nativeFabricUIManager.measureInWindow(stateNode.node, …)` — Fabric without public instance
+ * 3. `stateNode.canonical.publicInstance.measureInWindow`
+ * 4. `UIManager.measureInWindow(nativeTag, …)` — last resort
+ *
+ * Invokes `callback` with zeros when no measurable path is found (callers treat
+ * zero-size as missing).
+ */
+export function measureHostFiber(fiber: AnyFiber, callback: MeasureInWindowCallback): void {
+  const fail = (): void => {
+    callback(0, 0, 0, 0);
+  };
+
+  if (!fiber) {
+    fail();
+    return;
+  }
+
+  try {
+    const stateNode = getStateNode(fiber);
+    if (!stateNode || typeof stateNode !== 'object') {
+      fail();
+      return;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const node = stateNode as any;
+
+    if (typeof node.measureInWindow === 'function') {
+      node.measureInWindow(callback);
+      return;
+    }
+
+    // Fabric: measure via the shadow node without materializing a public instance.
+    const fabricNode = node.node;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fabricUIManager = (globalThis as any).nativeFabricUIManager;
+    if (
+      fabricNode != null &&
+      fabricUIManager &&
+      typeof fabricUIManager.measureInWindow === 'function'
+    ) {
+      fabricUIManager.measureInWindow(fabricNode, callback);
+      return;
+    }
+
+    const publicInstance = node.canonical?.publicInstance;
+    if (publicInstance && typeof publicInstance.measureInWindow === 'function') {
+      publicInstance.measureInWindow(callback);
+      return;
+    }
+
+    const nativeTag: unknown =
+      node._nativeTag ?? node.__nativeTag ?? node.nativeTag ?? node.canonical?.nativeTag;
+    if (typeof nativeTag === 'number' && Number.isFinite(nativeTag)) {
+      UIManager.measureInWindow(nativeTag, callback);
+      return;
+    }
+  } catch {
+    // Fall through to fail.
+  }
+
+  fail();
+}
+
+/**
+ * Build an `AnchorHost`-compatible `measureInWindow` bound to a host fiber.
+ */
+export function createFiberMeasureInWindow(
+  fiber: AnyFiber,
+): (callback: MeasureInWindowCallback) => void {
+  return (callback) => {
+    measureHostFiber(fiber, callback);
+  };
+}

package/src/anchors/fiber/visibleScreens.ts

@@ -0,0 +1,173 @@
+/**
+ * Restricts anchor scanning to the screens a user can actually see.
+ *
+ * A navigator keeps earlier screens mounted, so without this a tooltip could
+ * anchor to a view on a covered screen — measured on device: with a screen
+ * pushed on top, an anchor on the screen underneath still resolved and measured
+ * to an on-screen rect. Reusing one `testID` across two stacked screens also
+ * degraded to `ambiguous` and failed closed, even though only one was visible.
+ *
+ * Rules, derived from what react-native-screens actually exposes:
+ *
+ * - Native stack (`RNSScreenStack`): every mounted screen reports
+ *   `activityState === 2`, so it is useless as a discriminator. Sibling order
+ *   is what matters — the **last** branch owning a screen is on top.
+ * - Container-style navigators (tabs, non-native stacks) do vary
+ *   `activityState`, so the active branches win. When every branch is active
+ *   (e.g. multi-pane), all stay scannable — we must not fall back to
+ *   last-sibling there, or visible panes get pruned.
+ *
+ * Branches that own no screen at all (tab bars, headers, other global chrome)
+ * are always kept, so anchors outside the screen stack keep resolving.
+ *
+ * Everything is feature-detected: an app without react-native-screens, or a
+ * renamed native component, prunes nothing and behaves as before.
+ */
+import {
+  type AnyFiber,
+  MAX_ANCESTOR_WALK,
+  getAlternate,
+  getChild,
+  getHostTypeName,
+  getMemoizedProps,
+  getReturn,
+  getSibling,
+} from './fiberInternals';
+
+/** Host screen types (push screens and iOS modal presentations). */
+const SCREEN_TYPES = new Set(['RNSScreen', 'RNSModalScreen']);
+
+/** Host components that own a set of sibling screen branches. */
+const SCREEN_CONTAINER_TYPES = new Set([
+  'RNSScreenStack',
+  'RNSScreenContainer',
+  'RNSScreenNavigationContainer',
+]);
+
+/** Native stacks cannot use activityState; last sibling branch is on top. */
+const STACK_CONTAINER_TYPES = new Set(['RNSScreenStack']);
+
+/** `activityState === 2` is react-native-screens' "on screen" value. */
+const ACTIVITY_STATE_ACTIVE = 2;
+
+/** Bound for the per-branch search for the screen it owns. */
+const MAX_BRANCH_NODES = 400;
+
+export function isScreenContainerFiber(fiber: AnyFiber): boolean {
+  const type = getHostTypeName(fiber);
+  return type !== undefined && SCREEN_CONTAINER_TYPES.has(type);
+}
+
+function isScreenFiber(fiber: AnyFiber): boolean {
+  const type = getHostTypeName(fiber);
+  return type !== undefined && SCREEN_TYPES.has(type);
+}
+
+function isStackContainer(fiber: AnyFiber): boolean {
+  const type = getHostTypeName(fiber);
+  return type !== undefined && STACK_CONTAINER_TYPES.has(type);
+}
+
+/** Nearest screen under `branch`, not crossing into a nested container. */
+function ownedScreen(branch: AnyFiber): AnyFiber | null {
+  const stack: AnyFiber[] = [branch];
+  let visited = 0;
+  while (stack.length > 0 && visited < MAX_BRANCH_NODES) {
+    const fiber = stack.pop();
+    if (!fiber) continue;
+    visited += 1;
+    if (isScreenFiber(fiber)) return fiber;
+    // A nested container's screens belong to that container, not this branch.
+    // Still follow siblings so a screen next to a nested navigator is found.
+    if (fiber !== branch && isScreenContainerFiber(fiber)) {
+      const sibling = getSibling(fiber);
+      if (sibling) stack.push(sibling);
+      continue;
+    }
+    const child = getChild(fiber);
+    if (child) stack.push(child);
+    if (fiber !== branch) {
+      const sibling = getSibling(fiber);
+      if (sibling) stack.push(sibling);
+    }
+  }
+  return null;
+}
+
+function isActive(screen: AnyFiber): boolean {
+  return getMemoizedProps(screen)?.activityState === ACTIVITY_STATE_ACTIVE;
+}
+
+/**
+ * Branches of `container` that are covered by another screen and so must not be
+ * scanned. Empty when there is nothing to prune. Alternates are included so a
+ * fiber captured on a previous render still matches.
+ */
+export function coveredScreenBranches(container: AnyFiber): Set<AnyFiber> {
+  const branches: Array<{ branch: AnyFiber; screen: AnyFiber }> = [];
+  let child = getChild(container);
+  let guard = 0;
+  while (child && guard < 200) {
+    const screen = ownedScreen(child);
+    if (screen) branches.push({ branch: child, screen });
+    child = getSibling(child);
+    guard += 1;
+  }
+
+  const covered = new Set<AnyFiber>();
+  if (branches.length <= 1) return covered;
+
+  let visible: Array<{ branch: AnyFiber; screen: AnyFiber }>;
+  if (isStackContainer(container)) {
+    // Native stack: activityState is always 2 for mounted screens; last branch
+    // owns the top of the stack (including an iOS RNSModalScreen presentation).
+    visible = [branches[branches.length - 1]!];
+  } else {
+    const active = branches.filter((entry) => isActive(entry.screen));
+    // Keep every active pane (tabs + multi-visible). If none report active
+    // (transition), fall back to last sibling rather than pruning everything.
+    visible = active.length > 0 ? active : [branches[branches.length - 1]!];
+  }
+
+  for (const entry of branches) {
+    if (visible.includes(entry)) continue;
+    covered.add(entry.branch);
+    const alternate = entry.branch.alternate;
+    if (alternate) covered.add(alternate);
+  }
+  return covered;
+}
+
+/**
+ * Whether `fiber` lives on a screen the user can currently see.
+ *
+ * Needed in addition to scan-time pruning: a resolved anchor is cached, and the
+ * cache would otherwise keep serving a host after its screen was covered by a
+ * newly pushed one. Walks outward so nested navigators are handled.
+ */
+export function isFiberOnVisibleScreen(fiber: AnyFiber): boolean {
+  if (!fiber) return false;
+  try {
+    let previous: AnyFiber | null = null;
+    let current: AnyFiber = fiber;
+    for (let depth = 0; current && depth < MAX_ANCESTOR_WALK; depth += 1) {
+      if (previous) {
+        // A cached fiber's `return` chain can point at the previous render, whose
+        // container still lists the old branches — so consult both alternates.
+        for (const container of [current, getAlternate(current)]) {
+          if (!container || !isScreenContainerFiber(container)) continue;
+          const covered = coveredScreenBranches(container);
+          if (covered.size === 0) continue;
+          if (covered.has(previous)) return false;
+          const previousAlternate = getAlternate(previous);
+          if (previousAlternate && covered.has(previousAlternate)) return false;
+        }
+      }
+      previous = current;
+      current = getReturn(current);
+    }
+  } catch {
+    // Visibility is a refinement; never let it break resolution.
+  }
+  return true;
+}

package/src/anchors/hintsCodec.ts

@@ -0,0 +1,125 @@
+import type { SemanticRole, SemanticSegment } from '@userflow-tech/protocol';
+
+import { roleForKind, type BuildTimeHints } from './AutoAnchorRegistry';
+
+/**
+ * Compact build-time hints wire format (v1) emitted by `@userflow-tech/babel-plugin`.
+ * Expanded once at register time so the auto-anchor registry still sees full paths.
+ */
+export const COMPACT_HINTS_VERSION = 1 as const;
+
+export interface CompactBuildTimeHints {
+  v: typeof COMPACT_HINTS_VERSION;
+  /** nativeId (`uf_<hash>`). */
+  n: string;
+  /** Single template / structural path (was ufid + structuralPath + templatePath). */
+  p: string;
+  ct?: string;
+  cs?: string;
+  icn?: string;
+  img?: string;
+  o?: number;
+  si?: number;
+  tid?: string;
+  uid?: string;
+  lid?: string;
+}
+
+export type HintsInput = BuildTimeHints | CompactBuildTimeHints;
+
+export function isCompactHints(value: unknown): value is CompactBuildTimeHints {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as CompactBuildTimeHints).v === COMPACT_HINTS_VERSION &&
+    typeof (value as CompactBuildTimeHints).n === 'string' &&
+    typeof (value as CompactBuildTimeHints).p === 'string'
+  );
+}
+
+export function isLegacyBuildTimeHints(value: unknown): value is BuildTimeHints {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as BuildTimeHints).ufid === 'string' &&
+    typeof (value as BuildTimeHints).nativeId === 'string' &&
+    (value as CompactBuildTimeHints).v !== COMPACT_HINTS_VERSION
+  );
+}
+
+/** True when the value is either compact v1 or legacy long-key hints. */
+export function isHintsInput(value: unknown): value is HintsInput {
+  return isCompactHints(value) || isLegacyBuildTimeHints(value);
+}
+
+/**
+ * Parse path segments after `module::Component > …` into ancestor descriptors
+ * (everything except the leaf). Matches Babel `formatSegment` output.
+ */
+export function parseAncestorsFromPath(path: string): SemanticSegment[] {
+  const parts = path.split(' > ');
+  if (parts.length <= 1) return [];
+  const ancestorParts = parts.slice(1, -1);
+  const out: SemanticSegment[] = [];
+  for (const part of ancestorParts) {
+    const seg = parsePathSegment(part);
+    if (seg) out.push(seg);
+  }
+  return out;
+}
+
+const SEGMENT_RE = /^([A-Za-z_][\w.]*)(?:\{(userflowId|testID|nativeID|key)=([^}]*)\}|#(\d+))?$/;
+
+export function parsePathSegment(part: string): SemanticSegment | null {
+  const m = SEGMENT_RE.exec(part.trim());
+  if (!m) return null;
+  const kind = m[1]!;
+  const role = roleForKind(kind) as SemanticRole;
+  const idKey = m[2];
+  const idVal = m[3];
+  const ordinalRaw = m[4];
+  const seg: SemanticSegment = { kind, role };
+  if (idKey === 'userflowId' && idVal !== undefined) seg.userflowId = idVal;
+  else if (idKey === 'testID' && idVal !== undefined) seg.testID = idVal;
+  else if (idKey === 'nativeID' && idVal !== undefined) seg.nativeID = idVal;
+  else if (idKey === 'key' && idVal !== undefined) seg.key = idVal;
+  else if (ordinalRaw !== undefined) seg.ordinal = Number(ordinalRaw);
+  return seg;
+}
+
+/**
+ * Expand compact (or legacy) hints into the full `BuildTimeHints` shape used
+ * by AutoAnchorRegistry.
+ */
+export function expandBuildTimeHints(input: HintsInput, kind?: string): BuildTimeHints {
+  if (isLegacyBuildTimeHints(input)) {
+    const role = input.role ?? (kind ? roleForKind(kind) : undefined);
+    return {
+      ...input,
+      structuralPath: input.structuralPath ?? input.ufid,
+      templatePath: input.templatePath ?? input.ufid,
+      ...(role ? { role } : {}),
+      ancestors: input.ancestors ?? parseAncestorsFromPath(input.structuralPath ?? input.ufid),
+    };
+  }
+
+  const path = input.p;
+  const role = kind ? roleForKind(kind) : undefined;
+  return {
+    ufid: path,
+    nativeId: input.n,
+    structuralPath: path,
+    templatePath: path,
+    ...(input.ct !== undefined ? { childText: input.ct } : {}),
+    ...(input.cs !== undefined ? { childShape: input.cs } : {}),
+    ...(input.icn !== undefined ? { iconName: input.icn } : {}),
+    ...(input.img !== undefined ? { imageSrc: input.img } : {}),
+    ...(input.o !== undefined ? { ordinal: input.o } : {}),
+    ...(input.si !== undefined ? { siblingIndex: input.si } : {}),
+    ...(input.tid !== undefined ? { literalTestId: input.tid } : {}),
+    ...(input.uid !== undefined ? { literalUserflowId: input.uid } : {}),
+    ...(input.lid !== undefined ? { literalLabel: input.lid } : {}),
+    ...(role ? { role } : {}),
+    ancestors: parseAncestorsFromPath(path),
+  };
+}

package/src/anchors/resolveAnchorHost.ts

@@ -0,0 +1,102 @@
+import { type AnchorHost, anchorRegistry } from './AnchorRegistry';
+import { fiberScanRoot } from './fiber/FiberScanRoot';
+import type { AnyFiber } from './fiber/fiberInternals';
+import { isFiberMounted } from './fiber/fiberInternals';
+import { findAnchorFiber } from './fiber/findAnchorFiber';
+import { createFiberMeasureInWindow } from './fiber/measureHostFiber';
+import { isFiberOnVisibleScreen } from './fiber/visibleScreens';
+
+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();
+}
+
+/** Test helper — drop the fiber cache. */
+export function clearFiberAnchorCache(): void {
+  fiberCache.clear();
+}
+
+/**
+ * Resolve a MANUAL anchor id to a measurable host.
+ *
+ * Tier 0: {@link anchorRegistry} (`useUserflowAnchor`) — higher priority, fails
+ * closed on ambiguous registry keys.
+ * Tier 1+: fiber scan for `testID`, then `nativeID`, then `accessibilityLabel`.
+ *
+ * Synchronous (the walk is pure JS; only measurement is async via the returned
+ * host). Caches the resolved fiber per id and revalidates cheaply before reuse.
+ */
+export function resolveAnchorHost(id: string): AnchorResolution {
+  if (!id) return { status: 'missing' };
+
+  // Tier 0 — explicit manual anchors win.
+  if (anchorRegistry.isAmbiguous(id)) {
+    return { status: 'ambiguous' };
+  }
+  const registered = anchorRegistry.get(id);
+  if (registered) {
+    return { status: 'found', host: registered };
+  }
+
+  // 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);
+  if (
+    cached &&
+    cached.screenKey === currentScreenKey &&
+    isFiberMounted(cached.fiber) &&
+    isFiberOnVisibleScreen(cached.fiber)
+  ) {
+    return {
+      status: 'found',
+      host: { measureInWindow: createFiberMeasureInWindow(cached.fiber) },
+      fiber: cached.fiber,
+    };
+  }
+  if (cached) {
+    fiberCache.delete(id);
+  }
+
+  const root = fiberScanRoot.getFiber();
+  if (!root) {
+    return { status: 'missing' };
+  }
+
+  const result = findAnchorFiber(root, id);
+  if (result.status === 'ambiguous') {
+    return { status: 'ambiguous' };
+  }
+  if (result.status === 'missing') {
+    return { status: 'missing' };
+  }
+
+  fiberCache.set(id, { fiber: result.fiber, screenKey: currentScreenKey });
+  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);
+}

package/src/anchors/resolveManualAnchorId.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve a manual tooltip target id from `FlowSelectorFragment.css`.
+ * Web MANUAL fixtures use `#save-button`; strip a leading `#`.
+ */
+export function resolveManualAnchorId(css: string | null | undefined): string | null {
+  if (css == null) return null;
+  const trimmed = css.trim();
+  if (!trimmed) return null;
+  return trimmed.startsWith('#') ? trimmed.slice(1) : trimmed;
+}