@userflow-tech/react-native 0.1.0

package/src/index.ts

@@ -0,0 +1,362 @@
+/**
+ * @userflow-tech/react-native — public API for the Userflow React Native SDK.
+ *
+ * Exposes the `Userflow` singleton host apps import. Auth/identity and the
+ * transport live in `@userflow-tech/core`; this binding is a thin facade that
+ * delegates to the core engine, wires React Native app lifecycle
+ * (background/foreground + idle) to the connection, hosts the flow session
+ * engine + provider overlay for Phase 3 rendering, and tracks screen changes.
+ */
+
+import type {
+  UserflowAttributes,
+  UserflowConfig,
+  UserflowEventAttributes,
+  UserflowGroupOptions,
+  UserflowIdentifyOptions,
+  UserflowInitOptions,
+  UserflowTrackOptions,
+} from '@userflow-tech/core';
+
+import './anchors/autoAnchor';
+import { anchorChangeTicker } from './anchors/anchorChangeTicker';
+import { notifyAnchorScreenChange } from './anchors/resolveAnchorHost';
+import {
+  setCustomScrollIntoView as setCustomScrollIntoViewConfig,
+  setScrollPadding as setScrollPaddingConfig,
+  type CustomScrollIntoView,
+  type ScrollPadding,
+} from './anchors/scrollConfig';
+import { clearAnonymousId, getOrCreateAnonymousId } from './anonymousId';
+import {
+  didHandleURL,
+  flushPendingPreviewToken,
+  startDeepLinking,
+  stopDeepLinking,
+} from './deepLinking';
+import { LifecycleController } from './lifecycle';
+import { setHostOnNavigate, type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
+import { NetworkController } from './network';
+import { getPairingController, installPairingController } from './pairing/pairingRuntime';
+import {
+  attachClientConditionEngine,
+  resetClientConditionEngine,
+} from './runtime/clientConditions';
+import {
+  attachFlowSessionEngine,
+  clearFlowSessionEngineLocalSession,
+  getFlowSessionEngine,
+  hasActiveFlowSession,
+  resetFlowSessionEngine,
+} from './runtime/flowEngine';
+import { getUserflowCore } from './runtime/userflowCore';
+import {
+  disableScreenTracking,
+  enableScreenTracking,
+  handleScreenChange,
+  setScreenChangeReporter,
+} from './screenTracker';
+
+export { SDK_VERSION } from './version';
+export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
+export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
+export { useFlowSessionState } from './runtime/useFlowSessionState';
+export type { FlowSessionState } from './runtime/useFlowSessionState';
+export { useUserflowScreen } from './useUserflowScreen';
+export { useUserflowAnchor } from './anchors/useUserflowAnchor';
+export { __userflowAutoAnchor } from './anchors/autoAnchor';
+export { useUserflowScrollContainer } from './anchors/useUserflowScrollContainer';
+export type { UserflowScrollContainerProps } from './anchors/useUserflowScrollContainer';
+export type {
+  CustomScrollIntoView,
+  ScrollIntoViewTarget,
+  ScrollPadding,
+} from './anchors/scrollConfig';
+export {
+  INACTIVITY_TIMEOUT_MS,
+  SESSION_STALE_AFTER_BACKGROUND_MS,
+  SUSPEND_GRACE_MS,
+} from './lifecycle';
+export {
+  inspectPairingDeepLink,
+  isPairingAttempt,
+  parsePairingDeepLink,
+  isUserflowPairingUrl,
+  PreviewModeBanner,
+} from './pairing';
+export type {
+  PairingAttemptRejection,
+  PairingDeepLink,
+  PairingDeepLinkRejection,
+  PairingDeepLinkResult,
+} from './pairing';
+
+/** Configuration passed to {@link Userflow.init}. */
+export type UserflowInitConfig = UserflowInitOptions & {
+  /**
+   * Optional host handler for flow NAVIGATE actions. When set, wins over
+   * React Navigation / Expo Router / Linking.
+   */
+  onNavigate?: FlowNavigateHandler;
+  /**
+   * Override the US-pinned Builder pairing websocket host (local/staging).
+   * Defaults to `https://e.userflow.com`.
+   */
+  pairingEndpoint?: string;
+};
+
+export type {
+  UserflowAttributes,
+  UserflowConfig,
+  UserflowEventAttributes,
+  UserflowGroupOptions,
+  UserflowIdentifyOptions,
+  UserflowInitOptions,
+  UserflowTrackOptions,
+} from '@userflow-tech/core';
+
+const core = getUserflowCore();
+
+const lifecycle = new LifecycleController({
+  suspend: () => core.suspend(),
+  resume: () => {
+    core.resume();
+    // After reconnect, flush mid-flow client messages that failed while offline.
+    void getFlowSessionEngine(core).flushPendingSends();
+  },
+  clearLocalSession: () => {
+    clearFlowSessionEngineLocalSession();
+    // Engine may not exist yet; still clear any transport join resume id.
+    core.setFlowSessionId(null);
+  },
+  ensureAlive: () => core.ensureAlive(),
+  hasActiveSession: () => hasActiveFlowSession(),
+});
+
+const network = new NetworkController({
+  // Probe if still "connected" (half-open) or reconnect eagerly if already dropped.
+  ensureAlive: () => core.ensureAlive(),
+});
+
+function wireScreenChangeReporter(): void {
+  setScreenChangeReporter((location) => {
+    lifecycle.reportActivity();
+    const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
+    notifyAnchorScreenChange(screenKey);
+    anchorChangeTicker.notify();
+    if (__DEV__) {
+      const identified = core.getUserId() != null;
+      // eslint-disable-next-line no-console -- intentional development diagnostic
+      console.log(
+        '[Userflow] updateScreen',
+        location,
+        identified ? '(push UpdateClientContext)' : '(buffered until identify)',
+      );
+    }
+    // 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(() => {
+      // Screen updates are best-effort; connection drops / rate limits should not
+      // surface to the host app's navigation path.
+    });
+  });
+}
+
+wireScreenChangeReporter();
+
+function wireDeepLinking(): void {
+  startDeepLinking({
+    isIdentified: () => core.getUserId() != null,
+    startFlowWithToken: (token) => core.startFlowWithToken(token),
+  });
+}
+
+async function afterIdentify(): Promise<void> {
+  attachFlowSessionEngine(core);
+  attachClientConditionEngine(core);
+  getPairingController(core).notifyIdentified();
+  lifecycle.reportActivity();
+  try {
+    await flushPendingPreviewToken();
+  } catch {
+    // Preview start is best-effort; identify must still succeed for the host app.
+  }
+}
+
+/**
+ * Public SDK entry point. Delegates to the platform-agnostic engine in
+ * `@userflow-tech/core` and manages the app-lifecycle subscription.
+ */
+export const Userflow = {
+  /** Validate credentials, store configuration, and wire app-lifecycle handling. */
+  init(config: UserflowInitConfig): Promise<UserflowConfig> {
+    setHostOnNavigate(config.onNavigate);
+    lifecycle.start();
+    network.start();
+    wireScreenChangeReporter();
+    wireDeepLinking();
+    // Builder pairing (QR deep links) — active in all builds.
+    //
+    // Listeners attach *before* core.init so an inbound QR link is captured even
+    // when init is still in flight or ends up rejecting. The OS launches the app
+    // from the deep link regardless of SDK state, so a listener installed only on
+    // the success path makes a failed init look like a broken deep link.
+    const pairing = installPairingController(core, {
+      ...(config.pairingEndpoint !== undefined ? { pairingEndpoint: config.pairingEndpoint } : {}),
+      clearLocalSession: () => {
+        clearFlowSessionEngineLocalSession();
+        core.setFlowSessionId(null);
+      },
+    });
+    pairing.notifyInitStarted();
+    void pairing.start();
+
+    return core.init(config).then(
+      async (resolved) => {
+        enableScreenTracking();
+        await pairing.notifyInitialized();
+        return resolved;
+      },
+      (error: unknown) => {
+        pairing.notifyInitFailed(error);
+        throw error;
+      },
+    );
+  },
+  /**
+   * Forward a Userflow pairing deep link into the SDK.
+   * Prefer automatic Linking interception from {@link Userflow.init}; use this
+   * when the host app owns URL routing.
+   */
+  handlePairingUrl(url: string): Promise<boolean> {
+    return getPairingController(core).handleUrl(url);
+  },
+  /** Exit Builder preview mode and disconnect the pairing websocket. */
+  exitPreview(): Promise<void> {
+    return getPairingController(core).exitPreview();
+  },
+  /**
+   * Override or clear the host NAVIGATE handler (same as `init({ onNavigate })`).
+   * Wins over React Navigation / Expo Router / Linking when set.
+   */
+  setOnNavigate(handler: FlowNavigateHandler | null | undefined): void {
+    setHostOnNavigate(handler);
+  },
+  /** Identify the current user and upsert their attributes. */
+  async identify(
+    userId: string,
+    attributes?: UserflowAttributes,
+    options?: UserflowIdentifyOptions,
+  ): Promise<void> {
+    const previousId = core.getUserId();
+    // Clear before join so the new channel is not seeded with another user's
+    // client-condition snapshot.
+    if (previousId != null && previousId !== userId) {
+      resetClientConditionEngine();
+      core.setClientConditions([]);
+      await clearAnonymousId();
+    }
+    await core.identify(userId, attributes, options);
+    await afterIdentify();
+  },
+  /** Identify an anonymous user with a stable auto-generated id stored on device. */
+  async identifyAnonymous(
+    attributes?: UserflowAttributes,
+    options?: UserflowIdentifyOptions,
+  ): Promise<void> {
+    const anonymousId = await getOrCreateAnonymousId();
+    const previousId = core.getUserId();
+    if (previousId != null && previousId !== anonymousId) {
+      resetClientConditionEngine();
+      core.setClientConditions([]);
+    }
+    await core.identify(anonymousId, attributes, options);
+    await afterIdentify();
+  },
+  /**
+   * Handle an inbound URL. Returns `true` when it was a Userflow preview deep
+   * link (`userflow-*://?token=...`).
+   * Prefer letting {@link init} auto-listen; call this when the host app already
+   * owns Linking.
+   */
+  didHandleURL(url: string): Promise<boolean> {
+    return didHandleURL(url);
+  },
+  /** Associate the current user with a group and upsert group/membership attributes. */
+  group(
+    groupId: string | number,
+    attributes?: UserflowAttributes,
+    options?: UserflowGroupOptions,
+  ): Promise<void> {
+    lifecycle.reportActivity();
+    return core.group(groupId, attributes, options);
+  },
+  /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
+  track(
+    name: string,
+    attributes?: UserflowEventAttributes,
+    options?: UserflowTrackOptions,
+  ): Promise<void> {
+    lifecycle.reportActivity();
+    return core.track(name, attributes, options);
+  },
+  /** The currently identified user id, or `null` before identify. */
+  getUserId(): string | null {
+    return core.getUserId();
+  },
+  /** A copy of the attributes recorded for the current user. */
+  getAttributes(): UserflowAttributes {
+    return core.getAttributes();
+  },
+  /** The flow session engine (created lazily; attach runs after identify). */
+  getFlowSessionEngine() {
+    return getFlowSessionEngine(core);
+  },
+  /** Clears the current user identity and disconnects from Userflow. */
+  async reset(): Promise<void> {
+    resetClientConditionEngine();
+    resetFlowSessionEngine();
+    core.reset();
+    await clearAnonymousId();
+  },
+  /** Remove app-lifecycle, network, and deep-link subscriptions (call on unmount / teardown). */
+  teardown(): void {
+    getPairingController(core).stop();
+    lifecycle.stop();
+    network.stop();
+    disableScreenTracking();
+    stopDeepLinking();
+  },
+  /**
+   * Signal user activity so the foreground idle timer resets and an
+   * idle-suspended socket reconnects. Prefer automatic signals from
+   * {@link updateScreen} / identify / group; call this for touch or other
+   * host-app activity the SDK does not observe.
+   */
+  reportActivity(): void {
+    lifecycle.reportActivity();
+  },
+  /**
+   * Report the active React Navigation (or manual) screen name. Prefer
+   * {@link useUserflowScreen} in React trees; use this for imperative updates
+   * outside hooks. When a user is identified, pushes `UpdateClientContext`
+   * with `screen` set (Expo Router pathnames use `path` via the Expo helper).
+   */
+  updateScreen(screenName: string | undefined): void {
+    handleScreenChange(screenName ? { screen: screenName } : undefined);
+  },
+  /**
+   * Sticky header/footer insets applied when scrolling tooltip targets into
+   * view (mirrors web `userflow.setScrollPadding`).
+   */
+  setScrollPadding(padding: ScrollPadding | null | undefined): void {
+    setScrollPaddingConfig(padding);
+  },
+  /**
+   * Replace the SDK's scroll-into-view behavior. Pass `null` to restore the
+   * default fiber / registry path (mirrors web `userflow.setCustomScrollIntoView`).
+   */
+  setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void {
+    setCustomScrollIntoViewConfig(fn);
+  },
+};

