@userflow-tech/react-native 0.5.0 → 0.7.0

package/src/deviceContext.ts

@@ -1,16 +1,24 @@
 /**
- * Resolve mobile platform metadata for Userflow user attributes.
+ * Resolve mobile platform metadata and the running SDK version for Userflow
+ * user attributes.
  *
  * Cached once during {@link Userflow.init} and merged into identify attributes
  * (same lifecycle as {@link hostAppVersion.ts}).
  */
 
+import { SDK_VERSION } from './version';
+
 export type SdkPlatform = 'react_native';
 export type DeviceOs = 'ios' | 'android';
 export type DeviceType = 'phone' | 'tablet';
 
 export interface DeviceContext {
   sdk: SdkPlatform;
+  /**
+   * Published `@userflow-tech/react-native` version, e.g. `0.4.6`. Always set by
+   * the SDK; optional so context objects built by host code (mocks) stay valid.
+   */
+  sdkVersion?: string;
   deviceOs?: DeviceOs;
   deviceType?: DeviceType;
 }
@@ -19,6 +27,7 @@ export interface DeviceContext {
 export const ANDROID_TABLET_SMALLEST_WIDTH_DP = 600;
 
 export const SDK_USER_ATTRIBUTE = 'sdk';
+export const SDK_VERSION_USER_ATTRIBUTE = 'sdk_version';
 export const DEVICE_OS_USER_ATTRIBUTE = 'device_os';
 export const DEVICE_TYPE_USER_ATTRIBUTE = 'device_type';
 
@@ -70,6 +79,7 @@ export function resolveDeviceContextFromSources(sources: {
   const deviceType = resolveDeviceTypeFromSources(sources);
   return {
     sdk: 'react_native',
+    sdkVersion: SDK_VERSION,
     ...(deviceOs ? { deviceOs } : {}),
     ...(deviceType ? { deviceType } : {}),
   };
@@ -103,6 +113,7 @@ export function resolveDeviceContext(): DeviceContext {
 
 /** `undefined` until the first {@link cacheDeviceContextAtInit}; then resolved. */
 let cachedDeviceContext: DeviceContext | undefined;
+let didWarnSdkVersionOverride = false;
 
 /**
  * Resolve and cache device metadata during {@link Userflow.init}.
@@ -118,33 +129,57 @@ export function getCachedDeviceContext(): DeviceContext | null {
   return cachedDeviceContext ?? null;
 }
 
-/** Returns cached device fields for UpsertUser, or `{}` before init. */
-export function deviceContextUserAttributes(): Record<string, string> {
-  const cached = getCachedDeviceContext();
-  if (!cached) return {};
+/** Device fields for UpsertUser that identify attributes may override. */
+function overridableDeviceAttributes(context: DeviceContext): Record<string, string> {
   return {
-    [SDK_USER_ATTRIBUTE]: cached.sdk,
-    ...(cached.deviceOs ? { [DEVICE_OS_USER_ATTRIBUTE]: cached.deviceOs } : {}),
-    ...(cached.deviceType ? { [DEVICE_TYPE_USER_ATTRIBUTE]: cached.deviceType } : {}),
+    [SDK_USER_ATTRIBUTE]: context.sdk,
+    ...(context.deviceOs ? { [DEVICE_OS_USER_ATTRIBUTE]: context.deviceOs } : {}),
+    ...(context.deviceType ? { [DEVICE_TYPE_USER_ATTRIBUTE]: context.deviceType } : {}),
   };
 }
 
 /** Optional user-attribute keys added by {@link mergeDeviceContextUserAttributes}. */
 export type DeviceContextUserAttributeMap = Partial<{
   [SDK_USER_ATTRIBUTE]: SdkPlatform;
+  [SDK_VERSION_USER_ATTRIBUTE]: string;
   [DEVICE_OS_USER_ATTRIBUTE]: DeviceOs;
   [DEVICE_TYPE_USER_ATTRIBUTE]: DeviceType;
 }>;
 
-/** Merges cached device attrs into identify attributes; caller values win on key conflicts. */
+/** One development warning when identify attributes try to set `sdk_version`. */
+function warnIfSdkVersionOverridden(attributes: Record<string, unknown> | undefined): void {
+  if (!__DEV__ || didWarnSdkVersionOverride) return;
+  const passed = attributes?.[SDK_VERSION_USER_ATTRIBUTE];
+  // `{ set: value }` is the long form of a bare literal.
+  const value =
+    typeof passed === 'object' && passed !== null && 'set' in passed
+      ? (passed as { set: unknown }).set
+      : passed;
+  if (value === undefined || value === SDK_VERSION) return;
+  didWarnSdkVersionOverride = true;
+  // eslint-disable-next-line no-console -- intentional development diagnostic
+  console.warn(
+    `[Userflow] "${SDK_VERSION_USER_ATTRIBUTE}" is set by the SDK (${SDK_VERSION}); the value passed to identify / identifyAnonymous was ignored.`,
+  );
+}
+
+/**
+ * Merges cached device attrs into identify attributes. Caller values win on key
+ * conflicts, except `sdk_version`, which always reports the running SDK.
+ */
 export function mergeDeviceContextUserAttributes<T extends Record<string, unknown>>(
   attributes?: T,
 ): (T & DeviceContextUserAttributeMap) | undefined {
-  const system = deviceContextUserAttributes();
-  if (Object.keys(system).length === 0) {
+  const cached = getCachedDeviceContext();
+  if (!cached) {
     return attributes as (T & DeviceContextUserAttributeMap) | undefined;
   }
-  return { ...system, ...(attributes ?? {}) } as T & DeviceContextUserAttributeMap;
+  warnIfSdkVersionOverridden(attributes);
+  return {
+    ...overridableDeviceAttributes(cached),
+    ...(attributes ?? {}),
+    [SDK_VERSION_USER_ATTRIBUTE]: SDK_VERSION,
+  } as T & DeviceContextUserAttributeMap;
 }
 
 export function formatDeviceContextLog(resolved: DeviceContext | null): string {
@@ -153,7 +188,7 @@ export function formatDeviceContextLog(resolved: DeviceContext | null): string {
   }
   const os = resolved.deviceOs ?? 'unknown';
   const type = resolved.deviceType ?? 'unknown';
-  return `[Userflow] device context sdk=${resolved.sdk} device_os=${os} device_type=${type}`;
+  return `[Userflow] device context sdk=${resolved.sdk} sdk_version=${resolved.sdkVersion ?? 'unknown'} device_os=${os} device_type=${type}`;
 }
 
 /** Log cached user-attribute values. Requires {@link cacheDeviceContextAtInit}. */
@@ -162,7 +197,8 @@ export function logDeviceContext(): void {
   console.log(formatDeviceContextLog(getCachedDeviceContext()));
 }
 
-/** @internal Resets init cache between tests. */
+/** @internal Resets init cache and the one-time override warning between tests. */
 export function resetCachedDeviceContextForTests(): void {
   cachedDeviceContext = undefined;
+  didWarnSdkVersionOverride = false;
 }

package/src/index.ts

@@ -22,6 +22,7 @@ import type {
 
 import './anchors/autoAnchor';
 import { anchorChangeTicker } from './anchors/anchorChangeTicker';
+import { resetDetectedAppFont } from './anchors/fiber/detectAppFontFamily';
 import { notifyAnchorScreenChange } from './anchors/resolveAnchorHost';
 import {
   setCustomScrollIntoView as setCustomScrollIntoViewConfig,
@@ -367,7 +368,10 @@ export const Userflow = {
   setOnNavigate(handler: FlowNavigateHandler | null | undefined): void {
     setHostOnNavigate(handler);
   },
-  /** Identify the current user and upsert their attributes. */
+  /**
+   * Identify the current user and upsert their attributes. The SDK adds `sdk_version`
+   * itself; a value passed for it here is ignored.
+   */
   async identify(
     userId: string,
     attributes?: UserflowAttributes,
@@ -390,7 +394,10 @@ export const Userflow = {
     await core.identify(userId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
-  /** Identify an anonymous user with a stable auto-generated id stored on device. */
+  /**
+   * Identify an anonymous user with a stable auto-generated id stored on device. Like
+   * {@link identify}, the SDK sets `sdk_version` itself.
+   */
   async identifyAnonymous(
     attributes?: UserflowAttributes,
     options?: UserflowIdentifyOptions,
@@ -477,8 +484,8 @@ export const Userflow = {
     return getCachedHostAppVersion();
   },
   /**
-   * Platform metadata cached during {@link init} (`sdk`, `deviceOs`, `deviceType`),
-   * or `null` before init.
+   * Platform metadata cached during {@link init} (`sdk`, `sdkVersion`, `deviceOs`,
+   * `deviceType`), or `null` before init.
    */
   getDeviceContext(): DeviceContext | null {
     return getCachedDeviceContext();
@@ -493,6 +500,7 @@ export const Userflow = {
   },
   /** Clears the current user identity and disconnects from Userflow. */
   async reset(): Promise<void> {
+    resetDetectedAppFont();
     resetClientConditionEngine();
     resetFlowSessionEngine();
     resetBannerSessionEngine();
@@ -574,7 +582,7 @@ export const Userflow = {
     logHostAppVersionToConsole();
   },
   /**
-   * Log cached user-attribute values (`sdk`, `device_os`, `device_type`).
+   * Log cached user-attribute values (`sdk`, `sdk_version`, `device_os`, `device_type`).
    * Requires {@link init}; before init, logs that init is required.
    */
   logDeviceContext(): void {

package/src/installCheck.ts

@@ -10,7 +10,7 @@ export const INSTALL_ASYNC_STORAGE_LINE =
   '- @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.';
 
 export const INSTALL_VIEW_SHOT_LINE =
-  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.';
+  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.';
 
 export const INSTALL_WEBVIEW_LINE =
   '- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.';
@@ -36,7 +36,7 @@ export const INSTALL_SAFE_AREA_WARNING =
 export function formatViewShotVersionWarning(version: string): string {
   return (
     `[Userflow] react-native-view-shot@${version} is older than 5.0.0, so Builder element selection may not get a screenshot. ` +
-    'On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it, and rebuild. ' +
+    'On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it, and rebuild. ' +
     'Otherwise install react-native-view-shot@^5.0.0 in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add "react-native-view-shot" to expo.install.exclude. ' +
     'Do not retry the install with --force or --legacy-peer-deps; that leaves this version in place.\n' +
     INSTALL_CHECK_FOOTER
@@ -89,7 +89,7 @@ function readViewShotVersion(): string | null {
   }
 }
 
-/** Dev warning when view-shot 4.x is installed. Null on 5.x or when it is absent. */
+/** Dev warning when view-shot 4.x is installed. Null on 5.x and later, or when it is absent. */
 export function viewShotVersionWarning(): string | null {
   const version = readViewShotVersion();
   if (!version) return null;

package/src/lifecycle.ts

@@ -94,7 +94,8 @@ export class LifecycleController {
   private readonly scheduler: LifecycleScheduler;
   private readonly now: () => number;
   private readonly suspendGraceMs: number;
-  private readonly getCurrentAppState: () => AppStateStatus;
+  /** Wider than AppStateStatus: React Native 0.88 types currentState as `string | null | undefined`. */
+  private readonly getCurrentAppState: () => string | null | undefined;
   private readonly subscribeAppState: (handler: (status: AppStateStatus) => void) => () => void;
 
   private unsubscribeAppState: (() => void) | null = null;

package/src/pairing/PairingController.ts

@@ -59,7 +59,8 @@ export interface PairingControllerOptions {
    */
   cancelPendingDraftEnd?: () => void;
   LinkingModule?: {
-    getInitialURL(): Promise<string | null>;
+    // React Native 0.88 adds undefined to the result.
+    getInitialURL(): Promise<string | null | undefined>;
     addEventListener(type: 'url', handler: (event: { url: string }) => void): { remove(): void };
   };
   AppStateModule?: {

package/src/runtime/BannerHost.tsx

@@ -49,15 +49,15 @@ export function BannerHost({
   if (edgeFilter && edge !== edgeFilter) return null;
 
   const floats = banner.overlay !== false;
-  const usesWebView = bannerNeedsWebView(banner, session.version.theme);
-  // Custom-css / eval WebViews paint in the overlay host (same as userflow.js). A second
+  const usesWebView = bannerNeedsWebView(banner);
+  // Custom banner WebViews paint in the overlay host (same as userflow.js). A second
   // WKWebView in the flow slot often fails to load after the first banner dismisses.
   const hostAsOverlay = floats || usesWebView;
   if ((placement === 'overlay') !== hostAsOverlay) return null;
 
   const pushLayoutEdge = placement === 'flow' && !hostAsOverlay ? edge : null;
   // Builder overlay:true floats below the status bar. Push-layout WebViews in the overlay
-  // host still paint safe-area chrome (overlay:false + custom CSS).
+  // host still paint safe-area chrome (overlay:false + custom banner).
   const overlaySafeEdge = hostAsOverlay && !floats ? edge : null;
 
   const surface = (

package/src/runtime/UserflowOverlay.tsx

@@ -12,6 +12,7 @@ import { stepTrapsHostAccessibility } from '../surfaces/hostAccessibilityTrap';
 
 import { BannerHost } from './BannerHost';
 import { FlowRenderer } from './FlowRenderer';
+import { WindowOverlayHost } from './WindowOverlayHost';
 import { useFlowSessionState } from './useFlowSessionState';
 import { getUserflowCore } from './userflowCore';
 
@@ -86,30 +87,37 @@ export function UserflowOverlay({
        * destroy a running script. `suppressed` hides it for the pick.
        */}
       <EvalJsHost suppressed={pickerActive} />
-      <PreviewModeBanner
-        onConfirmingChange={setPreviewConfirming}
-        onExit={onExitPreview}
-        held={previewHeld}
-        onRestart={onRestartPreview}
-        state={pairingState}
-        suppressed={pickerActive}
-      />
       {/*
-       * Unmount flow chrome for the whole pick. The session stays alive;
-       * captureScreen would otherwise include the modal or tooltip.
-       * Remounting reads the same session back.
+       * One host for all three, so they keep this paint order above native
+       * modal screens. The host app's trap does not reach a natively presented
+       * modal, so the host traps VoiceOver itself.
        */}
-      {pickerActive ? null : (
-        <FlowRenderer
-          engine={engine}
-          previewRestartGeneration={pairingState.previewRestartGeneration}
+      <WindowOverlayHost accessibilityModal={trapHostAccessibility}>
+        <PreviewModeBanner
+          onConfirmingChange={setPreviewConfirming}
+          onExit={onExitPreview}
+          held={previewHeld}
+          onRestart={onRestartPreview}
+          state={pairingState}
+          suppressed={pickerActive}
         />
-      )}
-      {/*
-       * After flow chrome so BODY_FIRST / BODY_LAST overlay banners stay visible
-       * while a tour step (modal, tooltip, condition wait) is still active.
-       */}
-      <BannerHost engine={bannerEngine} hidden={pickerActive} />
+        {/*
+         * Unmount flow chrome for the whole pick. The session stays alive;
+         * captureScreen would otherwise include the modal or tooltip.
+         * Remounting reads the same session back.
+         */}
+        {pickerActive ? null : (
+          <FlowRenderer
+            engine={engine}
+            previewRestartGeneration={pairingState.previewRestartGeneration}
+          />
+        )}
+        {/*
+         * After flow chrome so BODY_FIRST / BODY_LAST overlay banners stay visible
+         * while a tour step (modal, tooltip, condition wait) is still active.
+         */}
+        <BannerHost engine={bannerEngine} hidden={pickerActive} />
+      </WindowOverlayHost>
       <ElementPickerOverlay />
     </>
   );

package/src/runtime/WindowOverlayHost.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import { Platform } from 'react-native';
+
+import { isNativeModuleLinked } from '../nativeModules';
+
+interface FullWindowOverlayProps {
+  children?: React.ReactNode;
+  /** react-native-screens 4.x. Defaults to true, which traps VoiceOver inside the overlay. */
+  unstable_accessibilityContainerViewIsModal?: boolean;
+}
+
+type FullWindowOverlayComponent = React.ComponentType<FullWindowOverlayProps>;
+
+/**
+ * Native module in every react-native-screens 3.x and 4.x build. Rendering
+ * `FullWindowOverlay` without the native half would mount an unregistered
+ * component, so the package is not required until this is linked.
+ */
+const SCREENS_NATIVE_MODULE = 'RNSModule';
+
+let cached: FullWindowOverlayComponent | null | undefined;
+
+/** react-native-screens' `FullWindowOverlay`, or null when it cannot host chrome here. */
+function getFullWindowOverlay(): FullWindowOverlayComponent | null {
+  if (cached !== undefined) return cached;
+  cached = null;
+
+  // FullWindowOverlay is iOS-only; elsewhere it renders a plain View.
+  if (Platform.OS !== 'ios' || typeof require !== 'function') return cached;
+  if (!isNativeModuleLinked(SCREENS_NATIVE_MODULE)) return cached;
+
+  try {
+    // Not a peer: apps that present native modals already have it, through
+    // Expo Router or React Navigation's native stack.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional package probe
+    const mod = require('react-native-screens') as {
+      FullWindowOverlay?: FullWindowOverlayComponent;
+    };
+    cached = mod?.FullWindowOverlay ?? null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+export interface WindowOverlayHostProps {
+  children: React.ReactNode;
+  /**
+   * Hide everything outside the host from VoiceOver, natively presented
+   * modals included. Defaults to false.
+   */
+  accessibilityModal?: boolean;
+}
+
+/** True when {@link WindowOverlayHost} draws above natively presented modals. */
+export function hasWindowOverlayHost(): boolean {
+  return getFullWindowOverlay() != null;
+}
+
+/**
+ * Hosts SDK chrome above everything else in the app window.
+ *
+ * On iOS, react-native-screens presents `modal`, `transparentModal`,
+ * `formSheet` and `fullScreenModal` screens, and React Native presents
+ * `<Modal>`, as view controllers above the React Native root view, so chrome
+ * rendered in `UserflowProvider`'s overlay is drawn beneath them and never
+ * receives touches there. `FullWindowOverlay` moves its children into a
+ * container on the window itself. Measured on iOS 17.4 and 26.5 with
+ * react-native-screens 4.16, that container stays above sheets whether they are
+ * presented before or after it mounts.
+ *
+ * Each host is its own container, stacked by when it was attached rather than
+ * by React order, so chrome that has to keep a paint order shares one host.
+ *
+ * Touches inside the host arrive in window coordinates, as they do in the root
+ * view. Children render in place when the overlay is unavailable: on Android,
+ * and in apps without react-native-screens.
+ */
+export function WindowOverlayHost({
+  children,
+  accessibilityModal = false,
+}: WindowOverlayHostProps): React.ReactElement {
+  const FullWindowOverlay = getFullWindowOverlay();
+  if (!FullWindowOverlay) return <>{children}</>;
+  return (
+    <FullWindowOverlay unstable_accessibilityContainerViewIsModal={accessibilityModal}>
+      {children}
+    </FullWindowOverlay>
+  );
+}
+
+/** @internal Clears the cached `FullWindowOverlay` lookup between tests. */
+export function resetWindowOverlayHostForTests(): void {
+  cached = undefined;
+}

package/src/runtime/pushBannerLayoutContext.tsx

@@ -92,6 +92,11 @@ export function usePushBannerLayoutRegistration(
  * Clears the host top/bottom safe-area override only after push-layout chrome
  * has laid out, so a session without visible chrome cannot leave a white strip.
  *
+ * Remembers which edge laid out instead of resetting a flag in an effect: on
+ * Fabric the chrome's first onLayout can run before the mount's passive effects
+ * flush, and a reset there would discard it until the banner happened to
+ * re-layout, leaving already-mounted host screens on the old inset.
+ *
  * @internal
  */
 export function usePushBannerHostInsetRegistration(
@@ -99,23 +104,23 @@ export function usePushBannerHostInsetRegistration(
   sessionId: string,
   enabled: boolean,
 ): (event: LayoutChangeEvent) => void {
-  const [laidOut, setLaidOut] = React.useState(false);
-
-  React.useEffect(() => {
-    setLaidOut(false);
-  }, [edge, enabled]);
+  const activeEdge = enabled && edge ? edge : null;
+  const [laidOutEdge, setLaidOutEdge] = React.useState<PushBannerLayoutEdge | null>(null);
 
-  usePushBannerLayoutRegistration(enabled && laidOut && edge ? edge : null, sessionId);
+  usePushBannerLayoutRegistration(
+    activeEdge && laidOutEdge === activeEdge ? activeEdge : null,
+    sessionId,
+  );
 
   return React.useCallback(
     (event: LayoutChangeEvent) => {
-      if (!enabled || !edge) {
+      if (!activeEdge) {
         return;
       }
       if (event.nativeEvent.layout.height > 0) {
-        setLaidOut(true);
+        setLaidOutEdge(activeEdge);
       }
     },
-    [edge, enabled],
+    [activeEdge],
   );
 }

package/src/runtime/userflowCore.ts

@@ -1,7 +1,13 @@
 import { UserflowCore } from '@userflow-tech/core';
 
-/** Shared {@link UserflowCore} singleton for the RN package facade + provider. */
-const core = new UserflowCore();
+import { SDK_VERSION } from '../version';
+
+/**
+ * Shared {@link UserflowCore} singleton for the RN package facade + provider.
+ * Joins report the published SDK version (not the internal core version) as
+ * `userflowClientBuild`.
+ */
+const core = new UserflowCore({ clientBuild: `react-native-${SDK_VERSION}` });
 
 export function getUserflowCore(): UserflowCore {
   return core;

package/src/surfaces/BannerSurface.tsx

@@ -25,10 +25,7 @@ export interface BannerSurfaceProps {
 
 let warnedMissingWebView = false;
 
-/**
- * Native banner bar, or a WebView when a button runs Evaluate JavaScript or the
- * theme has published custom CSS (same CDN stylesheet as userflow.js iframes).
- */
+/** Native banner bar, or a WebView when `customBannerEnabled` is set on the banner. */
 export function BannerSurface({
   session,
   pushLayoutEdge = null,
@@ -37,8 +34,7 @@ export function BannerSurface({
   onDismiss,
 }: BannerSurfaceProps): React.ReactElement | null {
   const banner = session.version.banner;
-  const theme = session.version.theme;
-  const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
+  const needsWebView = banner != null && bannerNeedsWebView(banner);
   const webView = needsWebView ? getEvalJsWebView() : null;
 
   React.useEffect(() => {

package/src/surfaces/ProgressBar.tsx

@@ -2,6 +2,7 @@ import type { ThemeFragment } from '@userflow-tech/protocol';
 import * as React from 'react';
 import { StyleSheet, Text, View } from 'react-native';
 
+import { resolveContentFontFamily } from '../content/resolveContentFontFamily';
 import { foregroundAlpha } from '../content/themeColor';
 
 export type ProgressBarPlacement = 'TOP' | 'BOTTOM';
@@ -72,7 +73,7 @@ export function ProgressBar({
             styles.numberedLabel,
             {
               color: foregroundAlpha(theme.fontColor, 0.55),
-              fontFamily: theme.fontFamily || undefined,
+              fontFamily: resolveContentFontFamily(theme),
               fontSize: Math.max(12, Math.round(theme.fontSize * 0.875)),
             },
           ]}