@userflow-tech/react-native 0.1.1 → 0.3.0

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

package/src/anchors/resolveAutoAnchorHost.ts

@@ -0,0 +1,182 @@
+import {
+  decodeMobileAutoData,
+  type MobileAutoData,
+  type MobileFingerprint,
+} from '@userflow-tech/protocol';
+
+import type { AnchorHost } from './AnchorRegistry';
+import type { AutoAnchorInstance } from './AutoAnchorRegistry';
+import type { AnyFiber } from './fiber/fiberInternals';
+import { fiberFromPublicInstance } from './fiber/fiberInternals';
+import { createFiberMeasureInWindow } from './fiber/measureHostFiber';
+import { resolveFiberPath } from './fiber/resolveFiberPath';
+import { createVisibleInstanceFilter } from './isInstanceOnVisibleScreen';
+import { resolveAnchorHost } from './resolveAnchorHost';
+import { matchFingerprint, type MatchResult } from './semanticMatcher';
+
+export type AutoAnchorResolution =
+  | {
+      status: 'found';
+      host: AnchorHost;
+      fiber?: AnyFiber;
+      /**
+       * Id to pass to `invalidateFiberAnchor` after a zero-size measure.
+       * Set on the exact-id fast path, where the host came from the fiber cache.
+       */
+      fiberCacheId?: string;
+      match?: MatchResult;
+    }
+  | { status: 'ambiguous'; match?: MatchResult }
+  | { status: 'absent'; match?: MatchResult }
+  | { status: 'unknown'; match?: MatchResult };
+
+type MeasureInWindowCallback = (x: number, y: number, width: number, height: number) => void;
+
+interface MeasurableNode {
+  measureInWindow: (callback: MeasureInWindowCallback) => void;
+  scrollIntoView?: () => void;
+}
+
+function isMeasurableNode(value: unknown): value is MeasurableNode {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { measureInWindow?: unknown }).measureInWindow === 'function'
+  );
+}
+
+/**
+ * Wrap a live auto-anchor instance into an {@link AnchorHost}. Returns null when
+ * the instance is unmounted or its node cannot be measured.
+ */
+function hostFromInstance(inst: AutoAnchorInstance): AnchorHost | null {
+  const node = inst.ref.current;
+  if (isMeasurableNode(node)) {
+    return {
+      measureInWindow: (callback) => {
+        node.measureInWindow(callback);
+      },
+      ...(typeof node.scrollIntoView === 'function'
+        ? {
+            scrollIntoView: () => {
+              node.scrollIntoView?.();
+            },
+          }
+        : {}),
+    };
+  }
+  const fiber = fiberFromInstance(inst);
+  if (!fiber) return null;
+  return { measureInWindow: createFiberMeasureInWindow(fiber) };
+}
+
+function fiberFromInstance(inst: AutoAnchorInstance): AnyFiber | null {
+  return fiberFromPublicInstance(inst.ref.current);
+}
+
+/** Authoritative id that the existing fiber / manual resolver can look up. */
+function exactIdFromFingerprint(fp: MobileFingerprint): string | null {
+  if (fp.userflowId) return fp.userflowId;
+  if (fp.testID) return fp.testID;
+  if (fp.nativeID && !fp.nativeID.startsWith('uf_')) return fp.nativeID;
+  return null;
+}
+
+function decodeInput(autoData: string | MobileAutoData | null | undefined): MobileAutoData | null {
+  if (autoData == null) return null;
+  if (typeof autoData === 'string') {
+    if (!autoData.trim()) return null;
+    return decodeMobileAutoData(autoData);
+  }
+  return autoData;
+}
+
+function mapMatch(match: MatchResult): AutoAnchorResolution {
+  if (match.instance) {
+    const host = hostFromInstance(match.instance);
+    if (!host) return { status: 'unknown', match };
+    const fiber = fiberFromInstance(match.instance);
+    return { status: 'found', host, match, ...(fiber ? { fiber } : {}) };
+  }
+
+  switch (match.reason) {
+    case 'ambiguous-explicit-id':
+      return { status: 'ambiguous', match };
+    case 'all-contradicted':
+      return { status: 'absent', match };
+    default:
+      // no-candidates / no-fingerprint / below-threshold / not-unique / unset
+      return { status: 'unknown', match };
+  }
+}
+
+/**
+ * Score visible-screen instances first so a covered look-alike cannot steal
+ * uniqueness or win over a host the user can actually see. If nothing visible
+ * scored and the unfiltered pool still has a hit, that hit is on a covered
+ * screen — `absent`, matching MANUAL covered-screen semantics.
+ */
+function mapScored(fp: MobileFingerprint): AutoAnchorResolution {
+  const visible = matchFingerprint(fp, { instanceFilter: createVisibleInstanceFilter() });
+  if (visible.instance) return mapMatch(visible);
+
+  if (visible.reason === 'no-candidates') {
+    const any = matchFingerprint(fp);
+    if (any.instance) return { status: 'absent', match: any };
+    if (any.reason === 'all-contradicted') return mapMatch(any);
+  }
+
+  return mapMatch(visible);
+}
+
+/**
+ * Resolve an AUTO (codeless) selector against the live UI.
+ *
+ * Exact-id fast path reuses {@link resolveAnchorHost} so a fingerprint that
+ * carries a real `testID` / `userflowId` / non-`uf_` `nativeID` still resolves
+ * under Babel `stampOnly: true` (no auto-registry population).
+ *
+ * Scored matches run over `autoAnchorRegistry` and fail closed: weak or
+ * non-unique evidence is `unknown`, not `absent`, so ELEMENT gates stay blocked
+ * rather than inventing a truth value. Hosts on a covered navigator screen
+ * are skipped the same way the fiber scan skips them.
+ */
+export function resolveAutoAnchorHost(
+  autoData: string | MobileAutoData | null | undefined,
+): AutoAnchorResolution {
+  const decoded = decodeInput(autoData);
+  const fp = decoded?.fingerprint;
+  if (!fp) return { status: 'unknown' };
+
+  if (decoded.resolver === 'fiber' && decoded.fiberPath) {
+    const fiberHit = resolveFiberPath(decoded.fiberPath);
+    if (fiberHit.status === 'found') {
+      return {
+        status: 'found',
+        host: { measureInWindow: createFiberMeasureInWindow(fiberHit.fiber) },
+        fiber: fiberHit.fiber,
+        fiberCacheId: fiberHit.cacheId,
+      };
+    }
+    if (fiberHit.status === 'ambiguous') return { status: 'ambiguous' };
+    return { status: 'unknown' };
+  }
+
+  const exactId = exactIdFromFingerprint(fp);
+  if (exactId) {
+    const exact = resolveAnchorHost(exactId);
+    if (exact.status === 'found') {
+      return {
+        status: 'found',
+        host: exact.host,
+        fiberCacheId: exactId,
+        ...(exact.fiber ? { fiber: exact.fiber } : {}),
+      };
+    }
+    if (exact.status === 'ambiguous') {
+      return { status: 'ambiguous' };
+    }
+  }
+
+  return mapScored(fp);
+}