package/src/lifecycle.ts

@@ -0,0 +1,253 @@
+/**
+ * Mobile connection lifecycle policy.
+ *
+ * - Background / inactive → arm a short grace timer, then suspend the socket.
+ *   Returning to active before grace elapses avoids suspend/resume churn: resume
+ *   if already idle-suspended, otherwise probe liveness (`ensureAlive`) so a
+ *   silently-dead socket recovers without waiting for the next heartbeat.
+ * - Foreground after grace but < {@link SESSION_STALE_AFTER_BACKGROUND_MS}
+ *   (5 min) → resume and keep the mid-flow session (short-background “resume”).
+ * - Foreground after ≥ 5 min → clear local flow session, then resume
+ *   (long-background reconnect without stale mid-flow UI).
+ * - Foreground idle for 5 min → suspend (skip while any flow session is active).
+ * - Activity while foreground → reset idle timer and resume if idle-suspended.
+ *
+ * This 5-minute policy is the ticket meaning of FLOW_RENDERING_SPEC “resume”:
+ * short backgrounds continue the active flow; long backgrounds clear then reconnect.
+ */
+
+import { AppState } from 'react-native';
+import type { AppStateStatus, NativeEventSubscription } from 'react-native';
+
+/** Match web `INACTIVITY_TIMEOUT` — disconnect after this much idle time in foreground. */
+export const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Away this long → drop local mid-flow session before reconnecting. */
+export const SESSION_STALE_AFTER_BACKGROUND_MS = 5 * 60 * 1000;
+
+/**
+ * Delay before suspending on leave. Covers transient iOS `inactive` (Control
+ * Center, biometric prompts, app-switcher peek) and quick app-switches.
+ */
+export const SUSPEND_GRACE_MS = 3_000;
+
+export type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface LifecycleScheduler {
+  setTimeout(handler: () => void, ms: number): TimerHandle;
+  clearTimeout(handle: TimerHandle): void;
+}
+
+export interface LifecycleControllerDeps {
+  suspend: () => void;
+  resume: () => void;
+  clearLocalSession: () => void;
+  /**
+   * Verify the socket is alive without a full suspend/resume. Called on a quick
+   * foreground (blur under grace) when the socket was never lifecycle-suspended
+   * but may have died silently. No-op if the transport is not connected.
+   * Do not call while lifecycle-suspended — use {@link resume} instead.
+   */
+  ensureAlive: () => void;
+  /** True while any mid-flow session (live or draft/preview) is on screen. */
+  hasActiveSession: () => boolean;
+  scheduler?: LifecycleScheduler;
+  now?: () => number;
+  /** Override for tests; defaults to {@link SUSPEND_GRACE_MS}. */
+  suspendGraceMs?: number;
+  /** Override for tests; defaults to React Native `AppState.currentState`. */
+  getCurrentAppState?: () => AppStateStatus;
+  /** Override for tests; defaults to React Native `AppState`. */
+  subscribeAppState?: (handler: (status: AppStateStatus) => void) => () => void;
+}
+
+const defaultScheduler: LifecycleScheduler = {
+  setTimeout: (handler, ms) => setTimeout(handler, ms),
+  clearTimeout: (handle) => clearTimeout(handle),
+};
+
+function defaultSubscribeAppState(handler: (status: AppStateStatus) => void): () => void {
+  const subscription: NativeEventSubscription = AppState.addEventListener('change', handler);
+  return () => subscription.remove();
+}
+
+/**
+ * Owns AppState subscription, background duration tracking, and the foreground
+ * idle timer. Call {@link start} from `Userflow.init` and {@link stop} from
+ * `Userflow.teardown`.
+ */
+export class LifecycleController {
+  private readonly suspend: () => void;
+  private readonly resume: () => void;
+  private readonly clearLocalSession: () => void;
+  private readonly ensureAlive: () => void;
+  private readonly hasActiveSession: () => boolean;
+  private readonly scheduler: LifecycleScheduler;
+  private readonly now: () => number;
+  private readonly suspendGraceMs: number;
+  private readonly getCurrentAppState: () => AppStateStatus;
+  private readonly subscribeAppState: (handler: (status: AppStateStatus) => void) => () => void;
+
+  private unsubscribeAppState: (() => void) | null = null;
+  private idleTimer: TimerHandle | null = null;
+  private graceTimer: TimerHandle | null = null;
+  private backgroundedAt: number | null = null;
+  private appIsActive = true;
+  private started = false;
+  /** True once the grace timer has fired (or we suspended on long-away resume). */
+  private suspended = false;
+
+  constructor(deps: LifecycleControllerDeps) {
+    this.suspend = deps.suspend;
+    this.resume = deps.resume;
+    this.clearLocalSession = deps.clearLocalSession;
+    this.ensureAlive = deps.ensureAlive;
+    this.hasActiveSession = deps.hasActiveSession;
+    this.scheduler = deps.scheduler ?? defaultScheduler;
+    this.now = deps.now ?? (() => Date.now());
+    this.suspendGraceMs = deps.suspendGraceMs ?? SUSPEND_GRACE_MS;
+    this.getCurrentAppState = deps.getCurrentAppState ?? (() => AppState.currentState);
+    this.subscribeAppState = deps.subscribeAppState ?? defaultSubscribeAppState;
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.appIsActive = this.getCurrentAppState() === 'active';
+    this.unsubscribeAppState = this.subscribeAppState((status) => {
+      this.handleAppStateChange(status);
+    });
+    if (this.appIsActive) {
+      this.scheduleIdleTimer();
+    }
+  }
+
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+    this.clearIdleTimer();
+    this.clearGraceTimer();
+    this.unsubscribeAppState?.();
+    this.unsubscribeAppState = null;
+    this.backgroundedAt = null;
+    this.suspended = false;
+  }
+
+  /**
+   * Signal user/SDK activity while the app is foregrounded. Resets the idle
+   * timer and reconnects if the socket was idle-suspended.
+   */
+  reportActivity(): void {
+    if (!this.started || !this.appIsActive) return;
+    this.resume();
+    this.suspended = false;
+    this.scheduleIdleTimer();
+  }
+
+  /** Visible for tests. */
+  handleAppStateChange(status: AppStateStatus): void {
+    if (!this.started) return;
+
+    if (status === 'active') {
+      this.onForeground();
+      return;
+    }
+
+    if (status === 'background' || status === 'inactive') {
+      this.onBackground();
+    }
+  }
+
+  private onBackground(): void {
+    // Already leaving (e.g. inactive → background): keep first timestamp; do not
+    // re-arm the grace timer.
+    if (!this.appIsActive && this.backgroundedAt != null) {
+      return;
+    }
+
+    if (this.appIsActive) {
+      this.backgroundedAt = this.now();
+    } else if (this.backgroundedAt == null) {
+      this.backgroundedAt = this.now();
+    }
+
+    this.appIsActive = false;
+    this.clearIdleTimer();
+    this.scheduleGraceTimer();
+  }
+
+  private onForeground(): void {
+    const awayMs = this.backgroundedAt != null ? this.now() - this.backgroundedAt : 0;
+    this.backgroundedAt = null;
+    this.appIsActive = true;
+    this.clearGraceTimer();
+
+    if (awayMs < this.suspendGraceMs) {
+      // Transient blur / quick switch. If already idle-suspended, resume —
+      // ensureAlive is a no-op while the transport is lifecycle-suspended.
+      // Otherwise probe liveness so a silently-dead socket recovers fast.
+      if (this.suspended) {
+        this.resume();
+        this.suspended = false;
+      } else {
+        this.ensureAlive();
+      }
+      this.scheduleIdleTimer();
+      return;
+    }
+
+    // Away past grace: ensure a clean suspend (covers iOS freezing JS before
+    // the grace timer fired) then resume. Clear mid-flow session if stale.
+    if (!this.suspended) {
+      this.suspend();
+      this.suspended = true;
+    }
+
+    if (awayMs >= SESSION_STALE_AFTER_BACKGROUND_MS) {
+      this.clearLocalSession();
+    }
+
+    this.resume();
+    this.suspended = false;
+    this.scheduleIdleTimer();
+  }
+
+  private scheduleGraceTimer(): void {
+    this.clearGraceTimer();
+    this.graceTimer = this.scheduler.setTimeout(() => {
+      this.graceTimer = null;
+      if (this.appIsActive) return;
+      if (this.suspended) return;
+      this.suspend();
+      this.suspended = true;
+    }, this.suspendGraceMs);
+  }
+
+  private clearGraceTimer(): void {
+    if (this.graceTimer != null) {
+      this.scheduler.clearTimeout(this.graceTimer);
+      this.graceTimer = null;
+    }
+  }
+
+  private scheduleIdleTimer(): void {
+    this.clearIdleTimer();
+    this.idleTimer = this.scheduler.setTimeout(() => {
+      this.idleTimer = null;
+      if (!this.appIsActive) return;
+      if (this.hasActiveSession()) {
+        this.scheduleIdleTimer();
+        return;
+      }
+      this.suspend();
+      this.suspended = true;
+    }, INACTIVITY_TIMEOUT_MS);
+  }
+
+  private clearIdleTimer(): void {
+    if (this.idleTimer != null) {
+      this.scheduler.clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+}

package/src/navigation/WithUserflowReactNavigation.tsx

@@ -0,0 +1,87 @@
+import { useNavigationContainerRef } from '@react-navigation/native';
+import type {
+  NavigationContainerRef,
+  NavigationState,
+  ParamListBase,
+} from '@react-navigation/native';
+import { cloneElement, isValidElement, useCallback, useEffect } from 'react';
+import type React from 'react';
+
+import { handleScreenChange } from '../screenTracker';
+
+import { chainCallbacks } from './chainCallbacks';
+import { getActiveRouteName } from './getActiveRouteName';
+import { setReactNavigationRef } from './openFlowNavigateUrl';
+
+type NavigationContainerChildProps = {
+  ref?: React.Ref<NavigationContainerRef<ParamListBase>>;
+  onReady?: () => void;
+  onStateChange?: (state?: NavigationState) => void;
+};
+
+export interface WithUserflowReactNavigationProps {
+  children: React.ReactElement<NavigationContainerChildProps>;
+}
+
+function assignRef<T>(ref: React.Ref<T> | undefined, value: T | null): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    (ref as React.MutableRefObject<T | null>).current = value;
+  }
+}
+
+function mergeRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T> {
+  return (value) => {
+    for (const ref of refs) {
+      assignRef(ref, value);
+    }
+  };
+}
+
+/**
+ * Wraps a React Navigation `NavigationContainer` to report screen changes to
+ * Userflow after {@link Userflow.init} has completed.
+ *
+ * Also registers the container ref for in-app NAVIGATE actions (path-like URLs).
+ * Screen tracking ≠ action routing — without this wrapper, NAVIGATE falls back to
+ * Linking / host `onNavigate`.
+ */
+export function WithUserflowReactNavigation({
+  children,
+}: WithUserflowReactNavigationProps): React.ReactElement {
+  const navigationRef = useNavigationContainerRef<ParamListBase>();
+
+  useEffect(() => {
+    setReactNavigationRef(navigationRef);
+    return () => {
+      setReactNavigationRef(null);
+    };
+  }, [navigationRef]);
+
+  const handleReady = useCallback(() => {
+    setReactNavigationRef(navigationRef);
+    const name = getActiveRouteName(navigationRef.getRootState());
+    handleScreenChange(name ? { screen: name } : undefined);
+  }, [navigationRef]);
+
+  const handleStateChange = useCallback(
+    (state?: NavigationState) => {
+      const name = getActiveRouteName(state ?? navigationRef.getRootState());
+      handleScreenChange(name ? { screen: name } : undefined);
+    },
+    [navigationRef],
+  );
+
+  if (!isValidElement(children)) {
+    throw new Error('WithUserflowReactNavigation expects a single React element child.');
+  }
+
+  const childProps = children.props;
+
+  return cloneElement(children, {
+    ref: mergeRefs(childProps.ref, navigationRef),
+    onReady: chainCallbacks(childProps.onReady, handleReady) ?? handleReady,
+    onStateChange: chainCallbacks(childProps.onStateChange, handleStateChange) ?? handleStateChange,
+  });
+}