@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/hostAppVersion.ts

@@ -0,0 +1,258 @@
+/**
+ * Read the host app's native marketing version (store version), not the
+ * SDK package version. React Native does not expose the store version on
+ * `Platform`; Expo hosts may use optional expo modules; bare RN reads
+ * `NativeModules.RNDeviceInfo` constants from the bundled device-info native
+ * module (after autolink + rebuild). The OS name is `Platform.OS`.
+ *
+ * Do not `require('react-native-device-info')` — that package throws at import
+ * when the native module is missing, and Metro/Hermes may surface it as uncaught
+ * even inside try/catch.
+ */
+
+export type HostAppVersionSource =
+  | 'expo-application'
+  | 'expo-constants'
+  | 'react-native-device-info'
+  | 'init-override';
+
+export interface HostAppVersion {
+  version: string;
+  build?: string;
+  source: HostAppVersionSource;
+}
+
+export interface RNDeviceInfoConstants {
+  appVersion?: string;
+  buildNumber?: string;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function unwrapModule(mod: unknown): Record<string, unknown> | null {
+  if (typeof mod !== 'object' || mod === null) return null;
+  const record = mod as Record<string, unknown>;
+  const nested = record['default'];
+  if (typeof nested === 'object' && nested !== null) {
+    return { ...record, ...(nested as Record<string, unknown>) };
+  }
+  return record;
+}
+
+function tryRequireExpoApplication(): unknown {
+  try {
+    // Optional on bare RN — Metro requires a string literal.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('expo-application');
+  } catch {
+    return undefined;
+  }
+}
+
+function tryRequireExpoConstants(): unknown {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('expo-constants');
+  } catch {
+    return undefined;
+  }
+}
+
+function loadLinkedDeviceInfoNativeModule(): RNDeviceInfoConstants | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const { NativeModules } = require('react-native') as {
+      NativeModules: { RNDeviceInfo?: RNDeviceInfoConstants };
+    };
+    return NativeModules.RNDeviceInfo ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Visible for tests: map an `expo-application` module shape to a version. */
+export function readExpoApplication(mod: unknown): HostAppVersion | null {
+  const record = unwrapModule(mod);
+  if (!record) return null;
+  const version = nonEmptyString(record['nativeApplicationVersion']);
+  if (!version) return null;
+  const build = nonEmptyString(record['nativeBuildVersion']);
+  return { version, source: 'expo-application', ...(build ? { build } : {}) };
+}
+
+/** Visible for tests: map an `expo-constants` module shape to a version. */
+export function readExpoConstants(mod: unknown): HostAppVersion | null {
+  const record = unwrapModule(mod);
+  if (!record) return null;
+  const expoConfig = record['expoConfig'];
+  const configVersion =
+    typeof expoConfig === 'object' && expoConfig !== null
+      ? nonEmptyString((expoConfig as Record<string, unknown>)['version'])
+      : undefined;
+  const version = nonEmptyString(record['nativeAppVersion']) ?? configVersion;
+  if (!version) return null;
+  const build = nonEmptyString(record['nativeBuildVersion']);
+  return { version, source: 'expo-constants', ...(build ? { build } : {}) };
+}
+
+/** Visible for tests: map linked RNDeviceInfo native constants to a version. */
+export function readDeviceInfoFromNativeModule(
+  module: RNDeviceInfoConstants | null | undefined,
+): HostAppVersion | null {
+  if (!module) return null;
+  const version = nonEmptyString(module.appVersion);
+  if (!version || version === 'unknown') return null;
+  const build = nonEmptyString(module.buildNumber);
+  return {
+    version,
+    source: 'react-native-device-info',
+    ...(build && build !== 'unknown' ? { build } : {}),
+  };
+}
+
+/** Visible for tests: first non-null reader wins (Expo modules, then RNDeviceInfo). */
+export function resolveHostAppVersionFromSources(sources: {
+  expoApplication?: unknown;
+  expoConstants?: unknown;
+  deviceInfoNative?: RNDeviceInfoConstants | null;
+}): HostAppVersion | null {
+  return (
+    readExpoApplication(sources.expoApplication) ??
+    readExpoConstants(sources.expoConstants) ??
+    readDeviceInfoFromNativeModule(sources.deviceInfoNative)
+  );
+}
+
+export function resolveHostAppVersion(): HostAppVersion | null {
+  return resolveHostAppVersionFromSources({
+    expoApplication: tryRequireExpoApplication(),
+    expoConstants: tryRequireExpoConstants(),
+    deviceInfoNative: loadLinkedDeviceInfoNativeModule(),
+  });
+}
+
+export interface HostAppVersionInitOptions {
+  /** When set, overrides auto-detection for the lifetime of this init. */
+  appVersion?: string;
+  appBuild?: string;
+}
+
+/** Visible for tests: resolve version for init, honoring an optional client override. */
+export function resolveHostAppVersionForInit(
+  options: HostAppVersionInitOptions = {},
+): HostAppVersion | null {
+  const overrideVersion = nonEmptyString(options.appVersion);
+  if (overrideVersion) {
+    const build = nonEmptyString(options.appBuild);
+    return {
+      version: overrideVersion,
+      source: 'init-override',
+      ...(build ? { build } : {}),
+    };
+  }
+  return resolveHostAppVersion();
+}
+
+/** `undefined` until the first {@link cacheHostAppVersionAtInit}; then resolved or null. */
+let cachedHostAppVersion: HostAppVersion | null | undefined;
+
+/**
+ * Resolve and cache the host app version during {@link Userflow.init}.
+ * Re-running init replaces the cache.
+ */
+export function cacheHostAppVersionAtInit(
+  options: HostAppVersionInitOptions = {},
+): HostAppVersion | null {
+  cachedHostAppVersion = resolveHostAppVersionForInit(options);
+  return cachedHostAppVersion;
+}
+
+/** Returns the version cached at init, or `null` before init or when unavailable. */
+export function getCachedHostAppVersion(): HostAppVersion | null {
+  return cachedHostAppVersion ?? null;
+}
+
+/** User attribute keys for the host app's native store version. */
+export const HOST_APP_VERSION_USER_ATTRIBUTE = 'app_version';
+export const HOST_APP_BUILD_USER_ATTRIBUTE = 'app_build';
+
+/** Returns cached host version fields for UpsertUser, or `{}` when unavailable. */
+export function hostAppVersionUserAttributes(): Record<string, string> {
+  const cached = getCachedHostAppVersion();
+  if (!cached) return {};
+  return {
+    [HOST_APP_VERSION_USER_ATTRIBUTE]: cached.version,
+    ...(cached.build ? { [HOST_APP_BUILD_USER_ATTRIBUTE]: cached.build } : {}),
+  };
+}
+
+/** Optional user-attribute keys added by {@link mergeHostAppVersionUserAttributes}. */
+export type HostAppVersionUserAttributeMap = Partial<{
+  [HOST_APP_VERSION_USER_ATTRIBUTE]: string;
+  [HOST_APP_BUILD_USER_ATTRIBUTE]: string;
+}>;
+
+/** Merges cached host version attrs into identify attributes; caller values win on key conflicts. */
+export function mergeHostAppVersionUserAttributes<T extends Record<string, unknown>>(
+  attributes?: T,
+): (T & HostAppVersionUserAttributeMap) | undefined {
+  const system = hostAppVersionUserAttributes();
+  if (Object.keys(system).length === 0) {
+    return attributes as (T & HostAppVersionUserAttributeMap) | undefined;
+  }
+  return { ...system, ...(attributes ?? {}) } as T & HostAppVersionUserAttributeMap;
+}
+
+/** @internal Resets init cache between tests. */
+export function resetCachedHostAppVersionForTests(): void {
+  cachedHostAppVersion = undefined;
+}
+
+function readPlatformOS(): string {
+  try {
+    // Lazy require so Node unit tests can format messages without loading RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const os = (require('react-native') as { Platform?: { OS?: string } }).Platform?.OS;
+    return typeof os === 'string' && os.length > 0 ? os : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+export function formatHostAppVersionLog(
+  resolved: HostAppVersion | null,
+  os: string,
+): {
+  level: 'log' | 'warn';
+  message: string;
+} {
+  if (!resolved) {
+    return {
+      level: 'warn',
+      message:
+        `[Userflow] host app version is unavailable on ${os}. Rebuild the native app ` +
+        '(for example `cd ios && pod install`) so the bundled version module is linked.',
+    };
+  }
+  const build = resolved.build ? ` (build ${resolved.build})` : '';
+  return {
+    level: 'log',
+    message: `[Userflow] host app version ${resolved.version}${build} on ${os}`,
+  };
+}
+
+/** Log the host app's native version and platform OS to the console. */
+export function logHostAppVersion(): void {
+  const resolved =
+    cachedHostAppVersion !== undefined ? cachedHostAppVersion : resolveHostAppVersion();
+  const { level, message } = formatHostAppVersionLog(resolved, readPlatformOS());
+  if (level === 'warn') {
+    // eslint-disable-next-line no-console -- public logHostAppVersion()
+    console.warn(message);
+    return;
+  }
+  // eslint-disable-next-line no-console -- public logHostAppVersion()
+  console.log(message);
+}

package/src/index.ts

@@ -9,6 +9,7 @@
  */
 
 import type {
+  PublicAttributes,
   UserflowAttributes,
   UserflowConfig,
   UserflowEventAttributes,
@@ -16,6 +17,7 @@ import type {
   UserflowIdentifyOptions,
   UserflowInitOptions,
   UserflowTrackOptions,
+  UserflowUpdateGroupOptions,
 } from '@userflow-tech/core';
 
 import './anchors/autoAnchor';
@@ -27,6 +29,7 @@ import {
   type CustomScrollIntoView,
   type ScrollPadding,
 } from './anchors/scrollConfig';
+import { setSurfaceInteractionBlocking as setSurfaceInteractionBlockingConfig } from './surfaces/surfaceInteractionConfig';
 import { clearAnonymousId, getOrCreateAnonymousId } from './anonymousId';
 import {
   didHandleURL,
@@ -34,6 +37,20 @@ import {
   startDeepLinking,
   stopDeepLinking,
 } from './deepLinking';
+import {
+  cacheDeviceContextAtInit,
+  getCachedDeviceContext,
+  logDeviceContext as logDeviceContextToConsole,
+  mergeDeviceContextUserAttributes,
+  type DeviceContext,
+} from './deviceContext';
+import {
+  cacheHostAppVersionAtInit,
+  getCachedHostAppVersion,
+  logHostAppVersion as logHostAppVersionToConsole,
+  mergeHostAppVersionUserAttributes,
+  type HostAppVersion,
+} from './hostAppVersion';
 import { LifecycleController } from './lifecycle';
 import { setHostOnNavigate, type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
 import { NetworkController } from './network';
@@ -53,11 +70,17 @@ import { getUserflowCore } from './runtime/userflowCore';
 import {
   disableScreenTracking,
   enableScreenTracking,
+  getCurrentScreenLocation,
   handleScreenChange,
+  reportCurrentScreen,
+  SCREEN_VIEWED_EVENT,
+  screenViewedAttributes,
   setScreenChangeReporter,
 } from './screenTracker';
 
 export { SDK_VERSION } from './version';
+export type { DeviceContext, DeviceOs, DeviceType, SdkPlatform } from './deviceContext';
+export type { HostAppVersion, HostAppVersionSource } from './hostAppVersion';
 export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
 export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
 export { useFlowSessionState } from './runtime/useFlowSessionState';
@@ -103,9 +126,18 @@ export type UserflowInitConfig = UserflowInitOptions & {
    * Defaults to `https://e.userflow.com`.
    */
   pairingEndpoint?: string;
+  /**
+   * Override auto-detected native store version. When omitted, the SDK reads
+   * the host app's marketing version at init (Expo modules or native constants).
+   */
+  appVersion?: string;
+  /** Optional build number paired with {@link appVersion}. */
+  appBuild?: string;
 };
 
 export type {
+  PublicAttributeChange,
+  PublicAttributes,
   UserflowAttributes,
   UserflowConfig,
   UserflowEventAttributes,
@@ -113,6 +145,7 @@ export type {
   UserflowIdentifyOptions,
   UserflowInitOptions,
   UserflowTrackOptions,
+  UserflowUpdateGroupOptions,
 } from '@userflow-tech/core';
 
 const core = getUserflowCore();
@@ -131,6 +164,9 @@ const lifecycle = new LifecycleController({
   },
   ensureAlive: () => core.ensureAlive(),
   hasActiveSession: () => hasActiveFlowSession(),
+  onScreenResume: () => {
+    reportCurrentScreen();
+  },
 });
 
 const network = new NetworkController({
@@ -138,14 +174,23 @@ const network = new NetworkController({
   ensureAlive: () => core.ensureAlive(),
 });
 
+/** True when a screen was reported before identify, so first identify should emit `screen_viewed`. */
+let screenViewedAwaitingIdentify = false;
+
+function armScreenViewedForNextIdentify(): void {
+  if (getCurrentScreenLocation() != null) {
+    screenViewedAwaitingIdentify = true;
+  }
+}
+
 function wireScreenChangeReporter(): void {
   setScreenChangeReporter((location) => {
     lifecycle.reportActivity();
     const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
     notifyAnchorScreenChange(screenKey);
     anchorChangeTicker.notify();
+    const identified = core.getUserId() != null;
     if (__DEV__) {
-      const identified = core.getUserId() != null;
       // eslint-disable-next-line no-console -- intentional development diagnostic
       console.log(
         '[Userflow] updateScreen',
@@ -155,9 +200,34 @@ function wireScreenChangeReporter(): void {
     }
     // Mirrors web: only pushes UpdateClientContext after identify; before that the
     // location is remembered and included on the next end-user channel join.
-    void core.updateScreen(location).catch(() => {
+    void core.updateScreen(location).catch((error: unknown) => {
       // Screen updates are best-effort; connection drops / rate limits should not
       // surface to the host app's navigation path.
+      if (__DEV__) {
+        // eslint-disable-next-line no-console -- intentional development diagnostic
+        console.warn('[Userflow] updateScreen failed', error);
+      }
+    });
+
+    const attrs = screenViewedAttributes(location);
+    if (!attrs) return;
+    if (!identified) {
+      screenViewedAwaitingIdentify = true;
+      return;
+    }
+    screenViewedAwaitingIdentify = false;
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional development diagnostic
+      console.log('[Userflow] track', SCREEN_VIEWED_EVENT, attrs);
+    }
+    void core.track(SCREEN_VIEWED_EVENT, attrs).catch((error: unknown) => {
+      // Screen views are best-effort; connection drops / rate limits should not
+      // surface to the host app's navigation path. Each accepted screen sends
+      // UpdateClientContext + TrackEvent (two slots of the 100/min cap).
+      if (__DEV__) {
+        // eslint-disable-next-line no-console -- intentional development diagnostic
+        console.warn('[Userflow] track', SCREEN_VIEWED_EVENT, 'failed', error);
+      }
     });
   });
 }
@@ -171,11 +241,20 @@ function wireDeepLinking(): void {
   });
 }
 
+function mergeSystemUserAttributes<T extends Record<string, unknown>>(
+  attributes?: T,
+): (T & Record<string, unknown>) | undefined {
+  return mergeDeviceContextUserAttributes(mergeHostAppVersionUserAttributes(attributes));
+}
+
 async function afterIdentify(): Promise<void> {
   attachFlowSessionEngine(core);
   attachClientConditionEngine(core);
   getPairingController(core).notifyIdentified();
   lifecycle.reportActivity();
+  if (screenViewedAwaitingIdentify) {
+    reportCurrentScreen();
+  }
   try {
     await flushPendingPreviewToken();
   } catch {
@@ -190,6 +269,11 @@ async function afterIdentify(): Promise<void> {
 export const Userflow = {
   /** Validate credentials, store configuration, and wire app-lifecycle handling. */
   init(config: UserflowInitConfig): Promise<UserflowConfig> {
+    cacheHostAppVersionAtInit({
+      ...(config.appVersion !== undefined ? { appVersion: config.appVersion } : {}),
+      ...(config.appBuild !== undefined ? { appBuild: config.appBuild } : {}),
+    });
+    cacheDeviceContextAtInit();
     setHostOnNavigate(config.onNavigate);
     lifecycle.start();
     network.start();
@@ -255,8 +339,9 @@ export const Userflow = {
       resetClientConditionEngine();
       core.setClientConditions([]);
       await clearAnonymousId();
+      armScreenViewedForNextIdentify();
     }
-    await core.identify(userId, attributes, options);
+    await core.identify(userId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
   /** Identify an anonymous user with a stable auto-generated id stored on device. */
@@ -269,8 +354,9 @@ export const Userflow = {
     if (previousId != null && previousId !== anonymousId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
+      armScreenViewedForNextIdentify();
     }
-    await core.identify(anonymousId, attributes, options);
+    await core.identify(anonymousId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
   /**
@@ -291,6 +377,23 @@ export const Userflow = {
     lifecycle.reportActivity();
     return core.group(groupId, attributes, options);
   },
+  /**
+   * Upsert attributes for the current user without re-identifying.
+   * Requires a prior {@link identify}. Flow button "Set user attribute" actions
+   * use this path.
+   */
+  updateUser(attributes?: PublicAttributes): Promise<void> {
+    lifecycle.reportActivity();
+    return core.updateUser(attributes);
+  },
+  /**
+   * Upsert attributes for the current group / membership without re-grouping.
+   * Requires a prior {@link group}.
+   */
+  updateGroup(attributes?: PublicAttributes, options?: UserflowUpdateGroupOptions): Promise<void> {
+    lifecycle.reportActivity();
+    return core.updateGroup(attributes, options);
+  },
   /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
   track(
     name: string,
@@ -308,6 +411,20 @@ export const Userflow = {
   getAttributes(): UserflowAttributes {
     return core.getAttributes();
   },
+  /**
+   * Host app marketing version cached during {@link init}, or `null` before init
+   * or when auto-detection and any init override are unavailable.
+   */
+  getHostAppVersion(): HostAppVersion | null {
+    return getCachedHostAppVersion();
+  },
+  /**
+   * Platform metadata cached during {@link init} (`sdk`, `deviceOs`, `deviceType`),
+   * or `null` before init.
+   */
+  getDeviceContext(): DeviceContext | null {
+    return getCachedDeviceContext();
+  },
   /** The flow session engine (created lazily; attach runs after identify). */
   getFlowSessionEngine() {
     return getFlowSessionEngine(core);
@@ -317,6 +434,7 @@ export const Userflow = {
     resetClientConditionEngine();
     resetFlowSessionEngine();
     core.reset();
+    armScreenViewedForNextIdentify();
     await clearAnonymousId();
   },
   /** Remove app-lifecycle, network, and deep-link subscriptions (call on unmount / teardown). */
@@ -325,6 +443,7 @@ export const Userflow = {
     lifecycle.stop();
     network.stop();
     disableScreenTracking();
+    screenViewedAwaitingIdentify = false;
     stopDeepLinking();
   },
   /**
@@ -359,4 +478,29 @@ export const Userflow = {
   setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void {
     setCustomScrollIntoViewConfig(fn);
   },
+  /**
+   * When true (default), tooltip cutout bands and step-transition exit block
+   * taps on the host app underneath. Pass `false` to restore legacy pass-through
+   * tooltip backdrop behavior (dim bands only; `tooltipTargetBlocked` hole seal
+   * is unchanged). Modals always block. Takes effect on the next surface re-render.
+   */
+  setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void {
+    setSurfaceInteractionBlockingConfig(enabled);
+  },
+  /**
+   * Log the host app's native marketing version (store version), not
+   * {@link SDK_VERSION}, and the platform OS (`ios` / `android` / …).
+   * Prefers `expo-application` / `expo-constants` when present; otherwise reads
+   * `NativeModules.RNDeviceInfo` from the bundled device-info native module.
+   */
+  logHostAppVersion(): void {
+    logHostAppVersionToConsole();
+  },
+  /**
+   * Log cached user-attribute values (`sdk`, `device_os`, `device_type`).
+   * Requires {@link init}; before init, logs that init is required.
+   */
+  logDeviceContext(): void {
+    logDeviceContextToConsole();
+  },
 };

package/src/lifecycle.ts

@@ -51,6 +51,11 @@ export interface LifecycleControllerDeps {
   ensureAlive: () => void;
   /** True while any mid-flow session (live or draft/preview) is on screen. */
   hasActiveSession: () => boolean;
+  /**
+   * Re-fire the current screen view after a real background (away past grace).
+   * Not called for Control Center / biometric blurs inside the grace window.
+   */
+  onScreenResume?: () => void;
   scheduler?: LifecycleScheduler;
   now?: () => number;
   /** Override for tests; defaults to {@link SUSPEND_GRACE_MS}. */
@@ -82,6 +87,7 @@ export class LifecycleController {
   private readonly clearLocalSession: () => void;
   private readonly ensureAlive: () => void;
   private readonly hasActiveSession: () => boolean;
+  private readonly onScreenResume: (() => void) | undefined;
   private readonly scheduler: LifecycleScheduler;
   private readonly now: () => number;
   private readonly suspendGraceMs: number;
@@ -103,6 +109,7 @@ export class LifecycleController {
     this.clearLocalSession = deps.clearLocalSession;
     this.ensureAlive = deps.ensureAlive;
     this.hasActiveSession = deps.hasActiveSession;
+    this.onScreenResume = deps.onScreenResume;
     this.scheduler = deps.scheduler ?? defaultScheduler;
     this.now = deps.now ?? (() => Date.now());
     this.suspendGraceMs = deps.suspendGraceMs ?? SUSPEND_GRACE_MS;
@@ -210,6 +217,7 @@ export class LifecycleController {
     this.resume();
     this.suspended = false;
     this.scheduleIdleTimer();
+    this.onScreenResume?.();
   }
 
   private scheduleGraceTimer(): void {

package/src/navigation/WithUserflowReactNavigation.tsx

@@ -4,13 +4,14 @@ import type {
   NavigationState,
   ParamListBase,
 } from '@react-navigation/native';
-import { cloneElement, isValidElement, useCallback, useEffect } from 'react';
+import { cloneElement, isValidElement, useCallback, useEffect, useRef } from 'react';
 import type React from 'react';
 
 import { handleScreenChange } from '../screenTracker';
 
 import { chainCallbacks } from './chainCallbacks';
 import { getActiveRouteName } from './getActiveRouteName';
+import { isOverlayPresentation, readNavigationPresentation } from './isOverlayPresentation';
 import { setReactNavigationRef } from './openFlowNavigateUrl';
 
 type NavigationContainerChildProps = {
@@ -51,6 +52,7 @@ export function WithUserflowReactNavigation({
   children,
 }: WithUserflowReactNavigationProps): React.ReactElement {
   const navigationRef = useNavigationContainerRef<ParamListBase>();
+  const overlayWasFocusedRef = useRef(false);
 
   useEffect(() => {
     setReactNavigationRef(navigationRef);
@@ -59,18 +61,32 @@ export function WithUserflowReactNavigation({
     };
   }, [navigationRef]);
 
+  const reportFocusedScreen = useCallback(
+    (state?: NavigationState) => {
+      if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
+        overlayWasFocusedRef.current = true;
+        return;
+      }
+      const name = getActiveRouteName(state ?? navigationRef.getRootState());
+      handleScreenChange(
+        name ? { screen: name } : undefined,
+        overlayWasFocusedRef.current ? { force: true } : undefined,
+      );
+      overlayWasFocusedRef.current = false;
+    },
+    [navigationRef],
+  );
+
   const handleReady = useCallback(() => {
     setReactNavigationRef(navigationRef);
-    const name = getActiveRouteName(navigationRef.getRootState());
-    handleScreenChange(name ? { screen: name } : undefined);
-  }, [navigationRef]);
+    reportFocusedScreen();
+  }, [navigationRef, reportFocusedScreen]);
 
   const handleStateChange = useCallback(
     (state?: NavigationState) => {
-      const name = getActiveRouteName(state ?? navigationRef.getRootState());
-      handleScreenChange(name ? { screen: name } : undefined);
+      reportFocusedScreen(state);
     },
-    [navigationRef],
+    [reportFocusedScreen],
   );
 
   if (!isValidElement(children)) {