@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/authoring/fingerprintFromInstance.ts

@@ -0,0 +1,318 @@
+import {
+  encodeMobileAutoData,
+  MOBILE_AUTODATA_VERSION,
+  MOBILE_FINGERPRINT_VERSION,
+  type DeviceMetadata,
+  type IdentityStrength,
+  type MobileAutoData,
+  type MobileFingerprint,
+} from '@userflow-tech/protocol';
+import { Dimensions, Platform } from 'react-native';
+
+import { autoAnchorRegistry, type AutoAnchorInstance } from '../anchors/AutoAnchorRegistry';
+import type { AnyFiber } from '../anchors/fiber/fiberInternals';
+import { fiberPathFromHost } from '../anchors/fiber/fiberPath';
+import { fibersMatch, resolveFiberPath } from '../anchors/fiber/resolveFiberPath';
+import { createVisibleInstanceFilter } from '../anchors/isInstanceOnVisibleScreen';
+import * as semanticMatcher from '../anchors/semanticMatcher';
+import type { MatchMissReason } from '../anchors/semanticMatcher';
+import { getCurrentScreenLocation } from '../screenTracker';
+
+import type { PickTarget } from './hitTest';
+
+function deriveIdentityStrength(inst: AutoAnchorInstance): IdentityStrength {
+  const hasId = !!(
+    inst.userflowId ||
+    inst.testID ||
+    inst.manualId ||
+    (inst.nativeID && !inst.nativeID.startsWith('uf_'))
+  );
+  if (hasId) return 'id';
+  if (inst.childText || inst.accessibilityLabel || inst.iconName || inst.imageSrc) {
+    return 'content';
+  }
+  return 'structural';
+}
+
+function screenFromLocation(): { screenId: string; screenName?: string } {
+  const location = getCurrentScreenLocation();
+  if (!location) return { screenId: 'unknown' };
+  if ('path' in location) return { screenId: location.path, screenName: location.path };
+  return { screenId: location.screen, screenName: location.screen };
+}
+
+function deviceMetadata(): DeviceMetadata | undefined {
+  try {
+    const window = Dimensions.get('window');
+    return {
+      screenWidth: window.width,
+      screenHeight: window.height,
+      scale: window.scale,
+      platform: Platform.OS === 'android' ? 'android' : 'ios',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Inverse of `scoreInstance` field-reads: snapshot a live registry instance
+ * into the fingerprint the scored matcher consumes at play time.
+ */
+export function fingerprintFromInstance(inst: AutoAnchorInstance): MobileFingerprint {
+  autoAnchorRegistry.refreshLiveContent([
+    inst,
+    ...autoAnchorRegistry.orderedSiblingsIncludingSelf(inst.instanceId),
+  ]);
+  const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
+  return {
+    version: MOBILE_FINGERPRINT_VERSION,
+    structuralPath: inst.structuralPath,
+    templatePath: inst.templatePath,
+    ...(inst.instanceScope ? { instanceScope: inst.instanceScope } : {}),
+    kind: inst.kind,
+    role: inst.role,
+    ...(inst.manualId ? { manualId: inst.manualId } : {}),
+    ...(inst.userflowId ? { userflowId: inst.userflowId } : {}),
+    ...(inst.testID ? { testID: inst.testID } : {}),
+    ...(inst.nativeID ? { nativeID: inst.nativeID } : {}),
+    ...(inst.childText ? { childText: inst.childText } : {}),
+    ...(inst.accessibilityLabel ? { accessibilityLabel: inst.accessibilityLabel } : {}),
+    ...(inst.childShape ? { childShape: inst.childShape } : {}),
+    ...(inst.iconName ? { iconName: inst.iconName } : {}),
+    ...(inst.imageSrc ? { imageSrc: inst.imageSrc } : {}),
+    ancestors: inst.ancestors ? [...inst.ancestors] : [],
+    previousSiblings: window.previous,
+    nextSiblings: window.next,
+    ...(inst.ordinal !== undefined ? { ordinal: inst.ordinal } : {}),
+    ...(inst.siblingIndex !== undefined ? { siblingIndex: inst.siblingIndex } : {}),
+    isPressable: inst.isPressable,
+    ambiguous: autoAnchorRegistry.isAmbiguousAmong(inst, createVisibleInstanceFilter()),
+    identityStrength: deriveIdentityStrength(inst),
+  };
+}
+
+/** Wrap a live instance in the `FlowSelector.autoData` envelope. */
+export function autoDataFromInstance(inst: AutoAnchorInstance): MobileAutoData {
+  const fingerprint = fingerprintFromInstance(inst);
+  const { screenId, screenName } = screenFromLocation();
+  const device = deviceMetadata();
+  const selector = inst.structuralPath || inst.templatePath || inst.registryKey;
+  return {
+    version: MOBILE_AUTODATA_VERSION,
+    platform: 'react-native',
+    selector,
+    displayName: inst.kind,
+    ...(inst.manualId ? { anchorId: inst.manualId, manualId: inst.manualId } : {}),
+    primary: {
+      ufid: inst.structuralPath || inst.registryKey,
+      ...(inst.nativeID ? { nativeId: inst.nativeID } : {}),
+    },
+    fingerprint,
+    screenId,
+    ...(screenName ? { screenName } : {}),
+    platformData: {
+      ...(inst.testID ? { testID: inst.testID } : {}),
+      ...(inst.accessibilityLabel ? { accessibilityLabel: inst.accessibilityLabel } : {}),
+      ...(inst.childText ? { childText: inst.childText } : {}),
+      ...(inst.childShape ? { childShape: inst.childShape } : {}),
+      ...(inst.structuralPath ? { structuralPath: inst.structuralPath } : {}),
+      ...(inst.templatePath ? { templatePath: inst.templatePath } : {}),
+      ...(inst.instanceScope ? { instanceScope: inst.instanceScope } : {}),
+      isPressable: inst.isPressable,
+    },
+    ...(device ? { device } : {}),
+  };
+}
+
+export function encodeInstanceAutoData(inst: AutoAnchorInstance): string {
+  return encodeMobileAutoData(autoDataFromInstance(inst));
+}
+
+export type PickerFingerprintFailure = {
+  ok: false;
+  reason: MatchMissReason | 'wrong-instance';
+};
+
+export type PickerFingerprintSuccess = {
+  ok: true;
+  autoData: string;
+};
+
+export type PickerFingerprintValidation = PickerFingerprintSuccess | PickerFingerprintFailure;
+
+/**
+ * Encode `inst` and run the play-time matcher over visible screens only — the
+ * same pool as the visible pass in `resolveAutoAnchorHost`. Confirm may proceed
+ * only on a unique hit of this same instance. A copy still mounted on a covered
+ * screen does not count.
+ */
+export function validatePickerFingerprint(inst: AutoAnchorInstance): PickerFingerprintValidation {
+  const autoData = encodeInstanceAutoData(inst);
+  const match = semanticMatcher.matchAutoData(autoData, {
+    instanceFilter: createVisibleInstanceFilter(),
+  });
+  if (!match.instance) {
+    return { ok: false, reason: match.reason ?? 'no-candidates' };
+  }
+  if (match.instance.instanceId !== inst.instanceId) {
+    return { ok: false, reason: 'wrong-instance' };
+  }
+  return { ok: true, autoData };
+}
+
+function fiberIdentityStrength(descriptor: {
+  testID?: string;
+  nativeID?: string;
+  accessibilityLabel?: string;
+  childText?: string;
+}): IdentityStrength {
+  if (descriptor.testID || descriptor.nativeID) return 'id';
+  if (descriptor.childText || descriptor.accessibilityLabel) return 'content';
+  return 'structural';
+}
+
+/**
+ * Envelope for a host the Babel plugin never registered. The minimal
+ * fingerprint lets an older SDK replay a `testID` through the exact-id path.
+ * `resolver: 'fiber'` is what current builds use for everything else.
+ */
+export function autoDataFromFiberTarget(
+  fiber: AnyFiber,
+  descriptor: {
+    kind: string;
+    role: MobileFingerprint['role'];
+    isPressable: boolean;
+    testID?: string;
+    nativeID?: string;
+    accessibilityLabel?: string;
+    childText?: string;
+  },
+): MobileAutoData {
+  const path = fiberPathFromHost(fiber);
+  const selector = descriptor.testID
+    ? descriptor.testID
+    : (path?.segments.map((segment) => segment.hostKind ?? segment.displayName).join(' > ') ??
+      descriptor.kind);
+  const strength = fiberIdentityStrength(descriptor);
+  const { screenId, screenName } = screenFromLocation();
+  const device = deviceMetadata();
+  const manualId = descriptor.testID ?? descriptor.nativeID;
+  return {
+    version: MOBILE_AUTODATA_VERSION,
+    platform: 'react-native',
+    selector,
+    displayName: descriptor.kind,
+    ...(manualId ? { anchorId: manualId, manualId } : {}),
+    resolver: 'fiber',
+    ...(path ? { fiberPath: path } : {}),
+    fingerprint: {
+      version: MOBILE_FINGERPRINT_VERSION,
+      structuralPath: selector,
+      templatePath: selector,
+      kind: descriptor.kind,
+      role: descriptor.role,
+      ...(manualId ? { manualId } : {}),
+      ...(descriptor.testID ? { testID: descriptor.testID } : {}),
+      ...(descriptor.nativeID ? { nativeID: descriptor.nativeID } : {}),
+      ...(descriptor.childText ? { childText: descriptor.childText } : {}),
+      ...(descriptor.accessibilityLabel
+        ? { accessibilityLabel: descriptor.accessibilityLabel }
+        : {}),
+      ancestors: [],
+      previousSiblings: [],
+      nextSiblings: [],
+      isPressable: descriptor.isPressable,
+      identityStrength: strength,
+    },
+    screenId,
+    ...(screenName ? { screenName } : {}),
+    platformData: {
+      ...(descriptor.testID ? { testID: descriptor.testID } : {}),
+      ...(descriptor.accessibilityLabel
+        ? { accessibilityLabel: descriptor.accessibilityLabel }
+        : {}),
+      ...(descriptor.childText ? { childText: descriptor.childText } : {}),
+      isPressable: descriptor.isPressable,
+    },
+    ...(device ? { device } : {}),
+  };
+}
+
+export function encodeFiberTargetAutoData(
+  fiber: AnyFiber,
+  descriptor: Parameters<typeof autoDataFromFiberTarget>[1],
+): string {
+  return encodeMobileAutoData(autoDataFromFiberTarget(fiber, descriptor));
+}
+
+/**
+ * Confirm may proceed only when replaying the pick hits this same host.
+ * Registry targets use the scored matcher; fiber targets use the fiber path.
+ */
+export function validatePickerTarget(target: PickTarget): PickerFingerprintValidation {
+  if (target.source === 'registry') return validatePickerFingerprint(target.instance);
+  const autoData = encodeFiberTargetAutoData(target.fiber, target.descriptor);
+  const decoded = autoDataFromFiberTarget(target.fiber, target.descriptor);
+  if (!decoded.fiberPath) return { ok: false, reason: 'no-fingerprint' };
+  const match = resolveFiberPath(decoded.fiberPath);
+  if (match.status === 'ambiguous') return { ok: false, reason: 'not-unique' };
+  if (match.status !== 'found') return { ok: false, reason: 'no-candidates' };
+  if (!fibersMatch(match.fiber, target.fiber)) return { ok: false, reason: 'wrong-instance' };
+  return { ok: true, autoData };
+}
+
+/** True when a fiber pick has no id and no content — Confirm still works, with advice. */
+export function fiberTargetNeedsIdAdvice(target: PickTarget): boolean {
+  if (target.source !== 'fiber') return false;
+  const strength = fiberIdentityStrength(target.descriptor);
+  return strength === 'structural';
+}
+
+export type PickerSelectionWarningReason = 'not-unique' | 'low-confidence';
+
+export type PickerSelectionAssessment =
+  | { kind: 'ok'; autoData: string }
+  | { kind: 'warning'; reason: PickerSelectionWarningReason; autoData: string }
+  | { kind: 'error'; reason: 'unresolvable' };
+
+/**
+ * Classify a stamped element for the picker chrome.
+ *
+ * A unique play-time hit can still be a warning: look-alike twins the matcher
+ * can still tell apart (`ambiguous`), or a structural-only identity that may
+ * break if the layout changes. Twins on a covered screen do not count. Any
+ * miss, including twins the matcher cannot separate, blocks confirm.
+ *
+ * Not-unique wins when both warnings apply. Call after live content is current;
+ * this refreshes it via {@link validatePickerFingerprint}.
+ */
+export function assessPickerSelection(inst: AutoAnchorInstance): PickerSelectionAssessment {
+  const validated = validatePickerFingerprint(inst);
+  if (!validated.ok) {
+    return { kind: 'error', reason: 'unresolvable' };
+  }
+  if (autoAnchorRegistry.isAmbiguousAmong(inst, createVisibleInstanceFilter())) {
+    return { kind: 'warning', reason: 'not-unique', autoData: validated.autoData };
+  }
+  if (deriveIdentityStrength(inst) === 'structural') {
+    return { kind: 'warning', reason: 'low-confidence', autoData: validated.autoData };
+  }
+  return { kind: 'ok', autoData: validated.autoData };
+}
+
+/**
+ * {@link assessPickerSelection} for any pick. Fiber picks resolve fail-closed,
+ * so twins the fiber path cannot separate are errors, never warnings.
+ */
+export function assessPickerTarget(target: PickTarget): PickerSelectionAssessment {
+  if (target.source === 'registry') return assessPickerSelection(target.instance);
+  const validated = validatePickerTarget(target);
+  if (!validated.ok) {
+    return { kind: 'error', reason: 'unresolvable' };
+  }
+  if (fiberTargetNeedsIdAdvice(target)) {
+    return { kind: 'warning', reason: 'low-confidence', autoData: validated.autoData };
+  }
+  return { kind: 'ok', autoData: validated.autoData };
+}