@userflow-tech/react-native 0.4.4 → 0.5.0

package/src/screenTracker.ts

@@ -24,6 +24,17 @@ function locationKey(location: ClientLocationUpdate): string {
   return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
 }
 
+/**
+ * The screen id stored on an AUTO envelope (`path` for Expo Router, `screen`
+ * otherwise). Missing or blank locations are `'unknown'`, the same sentinel
+ * the element picker writes when it has not seen a screen yet.
+ */
+export function screenIdFromLocation(location: ClientLocationUpdate | null | undefined): string {
+  if (!location) return 'unknown';
+  const id = 'path' in location ? location.path : location.screen;
+  return id || 'unknown';
+}
+
 /** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
 export function screenViewedAttributes(
   location: ClientLocationUpdate,

package/src/surfaces/BannerBar.tsx

@@ -11,14 +11,18 @@ import { Animated, Pressable, StyleSheet, Text, View } from 'react-native';
 import { BannerStepButton } from '../content/BannerStepButton';
 import { RichContentRenderer } from '../content/RichContentRenderer';
 import { mixThemeColors } from '../content/themeColor';
+import { usePushBannerHostInsetRegistration } from '../runtime/pushBannerLayoutContext';
 
 import {
   BANNER_CLOSE_SLOT_SIZE,
   BANNER_ROOT_PADDING,
+  bannerBarRootStyle,
   bannerFrameStyle,
   bannerInnerStyle,
+  bannerPushLayoutChrome,
   resolveBannerBarBorderRadius,
 } from './bannerBarLayout';
+import { useUserflowSafeAreaInsets } from './safeArea';
 import {
   BANNER_BUTTON_GAP,
   BANNER_CLOSE_BORDER_RADIUS,
@@ -28,6 +32,8 @@ import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from './re
 
 export interface BannerBarProps {
   session: BannerSessionFragment;
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -38,6 +44,8 @@ export interface BannerBarProps {
  */
 export function BannerBar({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerBarProps): React.ReactElement | null {
@@ -50,10 +58,20 @@ export function BannerBar({
     [theme, backgroundColor, foregroundColor],
   );
   const lookupAttribute = React.useMemo(() => genSessionDataLookup(session.data), [session.data]);
-  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+  const insets = useUserflowSafeAreaInsets();
+  const overlay = banner?.overlay !== false;
+  const hostInsetEdge = !overlay && pushLayoutEdge ? pushLayoutEdge : null;
+  const safeAreaEdge = hostInsetEdge ?? overlaySafeEdge ?? null;
+  const onPushChromeLayout = usePushBannerHostInsetRegistration(
+    hostInsetEdge,
+    session.id,
+    hostInsetEdge != null,
+  );
+  const fadeIn = banner?.animate === true && hostInsetEdge == null;
+  const opacity = React.useRef(new Animated.Value(fadeIn ? 0 : 1)).current;
 
   React.useEffect(() => {
-    if (!banner?.animate) {
+    if (!fadeIn) {
       opacity.setValue(1);
       return;
     }
@@ -67,73 +85,93 @@ export function BannerBar({
     return () => {
       animation.stop();
     };
-  }, [banner?.animate, opacity, session.id]);
+  }, [fadeIn, opacity, session.id]);
 
   if (!banner) return null;
 
-  const overlay = banner.overlay !== false;
   const frameStyle = bannerFrameStyle(banner);
+  const rootStyle = bannerBarRootStyle(banner);
   const innerStyle = bannerInnerStyle(banner);
   const closePressedBackground = mixThemeColors(backgroundColor, foregroundColor, 0.12);
   const overlayEdge = banner.embedMode === BannerEmbedMode.BODY_LAST ? 'bottom' : 'top';
   const barRadius = resolveBannerBarBorderRadius(banner);
+  const insetChrome = safeAreaEdge
+    ? bannerPushLayoutChrome(safeAreaEdge, insets, backgroundColor)
+    : null;
+  const insetChromeOutsideFade = insetChrome != null && fadeIn;
 
-  return (
-    <View testID="userflow-banner-frame" style={frameStyle}>
-      <Animated.View style={[{ opacity }, overlay ? bannerOverlayShadowStyle(overlayEdge) : null]}>
-        <View
-          testID="userflow-banner"
-          style={[
-            styles.root,
-            { backgroundColor },
-            barRadius != null ? { borderRadius: barRadius, overflow: 'hidden' as const } : null,
-          ]}
-        >
-          <View style={styles.startSpacer} />
-          <View style={innerStyle}>
-            <View style={styles.content}>
-              <RichContentRenderer
-                content={banner.content}
-                buttons={[]}
+  const bar = (
+    <View
+      testID="userflow-banner"
+      style={[
+        styles.root,
+        rootStyle,
+        { backgroundColor },
+        barRadius != null ? { borderRadius: barRadius, overflow: 'hidden' as const } : null,
+      ]}
+    >
+      <View style={styles.startSpacer} />
+      <View style={innerStyle}>
+        <View style={styles.content}>
+          <RichContentRenderer
+            content={banner.content}
+            buttons={[]}
+            theme={bannerTheme}
+            sessionData={session.data}
+            lookupAttribute={lookupAttribute}
+            onActions={onActions}
+          />
+        </View>
+        {banner.buttons.length > 0 ? (
+          <View style={styles.buttons}>
+            {banner.buttons.map((button) => (
+              <BannerStepButton
+                key={button.id}
+                button={button}
                 theme={bannerTheme}
                 sessionData={session.data}
-                lookupAttribute={lookupAttribute}
                 onActions={onActions}
               />
-            </View>
-            {banner.buttons.length > 0 ? (
-              <View style={styles.buttons}>
-                {banner.buttons.map((button) => (
-                  <BannerStepButton
-                    key={button.id}
-                    button={button}
-                    theme={bannerTheme}
-                    sessionData={session.data}
-                    onActions={onActions}
-                  />
-                ))}
-              </View>
-            ) : null}
+            ))}
           </View>
-          {session.version.closeDisabled ? (
-            <View style={styles.startSpacer} />
-          ) : (
-            <Pressable
-              testID="userflow-banner-dismiss"
-              accessibilityRole="button"
-              accessibilityLabel="Dismiss"
-              hitSlop={8}
-              onPress={() => onDismiss(EndFlowReasonInput.USER_CLOSED)}
-              style={({ pressed }) => [
-                styles.close,
-                pressed ? { backgroundColor: closePressedBackground } : null,
-              ]}
-            >
-              <Text style={[styles.dismissIcon, { color: foregroundColor }]}>×</Text>
-            </Pressable>
-          )}
-        </View>
-      </Animated.View>
+        ) : null}
+      </View>
+      {session.version.closeDisabled ? (
+        <View style={styles.startSpacer} />
+      ) : (
+        <Pressable
+          testID="userflow-banner-dismiss"
+          accessibilityRole="button"
+          accessibilityLabel="Dismiss"
+          hitSlop={8}
+          onPress={() => onDismiss(EndFlowReasonInput.USER_CLOSED)}
+          style={({ pressed }) => [
+            styles.close,
+            pressed ? { backgroundColor: closePressedBackground } : null,
+          ]}
+        >
+          <Text style={[styles.dismissIcon, { color: foregroundColor }]}>×</Text>
+        </Pressable>
+      )}
+    </View>
+  );
+
+  const animatedBar = (
+    <Animated.View
+      onLayout={hostInsetEdge ? onPushChromeLayout : undefined}
+      style={[
+        { opacity },
+        overlay ? bannerOverlayShadowStyle(overlayEdge) : null,
+        insetChromeOutsideFade ? null : insetChrome,
+      ]}
+    >
+      {bar}
+    </Animated.View>
+  );
+
+  return (
+    <View testID="userflow-banner-frame" style={frameStyle}>
+      {insetChromeOutsideFade ? <View style={insetChrome}>{animatedBar}</View> : animatedBar}
     </View>
   );
 }

package/src/surfaces/BannerSurface.tsx

@@ -15,6 +15,10 @@ import { bannerNeedsWebView } from './bannerWebView/bannerNeedsWebView';
 
 export interface BannerSurfaceProps {
   session: BannerSessionFragment;
+  /** When set, the banner pushes host layout and fills the safe-area inset on this edge. */
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  /** Overlay host edge — paints safe-area padding without pushing layout. */
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -27,6 +31,8 @@ let warnedMissingWebView = false;
  */
 export function BannerSurface({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerSurfaceProps): React.ReactElement | null {
@@ -35,6 +41,34 @@ export function BannerSurface({
   const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
   const webView = needsWebView ? getEvalJsWebView() : null;
 
+  React.useEffect(() => {
+    if (!banner || !__DEV__) {
+      return;
+    }
+    // eslint-disable-next-line no-console -- intentional development diagnostic
+    console.log('[Userflow] banner shown', {
+      flowId: session.flow.id,
+      flowName: session.flow.name,
+      bannerSessionId: session.id,
+      versionId: session.version.id,
+      embedMode: banner.embedMode,
+      overlay: banner.overlay !== false,
+      webView: needsWebView,
+      pushLayoutEdge: pushLayoutEdge ?? null,
+      overlaySafeEdge: overlaySafeEdge ?? null,
+      hostAsOverlay: banner.overlay !== false || needsWebView,
+    });
+  }, [
+    banner,
+    needsWebView,
+    overlaySafeEdge,
+    pushLayoutEdge,
+    session.flow.id,
+    session.flow.name,
+    session.id,
+    session.version.id,
+  ]);
+
   React.useLayoutEffect(() => {
     if (!needsWebView || !webView) {
       return;
@@ -69,13 +103,35 @@ export function BannerSurface({
           );
         }
       }
-      return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+      return (
+        <BannerBar
+          session={session}
+          pushLayoutEdge={pushLayoutEdge}
+          overlaySafeEdge={overlaySafeEdge}
+          onActions={onActions}
+          onDismiss={onDismiss}
+        />
+      );
     }
     return (
-      <BannerWebViewBar session={session} onActions={onActions} onDismiss={dismissWebViewBanner} />
+      <BannerWebViewBar
+        session={session}
+        pushLayoutEdge={pushLayoutEdge}
+        overlaySafeEdge={overlaySafeEdge}
+        onActions={onActions}
+        onDismiss={dismissWebViewBanner}
+      />
     );
   }
-  return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+  return (
+    <BannerBar
+      session={session}
+      pushLayoutEdge={pushLayoutEdge}
+      overlaySafeEdge={overlaySafeEdge}
+      onActions={onActions}
+      onDismiss={onDismiss}
+    />
+  );
 }
 
 /** @internal */

package/src/surfaces/TooltipSurface.tsx

@@ -1,9 +1,10 @@
 import type { FlowSessionEngine } from '@userflow-tech/core';
-import type {
-  EndFlowReasonInput,
-  FlowSessionFragment,
-  FlowStepFragment,
-  ThemeFragment,
+import {
+  decodeMobileAutoData,
+  type EndFlowReasonInput,
+  type FlowSessionFragment,
+  type FlowStepFragment,
+  type ThemeFragment,
 } from '@userflow-tech/protocol';
 import * as React from 'react';
 import {
@@ -20,6 +21,7 @@ import {
 import { anchorRegistry } from '../anchors/AnchorRegistry';
 import { autoAnchorRegistry } from '../anchors/AutoAnchorRegistry';
 import { addAnimationFrameCallback, removeAnimationFrameCallback } from '../anchors/animationFrame';
+import { isAppActive, subscribeAppActive } from '../anchors/appActive';
 import { fiberScanRoot } from '../anchors/fiber/FiberScanRoot';
 import type { AnyFiber } from '../anchors/fiber/fiberInternals';
 import { clipToScrollViewports } from '../anchors/fiber/visibleRect';
@@ -27,6 +29,7 @@ import {
   clearFiberAnchorCache,
   invalidateFiberAnchor,
   resolveAnchorHost,
+  subscribeAnchorScreenChange,
 } from '../anchors/resolveAnchorHost';
 import { resolveAutoAnchorHost } from '../anchors/resolveAutoAnchorHost';
 import { resolveManualAnchorId } from '../anchors/resolveManualAnchorId';
@@ -42,6 +45,7 @@ import { MADE_WITH_USERFLOW_GAP, MadeWithUserflow } from './MadeWithUserflow';
 import { ProgressBar } from './ProgressBar';
 import { ABSOLUTE_FILL } from './absoluteFill';
 import { useCardTransitionPhase } from './cardTransition';
+import { stepTrapsHostAccessibility } from './hostAccessibilityTrap';
 import { parseBackdropOpacity } from './parseBackdropOpacity';
 import { resolveStepProgress } from './progress';
 import { resolveCloseButtonColor } from './resolveCloseButtonColor';
@@ -77,6 +81,7 @@ import {
   tooltipSideGap,
   tooltipVerticalGap,
 } from './tooltip/resolveSideCardWidth';
+import { TargetSearchSchedule } from './tooltip/targetSearchSchedule';
 
 export interface TooltipSurfaceProps {
   engine: FlowSessionEngine;
@@ -94,10 +99,6 @@ export interface TooltipSurfaceProps {
 
 type MissingMode = 'waiting' | 'reported';
 
-/** Interval for re-resolving a missing / remounted anchor (not for live measure). */
-const RESOLVE_MS = 250;
-/** Slower resolve poll after FLAG/ERROR report so a late-mounting target can recover. */
-const RESOLVE_SLOW_MS = 1000;
 /**
  * One-frame delay before the first resolve after a step/reset so dialog
  * teardown cannot arm the missing-target timer with a 0-size measure.
@@ -162,6 +163,11 @@ export function TooltipSurface({
   const selector = currentStep.selector;
   const isAuto = (selector?.type as string | null) === 'AUTO';
   const autoData = selector?.autoData ?? null;
+  // Decoded once per step rather than on every search.
+  const decodedAutoData = React.useMemo(
+    () => (isAuto ? decodeMobileAutoData(autoData) : null),
+    [isAuto, autoData],
+  );
   const anchorId = isAuto ? null : resolveManualAnchorId(selector?.css);
   const targetKey = isAuto ? `auto:${autoData ?? ''}` : (anchorId ?? '');
   const highlight = currentStep.backdrop ? resolveHighlightChrome(theme, backdropPadding) : null;
@@ -191,7 +197,6 @@ export function TooltipSurface({
     desiredPlacement ?? 'BELOW',
   );
   const [missingMode, setMissingMode] = React.useState<MissingMode>('waiting');
-  const [registryTick, setRegistryTick] = React.useState(0);
   /** True after at least one *failed* measure for the current step/anchor. */
   const [measureAttempted, setMeasureAttempted] = React.useState(false);
   /**
@@ -272,18 +277,6 @@ export function TooltipSurface({
     };
   }, []);
 
-  React.useEffect(() => {
-    const bump = () => setRegistryTick((n) => n + 1);
-    const unsubRegistry = anchorRegistry.subscribe(bump);
-    const unsubAuto = autoAnchorRegistry.subscribe(bump);
-    const unsubScan = fiberScanRoot.subscribe(bump);
-    return () => {
-      unsubRegistry();
-      unsubAuto();
-      unsubScan();
-    };
-  }, []);
-
   React.useEffect(() => {
     reportedRef.current = false;
     scrollAttemptsRef.current = 0;
@@ -426,14 +419,14 @@ export function TooltipSurface({
   );
 
   /**
-   * Resolve the anchor host (registry / fiber scan). Used by the interval and
-   * on registry ticks — intentionally NOT on every animation frame.
+   * Resolve the anchor host (registry / fiber scan). Driven by
+   * {@link TargetSearchSchedule} — intentionally NOT on every animation frame.
    */
   const resolveTarget = React.useCallback(() => {
     if (!mountedRef.current) return;
 
     const resolution = isAuto
-      ? resolveAutoAnchorHost(autoData)
+      ? resolveAutoAnchorHost(decodedAutoData)
       : anchorId
         ? resolveAnchorHost(anchorId)
         : null;
@@ -474,7 +467,7 @@ export function TooltipSurface({
       maybeScrollIntoView(rect);
       applyTarget(rect);
     });
-  }, [anchorId, applyTarget, autoData, dropHost, isAuto, maybeScrollIntoView]);
+  }, [anchorId, applyTarget, decodedAutoData, dropHost, isAuto, maybeScrollIntoView]);
 
   /**
    * Live re-measure of an already-resolved host. Driven by the shared rAF hub
@@ -509,45 +502,60 @@ export function TooltipSurface({
     });
   }, [applyTarget, dropHost, maybeScrollIntoView]);
 
+  const resolveTargetRef = React.useRef(resolveTarget);
+  resolveTargetRef.current = resolveTarget;
+  const searchRef = React.useRef<TargetSearchSchedule | null>(null);
+  const searchAllowsRecovery =
+    behavior === 'FLAG' || behavior === 'ERROR' || (behavior === 'END' && session.draftMode);
+  const searchStopped = missingMode === 'reported' && !searchAllowsRecovery;
+
+  // Target search: steady poll while anchored, backoff while missing, nothing
+  // while the app is in the background. Live measurement is on rAF. A new step
+  // or target restarts it right away; a same-step restart (`resetNonce`) goes
+  // through `resolveArmed`, after the first-resolve delay.
   React.useEffect(() => {
-    if (!resolveArmed) return;
-    resolveTarget();
-  }, [resolveTarget, registryTick, resolveArmed]);
-
-  // Resolve poll: recover missing / remounted anchors. Live measurement is on rAF.
-  React.useEffect(() => {
-    if (!resolveArmed) {
+    if (!resolveArmed || searchStopped) {
       return;
     }
-    const allowsRecovery =
-      behavior === 'FLAG' || behavior === 'ERROR' || (behavior === 'END' && session.draftMode);
-    const pauseAfterReport = missingMode === 'reported' && !allowsRecovery;
-
-    if (pauseAfterReport) {
-      return;
-    }
-
-    resolveTarget();
-    const intervalMs = missingMode === 'reported' ? RESOLVE_SLOW_MS : RESOLVE_MS;
-    const handle = setInterval(resolveTarget, intervalMs);
-    const dimSub = Dimensions.addEventListener('change', resolveTarget);
+    const search = new TargetSearchSchedule(() => resolveTargetRef.current());
+    searchRef.current = search;
+    search.setMode(targetRef.current ? 'anchored' : 'missing');
+
+    const trigger = () => search.trigger();
+    const unsubscribers = [
+      anchorRegistry.subscribe(trigger),
+      autoAnchorRegistry.subscribe(trigger),
+      fiberScanRoot.subscribe(trigger),
+      subscribeAnchorScreenChange(() => search.rearm()),
+      subscribeAppActive((active) => (active ? search.resume() : search.pause())),
+    ];
+    if (!isAppActive()) search.pause();
+    search.runNow();
+
+    const dimSub = Dimensions.addEventListener('change', () => search.runNow());
     const onKeyboardShow = (event: { endCoordinates?: { height?: number } }) => {
       setKeyboardBottomInset(Math.max(0, event.endCoordinates?.height ?? 0));
-      resolveTarget();
+      search.runNow();
     };
     const onKeyboardHide = () => {
       setKeyboardBottomInset(0);
-      resolveTarget();
+      search.runNow();
     };
     const kbShow = Keyboard.addListener('keyboardDidShow', onKeyboardShow);
     const kbHide = Keyboard.addListener('keyboardDidHide', onKeyboardHide);
     return () => {
-      clearInterval(handle);
+      for (const unsubscribe of unsubscribers) unsubscribe();
       dimSub.remove();
       kbShow.remove();
       kbHide.remove();
+      search.dispose();
+      if (searchRef.current === search) searchRef.current = null;
     };
-  }, [resolveTarget, missingMode, behavior, session.draftMode, resolveArmed]);
+  }, [resolveArmed, searchStopped, currentStep.id, targetKey]);
+
+  React.useEffect(() => {
+    searchRef.current?.setMode(target ? 'anchored' : 'missing');
+  }, [target]);
 
   // rAF tracking while a host is resolved (and we are not paused after report).
   React.useEffect(() => {
@@ -864,6 +872,9 @@ export function TooltipSurface({
 
   const showBranding = session.flow.company.flowBranding;
   const contentPadding = chrome.contentPadding;
+  // Modal only while the host is trapped too. Otherwise VoiceOver would skip
+  // the host app, including the target this step asks the user to press.
+  const cardIsModal = stepTrapsHostAccessibility(currentStep);
 
   // Still pending the first measure attempt — only the blocker shows.
   if (isMissing && missingMode === 'waiting' && !measureAttempted) {
@@ -877,7 +888,7 @@ export function TooltipSurface({
         <View style={[styles.center, centerPaddingStyle]} pointerEvents="box-none">
           <CardFade
             testID="userflow-tooltip-waiting"
-            accessibilityViewIsModal
+            accessibilityViewIsModal={cardIsModal}
             pointerEvents="auto"
             style={[
               chrome.shadowStyle,
@@ -990,7 +1001,7 @@ export function TooltipSurface({
         <View style={[styles.center, centerPaddingStyle]} pointerEvents="box-none">
           <CardFade
             testID="userflow-tooltip-card"
-            accessibilityViewIsModal
+            accessibilityViewIsModal={cardIsModal}
             pointerEvents="auto"
             onLayout={onCardLayout}
             style={[
@@ -1032,6 +1043,7 @@ export function TooltipSurface({
         onLayout={onCardLayout}
         maxHeight={layout.maxCardHeight}
         showNotch={layout.showNotch}
+        accessibilityViewIsModal={cardIsModal}
         style={{
           position: 'absolute',
           left: layout.cardPosition.x,

package/src/surfaces/bannerBarLayout.ts

@@ -3,10 +3,12 @@ import { BannerContentLayout } from '@userflow-tech/protocol';
 import type { ViewStyle } from 'react-native';
 
 import {
+  BANNER_CLOSE_SLOT_SIZE,
   BANNER_INNER_COLUMN_GAP,
   BANNER_INNER_MARGIN_HORIZONTAL,
   BANNER_INNER_ROW_GAP,
   BANNER_OVERLAY_SCREEN_INSET_HORIZONTAL,
+  BANNER_ROOT_PADDING,
 } from './bannerBarTokens';
 import type { EdgeInsets } from './safeArea';
 
@@ -16,13 +18,50 @@ function optionalMargin(value: number | null | undefined): number | undefined {
   return value == null ? undefined : value;
 }
 
+/** Fixed horizontal chrome inside the embed width (padding, close/spacer slots, inner margins). */
+export function bannerHorizontalChromeWidth(): number {
+  return BANNER_ROOT_PADDING * 2 + BANNER_CLOSE_SLOT_SIZE * 2 + BANNER_INNER_MARGIN_HORIZONTAL * 2;
+}
+
+/** Outer bar cap — max embed width only (max content width limits the inner row on web). */
+export function resolveBannerFrameMaxWidth(banner: BannerFragment): number | null {
+  return banner.maxWidth;
+}
+
+export function bannerHasMaxContentWidth(banner: BannerFragment): boolean {
+  return banner.maxContentWidth != null;
+}
+
+/**
+ * Cap for the native inner row and WebView HTML `.userflowjs-banner-inner` only.
+ * Returns null when max content width is unset. May be 0 when embed width is narrower than chrome.
+ */
+export function resolveBannerInnerMaxWidth(banner: BannerFragment): number | null {
+  if (!bannerHasMaxContentWidth(banner)) {
+    return null;
+  }
+  let cap = banner.maxContentWidth!;
+  if (banner.maxWidth != null) {
+    const embedInnerCap = Math.max(0, banner.maxWidth - bannerHorizontalChromeWidth());
+    cap = Math.min(cap, embedInnerCap);
+  }
+  return cap;
+}
+
 /** Outer frame: max embed width and builder outer margin (web `userflowjs-banner-frame`). */
 export function bannerFrameStyle(banner: BannerFragment): ViewStyle {
-  const hasMaxWidth = banner.maxWidth != null;
+  const frameMaxWidth = resolveBannerFrameMaxWidth(banner);
+  const hasFrameCap = frameMaxWidth != null;
 
   return {
-    alignSelf: hasMaxWidth ? 'center' : 'stretch',
-    ...(hasMaxWidth ? { maxWidth: banner.maxWidth! } : null),
+    alignSelf: hasFrameCap ? 'center' : 'stretch',
+    ...(hasFrameCap
+      ? {
+          maxWidth: frameMaxWidth!,
+          width: '100%' as const,
+          overflow: 'hidden' as const,
+        }
+      : null),
     marginTop: optionalMargin(banner.marginTop),
     marginRight: optionalMargin(banner.marginRight),
     marginBottom: optionalMargin(banner.marginBottom),
@@ -56,12 +95,45 @@ export function bannerInnerJustifyContent(
   }
 }
 
+/**
+ * Push-layout chrome: safe-area pad + bar background on the same node as the
+ * fade so an animated banner does not leave a visible status-bar strip at opacity 0.
+ */
+export function bannerPushLayoutChrome(
+  edge: 'top' | 'bottom',
+  insets: EdgeInsets,
+  backgroundColor: string,
+): ViewStyle {
+  return {
+    backgroundColor,
+    paddingTop: edge === 'top' ? insets.top : 0,
+    paddingBottom: edge === 'bottom' ? insets.bottom : 0,
+  };
+}
+
+/** Matches web `.userflowjs-banner-inner { flex(1000000) }` vs start-spacer `flex(1)`. */
+const BANNER_INNER_FLEX_GROW = 1_000_000;
+
+/** Painted bar (`userflow-banner`) — fill the frame so max embed width clips chrome, not just margins. */
+export function bannerBarRootStyle(banner: BannerFragment): ViewStyle {
+  if (resolveBannerFrameMaxWidth(banner) == null) {
+    return {};
+  }
+  return {
+    width: '100%',
+    maxWidth: '100%',
+  };
+}
+
 export function bannerInnerStyle(banner: BannerFragment): ViewStyle {
-  const hasMaxContentWidth = banner.maxContentWidth != null;
+  const hasMaxContentWidth = bannerHasMaxContentWidth(banner);
+  const innerMaxWidth = resolveBannerInnerMaxWidth(banner);
   return {
-    flexGrow: 1,
+    // Web `.userflowjs-banner-inner { flex(1000000) }` — grow with shrink so text wraps and close stays visible.
+    flexGrow: BANNER_INNER_FLEX_GROW,
     flexShrink: 1,
-    flexBasis: 0,
+    // `auto` avoids the old `flexBasis: 0` + inner `width: 100%` sliver; `minWidth: 0` lets shrink wrap text.
+    flexBasis: hasMaxContentWidth ? ('auto' as const) : 0,
     flexDirection: 'row',
     flexWrap: 'wrap',
     alignItems: 'center',
@@ -69,6 +141,7 @@ export function bannerInnerStyle(banner: BannerFragment): ViewStyle {
     rowGap: BANNER_INNER_ROW_GAP,
     marginHorizontal: BANNER_INNER_MARGIN_HORIZONTAL,
     justifyContent: bannerInnerJustifyContent(banner.contentLayout),
-    ...(hasMaxContentWidth ? { maxWidth: banner.maxContentWidth!, width: '100%' } : null),
+    minWidth: hasMaxContentWidth ? 0 : undefined,
+    ...(innerMaxWidth != null && innerMaxWidth > 0 ? { maxWidth: innerMaxWidth } : null),
   };
 }