@userflow-tech/react-native 0.2.0 → 0.3.1

package/src/anchors/semanticMatcher.ts

@@ -160,7 +160,7 @@ function normalizeText(value: string): string {
   return value.trim().replace(/\d+/g, '#').replace(/\s+/g, ' ');
 }
 
-function textsAgree(a: string | undefined, b: string | undefined): boolean {
+export function textsAgree(a: string | undefined, b: string | undefined): boolean {
   if (!a || !b) return false;
   return a === b || normalizeText(a) === normalizeText(b);
 }
@@ -190,7 +190,11 @@ function intrinsicNonTextAgrees(fp: MobileFingerprint, inst: AutoAnchorInstance)
   );
 }
 
-function scoreInstance(fp: MobileFingerprint, inst: AutoAnchorInstance): number {
+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
@@ -233,13 +237,29 @@ function scoreInstance(fp: MobileFingerprint, inst: AutoAnchorInstance): number
   // which double-counted the next window.
   score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
 
-  if (inst.ambiguous && !inst.manualId) score -= 40;
+  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,
@@ -277,20 +297,27 @@ function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFi
   // 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.
-  const broad = instanceFilter
-    ? autoAnchorRegistry.allInstances().filter(instanceFilter)
+  // 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, instanceFilter);
+  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) }))
+    .map((inst) => ({ inst, score: scoreInstance(fp, inst, ambiguous(inst)) }))
     .filter((s) => s.score > -Infinity)
     .sort((a, b) => b.score - a.score);
 
