@scalebun-release/react-native 2.5.0

package/src/features/engage/EngageInAppView.tsx

@@ -0,0 +1,2678 @@
+/**
+ * ScaleBun SDK — Engage In-App Message View (shared cross-platform JS overlay, D4)
+ *
+ * One renderer, seven layout branches — chosen from `InAppMessageConfig.layout`
+ * delivered by the config lane. App developers import and mount ONE component
+ * (`EngageInAppView` or via `EngagePromptProvider`) and write zero layout code:
+ * the SDK reads the layout field and auto-selects the correct branch.
+ *
+ * Layout → branch mapping (1:1, config-driven):
+ *   modal        → centered dialog (backdrop + rounded card)
+ *   fullscreen   → edge-to-edge takeover (no margins, no rounded corners)
+ *   bottom_sheet → slides up from bottom (rounded top corners)
+ *   top_banner   → absolute strip pinned to top
+ *   bottom_banner→ absolute strip pinned to bottom
+ *   tooltip      → small compact popup (anchored look, top-right close)
+ *   toast        → transient strip, auto-dismisses after 3 seconds
+ *
+ * Legacy `banner` (old wire value) gracefully maps to `top_banner`.
+ *
+ * Callbacks (unchanged):
+ *   onShow()      — fired once when first visible (provider records impression)
+ *   onCta(cta)    — primary CTA tap (provider emits `click`; deep link surfaced to host)
+ *   onComplete()  — guided flow finished (provider emits `completion`)
+ *   onDismiss()   — secondary CTA / close / backdrop / auto-dismiss (provider emits `dismiss`)
+ */
+
+import React, { Component, useCallback, useEffect, useMemo, useRef, useState, type ReactElement, type ReactNode } from 'react';
+import {
+    AccessibilityInfo,
+    Modal,
+    Platform,
+    SafeAreaView,
+    ScrollView,
+    StatusBar,
+    useWindowDimensions,
+    View,
+    Text,
+    Image,
+    KeyboardAvoidingView,
+    Pressable,
+    type LayoutChangeEvent,
+    type StyleProp,
+    type ViewStyle,
+    type TextStyle,
+    type ImageStyle,
+} from 'react-native';
+import type {
+    InAppGameRequestHandler,
+    InAppGameResult,
+    InAppMessageConfig,
+    InAppRenderSpec,
+} from './engageTypes';
+import { useEngageAnchorRegistry, type EngageAnchorRect } from './EngageAnchor';
+import {
+    coachmarkAnchorError,
+    normalizeCoachmarkSteps,
+    normalizeLegacyAnchoredStep,
+    resolveAnchoredSurfaceKind,
+    resolveCoachmarkFinishMode,
+    resolveCoachmarkStepIndex,
+} from './engageCoachmarkTour';
+import {
+    ZERO_ENGAGE_WINDOW_INSETS,
+    useEngageWindowInsets,
+    type EngageWindowInsets,
+} from './engageWindowInsets';
+import { logger } from '../../core/logger/internalLogger';
+import { resolveArchetypeContent } from './EngageArchetypeRenderers';
+import { resolveVariantContent } from './EngageVariantContent';
+import {
+    resolveInAppMechanic,
+    resolveInAppPresentation,
+    type InAppArchetype,
+    type InAppMountModel,
+    type ResolvedInAppPresentation,
+} from './engageVariantResolver';
+import {
+    authoredPreviewGameResult,
+    buildInAppGameRequest,
+    inAppGameAllowedOutcomeIds,
+    isInAppGameVariant,
+    validateInAppGameResult,
+} from './engageGameLogic';
+import {
+    inAppOutcomeIconGlyph,
+    inAppOutcomeTerminalForCta,
+    resolveInAppOutcomeConfig,
+    resolveInAppOutcomeTerminal,
+    type InAppOutcomeRequest,
+    type InAppOutcomeTerminal,
+    type ResolvedInAppOutcomeConfig,
+} from './engageOutcome';
+import {
+    resolveInAppMediaAspectRatio,
+    resolveInAppMediaHeight,
+} from './engageMediaSizing';
+import {
+    resolveMultiStepSheetIndex,
+    resolveMultiStepSheetLabels,
+    resolveMultiStepSheetTerminalAction,
+    type MultiStepSheetTerminalAction,
+} from './engageMultiStepSheet';
+
+let gameAttemptSequence = 0;
+
+/** The seven distinct presentation branches (config-driven, 1:1 with layout strings). */
+export type InAppLayout =
+    | 'modal'
+    | 'fullscreen'
+    | 'bottom_sheet'
+    | 'top_banner'
+    | 'bottom_banner'
+    | 'tooltip'
+    | 'toast';
+
+/**
+ * Map the contract `layout` string onto one of the seven render branches.
+ * Legacy `banner` value → `top_banner` for backward compat with old configs.
+ * Any unknown future value → `modal` (safe default).
+ */
+export function resolveInAppLayout(layout: InAppMessageConfig['layout']): InAppLayout {
+    switch (layout) {
+        case 'modal':        return 'modal';
+        case 'fullscreen':   return 'fullscreen';
+        case 'bottom_sheet': return 'bottom_sheet';
+        case 'top_banner':   return 'top_banner';
+        case 'bottom_banner': return 'bottom_banner';
+        case 'tooltip':      return 'tooltip';
+        case 'toast':        return 'toast';
+        // legacy wire value (old configs sent 'banner' for top strip)
+        case 'banner' as string: return 'top_banner';
+        default:             return 'modal';
+    }
+}
+
+/** Props every in-app render branch receives (the Open/Closed contract). */
+export interface InAppBranchProps {
+    spec: InAppRenderSpec;
+    /** Canonical registry key, used to select family-specific content modes. */
+    variantKey?: string;
+    /** Resolved design tokens (dashboard-matching defaults + spec overrides). */
+    theme: InAppTheme;
+    /** Primary CTA tapped — provider emits `click` and surfaces `cta.deepLink`. */
+    onCta: (cta: NonNullable<InAppRenderSpec['cta']>) => void;
+    /** Dismissed (secondary CTA / close / backdrop / auto-timeout) — provider emits `dismiss`. */
+    onDismiss: () => void;
+    /** Finished a guided flow — provider emits `completion`, never a click/dismiss. */
+    onComplete?: () => void;
+    /** Present an authored terminal result/confirmation card before the final action. */
+    onOutcome?: (request: InAppOutcomeRequest) => void;
+    /** Optional additive gameplay telemetry; never used to determine a reward. */
+    onInteraction?: (interaction: InAppMechanicInteraction) => void;
+    /** Customer-backend result resolver. Retries reuse the same SDK-owned attempt id. */
+    requestGameResult?: (
+        attempt?: number,
+        input?: Record<string, unknown>,
+    ) => Promise<InAppGameResult>;
+    /** Anchored surfaces call this only after their native target has been measured. */
+    onReady?: () => void;
+    /** Anchored surfaces report a missing/invalid target instead of faking a position. */
+    onRenderError?: (reason: string) => void;
+    /** Optional family-specific body. The layout branch remains responsible for mounting. */
+    children?: ReactNode;
+}
+
+export interface InAppMechanicInteraction {
+    mechanic: string;
+    phase: 'started' | 'progress' | 'decision' | 'resolved' | 'claimed' | 'completed';
+    attempt?: number;
+    progress?: number;
+    result?: string;
+    value?: string | number | boolean;
+    meta?: Record<string, unknown>;
+}
+
+/** A render branch for one in-app layout. */
+export type InAppRenderer = (props: InAppBranchProps) => ReactElement | null;
+
+export type CoachmarkPlacement = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+
+export interface CoachmarkGeometry {
+    spotlight: EngageAnchorRect;
+    scrims: EngageAnchorRect[];
+    tooltip: {
+        left: number;
+        width: number;
+        top?: number;
+        bottom?: number;
+        maxHeight: number;
+        placement: Exclude<CoachmarkPlacement, 'auto'>;
+        arrowLeft?: number;
+        arrowTop?: number;
+    };
+}
+
+const clamp = (value: number, min: number, max: number): number =>
+    Math.max(min, Math.min(value, max));
+
+type ScreenPosition = 'top' | 'center' | 'bottom';
+
+const screenPosition = (value: unknown): ScreenPosition | undefined =>
+    value === 'top' || value === 'center' || value === 'bottom' ? value : undefined;
+
+const androidInsetPadding = (
+    insets: EngageWindowInsets,
+): ViewStyle | undefined => {
+    if (Platform.OS !== 'android') return undefined;
+    return {
+        paddingTop: insets.top,
+        paddingRight: insets.right,
+        paddingBottom: insets.bottom,
+        paddingLeft: insets.left,
+    };
+};
+
+/** Pure geometry shared by iOS/Android and covered without a native measurement mock. */
+export function resolveCoachmarkGeometry(
+    anchor: EngageAnchorRect,
+    viewport: { width: number; height: number },
+    preferred: CoachmarkPlacement = 'auto',
+    options: {
+        insets?: { top: number; right: number; bottom: number; left: number };
+        cardHeight?: number;
+    } = {},
+): CoachmarkGeometry {
+    const pad = 8;
+    const gap = 12;
+    const edge = 16;
+    const insets = options.insets ?? { top: 0, right: 0, bottom: 0, left: 0 };
+    const safeLeft = clamp(insets.left + edge, 0, viewport.width);
+    const safeRight = clamp(viewport.width - insets.right - edge, safeLeft, viewport.width);
+    const safeTop = clamp(insets.top + edge, 0, viewport.height);
+    const safeBottom = clamp(viewport.height - insets.bottom - edge, safeTop, viewport.height);
+    const requestedCardHeight = Math.min(
+        Math.max(1, options.cardHeight ?? 160),
+        Math.max(1, safeBottom - safeTop),
+    );
+    const left = clamp(anchor.x - pad, 0, viewport.width);
+    const top = clamp(anchor.y - pad, 0, viewport.height);
+    const right = clamp(anchor.x + anchor.width + pad, left, viewport.width);
+    const bottom = clamp(anchor.y + anchor.height + pad, top, viewport.height);
+    const spotlight = { x: left, y: top, width: right - left, height: bottom - top };
+    const above = Math.max(0, top - gap - safeTop);
+    const below = Math.max(0, safeBottom - bottom - gap);
+    const verticalPlacement = (): 'top' | 'bottom' => preferred === 'top'
+        ? (above >= requestedCardHeight || above >= below ? 'top' : 'bottom')
+        : preferred === 'bottom'
+        ? (below >= requestedCardHeight || below >= above ? 'bottom' : 'top')
+        : (below >= requestedCardHeight || below >= above ? 'bottom' : 'top');
+    const leftRoom = Math.max(0, left - gap - safeLeft);
+    const rightRoom = Math.max(0, safeRight - right - gap);
+    let placement: Exclude<CoachmarkPlacement, 'auto'>;
+    if (preferred === 'left' || preferred === 'right') {
+        const preferredRoom = preferred === 'left' ? leftRoom : rightRoom;
+        const oppositeRoom = preferred === 'left' ? rightRoom : leftRoom;
+        if (preferredRoom >= 100 || (preferredRoom >= 80 && preferredRoom >= oppositeRoom)) {
+            placement = preferred;
+        } else if (oppositeRoom >= 80) {
+            placement = preferred === 'left' ? 'right' : 'left';
+        } else {
+            placement = below >= requestedCardHeight || below >= above ? 'bottom' : 'top';
+        }
+    } else {
+        placement = verticalPlacement();
+    }
+    const tooltipWidth = Math.max(0, Math.min(280, safeRight - safeLeft));
+    const anchorCenter = anchor.x + anchor.width / 2;
+    const verticalLeft = clamp(
+        anchorCenter - tooltipWidth / 2,
+        safeLeft,
+        Math.max(safeLeft, safeRight - tooltipWidth),
+    );
+    const side = placement === 'left' || placement === 'right';
+    const sideWidth = Math.min(240, placement === 'left' ? leftRoom : rightRoom);
+    const tooltipLeft = side
+        ? (placement === 'left' ? left - gap - sideWidth : right + gap)
+        : verticalLeft;
+    const resolvedWidth = side ? sideWidth : tooltipWidth;
+    const tooltipMaxHeight = side
+        ? Math.max(0, safeBottom - safeTop)
+        : placement === 'top'
+          ? above
+          : below;
+    const cardHeight = Math.min(requestedCardHeight, tooltipMaxHeight);
+    const tooltipTop = clamp(
+        anchor.y + anchor.height / 2 - cardHeight / 2,
+        safeTop,
+        Math.max(safeTop, safeBottom - cardHeight),
+    );
+    const verticalPosition = placement === 'bottom'
+        ? { top: clamp(bottom + gap, safeTop, Math.max(safeTop, safeBottom - cardHeight)) }
+        : { bottom: Math.max(0, viewport.height - top + gap) };
+
+    return {
+        spotlight,
+        scrims: [
+            { x: 0, y: 0, width: viewport.width, height: top },
+            { x: 0, y: top, width: left, height: bottom - top },
+            { x: right, y: top, width: viewport.width - right, height: bottom - top },
+            { x: 0, y: bottom, width: viewport.width, height: viewport.height - bottom },
+        ],
+        tooltip: {
+            left: tooltipLeft,
+            width: resolvedWidth,
+            ...(side ? { top: tooltipTop } : verticalPosition),
+            maxHeight: tooltipMaxHeight,
+            placement,
+            ...(side
+                ? { arrowTop: clamp(anchor.y + anchor.height / 2 - tooltipTop - 7, 20, Math.max(20, cardHeight - 34)) }
+                : { arrowLeft: clamp(anchorCenter - tooltipLeft - 7, 20, Math.max(20, resolvedWidth - 34)) }),
+        },
+    };
+}
+
+// ─── Normalized theme contract (single source of truth, dashboard-matching) ────
+// The renderer NEVER hardcodes dashboard CSS per message. Instead each token has a
+// light/dark default copied ONCE from the dashboard's in-app preview look, and any
+// `spec.style` key overrides it. This is the design contract the dashboard preview,
+// the backend payload, and the SDK all share.
+
+export interface InAppTheme {
+    dark: boolean;
+    rtl: boolean;
+    accent: string;
+    cardBg: string;
+    titleColor: string;
+    bodyColor: string;
+    ctaText: string;
+    secondaryColor: string;
+    couponBg: string;
+    couponFg: string;
+    couponBorder: string;
+    backdrop: string;
+}
+
+// Default tokens — values mirror the dashboard `inapp.theme.css` in-app preview so a
+// message with no style overrides looks identical on device and in the dashboard.
+const LIGHT_DEFAULTS = {
+    accent: '#5B4FE0',
+    cardBg: '#FFFFFF',
+    titleColor: '#0E1422',
+    bodyColor: '#697586',
+    ctaText: '#FFFFFF',
+    secondaryColor: '#697586',
+    couponBg: '#F2F1FD',
+    couponFg: '#5B4FE0',
+    couponBorder: '#5B4FE0',
+    backdrop: 'rgba(15,20,32,0.4)',
+} as const;
+const DARK_DEFAULTS = {
+    accent: '#5B4FE0',
+    cardBg: '#1E2128',
+    titleColor: '#E6E8EC',
+    bodyColor: '#697586',
+    ctaText: '#FFFFFF',
+    secondaryColor: '#9AA3AF',
+    couponBg: '#23203A',
+    couponFg: '#8B81F0',
+    couponBorder: '#8B81F0',
+    backdrop: 'rgba(15,20,32,0.4)',
+} as const;
+
+const KNOWN_STYLE_KEYS = new Set([
+    'accent', 'cardBg', 'titleColor', 'bodyColor', 'ctaText',
+    'secondaryColor', 'couponBg', 'couponFg', 'couponBorder', 'backdrop',
+]);
+
+/** Resolve dashboard-matching tokens, applying `spec.style` overrides on top. */
+export function resolveTheme(spec: InAppRenderSpec): InAppTheme {
+    const dark = spec.dark === true;
+    const base = dark ? DARK_DEFAULTS : LIGHT_DEFAULTS;
+    const style = spec.style ?? {};
+    if (__DEV__) {
+        for (const k of Object.keys(style)) {
+            if (!KNOWN_STYLE_KEYS.has(k)) {
+                logger.warn(`[Engage] in-app spec.style has unknown token "${k}" — ignored. Known: ${[...KNOWN_STYLE_KEYS].join(', ')}`);
+            }
+        }
+    }
+    const pick = (k: keyof typeof base): string => style[k] ?? base[k];
+    return {
+        dark,
+        rtl: spec.rtl === true,
+        accent: pick('accent'),
+        cardBg: pick('cardBg'),
+        titleColor: pick('titleColor'),
+        bodyColor: pick('bodyColor'),
+        ctaText: pick('ctaText'),
+        secondaryColor: pick('secondaryColor'),
+        couponBg: pick('couponBg'),
+        couponFg: pick('couponFg'),
+        couponBorder: pick('couponBorder'),
+        backdrop: pick('backdrop'),
+    };
+}
+
+// ─── Shared primitives ────────────────────────────────────────────────────────
+
+function rtlText(theme: InAppTheme): TextStyle {
+    return theme.rtl ? { writingDirection: 'rtl', textAlign: 'right' } : {};
+}
+
+function CouponChip({ code, theme }: { code: string; theme: InAppTheme }): ReactElement {
+    return (
+        <View style={[styles.coupon, { backgroundColor: theme.couponBg, borderColor: theme.couponBorder }]}>
+            <Text style={[styles.couponText, { color: theme.couponFg }]}>{code}</Text>
+        </View>
+    );
+}
+
+function MessageContent({ spec, theme }: { spec: InAppRenderSpec; theme: InAppTheme }): ReactElement {
+    const mediaHeight = resolveInAppMediaHeight(spec, 140, 320);
+    return (
+        <View style={styles.contentBlock}>
+            {spec.imageUrl ? (
+                <Image
+                    accessibilityRole="image"
+                    source={{ uri: spec.imageUrl }}
+                    style={[
+                        styles.image,
+                        mediaHeight === undefined ? null : { height: mediaHeight },
+                    ]}
+                    resizeMode="cover"
+                />
+            ) : null}
+            {spec.title ? <Text style={[styles.title, { color: theme.titleColor }, rtlText(theme)]}>{spec.title}</Text> : null}
+            <Text style={[styles.body, { color: theme.bodyColor }, rtlText(theme)]}>{spec.body}</Text>
+            {spec.coupon ? <CouponChip code={spec.coupon} theme={theme} /> : null}
+        </View>
+    );
+}
+
+function CtaRow({ spec, theme, onCta, onDismiss, onOutcome }: InAppBranchProps): ReactElement | null {
+    const cta = spec.cta;
+    const secondary = spec.secondaryCta;
+    if (!cta && !secondary) return null;
+    return (
+        <View style={[styles.actions, theme.rtl ? { flexDirection: 'row-reverse' } : null]}>
+            {secondary ? (
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={secondary.label}
+                    onPress={onDismiss}
+                    style={styles.secondaryBtn}
+                >
+                    <Text style={[styles.secondaryText, { color: theme.secondaryColor }]}>{secondary.label}</Text>
+                </Pressable>
+            ) : null}
+            {cta ? (
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={cta.label}
+                    onPress={() => {
+                        if (onOutcome) {
+                            onOutcome({ fallback: inAppOutcomeTerminalForCta(cta) });
+                            return;
+                        }
+                        if (cta.action === 'dismiss') onDismiss();
+                        else onCta(cta);
+                    }}
+                    style={[styles.primaryBtn, { backgroundColor: theme.accent }]}
+                >
+                    <Text style={[styles.primaryText, { color: theme.ctaText }]}>{cta.label}</Text>
+                </Pressable>
+            ) : null}
+        </View>
+    );
+}
+
+function InAppOutcomeModal({
+    outcome,
+    resultLabel,
+    theme,
+    onAction,
+    onRequestClose,
+}: {
+    outcome: ResolvedInAppOutcomeConfig;
+    resultLabel?: string;
+    theme: InAppTheme;
+    onAction: () => void;
+    onRequestClose: () => void;
+}): ReactElement {
+    const announcement = [outcome.title, outcome.body, resultLabel]
+        .filter(Boolean)
+        .join('. ');
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="fade"
+            statusBarTranslucent
+            onRequestClose={onRequestClose}
+            onShow={() => AccessibilityInfo.announceForAccessibility(announcement)}
+        >
+            <SafeAreaView
+                style={[
+                    outcomeStyles.backdrop,
+                    { backgroundColor: theme.backdrop },
+                ]}
+            >
+                <View
+                    accessibilityViewIsModal
+                    style={[
+                        outcomeStyles.card,
+                        {
+                            backgroundColor: theme.cardBg,
+                            borderColor: theme.couponBorder,
+                        },
+                    ]}
+                >
+                    <View
+                        accessible
+                        accessibilityRole="alert"
+                        accessibilityLabel={announcement}
+                        accessibilityLiveRegion="assertive"
+                        style={outcomeStyles.copy}
+                    >
+                        <View
+                            importantForAccessibility="no-hide-descendants"
+                            style={[
+                                outcomeStyles.icon,
+                                { backgroundColor: theme.couponBg },
+                            ]}
+                        >
+                            <Text
+                                style={[
+                                    outcomeStyles.iconText,
+                                    { color: theme.couponFg },
+                                ]}
+                            >
+                                {inAppOutcomeIconGlyph(outcome.icon)}
+                            </Text>
+                        </View>
+                        <Text
+                            style={[
+                                outcomeStyles.title,
+                                { color: theme.titleColor },
+                                rtlText(theme),
+                            ]}
+                        >
+                            {outcome.title}
+                        </Text>
+                        <Text
+                            style={[
+                                outcomeStyles.body,
+                                { color: theme.bodyColor },
+                                rtlText(theme),
+                            ]}
+                        >
+                            {outcome.body}
+                        </Text>
+                        {resultLabel ? (
+                            <View
+                                style={[
+                                    outcomeStyles.result,
+                                    { backgroundColor: theme.couponBg },
+                                ]}
+                            >
+                                <Text
+                                    style={[
+                                        outcomeStyles.resultText,
+                                        { color: theme.couponFg },
+                                        rtlText(theme),
+                                    ]}
+                                >
+                                    {resultLabel}
+                                </Text>
+                            </View>
+                        ) : null}
+                    </View>
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel={outcome.buttonLabel}
+                        onPress={onAction}
+                        style={[
+                            outcomeStyles.button,
+                            { backgroundColor: theme.accent },
+                        ]}
+                    >
+                        <Text
+                            style={[
+                                outcomeStyles.buttonText,
+                                { color: theme.ctaText },
+                            ]}
+                        >
+                            {outcome.buttonLabel}
+                        </Text>
+                    </Pressable>
+                </View>
+            </SafeAreaView>
+        </Modal>
+    );
+}
+
+/** Default legacy content when a registry mechanic does not provide a custom body. */
+function BranchContent(props: InAppBranchProps): ReactElement {
+    if (props.children !== undefined) return <>{props.children}</>;
+    return (
+        <>
+            <MessageContent spec={props.spec} theme={props.theme} />
+            <CtaRow {...props} />
+        </>
+    );
+}
+
+function CloseBtn({ onPress, style }: { onPress: () => void; style?: ViewStyle }): ReactElement {
+    return (
+        <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Dismiss"
+            onPress={onPress}
+            hitSlop={8}
+            style={[styles.closeBtn, style]}
+        >
+            <Text style={styles.closeBtnText}>×</Text>
+        </Pressable>
+    );
+}
+
+function ScreenEdgeSurface({
+    edge,
+    contentStyle,
+    children,
+}: {
+    edge: Exclude<ScreenPosition, 'center'>;
+    contentStyle: StyleProp<ViewStyle>;
+    children: ReactNode;
+}): ReactElement {
+    const insets = useEngageWindowInsets(true) ?? ZERO_ENGAGE_WINDOW_INSETS;
+    const content = (
+        <View pointerEvents="box-none" style={contentStyle}>
+            {children}
+        </View>
+    );
+    return (
+        <SafeAreaView
+            pointerEvents="box-none"
+            style={[
+                styles.screenEdge,
+                edge === 'top' ? styles.screenEdgeTop : styles.screenEdgeBottom,
+                androidInsetPadding(insets),
+            ]}
+        >
+            {edge === 'bottom' ? (
+                <KeyboardAvoidingView
+                    pointerEvents="box-none"
+                    behavior={Platform.OS === 'ios' ? 'padding' : undefined}
+                    style={styles.screenEdgeKeyboard}
+                >
+                    {content}
+                </KeyboardAvoidingView>
+            ) : content}
+        </SafeAreaView>
+    );
+}
+
+// ─── 1. modal — centered dialog ───────────────────────────────────────────────
+
+function ModalInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const centerDrawer = props.variantKey === 'center_drawer';
+    const position = screenPosition(spec.ext?.position)
+        ?? screenPosition(spec.ext?.layoutPosition)
+        ?? 'center';
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="fade"
+            statusBarTranslucent={false}
+            onRequestClose={onDismiss}
+        >
+            <SafeAreaView
+                style={[
+                    styles.modalSafeArea,
+                    { backgroundColor: theme.backdrop },
+                ]}
+            >
+                <KeyboardAvoidingView
+                    behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+                    style={styles.keyboardAvoider}
+                >
+                    <Pressable
+                        style={[
+                            styles.modalBackdrop,
+                            position === 'top' ? styles.modalBackdropTop : null,
+                            position === 'bottom' ? styles.modalBackdropBottom : null,
+                            { backgroundColor: theme.backdrop },
+                        ]}
+                        onPress={onDismiss}
+                        accessibilityRole="none"
+                    >
+                        <Pressable
+                            style={[
+                                styles.modalCard,
+                                centerDrawer && styles.centerDrawerCard,
+                                { backgroundColor: theme.cardBg },
+                            ]}
+                            onPress={() => {}}
+                            accessibilityRole="none"
+                        >
+                            <CloseBtn onPress={onDismiss} style={styles.modalClosePos} />
+                            <ScrollView
+                                style={styles.modalScroll}
+                                contentContainerStyle={styles.modalScrollContent}
+                                showsVerticalScrollIndicator={false}
+                                keyboardShouldPersistTaps="handled"
+                            >
+                                <BranchContent {...props} />
+                            </ScrollView>
+                        </Pressable>
+                    </Pressable>
+                </KeyboardAvoidingView>
+            </SafeAreaView>
+        </Modal>
+    );
+}
+
+// ─── 2. fullscreen — edge-to-edge takeover ────────────────────────────────────
+
+function FullScreenInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const mediaAspectRatio = resolveInAppMediaAspectRatio(spec, 16 / 9);
+    const mediaMaxHeight = resolveInAppMediaHeight(spec, 320, 480);
+    return (
+        <Modal
+            visible
+            transparent={false}
+            animationType="slide"
+            presentationStyle="fullScreen"
+            onRequestClose={onDismiss}
+        >
+            <SafeAreaView style={[styles.fullscreenCard, { backgroundColor: theme.cardBg }]}>
+                <View style={styles.fullscreenHeader}>
+                    <CloseBtn onPress={onDismiss} />
+                </View>
+                <ScrollView
+                    style={styles.fullscreenScroll}
+                    contentContainerStyle={styles.fullscreenScrollContent}
+                    showsVerticalScrollIndicator={false}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    {props.children === undefined && spec.imageUrl ? (
+                        <Image
+                            accessibilityRole="image"
+                            source={{ uri: spec.imageUrl }}
+                            style={[
+                                styles.fullscreenImage,
+                                mediaAspectRatio === undefined
+                                    ? null
+                                    : {
+                                        aspectRatio: mediaAspectRatio,
+                                        maxHeight: mediaMaxHeight,
+                                    },
+                            ]}
+                            resizeMode="cover"
+                        />
+                    ) : null}
+                    <View style={styles.fullscreenContent}>
+                        {props.children !== undefined ? <>{props.children}</> : (
+                            <>
+                                {spec.title ? <Text style={[styles.fullscreenTitle, { color: theme.titleColor }, rtlText(theme)]}>{spec.title}</Text> : null}
+                                {spec.body ? <Text style={[styles.fullscreenBody, { color: theme.bodyColor }, rtlText(theme)]}>{spec.body}</Text> : null}
+                                {spec.coupon ? <CouponChip code={spec.coupon} theme={theme} /> : null}
+                                <CtaRow {...props} />
+                            </>
+                        )}
+                    </View>
+                </ScrollView>
+            </SafeAreaView>
+        </Modal>
+    );
+}
+
+// ─── 3. bottom_sheet — slides up from bottom ──────────────────────────────────
+
+function SheetSurface({
+    theme,
+    onDismiss,
+    children,
+}: Pick<InAppBranchProps, 'theme' | 'onDismiss'> & {
+    children: ReactNode;
+}): ReactElement {
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="slide"
+            statusBarTranslucent={false}
+            onRequestClose={onDismiss}
+        >
+            <KeyboardAvoidingView
+                behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+                style={styles.keyboardAvoider}
+            >
+                <Pressable
+                    style={[styles.sheetBackdrop, { backgroundColor: theme.backdrop }]}
+                    onPress={onDismiss}
+                    accessibilityRole="none"
+                >
+                    <Pressable
+                        style={[styles.sheetCard, { backgroundColor: theme.cardBg }]}
+                        onPress={() => {}}
+                        accessibilityRole="none"
+                    >
+                        <SafeAreaView
+                            style={[
+                                styles.sheetSafeArea,
+                                { backgroundColor: theme.cardBg },
+                            ]}
+                        >
+                            <ScrollView
+                                style={styles.sheetScroll}
+                                contentContainerStyle={styles.sheetContent}
+                                showsVerticalScrollIndicator={false}
+                                keyboardShouldPersistTaps="handled"
+                            >
+                                <View style={styles.sheetHandle} />
+                                {children}
+                            </ScrollView>
+                        </SafeAreaView>
+                    </Pressable>
+                </Pressable>
+            </KeyboardAvoidingView>
+        </Modal>
+    );
+}
+
+function BottomSheetInApp(props: InAppBranchProps): ReactElement {
+    return (
+        <SheetSurface theme={props.theme} onDismiss={props.onDismiss}>
+            <BranchContent {...props} />
+        </SheetSurface>
+    );
+}
+
+// ─── Additive surfaces — canonical variants outside the legacy seven ────────
+
+function MultiStepSheetInApp(props: InAppBranchProps): ReactElement {
+    const rawSteps = Array.isArray(props.spec.ext?.steps) ? props.spec.ext.steps : [];
+    const steps = rawSteps.filter((step): step is Record<string, unknown> =>
+        step !== null && typeof step === 'object' && !Array.isArray(step),
+    );
+    const [stepIndex, setStepIndex] = useState(0);
+    const stepCount = steps.length;
+    const current = steps[Math.min(stepIndex, Math.max(0, stepCount - 1))];
+    const title = typeof current?.title === 'string' ? current.title : props.spec.title;
+    const body = typeof current?.body === 'string' ? current.body : props.spec.body;
+    const image = typeof current?.image === 'string'
+        ? current.image
+        : typeof current?.stepImage === 'string'
+          ? current.stepImage
+          : undefined;
+    const mediaHeight = resolveInAppMediaHeight(props.spec, 140, 320);
+    const last = stepCount === 0 || stepIndex >= stepCount - 1;
+    const labels = resolveMultiStepSheetLabels(props.spec);
+    const progressAt = (index: number): number =>
+        stepCount > 0 ? (index + 1) / stepCount : 0;
+    const runTerminal = (action: MultiStepSheetTerminalAction): void => {
+        if (action.kind === 'cta') props.onCta(action.cta);
+        else props.onDismiss();
+    };
+    const back = (): void => {
+        const previousIndex = resolveMultiStepSheetIndex(stepIndex, stepCount, 'back');
+        setStepIndex(previousIndex);
+        props.onInteraction?.({
+            mechanic: 'multi_step_sheet',
+            phase: 'progress',
+            progress: progressAt(previousIndex),
+            result: 'back',
+            value: previousIndex + 1,
+        });
+    };
+    const skip = (): void => {
+        props.onInteraction?.({
+            mechanic: 'multi_step_sheet',
+            phase: 'decision',
+            progress: progressAt(stepIndex),
+            result: 'skipped',
+            value: stepIndex + 1,
+        });
+        runTerminal(resolveMultiStepSheetTerminalAction(props.spec.secondaryCta));
+    };
+    const next = (): void => {
+        if (!last) {
+            const nextIndex = resolveMultiStepSheetIndex(stepIndex, stepCount, 'next');
+            setStepIndex(nextIndex);
+            props.onInteraction?.({
+                mechanic: 'multi_step_sheet',
+                phase: 'progress',
+                progress: progressAt(nextIndex),
+                result: 'next',
+                value: nextIndex + 1,
+            });
+            return;
+        }
+        props.onInteraction?.({
+            mechanic: 'multi_step_sheet',
+            phase: 'completed',
+            progress: 1,
+            result: 'finished',
+            value: stepCount > 0 ? stepCount : 1,
+        });
+        const terminal = resolveMultiStepSheetTerminalAction(props.spec.cta);
+        if (props.onOutcome) {
+            props.onOutcome({
+                fallback: terminal.kind === 'cta'
+                    ? terminal
+                    : { kind: 'dismiss' },
+            });
+            return;
+        }
+        runTerminal(terminal);
+    };
+    return (
+        <SheetSurface theme={props.theme} onDismiss={props.onDismiss}>
+            {stepCount > 1 ? (
+                <View
+                    accessibilityRole="progressbar"
+                    accessibilityLabel={`Step ${stepIndex + 1} of ${stepCount}`}
+                    accessibilityValue={{ min: 1, max: stepCount, now: stepIndex + 1 }}
+                    style={styles.stepProgress}
+                >
+                    <Text
+                        style={[styles.stepLabel, { color: props.theme.secondaryColor }]}
+                    >{`Step ${stepIndex + 1} of ${stepCount}`}</Text>
+                    <View style={styles.stepTrack}>
+                        <View
+                            style={[
+                                styles.stepFill,
+                                {
+                                    backgroundColor: props.theme.accent,
+                                    width: `${((stepIndex + 1) / stepCount) * 100}%`,
+                                },
+                            ]}
+                        />
+                    </View>
+                </View>
+            ) : null}
+            <View style={styles.contentBlock}>
+                {image ? (
+                    <Image
+                        source={{ uri: image }}
+                        resizeMode="cover"
+                        style={[
+                            styles.image,
+                            mediaHeight === undefined ? null : { height: mediaHeight },
+                        ]}
+                    />
+                ) : null}
+                {title ? <Text style={[styles.title, { color: props.theme.titleColor }]}>{title}</Text> : null}
+                {body ? <Text style={[styles.body, { color: props.theme.bodyColor }]}>{body}</Text> : null}
+            </View>
+            <View style={styles.actions}>
+                {stepIndex > 0 ? (
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel={labels.back}
+                        onPress={back}
+                        style={styles.secondaryBtn}
+                    >
+                        <Text style={[styles.secondaryText, { color: props.theme.secondaryColor }]}>{labels.back}</Text>
+                    </Pressable>
+                ) : null}
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={labels.skip}
+                    onPress={skip}
+                    style={styles.secondaryBtn}
+                >
+                    <Text style={[styles.secondaryText, { color: props.theme.secondaryColor }]}>{labels.skip}</Text>
+                </Pressable>
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={last ? labels.finish : labels.next}
+                    onPress={next}
+                    style={[styles.primaryBtn, { backgroundColor: props.theme.accent }]}
+                >
+                    <Text style={[styles.primaryText, { color: props.theme.ctaText }]}>
+                        {last ? labels.finish : labels.next}
+                    </Text>
+                </Pressable>
+            </View>
+        </SheetSurface>
+    );
+}
+
+function SideSheetInApp(props: InAppBranchProps): ReactElement {
+    const { theme, onDismiss } = props;
+    const side = props.spec.ext?.sidePosition === 'left' ? 'left' : 'right';
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="fade"
+            statusBarTranslucent={false}
+            onRequestClose={onDismiss}
+        >
+            <KeyboardAvoidingView
+                behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+                style={styles.keyboardAvoider}
+            >
+                <Pressable
+                    accessibilityRole="none"
+                    onPress={onDismiss}
+                    style={[
+                        styles.sideSheetBackdrop,
+                        { backgroundColor: theme.backdrop },
+                        side === 'left' ? styles.sideSheetLeft : styles.sideSheetRight,
+                    ]}
+                >
+                    <Pressable
+                        accessibilityRole="none"
+                        onPress={() => {}}
+                        style={[
+                            styles.sideSheetPanel,
+                            { backgroundColor: theme.cardBg },
+                            side === 'left' ? styles.sideSheetPanelLeft : styles.sideSheetPanelRight,
+                        ]}
+                    >
+                        <SafeAreaView style={styles.sideSheetSafeArea}>
+                            <View style={styles.sideSheetHeader}>
+                                <CloseBtn onPress={onDismiss} />
+                            </View>
+                            <ScrollView
+                                style={styles.sideSheetScroll}
+                                contentContainerStyle={styles.sideSheetContent}
+                                showsVerticalScrollIndicator={false}
+                                keyboardShouldPersistTaps="handled"
+                            >
+                                <BranchContent {...props} />
+                            </ScrollView>
+                        </SafeAreaView>
+                    </Pressable>
+                </Pressable>
+            </KeyboardAvoidingView>
+        </Modal>
+    );
+}
+
+function PeekCardInApp(props: InAppBranchProps): ReactElement {
+    const [expanded, setExpanded] = useState(false);
+    const peekLabel = typeof props.spec.ext?.peekLabel === 'string' ? props.spec.ext.peekLabel : 'View more';
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="slide"
+            statusBarTranslucent={false}
+            onRequestClose={props.onDismiss}
+        >
+            <KeyboardAvoidingView
+                behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+                style={styles.peekRoot}
+                pointerEvents="box-none"
+            >
+                {expanded ? (
+                    <Pressable style={[styles.peekExpanded, { backgroundColor: props.theme.cardBg }]} onPress={() => {}}>
+                        <SafeAreaView
+                            style={[
+                                styles.peekSafeArea,
+                                { backgroundColor: props.theme.cardBg },
+                            ]}
+                        >
+                            <ScrollView
+                                style={styles.peekScroll}
+                                contentContainerStyle={styles.peekExpandedContent}
+                                showsVerticalScrollIndicator={false}
+                                keyboardShouldPersistTaps="handled"
+                            >
+                                <View style={styles.sheetHandle} />
+                                <CloseBtn onPress={props.onDismiss} style={styles.peekClose} />
+                                <BranchContent {...props} />
+                            </ScrollView>
+                        </SafeAreaView>
+                    </Pressable>
+                ) : (
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel={peekLabel}
+                        onPress={() => {
+                            setExpanded(true);
+                            props.onInteraction?.({ mechanic: 'peek_card', phase: 'started' });
+                        }}
+                        style={[styles.peekCollapsed, { backgroundColor: props.theme.cardBg, borderColor: props.theme.accent }]}
+                    >
+                        <SafeAreaView
+                            style={[
+                                styles.peekSafeArea,
+                                { backgroundColor: props.theme.cardBg },
+                            ]}
+                        >
+                            <View style={styles.peekCollapsedContent}>
+                                <View style={styles.sheetHandle} />
+                                <Text style={[styles.peekLabel, { color: props.theme.titleColor }]}>{peekLabel}</Text>
+                            </View>
+                        </SafeAreaView>
+                    </Pressable>
+                )}
+            </KeyboardAvoidingView>
+        </Modal>
+    );
+}
+
+const ADDITIVE_INAPP_RENDERERS: Partial<Record<InAppArchetype, InAppRenderer>> = {
+    multiStepSheet: MultiStepSheetInApp,
+    sideSheet: SideSheetInApp,
+};
+
+// ─── 4. top_banner — strip pinned to top ─────────────────────────────────────
+
+function TopBannerInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const window = useWindowDimensions();
+    const edge = screenPosition(spec.ext?.position)
+        ?? screenPosition(spec.ext?.layoutPosition)
+        ?? 'top';
+    const rawProgress = spec.ext?.progress;
+    const stickyProgress = props.variantKey === 'sticky_header_bar' && typeof rawProgress === 'number'
+        ? clamp(rawProgress <= 1 ? rawProgress * 100 : rawProgress, 0, 100)
+        : null;
+    return (
+        <ScreenEdgeSurface edge={edge === 'bottom' ? 'bottom' : 'top'} contentStyle={styles.bannerWrap}>
+            <View style={[styles.bannerCard, { backgroundColor: theme.cardBg }, theme.rtl ? { flexDirection: 'row-reverse' } : null]}>
+                <ScrollView
+                    style={[styles.bannerContent, { maxHeight: Math.max(120, window.height * 0.45) }]}
+                    showsVerticalScrollIndicator={false}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    {props.variantKey === 'sticky_header_bar' ? <Text style={[styles.stickyLabel, { color: theme.accent }]}>PINNED</Text> : null}
+                    <BranchContent {...props} />
+                    {stickyProgress !== null ? (
+                        <View
+                            accessibilityRole="progressbar"
+                            accessibilityValue={{ min: 0, max: 100, now: Math.round(stickyProgress) }}
+                            style={styles.stickyTrack}
+                        >
+                            <View style={[styles.stickyFill, { backgroundColor: theme.accent, width: `${stickyProgress}%` }]} />
+                        </View>
+                    ) : null}
+                </ScrollView>
+                <CloseBtn onPress={onDismiss} style={styles.bannerClosePos} />
+            </View>
+        </ScreenEdgeSurface>
+    );
+}
+
+// ─── 5. bottom_banner — strip pinned to bottom ───────────────────────────────
+
+function BottomBannerInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const window = useWindowDimensions();
+    const edge = screenPosition(spec.ext?.position)
+        ?? screenPosition(spec.ext?.layoutPosition)
+        ?? 'bottom';
+    return (
+        <ScreenEdgeSurface edge={edge === 'top' ? 'top' : 'bottom'} contentStyle={styles.bannerWrap}>
+            <View style={[styles.bannerCard, { backgroundColor: theme.cardBg }, theme.rtl ? { flexDirection: 'row-reverse' } : null]}>
+                <ScrollView
+                    style={[styles.bannerContent, { maxHeight: Math.max(120, window.height * 0.45) }]}
+                    showsVerticalScrollIndicator={false}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    {props.variantKey === 'sticky_footer_bar' ? <Text style={[styles.stickyLabel, { color: theme.accent }]}>PINNED</Text> : null}
+                    <BranchContent {...props} />
+                </ScrollView>
+                <CloseBtn onPress={onDismiss} style={styles.bannerClosePos} />
+            </View>
+        </ScreenEdgeSurface>
+    );
+}
+
+// ─── 6. floating tooltip (bubble fallback only) ──────────────────────────────
+
+function FloatingTooltipInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const window = useWindowDimensions();
+    const floatingBubble = props.variantKey === 'floating_bubble';
+    const [expanded, setExpanded] = useState(!floatingBubble);
+    const authoredPosition = typeof spec.ext?.position === 'string'
+        ? spec.ext.position.toLowerCase()
+        : typeof spec.ext?.layoutPosition === 'string'
+          ? spec.ext.layoutPosition.toLowerCase()
+          : 'bottom-right';
+    const edge = authoredPosition.includes('top') ? 'top' : 'bottom';
+    const edgeStyle = [
+        styles.floatingEdge,
+        authoredPosition.includes('left') ? styles.edgeAlignLeft : styles.edgeAlignRight,
+    ];
+    if (floatingBubble && !expanded) {
+        const label = typeof spec.ext?.bubbleLabel === 'string' ? spec.ext.bubbleLabel : 'Open';
+        return (
+            <ScreenEdgeSurface edge={edge} contentStyle={edgeStyle}>
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={label}
+                    onPress={() => {
+                        setExpanded(true);
+                        props.onInteraction?.({ mechanic: 'floating_bubble', phase: 'started', value: spec.ext?.tapAction as string | undefined });
+                    }}
+                    style={[styles.floatingBubble, { backgroundColor: theme.accent }]}
+                >
+                    <Text style={[styles.floatingBubbleText, { color: theme.ctaText }]}>{label}</Text>
+                </Pressable>
+            </ScreenEdgeSurface>
+        );
+    }
+    return (
+        <ScreenEdgeSurface edge={edge} contentStyle={edgeStyle}>
+            <View style={[styles.floatingPanel, { maxHeight: Math.max(120, window.height * 0.6) }]}>
+                <View style={[styles.tooltipCard, { backgroundColor: theme.cardBg }]}>
+                    <CloseBtn onPress={onDismiss} style={styles.tooltipClosePos} />
+                    <ScrollView
+                        style={styles.floatingScroll}
+                        showsVerticalScrollIndicator={false}
+                        keyboardShouldPersistTaps="handled"
+                    >
+                        {props.children !== undefined ? <>{props.children}</> : (
+                            <>
+                                {spec.title ? <Text style={[styles.tooltipTitle, { color: theme.titleColor }, rtlText(theme)]}>{spec.title}</Text> : null}
+                                <Text style={[styles.tooltipBody, { color: theme.bodyColor }, rtlText(theme)]}>{spec.body}</Text>
+                                {spec.coupon ? <CouponChip code={spec.coupon} theme={theme} /> : null}
+                                {spec.cta ? (
+                                    <Pressable
+                                        accessibilityRole="button"
+                                        accessibilityLabel={spec.cta.label}
+                                        onPress={() => spec.cta!.action === 'dismiss' ? onDismiss() : props.onCta(spec.cta!)}
+                                        style={styles.tooltipCta}
+                                    >
+                                        <Text style={[styles.tooltipCtaText, { color: theme.accent }]}>{spec.cta.label}</Text>
+                                    </Pressable>
+                                ) : null}
+                            </>
+                        )}
+                    </ScrollView>
+                </View>
+            </View>
+        </ScreenEdgeSurface>
+    );
+}
+
+/** A placement-only micro popover; unlike coachmarks it does not require a measured anchor. */
+function MiniPopoverInApp(props: InAppBranchProps): ReactElement {
+    const placement = props.spec.ext?.placement;
+    const atBottom = placement === 'bottom';
+    const window = useWindowDimensions();
+    return (
+        <ScreenEdgeSurface
+            edge={atBottom ? 'bottom' : 'top'}
+            contentStyle={[
+                styles.floatingEdge,
+                placement === 'left' ? styles.edgeAlignLeft : styles.edgeAlignRight,
+            ]}
+        >
+            <View style={[styles.miniPopoverPanel, { maxHeight: Math.max(120, window.height * 0.6) }]}>
+                <View style={[styles.tooltipCard, { backgroundColor: props.theme.cardBg }]}>
+                    <CloseBtn onPress={props.onDismiss} style={styles.tooltipClosePos} />
+                    <ScrollView
+                        style={styles.floatingScroll}
+                        showsVerticalScrollIndicator={false}
+                        keyboardShouldPersistTaps="handled"
+                    >
+                        <BranchContent {...props} />
+                    </ScrollView>
+                </View>
+            </View>
+        </ScreenEdgeSurface>
+    );
+}
+
+const rectStyle = (rect: EngageAnchorRect): ViewStyle => ({
+    position: 'absolute',
+    left: rect.x,
+    top: rect.y,
+    width: rect.width,
+    height: rect.height,
+});
+
+type MeasuredCoachmark = {
+    anchorKey: string;
+    anchor: EngageAnchorRect;
+    viewport: { width: number; height: number };
+};
+
+interface MeasuredAnchorOptions {
+    anchorKey: string;
+    readyKey?: string;
+    onReady?: () => void;
+    onRenderError?: (reason: string) => void;
+}
+
+/** Measure an anchor relative to its overlay and repeat after rotation/layout changes. */
+function useMeasuredAnchor({
+    anchorKey,
+    readyKey = anchorKey,
+    onReady,
+    onRenderError,
+}: MeasuredAnchorOptions): {
+    overlayRef: React.RefObject<View>;
+    measured: MeasuredCoachmark | null;
+    remeasureOverlay: () => void;
+} {
+    const registry = useEngageAnchorRegistry();
+    const overlayRef = useRef<View>(null);
+    const onReadyRef = useRef(onReady);
+    const onErrorRef = useRef(onRenderError);
+    const readyKeyRef = useRef<string | null>(null);
+    const [measured, setMeasured] = useState<MeasuredCoachmark | null>(null);
+    const [overlayRevision, setOverlayRevision] = useState(0);
+    const window = useWindowDimensions();
+
+    onReadyRef.current = onReady;
+    onErrorRef.current = onRenderError;
+
+    const remeasureOverlay = useCallback((): void => {
+        setOverlayRevision((revision) => revision + 1);
+    }, []);
+
+    useEffect(() => {
+        setMeasured(null);
+        readyKeyRef.current = null;
+        if (!anchorKey) {
+            onErrorRef.current?.('missing_anchor_key');
+            return;
+        }
+
+        let cancelled = false;
+        let exhausted = false;
+        let attempts = 0;
+        let retry: ReturnType<typeof setTimeout> | null = null;
+
+        const failOrRetry = (): void => {
+            if (cancelled || exhausted) return;
+            if (attempts >= 20) {
+                exhausted = true;
+                onErrorRef.current?.(coachmarkAnchorError(anchorKey));
+                return;
+            }
+            attempts += 1;
+            retry = setTimeout(measure, 100);
+        };
+
+        const measure = (): void => {
+            if (cancelled || exhausted) return;
+            const overlay = overlayRef.current;
+            if (!overlay) {
+                failOrRetry();
+                return;
+            }
+            overlay.measureInWindow((overlayX, overlayY, overlayWidth, overlayHeight) => {
+                if (cancelled || overlayWidth <= 0 || overlayHeight <= 0) {
+                    failOrRetry();
+                    return;
+                }
+                const found = registry.measure(anchorKey, (anchor) => {
+                    if (cancelled) return;
+                    if (!anchor) {
+                        failOrRetry();
+                        return;
+                    }
+                    const local = {
+                        x: anchor.x - overlayX,
+                        y: anchor.y - overlayY,
+                        width: anchor.width,
+                        height: anchor.height,
+                    };
+                    const visible = local.x + local.width > 0 &&
+                        local.y + local.height > 0 &&
+                        local.x < overlayWidth &&
+                        local.y < overlayHeight;
+                    if (!visible) {
+                        failOrRetry();
+                        return;
+                    }
+                    setMeasured({
+                        anchorKey,
+                        anchor: local,
+                        viewport: { width: overlayWidth, height: overlayHeight },
+                    });
+                    if (readyKeyRef.current !== readyKey) {
+                        readyKeyRef.current = readyKey;
+                        onReadyRef.current?.();
+                    }
+                });
+                if (!found) failOrRetry();
+            });
+        };
+
+        const unsubscribe = registry.subscribe(anchorKey, () => {
+            attempts = 0;
+            if (retry) clearTimeout(retry);
+            measure();
+        });
+        const kickoff = setTimeout(measure, 0);
+        return () => {
+            cancelled = true;
+            clearTimeout(kickoff);
+            if (retry) clearTimeout(retry);
+            unsubscribe();
+        };
+    }, [anchorKey, overlayRevision, readyKey, registry, window.height, window.width]);
+
+    return {
+        overlayRef,
+        measured: measured?.anchorKey === anchorKey ? measured : null,
+        remeasureOverlay,
+    };
+}
+
+interface AnchoredCardProps {
+    geometry: CoachmarkGeometry;
+    theme: InAppTheme;
+    onDismiss: () => void;
+    onLayout: (event: LayoutChangeEvent) => void;
+    children: ReactNode;
+}
+
+/** Shared measured card/arrow; spotlight and tooltip differ only in their root. */
+function AnchoredCard({
+    geometry,
+    theme,
+    onDismiss,
+    onLayout,
+    children,
+}: AnchoredCardProps): ReactElement {
+    return (
+        <View
+            style={[
+                styles.coachmarkTooltipWrap,
+                {
+                    left: geometry.tooltip.left,
+                    width: geometry.tooltip.width,
+                    ...(geometry.tooltip.top !== undefined
+                        ? { top: geometry.tooltip.top }
+                        : { bottom: geometry.tooltip.bottom }),
+                },
+            ]}
+        >
+            <View
+                pointerEvents="none"
+                style={[
+                    styles.coachmarkArrow,
+                    {
+                        ...(geometry.tooltip.arrowLeft !== undefined
+                            ? { left: geometry.tooltip.arrowLeft }
+                            : { top: geometry.tooltip.arrowTop }),
+                        backgroundColor: theme.cardBg,
+                    },
+                    geometry.tooltip.placement === 'bottom'
+                        ? styles.coachmarkArrowTop
+                        : geometry.tooltip.placement === 'top'
+                        ? styles.coachmarkArrowBottom
+                        : geometry.tooltip.placement === 'left'
+                        ? styles.coachmarkArrowRight
+                        : styles.coachmarkArrowLeft,
+                ]}
+            />
+            <View
+                onLayout={onLayout}
+                style={[
+                    styles.coachmarkCard,
+                    { backgroundColor: theme.cardBg, maxHeight: geometry.tooltip.maxHeight },
+                ]}
+            >
+                <CloseBtn onPress={onDismiss} style={styles.tooltipClosePos} />
+                <ScrollView
+                    style={styles.coachmarkScroll}
+                    showsVerticalScrollIndicator={false}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    {children}
+                </ScrollView>
+            </View>
+        </View>
+    );
+}
+
+const coachmarkLabel = (value: unknown, fallback: string): string =>
+    typeof value === 'string' && value.trim() ? value.trim() : fallback;
+
+/** Plain tooltip: attached to an anchor without dimming or blocking the host screen. */
+function AnchoredTooltipInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const step = useMemo(() => normalizeLegacyAnchoredStep(spec), [spec]);
+    const [cardHeight, setCardHeight] = useState(160);
+    // Android's RN content root commonly consumes system bars; iOS needs the raw
+    // safe-area because an absolute sibling can extend beneath a cutout.
+    const nativeInsets = useEngageWindowInsets(Platform.OS === 'android');
+    const safeInsets = nativeInsets ?? (Platform.OS === 'ios'
+        ? { top: 44, right: 0, bottom: 34, left: 0 }
+        : ZERO_ENGAGE_WINDOW_INSETS);
+    const { overlayRef, measured, remeasureOverlay } = useMeasuredAnchor({
+        anchorKey: step?.anchorKey ?? '',
+        onReady: props.onReady,
+        onRenderError: props.onRenderError,
+    });
+    const geometry = measured && step
+        ? resolveCoachmarkGeometry(measured.anchor, measured.viewport, step.placement, {
+            cardHeight,
+            insets: safeInsets,
+        })
+        : null;
+    const measureCard = useCallback((event: LayoutChangeEvent): void => {
+        const next = Math.round(event.nativeEvent.layout.height);
+        if (next > 0) setCardHeight((current) => Math.abs(current - next) > 1 ? next : current);
+    }, []);
+
+    return (
+        <View
+            ref={overlayRef}
+            collapsable={false}
+            pointerEvents="box-none"
+            style={styles.anchoredTooltipRoot}
+            onLayout={remeasureOverlay}
+        >
+            {geometry && step ? (
+                <AnchoredCard
+                    geometry={geometry}
+                    theme={theme}
+                    onDismiss={onDismiss}
+                    onLayout={measureCard}
+                >
+                    {props.variantKey === 'fab_prompt' ? (
+                        <Text style={[styles.coachmarkEyebrow, { color: theme.accent }]}>＋ QUICK ACTION</Text>
+                    ) : null}
+                    {step.title ? <Text style={[styles.tooltipTitle, { color: theme.titleColor }, rtlText(theme)]}>{step.title}</Text> : null}
+                    {step.body ? <Text style={[styles.tooltipBody, { color: theme.bodyColor }, rtlText(theme)]}>{step.body}</Text> : null}
+                    {step.cta ? (
+                        <Pressable
+                            accessibilityRole="button"
+                            accessibilityLabel={step.cta.label}
+                            onPress={() => step.cta!.action === 'dismiss' ? onDismiss() : props.onCta(step.cta!)}
+                            style={styles.tooltipCta}
+                        >
+                            <Text style={[styles.tooltipCtaText, { color: theme.accent }]}>{step.cta.label}</Text>
+                        </Pressable>
+                    ) : null}
+                </AnchoredCard>
+            ) : null}
+        </View>
+    );
+}
+
+/** Guided tour: one measured spotlight per ordered step, with full-screen scrim. */
+function CoachmarkSpotlightInApp(props: InAppBranchProps): ReactElement {
+    const { spec, theme, onDismiss } = props;
+    const steps = useMemo(() => normalizeCoachmarkSteps(spec), [spec]);
+    const [stepIndex, setStepIndex] = useState(0);
+    const [cardHeight, setCardHeight] = useState(160);
+    const viewedStepsRef = useRef(new Set<number>());
+    const step = steps[stepIndex];
+    const nativeInsets = useEngageWindowInsets();
+    const safeInsets = nativeInsets ?? (Platform.OS === 'ios'
+        ? { top: 59, right: 44, bottom: 34, left: 44 }
+        : { top: StatusBar.currentHeight ?? 0, right: 0, bottom: 16, left: 0 });
+
+    useEffect(() => {
+        setStepIndex(0);
+        setCardHeight(160);
+        viewedStepsRef.current.clear();
+    }, [steps]);
+
+    const handleStepReady = useCallback((): void => {
+        props.onReady?.();
+        if (viewedStepsRef.current.has(stepIndex)) return;
+        viewedStepsRef.current.add(stepIndex);
+        props.onInteraction?.({
+            mechanic: 'coachmark_spotlight',
+            phase: stepIndex === 0 ? 'started' : 'progress',
+            result: 'step_viewed',
+            meta: { anchorKey: step?.anchorKey, step: stepIndex + 1, totalSteps: steps.length },
+        });
+    }, [props, step?.anchorKey, stepIndex, steps.length]);
+
+    const { overlayRef, measured, remeasureOverlay } = useMeasuredAnchor({
+        anchorKey: step?.anchorKey ?? '',
+        readyKey: `${stepIndex}:${step?.anchorKey ?? ''}`,
+        onReady: handleStepReady,
+        onRenderError: props.onRenderError,
+    });
+
+    const geometry = measured
+        ? resolveCoachmarkGeometry(measured.anchor, measured.viewport, step?.placement, {
+            cardHeight,
+            insets: safeInsets,
+        })
+        : null;
+    const measureCard = useCallback((event: LayoutChangeEvent): void => {
+        const next = Math.round(event.nativeEvent.layout.height);
+        if (next > 0) setCardHeight((current) => Math.abs(current - next) > 1 ? next : current);
+    }, []);
+    const scrim = spec.style?.backdrop ?? 'rgba(0,0,0,0.68)';
+    const radius = typeof spec.ext?.spotlightRadius === 'number'
+        ? clamp(spec.ext.spotlightRadius, 0, 40)
+        : 14;
+    const finalCta = stepIndex === steps.length - 1 ? step?.cta ?? spec.cta : undefined;
+    const goTo = (result: 'next' | 'back'): void => {
+        const nextIndex = resolveCoachmarkStepIndex(stepIndex, steps.length, result);
+        props.onInteraction?.({
+            mechanic: 'coachmark_spotlight',
+            phase: 'progress',
+            result,
+            meta: {
+                anchorKey: step?.anchorKey,
+                fromStep: stepIndex + 1,
+                toStep: nextIndex + 1,
+                totalSteps: steps.length,
+            },
+        });
+        setCardHeight(160);
+        setStepIndex(nextIndex);
+    };
+    const skip = (): void => {
+        props.onInteraction?.({
+            mechanic: 'coachmark_spotlight',
+            phase: 'decision',
+            result: 'skipped',
+            meta: { anchorKey: step?.anchorKey, step: stepIndex + 1, totalSteps: steps.length },
+        });
+        onDismiss();
+    };
+    const finish = (): void => {
+        props.onInteraction?.({
+            mechanic: 'coachmark_spotlight',
+            phase: 'completed',
+            result: 'finished',
+            meta: { anchorKey: step?.anchorKey, step: stepIndex + 1, totalSteps: steps.length },
+        });
+        if (resolveCoachmarkFinishMode(finalCta) === 'cta' && finalCta) props.onCta(finalCta);
+        else if (props.onComplete) props.onComplete();
+        else onDismiss();
+    };
+
+    return (
+        <Modal
+            visible
+            transparent
+            animationType="fade"
+            statusBarTranslucent
+            onRequestClose={onDismiss}
+        >
+            <View
+                ref={overlayRef}
+                collapsable={false}
+                style={styles.coachmarkRoot}
+                onLayout={remeasureOverlay}
+                pointerEvents="box-none"
+            >
+                {geometry && step ? <>
+                    {geometry.scrims.map((rect, index) => (
+                        <Pressable
+                            key={index}
+                            accessibilityRole="none"
+                            onPress={onDismiss}
+                            style={[rectStyle(rect), { backgroundColor: scrim }]}
+                        />
+                    ))}
+                    <View
+                        pointerEvents="none"
+                        style={[
+                            styles.coachmarkSpotlight,
+                            rectStyle(geometry.spotlight),
+                            { borderRadius: radius, borderColor: theme.accent },
+                        ]}
+                    />
+                    <AnchoredCard
+                        geometry={geometry}
+                        theme={theme}
+                        onDismiss={skip}
+                        onLayout={measureCard}
+                    >
+                        <Text style={[styles.coachmarkEyebrow, { color: theme.accent }]}>STEP {stepIndex + 1} OF {steps.length}</Text>
+                        {step.title ? <Text style={[styles.tooltipTitle, { color: theme.titleColor }, rtlText(theme)]}>{step.title}</Text> : null}
+                        {step.body ? <Text style={[styles.tooltipBody, { color: theme.bodyColor }, rtlText(theme)]}>{step.body}</Text> : null}
+                        <View style={styles.coachmarkActions}>
+                            <Pressable
+                                accessibilityRole="button"
+                                accessibilityLabel={coachmarkLabel(spec.ext?.skipLabel, 'Skip tour')}
+                                onPress={skip}
+                                style={styles.coachmarkTextButton}
+                            >
+                                <Text style={[styles.coachmarkSecondaryText, { color: theme.bodyColor }]}>{coachmarkLabel(spec.ext?.skipLabel, 'Skip')}</Text>
+                            </Pressable>
+                            <View style={styles.coachmarkNavActions}>
+                                {stepIndex > 0 ? (
+                                    <Pressable
+                                        accessibilityRole="button"
+                                        accessibilityLabel={coachmarkLabel(spec.ext?.backLabel, 'Previous step')}
+                                        onPress={() => goTo('back')}
+                                        style={styles.coachmarkTextButton}
+                                    >
+                                        <Text style={[styles.coachmarkSecondaryText, { color: theme.bodyColor }]}>{coachmarkLabel(spec.ext?.backLabel, 'Back')}</Text>
+                                    </Pressable>
+                                ) : null}
+                                <Pressable
+                                    accessibilityRole="button"
+                                    accessibilityLabel={stepIndex < steps.length - 1
+                                        ? coachmarkLabel(spec.ext?.nextLabel, 'Next step')
+                                        : coachmarkLabel(spec.ext?.finishLabel, finalCta?.label ?? spec.cta?.label ?? 'Finish tour')}
+                                    onPress={() => stepIndex < steps.length - 1
+                                        ? goTo('next')
+                                        : finish()}
+                                    style={[styles.coachmarkPrimaryButton, { backgroundColor: theme.accent }]}
+                                >
+                                    <Text style={[styles.coachmarkPrimaryText, { color: theme.ctaText }]}>
+                                        {stepIndex < steps.length - 1
+                                            ? coachmarkLabel(spec.ext?.nextLabel, 'Next')
+                                            : coachmarkLabel(spec.ext?.finishLabel, finalCta?.label ?? spec.cta?.label ?? 'Finish')}
+                                    </Text>
+                                </Pressable>
+                            </View>
+                        </View>
+                    </AnchoredCard>
+                </> : null}
+            </View>
+        </Modal>
+    );
+}
+
+function AnchoredInApp(props: InAppBranchProps): ReactElement {
+    return resolveAnchoredSurfaceKind(props.variantKey) === 'spotlight'
+        ? <CoachmarkSpotlightInApp {...props} />
+        : <AnchoredTooltipInApp {...props} />;
+}
+
+// ─── inline — participates in host layout and never opens an overlay ─────────
+
+function InlineInApp(props: InAppBranchProps): ReactElement {
+    const { theme, onDismiss } = props;
+    return (
+        <View style={[styles.inlineCard, { backgroundColor: theme.cardBg }]}>
+            <CloseBtn onPress={onDismiss} style={styles.inlineClosePos} />
+            <BranchContent {...props} />
+        </View>
+    );
+}
+
+// ─── 7. toast — transient strip, auto-dismisses after 3 s ────────────────────
+
+export function resolveToastDuration(value: unknown): number {
+    return clamp(typeof value === 'number' && Number.isFinite(value) ? value : 3000, 1000, 60_000);
+}
+
+function ToastInApp(props: InAppBranchProps): ReactElement {
+    const { spec, onDismiss } = props;
+    const window = useWindowDimensions();
+    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const autoDismiss = spec.ext?.autoDismiss !== false;
+    const duration = resolveToastDuration(
+        typeof spec.ext?.autoDismiss === 'number' ? spec.ext.autoDismiss : spec.ext?.durationMs,
+    );
+    useEffect(() => {
+        if (!autoDismiss) return;
+        timerRef.current = setTimeout(onDismiss, duration);
+        return () => { if (timerRef.current) clearTimeout(timerRef.current); };
+    // onDismiss identity stable (memoized in provider); exhaustive-deps would re-arm on every render
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [autoDismiss, duration]);
+    const { theme } = props;
+    const position = screenPosition(spec.ext?.position)
+        ?? screenPosition(spec.ext?.layoutPosition)
+        ?? 'bottom';
+    const edge = position === 'top' ? 'top' : 'bottom';
+    return (
+        <ScreenEdgeSurface edge={edge} contentStyle={styles.toastWrap}>
+            <Pressable style={[styles.toastCard, { backgroundColor: theme.cardBg }]} onPress={onDismiss} accessibilityRole="none">
+                <ScrollView
+                    style={[styles.toastScroll, { maxHeight: Math.max(96, window.height * 0.4) }]}
+                    showsVerticalScrollIndicator={false}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    {props.children !== undefined ? <>{props.children}</> : (
+                        <>
+                            {spec.title ? <Text style={[styles.toastTitle, { color: theme.titleColor }, rtlText(theme)]}>{spec.title}</Text> : null}
+                            <Text style={[styles.toastBody, { color: theme.bodyColor }, rtlText(theme)]} numberOfLines={2}>{spec.body}</Text>
+                            {spec.cta ? (
+                                <Pressable
+                                    accessibilityRole="button"
+                                    accessibilityLabel={spec.cta.label}
+                                    onPress={() => spec.cta!.action === 'dismiss' ? onDismiss() : props.onCta(spec.cta!)}
+                                >
+                                    <Text style={[styles.toastCtaText, { color: theme.accent }]}>{spec.cta.label}</Text>
+                                </Pressable>
+                            ) : null}
+                        </>
+                    )}
+                </ScrollView>
+            </Pressable>
+        </ScreenEdgeSurface>
+    );
+}
+
+// ─── Open/Closed registry ─────────────────────────────────────────────────────
+
+export const INAPP_RENDERERS: Record<InAppLayout, InAppRenderer> = {
+    modal:         ModalInApp,
+    fullscreen:    FullScreenInApp,
+    bottom_sheet:  BottomSheetInApp,
+    top_banner:    TopBannerInApp,
+    bottom_banner: BottomBannerInApp,
+    tooltip:       AnchoredInApp,
+    toast:         ToastInApp,
+};
+
+const MOUNT_MODEL_RENDERERS: Record<InAppMountModel, InAppRenderer> = {
+    overlay: ModalInApp,
+    sheet: BottomSheetInApp,
+    banner: TopBannerInApp,
+    fullscreen: FullScreenInApp,
+    toast: ToastInApp,
+    bubble: FloatingTooltipInApp,
+    anchored: AnchoredInApp,
+    inline: InlineInApp,
+};
+
+/** Resolve the render branch for a config layout (always defined). */
+export function resolveInAppRenderer(layout: InAppMessageConfig['layout']): InAppRenderer {
+    return INAPP_RENDERERS[resolveInAppLayout(layout)];
+}
+
+/**
+ * Resolve canonical additive surfaces before degrading to the stable seven-layout
+ * registry. Content remains a child of the selected surface in either path.
+ */
+export function resolveInAppPresentationRenderer(
+    presentation: Pick<ResolvedInAppPresentation, 'archetype' | 'mountModel' | 'legacyLayout' | 'variantKey'>,
+    mountModelOverride?: InAppMountModel,
+): InAppRenderer {
+    if (mountModelOverride) return MOUNT_MODEL_RENDERERS[mountModelOverride];
+    const additive = ADDITIVE_INAPP_RENDERERS[presentation.archetype];
+    if (additive) return additive;
+    if (presentation.variantKey === 'mini_popover') return MiniPopoverInApp;
+    if (presentation.variantKey === 'peek_card') return PeekCardInApp;
+    if (presentation.mountModel === 'banner' && presentation.legacyLayout === 'bottom_banner') {
+        return BottomBannerInApp;
+    }
+    return MOUNT_MODEL_RENDERERS[presentation.mountModel];
+}
+
+// ─── Render-failure boundary (T1 G/render honesty) ────────────────────────────
+// A malformed render spec (or a downstream render throw) must NEVER crash the host
+// app and must NEVER silently vanish. This boundary catches the render error, reports
+// it via `onError(reason)` (provider → `render_failed` diagnostic, which also marks a
+// test preview failed server-side), and renders nothing in its place. Reset keys on
+// the message id so a new message after a failure gets a fresh attempt.
+interface InAppErrorBoundaryProps {
+    resetKey: string;
+    onError: (reason: string) => void;
+    children: ReactNode;
+}
+
+class InAppErrorBoundary extends Component<InAppErrorBoundaryProps, { failed: boolean }> {
+    constructor(props: InAppErrorBoundaryProps) {
+        super(props);
+        this.state = { failed: false };
+    }
+
+    static getDerivedStateFromError(): { failed: boolean } {
+        return { failed: true };
+    }
+
+    componentDidUpdate(prev: InAppErrorBoundaryProps): void {
+        // New message after a prior failure → clear the failed state and retry render.
+        if (prev.resetKey !== this.props.resetKey && this.state.failed) {
+            this.setState({ failed: false });
+        }
+    }
+
+    componentDidCatch(error: Error): void {
+        this.props.onError(error?.message || 'render_error');
+    }
+
+    render(): ReactNode {
+        return this.state.failed ? null : this.props.children;
+    }
+}
+
+// ─── Public mount point ───────────────────────────────────────────────────────
+
+export interface EngageInAppViewProps {
+    message: InAppMessageConfig | null;
+    visible: boolean;
+    /**
+     * Optional render spec override (A/B experiment, D8/J6). When supplied, this
+     * spec is rendered instead of `message.spec` — the provider resolves the chosen
+     * variant's content and passes it here. Omitted ⇒ render `message.spec`.
+     */
+    spec?: InAppRenderSpec;
+    /**
+     * Provider-only graceful degradation for an unavailable host placement.
+     * Content still resolves from the canonical variant; only its physical mount changes.
+     */
+    mountModelOverride?: InAppMountModel;
+    /** Fired once when the message first becomes visible (provider → impression). */
+    onShow: () => void;
+    /** Primary CTA tapped — provider emits `click` + surfaces the deep link. */
+    onCta: (cta: NonNullable<InAppRenderSpec['cta']>) => void;
+    /** Dismissed — provider emits `dismiss`. */
+    onDismiss: () => void;
+    /** Guided flow finished — provider emits `completion`. */
+    onComplete?: () => void;
+    /** Optional host-visible mechanic lifecycle callback. */
+    onInteraction?: (interaction: InAppMechanicInteraction) => void;
+    /** Customer-owned backend resolver for the eight gamified variants. */
+    onInAppGameRequest?: InAppGameRequestHandler;
+    /** Render failed (malformed spec / render throw) — provider emits `render_failed`. */
+    onRenderError?: (reason: string) => void;
+}
+
+/**
+ * Single mount point for in-app messages. Reads `message.layout`, auto-selects
+ * the correct renderer from the registry, fires `onShow()` exactly once per
+ * message. App developers write zero layout code.
+ */
+export function EngageInAppView({
+    message,
+    visible,
+    spec,
+    mountModelOverride,
+    onShow,
+    onCta,
+    onDismiss,
+    onComplete,
+    onInteraction,
+    onInAppGameRequest,
+    onRenderError,
+}: EngageInAppViewProps): ReactElement | null {
+    const effectiveSpec = spec ?? message?.spec;
+    const presentation = message && effectiveSpec
+        ? resolveInAppPresentation({
+            layout: message.layout,
+            variantKey: message.variantKey,
+            spec: effectiveSpec,
+        })
+        : null;
+    const effectiveMountModel = mountModelOverride ?? presentation?.mountModel;
+    const gameAttemptsRef = useRef<{
+        messageId: string | null;
+        ids: Map<string, string>;
+    }>({ messageId: null, ids: new Map() });
+    if (gameAttemptsRef.current.messageId !== (message?.id ?? null)) {
+        gameAttemptsRef.current = { messageId: message?.id ?? null, ids: new Map() };
+    }
+    const requestGameResult = useCallback(async (
+        rawAttempt = 1,
+        input?: Record<string, unknown>,
+    ): Promise<InAppGameResult> => {
+        if (!message || !effectiveSpec || !isInAppGameVariant(presentation?.variantKey)) {
+            throw new Error('Game result requested by a non-gamified message');
+        }
+        const variantKey = presentation.variantKey;
+        const attempt = Number.isFinite(rawAttempt)
+            ? Math.max(1, Math.floor(rawAttempt))
+            : 1;
+        const idKey = `${variantKey}:${attempt}`;
+        let attemptId = gameAttemptsRef.current.ids.get(idKey);
+        if (!attemptId) {
+            gameAttemptSequence += 1;
+            attemptId = `scalebun_game_${Date.now().toString(36)}_${gameAttemptSequence.toString(36)}`;
+            gameAttemptsRef.current.ids.set(idKey, attemptId);
+        }
+        const rawExt = effectiveSpec.ext as Record<string, unknown> | undefined;
+        const gameKey = typeof rawExt?.gameKey === 'string' ? rawExt.gameKey.trim() : '';
+        const isPreview = message.preview === true || message.isTest === true;
+        if (!isPreview && !gameKey) throw new Error('Game key is missing');
+        const request = buildInAppGameRequest({
+            campaignId: message.id,
+            gameKey: gameKey || `preview:${variantKey}`,
+            variantKey,
+            attemptId,
+            attempt,
+            payload: input,
+            allowedOutcomeIds: inAppGameAllowedOutcomeIds(effectiveSpec),
+        });
+        if (isPreview) {
+            const previewResult = authoredPreviewGameResult(request, effectiveSpec);
+            if (!previewResult) throw new Error('Preview outcome is not configured');
+            return previewResult;
+        }
+        if (!onInAppGameRequest) throw new Error('Game result handler is not configured');
+        return validateInAppGameResult(request, await onInAppGameRequest(request));
+    }, [message, effectiveSpec, presentation?.variantKey, onInAppGameRequest]);
+    const outcomeConfig = useMemo(
+        () => resolveInAppOutcomeConfig(effectiveSpec),
+        [effectiveSpec],
+    );
+    const [pendingOutcome, setPendingOutcome] = useState<InAppOutcomeRequest | null>(null);
+    useEffect(() => {
+        setPendingOutcome(null);
+    }, [message?.id, visible]);
+    const presentOutcome = useCallback((request: InAppOutcomeRequest): void => {
+        setPendingOutcome((current) => current ?? request);
+    }, []);
+    const outcomeAwareCta = useCallback((cta: NonNullable<InAppRenderSpec['cta']>): void => {
+        if (outcomeConfig) {
+            presentOutcome({ fallback: inAppOutcomeTerminalForCta(cta) });
+            return;
+        }
+        onCta(cta);
+    }, [onCta, outcomeConfig, presentOutcome]);
+    const outcomeAwareComplete = useCallback((): void => {
+        if (outcomeConfig) {
+            presentOutcome({ fallback: { kind: 'complete' } });
+            return;
+        }
+        if (onComplete) onComplete();
+        else onDismiss();
+    }, [onComplete, onDismiss, outcomeConfig, presentOutcome]);
+    const runOutcomeAction = useCallback((): void => {
+        if (!outcomeConfig || !pendingOutcome) return;
+        const terminal: InAppOutcomeTerminal = resolveInAppOutcomeTerminal(
+            outcomeConfig,
+            pendingOutcome.fallback,
+        );
+        setPendingOutcome(null);
+        if (terminal.kind === 'cta') {
+            onCta(terminal.cta);
+        } else if (terminal.kind === 'complete') {
+            if (onComplete) onComplete();
+            else onDismiss();
+        } else {
+            onDismiss();
+        }
+    }, [onComplete, onCta, onDismiss, outcomeConfig, pendingOutcome]);
+    const waitsForAnchor = presentation !== null &&
+        effectiveMountModel === 'anchored';
+    const [readyMessageId, setReadyMessageId] = useState<string | null>(null);
+    // Mechanics such as wheel, quiz, and checklist can be fully authored in `ext`
+    // without generic body copy. Reject only a truly empty render model.
+    const contentMissing = !effectiveSpec || !(
+        effectiveSpec.title ||
+        effectiveSpec.body ||
+        effectiveSpec.imageUrl ||
+        effectiveSpec.coupon ||
+        effectiveSpec.cta ||
+        (effectiveSpec.assets && Object.keys(effectiveSpec.assets).length > 0) ||
+        (effectiveSpec.ext && Object.keys(effectiveSpec.ext).length > 0)
+    );
+
+    const shownIdRef = useRef<string | null>(null);
+    useEffect(() => {
+        if (visible && message && shownIdRef.current !== message.id) {
+            if (contentMissing) {
+                shownIdRef.current = message.id;
+                onRenderError?.('missing_content');
+            } else if (!waitsForAnchor || readyMessageId === message.id) {
+                shownIdRef.current = message.id;
+                onShow();
+            }
+        }
+        if (!visible) shownIdRef.current = null;
+    }, [visible, message, onShow, onRenderError, contentMissing, waitsForAnchor, readyMessageId]);
+
+    if (!message || !visible || contentMissing || !effectiveSpec || !presentation) return null;
+
+    const mechanic = resolveInAppMechanic({
+        variantKey: message.variantKey,
+        spec: effectiveSpec,
+    });
+    const MechanicContent = resolveArchetypeContent(mechanic ?? presentation.archetype);
+    const Content = MechanicContent ?? resolveVariantContent(presentation.variantKey ?? undefined);
+    const Branch = resolveInAppPresentationRenderer(presentation, mountModelOverride);
+    const theme = resolveTheme(effectiveSpec);
+    if (__DEV__) {
+        __DEV__ && logger.debug(
+            `[Engage] in-app ${message.id} rendering variant="${presentation.variantKey ?? 'legacy'}" archetype="${presentation.archetype}" mount="${effectiveMountModel}" layout="${presentation.legacyLayout}" fallback="${presentation.fallback?.reason ?? 'none'}"${message.isTest ? ` (test ${message.testRunId ?? message.previewId ?? message.id})` : ''}`,
+        );
+    }
+    return (
+        <InAppErrorBoundary resetKey={message.id} onError={(reason) => onRenderError?.(reason)}>
+            <Branch
+                key={`${message.id}:${presentation.variantKey ?? presentation.archetype}`}
+                spec={effectiveSpec}
+                variantKey={presentation.variantKey ?? undefined}
+                theme={theme}
+                onCta={outcomeAwareCta}
+                onDismiss={onDismiss}
+                onComplete={outcomeAwareComplete}
+                onOutcome={outcomeConfig ? presentOutcome : undefined}
+                onInteraction={onInteraction}
+                requestGameResult={requestGameResult}
+                onReady={() => setReadyMessageId(message.id)}
+                onRenderError={onRenderError}
+            >
+                {Content ? (
+                    <Content
+                        spec={effectiveSpec}
+                        variantKey={presentation.variantKey ?? undefined}
+                        theme={theme}
+                        onCta={outcomeAwareCta}
+                        onDismiss={onDismiss}
+                        onComplete={outcomeAwareComplete}
+                        onOutcome={outcomeConfig ? presentOutcome : undefined}
+                        onInteraction={onInteraction}
+                        requestGameResult={requestGameResult}
+                    />
+                ) : undefined}
+            </Branch>
+            {pendingOutcome && outcomeConfig ? (
+                <InAppOutcomeModal
+                    outcome={outcomeConfig}
+                    resultLabel={pendingOutcome.resultLabel}
+                    theme={theme}
+                    onAction={runOutcomeAction}
+                    onRequestClose={() => {
+                        setPendingOutcome(null);
+                        onDismiss();
+                    }}
+                />
+            ) : null}
+        </InAppErrorBoundary>
+    );
+}
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const CARD_BG = '#FFFFFF';
+const SHADOW: ViewStyle = {
+    shadowColor: '#000000',
+    shadowOpacity: 0.15,
+    shadowRadius: 12,
+    shadowOffset: { width: 0, height: 4 },
+    elevation: 6,
+};
+
+const outcomeStyles: Record<string, ViewStyle & TextStyle> = {
+    backdrop: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 24,
+    },
+    card: {
+        width: '100%',
+        maxWidth: 340,
+        borderWidth: 1,
+        borderRadius: 24,
+        padding: 24,
+        alignItems: 'center',
+        ...SHADOW,
+    },
+    copy: { alignSelf: 'stretch', alignItems: 'center' },
+    icon: {
+        width: 64,
+        height: 64,
+        borderRadius: 20,
+        alignItems: 'center',
+        justifyContent: 'center',
+        marginBottom: 14,
+    },
+    iconText: { fontSize: 30, fontWeight: '800' },
+    title: { fontSize: 21, fontWeight: '800', textAlign: 'center' },
+    body: { fontSize: 14, lineHeight: 20, textAlign: 'center', marginTop: 7 },
+    result: {
+        alignSelf: 'stretch',
+        borderRadius: 12,
+        padding: 10,
+        marginTop: 12,
+    },
+    resultText: { fontSize: 17, fontWeight: '800', textAlign: 'center' },
+    button: {
+        alignSelf: 'stretch',
+        minHeight: 44,
+        borderRadius: 12,
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 16,
+        marginTop: 18,
+    },
+    buttonText: { fontSize: 15, fontWeight: '800', textAlign: 'center' },
+};
+
+const styles: {
+    // shared content
+    contentBlock: ViewStyle;
+    image: ImageStyle;
+    title: TextStyle;
+    body: TextStyle;
+    actions: ViewStyle;
+    primaryBtn: ViewStyle;
+    primaryText: TextStyle;
+    secondaryBtn: ViewStyle;
+    secondaryText: TextStyle;
+    coupon: ViewStyle;
+    couponText: TextStyle;
+    closeBtn: ViewStyle;
+    closeBtnText: TextStyle;
+    keyboardAvoider: ViewStyle;
+    screenEdgeKeyboard: ViewStyle;
+    screenEdge: ViewStyle;
+    screenEdgeTop: ViewStyle;
+    screenEdgeBottom: ViewStyle;
+    // modal
+    modalSafeArea: ViewStyle;
+    modalBackdrop: ViewStyle;
+    modalBackdropTop: ViewStyle;
+    modalBackdropBottom: ViewStyle;
+    modalCard: ViewStyle;
+    modalScroll: ViewStyle;
+    modalScrollContent: ViewStyle;
+    centerDrawerCard: ViewStyle;
+    modalClosePos: ViewStyle;
+    // fullscreen
+    fullscreenCard: ViewStyle;
+    fullscreenHeader: ViewStyle;
+    fullscreenScroll: ViewStyle;
+    fullscreenScrollContent: ViewStyle;
+    fullscreenImage: ImageStyle;
+    fullscreenContent: ViewStyle;
+    fullscreenTitle: TextStyle;
+    fullscreenBody: TextStyle;
+    // bottom_sheet
+    sheetBackdrop: ViewStyle;
+    sheetCard: ViewStyle;
+    sheetSafeArea: ViewStyle;
+    sheetScroll: ViewStyle;
+    sheetContent: ViewStyle;
+    sheetHandle: ViewStyle;
+    stepProgress: ViewStyle;
+    stepLabel: TextStyle;
+    stepTrack: ViewStyle;
+    stepFill: ViewStyle;
+    // additive side_sheet
+    sideSheetBackdrop: ViewStyle;
+    sideSheetLeft: ViewStyle;
+    sideSheetRight: ViewStyle;
+    sideSheetPanel: ViewStyle;
+    sideSheetPanelLeft: ViewStyle;
+    sideSheetPanelRight: ViewStyle;
+    sideSheetSafeArea: ViewStyle;
+    sideSheetHeader: ViewStyle;
+    sideSheetScroll: ViewStyle;
+    sideSheetContent: ViewStyle;
+    peekRoot: ViewStyle;
+    peekExpanded: ViewStyle;
+    peekCollapsed: ViewStyle;
+    peekSafeArea: ViewStyle;
+    peekScroll: ViewStyle;
+    peekExpandedContent: ViewStyle;
+    peekCollapsedContent: ViewStyle;
+    peekClose: ViewStyle;
+    peekLabel: TextStyle;
+    // banners
+    bannerWrap: ViewStyle;
+    bannerCard: ViewStyle;
+    bannerContent: ViewStyle;
+    bannerClosePos: ViewStyle;
+    stickyLabel: TextStyle;
+    stickyTrack: ViewStyle;
+    stickyFill: ViewStyle;
+    // tooltip
+    floatingEdge: ViewStyle;
+    edgeAlignLeft: ViewStyle;
+    edgeAlignRight: ViewStyle;
+    floatingBubble: ViewStyle;
+    floatingBubbleText: TextStyle;
+    floatingPanel: ViewStyle;
+    floatingScroll: ViewStyle;
+    miniPopoverPanel: ViewStyle;
+    tooltipCard: ViewStyle;
+    tooltipClosePos: ViewStyle;
+    tooltipTitle: TextStyle;
+    tooltipBody: TextStyle;
+    tooltipCta: ViewStyle;
+    tooltipCtaText: TextStyle;
+    anchoredTooltipRoot: ViewStyle;
+    coachmarkRoot: ViewStyle;
+    coachmarkSpotlight: ViewStyle;
+    coachmarkTooltipWrap: ViewStyle;
+    coachmarkArrow: ViewStyle;
+    coachmarkArrowTop: ViewStyle;
+    coachmarkArrowBottom: ViewStyle;
+    coachmarkArrowLeft: ViewStyle;
+    coachmarkArrowRight: ViewStyle;
+    coachmarkCard: ViewStyle;
+    coachmarkScroll: ViewStyle;
+    coachmarkEyebrow: TextStyle;
+    coachmarkActions: ViewStyle;
+    coachmarkNavActions: ViewStyle;
+    coachmarkTextButton: ViewStyle;
+    coachmarkSecondaryText: TextStyle;
+    coachmarkPrimaryButton: ViewStyle;
+    coachmarkPrimaryText: TextStyle;
+    // inline
+    inlineCard: ViewStyle;
+    inlineClosePos: ViewStyle;
+    // toast
+    toastWrap: ViewStyle;
+    toastCard: ViewStyle;
+    toastScroll: ViewStyle;
+    toastTitle: TextStyle;
+    toastBody: TextStyle;
+    toastCtaText: TextStyle;
+} = {
+    // ── shared content ──
+    contentBlock: { marginBottom: 12 },
+    image: { width: '100%', height: 140, borderRadius: 12, marginBottom: 12 },
+    title: { fontSize: 17, fontWeight: '700', color: '#11151C', marginBottom: 6 },
+    body: { fontSize: 14, color: '#3A4250', lineHeight: 20 },
+    actions: {
+        flexDirection: 'row',
+        flexWrap: 'wrap',
+        justifyContent: 'flex-end',
+        alignItems: 'center',
+        gap: 8,
+    },
+    primaryBtn: {
+        flexGrow: 1,
+        flexShrink: 1,
+        minWidth: 120,
+        maxWidth: '100%',
+        paddingVertical: 10,
+        paddingHorizontal: 20,
+        borderRadius: 10,
+        backgroundColor: '#2F6BFF',
+    },
+    primaryText: { fontSize: 15, color: '#FFFFFF', fontWeight: '600', textAlign: 'center', flexShrink: 1 },
+    secondaryBtn: { maxWidth: '100%', flexShrink: 1, paddingVertical: 10, paddingHorizontal: 16 },
+    secondaryText: { fontSize: 15, color: '#6B7280', fontWeight: '500', textAlign: 'center', flexShrink: 1 },
+    coupon: {
+        marginTop: 10,
+        borderWidth: 1.5,
+        borderStyle: 'dashed',
+        borderRadius: 8,
+        paddingVertical: 8,
+        paddingHorizontal: 10,
+        alignItems: 'center',
+    },
+    couponText: { fontSize: 14, fontWeight: '700', letterSpacing: 1.2 },
+    closeBtn: {
+        width: 32,
+        height: 32,
+        padding: 0,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    closeBtnText: {
+        fontSize: 18,
+        color: '#9097A3',
+        fontWeight: '600',
+        lineHeight: 20,
+        textAlign: 'center',
+        includeFontPadding: false,
+        transform: [{ translateY: -1 }],
+    },
+    keyboardAvoider: { flex: 1 },
+    screenEdgeKeyboard: { width: '100%' },
+    screenEdge: {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        left: 0,
+        right: 0,
+        zIndex: 1000,
+    },
+    screenEdgeTop: { justifyContent: 'flex-start' },
+    screenEdgeBottom: { justifyContent: 'flex-end' },
+
+    // ── modal ──
+    modalSafeArea: { flex: 1 },
+    modalBackdrop: {
+        flex: 1,
+        backgroundColor: 'rgba(0,0,0,0.52)',
+        justifyContent: 'center',
+        alignItems: 'center',
+        padding: 20,
+    },
+    modalBackdropTop: { justifyContent: 'flex-start' },
+    modalBackdropBottom: { justifyContent: 'flex-end' },
+    modalCard: {
+        width: '100%',
+        maxWidth: 420,
+        maxHeight: '100%',
+        backgroundColor: CARD_BG,
+        borderRadius: 18,
+        padding: 22,
+        ...SHADOW,
+    },
+    modalScroll: { flexShrink: 1 },
+    modalScrollContent: {},
+    centerDrawerCard: { maxHeight: '78%' },
+    modalClosePos: { position: 'absolute', top: 12, right: 12, zIndex: 1 },
+
+    // ── fullscreen ──
+    fullscreenCard: {
+        flex: 1,
+        backgroundColor: CARD_BG,
+    },
+    fullscreenHeader: {
+        minHeight: 44,
+        paddingHorizontal: 16,
+        alignItems: 'flex-end',
+        justifyContent: 'center',
+    },
+    fullscreenScroll: { flex: 1 },
+    fullscreenScrollContent: { flexGrow: 1 },
+    fullscreenImage: { width: '100%', maxWidth: 600, alignSelf: 'center', aspectRatio: 16 / 9, maxHeight: 320 },
+    fullscreenContent: {
+        flexGrow: 1,
+        width: '100%',
+        maxWidth: 600,
+        alignSelf: 'center',
+        paddingHorizontal: 24,
+        paddingTop: 8,
+        paddingBottom: 24,
+    },
+    fullscreenTitle: {
+        fontSize: 22,
+        fontWeight: '800',
+        color: '#11151C',
+        marginBottom: 10,
+    },
+    fullscreenBody: {
+        fontSize: 15,
+        color: '#3A4250',
+        lineHeight: 22,
+        marginBottom: 24,
+    },
+
+    // ── bottom_sheet ──
+    sheetBackdrop: {
+        flex: 1,
+        backgroundColor: 'rgba(0,0,0,0.48)',
+        justifyContent: 'flex-end',
+        alignItems: 'center',
+    },
+    sheetCard: {
+        width: '100%',
+        maxWidth: 600,
+        maxHeight: '92%',
+        backgroundColor: CARD_BG,
+        borderTopLeftRadius: 22,
+        borderTopRightRadius: 22,
+        overflow: 'hidden',
+        ...SHADOW,
+    },
+    sheetSafeArea: { width: '100%' },
+    sheetScroll: { flexShrink: 1 },
+    sheetContent: { padding: 22, paddingBottom: 20 },
+    sheetHandle: {
+        width: 38,
+        height: 4,
+        borderRadius: 2,
+        backgroundColor: '#D1D5DB',
+        alignSelf: 'center',
+        marginBottom: 16,
+    },
+    stepProgress: { marginBottom: 16 },
+    stepLabel: { fontSize: 12, fontWeight: '600', marginBottom: 7 },
+    stepTrack: {
+        height: 4,
+        borderRadius: 2,
+        backgroundColor: '#E5E7EB',
+        overflow: 'hidden',
+    },
+    stepFill: { height: '100%', borderRadius: 2 },
+
+    // ── additive side_sheet ──
+    sideSheetBackdrop: { flex: 1, flexDirection: 'row' },
+    sideSheetLeft: { justifyContent: 'flex-start' },
+    sideSheetRight: { justifyContent: 'flex-end' },
+    sideSheetPanel: {
+        width: '82%',
+        maxWidth: 420,
+        height: '100%',
+        ...SHADOW,
+    },
+    sideSheetPanelLeft: { borderTopRightRadius: 22, borderBottomRightRadius: 22 },
+    sideSheetPanelRight: { borderTopLeftRadius: 22, borderBottomLeftRadius: 22 },
+    sideSheetSafeArea: { flex: 1 },
+    sideSheetHeader: {
+        minHeight: 44,
+        paddingHorizontal: 14,
+        alignItems: 'flex-end',
+        justifyContent: 'center',
+    },
+    sideSheetScroll: { flex: 1 },
+    sideSheetContent: { flexGrow: 1, paddingHorizontal: 22, paddingTop: 8, paddingBottom: 24 },
+    peekRoot: { flex: 1, justifyContent: 'flex-end', alignItems: 'center', paddingHorizontal: 14 },
+    peekExpanded: {
+        width: '100%',
+        maxWidth: 600,
+        maxHeight: '92%',
+        borderTopLeftRadius: 22,
+        borderTopRightRadius: 22,
+        overflow: 'hidden',
+        ...SHADOW,
+    },
+    peekCollapsed: {
+        width: '100%',
+        maxWidth: 600,
+        minHeight: 72,
+        borderTopLeftRadius: 18,
+        borderTopRightRadius: 18,
+        borderWidth: 1,
+        borderBottomWidth: 0,
+        overflow: 'hidden',
+        ...SHADOW,
+    },
+    peekSafeArea: { width: '100%' },
+    peekScroll: { flexShrink: 1 },
+    peekExpandedContent: { padding: 22, paddingBottom: 20 },
+    peekCollapsedContent: { padding: 14 },
+    peekClose: { position: 'absolute', top: 10, right: 12 },
+    peekLabel: { fontSize: 15, fontWeight: '800', textAlign: 'center' },
+
+    // ── banners (shared card shape) ──
+    bannerWrap: {
+        padding: 12,
+        alignItems: 'center',
+    },
+    bannerCard: {
+        width: '100%',
+        maxWidth: 420,
+        backgroundColor: CARD_BG,
+        borderRadius: 14,
+        padding: 14,
+        flexDirection: 'row',
+        alignItems: 'flex-start',
+        ...SHADOW,
+    },
+    bannerContent: { flex: 1, paddingRight: 8 },
+    bannerClosePos: { alignSelf: 'flex-start', marginTop: -2 },
+    stickyLabel: { fontSize: 9, fontWeight: '900', letterSpacing: 1, marginBottom: 3 },
+    stickyTrack: { height: 4, borderRadius: 2, backgroundColor: '#E5E7EB', overflow: 'hidden', marginTop: 7 },
+    stickyFill: { height: '100%', borderRadius: 2 },
+
+    // ── tooltip ──
+    floatingEdge: { padding: 16 },
+    edgeAlignLeft: { alignItems: 'flex-start' },
+    edgeAlignRight: { alignItems: 'flex-end' },
+    floatingBubble: {
+        minWidth: 62,
+        minHeight: 62,
+        borderRadius: 31,
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 14,
+        ...SHADOW,
+    },
+    floatingBubbleText: { fontSize: 12, fontWeight: '800', textAlign: 'center' },
+    floatingPanel: { width: '100%', maxWidth: 260, overflow: 'hidden', borderRadius: 12 },
+    floatingScroll: { flexShrink: 1 },
+    miniPopoverPanel: { width: '100%', maxWidth: 240, overflow: 'hidden', borderRadius: 12 },
+    tooltipCard: {
+        width: '100%',
+        maxHeight: '100%',
+        backgroundColor: CARD_BG,
+        borderRadius: 12,
+        padding: 14,
+        ...SHADOW,
+    },
+    tooltipClosePos: { position: 'absolute', top: 4, right: 4 },
+    tooltipTitle: {
+        fontSize: 13,
+        fontWeight: '700',
+        color: '#11151C',
+        marginBottom: 4,
+        paddingRight: 20,
+    },
+    tooltipBody: { fontSize: 12, color: '#3A4250', lineHeight: 17 },
+    tooltipCta: { marginTop: 8 },
+    tooltipCtaText: { fontSize: 12, color: '#2F6BFF', fontWeight: '600' },
+    anchoredTooltipRoot: {
+        position: 'absolute',
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+        zIndex: 9999,
+        elevation: 9999,
+    },
+    coachmarkRoot: { flex: 1 },
+    coachmarkSpotlight: {
+        borderWidth: 2,
+        shadowColor: '#FFFFFF',
+        shadowOpacity: 0.45,
+        shadowRadius: 8,
+        elevation: 2,
+    },
+    coachmarkTooltipWrap: { position: 'absolute', zIndex: 2 },
+    coachmarkArrow: {
+        position: 'absolute',
+        width: 14,
+        height: 14,
+        transform: [{ rotate: '45deg' }],
+        zIndex: 0,
+    },
+    coachmarkArrowTop: { top: -6 },
+    coachmarkArrowBottom: { bottom: -6 },
+    coachmarkArrowLeft: { left: -6 },
+    coachmarkArrowRight: { right: -6 },
+    coachmarkCard: {
+        borderRadius: 14,
+        padding: 16,
+        overflow: 'hidden',
+        zIndex: 1,
+        ...SHADOW,
+    },
+    coachmarkScroll: { flexShrink: 1 },
+    coachmarkEyebrow: {
+        fontSize: 10,
+        fontWeight: '800',
+        letterSpacing: 0.8,
+        marginBottom: 5,
+    },
+    coachmarkActions: {
+        alignItems: 'center',
+        flexDirection: 'row',
+        flexWrap: 'wrap',
+        justifyContent: 'space-between',
+        gap: 8,
+        marginTop: 14,
+    },
+    coachmarkNavActions: {
+        alignItems: 'center',
+        flexDirection: 'row',
+        flexWrap: 'wrap',
+        justifyContent: 'flex-end',
+        gap: 6,
+    },
+    coachmarkTextButton: {
+        minHeight: 44,
+        minWidth: 44,
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 8,
+    },
+    coachmarkSecondaryText: { fontSize: 13, fontWeight: '700' },
+    coachmarkPrimaryButton: {
+        minHeight: 44,
+        minWidth: 72,
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: 10,
+        paddingHorizontal: 14,
+    },
+    coachmarkPrimaryText: { fontSize: 13, fontWeight: '800' },
+
+    // ── inline ──
+    inlineCard: {
+        width: '100%',
+        borderRadius: 14,
+        padding: 16,
+        ...SHADOW,
+    },
+    inlineClosePos: { position: 'absolute', top: 6, right: 6, zIndex: 1 },
+
+    // ── toast ──
+    toastWrap: {
+        paddingHorizontal: 16,
+        paddingVertical: 12,
+        alignItems: 'center',
+    },
+    toastCard: {
+        width: '100%',
+        maxWidth: 420,
+        backgroundColor: '#1C1C1E',
+        borderRadius: 12,
+        paddingVertical: 12,
+        paddingHorizontal: 16,
+        ...SHADOW,
+    },
+    toastScroll: { flexShrink: 1 },
+    toastTitle: {
+        fontSize: 13,
+        fontWeight: '700',
+        color: '#FFFFFF',
+        marginBottom: 2,
+    },
+    toastBody: { fontSize: 13, color: 'rgba(255,255,255,0.8)' },
+    toastCtaText: {
+        fontSize: 13,
+        color: '#60A5FA',
+        fontWeight: '600',
+        marginTop: 6,
+    },
+};