@userflow-tech/react-native 0.2.0 → 0.3.1

package/src/pairing/deviceId.ts

@@ -0,0 +1,46 @@
+import { uuid } from '../anonymousId';
+import { getAsyncStorage } from '../storage/asyncStorage';
+
+/**
+ * Stable id for this install on the pairing channel.
+ *
+ * The server allows one device per pairing topic and only the same id may
+ * rejoin while the previous presence lingers. The id identifies the device,
+ * not the user, so `reset()` and `exitPreview()` must not clear it.
+ */
+export const PAIRING_DEVICE_ID_STORAGE_KEY = 'userflow:pairingDeviceId';
+
+let memoized: string | null = null;
+
+export async function getOrCreatePairingDeviceId(): Promise<string> {
+  if (memoized !== null) return memoized;
+
+  const storage = getAsyncStorage();
+  if (storage) {
+    try {
+      const stored = await storage.getItem(PAIRING_DEVICE_ID_STORAGE_KEY);
+      if (typeof stored === 'string' && stored.length > 0) {
+        memoized = stored;
+        return stored;
+      }
+    } catch {
+      memoized = uuid();
+      return memoized;
+    }
+  }
+
+  const created = uuid();
+  memoized = created;
+  if (!storage) return created;
+  try {
+    await storage.setItem(PAIRING_DEVICE_ID_STORAGE_KEY, created);
+  } catch {
+    // Keep the in-memory id for this process. A later launch may mint another.
+  }
+  return created;
+}
+
+/** @internal Clears the process memo so tests can simulate a new launch. */
+export function resetPairingDeviceIdForTests(): void {
+  memoized = null;
+}

package/src/pairing/diagnostics.ts

@@ -91,7 +91,7 @@ export function pairingForeignSchemeMessage(url: string): string {
   return (
     `${PREFIX} Ignoring "${redactPairingToken(url)}": this is a Builder pairing ` +
     `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 ` +
+    `environment's scheme_id ("userflow-" followed by its id) exactly as the ` +
     `pairing QR code provides it — do not substitute your app's own scheme. ` +
     `Register it via the @userflow-tech/react-native plugin ({ schemeId: 'userflow-…' }) and ` +
     `rebuild the native app; a Metro reload is not enough.`
@@ -131,13 +131,15 @@ export function pairingListenerSetupFailedMessage(reason: string): string {
 
 /**
  * The URL used a `userflow-` scheme that is not a valid `scheme_id`. Pairing
- * requires `userflow-` followed by digits, so an arbitrary `userflow-*` scheme
- * can match preview links but not pairing ones.
+ * requires `userflow-` followed by one or more alphanumeric segments joined by
+ * single hyphens. A malformed `userflow-*` scheme can match preview links but
+ * not pairing ones.
  */
 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). ` +
+    `environment's scheme_id — "userflow-" followed by letters and digits, optionally ` +
+    `split by single hyphens (e.g. userflow-v7twv2fw2ja2jaco7kesvowmem). ` +
     `Check the schemeId passed to the @userflow-tech/react-native plugin.`
   );
 }

package/src/pairing/tokenStorage.ts

@@ -1,14 +1,29 @@
 /**
- * Persist the pairing JWT for reconnect within the current app session.
- * Cleared on SDK init / exit preview / app restart (pairing exits on restart).
+ * Persist the pairing JWT so a relaunch can resume Builder pairing until the
+ * token expires or preview is exited. Resume requires `expo-secure-store`;
+ * the in-memory fallback does not survive a process restart.
  */
 
