@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/pairing/PairingController.ts

@@ -2,13 +2,17 @@ import {
   DEFAULT_PAIRING_ENDPOINT,
   PairingEngine,
   type PairingEngineState,
+  type PairingPurpose,
   type UserflowCore,
 } from '@userflow-tech/core';
+import { decodePairingJwt, isPairingJwtExpired } from '@userflow-tech/protocol';
 import { AppState, type AppStateStatus, Linking, Platform } from 'react-native';
 
 import { clearFiberAnchorCache } from '../anchors/fiberAnchorCache';
+import { evalJsController } from '../evalJs/evalJsController';
 
 import { inspectPairingDeepLink, isPairingAttempt } from './deepLink';
+import { getOrCreatePairingDeviceId } from './deviceId';
 import {
   defaultPairingLogger,
   pairingAttemptRejectionMessage,
@@ -42,6 +46,13 @@ export interface PairingControllerOptions {
   tokenStore?: PairingTokenStore;
   /** Clear mid-flow session when exiting preview. */
   clearLocalSession?: () => void;
+  /** End the previewed draft on the server when exiting preview. */
+  endDraftSession?: () => Promise<void>;
+  /**
+   * Drop an end that is waiting for a draft identify has not delivered.
+   * A new preview must call this so that draft is not ended when it arrives.
+   */
+  cancelPendingDraftEnd?: () => void;
   LinkingModule?: {
     getInitialURL(): Promise<string | null>;
     addEventListener(type: 'url', handler: (event: { url: string }) => void): { remove(): void };
@@ -51,6 +62,11 @@ export interface PairingControllerOptions {
   };
   /** Sink for pairing diagnostics. Injected in tests. */
   logger?: PairingLogger;
+  /**
+   * Stable pairing device id. Defaults to the persisted install id.
+   * Injected in tests.
+   */
+  deviceIdProvider?: () => Promise<string>;
 }
 
 /**
@@ -68,13 +84,33 @@ export class PairingController {
   private readonly LinkingModule: NonNullable<PairingControllerOptions['LinkingModule']>;
   private readonly AppStateModule: NonNullable<PairingControllerOptions['AppStateModule']>;
   private readonly clearLocalSession: (() => void) | undefined;
+  private readonly endDraftSession: (() => Promise<void>) | undefined;
+  private readonly cancelPendingDraftEnd: (() => void) | undefined;
   private readonly core: UserflowCore;
   private readonly pairingEndpoint: string;
   private readonly logger: PairingLogger;
+  private readonly deviceIdProvider: () => Promise<string>;
+  private pairingDeviceId: string | null = null;
+  /** A link or resume already claimed this launch, so a stored token must not. */
+  private acceptedPairingToken = false;
+  /**
+   * Bumped by exitPreview. An in-flight resume or connect checks it after
+   * every await and does not write the token or leave the socket up.
+   */
+  private launchEpoch = 0;
+  /** Latest enterPreview. An older attempt must not clear a newer token. */
+  private enterAttempt = 0;
+  /**
+   * Orders token and purpose writes. Two scans can overlap on the awaits, and
+   * the slower one's purpose must not land on the token the faster one saved.
+   */
+  private previewSaveQueue: Promise<void> = Promise.resolve();
   private initPhase: InitPhase = 'ready';
   private initFailureReason: string | null = null;
   /** Pairing token captured before init resolved, replayed once it does. */
   private deferredPairingToken: string | null = null;
+  /** Purpose of {@link deferredPairingToken}, so the held banner already honours it. */
+  private deferredPurpose: PairingPurpose | null = null;
   /** Diagnostics already emitted for the current init attempt. */
   private readonly loggedOnce = new Set<string>();
   private relayUnsub: (() => void) | null = null;
@@ -86,7 +122,10 @@ export class PairingController {
     this.LinkingModule = options.LinkingModule ?? Linking;
     this.AppStateModule = options.AppStateModule ?? AppState;
     this.clearLocalSession = options.clearLocalSession ?? undefined;
+    this.endDraftSession = options.endDraftSession ?? undefined;
+    this.cancelPendingDraftEnd = options.cancelPendingDraftEnd ?? undefined;
     this.logger = options.logger ?? defaultPairingLogger;
+    this.deviceIdProvider = options.deviceIdProvider ?? getOrCreatePairingDeviceId;
   }
 
   getEngine(): PairingEngine | null {
@@ -101,6 +140,8 @@ export class PairingController {
   getState(): PairingEngineState {
     const blocked = this.blockedState();
     if (blocked) return blocked;
+    const held = this.heldState();
+    if (held) return held;
 
     return (
       this.engine?.getState() ?? {
@@ -113,6 +154,8 @@ export class PairingController {
         awaitingStartCondition: false,
         canRestartPreview: false,
         previewRestartGeneration: 0,
+        pairingSessionGeneration: 0,
+        previewStartGeneration: 0,
       }
     );
   }
@@ -136,6 +179,31 @@ export class PairingController {
       awaitingStartCondition: false,
       canRestartPreview: false,
       previewRestartGeneration: 0,
+      pairingSessionGeneration: 0,
+      previewStartGeneration: 0,
+    };
+  }
+
+  /**
+   * A link or resumed token is waiting for init. Report connecting so the
+   * banner is visible during credential validation instead of looking idle.
+   */
+  private heldState(): PairingEngineState | null {
+    if (this.initPhase !== 'pending' || this.deferredPairingToken === null) return null;
+
+    return {
+      status: 'connecting',
+      pairingId: null,
+      deviceId: this.pairingDeviceId,
+      previewActive: true,
+      lastError: null,
+      needsRescan: false,
+      awaitingStartCondition: false,
+      canRestartPreview: false,
+      previewRestartGeneration: 0,
+      pairingSessionGeneration: 0,
+      previewStartGeneration: 0,
+      ...(this.deferredPurpose ? { pairingPurpose: this.deferredPurpose } : {}),
     };
   }
 
@@ -163,15 +231,6 @@ export class PairingController {
   }
 
   private async startListening(): Promise<void> {
-    // Exit pairing on app restart: drop any leftover secure token. Guarded so a
-    // storage failure cannot cost us the listeners registered below — losing
-    // those is what makes an inbound QR link vanish without explanation.
-    try {
-      await this.tokenStore.clear();
-    } catch (error) {
-      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
-    }
-
     this.ensureEngine();
 
     this.urlSub = this.LinkingModule.addEventListener('url', ({ url }) => {
@@ -195,6 +254,58 @@ export class PairingController {
     } catch {
       // Linking may throw on some platforms before the native module is ready.
     }
+
+    // A launch URL already claimed this process. Do not also resume storage.
+    if (this.acceptedPairingToken) return;
+    await this.resumeStoredToken();
+  }
+
+  /**
+   * Rejoin the Builder session after a relaunch when no new pairing link won.
+   * An expired or undecodable token is cleared so the next launch stays idle.
+   */
+  private async resumeStoredToken(): Promise<void> {
+    const epoch = this.launchEpoch;
+    let stored: string | null;
+    try {
+      stored = await this.tokenStore.get();
+    } catch (error) {
+      this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+      return;
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken || !stored) return;
+
+    const claims = decodePairingJwt(stored);
+    if (!claims || isPairingJwtExpired(claims)) {
+      // A link that arrived while we were reading storage owns the session.
+      if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+      try {
+        const current = await this.tokenStore.get();
+        if (epoch !== this.launchEpoch || this.acceptedPairingToken || current !== stored) return;
+        await this.tokenStore.clear();
+      } catch (error) {
+        this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+      }
+      return;
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+
+    let purpose: PairingPurpose | null = null;
+    try {
+      purpose = (await this.tokenStore.getPurpose?.()) ?? null;
+    } catch {
+      // Resume without it; the banner falls back to its default reveal.
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+
+    try {
+      await this.connectWhenReady(stored, 'resume', purpose);
+    } catch (error) {
+      this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+    }
   }
 
   stop(): void {
@@ -227,21 +338,42 @@ export class PairingController {
       return true;
     }
 
+    await this.connectWhenReady(
+      inspected.link.pairingToken,
+      'link',
+      inspected.link.purpose ?? null,
+    );
+    return true;
+  }
+
+  /**
+   * Connect now, or hold the token until init resolves or fails. Links and
+   * resumed sessions share this gate so both are deferred, replayed, and
+   * shown the same way.
+   */
+  private async connectWhenReady(
+    token: string,
+    source: 'link' | 'resume' = 'link',
+    purpose: PairingPurpose | null = null,
+  ): Promise<void> {
+    this.acceptedPairingToken = true;
+
     if (this.initPhase !== 'ready') {
       // Hold the token rather than discarding it. `notifyInitialized` replays it;
       // `notifyInitFailed` turns it into visible state.
-      this.deferredPairingToken = inspected.link.pairingToken;
-      this.warnOnce(
-        this.initPhase === 'failed'
-          ? pairingLinkInitFailedMessage(this.initFailureReason ?? 'unknown error')
-          : pairingLinkDeferredMessage(),
-      );
-      if (this.initPhase === 'failed') this.emit(this.getState());
-      return true;
+      this.deferredPairingToken = token;
+      this.deferredPurpose = purpose;
+      if (this.initPhase === 'failed') {
+        this.warnOnce(pairingLinkInitFailedMessage(this.initFailureReason ?? 'unknown error'));
+      } else if (source === 'link') {
+        // A resume waits on init on every relaunch; only a link needs this note.
+        this.warnOnce(pairingLinkDeferredMessage());
+      }
+      this.emit(this.getState());
+      return;
     }
 
-    await this.enterPreview(inspected.link.pairingToken);
-    return true;
+    await this.enterPreview(token, purpose);
   }
 
   /**
@@ -259,8 +391,9 @@ export class PairingController {
   }
 
   /**
-   * Called when `Userflow.init()` resolves. Connects a link that arrived while
-   * init was still in flight.
+   * Called when `Userflow.init()` resolves. Connects a link or resumed session
+   * that arrived while init was still in flight. `Userflow.init` does not await
+   * this — the pairing socket must not block identify.
    */
   async notifyInitialized(): Promise<void> {
     this.initPhase = 'ready';
@@ -268,14 +401,17 @@ export class PairingController {
 
     const deferred = this.deferredPairingToken;
     if (deferred === null) return;
+    const purpose = this.deferredPurpose;
     this.deferredPairingToken = null;
+    this.deferredPurpose = null;
 
     try {
-      await this.enterPreview(deferred);
+      await this.enterPreview(deferred, purpose);
     } catch (error) {
-      // Preview must not fail host init. `Userflow.init` awaits this, and
-      // PairingEngine.start rethrows on every connect failure, so letting this
-      // escape would let an expired QR token fail the host app's entire init.
+      // Preview must not fail host init. `Userflow.init` does not await this,
+      // and PairingEngine.start rethrows on every connect failure, so letting
+      // this escape would be an unhandled rejection — and, if it were awaited,
+      // an expired QR token would fail the host app's entire init.
       this.warnOnce(pairingConnectFailedMessage(describeError(error)));
     }
   }
@@ -305,17 +441,128 @@ export class PairingController {
   }
 
   /** Explicit entry with a raw pairing JWT (tests / advanced hosts). */
-  async enterPreview(pairingToken: string): Promise<void> {
+  async enterPreview(pairingToken: string, purpose: PairingPurpose | null = null): Promise<void> {
+    const epoch = this.launchEpoch;
+    const attempt = ++this.enterAttempt;
     const engine = this.ensureEngine();
-    await this.tokenStore.set(pairingToken);
-    await engine.start(pairingToken);
+    // Before the first await, so an exit that runs later still arms its own end.
+    if (epoch === this.launchEpoch) this.cancelPendingDraftEnd?.();
+
+    const deviceId = await this.resolveDeviceId();
+    if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) return;
+
+    this.pairingDeviceId = deviceId;
+    const saved = await this.savePreviewCredentials(pairingToken, purpose, attempt, epoch);
+    if (!saved) return;
+
+    try {
+      await (purpose ? engine.start(pairingToken, { purpose }) : engine.start(pairingToken));
+    } catch (error) {
+      // A newer pair owns the engine now. Stopping here would drop it.
+      if (attempt !== this.enterAttempt) return;
+      if (epoch !== this.launchEpoch) {
+        // start() records a connect failure after stop() has already gone idle.
+        await this.discardPreviewToken(pairingToken, attempt);
+        this.engine?.stop();
+        return;
+      }
+      throw error;
+    }
+
+    if (attempt !== this.enterAttempt) return;
+    if (epoch !== this.launchEpoch) {
+      await this.discardPreviewToken(pairingToken, attempt);
+      this.engine?.stop();
+    }
+  }
+
+  /**
+   * Write the token and its purpose as one attempt. Writes are queued so an
+   * older scan cannot finish its purpose after a newer scan has saved its own.
+   * Returns false when this attempt lost the race; storage then still belongs
+   * to whoever connected, or is cleared if this attempt was the last writer.
+   */
+  private async savePreviewCredentials(
+    pairingToken: string,
+    purpose: PairingPurpose | null,
+    attempt: number,
+    epoch: number,
+  ): Promise<boolean> {
+    const previous = this.previewSaveQueue;
+    let release: () => void = () => undefined;
+    this.previewSaveQueue = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    try {
+      await previous;
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) return false;
+
+      await this.tokenStore.set(pairingToken);
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) {
+        await this.revertPreviewCredentials(pairingToken);
+        return false;
+      }
+
+      await this.tokenStore.setPurpose?.(purpose);
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) {
+        await this.revertPreviewCredentials(pairingToken);
+        return false;
+      }
+      return true;
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Drop credentials this attempt wrote, when they are still the ones stored.
+   * A newer scan may already have replaced them; those stay.
+   */
+  private async revertPreviewCredentials(pairingToken: string): Promise<void> {
+    try {
+      const current = await this.tokenStore.get();
+      if (current !== pairingToken) return;
+      await this.tokenStore.clear();
+    } catch (error) {
+      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+    }
+  }
+
+  /**
+   * Remove the token this attempt wrote. A newer pair may already have
+   * replaced it; that token stays.
+   */
+  private async discardPreviewToken(pairingToken: string, attempt: number): Promise<void> {
+    if (attempt !== this.enterAttempt) return;
+    try {
+      const current = await this.tokenStore.get();
+      if (attempt !== this.enterAttempt || current !== pairingToken) return;
+      await this.tokenStore.clear();
+    } catch (error) {
+      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+    }
+  }
+
+  private async resolveDeviceId(): Promise<string> {
+    if (this.pairingDeviceId !== null) return this.pairingDeviceId;
+    return this.deviceIdProvider();
   }
 
   async exitPreview(): Promise<void> {
     // Drop any held link too, so dismissing a blocked banner actually clears it.
+    // Bump before the awaits so a resume still reading storage does not reconnect.
+    this.launchEpoch += 1;
+    evalJsController.reset();
     this.deferredPairingToken = null;
+    this.deferredPurpose = null;
     await this.tokenStore.clear();
     this.engine?.stop();
+    // Not awaited: the local clear is synchronous, and the banner must not wait
+    // on the end-user socket.
+    void this.endDraftSession?.().catch((error: unknown) => {
+      this.warnOnce(pairingPreviewErrorMessage(describeError(error)));
+    });
     this.clearLocalSession?.();
     this.emit(this.getState());
   }
@@ -327,6 +574,7 @@ export class PairingController {
   async restartPreview(): Promise<boolean> {
     if (!this.engine) return false;
     clearFiberAnchorCache();
+    evalJsController.reset();
     return this.engine.restartPreview();
   }
 
@@ -343,7 +591,13 @@ 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.pairingDeviceId !== null ? { device_id: this.pairingDeviceId } : {}),
+      }),
+      onBeforePreviewStart: () => {
+        this.clearLocalSession?.();
+      },
     });
 
     this.engine.onStateChange((state) => {

package/src/pairing/PreviewModeBanner.tsx

@@ -16,6 +16,8 @@ type VisiblePreviewChrome = Extract<PreviewChrome, { visible: true }>;
 type ConfirmingKind = 'exit' | 'restart';
 
 const ONBOARDING_COPY = 'Double tap anywhere to access the menu';
+/** A short blip stays quiet. Longer than this, the hidden bar comes back until the socket recovers. */
+export const RECONNECT_REVEAL_DELAY_MS = 2000;
 
 export interface PreviewModeBannerProps {
   state: PairingEngineState;
@@ -25,6 +27,12 @@ export interface PreviewModeBannerProps {
   onConfirmingChange?: (open: boolean) => void;
   /** Hide the preview bar while the element picker is using the same top slot. */
   suppressed?: boolean | undefined;
+  /**
+   * Hide default-tone chrome without giving the top slot to the picker.
+   * Error tone still shows. Set for the brief intro after a new pairing and
+   * for the stretch after element selection until the Builder starts a preview.
+   */
+  held?: boolean | undefined;
 }
 
 /**
@@ -36,15 +44,20 @@ export function PreviewModeBanner({
   onRestart,
   onConfirmingChange,
   suppressed = false,
+  held = false,
 }: PreviewModeBannerProps): React.ReactElement | 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 [reconnectRevealed, setReconnectRevealed] = React.useState(false);
+  const reconnectRevealedRef = React.useRef(reconnectRevealed);
+  reconnectRevealedRef.current = reconnectRevealed;
+  const armedGenerationRef = React.useRef<number | null>(null);
   const isError = chrome.visible && chrome.tone === 'error';
-  const visible = chrome.visible && !suppressed && (chromeShown || isError);
+  const visible =
+    chrome.visible && !suppressed && (isError || (!held && (chromeShown || reconnectRevealed)));
   const [confirming, setConfirming] = React.useState<ConfirmingKind | null>(null);
   const showRestart = Boolean(state.canRestartPreview) && !isError;
   const showDialog = confirming != null && visible && !isError;
@@ -59,10 +72,11 @@ export function PreviewModeBanner({
 
   React.useEffect(() => {
     if (!chrome.visible) {
-      sessionArmedRef.current = false;
+      armedGenerationRef.current = null;
       setChromeShown(true);
       setShowOnboarding(false);
       setBarHeight(0);
+      setReconnectRevealed(false);
       return;
     }
     if (isError) {
@@ -70,11 +84,26 @@ export function PreviewModeBanner({
       setShowOnboarding(false);
       return;
     }
-    if (!sessionArmedRef.current) {
-      sessionArmedRef.current = true;
+    if (armedGenerationRef.current !== state.pairingSessionGeneration) {
+      armedGenerationRef.current = state.pairingSessionGeneration;
+      setChromeShown(true);
       setShowOnboarding(true);
     }
-  }, [chrome.visible, isError]);
+  }, [chrome.visible, isError, state.pairingSessionGeneration]);
+
+  React.useEffect(() => {
+    if (!chrome.visible || held || state.status !== 'reconnecting') return;
+    const timer = setTimeout(() => setReconnectRevealed(true), RECONNECT_REVEAL_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, [chrome.visible, held, state.status]);
+
+  React.useEffect(() => {
+    if (chrome.visible && state.status === 'reconnecting') return;
+    // An exit dialog opened from the revealed bar must survive recovery.
+    // Dropping the reveal immediately would unmount that dialog.
+    if (chrome.visible && confirming != null) return;
+    setReconnectRevealed(false);
+  }, [chrome.visible, confirming, state.status]);
 
   React.useEffect(() => {
     if (!visible || isError) {
@@ -92,30 +121,56 @@ export function PreviewModeBanner({
       return;
     }
     if (suppressed) return;
-    if (!chromeShown && !isError) {
+    // Held chrome is absent, and nothing else is reporting this slot. An error
+    // bar still shows, so it keeps the inset.
+    if (held && !isError) {
+      setBannerHeight(0);
+      return;
+    }
+    if (!chromeShown && !isError && !reconnectRevealed) {
       setBannerHeight(0);
       return;
     }
     if (barHeight > 0) {
       setBannerHeight(barHeight);
     }
-  }, [barHeight, chrome.visible, chromeShown, isError, setBannerHeight, suppressed]);
+  }, [
+    barHeight,
+    chrome.visible,
+    chromeShown,
+    held,
+    isError,
+    reconnectRevealed,
+    setBannerHeight,
+    suppressed,
+  ]);
 
   React.useEffect(() => {
-    if (!chrome.visible || suppressed || isError) {
-      doubleTapMonitor.set(null);
+    // Navigate-mode picking uses this same singleton. Only drop the subscription
+    // we installed — set(null) here would clear that owner when pairing chrome
+    // changes while this bar is already suppressed.
+    if (!chrome.visible || suppressed || isError || held) {
       return;
     }
-    doubleTapMonitor.set({
+    const subscription = {
       onDoubleTap: () => {
         setShowOnboarding(false);
+        // The reveal keeps the bar up regardless of chromeShown, so toggling
+        // chromeShown alone would look like a no-op and then pin the bar on
+        // after recovery. A double tap on a revealed bar hides it.
+        if (reconnectRevealedRef.current) {
+          setReconnectRevealed(false);
+          setChromeShown(false);
+          return;
+        }
         setChromeShown((shown) => !shown);
       },
-    });
+    };
+    doubleTapMonitor.set(subscription);
     return () => {
-      doubleTapMonitor.set(null);
+      doubleTapMonitor.clearIfCurrent(subscription);
     };
-  }, [chrome.visible, isError, suppressed]);
+  }, [chrome.visible, held, isError, suppressed]);
 
   React.useEffect(() => {
     onConfirmingChange?.(showDialog);
@@ -253,8 +308,10 @@ export function PreviewModeBanner({
       {tooltipVisible ? (
         <View pointerEvents="none" style={[styles.tooltip, { top: barHeight }]}>
           <ChromeTooltip
+            key={state.pairingSessionGeneration}
             onDismiss={() => {
               setShowOnboarding(false);
+              setChromeShown(false);
             }}
           >
             {ONBOARDING_COPY}

package/src/pairing/deepLink.ts

@@ -1,18 +1,35 @@
+import type { PairingPurpose } from '@userflow-tech/core';
+
 /**
  * Parse Builder pairing deep links:
- *   {scheme_id}://?pairing_token=<jwt>
+ *   {scheme_id}://?pairing_token=<jwt>[&purpose=preview|select_element]
  *
- * `scheme_id` is typically `userflow-<digits>`.
+ * `scheme_id` is `userflow-` followed by an opaque, backend-generated id.
  */
 
 export interface PairingDeepLink {
   scheme: string;
   pairingToken: string;
+  /** Absent when the link has no `purpose`, or one this SDK does not know. */
+  purpose?: PairingPurpose;
+}
+
+const PAIRING_PURPOSES: readonly PairingPurpose[] = ['preview', 'select_element'];
+
+export function parsePairingPurpose(value: string | null | undefined): PairingPurpose | null {
+  return PAIRING_PURPOSES.find((purpose) => purpose === value) ?? null;
 }
 
 /** Scheme prefix shared by preview and pairing links. */
 const USERFLOW_SCHEME_PREFIX = 'userflow-';
-const USERFLOW_SCHEME = /^userflow-\d+$/i;
+/**
+ * Environment scheme_id shape — must match Expo plugin registration
+ * (`packages/expo/plugin/withUserflow.ts`). Everything after `userflow-` is an
+ * opaque id owned by the backend (today 26 base32 chars), so only check that it
+ * is one or more alphanumeric segments joined by single hyphens. Digit-only ids
+ * used in local configs also pass.
+ */
+const USERFLOW_SCHEME = /^userflow-[a-z0-9]+(?:-[a-z0-9]+)*$/i;
 
 /**
  * Why a URL was not treated as a pairing link.
@@ -105,12 +122,13 @@ export function inspectPairingDeepLink(url: string | null | undefined): PairingD
   if (!isPair) return { ok: false, reason: 'not-pair-path' };
 
   // Only once the URL is known to target pairing does the scheme shape matter.
-  // Checking it earlier would misreport preview links on non-numeric schemes.
+  // Checking it earlier would misreport preview links on malformed schemes.
   if (!USERFLOW_SCHEME.test(scheme)) return { ok: false, reason: 'bad-scheme-shape' };
 
   if (!pairingToken) return { ok: false, reason: 'missing-token' };
 
-  return { ok: true, link: { scheme, pairingToken } };
+  const purpose = parsePairingPurpose(parsed.searchParams.get('purpose'));
+  return { ok: true, link: { scheme, pairingToken, ...(purpose ? { purpose } : {}) } };
 }
 
 /**