@userflow-tech/react-native 0.4.5 → 0.6.0

package/src/navigation/navigateUrlUtils.ts

@@ -0,0 +1,100 @@
+const ABSOLUTE_WEB_URL = /^https?:\/\//i;
+
+/** Hostname.tld with optional port, path, query, or hash — not an in-app screen name like `Profile`. */
+const BARE_EXTERNAL_HOST =
+  /^[\w.-]+\.[a-z]{2,}(?::\d+)?(?:\/[^\s?#]*)?(?:\?[^\s#]*)?(?:#[^\s]*)?$/i;
+
+function isAllowlistedWebUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (!ABSOLUTE_WEB_URL.test(trimmed) && !/^mailto:/i.test(trimmed) && !/^tel:/i.test(trimmed)) {
+    return false;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return (
+      parsed.protocol === 'http:' ||
+      parsed.protocol === 'https:' ||
+      parsed.protocol === 'mailto:' ||
+      parsed.protocol === 'tel:'
+    );
+  } catch {
+    return ABSOLUTE_WEB_URL.test(trimmed);
+  }
+}
+
+/** Fix common builder typos before classification (`https:/google.com`). */
+export function normalizeNavigateUrlInput(url: string): string {
+  const trimmed = url.trim();
+  return trimmed.replace(/^(https?):\/(?!\/)/i, '$1://');
+}
+
+/** Prefix `https://` when the builder URL omitted the scheme (e.g. `google.com`). */
+export function normalizeExternalNavigateUrl(url: string): string {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (ABSOLUTE_WEB_URL.test(trimmed)) {
+    return trimmed;
+  }
+  if (BARE_EXTERNAL_HOST.test(trimmed) && !trimmed.startsWith('/')) {
+    return `https://${trimmed}`;
+  }
+  return trimmed;
+}
+
+/** True when the URL should open outside the app (browser / mail / tel). */
+export function shouldOpenExternalNavigateUrl(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) {
+    return false;
+  }
+  if (isAllowlistedWebUrl(trimmed)) {
+    return true;
+  }
+  if (ABSOLUTE_WEB_URL.test(trimmed)) {
+    return true;
+  }
+  if (/^mailto:/i.test(trimmed) || /^tel:/i.test(trimmed)) {
+    return true;
+  }
+  if (BARE_EXTERNAL_HOST.test(trimmed) && !trimmed.startsWith('/')) {
+    return true;
+  }
+  return false;
+}
+
+/** True for http(s) / mailto / tel (external). */
+export function isExternalNavigateUrl(url: string): boolean {
+  return shouldOpenExternalNavigateUrl(url);
+}
+
+/** Path-like in-app URL: leading slash, or no scheme. */
+export function isInAppNavigateUrl(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) return false;
+  if (shouldOpenExternalNavigateUrl(trimmed)) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
+  return true;
+}
+
+/** Never pass absolute / external URLs to Expo Router `push`. */
+export function mustNotUseExpoRouterPush(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) return false;
+  if (shouldOpenExternalNavigateUrl(trimmed)) return true;
+  if (trimmed.includes('://')) return true;
+  return false;
+}
+
+export function normalizeInAppPath(url: string): string {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (trimmed.startsWith('/')) return trimmed;
+  return `/${trimmed}`;
+}
+
+export function routeNameFromPath(path: string): string {
+  const normalized = normalizeInAppPath(path).replace(/^\//, '');
+  const [first] = normalized.split(/[/?#]/);
+  return first || normalized;
+}

package/src/navigation/openExternalNavigateUrl.ts

@@ -0,0 +1,9 @@
+import { openSafeUrl } from '../content/openSafeUrl';
+
+import { normalizeExternalNavigateUrl } from './navigateUrlUtils';
+
+/** Open http(s)/mailto/tel via Linking (documented SDK behavior). */
+export async function openExternalNavigateUrl(url: string): Promise<void> {
+  const external = normalizeExternalNavigateUrl(url);
+  await openSafeUrl(external);
+}

package/src/navigation/openFlowNavigateUrl.ts

@@ -1,9 +1,18 @@
 import type { NavigationContainerRef, ParamListBase } from '@react-navigation/native';
-import { Linking } from 'react-native';
 
-import { isSafeUrl, openSafeUrl } from '../content/openSafeUrl';
+import { isSafeUrl } from '../content/openSafeUrl';
 import { isolateAsync, isolateSync } from '../runtime/isolateCall';
 
+import {
+  isInAppNavigateUrl,
+  mustNotUseExpoRouterPush,
+  normalizeInAppPath,
+  normalizeNavigateUrlInput,
+  routeNameFromPath,
+  shouldOpenExternalNavigateUrl,
+} from './navigateUrlUtils';
+import { openExternalNavigateUrl } from './openExternalNavigateUrl';
+
 export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
 
 export type ExpoRouterLike = {
@@ -31,38 +40,19 @@ export function setExpoRouterNavigator(router: ExpoRouterLike | null | undefined
   expoRouter = router ?? null;
 }
 
-/** True for http(s) / mailto / tel (external). */
-export function isExternalNavigateUrl(url: string): boolean {
-  return isSafeUrl(url);
-}
-
-/** Path-like in-app URL: leading slash, or no scheme. */
-export function isInAppNavigateUrl(url: string): boolean {
-  const trimmed = url.trim();
-  if (!trimmed) return false;
-  if (isExternalNavigateUrl(trimmed)) return false;
-  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
-  return true;
-}
-
-function normalizeInAppPath(url: string): string {
-  const trimmed = url.trim();
-  if (trimmed.startsWith('/')) return trimmed;
-  return `/${trimmed}`;
-}
-
-function routeNameFromPath(path: string): string {
-  const normalized = normalizeInAppPath(path).replace(/^\//, '');
-  const [first] = normalized.split(/[/?#]/);
-  return first || normalized;
-}
+export {
+  isExternalNavigateUrl,
+  isInAppNavigateUrl,
+  normalizeExternalNavigateUrl,
+  shouldOpenExternalNavigateUrl,
+} from './navigateUrlUtils';
 
 /**
  * Open a flow NAVIGATE url.
  *
  * Priority:
  * 1. Host `onNavigate` (custom schemes / exotic routing)
- * 2. External allowlisted schemes → Linking / `openSafeUrl`
+ * 2. External allowlisted schemes → in-app browser / Linking
  * 3. Path-like → Expo Router `push` or React Navigation `navigate`
  * 4. Fallback → Linking (best-effort)
  *
@@ -72,9 +62,18 @@ function routeNameFromPath(path: string): string {
  * `@userflow-tech/react-native/expo-router` under `UserflowProvider`.
  */
 export async function openFlowNavigateUrl(url: string): Promise<void> {
-  const trimmed = url.trim();
+  const trimmed = normalizeNavigateUrlInput(url);
   if (!trimmed) return;
 
+  if (__DEV__) {
+    // eslint-disable-next-line no-console -- intentional development diagnostic
+    console.log('[Userflow] NAVIGATE openFlowNavigateUrl', {
+      url: trimmed,
+      external: shouldOpenExternalNavigateUrl(trimmed),
+      inApp: isInAppNavigateUrl(trimmed),
+    });
+  }
+
   if (hostOnNavigate) {
     await isolateAsync('onNavigate', async () => {
       await hostOnNavigate!(trimmed);
@@ -82,13 +81,17 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
     return;
   }
 
-  if (isExternalNavigateUrl(trimmed)) {
-    await openSafeUrl(trimmed);
+  if (shouldOpenExternalNavigateUrl(trimmed)) {
+    await openExternalNavigateUrl(trimmed);
     return;
   }
 
   if (isInAppNavigateUrl(trimmed)) {
     if (expoRouter) {
+      if (mustNotUseExpoRouterPush(trimmed)) {
+        await openExternalNavigateUrl(trimmed);
+        return;
+      }
       isolateSync('onNavigate', () => {
         expoRouter!.push(normalizeInAppPath(trimmed));
       });
@@ -104,11 +107,8 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
     }
   }
 
-  // Last resort — may fail for custom schemes; hosts should set onNavigate.
-  try {
-    await Linking.openURL(trimmed);
-  } catch {
-    // Best-effort.
+  if (isSafeUrl(trimmed) || /^https?:\/\//i.test(trimmed)) {
+    await openExternalNavigateUrl(trimmed);
   }
 }
 

package/src/pairing/PairingController.ts

@@ -46,6 +46,11 @@ export interface PairingControllerOptions {
   tokenStore?: PairingTokenStore;
   /** Clear mid-flow session when exiting preview. */
   clearLocalSession?: () => void;
+  /**
+   * Runs before a Builder preview start is sent on the end-user channel.
+   * Defaults to {@link clearLocalSession} when omitted.
+   */
+  prepareForBuilderPreviewStart?: () => void | Promise<void>;
   /** End the previewed draft on the server when exiting preview. */
   endDraftSession?: () => Promise<void>;
   /**
@@ -84,6 +89,7 @@ export class PairingController {
   private readonly LinkingModule: NonNullable<PairingControllerOptions['LinkingModule']>;
   private readonly AppStateModule: NonNullable<PairingControllerOptions['AppStateModule']>;
   private readonly clearLocalSession: (() => void) | undefined;
+  private readonly prepareForBuilderPreviewStart: (() => void | Promise<void>) | undefined;
   private readonly endDraftSession: (() => Promise<void>) | undefined;
   private readonly cancelPendingDraftEnd: (() => void) | undefined;
   private readonly core: UserflowCore;
@@ -122,6 +128,7 @@ export class PairingController {
     this.LinkingModule = options.LinkingModule ?? Linking;
     this.AppStateModule = options.AppStateModule ?? AppState;
     this.clearLocalSession = options.clearLocalSession ?? undefined;
+    this.prepareForBuilderPreviewStart = options.prepareForBuilderPreviewStart ?? undefined;
     this.endDraftSession = options.endDraftSession ?? undefined;
     this.cancelPendingDraftEnd = options.cancelPendingDraftEnd ?? undefined;
     this.logger = options.logger ?? defaultPairingLogger;
@@ -596,7 +603,8 @@ export class PairingController {
         ...(this.pairingDeviceId !== null ? { device_id: this.pairingDeviceId } : {}),
       }),
       onBeforePreviewStart: () => {
-        this.clearLocalSession?.();
+        const run = this.prepareForBuilderPreviewStart ?? this.clearLocalSession;
+        return run?.();
       },
     });
 

package/src/runtime/BannerHost.tsx

@@ -1,11 +1,10 @@
 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 { bannerNeedsWebView } from '../surfaces/bannerWebView/bannerNeedsWebView';
 import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
 
 import { SdkErrorBoundary } from './SdkErrorBoundary';
@@ -50,53 +49,72 @@ export function BannerHost({
   if (edgeFilter && edge !== edgeFilter) return null;
 
   const floats = banner.overlay !== false;
-  if ((placement === 'overlay') !== floats) return null;
+  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 banner).
+  const overlaySafeEdge = hostAsOverlay && !floats ? edge : null;
+
+  const surface = (
+    <BannerSurface
+      session={session}
+      pushLayoutEdge={pushLayoutEdge}
+      overlaySafeEdge={overlaySafeEdge}
+      onActions={(actions) => engine.handleActions(actions)}
+      onDismiss={(endReason) => {
+        void engine.endBanner(endReason);
+      }}
+    />
+  );
 
   const bar = (
     <SdkErrorBoundary scope="banner" resetKey={session.id}>
-      <BannerSurface
-        session={session}
-        onActions={(actions) => engine.handleActions(actions)}
-        onDismiss={(endReason) => {
-          void engine.endBanner(endReason);
-        }}
-      />
+      {placement === 'flow' ? (
+        <View testID="userflow-banner-flow" style={styles.flow}>
+          {surface}
+        </View>
+      ) : (
+        surface
+      )}
     </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>
-    );
+    return bar;
   }
 
-  const edgeStyle = edge === 'top' ? { top: insets.top } : { bottom: insets.bottom };
+  const edgeStyle =
+    edge === 'top' ? { top: floats ? insets.top : 0 } : { bottom: floats ? insets.bottom : 0 };
 
   return (
     <View
       pointerEvents="box-none"
       style={[styles.pin, edgeStyle, bannerOverlayHostPadding(insets)]}
     >
-      {bar}
+      <View pointerEvents="auto" style={styles.pinInteractive}>
+        {bar}
+      </View>
     </View>
   );
 }
 
-function bannerBackground(session: BannerSessionFragment): string {
-  return resolveBannerBackgroundColor(session.version.theme);
-}
-
 const styles = StyleSheet.create({
   pin: {
     position: 'absolute',
     left: 0,
     right: 0,
+    zIndex: 10,
+    elevation: 10,
   },
   flow: {
     alignSelf: 'stretch',
   },
+  pinInteractive: {
+    alignSelf: 'stretch',
+  },
 });

package/src/runtime/TargetPressBridge.tsx

@@ -2,10 +2,12 @@ import * as React from 'react';
 import { StyleSheet, View, type GestureResponderEvent } from 'react-native';
 
 import { elementTapMonitor } from '../anchors/elementTapMonitor';
+import type { AnyFiber } from '../anchors/fiber/fiberInternals';
 import { touchBelongsToEvent, touchTargetFiber } from '../anchors/fiber/touchTargetFiber';
-import { targetPressMonitor } from '../anchors/targetPressMonitor';
+import { collectGestureHandlerTags } from '../anchors/gestureHandlerHandoff';
+import { targetPressMonitor, type TouchIdentifier } from '../anchors/targetPressMonitor';
 
-import { changedTouchPoints, forEachChangedTouch } from './changedTouchPoints';
+import { forEachChangedTouch } from './changedTouchPoints';
 import { isolateSync } from './isolateCall';
 
 export interface TargetPressBridgeProps {
@@ -25,6 +27,9 @@ export interface TargetPressBridgeProps {
  * Preview-chrome double taps are observed by `DoubleTapBridge` around the
  * whole provider tree — this bridge never sees overlay touches.
  *
+ * A touch that gesture-handler cancels is not dropped. The start is kept and
+ * counts as a tap if that handler later ends from ACTIVE.
+ *
  * Does not claim the gesture responder.
  */
 export function TargetPressBridge({ children }: TargetPressBridgeProps): React.ReactElement {
@@ -57,15 +62,23 @@ export function TargetPressBridge({ children }: TargetPressBridgeProps): React.R
 
   const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {
     isolateSync('target-press', () => {
-      const points = changedTouchPoints(event);
-      if (points.length === 0) {
-        targetPressMonitor.cancelTouch();
-        elementTapMonitor.cancelTouch();
+      const changed = event.nativeEvent.changedTouches;
+      if (!changed || changed.length === 0) {
+        const identifiers = inProgressIdentifiers();
+        if (identifiers.length === 0) {
+          targetPressMonitor.cancelTouch();
+          elementTapMonitor.cancelTouch();
+          return;
+        }
+        // No per-finger target on this event; every finger shares its view.
+        const fallback = touchTargetFiber(event);
+        for (const identifier of identifiers) {
+          handOffCancelledTouch(event, identifier, fallback);
+        }
         return;
       }
-      for (const touch of points) {
-        targetPressMonitor.cancelTouch(touch.identifier);
-        elementTapMonitor.cancelTouch(touch.identifier);
+      for (const touch of changed) {
+        handOffCancelledTouch(event, touch.identifier, null);
       }
     });
   }, []);
@@ -84,6 +97,50 @@ export function TargetPressBridge({ children }: TargetPressBridgeProps): React.R
   );
 }
 
+/**
+ * A finger gesture-handler cancelled. Keep it if the touched view belongs to a
+ * gesture-handler control. A scroll container, or a touch with no handler, is
+ * dropped the way a system cancel is.
+ * `fallbackFiber` is used when this event names no per-finger target.
+ */
+function handOffCancelledTouch(
+  event: GestureResponderEvent,
+  identifier: TouchIdentifier,
+  fallbackFiber: AnyFiber | null,
+): void {
+  const elementHas = elementTapMonitor.hasTouch(identifier);
+  const tooltipHas = targetPressMonitor.hasTouch(identifier);
+  if (!elementHas && !tooltipHas) {
+    elementTapMonitor.cancelTouch(identifier);
+    targetPressMonitor.cancelTouch(identifier);
+    return;
+  }
+  const stored = elementHas ? elementTapMonitor.startFiber(identifier) : null;
+  const fiber = stored ?? fallbackFiber ?? touchTargetFiber(event, identifier);
+  const tags = collectGestureHandlerTags(fiber);
+  if (tags.length === 0) {
+    elementTapMonitor.cancelTouch(identifier);
+    targetPressMonitor.cancelTouch(identifier);
+    return;
+  }
+  if (elementHas) elementTapMonitor.handOffTouch(identifier, tags);
+  if (tooltipHas) targetPressMonitor.handOffTouch(identifier, tags);
+}
+
+function inProgressIdentifiers(): TouchIdentifier[] {
+  const seen = new Set<TouchIdentifier>();
+  const identifiers: TouchIdentifier[] = [];
+  for (const identifier of [
+    ...elementTapMonitor.inProgressIdentifiers(),
+    ...targetPressMonitor.inProgressIdentifiers(),
+  ]) {
+    if (seen.has(identifier)) continue;
+    seen.add(identifier);
+    identifiers.push(identifier);
+  }
+  return identifiers;
+}
+
 const styles = StyleSheet.create({
   root: {
     flex: 1,

package/src/runtime/UserflowOverlay.tsx

@@ -8,6 +8,7 @@ import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
 import { getPairingController } from '../pairing/pairingRuntime';
 import { usePairingState } from '../pairing/usePairingState';
 import { usePreviewBarHold } from '../pairing/usePreviewBarHold';
+import { stepTrapsHostAccessibility } from '../surfaces/hostAccessibilityTrap';
 
 import { BannerHost } from './BannerHost';
 import { FlowRenderer } from './FlowRenderer';
@@ -57,14 +58,7 @@ export function UserflowOverlay({
     if (!session || !currentStep) {
       return false;
     }
-    const appearance = String(currentStep.appearance).toUpperCase();
-    if (appearance === 'HIDDEN') {
-      return false;
-    }
-    if (appearance !== 'TOOLTIP') {
-      return true;
-    }
-    return currentStep.tooltipTargetBlocked;
+    return stepTrapsHostAccessibility(currentStep);
   }, [pickerActive, previewConfirming, session, currentStep]);
 
   React.useLayoutEffect(() => {
@@ -105,13 +99,17 @@ export function UserflowOverlay({
        * captureScreen would otherwise include the modal or tooltip.
        * Remounting reads the same session back.
        */}
-      <BannerHost engine={bannerEngine} hidden={pickerActive} />
       {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} />
       <ElementPickerOverlay />
     </>
   );

package/src/runtime/UserflowProvider.tsx

@@ -15,15 +15,15 @@ import type { EdgeInsets } from '../surfaces/safeArea';
 import { SurfaceLayoutInsetsProvider } from '../surfaces/surfaceLayoutInsets';
 
 import { BannerHost } from './BannerHost';
+import { BannerWebViewFlowSpacer } from './bannerFlowSpacer';
 import { SdkErrorBoundary } from './SdkErrorBoundary';
 import { TargetPressBridge } from './TargetPressBridge';
 import { UserflowOverlay } from './UserflowOverlay';
 import { getBannerSessionEngine } from './bannerEngine';
 import { BannerEngineContext } from './bannerEngineContext';
-import { bannerEdge } from './bannerPlacement';
 import { getFlowSessionEngine } from './flowEngine';
+import { PushBannerLayoutProvider, type PushBannerLayoutEdge } from './pushBannerLayoutContext';
 import { isolateSync } from './isolateCall';
-import { useBannerSession } from './useBannerSession';
 import { getUserflowCore } from './userflowCore';
 
 export interface UserflowContextValue {
@@ -122,8 +122,9 @@ export function UserflowProvider({
   const onOverlayError = React.useCallback(() => {
     setTrapHostAccessibility(false);
   }, []);
-  const bannerSession = useBannerSession(bannerEngine);
   const safeInsets = useUserflowSafeAreaInsets();
+  const [pushBannerLayoutEdge, setPushBannerLayoutEdge] =
+    React.useState<PushBannerLayoutEdge | null>(null);
   const [pickerActive, setPickerActive] = React.useState(
     () => elementPickerController.getState().active,
   );
@@ -134,15 +135,12 @@ export function UserflowProvider({
     });
   }, []);
 
-  const banner = bannerSession?.version.banner ?? null;
-  const flowEdge =
-    banner && banner.overlay === false && !pickerActive ? bannerEdge(banner.embedMode) : null;
   const hostInsets: EdgeInsets | null =
-    flowEdge === 'top' || flowEdge === 'bottom'
+    pushBannerLayoutEdge === 'top' || pushBannerLayoutEdge === 'bottom'
       ? {
           ...safeInsets,
-          top: flowEdge === 'top' ? 0 : safeInsets.top,
-          bottom: flowEdge === 'bottom' ? 0 : safeInsets.bottom,
+          top: pushBannerLayoutEdge === 'top' ? 0 : safeInsets.top,
+          bottom: pushBannerLayoutEdge === 'bottom' ? 0 : safeInsets.bottom,
         }
       : null;
 
@@ -163,31 +161,44 @@ export function UserflowProvider({
     <BannerEngineContext.Provider value={bannerEngine}>
       <UserflowContext.Provider value={contextValue}>
         <SurfaceLayoutInsetsProvider>
-          <DoubleTapBridge>
-            <View style={styles.root} collapsable={false} testID="userflow-root">
-              <BannerHost engine={bannerEngine} placement="flow" edge="top" hidden={pickerActive} />
-              <HostSafeArea insets={hostInsets}>{appContent}</HostSafeArea>
-              <BannerHost
-                engine={bannerEngine}
-                placement="flow"
-                edge="bottom"
-                hidden={pickerActive}
-              />
-              <View style={styles.overlay} pointerEvents="box-none">
-                <SdkErrorBoundary
-                  scope="overlay"
-                  resetKey={overlayResetKey}
-                  onError={onOverlayError}
-                >
-                  <UserflowOverlay
-                    engine={engine}
-                    bannerEngine={bannerEngine}
-                    onTrapChange={onTrapChange}
+          <PushBannerLayoutProvider onActiveEdgeChange={setPushBannerLayoutEdge}>
+            <DoubleTapBridge>
+              <View style={styles.root} collapsable={false} testID="userflow-root">
+                <View style={styles.flowBannerTop}>
+                  <BannerHost
+                    engine={bannerEngine}
+                    placement="flow"
+                    edge="top"
+                    hidden={pickerActive}
                   />
-                </SdkErrorBoundary>
+                  <BannerWebViewFlowSpacer engine={bannerEngine} edge="top" />
+                </View>
+                <HostSafeArea insets={hostInsets}>{appContent}</HostSafeArea>
+                <View style={styles.flowBannerBottom}>
+                  <BannerHost
+                    engine={bannerEngine}
+                    placement="flow"
+                    edge="bottom"
+                    hidden={pickerActive}
+                  />
+                  <BannerWebViewFlowSpacer engine={bannerEngine} edge="bottom" />
+                </View>
+                <View style={styles.overlay} pointerEvents="box-none">
+                  <SdkErrorBoundary
+                    scope="overlay"
+                    resetKey={overlayResetKey}
+                    onError={onOverlayError}
+                  >
+                    <UserflowOverlay
+                      engine={engine}
+                      bannerEngine={bannerEngine}
+                      onTrapChange={onTrapChange}
+                    />
+                  </SdkErrorBoundary>
+                </View>
               </View>
-            </View>
-          </DoubleTapBridge>
+            </DoubleTapBridge>
+          </PushBannerLayoutProvider>
         </SurfaceLayoutInsetsProvider>
       </UserflowContext.Provider>
     </BannerEngineContext.Provider>
@@ -228,7 +239,20 @@ const styles = StyleSheet.create({
   appContent: {
     flex: 1,
   },
+  flowBannerTop: {
+    zIndex: 1,
+    elevation: 1,
+    pointerEvents: 'box-none',
+  },
+  flowBannerBottom: {
+    zIndex: 1,
+    elevation: 1,
+    pointerEvents: 'box-none',
+  },
   overlay: {
     ...ABSOLUTE_FILL,
+    // Above flow banner slots so WebView banners receive touches (spacers are layout-only).
+    zIndex: 2,
+    elevation: 2,
   },
 });