@userflow-tech/react-native 0.4.5 → 0.6.0

package/src/surfaces/bannerWebView/BannerWebViewBar.tsx

@@ -23,11 +23,14 @@ import { getEvalJsWebView, type EvalJsWebViewHandle } from '../../evalJs/getWebV
 import { injectEvalPendingIntoWebView } from '../../evalJs/injectEvalPending';
 import type { EvalJsContext } from '../../evalJs/types';
 import { useEvalJsWebViewInjection } from '../../evalJs/useEvalJsWebViewInjection';
+import { usePushBannerHostInsetRegistration } from '../../runtime/pushBannerLayoutContext';
+import { setBannerFlowSpacerHeight } from '../../runtime/bannerFlowSpacer';
+import { warnBannerOnce } from '../../runtime/bannerPlacement';
 import { getUserflowCore } from '../../runtime/userflowCore';
 import { getCurrentScreenLocation, subscribeScreenLocation } from '../../screenTracker';
 import {
   bannerFrameStyle,
-  bannerInnerStyle,
+  bannerPushLayoutChrome,
   resolveBannerBarBorderRadius,
 } from '../bannerBarLayout';
 import { bannerOverlayShadowStyle } from '../bannerBarTokens';
@@ -39,6 +42,8 @@ import { buildCustomBannerBodyHtml } from './buildCustomBannerHtml';
 
 export interface BannerWebViewBarProps {
   session: BannerSessionFragment;
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -68,14 +73,27 @@ function useEvalJsScreen(): { name?: string; path?: string } {
 
 export function BannerWebViewBar({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerWebViewBarProps): React.ReactElement | null {
   const banner = session.version.banner;
+  const overlay = banner?.overlay !== false;
+  const hostInsetEdge = banner && !overlay && pushLayoutEdge ? pushLayoutEdge : null;
+  const pushLayoutRegistrationEdge =
+    hostInsetEdge ?? (!overlay && overlaySafeEdge ? overlaySafeEdge : null);
+  const safeAreaEdge = hostInsetEdge ?? overlaySafeEdge ?? null;
+  const onPushChromeLayout = usePushBannerHostInsetRegistration(
+    pushLayoutRegistrationEdge,
+    session.id,
+    pushLayoutRegistrationEdge != null,
+  );
   const WebView = getEvalJsWebView();
   const webRef = React.useRef<EvalJsWebViewHandle>(null);
   const [pageReady, setPageReady] = React.useState(false);
   const [contentHeight, setContentHeight] = React.useState(56);
+  const [webLayoutHeight, setWebLayoutHeight] = React.useState<number | null>(null);
   const colorScheme = useColorScheme();
   const viewport = useWindowDimensions();
   const insets = useUserflowSafeAreaInsets();
@@ -104,18 +122,18 @@ export function BannerWebViewBar({
   const serverEndpoint = getUserflowCore().getServerEndpoint() ?? DEFAULT_SERVER_ENDPOINT;
 
   const skipAutoRunEval = shouldSkipBannerAutoRunEval(session.id);
-  const initialContext = React.useRef(context);
   const html = React.useMemo(() => {
     const body = buildCustomBannerBodyHtml(session, lookupAttribute, serverEndpoint, {
       skipAutoRunEval,
     });
-    return buildBootstrapHtml(initialContext.current, body);
-  }, [lookupAttribute, serverEndpoint, session, skipAutoRunEval]);
+    return buildBootstrapHtml(context, body);
+  }, [context, lookupAttribute, serverEndpoint, session, skipAutoRunEval]);
 
-  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+  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;
     }
@@ -129,13 +147,39 @@ export function BannerWebViewBar({
     return () => {
       animation.stop();
     };
-  }, [banner?.animate, opacity, session.id]);
+  }, [fadeIn, opacity, session.id]);
 
   React.useEffect(() => {
     setPageReady(false);
     setContentHeight(56);
+    setWebLayoutHeight(null);
   }, [session.id, html]);
 
+  const reserveFlowSpace = !overlay && overlaySafeEdge != null;
+  React.useEffect(() => {
+    if (!reserveFlowSpace || !overlaySafeEdge) {
+      return;
+    }
+    return () => {
+      setBannerFlowSpacerHeight(overlaySafeEdge, 0);
+    };
+  }, [overlaySafeEdge, reserveFlowSpace, session.id]);
+
+  React.useEffect(() => {
+    if (pushLayoutRegistrationEdge == null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (webLayoutHeight == null) {
+        warnBannerOnce(
+          `push-webview-layout:${session.id}`,
+          'Userflow: push-layout WebView banner did not report a layout height; check custom CSS / WebView logs',
+        );
+      }
+    }, 4000);
+    return () => clearTimeout(timer);
+  }, [pushLayoutRegistrationEdge, session.id, webLayoutHeight]);
+
   React.useEffect(() => {
     if (!pageReady || skipAutoRunEval || !banner) {
       return;
@@ -177,17 +221,23 @@ export function BannerWebViewBar({
             const maxHeight = Math.floor(viewport.height * 0.92);
             const next = Math.min(Math.ceil(height), maxHeight);
             setContentHeight((prev) => (Math.abs(next - prev) <= 1 ? prev : next));
+            setWebLayoutHeight(next);
           }
           return;
         }
         if (record.__userflow === 1 && record.type === 'bannerButton') {
           const buttonId = record.buttonId;
           if (typeof buttonId === 'string' && banner) {
-            const button = banner.buttons.find((entry) => entry.id === buttonId);
+            const button =
+              banner.buttons.find((entry) => entry.id === buttonId) ??
+              banner.buttons.find((entry) => entry.cvid === buttonId);
             if (button) {
               void Promise.resolve(onActions(button.actions)).then(() => {
                 injectEvalPendingIntoWebView(webRef.current);
               });
+            } else if (__DEV__) {
+              // eslint-disable-next-line no-console -- intentional development diagnostic
+              console.warn('[Userflow] banner button not found for id', buttonId);
             }
           }
           return;
@@ -241,72 +291,116 @@ export function BannerWebViewBar({
           return;
       }
     },
-    [banner, onActions, onDismiss, viewport.height],
+    [
+      banner,
+      insets.bottom,
+      insets.top,
+      onActions,
+      onDismiss,
+      overlaySafeEdge,
+      reserveFlowSpace,
+      viewport.height,
+    ],
   );
 
   if (!banner || !WebView) {
     return null;
   }
 
-  const overlay = banner.overlay !== false;
   const frameStyle = bannerFrameStyle(banner);
-  const innerStyle = bannerInnerStyle(banner);
   const overlayEdge = banner.embedMode === BannerEmbedMode.BODY_LAST ? 'bottom' : 'top';
   const barRadius = resolveBannerBarBorderRadius(banner);
+  // Custom CSS paints the card, often with its own radius. The theme color
+  // (brand blue when banner tokens are unset) would otherwise fill the
+  // status-bar pad and the corners outside that radius.
+  const shellBackground = 'transparent';
   const webStyle: ViewStyle = {
     width: '100%',
     height: contentHeight,
-    backgroundColor: 'transparent',
+    backgroundColor: shellBackground,
   };
   const debugging = typeof __DEV__ !== 'undefined' && __DEV__ ? true : undefined;
+  const insetChrome = safeAreaEdge
+    ? bannerPushLayoutChrome(safeAreaEdge, insets, shellBackground)
+    : null;
+  const insetChromeOutsideFade = insetChrome != null && fadeIn;
+
+  const webViewBar = (
+    <View
+      testID="userflow-banner-webview"
+      pointerEvents="auto"
+      style={[{ borderRadius: barRadius ?? 0, overflow: 'hidden' as const }]}
+    >
+      <WebView
+        key={session.id}
+        ref={webRef}
+        source={{ html, baseUrl: EVAL_JS_BASE_URL }}
+        style={webStyle}
+        javaScriptEnabled
+        domStorageEnabled
+        scrollEnabled={false}
+        bounces={false}
+        showsHorizontalScrollIndicator={false}
+        showsVerticalScrollIndicator={false}
+        originWhitelist={['*']}
+        setSupportMultipleWindows={false}
+        androidLayerType="hardware"
+        {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
+        onMessage={onMessage}
+        onLoadEnd={() => {
+          setPageReady(true);
+          webRef.current?.injectJavaScript(
+            'window.__userflowBannerLayout&&window.__userflowBannerLayout();true;',
+          );
+        }}
+        onShouldStartLoadWithRequest={(request) => {
+          if (isBootstrapUrl(request.url)) {
+            return true;
+          }
+          openExternal(request.url);
+          return false;
+        }}
+        onOpenWindow={(event) => {
+          const url = event.nativeEvent.targetUrl;
+          if (url) {
+            openExternal(url);
+          }
+        }}
+      />
+    </View>
+  );
+
+  const animatedBar = (
+    <Animated.View
+      style={[
+        { opacity },
+        overlay ? bannerOverlayShadowStyle(overlayEdge) : null,
+        insetChromeOutsideFade ? null : insetChrome,
+      ]}
+    >
+      {webViewBar}
+    </Animated.View>
+  );
 
   return (
-    <View testID="userflow-banner-frame" style={frameStyle}>
-      <Animated.View style={[{ opacity }, overlay ? bannerOverlayShadowStyle(overlayEdge) : null]}>
-        <View
-          testID="userflow-banner-webview"
-          style={[
-            { borderRadius: barRadius ?? 0, overflow: 'hidden' as const },
-            innerStyle.maxWidth != null ? { maxWidth: innerStyle.maxWidth } : null,
-          ]}
-        >
-          <WebView
-            ref={webRef}
-            source={{ html, baseUrl: EVAL_JS_BASE_URL }}
-            style={webStyle}
-            javaScriptEnabled
-            domStorageEnabled
-            scrollEnabled={false}
-            bounces={false}
-            showsHorizontalScrollIndicator={false}
-            showsVerticalScrollIndicator={false}
-            originWhitelist={['*']}
-            setSupportMultipleWindows={false}
-            androidLayerType="hardware"
-            {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
-            onMessage={onMessage}
-            onLoadEnd={() => {
-              setPageReady(true);
-              webRef.current?.injectJavaScript(
-                'window.__userflowBannerLayout&&window.__userflowBannerLayout();true;',
-              );
-            }}
-            onShouldStartLoadWithRequest={(request) => {
-              if (isBootstrapUrl(request.url)) {
-                return true;
+    <View
+      testID="userflow-banner-frame"
+      style={frameStyle}
+      onLayout={
+        reserveFlowSpace && overlaySafeEdge
+          ? (event) => {
+              onPushChromeLayout(event);
+              const h = event.nativeEvent.layout.height;
+              if (h > 0) {
+                setBannerFlowSpacerHeight(overlaySafeEdge, h);
               }
-              openExternal(request.url);
-              return false;
-            }}
-            onOpenWindow={(event) => {
-              const url = event.nativeEvent.targetUrl;
-              if (url) {
-                openExternal(url);
-              }
-            }}
-          />
-        </View>
-      </Animated.View>
+            }
+          : pushLayoutRegistrationEdge
+            ? onPushChromeLayout
+            : undefined
+      }
+    >
+      {insetChromeOutsideFade ? <View style={insetChrome}>{animatedBar}</View> : animatedBar}
     </View>
   );
 }

package/src/surfaces/bannerWebView/bannerNeedsWebView.ts

@@ -1,38 +1,6 @@
-import type { BannerFragment, ThemeFragment } from '@userflow-tech/protocol';
-import { FlowActionType } from '@userflow-tech/protocol';
+import type { BannerFragment } from '@userflow-tech/protocol';
 
-import { themeHasPublishedCustomCss } from './resolveCdnHost';
-
-let debugForceWebViewBanner = false;
-
-/** POC / local testing when the builder flag is not on the wire yet. */
-export function setDebugForceWebViewBanner(enabled: boolean): void {
-  debugForceWebViewBanner = enabled;
-}
-
-/** @internal */
-export function resetDebugForceWebViewBannerForTests(): void {
-  debugForceWebViewBanner = false;
-}
-
-function bannerHasEvalJsAction(banner: BannerFragment): boolean {
-  return banner.buttons.some((button) =>
-    button.actions.some((action) => action.type === FlowActionType.EVAL_JS),
-  );
-}
-
-/**
- * Use the WebView banner renderer when any button runs Evaluate JavaScript
- * (needs the shared eval page), when the theme has published custom CSS
- * (`.userflow-custom-container-*` / `.userflow-custom-button-*` via CDN),
- * or when {@link setDebugForceWebViewBanner} is true.
- */
-export function bannerNeedsWebView(banner: BannerFragment, theme?: ThemeFragment | null): boolean {
-  if (debugForceWebViewBanner) {
-    return true;
-  }
-  if (theme != null && themeHasPublishedCustomCss(theme)) {
-    return true;
-  }
-  return bannerHasEvalJsAction(banner);
+/** Use the WebView banner renderer when the builder enabled custom banners. */
+export function bannerNeedsWebView(banner: BannerFragment): boolean {
+  return banner.customBannerEnabled === true;
 }

package/src/surfaces/bannerWebView/bannerThemeStyles.ts

@@ -1,5 +1,6 @@
 import type { ThemeFragment } from '@userflow-tech/protocol';
 
+import { contentFontFamilyCss } from '../../content/resolveContentFontFamily';
 import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from '../resolveBannerTheme';
 
 function readString(theme: ThemeFragment, key: string, fallback: string): string {
@@ -68,7 +69,7 @@ export function bannerThemeInlineStyles(theme: ThemeFragment): Record<string, st
       'bannerActiveForegroundColor',
       bannerFg,
     ),
-    '--userflow-font-family': readString(theme, 'fontFamily', 'system-ui, sans-serif'),
+    '--userflow-font-family': contentFontFamilyCss(theme),
     '--userflow-font-size': `${fontSize}px`,
     '--userflow-line-height': `${lineHeight}px`,
     '--userflow-button-height': readCssLength(theme, 'buttonHeight', 32),

package/src/surfaces/bannerWebView/bannerWebViewHeight.ts

@@ -0,0 +1,32 @@
+/**
+ * Height the native WebView should use for a custom banner.
+ *
+ * Custom CSS often sizes the card with `min-height` and takes the copy and
+ * buttons out of flow (`position: absolute`). The WebView is created shorter
+ * than that card, so a root that only looks as tall as the viewport because of
+ * `min-height` must not be replaced with the close button's box.
+ *
+ * When the root really is stretching to fill a taller viewport (`height: 100%`),
+ * fall back to in-flow content, and never below `min-height`.
+ */
+export function resolveBannerWebViewHeight(
+  rectHeight: number,
+  scrollHeight: number,
+  viewportHeight: number,
+  minHeight: number,
+  contentHeight: number,
+): number {
+  const rect = rectHeight > 0 ? rectHeight : 0;
+  const scroll = scrollHeight > 0 ? scrollHeight : 0;
+  let height = Math.ceil(Math.max(rect, scroll));
+  const floor = minHeight > 0 ? Math.ceil(minHeight) : 0;
+  if (viewportHeight > 0 && height >= viewportHeight - 2 && height > floor + 1) {
+    if (contentHeight > 0 && contentHeight < height) {
+      height = Math.ceil(contentHeight > floor ? contentHeight : floor);
+    }
+  }
+  if (floor > height) {
+    height = floor;
+  }
+  return height;
+}

package/src/surfaces/bannerWebView/buildCustomBannerHtml.ts

@@ -2,11 +2,17 @@ import { interpolateVariables } from '@userflow-tech/core';
 import type { BannerFragment, BannerSessionFragment } from '@userflow-tech/protocol';
 import { BannerContentLayout } from '@userflow-tech/protocol';
 
+import {
+  bannerContentFontLockCss,
+  contentFontFaceCss,
+} from '../../content/resolveContentFontFamily';
 import { buildBootstrapHtml, wrapCode } from '../../evalJs/bootstrap';
 import type { EvalJsContext } from '../../evalJs/types';
 
 import { collectBannerAutoRunEvalCodes } from './bannerAutoRunEvalJs';
 import { bannerThemeStyleAttribute } from './bannerThemeStyles';
+import { resolveBannerInnerMaxWidth } from '../bannerBarLayout';
+
 import { BANNER_WEB_FRAME_CSS } from './bannerWebFrameCss';
 import { buttonClassName } from './buttonClassName';
 import { resolveCustomStylesheetUrl } from './resolveCdnHost';
@@ -25,26 +31,45 @@ function contentLayoutClass(layout: BannerContentLayout): string {
 }
 
 function layoutMeasureScript(): string {
+  // Inlined on purpose. Hermes' Function#toString is not the source text, so
+  // interpolating resolveBannerWebViewHeight.toString() ships a dead function.
+  // Keep this body in sync with resolveBannerWebViewHeight.
   return `
 (function(){
+  function resolveBannerWebViewHeight(rectHeight,scrollHeight,viewportHeight,minHeight,contentHeight){
+    var rect=rectHeight>0?rectHeight:0;
+    var scroll=scrollHeight>0?scrollHeight:0;
+    var height=Math.ceil(Math.max(rect,scroll));
+    var floor=minHeight>0?Math.ceil(minHeight):0;
+    if(viewportHeight>0&&height>=viewportHeight-2&&height>floor+1){
+      if(contentHeight>0&&contentHeight<height){
+        height=Math.ceil(contentHeight>floor?contentHeight:floor);
+      }
+    }
+    if(floor>height) height=floor;
+    return height;
+  }
   function postLayout(){
     var root=document.querySelector('.userflowjs-banner-root');
     if(!root||!window.ReactNativeWebView||!window.ReactNativeWebView.postMessage)return;
     var rectH=root.getBoundingClientRect().height;
     var scrollH=root.scrollHeight;
-    var h=Math.ceil(Math.max(scrollH,rectH));
+    var minH=parseFloat(window.getComputedStyle(root).minHeight);
+    if(!(minH>0)) minH=0;
     var vh=window.innerHeight||0;
-    if(vh>0&&h>=vh-2){
-      var sum=0;
-      for(var i=0;i<root.childNodes.length;i++){
-        var node=root.childNodes[i];
-        if(node&&node.nodeType===1){
-          var el=node;
-          sum+=el.scrollHeight||el.offsetHeight||0;
-        }
-      }
-      if(sum>0&&sum<h) h=Math.ceil(sum);
+    var inFlow=0;
+    var all=0;
+    for(var i=0;i<root.childNodes.length;i++){
+      var node=root.childNodes[i];
+      if(!node||node.nodeType!==1) continue;
+      var box=node.scrollHeight||node.offsetHeight||0;
+      all+=box;
+      var cs=window.getComputedStyle(node);
+      if(cs.display==='none'||cs.position==='absolute'||cs.position==='fixed') continue;
+      inFlow+=box;
     }
+    var content=inFlow>0?inFlow:all;
+    var h=resolveBannerWebViewHeight(rectH,scrollH,vh,minH,content);
     window.ReactNativeWebView.postMessage(JSON.stringify({__userflow:1,type:'bannerLayout',height:h}));
   }
   window.__userflowBannerLayout=postLayout;
@@ -52,36 +77,87 @@ function layoutMeasureScript(): string {
     var root=document.querySelector('.userflowjs-banner-root');
     if(root){new ResizeObserver(postLayout).observe(root);}
   }
+  var links=document.querySelectorAll('link[rel="stylesheet"]');
+  for(var s=0;s<links.length;s++){
+    links[s].addEventListener('load',postLayout);
+    links[s].addEventListener('error',postLayout);
+  }
   window.addEventListener('load',postLayout);
+  // Custom CSS is often still applying on the first pass. A short WebView
+  // then clamps used height, so min-height never changes the box and
+  // ResizeObserver does not fire. Measure again after the stylesheet can apply.
   setTimeout(postLayout,0);
+  setTimeout(postLayout,60);
+  setTimeout(postLayout,250);
 })();
 `;
 }
 
-function bannerInteractionScript(): string {
+function bannerInteractionScript(buttonsJson: string): string {
   return `
 (function(){
+  var __userflowBannerButtons=${buttonsJson};
   function post(msg){
     if(window.ReactNativeWebView&&window.ReactNativeWebView.postMessage){
       window.ReactNativeWebView.postMessage(JSON.stringify(Object.assign({__userflow:1},msg)));
     }
   }
-  document.addEventListener('click',function(ev){
+  function resolveButtonId(el){
+    if(!el||!el.closest)return null;
+    var tagged=el.closest('[data-userflow-banner-button]');
+    if(tagged){
+      return tagged.getAttribute('data-userflow-banner-button');
+    }
+    function hasClass(el,token){
+      if(!token)return false;
+      var cls=el.className||'';
+      var parts=cls.split(/\\s+/);
+      for(var p=0;p<parts.length;p++){
+        if(parts[p]===token)return true;
+      }
+      return false;
+    }
+    function appearanceClass(appearance){
+      if(!appearance)return '';
+      var value=appearance;
+      var known=value==='primary'||value==='PRIMARY'||value==='default'||value==='DEFAULT'||value==='banner-primary'||value==='banner-secondary';
+      return known?'userflowjs-bubble-button--'+value.toLowerCase():value;
+    }
+    var bubble=el.closest('.userflowjs-bubble-button,button.userflowjs-bubble-button');
+    if(bubble){
+      var id=bubble.getAttribute('data-userflow-banner-button');
+      if(id)return id;
+      for(var i=0;i<__userflowBannerButtons.length;i++){
+        var meta=__userflowBannerButtons[i];
+        if(meta.appearance&&hasClass(bubble,appearanceClass(meta.appearance)))return meta.id;
+      }
+    }
+    var custom=el.closest('[class*="userflow-custom-button"]');
+    if(custom){
+      for(var j=0;j<__userflowBannerButtons.length;j++){
+        var entry=__userflowBannerButtons[j];
+        if(entry.appearance&&hasClass(custom,appearanceClass(entry.appearance)))return entry.id;
+      }
+    }
+    return null;
+  }
+  function onActivate(ev){
     var t=ev.target;
     if(!t||!t.closest)return;
-    var btn=t.closest('[data-userflow-banner-button]');
-    if(btn){
-      ev.preventDefault();
-      post({type:'bannerButton',buttonId:btn.getAttribute('data-userflow-banner-button')});
-      return;
-    }
     var close=t.closest('[data-userflow-banner-dismiss]');
     if(close){
       ev.preventDefault();
       window.__userflowBannerEvalDismissed=true;
       post({type:'bannerDismiss'});
+      return;
+    }
+    var buttonId=resolveButtonId(t);
+    if(buttonId){
+      ev.preventDefault();
+      post({type:'bannerButton',buttonId:buttonId});
     }
-  });
+  }
+  document.addEventListener('click',onActivate,true);
 })();
 `;
 }
@@ -128,9 +204,12 @@ export function buildCustomBannerBodyHtml(
   const theme = session.version.theme;
   const layoutClass = contentLayoutClass(banner.contentLayout);
   const themeStyle = bannerThemeStyleAttribute(theme);
+  const fontFaceCss = contentFontFaceCss(theme);
+  const fontLockCss = bannerContentFontLockCss(theme);
   const customCssUrl = resolveCustomStylesheetUrl(serverEndpoint, theme);
+  const innerMaxWidth = resolveBannerInnerMaxWidth(banner);
   const maxInner =
-    banner.maxContentWidth != null ? ` style="max-width:${banner.maxContentWidth}px"` : '';
+    innerMaxWidth != null && innerMaxWidth > 0 ? ` style="max-width:${innerMaxWidth}px"` : '';
   const contentHtml = richContentDocToHtml(banner.content, lookupAttribute);
   const buttonsHtml = banner.buttons
     .map((button) => {
@@ -143,13 +222,22 @@ export function buildCustomBannerBodyHtml(
     ? '<div class="userflowjs-banner-start-spacer"></div>'
     : '<button type="button" class="userflowjs-banner-close userflowjs-button-reset" data-userflow-banner-dismiss="1" aria-label="Dismiss">×</button>';
 
+  const buttonMetaJson = JSON.stringify(
+    banner.buttons.map((button) => ({
+      id: button.id,
+      cvid: button.cvid,
+      appearance: button.appearance ?? '',
+    })),
+  ).replace(/</g, '\\u003c');
+
   const customLink = customCssUrl
     ? `<link rel="stylesheet" href="${escapeAttr(customCssUrl)}" />`
     : '';
 
   return `
-<style>${BANNER_WEB_FRAME_CSS}</style>
+<style>${fontFaceCss}${BANNER_WEB_FRAME_CSS}</style>
 ${customLink}
+<style>${fontLockCss}</style>
 <div class="userflowjs-banner-root userflowjs-theme-root ${layoutClass}" style="${themeStyle}">
   <div class="userflowjs-banner-start-spacer"></div>
   <div class="userflowjs-banner-inner"${maxInner}>
@@ -158,7 +246,7 @@ ${customLink}
   </div>
   ${closeHtml}
 </div>
-<script>${layoutMeasureScript()}${bannerInteractionScript()}${options?.skipAutoRunEval ? '' : bannerAutoRunEvalScript(banner, lookupAttribute)}</script>
+<script>${layoutMeasureScript()}${bannerInteractionScript(buttonMetaJson)}${options?.skipAutoRunEval ? '' : bannerAutoRunEvalScript(banner, lookupAttribute)}</script>
 `;
 }
 

package/src/surfaces/hostAccessibilityTrap.ts

@@ -0,0 +1,25 @@
+import type { FlowStepFragment } from '@userflow-tech/protocol';
+
+/**
+ * Whether a step hides host app content from the accessibility tree.
+ *
+ * Modals always do. A tooltip does only when `tooltipTargetBlocked` seals its
+ * target too — otherwise the target is the control the step asks the user to
+ * press, so a screen reader has to be able to reach it.
+ *
+ * `UserflowOverlay` traps the host with this, and tooltip cards gate
+ * `accessibilityViewIsModal` on it: on iOS that flag alone drops the host app,
+ * target included, out of VoiceOver's reach.
+ */
+export function stepTrapsHostAccessibility(
+  step: Pick<FlowStepFragment, 'appearance' | 'tooltipTargetBlocked'>,
+): boolean {
+  const appearance = String(step.appearance).toUpperCase();
+  if (appearance === 'HIDDEN') {
+    return false;
+  }
+  if (appearance !== 'TOOLTIP') {
+    return true;
+  }
+  return step.tooltipTargetBlocked;
+}

package/src/surfaces/resolveBannerTheme.ts

@@ -1,6 +1,9 @@
 import type { ThemeFragment } from '@userflow-tech/protocol';
 
-/** Default banner chrome when theme banner tokens are unset (matches product / web debugger palette). */
+/**
+ * Last-resort banner chrome when neither banner nor brand tokens are set on the
+ * wire (web `applyThemeDefaults` falls back to brand first).
+ */
 export const DEFAULT_BANNER_BACKGROUND_COLOR = '#0A1A24';
 export const DEFAULT_BANNER_FOREGROUND_COLOR = '#FFFFFF';
 
@@ -10,9 +13,17 @@ function readThemeColor(theme: ThemeFragment, key: string): string | undefined {
 }
 
 export function resolveBannerBackgroundColor(theme: ThemeFragment): string {
-  return readThemeColor(theme, 'bannerBackgroundColor') ?? DEFAULT_BANNER_BACKGROUND_COLOR;
+  return (
+    readThemeColor(theme, 'bannerBackgroundColor') ??
+    readThemeColor(theme, 'brandBackgroundColor') ??
+    DEFAULT_BANNER_BACKGROUND_COLOR
+  );
 }
 
 export function resolveBannerForegroundColor(theme: ThemeFragment): string {
-  return readThemeColor(theme, 'bannerForegroundColor') ?? DEFAULT_BANNER_FOREGROUND_COLOR;
+  return (
+    readThemeColor(theme, 'bannerForegroundColor') ??
+    readThemeColor(theme, 'brandForegroundColor') ??
+    DEFAULT_BANNER_FOREGROUND_COLOR
+  );
 }