-const STORAGE_KEY = 'userflow:pairingToken';
+import type { PairingPurpose } from '@userflow-tech/core';
+
+import { parsePairingPurpose } from './deepLink';
+
+// SecureStore rejects keys outside [A-Za-z0-9._-], so no `userflow:` prefix here.
+export const PAIRING_TOKEN_STORAGE_KEY = 'userflow.pairingToken';
+export const PAIRING_PURPOSE_STORAGE_KEY = 'userflow.pairingPurpose';
 
 export interface PairingTokenStore {
   get(): Promise<string | null>;
   set(token: string): Promise<void>;
+  /** Clears the token and its purpose. */
   clear(): Promise<void>;
+  /**
+   * Purpose of the link that wrote the token, so a resume keeps the same
+   * preview chrome. Optional so custom stores keep working; a store without
+   * it resumes with no purpose.
+   */
+  getPurpose?(): Promise<PairingPurpose | null>;
+  setPurpose?(purpose: PairingPurpose | null): Promise<void>;
 }
 
 type SecureStoreModule = {
@@ -54,6 +69,7 @@ function tryLoadExpoSecureStore(): SecureStoreModule | null {
 /** In-memory store used when SecureStore is unavailable (and in tests). */
 export function createMemoryPairingTokenStore(): PairingTokenStore {
   let value: string | null = null;
+  let purposeValue: PairingPurpose | null = null;
   return {
     async get() {
       return value;
@@ -63,6 +79,13 @@ export function createMemoryPairingTokenStore(): PairingTokenStore {
     },
     async clear() {
       value = null;
+      purposeValue = null;
+    },
+    async getPurpose() {
+      return purposeValue;
+    },
+    async setPurpose(purpose: PairingPurpose | null) {
+      purposeValue = purpose;
     },
   };
 }
@@ -77,25 +100,55 @@ export function createPairingTokenStore(): PairingTokenStore {
   return {
     async get() {
       try {
-        return await secure.getItemAsync(STORAGE_KEY);
+        return await secure.getItemAsync(PAIRING_TOKEN_STORAGE_KEY);
       } catch {
         return null;
       }
     },
     async set(token: string) {
       try {
-        await secure.setItemAsync(STORAGE_KEY, token);
-      } catch {
+        await secure.setItemAsync(PAIRING_TOKEN_STORAGE_KEY, token);
+      } catch (error) {
         // Best-effort; reconnect still works from in-memory PairingEngine token.
+        if (__DEV__) {
+          // eslint-disable-next-line no-console -- intentional persistence diagnostic
+          console.warn(
+            '[Userflow] Could not save the pairing token, so preview will not resume after a relaunch:',
+            error instanceof Error ? error.message : String(error),
+          );
+        }
       }
     },
     async clear() {
       try {
-        await secure.deleteItemAsync(STORAGE_KEY);
+        await secure.deleteItemAsync(PAIRING_TOKEN_STORAGE_KEY);
+      } catch {
+        // ignore
+      }
+      try {
+        await secure.deleteItemAsync(PAIRING_PURPOSE_STORAGE_KEY);
       } catch {
         // ignore
       }
     },
+    async getPurpose() {
+      try {
+        return parsePairingPurpose(await secure.getItemAsync(PAIRING_PURPOSE_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    async setPurpose(purpose: PairingPurpose | null) {
+      try {
+        if (purpose) {
+          await secure.setItemAsync(PAIRING_PURPOSE_STORAGE_KEY, purpose);
+        } else {
+          await secure.deleteItemAsync(PAIRING_PURPOSE_STORAGE_KEY);
+        }
+      } catch {
+        // Best-effort; a resume without it falls back to the default reveal.
+      }
+    },
   };
 }
 

package/src/pairing/usePairingState.ts

@@ -14,6 +14,8 @@ const IDLE: PairingEngineState = {
   awaitingStartCondition: false,
   canRestartPreview: false,
   previewRestartGeneration: 0,
+  pairingSessionGeneration: 0,
+  previewStartGeneration: 0,
 };
 
 /** Subscribe to Builder pairing / preview-mode state (dev builds only). */

package/src/pairing/usePreviewBarHold.ts

@@ -0,0 +1,160 @@
+import type { PairingEngineState, PairingPurpose } from '@userflow-tech/core';
+import * as React from 'react';
+
+import { resolvePreviewChrome } from './resolvePreviewChrome';
+
+/**
+ * How long a new pairing session with no `purpose` on its link keeps the
+ * default preview bar hidden, so a `selectElement` that arrives after the join
+ * never flashes "Preview mode". Restarts once when the socket first reaches
+ * `connected` while the hold is still up: a slow connect still shows
+ * "Connecting…" after this delay, and a pick that starts shortly after the
+ * join stays inside the window.
+ */
+export const INITIAL_REVEAL_DELAY_MS = 2000;
+
+interface HoldInputs {
+  session: number;
+  previewStart: number;
+  chromeVisible: boolean;
+  pickerActive: boolean;
+  status: PairingEngineState['status'];
+  purpose: PairingPurpose | null;
+  connectRestarted: boolean;
+}
+
+interface HoldDecision {
+  introHeld: boolean;
+  selectionHeld: boolean;
+  restartTimer: boolean;
+  inputs: HoldInputs;
+}
+
+/**
+ * A new session (or chrome appearing) is decided by the link's purpose:
+ * `select_element` starts in the selection hold, `preview` is never held, and
+ * no purpose falls back to the intro hold. The intro hold hides the bar when
+ * preview chrome appears, and again when the session changes while a hold is
+ * already hiding it. A bar that is already showing stays up across a re-scan
+ * with no purpose. Selection hold replaces the intro once the picker is active
+ * and outlives the picker until a Builder preview, a `preview` re-scan, or a
+ * re-scan with no purpose. A `select_element` re-scan starts held, including
+ * when the bar is already up.
+ */
+function decideHold(
+  prev: HoldInputs,
+  holds: { introHeld: boolean; selectionHeld: boolean },
+  input: HoldInputs,
+): HoldDecision {
+  let introHeld = holds.introHeld;
+  let selectionHeld = holds.selectionHeld;
+  let connectRestarted = prev.connectRestarted;
+  let restartTimer = false;
+
+  const armIntro = (): void => {
+    introHeld = true;
+    connectRestarted = false;
+    restartTimer = true;
+  };
+
+  if (!input.chromeVisible) {
+    return {
+      introHeld: false,
+      selectionHeld: false,
+      restartTimer: false,
+      inputs: { ...input, connectRestarted: false },
+    };
+  }
+
+  const sessionChanged = input.session !== prev.session;
+  const previewStarted = input.previewStart > prev.previewStart;
+
+  if (previewStarted) {
+    introHeld = false;
+    selectionHeld = false;
+    connectRestarted = true;
+  } else if (input.pickerActive) {
+    selectionHeld = true;
+    introHeld = false;
+  } else if (sessionChanged || !prev.chromeVisible) {
+    if (input.purpose === 'select_element') {
+      selectionHeld = true;
+      introHeld = false;
+    } else if (input.purpose === 'preview') {
+      selectionHeld = false;
+      introHeld = false;
+    } else if (introHeld || selectionHeld || !prev.chromeVisible) {
+      selectionHeld = false;
+      armIntro();
+    }
+  }
+
+  if (introHeld && input.status === 'connected' && !connectRestarted) {
+    connectRestarted = true;
+    restartTimer = true;
+  }
+
+  return {
+    introHeld,
+    selectionHeld,
+    restartTimer,
+    inputs: { ...input, connectRestarted },
+  };
+}
+
+/**
+ * Whether the preview top bar should stay down.
+ *
+ * The decision is applied during render. Waiting for an effect would mount
+ * the bar for a frame and play its slide-in before the hold could hide it.
+ * The reveal timer stays in an effect.
+ */
+export function usePreviewBarHold(state: PairingEngineState, pickerActive: boolean): boolean {
+  const chromeVisible = resolvePreviewChrome(state).visible;
+  const [introHeld, setIntroHeld] = React.useState(false);
+  const [selectionHeld, setSelectionHeld] = React.useState(false);
+  const [introEpoch, setIntroEpoch] = React.useState(0);
+  const purpose = state.pairingPurpose ?? null;
+  const inputsRef = React.useRef<HoldInputs>({
+    session: state.pairingSessionGeneration,
+    previewStart: state.previewStartGeneration,
+    chromeVisible: false,
+    pickerActive: false,
+    status: state.status,
+    purpose,
+    connectRestarted: false,
+  });
+
+  const decision = decideHold(
+    inputsRef.current,
+    { introHeld, selectionHeld },
+    {
+      session: state.pairingSessionGeneration,
+      previewStart: state.previewStartGeneration,
+      chromeVisible,
+      pickerActive,
+      status: state.status,
+      purpose,
+      connectRestarted: false,
+    },
+  );
+  inputsRef.current = decision.inputs;
+
+  if (decision.introHeld !== introHeld) {
+    setIntroHeld(decision.introHeld);
+  }
+  if (decision.selectionHeld !== selectionHeld) {
+    setSelectionHeld(decision.selectionHeld);
+  }
+  if (decision.restartTimer) {
+    setIntroEpoch((epoch) => epoch + 1);
+  }
+
+  React.useEffect(() => {
+    if (!introHeld) return;
+    const timer = setTimeout(() => setIntroHeld(false), INITIAL_REVEAL_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, [introEpoch, introHeld]);
+
+  return decision.introHeld || decision.selectionHeld;
+}

package/src/runtime/BannerHost.tsx

@@ -0,0 +1,102 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { BannerSurface } from '../surfaces/BannerSurface';
+import { bannerOverlayHostPadding } from '../surfaces/bannerBarLayout';
+import { resolveBannerBackgroundColor } from '../surfaces/resolveBannerTheme';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { SdkErrorBoundary } from './SdkErrorBoundary';
+import { bannerEdge, embedBannerPlaceholderId, warnBannerOnce } from './bannerPlacement';
+import { hasEmbedBannerPlaceholder } from './embedBannerRegistry';
+import { useBannerSession } from './useBannerSession';
+
+/**
+ * Top or bottom banner bar. Element modes render in {@link EmbedBannerPlaceholder}.
+ *
+ * `overlay` floats over the host. `flow` sits in layout and pushes the app.
+ * The bar does not participate in the host accessibility trap.
+ */
+export function BannerHost({
+  engine,
+  hidden,
+  placement = 'overlay',
+  edge: edgeFilter,
+}: {
+  engine: BannerSessionEngine;
+  hidden?: boolean;
+  placement?: 'overlay' | 'flow';
+  /** When set, render only the banner pinned to this edge. */
+  edge?: 'top' | 'bottom';
+}): React.ReactElement | null {
+  const session = useBannerSession(engine);
+  const banner = session?.version.banner ?? null;
+  const edge = banner ? bannerEdge(banner.embedMode) : null;
+  const insets = useUserflowSafeAreaInsets();
+
+  React.useEffect(() => {
+    if (!session || !banner || edge) return;
+    const placeholderId = embedBannerPlaceholderId(banner);
+    if (placeholderId && hasEmbedBannerPlaceholder(placeholderId)) return;
+    const message = placeholderId
+      ? `Userflow: no EmbedBannerPlaceholder with id "${placeholderId}" is mounted; the banner is not shown`
+      : `Userflow: banner embed mode ${banner.embedMode} needs a manual embed selector and an EmbedBannerPlaceholder with that id`;
+    warnBannerOnce(`embed:${session.id}:${banner.embedMode}:${placeholderId ?? 'none'}`, message);
+  }, [banner, edge, session]);
+
+  if (hidden || !session || !banner || !edge) return null;
+  if (edgeFilter && edge !== edgeFilter) return null;
+
+  const floats = banner.overlay !== false;
+  if ((placement === 'overlay') !== floats) return null;
+
+  const bar = (
+    <SdkErrorBoundary scope="banner" resetKey={session.id}>
+      <BannerSurface
+        session={session}
+        onActions={(actions) => engine.handleActions(actions)}
+        onDismiss={(endReason) => {
+          void engine.endBanner(endReason);
+        }}
+      />
+    </SdkErrorBoundary>
+  );
+
+  if (placement === 'flow') {
+    const backgroundColor = bannerBackground(session);
+    const safePad = edge === 'top' ? { paddingTop: insets.top } : { paddingBottom: insets.bottom };
+    return (
+      <View testID="userflow-banner-flow" style={[styles.flow, safePad, { backgroundColor }]}>
+        {bar}
+      </View>
+    );
+  }
+
+  const edgeStyle = edge === 'top' ? { top: insets.top } : { bottom: insets.bottom };
+
+  return (
+    <View
+      pointerEvents="box-none"
+      style={[styles.pin, edgeStyle, bannerOverlayHostPadding(insets)]}
+    >
+      {bar}
+    </View>
+  );
+}
+
+function bannerBackground(session: BannerSessionFragment): string {
+  return resolveBannerBackgroundColor(session.version.theme);
+}
+
+const styles = StyleSheet.create({
+  pin: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+  },
+  flow: {
+    alignSelf: 'stretch',
+  },
+});

package/src/runtime/EmbedBannerPlaceholder.tsx

@@ -0,0 +1,115 @@
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { elementPickerController } from '../authoring/elementPickerController';
+import { BannerSurface } from '../surfaces/BannerSurface';
+import { bannerOverlayHostPadding } from '../surfaces/bannerBarLayout';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { SdkErrorBoundary } from './SdkErrorBoundary';
+import { BannerEngineContext } from './bannerEngineContext';
+import { embedBannerPlaceholderId, warnBannerOnce } from './bannerPlacement';
+import { registerEmbedBannerPlaceholder } from './embedBannerRegistry';
+import { useBannerSession } from './useBannerSession';
+
+export interface EmbedBannerPlaceholderProps {
+  /**
+   * Matches the banner's manual embed selector. `#welcome-banner` and
+   * `welcome-banner` both match this id.
+   */
+  id: string;
+}
+
+/**
+ * Host slot for an element-mode banner (`ELEMENT_BEFORE`, `ELEMENT_AFTER`,
+ * `ELEMENT_FIRST`, `ELEMENT_LAST`). Mount it where the bar should appear.
+ * Until a matching banner is active the slot renders nothing, so it takes no
+ * space and is not visible. Top and bottom bars ignore this slot.
+ * `overlay: false` keeps the bar in layout; `overlay: true` paints it over
+ * the content below the slot.
+ */
+export function EmbedBannerPlaceholder({
+  id,
+}: EmbedBannerPlaceholderProps): React.ReactElement | null {
+  const engine = React.useContext(BannerEngineContext);
+  const placeholderId = id.trim();
+  const session = useBannerSession(engine);
+  const insets = useUserflowSafeAreaInsets();
+  const [pickerActive, setPickerActive] = React.useState(
+    () => elementPickerController.getState().active,
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setPickerActive(next.active);
+    });
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (!placeholderId) {
+      warnBannerOnce('embed-banner-empty-id', 'Userflow: EmbedBannerPlaceholder requires an id');
+      return;
+    }
+    return registerEmbedBannerPlaceholder(placeholderId);
+  }, [placeholderId]);
+
+  React.useEffect(() => {
+    if (engine) return;
+    warnBannerOnce(
+      'embed-banner-outside-provider',
+      'Userflow: EmbedBannerPlaceholder must be rendered inside UserflowProvider',
+    );
+  }, [engine]);
+
+  // No host view until a banner is actually shown. An empty slot would still
+  // participate in flex gap and stretch layout.
+  if (!engine || !placeholderId || pickerActive || !session) return null;
+
+  const banner = session.version.banner ?? null;
+  if (!banner || embedBannerPlaceholderId(banner) !== placeholderId) return null;
+
+  const bar = (
+    <BannerSurface
+      session={session}
+      onActions={(actions) => engine.handleActions(actions)}
+      onDismiss={(endReason) => {
+        void engine.endBanner(endReason);
+      }}
+    />
+  );
+
+  return (
+    <SdkErrorBoundary scope="banner" resetKey={session.id}>
+      {banner.overlay !== false ? (
+        <View pointerEvents="box-none" testID="userflow-embed-banner" style={styles.overlaySlot}>
+          <View
+            pointerEvents="box-none"
+            style={[styles.overlayBar, bannerOverlayHostPadding(insets)]}
+          >
+            {bar}
+          </View>
+        </View>
+      ) : (
+        <View testID="userflow-embed-banner" style={styles.slot}>
+          {bar}
+        </View>
+      )}
+    </SdkErrorBoundary>
+  );
+}
+
+const styles = StyleSheet.create({
+  slot: {
+    alignSelf: 'stretch',
+  },
+  overlaySlot: {
+    height: 0,
+    alignSelf: 'stretch',
+  },
+  overlayBar: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+  },
+});

package/src/runtime/SdkErrorBoundary.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+
+import { reportSdkError } from './reportSdkError';
+
+export interface SdkErrorBoundaryProps {
+  /** Label included in the isolated-error log (for example `overlay`). */
+  scope: string;
+  /**
+   * When this value changes after a caught error, the boundary retries its
+   * children — but only if that identity has not already failed. A reconnect
+   * that restores the same session/step stays blank. Does not remount children
+   * while they are healthy.
+   */
+  resetKey?: string;
+  /** Called after a render error is isolated (for example to clear an a11y trap). */
+  onError?: (error: Error) => void;
+  children: React.ReactNode;
+}
+
+interface SdkErrorBoundaryState {
+  hasError: boolean;
+  resetKey: string | undefined;
+  failedKeys: string[];
+}
+
+/**
+ * Contains React render/lifecycle errors in SDK UI so they cannot unmount the
+ * host app tree. Event handlers and async work are not covered — those use
+ * {@link isolateSync} / {@link isolateAsync}.
+ */
+export class SdkErrorBoundary extends React.Component<
+  SdkErrorBoundaryProps,
+  SdkErrorBoundaryState
+> {
+  override state: SdkErrorBoundaryState = {
+    hasError: false,
+    resetKey: this.props.resetKey,
+    failedKeys: [],
+  };
+
+  static getDerivedStateFromError(): Partial<SdkErrorBoundaryState> {
+    return { hasError: true };
+  }
+
+  static getDerivedStateFromProps(
+    props: SdkErrorBoundaryProps,
+    state: SdkErrorBoundaryState,
+  ): Partial<SdkErrorBoundaryState> | null {
+    if (props.resetKey === state.resetKey) {
+      return null;
+    }
+    const nextKey = props.resetKey ?? '';
+    if (nextKey !== '' && state.failedKeys.includes(nextKey)) {
+      return { hasError: true, resetKey: props.resetKey };
+    }
+    return { hasError: false, resetKey: props.resetKey };
+  }
+
+  override componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    reportSdkError(this.props.scope, error, info.componentStack);
+    this.props.onError?.(error);
+    const key = this.props.resetKey;
+    if (!key) {
+      return;
+    }
+    this.setState((prev) =>
+      prev.failedKeys.includes(key) ? null : { failedKeys: [...prev.failedKeys, key] },
+    );
+  }
+
+  override render(): React.ReactNode {
+    if (this.state.hasError) {
+      return null;
+    }
+    return this.props.children;
+  }
+}