@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/runtime/isolateCall.ts

@@ -0,0 +1,53 @@
+import { reportSdkError } from './reportSdkError';
+
+/**
+ * True for missing `init` / `identify`, invalid event or attribute names — not
+ * for transport `UserflowAuthError`s. The flag is set at the throw site on
+ * `UserflowAuthError.isHostContract`; message text is not consulted.
+ * Matched by `error.name` plus the flag so mocked test doubles with the same
+ * name are treated like the real class.
+ */
+export function isHostContractError(error: unknown): boolean {
+  if (!(error instanceof Error) || error.name !== 'UserflowAuthError') {
+    return false;
+  }
+  return (error as { isHostContract?: boolean }).isHostContract === true;
+}
+
+export interface IsolateAsyncOptions {
+  /**
+   * When true (default), host-contract `UserflowAuthError`s are rethrown so the
+   * host sees integration misuse. Internal fire-and-forget paths pass false.
+   */
+  rethrowHostContract?: boolean;
+}
+
+/** Run synchronous SDK work; swallow and report anything except host-contract errors. */
+export function isolateSync<T>(scope: string, work: () => T): T | undefined {
+  try {
+    return work();
+  } catch (error) {
+    if (isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}
+
+/** Run async SDK work; swallow and report anything except host-contract errors. */
+export async function isolateAsync<T>(
+  scope: string,
+  work: () => Promise<T>,
+  options?: IsolateAsyncOptions,
+): Promise<T | undefined> {
+  try {
+    return await work();
+  } catch (error) {
+    if ((options?.rethrowHostContract ?? true) && isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}

package/src/runtime/reportSdkError.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal reporter for SDK failures that must not reach the host app.
+ * Always logs (not `__DEV__`-only) so a swallowed error is still diagnosable.
+ *
+ * Uses `console.warn`, not `console.error`: React Native release builds forward
+ * `console.error` to the native exception manager (Crashlytics / Sentry), which
+ * would report an isolated tooltip failure as a host crash.
+ */
+export function reportSdkError(scope: string, error: unknown, extra?: unknown): void {
+  // eslint-disable-next-line no-console -- isolation diagnostics must reach host logs
+  console.warn('[Userflow] isolated error', scope, error, extra ?? '');
+}

package/src/runtime/useBannerSession.ts

@@ -0,0 +1,35 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { isolateSync } from './isolateCall';
+
+/** Subscribe to the active banner. A throw while reading the session stays off the host tree. */
+export function useBannerSession(engine: BannerSessionEngine | null): BannerSessionFragment | null {
+  const [session, setSession] = React.useState<BannerSessionFragment | null>(() => {
+    if (!engine) return null;
+    try {
+      return engine.getBannerSession();
+    } catch {
+      return null;
+    }
+  });
+
+  React.useEffect(() => {
+    if (!engine) {
+      setSession(null);
+      return;
+    }
+    const read = () => {
+      isolateSync('banner-session', () => {
+        setSession(engine.getBannerSession());
+      });
+    };
+    read();
+    return engine.on(() => {
+      read();
+    });
+  }, [engine]);
+
+  return session;
+}

package/src/screenTracker.ts

@@ -18,6 +18,7 @@ let currentLocation: ClientLocationUpdate | null = null;
 /** Latest location seen while tracking was disabled; flushed on enable. */
 let pendingLocation: ClientLocationUpdate | null = null;
 let reporter: ScreenChangeReporter | null = null;
+const screenListeners = new Set<ScreenChangeReporter>();
 
 function locationKey(location: ClientLocationUpdate): string {
   return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
@@ -26,13 +27,10 @@ function locationKey(location: ClientLocationUpdate): string {
 /** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
 export function screenViewedAttributes(
   location: ClientLocationUpdate,
-): { screen_path: string } | { screen_name: string } | null {
-  if ('path' in location) {
-    if (!location.path) return null;
-    return { screen_path: location.path };
-  }
-  if (!location.screen) return null;
-  return { screen_name: location.screen };
+): { screen_name: string } | null {
+  const screenName = 'path' in location ? location.path : location.screen;
+  if (!screenName) return null;
+  return { screen_name: screenName };
 }
 
 /**
@@ -43,10 +41,37 @@ export function setScreenChangeReporter(next: ScreenChangeReporter | null): void
   reporter = next;
 }
 
+/**
+ * Observe accepted screen changes (Evaluate JavaScript context, and similar).
+ * Fires immediately with the latest known location when one exists.
+ * A throwing listener does not block the reporter or the other listeners.
+ */
+export function subscribeScreenLocation(listener: ScreenChangeReporter): () => void {
+  screenListeners.add(listener);
+  const current = getCurrentScreenLocation();
+  if (current) {
+    try {
+      listener(current);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
+  return () => {
+    screenListeners.delete(listener);
+  };
+}
+
 function report(location: ClientLocationUpdate): void {
   currentKey = locationKey(location);
   currentLocation = location;
   reporter?.(location);
+  for (const listener of screenListeners) {
+    try {
+      listener(location);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
 }
 
 /** Latest screen/path the SDK has recorded, or `null` before the first report. */
@@ -85,7 +110,7 @@ export function disableScreenTracking(): void {
  * flushed when tracking is enabled (so init-after-mount still picks up the
  * active route).
  *
- * - Expo Router: `{ path: "/settings/billing" }` → wire `screenPath`
+ * - Expo Router: `{ path: "/settings/billing" }` → wire `screenName`
  * - React Navigation / manual: `{ screen: "BillingSettings" }` → wire `screenName`
  */
 export function handleScreenChange(
@@ -122,4 +147,5 @@ export function resetScreenTrackerForTests(): void {
   currentLocation = null;
   currentKey = null;
   pendingLocation = null;
+  screenListeners.clear();
 }

package/src/surfaces/BannerBar.tsx

@@ -0,0 +1,176 @@
+import { genSessionDataLookup } from '@userflow-tech/core';
+import type { FlowActionFragment } from '@userflow-tech/protocol';
+import {
+  BannerEmbedMode,
+  EndFlowReasonInput,
+  type BannerSessionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+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 {
+  BANNER_CLOSE_SLOT_SIZE,
+  BANNER_ROOT_PADDING,
+  bannerFrameStyle,
+  bannerInnerStyle,
+  resolveBannerBarBorderRadius,
+} from './bannerBarLayout';
+import {
+  BANNER_BUTTON_GAP,
+  BANNER_CLOSE_BORDER_RADIUS,
+  bannerOverlayShadowStyle,
+} from './bannerBarTokens';
+import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from './resolveBannerTheme';
+
+export interface BannerBarProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+/**
+ * Banner chrome. An overlay parent floats this over the host. A flow parent
+ * keeps it in layout so the app is pushed instead of covered.
+ */
+export function BannerBar({
+  session,
+  onActions,
+  onDismiss,
+}: BannerBarProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const backgroundColor = resolveBannerBackgroundColor(theme);
+  const foregroundColor = resolveBannerForegroundColor(theme);
+  const bannerTheme = React.useMemo(
+    () => ({ ...theme, backgroundColor, fontColor: foregroundColor }),
+    [theme, backgroundColor, foregroundColor],
+  );
+  const lookupAttribute = React.useMemo(() => genSessionDataLookup(session.data), [session.data]);
+  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+
+  React.useEffect(() => {
+    if (!banner?.animate) {
+      opacity.setValue(1);
+      return;
+    }
+    opacity.setValue(0);
+    const animation = Animated.timing(opacity, {
+      toValue: 1,
+      duration: 200,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => {
+      animation.stop();
+    };
+  }, [banner?.animate, opacity, session.id]);
+
+  if (!banner) return null;
+
+  const overlay = banner.overlay !== false;
+  const frameStyle = bannerFrameStyle(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);
+
+  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={[]}
+                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>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: BANNER_ROOT_PADDING,
+  },
+  startSpacer: {
+    flexGrow: 1,
+    flexShrink: 1,
+    maxWidth: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+  },
+  content: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
+  buttons: {
+    flexDirection: 'row',
+    flexWrap: 'nowrap',
+    alignItems: 'center',
+    gap: BANNER_BUTTON_GAP,
+  },
+  close: {
+    width: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    borderRadius: BANNER_CLOSE_BORDER_RADIUS,
+  },
+  dismissIcon: {
+    fontSize: 18,
+    lineHeight: 22,
+    fontWeight: '300',
+  },
+});

package/src/surfaces/BannerSurface.tsx

@@ -0,0 +1,82 @@
+import type {
+  BannerSessionFragment,
+  EndFlowReasonInput,
+  FlowActionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { evalJsController } from '../evalJs/evalJsController';
+import { getEvalJsWebView } from '../evalJs/getWebView';
+
+import { BannerBar } from './BannerBar';
+import { BannerWebViewBar } from './bannerWebView/BannerWebViewBar';
+import { clearBannerAutoRunEvalSession } from './bannerWebView/bannerAutoRunSession';
+import { bannerNeedsWebView } from './bannerWebView/bannerNeedsWebView';
+
+export interface BannerSurfaceProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+let warnedMissingWebView = false;
+
+/**
+ * Native banner bar, or a WebView when a button runs Evaluate JavaScript or the
+ * theme has published custom CSS (same CDN stylesheet as userflow.js iframes).
+ */
+export function BannerSurface({
+  session,
+  onActions,
+  onDismiss,
+}: BannerSurfaceProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
+  const webView = needsWebView ? getEvalJsWebView() : null;
+
+  React.useLayoutEffect(() => {
+    if (!needsWebView || !webView) {
+      return;
+    }
+    evalJsController.setBannerOwnsWebView(true);
+    return () => {
+      evalJsController.setBannerOwnsWebView(false);
+    };
+  }, [needsWebView, webView, session.id]);
+
+  const dismissWebViewBanner = React.useCallback(
+    (endReason: EndFlowReasonInput) => {
+      clearBannerAutoRunEvalSession(session.id);
+      evalJsController.reset();
+      onDismiss(endReason);
+    },
+    [onDismiss, session.id],
+  );
+
+  if (!banner) {
+    return null;
+  }
+  if (needsWebView) {
+    if (!webView) {
+      if (!warnedMissingWebView) {
+        warnedMissingWebView = true;
+        console.warn(
+          'Userflow: WebView banner requires react-native-webview in the native binary. ' +
+            'Add it to your app (e.g. npx expo install react-native-webview), run pod install under ios/, ' +
+            'then rebuild with expo run:ios (not Expo Go). Falling back to the native banner bar.',
+        );
+      }
+      return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+    }
+    return (
+      <BannerWebViewBar session={session} onActions={onActions} onDismiss={dismissWebViewBanner} />
+    );
+  }
+  return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+}
+
+/** @internal */
+export function resetBannerSurfaceWarningsForTests(): void {
+  warnedMissingWebView = false;
+}

package/src/surfaces/MadeWithUserflow.tsx

@@ -11,13 +11,14 @@ export interface MadeWithUserflowProps {
   /** Theme main foreground (`fontColor`) — matches web `--userflow-main-foreground-color`. */
   color: string;
   /**
-   * Bubble content inset (modal 24 / tooltip 24). Applied as horizontal + bottom
-   * padding so the legend aligns with the step body, matching the modal mockup.
+   * Bubble content inset (modal 24 / tooltip 24). Only used when `embedded`,
+   * to pull the legend back out to the card edge.
    */
   contentPadding: number;
   /**
-   * When true, horizontal inset comes from the parent ScrollView; only vertical
-   * spacing and bottom inset are applied here (modal body).
+   * When true, the footer sits inside a ScrollView whose start padding is
+   * `contentPadding` and owns the gap above itself (modal body). Otherwise the
+   * parent supplies {@link MADE_WITH_USERFLOW_GAP} and the footer spans the card.
    */
   embedded?: boolean;
 }
@@ -26,8 +27,9 @@ export interface MadeWithUserflowProps {
  * Web "Made with Userflow" attribution (FlowChrome). Shown when the company
  * has `flowBranding` enabled; opens the Userflow homepage with UTM params.
  *
- * Rendered as a card footer (not absolutely pinned to the card corner) so left
- * and bottom insets match the surface content padding.
+ * Sits in the card corner (Figma: 8pt from the start and bottom edges) rather
+ * than on the content inset. Rendered in flow instead of absolutely so a
+ * scaled-up label pushes the card taller instead of overlapping the body.
  */
 export function MadeWithUserflow({
   company,
@@ -48,11 +50,10 @@ export function MadeWithUserflow({
         embedded
           ? {
               marginTop: MADE_WITH_USERFLOW_GAP,
-              paddingBottom: contentPadding,
+              marginStart: MADE_WITH_USERFLOW_INSET - contentPadding,
             }
           : {
-              paddingHorizontal: contentPadding,
-              paddingBottom: contentPadding,
+              paddingStart: MADE_WITH_USERFLOW_INSET,
             },
       ]}
       pointerEvents="box-none"
@@ -81,9 +82,13 @@ export function MadeWithUserflow({
 /** Gap between step content/buttons and the branding footer (web spacer height). */
 export const MADE_WITH_USERFLOW_GAP = 16;
 
+/** Legend offset from the card's start and bottom edges. */
+export const MADE_WITH_USERFLOW_INSET = 8;
+
 const styles = StyleSheet.create({
   footer: {
     flexShrink: 0,
+    paddingBottom: MADE_WITH_USERFLOW_INSET,
   },
   link: {
     flexDirection: 'row',
@@ -98,6 +103,6 @@ const styles = StyleSheet.create({
   label: {
     fontSize: 12,
     fontWeight: '500',
-    lineHeight: 14,
+    lineHeight: 16,
   },
 });

package/src/surfaces/ModalSurface.tsx

@@ -13,12 +13,12 @@ import type { LookupAttribute } from '../content/types';
 
 import { CardFade } from './CardFade';
 import { CLOSE_BUTTON_INSET, CLOSE_BUTTON_SIZE, CloseButton } from './CloseButton';
-import { resolveCloseButtonColor } from './resolveCloseButtonColor';
 import { MadeWithUserflow } from './MadeWithUserflow';
 import { ProgressBar } from './ProgressBar';
 import { ABSOLUTE_FILL } from './absoluteFill';
 import { parseBackdropOpacity } from './parseBackdropOpacity';
 import { resolveStepProgress } from './progress';
+import { resolveCloseButtonColor } from './resolveCloseButtonColor';
 import {
   resolveModalButtonsAlign,
   resolveModalCardMaxHeight,

package/src/surfaces/TooltipSurface.tsx

@@ -22,6 +22,7 @@ import { autoAnchorRegistry } from '../anchors/AutoAnchorRegistry';
 import { addAnimationFrameCallback, removeAnimationFrameCallback } from '../anchors/animationFrame';
 import { fiberScanRoot } from '../anchors/fiber/FiberScanRoot';
 import type { AnyFiber } from '../anchors/fiber/fiberInternals';
+import { clipToScrollViewports } from '../anchors/fiber/visibleRect';
 import {
   clearFiberAnchorCache,
   invalidateFiberAnchor,
@@ -230,6 +231,9 @@ export function TooltipSurface({
   const resolveEpochRef = React.useRef(0);
   /** Latest resolved host fiber (for scroll-ancestor walk + rAF remeasure). */
   const hostFiberRef = React.useRef<AnyFiber | null>(null);
+  /** Target rect clipped to scroll viewports, for tap detection only. */
+  const clippedPressRef = React.useRef<Rect | null>(null);
+  const clipGenRef = React.useRef(0);
   const hostMeasureRef = React.useRef<
     ((callback: (x: number, y: number, width: number, height: number) => void) => void) | null
   >(null);
@@ -333,6 +337,18 @@ export function TooltipSurface({
     }
     targetRef.current = next;
     setTarget(next);
+    if (next == null) {
+      clippedPressRef.current = null;
+      return;
+    }
+    clippedPressRef.current = next;
+    const fiber = hostFiberRef.current;
+    const gen = (clipGenRef.current += 1);
+    if (!fiber) return;
+    void clipToScrollViewports(fiber, next).then((clipped) => {
+      if (clipGenRef.current !== gen) return;
+      clippedPressRef.current = clipped;
+    });
   }, []);
 
   const markMeasureAttempted = React.useCallback(() => {
@@ -815,7 +831,7 @@ export function TooltipSurface({
     }
 
     targetPressMonitor.set({
-      getRect: () => targetRef.current,
+      getRect: () => clippedPressRef.current,
       onPress: () => {
         // Native touches are async relative to commits, so re-check the phase.
         if (exitingRef.current) return;

package/src/surfaces/bannerBarLayout.ts

@@ -0,0 +1,74 @@
+import type { BannerFragment } from '@userflow-tech/protocol';
+import { BannerContentLayout } from '@userflow-tech/protocol';
+import type { ViewStyle } from 'react-native';
+
+import {
+  BANNER_INNER_COLUMN_GAP,
+  BANNER_INNER_MARGIN_HORIZONTAL,
+  BANNER_INNER_ROW_GAP,
+  BANNER_OVERLAY_SCREEN_INSET_HORIZONTAL,
+} from './bannerBarTokens';
+import type { EdgeInsets } from './safeArea';
+
+export { BANNER_CLOSE_SLOT_SIZE, BANNER_ROOT_PADDING } from './bannerBarTokens';
+
+function optionalMargin(value: number | null | undefined): number | undefined {
+  return value == null ? undefined : value;
+}
+
+/** Outer frame: max embed width and builder outer margin (web `userflowjs-banner-frame`). */
+export function bannerFrameStyle(banner: BannerFragment): ViewStyle {
+  const hasMaxWidth = banner.maxWidth != null;
+
+  return {
+    alignSelf: hasMaxWidth ? 'center' : 'stretch',
+    ...(hasMaxWidth ? { maxWidth: banner.maxWidth! } : null),
+    marginTop: optionalMargin(banner.marginTop),
+    marginRight: optionalMargin(banner.marginRight),
+    marginBottom: optionalMargin(banner.marginBottom),
+    marginLeft: optionalMargin(banner.marginLeft),
+  };
+}
+
+/** Corner radius on the painted bar when configured in the builder. */
+export function resolveBannerBarBorderRadius(banner: BannerFragment): number | undefined {
+  return banner.borderRadius ?? undefined;
+}
+
+/** Horizontal inset for overlay hosts — at least Figma inset, or safe area when larger. */
+export function bannerOverlayHostPadding(insets: EdgeInsets): ViewStyle {
+  const horizontal = Math.max(BANNER_OVERLAY_SCREEN_INSET_HORIZONTAL, insets.left, insets.right);
+  return { paddingHorizontal: horizontal };
+}
+
+/** Flex justification for the inner row (web content-layout modifiers). */
+export function bannerInnerJustifyContent(
+  layout: BannerContentLayout,
+): ViewStyle['justifyContent'] {
+  switch (layout) {
+    case BannerContentLayout.CENTER:
+      return 'center';
+    case BannerContentLayout.SPACE_BETWEEN:
+      return 'space-between';
+    case BannerContentLayout.START:
+    default:
+      return 'flex-start';
+  }
+}
+
+export function bannerInnerStyle(banner: BannerFragment): ViewStyle {
+  const hasMaxContentWidth = banner.maxContentWidth != null;
+  return {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 0,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    columnGap: BANNER_INNER_COLUMN_GAP,
+    rowGap: BANNER_INNER_ROW_GAP,
+    marginHorizontal: BANNER_INNER_MARGIN_HORIZONTAL,
+    justifyContent: bannerInnerJustifyContent(banner.contentLayout),
+    ...(hasMaxContentWidth ? { maxWidth: banner.maxContentWidth!, width: '100%' } : null),
+  };
+}

package/src/surfaces/bannerBarTokens.ts

@@ -0,0 +1,34 @@
+import type { ViewStyle } from 'react-native';
+
+/**
+ * End-user banner chrome from Figma `Userflow - React native`
+ * (`BojC6qdlFUytdD1bRsNLV8`, node `1551-1208` — SDK Embed Banner) and web
+ * `userflowjs-banner-*` in bubble-frame.styl. Layout numbers match web
+ * `$padding-*` at 1rem = 16px.
+ */
+
+export const BANNER_ROOT_PADDING = 8;
+export const BANNER_INNER_MARGIN_HORIZONTAL = 8;
+export const BANNER_INNER_COLUMN_GAP = 16;
+export const BANNER_INNER_ROW_GAP = 8;
+export const BANNER_BUTTON_GAP = 8;
+export const BANNER_BUTTON_PADDING_HORIZONTAL = 12;
+/** Web `--userflow-button-height` default (36). Close control is square at this size. */
+export const BANNER_CLOSE_SLOT_SIZE = 36;
+export const BANNER_CLOSE_BORDER_RADIUS = 4;
+
+/** Overlay embed: horizontal inset from screen edges (Figma; excludes builder outer margin). */
+export const BANNER_OVERLAY_SCREEN_INSET_HORIZONTAL = 16;
+/** Figma Shadow/Card — separates a full-bleed overlay bar from app content. */
+const BANNER_SHADOW_COLOR = '#132b39';
+
+export function bannerOverlayShadowStyle(edge: 'top' | 'bottom'): ViewStyle {
+  const offsetY = edge === 'top' ? 4 : -4;
+  return {
+    shadowColor: BANNER_SHADOW_COLOR,
+    shadowOffset: { width: 0, height: offsetY },
+    shadowOpacity: 0.1,
+    shadowRadius: 12,
+    elevation: 8,
+  };
+}