package/src/anchors/semanticMatcher.ts

@@ -0,0 +1,385 @@
+import {
+  decodeMobileAutoData,
+  type IdentityStrength,
+  type MobileAutoData,
+  type MobileFingerprint,
+  type SemanticSegment,
+  type SiblingDescriptor,
+} from '@userflow-tech/protocol';
+
+import { autoAnchorRegistry, type AutoAnchorInstance } from './AutoAnchorRegistry';
+
+/**
+ * Scored semantic matcher (rn-v3).
+ *
+ * Ranks live {@link autoAnchorRegistry} instances against a recorded
+ * fingerprint. Explicit IDs are authoritative. Absolute ordinals are not
+ * scored. Accepts only when the best score clears a threshold and beats the
+ * runner-up by a margin.
+ *
+ * Play-time AUTO resolution goes through `resolveAutoAnchorHost`, which
+ * maps a hit into a measurable host.
+ */
+
+export type MatchMissReason =
+  | 'no-candidates'
+  | 'all-contradicted'
+  | 'below-threshold'
+  | 'not-unique'
+  | 'ambiguous-explicit-id'
+  | 'no-fingerprint';
+
+export interface MatchResult {
+  instance: AutoAnchorInstance | null;
+  score: number;
+  secondScore: number;
+  reason?: MatchMissReason;
+  /** Strongest signal the recorded fingerprint rests on (telemetry / author guidance). */
+  identityStrength?: IdentityStrength;
+  /**
+   * True when the match was won even though the live text is not byte-identical
+   * to the recorded `childText`. Covers both a benign counter tick
+   * (`Count: 0` → `Count: 1`, which normalization forgives) and a real rename
+   * that an icon/shape/structure vouched for. Raw inequality, not the fatal
+   * check — a fatal mismatch never reaches a won match.
+   */
+  textDisagreed?: boolean;
+}
+
+export const MATCH_MIN_SCORE = 40;
+export const MATCH_UNIQUENESS_MARGIN = 12;
+/** Max contribution of structural-path similarity — matches the previous flat weight. */
+const STRUCTURAL_PATH_MAX = 35;
+
+function pathSegments(path: string): string[] {
+  return path.split(' > ');
+}
+
+/** Kind (name) prefix of a canonical segment, before any `{…}` / `#ordinal`. */
+function segmentKind(seg: string): string {
+  const m = /^([A-Za-z_][\w.]*)/.exec(seg);
+  return m ? m[1]! : seg;
+}
+
+/** The `{k=v}` identity token of a segment (id or text), or null for ordinal-only. */
+function segmentLabel(seg: string): string | null {
+  const i = seg.indexOf('{');
+  return i >= 0 && seg.endsWith('}') ? seg.slice(i) : null;
+}
+
+/**
+ * Graded structural-path similarity (replaces all-or-nothing exact match).
+ *
+ * Scores by aligned segments from the root: matching id/text-bearing segments
+ * count strongly, matching kinds lightly, and a *pure ordinal* difference in an
+ * otherwise same-kind segment is tolerated (no penalty) instead of zeroing the
+ * whole signal. A kind divergence stops deeper credit.
+ */
+function scoreStructuralPath(
+  fpPath: string | undefined,
+  instPath: string | undefined,
+  max = STRUCTURAL_PATH_MAX,
+): number {
+  if (!fpPath || !instPath) return 0;
+  if (fpPath === instPath) return max;
+
+  const a = pathSegments(fpPath);
+  const b = pathSegments(instPath);
+  const n = Math.min(a.length, b.length);
+  let matchedLabeled = 0;
+  let kindAligned = 0;
+
+  for (let i = 0; i < n; i += 1) {
+    const sa = a[i]!;
+    const sb = b[i]!;
+    if (segmentKind(sa) !== segmentKind(sb)) break;
+    kindAligned += 1;
+    const la = segmentLabel(sa);
+    const lb = segmentLabel(sb);
+    if (la !== null && la === lb) matchedLabeled += 1;
+  }
+
+  const score = matchedLabeled * 12 + kindAligned * 2 + (a.length === b.length ? 3 : 0);
+  return Math.min(max, Math.round(score * (max / STRUCTURAL_PATH_MAX)));
+}
+
+function scoreSiblingWindow(expected: SiblingDescriptor[], actual: SiblingDescriptor[]): number {
+  if (expected.length === 0) return 0;
+  let score = 0;
+  const len = Math.min(expected.length, actual.length);
+  for (let i = 0; i < len; i += 1) {
+    const e = expected[expected.length - 1 - i]!;
+    const a = actual[actual.length - 1 - i]!;
+    if (e.kind === a.kind) score += 4;
+    if (e.role && a.role && e.role === a.role) score += 2;
+    if (e.userflowId && a.userflowId && e.userflowId === a.userflowId) score += 10;
+    if (e.testID && a.testID && e.testID === a.testID) score += 8;
+    if (e.text && a.text && textsAgree(e.text, a.text)) score += 6;
+  }
+  score -= Math.abs(expected.length - actual.length) * 2;
+  return Math.max(0, score);
+}
+
+function scoreAncestors(expected: SemanticSegment[], actual: SemanticSegment[]): number {
+  if (expected.length === 0) return 0;
+  let score = 0;
+  const eTail = expected.slice(-4);
+  const aTail = actual.slice(-4);
+  const len = Math.min(eTail.length, aTail.length);
+  for (let i = 0; i < len; i += 1) {
+    const e = eTail[eTail.length - 1 - i]!;
+    const a = aTail[aTail.length - 1 - i]!;
+    if (e.kind === a.kind) score += 5;
+    if (e.role && a.role && e.role === a.role) score += 3;
+    if (e.userflowId && a.userflowId && e.userflowId === a.userflowId) score += 15;
+    if (e.testID && a.testID && e.testID === a.testID) score += 12;
+  }
+  return score;
+}
+
+function contradictsStrong(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  if (fp.userflowId && inst.userflowId && fp.userflowId !== inst.userflowId) return true;
+  if (fp.testID && inst.testID && fp.testID !== inst.testID) return true;
+  if (fp.manualId && inst.manualId && fp.manualId !== inst.manualId) return true;
+  if (fp.kind && inst.kind && fp.kind !== inst.kind) return true;
+  return false;
+}
+
+/** True when an authoritative id in the fingerprint matches the live instance. */
+function idAgrees(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  return (
+    (!!fp.manualId && inst.manualId === fp.manualId) ||
+    (!!fp.userflowId && inst.userflowId === fp.userflowId) ||
+    (!!fp.testID && inst.testID === fp.testID) ||
+    (!!fp.nativeID && inst.nativeID === fp.nativeID && !fp.nativeID.startsWith('uf_'))
+  );
+}
+
+/** Collapse digit runs so `Count: 0` and `Count: 1` compare as the same template. */
+function normalizeText(value: string): string {
+  return value.trim().replace(/\d+/g, '#').replace(/\s+/g, ' ');
+}
+
+export function textsAgree(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b) return false;
+  return a === b || normalizeText(a) === normalizeText(b);
+}
+
+/** Recorded and live raw text both present but disagree (a rename / translation). */
+function childTextRawDiffers(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  return !!fp.childText && !!inst.childText && fp.childText !== inst.childText;
+}
+
+/**
+ * Fatal text mismatch: raw strings differ *and* the digit-normalized forms
+ * differ. `Count: 0` vs `Count: 1` is not fatal; `Save` vs `Cancelar` is.
+ */
+function childTextDisagrees(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  return childTextRawDiffers(fp, inst) && !textsAgree(fp.childText, inst.childText);
+}
+
+/**
+ * A text-independent intrinsic signal agrees: a matching icon or image. These
+ * survive translation/relabeling. (accessibilityLabel is excluded — it is
+ * typically localized too.)
+ */
+function intrinsicNonTextAgrees(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  return (
+    (!!fp.iconName && inst.iconName === fp.iconName) ||
+    (!!fp.imageSrc && inst.imageSrc === fp.imageSrc)
+  );
+}
+
+function scoreInstance(
+  fp: MobileFingerprint,
+  inst: AutoAnchorInstance,
+  ambiguous: boolean,
+): number {
+  if (contradictsStrong(fp, inst)) return -Infinity;
+
+  // A childText disagreement is disqualifying unless a text-independent identity
+  // vouches for the element (authoritative id, or matching icon/image).
+  if (childTextDisagrees(fp, inst) && !idAgrees(fp, inst) && !intrinsicNonTextAgrees(fp, inst)) {
+    return -Infinity;
+  }
+
+  let score = 0;
+
+  if (fp.manualId && inst.manualId === fp.manualId) score += 100;
+  if (fp.userflowId && inst.userflowId === fp.userflowId) score += 100;
+  if (fp.testID && inst.testID === fp.testID) score += 90;
+  if (fp.nativeID && inst.nativeID === fp.nativeID && !fp.nativeID.startsWith('uf_')) {
+    score += 80;
+  }
+
+  if (fp.kind === inst.kind) score += 20;
+  if (fp.role === inst.role) score += 10;
+  if (fp.isPressable === true && inst.isPressable) score += 5;
+
+  score += scoreStructuralPath(fp.structuralPath, inst.structuralPath, STRUCTURAL_PATH_MAX);
+  score += scoreStructuralPath(fp.templatePath, inst.templatePath, 15);
+  if (fp.instanceScope && inst.instanceScope === fp.instanceScope) score += 30;
+
+  if (fp.childText && inst.childText === fp.childText) score += 40;
+  else if (fp.childText && inst.childText && textsAgree(fp.childText, inst.childText)) score += 18;
+  if (fp.accessibilityLabel && inst.accessibilityLabel === fp.accessibilityLabel) {
+    score += 25;
+  }
+  if (fp.iconName && inst.iconName) score += fp.iconName === inst.iconName ? 45 : -30;
+  if (fp.imageSrc && inst.imageSrc) score += fp.imageSrc === inst.imageSrc ? 45 : -30;
+  if (fp.childShape && inst.childShape === fp.childShape) score += 15;
+
+  score += scoreAncestors(fp.ancestors ?? [], inst.ancestors ?? []);
+
+  const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
+  score += scoreSiblingWindow(fp.previousSiblings ?? [], window.previous);
+  // Score next siblings once. The POC added a reversed pass *and* a direct pass,
+  // which double-counted the next window.
+  score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
+
+  if (ambiguous && !inst.manualId) score -= 40;
+
+  return score;
+}
+
+type InstanceFilter = (inst: AutoAnchorInstance) => boolean;
+
+interface MatchOptions {
+  instanceFilter?: InstanceFilter;
+}
+
+/** Each instance's visibility is computed once per match. */
+function memoizeFilter(filter: InstanceFilter): InstanceFilter {
+  const memo = new Map<string, boolean>();
+  return (inst) => {
+    const cached = memo.get(inst.instanceId);
+    if (cached !== undefined) return cached;
+    const visible = filter(inst);
+    memo.set(inst.instanceId, visible);
+    return visible;
+  };
+}
+
+function candidatePool(
+  fp: MobileFingerprint,
+  instanceFilter?: InstanceFilter,
+): AutoAnchorInstance[] {
+  // Explicit ids are authoritative: a miss is no-candidates, not a full-registry search.
+  let pool: AutoAnchorInstance[];
+  if (fp.manualId) {
+    pool = autoAnchorRegistry.getInstancesByManualId(fp.manualId);
+  } else if (fp.userflowId) {
+    pool = autoAnchorRegistry.getInstancesByManualId(fp.userflowId);
+  } else if (fp.testID) {
+    pool = autoAnchorRegistry.getInstancesByManualId(fp.testID);
+  } else {
+    pool = autoAnchorRegistry.allInstances();
+    if (fp.role) {
+      const filtered = pool.filter((i) => i.role === fp.role);
+      if (filtered.length > 0) pool = filtered;
+    } else if (fp.kind) {
+      const filtered = pool.filter((i) => i.kind === fp.kind);
+      if (filtered.length > 0) pool = filtered;
+    }
+    if (fp.isPressable) {
+      const filtered = pool.filter((i) => i.isPressable);
+      if (filtered.length > 0) pool = filtered;
+    }
+  }
+  return instanceFilter ? pool.filter(instanceFilter) : pool;
+}
+
+function miss(reason: MatchMissReason, score = 0, secondScore = 0): MatchResult {
+  return { instance: null, score, secondScore, reason };
+}
+
+function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFilter): MatchResult {
+  // Live text / testID must be applied *before* pooling. A shared Babel helper
+  // (`const field = () => <TextInput testID={id} />`) reuses one auto-anchor
+  // callback, so the runtime bag is last-writer-wins until we read the host.
+  // A filter's verdict is memoized so covered-screen checks run once per instance.
+  const filter = instanceFilter ? memoizeFilter(instanceFilter) : undefined;
+  const broad = filter
+    ? autoAnchorRegistry.allInstances().filter(filter)
+    : autoAnchorRegistry.allInstances();
+  if (broad.length > 0) {
+    autoAnchorRegistry.refreshLiveContent(broad);
+  }
+
+  const pool = candidatePool(fp, filter);
+  if (pool.length === 0) {
+    return miss('no-candidates');
+  }
+
+  // Visibility can clear a registry-wide ambiguous flag (a covered twin) but
+  // never add one. Unfiltered matches keep the stored flag.
+  const ambiguous = (inst: AutoAnchorInstance) =>
+    filter ? autoAnchorRegistry.isAmbiguousAmong(inst, filter) : inst.ambiguous;
+
+  const scored = pool
+    .map((inst) => ({ inst, score: scoreInstance(fp, inst, ambiguous(inst)) }))
+    .filter((s) => s.score > -Infinity)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length === 0) {
+    return miss('all-contradicted');
+  }
+
+  const best = scored[0]!;
+  const second = scored[1];
+  const secondScore = second?.score ?? 0;
+
+  if (
+    (fp.manualId || fp.userflowId || fp.testID) &&
+    best.score >= 90 &&
+    (!second || best.score - secondScore >= MATCH_UNIQUENESS_MARGIN)
+  ) {
+    if (ambiguous(best.inst)) {
+      return miss('ambiguous-explicit-id', best.score, secondScore);
+    }
+    return {
+      instance: best.inst,
+      score: best.score,
+      secondScore,
+      textDisagreed: childTextRawDiffers(fp, best.inst),
+    };
+  }
+
+  if (best.score < MATCH_MIN_SCORE) {
+    return miss('below-threshold', best.score, secondScore);
+  }
+
+  if (best.score - secondScore < MATCH_UNIQUENESS_MARGIN) {
+    return miss('not-unique', best.score, secondScore);
+  }
+
+  return {
+    instance: best.inst,
+    score: best.score,
+    secondScore,
+    textDisagreed: childTextRawDiffers(fp, best.inst),
+  };
+}
+
+/**
+ * Resolve a recorded fingerprint against the live auto-anchor registry.
+ * Surfaces the recorded `identityStrength` on every result so callers/telemetry
+ * can flag weak (`structural`) targets.
+ */
+export function matchFingerprint(fp: MobileFingerprint, opts?: MatchOptions): MatchResult {
+  const result = matchFingerprintCore(fp, opts?.instanceFilter);
+  if (fp.identityStrength) result.identityStrength = fp.identityStrength;
+  return result;
+}
+
+/**
+ * Decode an `autoData` envelope (or accept an already-decoded one) and score
+ * its fingerprint. Missing / malformed envelopes fail closed.
+ */
+export function matchAutoData(input: MobileAutoData | string, opts?: MatchOptions): MatchResult {
+  const decoded = typeof input === 'string' ? decodeMobileAutoData(input) : input;
+  if (!decoded?.fingerprint) {
+    return miss('no-fingerprint');
+  }
+  return matchFingerprint(decoded.fingerprint, opts);
+}

package/src/anonymousId.ts

@@ -4,7 +4,7 @@ import { UserflowAuthError } from '@userflow-tech/core';
 /** Matches the web SDK's `userflow:anonymousId` localStorage key. */
 export const ANONYMOUS_ID_STORAGE_KEY = 'userflow:anonymousId';
 
-function uuid(): string {
+export function uuid(): string {
   const webcrypto = globalThis.crypto;
   if (webcrypto?.randomUUID) return webcrypto.randomUUID();
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
@@ -25,6 +25,7 @@ export async function getOrCreateAnonymousId(): Promise<string> {
   } catch {
     throw new UserflowAuthError(
       'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.',
+      { isHostContract: true },
     );
   }
 }