@@ -307,7 +334,7 @@ function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFi
     best.score >= 90 &&
     (!second || best.score - secondScore >= MATCH_UNIQUENESS_MARGIN)
   ) {
-    if (best.inst.ambiguous) {
+    if (ambiguous(best.inst)) {
       return miss('ambiguous-explicit-id', best.score, secondScore);
     }
     return {
@@ -339,10 +366,7 @@ function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFi
  * Surfaces the recorded `identityStrength` on every result so callers/telemetry
  * can flag weak (`structural`) targets.
  */
-export function matchFingerprint(
-  fp: MobileFingerprint,
-  opts?: { instanceFilter?: InstanceFilter },
-): MatchResult {
+export function matchFingerprint(fp: MobileFingerprint, opts?: MatchOptions): MatchResult {
   const result = matchFingerprintCore(fp, opts?.instanceFilter);
   if (fp.identityStrength) result.identityStrength = fp.identityStrength;
   return result;
@@ -352,10 +376,10 @@ export function matchFingerprint(
  * 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): MatchResult {
+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);
+  return matchFingerprint(decoded.fingerprint, opts);
 }

package/src/anchors/targetPressMonitor.ts

@@ -31,6 +31,17 @@ export interface TouchPoint {
   pageY: number;
 }
 
+/** True when the finger moved no more than `slop` between start and end. */
+export function withinTapSlop(
+  start: TouchPoint,
+  end: TouchPoint,
+  slop: number = TARGET_PRESS_TAP_SLOP,
+): boolean {
+  const dx = end.pageX - start.pageX;
+  const dy = end.pageY - start.pageY;
+  return dx * dx + dy * dy <= slop * slop;
+}
+
 /**
  * True when start and end both land in `rect` and movement stays within tap
  * slop — mirrors a DOM click on the target without claiming the responder.
@@ -43,9 +54,7 @@ export function isTargetTap(
 ): boolean {
   if (!pointInRect(start.pageX, start.pageY, rect)) return false;
   if (!pointInRect(end.pageX, end.pageY, rect)) return false;
-  const dx = end.pageX - start.pageX;
-  const dy = end.pageY - start.pageY;
-  return dx * dx + dy * dy <= slop * slop;
+  return withinTapSlop(start, end, slop);
 }
 
 /**

package/src/anchors/useUserflowAnchor.ts

@@ -71,6 +71,7 @@ export function useUserflowAnchor(id: string): React.RefCallback<View> {
       measureInWindow: (callback) => {
         node.measureInWindow(callback);
       },
+      node,
       scrollIntoView: () => {
         const scrollable = node as View & {
           scrollIntoView?: (options?: { block?: string; inline?: string }) => void;

package/src/anonymousId.ts

@@ -1,10 +1,18 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import { UserflowAuthError } from '@userflow-tech/core';
 
+import { getAsyncStorage } from './storage/asyncStorage';
+
 /** Matches the web SDK's `userflow:anonymousId` localStorage key. */
 export const ANONYMOUS_ID_STORAGE_KEY = 'userflow:anonymousId';
 
-function uuid(): string {
+export const ANONYMOUS_STORAGE_UNAVAILABLE =
+  'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.';
+
+export const ANONYMOUS_STORAGE_NOT_LINKED =
+  'Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not ' +
+  "linked in this native build. Add it to your app's package.json, run pod install, and rebuild.";
+
+export function uuid(): string {
   const webcrypto = globalThis.crypto;
   if (webcrypto?.randomUUID) return webcrypto.randomUUID();
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
@@ -15,23 +23,27 @@ function uuid(): string {
 }
 
 export async function getOrCreateAnonymousId(): Promise<string> {
+  const storage = getAsyncStorage();
+  if (!storage) {
+    throw new UserflowAuthError(ANONYMOUS_STORAGE_NOT_LINKED, { isHostContract: true });
+  }
   try {
-    let externalId = await AsyncStorage.getItem(ANONYMOUS_ID_STORAGE_KEY);
+    let externalId = await storage.getItem(ANONYMOUS_ID_STORAGE_KEY);
     if (!externalId) {
       externalId = `anon-${uuid()}`;
-      await AsyncStorage.setItem(ANONYMOUS_ID_STORAGE_KEY, externalId);
+      await storage.setItem(ANONYMOUS_ID_STORAGE_KEY, externalId);
     }
     return externalId;
   } catch {
-    throw new UserflowAuthError(
-      'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.',
-    );
+    throw new UserflowAuthError(ANONYMOUS_STORAGE_UNAVAILABLE, { isHostContract: true });
   }
 }
 
 export async function clearAnonymousId(): Promise<void> {
+  const storage = getAsyncStorage();
+  if (!storage) return;
   try {
-    await AsyncStorage.removeItem(ANONYMOUS_ID_STORAGE_KEY);
+    await storage.removeItem(ANONYMOUS_ID_STORAGE_KEY);
   } catch {
     // Best-effort clear, mirroring the web SDK when storage access is denied.
   }

package/src/authoring/ElementPickerOverlay.tsx

@@ -13,32 +13,49 @@ import { capturePickerScreenshot } from './capturePickerScreenshot';
 import { ChromeBarTransition, useChromeBarMounted } from './chrome/ChromeBarTransition';
 import { ChromeBottomSheet } from './chrome/ChromeBottomSheet';
 import { ChromeButton } from './chrome/ChromeButton';
+import { ChromeDialog } from './chrome/ChromeDialog';
 import { ChromeTooltip } from './chrome/ChromeTooltip';
 import { ChromeTopBar } from './chrome/ChromeTopBar';
+import { doubleTapMonitor } from './chrome/doubleTapMonitor';
 import { chromeColors, chromeOverlay, chromeRadius } from './chrome/tokens';
 import { DOUBLE_TAP_WINDOW_MS, isDoubleTap, type TapSample } from './doubleTap';
 import { elementPickerController, type ElementPickerState } from './elementPickerController';
+import { assessPickerTarget, type PickerSelectionAssessment } from './fingerprintFromInstance';
 import {
-  validatePickerFingerprint,
-  type PickerFingerprintFailure,
-} from './fingerprintFromInstance';
-import { hitTestAt, nextContainingIndex, type HitCandidate, type HitRect } from './hitTest';
-
-function statusForValidationFailure(reason: PickerFingerprintFailure['reason']): string {
-  if (reason === 'not-unique' || reason === 'ambiguous-explicit-id') {
-    return 'This element is not uniquely identifiable — add a testID or userflowId, or it may match the wrong item at play time.';
+  defaultCandidateIndex,
+  hitTestAt,
+  nextContainingIndex,
+  type HitCandidate,
+  type HitRect,
+  type PickTarget,
+} from './hitTest';
+
+function targetText(target: PickTarget): string | null {
+  if (target.source === 'registry') {
+    return target.instance.childText ?? target.instance.accessibilityLabel ?? null;
   }
-  if (reason === 'wrong-instance') {
-    return 'That fingerprint matches a different element — pick again or add a testID.';
-  }
-  return 'Could not uniquely match that element at play time.';
+  return target.descriptor.childText ?? target.descriptor.accessibilityLabel ?? null;
 }
 
 type PickerMode = 'navigate' | 'select';
-type PickerPhase = 'selecting' | 'navigating' | 'selected';
-
-const CONFIRM_HELPER = 'Navigate back to the Userflow app after confirming';
+type PickerPhase = 'selecting' | 'navigating' | 'selected' | 'blocked';
+type SelectionState = 'idle' | 'ok' | 'warning' | 'error-no-element' | 'error-unresolvable';
+
+const CONFIRM_HELPER = 'Return to the Userflow app after confirming';
+const WARNING_HELPER =
+  'Element may have an unreliable ID. This element may be selected but could break later on.';
+const ERROR_LABEL = 'Can’t select this element';
+const ERROR_HELPER = 'Element ID not found — select a different element';
 const ONBOARDING_COPY = 'Double tap anywhere to access the menu';
+const RETURN_NUDGE_TITLE = 'Return to the Userflow app';
+const RETURN_NUDGE_BODY =
+  'The element was selected successfully. You may now return to the Userflow app to continue editing your flow.';
+
+function selectionFromAssessment(assessment: PickerSelectionAssessment): SelectionState {
+  if (assessment.kind === 'error') return 'error-unresolvable';
+  if (assessment.kind === 'warning') return 'warning';
+  return 'ok';
+}
 
 /** Yield until chrome has left the native tree so captureScreen cannot include it. */
 function waitForCapturePaint(): Promise<void> {
@@ -68,6 +85,7 @@ function ringStyle(rect: HitRect, inset: number): ViewStyle {
 /**
  * Overlay chrome for in-app element picking. Mounted by UserflowProvider;
  * renders nothing until {@link elementPickerController.beginSelection}.
+ * Every pick shows the menu and onboarding tooltip.
  */
 export function ElementPickerOverlay(): React.ReactElement | null {
   const [state, setState] = React.useState<ElementPickerState>(() =>
@@ -78,9 +96,11 @@ export function ElementPickerOverlay(): React.ReactElement | null {
   const [index, setIndex] = React.useState(0);
   const [busy, setBusy] = React.useState(false);
   const [status, setStatus] = React.useState<string | null>(null);
+  const [selection, setSelection] = React.useState<SelectionState>('idle');
   const [chromeVisible, setChromeVisible] = React.useState(true);
   const [hidingForCapture, setHidingForCapture] = React.useState(false);
   const [showOnboarding, setShowOnboarding] = React.useState(false);
+  const [returnNudge, setReturnNudge] = React.useState(false);
   const [barHeight, setBarHeight] = React.useState(0);
   const [sheetHeight, setSheetHeight] = React.useState(0);
   const tapStartRef = React.useRef<{ pageX: number; pageY: number } | null>(null);
@@ -114,6 +134,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       setIndex(0);
       setBusy(false);
       setStatus(null);
+      setSelection('idle');
       setChromeVisible(true);
       setBarHeight(0);
       setSheetHeight(0);
@@ -135,10 +156,13 @@ export function ElementPickerOverlay(): React.ReactElement | null {
         return;
       }
       // Successful confirm leaves hidingForCapture true so chrome does not
-      // flash back during teardown. Clear it with the new session's setState
-      // so the first paint of this pick has bars.
-      if (armedRequestIdRef.current !== next.requestId) {
+      // flash back during teardown. Clear it with the new pick's setState so
+      // the first paint of this pick has its bars.
+      if (armedRequestIdRef.current !== next.requestId && next.requestId != null) {
         setHidingForCapture(false);
+        setReturnNudge(false);
+        setChromeVisible(true);
+        setShowOnboarding(true);
       }
     });
   }, [resetTransient]);
@@ -149,6 +173,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
     armedRequestIdRef.current = state.requestId;
     resetTransient();
     setShowOnboarding(true);
+    setReturnNudge(false);
   }, [resetTransient, state.active, state.requestId]);
 
   React.useEffect(() => {
@@ -200,7 +225,14 @@ export function ElementPickerOverlay(): React.ReactElement | null {
   }, []);
 
   const selected = candidates[index] ?? null;
-  const phase: PickerPhase = selected ? 'selected' : mode === 'select' ? 'selecting' : 'navigating';
+  const phase: PickerPhase =
+    selection === 'error-no-element'
+      ? 'blocked'
+      : selected
+        ? 'selected'
+        : mode === 'select'
+          ? 'selecting'
+          : 'navigating';
   modeRef.current = mode;
 
   // Bars slide/fade in with the picker, out on double-tap hide, and out again
@@ -216,21 +248,31 @@ export function ElementPickerOverlay(): React.ReactElement | null {
     }
   }, [phase]);
 
-  const applyHits = React.useCallback((hits: HitCandidate[]) => {
-    if (modeRef.current !== 'select') return;
-    lastTapRef.current = null;
-    setChromeVisible(true);
+  const applySelection = React.useCallback((hits: HitCandidate[]) => {
     if (hits.length === 0) {
       setCandidates([]);
       setIndex(0);
-      setStatus('No stamped element under that tap.');
+      setSelection('error-no-element');
+      setStatus(null);
       return;
     }
+    const nextIndex = defaultCandidateIndex(hits);
     setCandidates(hits);
-    setIndex(0);
+    setIndex(nextIndex);
+    setSelection(selectionFromAssessment(assessPickerTarget(hits[nextIndex]!.target)));
     setStatus(null);
   }, []);
 
+  const applyHits = React.useCallback(
+    (hits: HitCandidate[]) => {
+      if (modeRef.current !== 'select') return;
+      lastTapRef.current = null;
+      setChromeVisible(true);
+      applySelection(hits);
+    },
+    [applySelection],
+  );
+
   const scheduleSelection = React.useCallback(
     (pageX: number, pageY: number) => {
       cancelPendingSelection();
@@ -262,7 +304,12 @@ export function ElementPickerOverlay(): React.ReactElement | null {
   const onTap = React.useCallback(
     async (pageX: number, pageY: number) => {
       if (selected && candidates.length > 1 && pointInRect(pageX, pageY, selected.rect)) {
-        setIndex((current) => nextContainingIndex(candidates, current));
+        const next = nextContainingIndex(candidates, index);
+        setIndex(next);
+        const nextHit = candidates[next];
+        if (nextHit) {
+          setSelection(selectionFromAssessment(assessPickerTarget(nextHit.target)));
+        }
         setStatus(null);
         return;
       }
@@ -270,21 +317,34 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       setStatus(null);
       try {
         const hits = await hitTestAt(pageX, pageY);
-        if (hits.length === 0) {
-          setCandidates([]);
-          setIndex(0);
-          setStatus('No stamped element under that tap.');
-          return;
-        }
-        setCandidates(hits);
-        setIndex(0);
+        applySelection(hits);
       } finally {
         setBusy(false);
       }
     },
-    [candidates, selected],
+    [applySelection, candidates, index, selected],
   );
 
+  const hideOrShowChrome = React.useCallback(() => {
+    cancelPendingSelection();
+    lastTapRef.current = null;
+    setShowOnboarding(false);
+    setChromeVisible((visible) => !visible);
+  }, [cancelPendingSelection]);
+
+  // Navigate mode unmounts the capture layer so the host app can receive
+  // touches. Double-tap still has to reach the bars, via the screen-wide
+  // monitor the preview bar uses. Select mode keeps its own capture handler
+  // and must not also subscribe, or one double tap would toggle twice.
+  React.useEffect(() => {
+    if (!state.active || mode !== 'navigate') return;
+    const subscription = { onDoubleTap: hideOrShowChrome };
+    doubleTapMonitor.set(subscription);
+    return () => {
+      doubleTapMonitor.clearIfCurrent(subscription);
+    };
+  }, [hideOrShowChrome, mode, state.active]);
+
   const onGrant = React.useCallback((event: GestureResponderEvent) => {
     const { pageX, pageY } = event.nativeEvent;
     tapStartRef.current = { pageX, pageY };
@@ -301,41 +361,41 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       if (dx * dx + dy * dy > TARGET_PRESS_TAP_SLOP * TARGET_PRESS_TAP_SLOP) return;
 
       const sample: TapSample = { pageX, pageY, timestamp: Date.now() };
-      if (!selected && isDoubleTap(lastTapRef.current, sample)) {
-        cancelPendingSelection();
-        lastTapRef.current = null;
-        setShowOnboarding(false);
-        setChromeVisible((visible) => !visible);
+      const engaged = selected != null || selection === 'error-no-element';
+      if (!engaged && isDoubleTap(lastTapRef.current, sample)) {
+        hideOrShowChrome();
         return;
       }
       lastTapRef.current = sample;
 
-      if (selected) {
+      if (engaged) {
         void onTap(pageX, pageY);
         return;
       }
       scheduleSelection(pageX, pageY);
     },
-    [cancelPendingSelection, onTap, scheduleSelection, selected],
+    [hideOrShowChrome, onTap, scheduleSelection, selected, selection],
   );
 
   const deselect = React.useCallback(() => {
     setCandidates([]);
     setIndex(0);
+    setSelection('idle');
     setStatus(null);
     setChromeVisible(true);
   }, []);
 
   const confirm = React.useCallback(async () => {
     if (!selected) return;
+    if (selection === 'error-unresolvable' || selection === 'error-no-element') return;
     const requestId = elementPickerController.getState().requestId;
     if (!requestId) return;
     setBusy(true);
     setStatus(null);
     try {
-      const validated = validatePickerFingerprint(selected.instance);
-      if (!validated.ok) {
-        setStatus(statusForValidationFailure(validated.reason));
+      const assessed = assessPickerTarget(selected.target);
+      if (assessed.kind === 'error') {
+        setSelection('error-unresolvable');
         return;
       }
       setHidingForCapture(true);
@@ -343,15 +403,17 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       const screenshot = await capturePickerScreenshot(selected.rect);
       const delivered = await elementPickerController.commit(
         {
-          instance: selected.instance,
-          autoData: validated.autoData,
-          text: selected.instance.childText ?? selected.instance.accessibilityLabel ?? null,
+          target: selected.target,
+          autoData: assessed.autoData,
+          text: targetText(selected.target),
           rect: selected.rect,
           ...(screenshot ? { screenshot } : {}),
         },
         requestId,
       );
-      if (!delivered && elementPickerController.getState().requestId === requestId) {
+      if (delivered && !elementPickerController.getState().active) {
+        setReturnNudge(true);
+      } else if (!delivered && elementPickerController.getState().requestId === requestId) {
         setHidingForCapture(false);
         setStatus("Couldn't send to Builder");
       }
@@ -361,23 +423,59 @@ export function ElementPickerOverlay(): React.ReactElement | null {
     } finally {
       setBusy(false);
     }
-  }, [selected]);
+  }, [selected, selection]);
 
-  if (!state.active && !chromeBarsMounted) return null;
+  const dismissReturnNudge = () => {
+    setReturnNudge(false);
+  };
 
-  const barLabel =
-    phase === 'selected'
+  if (!state.active && !chromeBarsMounted && !returnNudge) return null;
+
+  const isError = selection === 'error-no-element' || selection === 'error-unresolvable';
+  const toneIcon = isError
+    ? { name: 'triangle-exclamation' as const, tintColor: chromeColors.dangerAccent }
+    : selection === 'warning'
+      ? { name: 'circle-exclamation' as const, tintColor: chromeColors.warningAccent }
+      : undefined;
+
+  const barLabel = isError
+    ? ERROR_LABEL
+    : phase === 'selected' || selection === 'warning'
       ? 'Confirm selected element'
       : phase === 'selecting'
         ? 'Tap an element to select it'
         : 'Navigate screens';
 
-  const helperText = status ?? (phase === 'selected' ? CONFIRM_HELPER : undefined);
+  const helperText =
+    status ??
+    (isError
+      ? ERROR_HELPER
+      : selection === 'warning'
+        ? WARNING_HELPER
+        : phase === 'selected'
+          ? CONFIRM_HELPER
+          : undefined);
+  const helperIcon = status ? undefined : toneIcon;
   const tooltipVisible = state.active && showOnboarding && chromeVisible && phase === 'selecting';
 
   return (
     <View pointerEvents="box-none" style={styles.root} testID="userflow-element-picker">
-      {state.active && phase === 'selecting' ? (
+      {returnNudge && !state.active ? (
+        <ChromeDialog
+          body={RETURN_NUDGE_BODY}
+          onClose={dismissReturnNudge}
+          title={RETURN_NUDGE_TITLE}
+        >
+          <ChromeButton
+            accessibilityLabel="Okay"
+            flex
+            label="Okay"
+            onPress={dismissReturnNudge}
+            testID="userflow-element-picker-return-okay"
+          />
+        </ChromeDialog>
+      ) : null}
+      {state.active && (phase === 'selecting' || phase === 'blocked') ? (
         <View pointerEvents="none" style={styles.dim} testID="userflow-element-picker-dim" />
       ) : null}
 
@@ -435,7 +533,12 @@ export function ElementPickerOverlay(): React.ReactElement | null {
           style={styles.top}
           visible={chromeBarsVisible}
         >
-          <ChromeTopBar label={barLabel} onMeasureHeight={onMeasureHeight} />
+          <ChromeTopBar
+            label={barLabel}
+            onMeasureHeight={onMeasureHeight}
+            tone={isError ? 'error' : 'default'}
+            {...(toneIcon ? { icon: toneIcon } : {})}
+          />
         </ChromeBarTransition>
       ) : null}
 
@@ -444,6 +547,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
           <ChromeTooltip
             onDismiss={() => {
               setShowOnboarding(false);
+              setChromeVisible(false);
             }}
           >
             {ONBOARDING_COPY}
@@ -458,8 +562,13 @@ export function ElementPickerOverlay(): React.ReactElement | null {
           style={styles.bottom}
           visible={chromeBarsVisible}
         >
-          <ChromeBottomSheet helperText={helperText} onMeasureHeight={onMeasureSheetHeight}>
-            {phase === 'selected' ? (
+          <ChromeBottomSheet
+            helperText={helperText}
+            onMeasureHeight={onMeasureSheetHeight}
+            tone={isError ? 'error' : 'default'}
+            {...(helperIcon ? { helperIcon } : {})}
+          >
+            {phase === 'selected' || phase === 'blocked' ? (
               <>
                 <ChromeButton
                   accessibilityLabel="Deselect"
@@ -470,7 +579,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
                 />
                 <ChromeButton
                   accessibilityLabel="Confirm element"
-                  disabled={busy}
+                  disabled={busy || isError}
                   label="Confirm element"
                   onPress={() => {
                     void confirm();