@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/navigation/isOverlayPresentation.ts

@@ -0,0 +1,76 @@
+/** React Navigation `options.presentation` values that are overlays, not screens. */
+const OVERLAY_PRESENTATIONS = new Set([
+  'modal',
+  'transparentModal',
+  'containedModal',
+  'containedTransparentModal',
+  'fullScreenModal',
+  'formSheet',
+  'pageSheet',
+]);
+
+/** True when the focused route is a modal / sheet overlay, not a screen navigation. */
+export function isOverlayPresentation(presentation: unknown): boolean {
+  return typeof presentation === 'string' && OVERLAY_PRESENTATIONS.has(presentation);
+}
+
+type OptionsHolder = {
+  getCurrentOptions?: () => { presentation?: string } | undefined;
+};
+
+function presentationFromHolder(holder: unknown): string | undefined {
+  if (holder == null || typeof holder !== 'object') return undefined;
+  const getCurrentOptions = (holder as OptionsHolder).getCurrentOptions;
+  if (typeof getCurrentOptions !== 'function') return undefined;
+  try {
+    return getCurrentOptions()?.presentation;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads `presentation` from a React Navigation container ref.
+ * Accepts either a `NavigationContainerRef` or a `NavigationContainerRefWithCurrent`
+ * (`ref.current` is checked when the wrapper itself has no `getCurrentOptions`).
+ */
+export function readNavigationPresentation(ref: unknown): string | undefined {
+  const fromRef = presentationFromHolder(ref);
+  if (fromRef !== undefined) return fromRef;
+  if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    return presentationFromHolder((ref as { current: unknown }).current);
+  }
+  return undefined;
+}
+
+type StateListenerHolder = {
+  addListener?: (event: string, listener: () => void) => (() => void) | void;
+};
+
+function subscribeHolder(holder: unknown, listener: () => void): (() => void) | undefined {
+  if (holder == null || typeof holder !== 'object') return undefined;
+  const addListener = (holder as StateListenerHolder).addListener;
+  if (typeof addListener !== 'function') return undefined;
+  try {
+    const unsubscribe = addListener.call(holder, 'state', listener);
+    return typeof unsubscribe === 'function' ? unsubscribe : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Subscribes to React Navigation container `state` events.
+ * Accepts a `NavigationContainerRef` or `NavigationContainerRefWithCurrent`.
+ */
+export function subscribeNavigationState(
+  ref: unknown,
+  listener: () => void,
+): (() => void) | undefined {
+  const fromRef = subscribeHolder(ref, listener);
+  if (fromRef) return fromRef;
+  if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    return subscribeHolder((ref as { current: unknown }).current, listener);
+  }
+  return undefined;
+}

package/src/pairing/PairingController.ts

@@ -6,6 +6,8 @@ import {
 } from '@userflow-tech/core';
 import { AppState, type AppStateStatus, Linking, Platform } from 'react-native';
 
+import { clearFiberAnchorCache } from '../anchors/fiberAnchorCache';
+
 import { inspectPairingDeepLink, isPairingAttempt } from './deepLink';
 import {
   defaultPairingLogger,
@@ -14,9 +16,11 @@ import {
   pairingLinkDeferredMessage,
   pairingLinkInitFailedMessage,
   pairingListenerSetupFailedMessage,
+  pairingPreviewErrorMessage,
   pairingTokenStoreClearFailedMessage,
   type PairingLogger,
 } from './diagnostics';
+import { bindElementPickerRelay } from './elementPickerRelay';
 import { createPairingTokenStore, type PairingTokenStore } from './tokenStorage';
 
 export type PairingControllerListener = (state: PairingEngineState) => void;
@@ -73,6 +77,7 @@ export class PairingController {
   private deferredPairingToken: string | null = null;
   /** Diagnostics already emitted for the current init attempt. */
   private readonly loggedOnce = new Set<string>();
+  private relayUnsub: (() => void) | null = null;
 
   constructor(options: PairingControllerOptions) {
     this.core = options.core;
@@ -106,6 +111,8 @@ export class PairingController {
         lastError: null,
         needsRescan: false,
         awaitingStartCondition: false,
+        canRestartPreview: false,
+        previewRestartGeneration: 0,
       }
     );
   }
@@ -127,6 +134,8 @@ export class PairingController {
       }`,
       needsRescan: true,
       awaitingStartCondition: false,
+      canRestartPreview: false,
+      previewRestartGeneration: 0,
     };
   }
 
@@ -194,6 +203,7 @@ export class PairingController {
     this.appStateSub?.remove();
     this.appStateSub = null;
     this.started = false;
+    this.unbindRelay();
     void this.exitPreview();
   }
 
@@ -310,6 +320,16 @@ export class PairingController {
     this.emit(this.getState());
   }
 
+  /**
+   * Replay the last previewed flow from step 1. No-ops when nothing has been
+   * delivered yet (restart control is hidden in that case).
+   */
+  async restartPreview(): Promise<boolean> {
+    if (!this.engine) return false;
+    clearFiberAnchorCache();
+    return this.engine.restartPreview();
+  }
+
   /** Flush queued startFlowWithToken after identify. */
   notifyIdentified(): void {
     this.engine?.notifyIdentified();
@@ -323,21 +343,30 @@ export class PairingController {
       onServerMessage: (handler) => this.core.onServerMessage(handler),
       isIdentified: () => this.core.getUserId() != null,
       pairingOptions: { pairingEndpoint: this.pairingEndpoint },
-      deviceMeta: () => ({
-        os: Platform.OS,
-      }),
+      deviceMeta: () => ({ os: Platform.OS }),
     });
 
     this.engine.onStateChange((state) => {
       this.emit(state);
+      if (state.lastError) {
+        this.warnOnce(pairingPreviewErrorMessage(state.lastError));
+      }
       if (state.status === 'token_expired' || state.needsRescan) {
         void this.tokenStore.clear();
       }
     });
 
+    this.unbindRelay();
+    this.relayUnsub = bindElementPickerRelay(this.engine);
+
     return this.engine;
   }
 
+  private unbindRelay(): void {
+    this.relayUnsub?.();
+    this.relayUnsub = null;
+  }
+
   private emit(state: PairingEngineState): void {
     for (const listener of this.listeners) {
       try {

package/src/pairing/PreviewModeBanner.tsx

@@ -1,10 +1,30 @@
 import type { PairingEngineState } from '@userflow-tech/core';
 import * as React from 'react';
-import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { StyleSheet, View } from 'react-native';
+
+import { ChromeBarTransition, useChromeBarMounted } from '../authoring/chrome/ChromeBarTransition';
+import { ChromeButton } from '../authoring/chrome/ChromeButton';
+import { ChromeDialog } from '../authoring/chrome/ChromeDialog';
+import { ChromeTooltip } from '../authoring/chrome/ChromeTooltip';
+import { ChromeTopBar } from '../authoring/chrome/ChromeTopBar';
+import { doubleTapMonitor } from '../authoring/chrome/doubleTapMonitor';
+import { useReportPreviewBannerHeight } from '../surfaces/surfaceLayoutInsets';
+
+import { resolvePreviewChrome, type PreviewChrome } from './resolvePreviewChrome';
+
+type VisiblePreviewChrome = Extract<PreviewChrome, { visible: true }>;
+type ConfirmingKind = 'exit' | 'restart';
+
+const ONBOARDING_COPY = 'Double tap anywhere to access the menu';
 
 export interface PreviewModeBannerProps {
   state: PairingEngineState;
   onExit: () => void;
+  onRestart?: () => void;
+  /** True while a chrome confirm dialog is open, so the provider can trap host a11y. */
+  onConfirmingChange?: (open: boolean) => void;
+  /** Hide the preview bar while the element picker is using the same top slot. */
+  suppressed?: boolean | undefined;
 }
 
 /**
@@ -13,68 +33,234 @@ export interface PreviewModeBannerProps {
 export function PreviewModeBanner({
   state,
   onExit,
+  onRestart,
+  onConfirmingChange,
+  suppressed = false,
 }: PreviewModeBannerProps): React.ReactElement | null {
-  if (!state.previewActive && state.status === 'idle') return null;
-  if (
-    !state.previewActive &&
-    state.status !== 'token_expired' &&
-    state.status !== 'device_already_paired' &&
-    state.status !== 'error'
-  ) {
-    return null;
+  const setBannerHeight = useReportPreviewBannerHeight();
+  const chrome = resolvePreviewChrome(state);
+  const [chromeShown, setChromeShown] = React.useState(true);
+  const [showOnboarding, setShowOnboarding] = React.useState(false);
+  const [barHeight, setBarHeight] = React.useState(0);
+  const sessionArmedRef = React.useRef(false);
+  const isError = chrome.visible && chrome.tone === 'error';
+  const visible = chrome.visible && !suppressed && (chromeShown || isError);
+  const [confirming, setConfirming] = React.useState<ConfirmingKind | null>(null);
+  const showRestart = Boolean(state.canRestartPreview) && !isError;
+  const showDialog = confirming != null && visible && !isError;
+  // Keep the bar mounted through its slide-out (double-tap hide, preview end,
+  // or picker suppression), rendering the last known chrome while it leaves.
+  const barMounted = useChromeBarMounted(visible);
+  const lastVisibleChromeRef = React.useRef<VisiblePreviewChrome | null>(null);
+  if (chrome.visible) {
+    lastVisibleChromeRef.current = chrome;
   }
+  const barChrome = chrome.visible ? chrome : lastVisibleChromeRef.current;
+
+  React.useEffect(() => {
+    if (!chrome.visible) {
+      sessionArmedRef.current = false;
+      setChromeShown(true);
+      setShowOnboarding(false);
+      setBarHeight(0);
+      return;
+    }
+    if (isError) {
+      setChromeShown(true);
+      setShowOnboarding(false);
+      return;
+    }
+    if (!sessionArmedRef.current) {
+      sessionArmedRef.current = true;
+      setShowOnboarding(true);
+    }
+  }, [chrome.visible, isError]);
+
+  React.useEffect(() => {
+    if (!visible || isError) {
+      setConfirming(null);
+      return;
+    }
+    if (confirming === 'restart' && !state.canRestartPreview) {
+      setConfirming(null);
+    }
+  }, [confirming, isError, state.canRestartPreview, visible]);
+
+  React.useEffect(() => {
+    if (!chrome.visible) {
+      setBannerHeight(0);
+      return;
+    }
+    if (suppressed) return;
+    if (!chromeShown && !isError) {
+      setBannerHeight(0);
+      return;
+    }
+    if (barHeight > 0) {
+      setBannerHeight(barHeight);
+    }
+  }, [barHeight, chrome.visible, chromeShown, isError, setBannerHeight, suppressed]);
+
+  React.useEffect(() => {
+    if (!chrome.visible || suppressed || isError) {
+      doubleTapMonitor.set(null);
+      return;
+    }
+    doubleTapMonitor.set({
+      onDoubleTap: () => {
+        setShowOnboarding(false);
+        setChromeShown((shown) => !shown);
+      },
+    });
+    return () => {
+      doubleTapMonitor.set(null);
+    };
+  }, [chrome.visible, isError, suppressed]);
+
+  React.useEffect(() => {
+    onConfirmingChange?.(showDialog);
+  }, [showDialog, onConfirmingChange]);
+
+  React.useEffect(() => {
+    return () => {
+      onConfirmingChange?.(false);
+    };
+  }, [onConfirmingChange]);
+
+  const onMeasureHeight = React.useCallback((height: number) => {
+    setBarHeight(Math.max(0, height));
+  }, []);
+
+  const onLeftPress = React.useCallback(() => {
+    if (isError) {
+      onExit();
+      return;
+    }
+    setConfirming('exit');
+  }, [isError, onExit]);
+
+  const onRightPress = React.useCallback(() => {
+    if (isError || !state.canRestartPreview) return;
+    setConfirming('restart');
+  }, [isError, state.canRestartPreview]);
+
+  const closeDialog = React.useCallback(() => {
+    setConfirming(null);
+  }, []);
+
+  const confirmExit = React.useCallback(() => {
+    setConfirming(null);
+    onExit();
+  }, [onExit]);
+
+  const confirmRestart = React.useCallback(() => {
+    setConfirming(null);
+    onRestart?.();
+  }, [onRestart]);
 
-  const needsRescan = state.needsRescan;
-  // No pairing id means the session never started (e.g. init failed), so
-  // "Pairing ended" would misdescribe it.
-  const neverPaired = state.status === 'error' && !state.previewActive && state.pairingId === null;
-  const title = neverPaired
-    ? 'Preview unavailable'
-    : needsRescan
-      ? 'Pairing ended'
-      : 'Preview mode';
-  const detail =
-    state.lastError ??
-    (state.status === 'reconnecting'
-      ? 'Reconnecting…'
-      : state.status === 'connecting'
-        ? 'Connecting to Builder…'
-        : // Mirrors the Builder's own wording. Without this the banner reads
-          // "Paired" while the flow is absent, which looks like a broken preview
-          // rather than a condition that has not matched yet.
-          state.awaitingStartCondition
-          ? 'Waiting for auto-start condition to trigger…'
-          : 'Paired with Userflow Builder');
+  if (!barMounted && !showDialog) return null;
+
+  const tooltipVisible = visible && showOnboarding && !isError && !showDialog;
 
   return (
-    <View style={styles.wrap} pointerEvents="box-none">
-      <View style={[styles.banner, needsRescan ? styles.bannerWarn : styles.bannerActive]}>
-        <View style={styles.textCol}>
-          <Text style={styles.title}>{title}</Text>
-          <Text style={styles.detail} numberOfLines={2}>
-            {needsRescan ? `${detail} Re-scan the QR code to continue.` : detail}
-          </Text>
-        </View>
-        {!needsRescan ? (
-          <Pressable
-            accessibilityRole="button"
+    <View
+      accessibilityViewIsModal={showDialog}
+      pointerEvents="box-none"
+      style={[styles.wrap, showDialog ? styles.wrapConfirming : null]}
+      testID="userflow-preview-banner"
+    >
+      {showDialog && confirming === 'exit' ? (
+        // Dialog first so its scrim paints under the bar (Figma: Overlay then Button Sheet).
+        <ChromeDialog
+          body="You will need to pair your device again in Userflow to preview this flow."
+          onClose={closeDialog}
+          title="Exit preview mode?"
+        >
+          <ChromeButton
+            accessibilityLabel="Cancel"
+            flex
+            label="Cancel"
+            onPress={closeDialog}
+            testID="userflow-preview-exit-cancel"
+            variant="secondary"
+          />
+          <ChromeButton
             accessibilityLabel="Exit preview"
-            onPress={onExit}
-            style={styles.button}
+            flex
+            icon="arrow-left-from-bracket"
+            label="Exit"
+            onPress={confirmExit}
+            testID="userflow-preview-exit-confirm"
+          />
+        </ChromeDialog>
+      ) : null}
+      {showDialog && confirming === 'restart' ? (
+        <ChromeDialog
+          body="This will restart the flow from the first step."
+          onClose={closeDialog}
+          title="Restart flow?"
+        >
+          <ChromeButton
+            accessibilityLabel="Cancel"
+            flex
+            label="Cancel"
+            onPress={closeDialog}
+            testID="userflow-preview-restart-cancel"
+            variant="secondary"
+          />
+          <ChromeButton
+            accessibilityLabel="Restart flow"
+            flex
+            icon="arrow-rotate-left"
+            label="Restart"
+            onPress={confirmRestart}
+            testID="userflow-preview-restart-confirm"
+          />
+        </ChromeDialog>
+      ) : null}
+      {barMounted && barChrome ? (
+        <ChromeBarTransition edge="top" pointerEvents="box-none" visible={visible}>
+          <ChromeTopBar
+            accessibilityElementsHidden={showDialog}
+            importantForAccessibility={showDialog ? 'no-hide-descendants' : undefined}
+            label={barChrome.label}
+            numberOfLines={barChrome.numberOfLines}
+            onMeasureHeight={onMeasureHeight}
+            tone={barChrome.tone}
+            left={
+              <ChromeButton
+                accessibilityLabel={isError ? 'Dismiss pairing message' : 'Exit preview'}
+                icon="arrow-left-from-bracket"
+                onPress={onLeftPress}
+                testID="userflow-preview-exit"
+                variant="icon"
+              />
+            }
+            right={
+              showRestart ? (
+                <ChromeButton
+                  accessibilityLabel="Restart flow"
+                  icon="arrow-rotate-left"
+                  onPress={onRightPress}
+                  testID="userflow-preview-restart"
+                  variant="icon"
+                />
+              ) : undefined
+            }
+          />
+        </ChromeBarTransition>
+      ) : null}
+      {tooltipVisible ? (
+        <View pointerEvents="none" style={[styles.tooltip, { top: barHeight }]}>
+          <ChromeTooltip
+            onDismiss={() => {
+              setShowOnboarding(false);
+            }}
           >
-            <Text style={styles.buttonLabel}>Exit preview</Text>
-          </Pressable>
-        ) : (
-          <Pressable
-            accessibilityRole="button"
-            accessibilityLabel="Dismiss pairing message"
-            onPress={onExit}
-            style={styles.button}
-          >
-            <Text style={styles.buttonLabel}>Dismiss</Text>
-          </Pressable>
-        )}
-      </View>
+            {ONBOARDING_COPY}
+          </ChromeTooltip>
+        </View>
+      ) : null}
     </View>
   );
 }
@@ -85,46 +271,16 @@ const styles = StyleSheet.create({
     top: 0,
     left: 0,
     right: 0,
+    bottom: 0,
     zIndex: 1000,
   },
-  banner: {
-    marginTop: 48,
-    marginHorizontal: 12,
-    borderRadius: 10,
-    paddingHorizontal: 12,
-    paddingVertical: 10,
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: 10,
-  },
-  bannerActive: {
-    backgroundColor: 'rgba(17, 24, 39, 0.92)',
-  },
-  bannerWarn: {
-    backgroundColor: 'rgba(127, 29, 29, 0.94)',
-  },
-  textCol: {
-    flex: 1,
+  wrapConfirming: {
+    zIndex: 1200,
   },
-  title: {
-    color: '#ffffff',
-    fontSize: 13,
-    fontWeight: '700',
-  },
-  detail: {
-    color: 'rgba(255,255,255,0.85)',
-    fontSize: 12,
-    marginTop: 2,
-  },
-  button: {
-    paddingHorizontal: 10,
-    paddingVertical: 8,
-    borderRadius: 8,
-    backgroundColor: 'rgba(255,255,255,0.14)',
-  },
-  buttonLabel: {
-    color: '#ffffff',
-    fontSize: 12,
-    fontWeight: '600',
+  tooltip: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    alignItems: 'center',
   },
 });

package/src/pairing/diagnostics.ts

@@ -66,6 +66,14 @@ export function pairingConnectFailedMessage(reason: string): string {
   );
 }
 
+/**
+ * Engine-reported pairing failure (`lastError`). The preview top bar no longer
+ * has a second line for this, so it must reach Metro under the `[Userflow]` prefix.
+ */
+export function pairingPreviewErrorMessage(reason: string): string {
+  return `${PREFIX} Builder pairing: ${reason}`;
+}
+
 /** A pairing link arrived without the `pairing_token` query parameter. */
 export function pairingMissingTokenMessage(url: string): string {
   return (
@@ -85,7 +93,7 @@ export function pairingForeignSchemeMessage(url: string): string {
     `link, but it was opened with a scheme Userflow does not own. Use your ` +
     `environment's scheme_id ("userflow-" followed by digits) exactly as the ` +
     `pairing QR code provides it — do not substitute your app's own scheme. ` +
-    `Register it via the @userflow-tech/expo plugin ({ schemeId: 'userflow-…' }) and ` +
+    `Register it via the @userflow-tech/react-native plugin ({ schemeId: 'userflow-…' }) and ` +
     `rebuild the native app; a Metro reload is not enough.`
   );
 }
@@ -130,6 +138,6 @@ export function pairingSchemeShapeMessage(url: string): string {
   return (
     `${PREFIX} Ignoring Builder pairing link "${redactPairingToken(url)}": the scheme must be your ` +
     `environment's scheme_id — "userflow-" followed by digits (e.g. userflow-257587). ` +
-    `Check the schemeId passed to the @userflow-tech/expo plugin.`
+    `Check the schemeId passed to the @userflow-tech/react-native plugin.`
   );
 }

package/src/pairing/elementPickerRelay.ts

@@ -0,0 +1,100 @@
+import { isPairingPushAckTimeout } from '@userflow-tech/core';
+import type { PairingRelayEvent } from '@userflow-tech/protocol';
+
+import {
+  elementPickerController,
+  type ElementPickerResult,
+} from '../authoring/elementPickerController';
+
+export interface ElementPickerRelayEngine {
+  onRelay: (handler: (event: PairingRelayEvent, payload: unknown) => void) => () => void;
+  sendRelay: (event: PairingRelayEvent, payload: unknown) => Promise<unknown>;
+}
+
+function asRecord(payload: unknown): Record<string, unknown> {
+  return payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {};
+}
+
+function idempotencyKeyOf(payload: unknown): string | null {
+  const key = asRecord(payload)['idempotency_key'];
+  return typeof key === 'string' && key.length > 0 ? key : null;
+}
+
+function resultPayload(key: string, result: ElementPickerResult): Record<string, unknown> {
+  return {
+    idempotency_key: key,
+    ok: true,
+    autoData: result.autoData,
+    text: result.text ?? null,
+    ...(result.screenshot
+      ? {
+          screenshot: {
+            dataUrl: result.screenshot.dataUrl,
+            width: result.screenshot.width,
+            height: result.screenshot.height,
+            targetX1: result.screenshot.targetX1,
+            targetY1: result.screenshot.targetY1,
+            targetX2: result.screenshot.targetX2,
+            targetY2: result.screenshot.targetY2,
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * Bridge pairing-channel `selectElement*` events onto {@link elementPickerController}.
+ * UI-free: the overlay (and QA harness) own the actual picking.
+ */
+export function bindElementPickerRelay(engine: ElementPickerRelayEngine): () => void {
+  if (typeof engine.onRelay !== 'function' || typeof engine.sendRelay !== 'function') {
+    return () => undefined;
+  }
+  let ignoreNextCancelSend = false;
+
+  /** Result delivery: ignore ack timeouts; surface connection failures. */
+  const sendResult = async (key: string, result: ElementPickerResult): Promise<void> => {
+    try {
+      await engine.sendRelay('selectElementResult', resultPayload(key, result));
+    } catch (error) {
+      if (typeof isPairingPushAckTimeout === 'function' && isPairingPushAckTimeout(error)) {
+        return;
+      }
+      throw error;
+    }
+  };
+
+  /** Cancel is best-effort: ignore timeout and disconnect. */
+  const sendCancel = (key: string): void => {
+    void engine.sendRelay('selectElementCancel', { idempotency_key: key }).catch(() => undefined);
+  };
+
+  const unsub = engine.onRelay((event, payload) => {
+    if (event === 'selectElement') {
+      const key = idempotencyKeyOf(payload);
+      if (!key) return;
+      elementPickerController.beginSelection({
+        requestId: key,
+        onResult: (result) => sendResult(key, result),
+        onCancel: () => {
+          if (ignoreNextCancelSend) return;
+          sendCancel(key);
+        },
+      });
+      return;
+    }
+
+    if (event === 'selectElementCancel') {
+      ignoreNextCancelSend = true;
+      elementPickerController.cancel();
+      ignoreNextCancelSend = false;
+    }
+  });
+
+  return () => {
+    unsub();
+    ignoreNextCancelSend = true;
+    elementPickerController.cancel();
+    ignoreNextCancelSend = false;
+  };
+}