@scalebun/react-native 1.0.0 → 1.0.2

package/src/features/engage/EngagePromptProvider.tsx

@@ -1,1270 +1,1270 @@
-/**
- * ScaleBun SDK — Engage Prompt Provider (campaign renderer core, D4)
- *
- * Wraps the host app and owns the campaign-render lifecycle for the shared
- * cross-platform JS overlay:
- *   1. on a trigger (app-controlled via `showEngagePrompt()` and/or the campaign's
- *      own `trigger` from config), calls `facade.engage.fetchConfig()`,
- *   2. runs the throttle/decision core (`selectCampaignToRender`) to pick which
- *      campaign — if any — is eligible, honoring frequency caps,
- *   3. mounts the parameterized `EngagePromptView` (Open/Closed: NPS now,
- *      ratings/feedback/survey later via the renderer registry),
- *   4. on submit → `facade.engage.submitResponse({ surveyId, score, text })`
- *      (transport stamps `responseId` UUID + `schemaVersion` per contract),
- *      records the impression as completed, and emits an in-app dismiss/submit
- *      tracking event,
- *   5. on dismiss → `facade.engage.trackEvent` with a `dismiss` event.
- *
- * The provider depends only on the `engage` namespace shape — NOT the whole
- * facade — so it stays decoupled and testable, and reuses the existing transport
- * (no second HTTP path).
- *
- * IN-APP MESSAGES (the second Engage family, §2.4/§2.5) are surfaced by this SAME
- * provider — NOT a parallel one. `showInAppMessage()` fetches the config, picks an
- * eligible message from `inAppMessages[]` (shared throttle store), and mounts the
- * config-driven `EngageInAppView` (banner/modal/overlay). Events: `impression` on
- * show, `click` on CTA tap (the resolved deep link is surfaced to the host via
- * `onInAppDeepLink` — the SDK never opens URLs), `dismiss` on close.
- *
- * PRECEDENCE (campaign vs in-app): a campaign prompt wins the screen. If a
- * campaign prompt is already visible, `showInAppMessage()` is a no-op (returns
- * false) and the mounted in-app view is hidden while a campaign is up, so the two
- * families never fight for the screen.
- */
-
-import React, {
-    createContext,
-    useContext,
-    useCallback,
-    useEffect,
-    useMemo,
-    useRef,
-    useState,
-    type ReactNode,
-    type ReactElement,
-} from 'react';
-import { Linking, Platform } from 'react-native';
-import { logger } from '../../core/logger/internalLogger';
-import { installEngageTriggerEngine } from './engageTriggerEngine';
-import { appLifecycle } from '../../core/lifecycle/appLifecycle';
-import { getDeviceId } from '../../core/id/deviceId';
-import { ReplaySdk } from '../replay/public/api';
-import { SessionManager } from '../session/SessionManager';
-import {
-    EngagePromptView,
-    type EngagePromptResult,
-    type EngageSubmitStatus,
-    type RatingPromptConfig,
-} from './EngagePromptView';
-import { EngageInAppView, type InAppMechanicInteraction } from './EngageInAppView';
-import { EngageAnchorProvider } from './EngageAnchor';
-import {
-    EngageInlinePlacementProvider,
-    createEngageInlinePlacementRegistry,
-    resolveEngageInlinePlacement,
-    type EngageInlineDelivery,
-} from './EngageInlinePlacement';
-import { resolveInAppPresentation } from './engageVariantResolver';
-import { shouldTrackInAppCta } from './engageOutcome';
-import type { SubmitStage } from './EngageTransport';
-import {
-    EngageThrottleStore,
-    selectCampaignToRender,
-    selectInAppToRender,
-    selectInAppVariant,
-    selectLatestUnseenTest,
-    testRunIdOf,
-} from './engageThrottle';
-import { EngageTestSeenStore } from './engageTestSeenStore';
-import type {
-    EngageAttachmentDraft,
-    EngageCampaignConfig,
-    EngageCampaignType,
-    EngageConfigContext,
-    EngageConfigResponse,
-    EngageEventInput,
-    InAppGameRequestHandler,
-    EngageResponseInput,
-    InAppMessageConfig,
-    InAppRenderSpec,
-    InAppVariantId,
-    RatingFunnelEventDims,
-    RatingFunnelEventInput,
-    RatingFunnelEventType,
-    SurveyAnswer,
-    SurveyImpressionInput,
-} from './engageTypes';
-
-/** Client-generated UUID for app-rating idempotency (D8: `clientRatingId`). */
-function ratingUuid(): string {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
-
-/** Preserve a multi-question survey answer in the keyed wire shape (§1.4). */
-export function toWireAnswers(
-    answers: SurveyAnswer[],
-): { key: string; value: string | number | string[] }[] {
-    return answers.map((a) => ({
-        key: a.key,
-        value: a.value,
-    }));
-}
-
-/**
- * Resolve the canonical session id for response linkage (contract §1/§7).
- * Primary source is `SessionManager.currentSessionId` — the always-on analytics
- * session id (`rs-…`) that the replay recording attaches to (and that `/sessions/:id`
- * keys on). `ReplaySdk.sessionId` (the orchestrator's recording id) is only set
- * while a recording is mid-flight and reads `null` at submit time, so it is a
- * fallback, not the primary. Returns `undefined` (not `null`) so the optional wire
- * field is simply omitted when no session is active.
- */
-function currentSessionId(): string | undefined {
-    return (
-        SessionManager.getExistingInstance()?.currentSessionId ??
-        ReplaySdk.sessionId ??
-        undefined
-    );
-}
-
-/**
- * The host app version for by-version analytics (contract §1). Read from the
- * SAME synchronous source the SDK's rating lane already uses
- * (`SessionManager.currentSessionMetadata.appVersion`, populated from native
- * device info) — NOT hardcoded, and NOT the SDK build version. `undefined` when
- * no session metadata is available yet, so the optional field is omitted.
- */
-function currentAppVersion(): string | undefined {
-    return SessionManager.getExistingInstance()?.currentSessionMetadata?.appVersion ?? undefined;
-}
-
-/**
- * Device platform as the `'android' | 'ios'` wire union (contract §1). Shared JS
- * path — NOT platform-gated — so Android and iOS both stamp their own value.
- * `Platform.OS` also yields `'windows' | 'macos' | 'web'`; those are out of the
- * SDK's mobile scope and intentionally collapse to `undefined` (field omitted).
- */
-function currentPlatform(): 'android' | 'ios' | undefined {
-    return Platform.OS === 'android' || Platform.OS === 'ios' ? Platform.OS : undefined;
-}
-
-/**
- * Build the config-serve context (contract §1.3 query). ALWAYS carries `deviceId`
- * — the backend keys per-device test previews on it, so omitting it would hide a
- * "Send Test" preview from the very device it was queued for (T1). `platform`/
- * `appVersion` ride along for server-side targeting; both honest, both omitted when
- * unresolved. A caller-supplied `context` (manual show) overrides field-by-field.
- */
-function buildConfigContext(
-    engage: EngageRendererFacade,
-    override?: EngageConfigContext,
-): EngageConfigContext {
-    const identifiedUserId = engage.getIdentifiedUserId?.();
-    return {
-        deviceId: getDeviceId(),
-        ...(currentPlatform() ? { platform: currentPlatform() } : {}),
-        ...(currentAppVersion() ? { appVersion: currentAppVersion() } : {}),
-        ...(identifiedUserId ? { endUserId: identifiedUserId } : {}),
-        ...override,
-    };
-}
-
-/**
- * Build the rating-funnel breakdown dimensions (ratings-rebuild CONTRACT §1.2 `dims`)
- * from the SAME live session metadata the response builder reads — NOT hardcoded.
- * Only honest, present values are included; `country`/`locale`/`acquisitionSource`
- * are intentionally omitted here (no on-device source yet) so the backend reports
- * them as absent rather than fabricated.
- */
-function currentRatingDims(): RatingFunnelEventDims {
-    const meta = SessionManager.getExistingInstance()?.currentSessionMetadata;
-    const platform = currentPlatform();
-    return {
-        ...(platform ? { platform } : {}),
-        ...(meta?.appVersion ? { appVersion: meta.appVersion } : {}),
-        ...(meta?.osVersion ? { osVersion: meta.osVersion } : {}),
-        ...(meta?.deviceModel ? { deviceModel: meta.deviceModel } : {}),
-    };
-}
-
-/**
- * The slice of the SDK facade the renderer consumes (the `engage` namespace).
- * Matching this shape — rather than importing the facade — keeps the renderer a
- * pure consumer of the foundation transport and trivially testable.
- */
-export interface EngageRendererFacade {
-    /** External user id last supplied through ScaleBun.identify(). */
-    getIdentifiedUserId?: () => string | undefined;
-    fetchConfig: (context?: EngageConfigContext) => Promise<EngageConfigResponse | null>;
-    trackCoachmarkEvent?: (name: string, properties: Record<string, unknown>) => void;
-    submitResponse: (input: EngageResponseInput) => void;
-    /**
-     * [P3-e] Submit a response with native attachments (screenshot/voice). Optional
-     * so a host wired to an older facade still renders prompts (media silently
-     * degrades to a plain response).
-     */
-    submitResponseWithAttachments?: (
-        input: EngageResponseInput,
-        attachments: EngageAttachmentDraft[],
-    ) => void;
-    /**
-     * [Slice D5] CONFIRMED submit used by the reusable submitting→success→error state
-     * machine: resolves only on real server persistence, rejects on failure, idempotent
-     * on `responseId`. Optional so an older facade still renders prompts (falls back to
-     * the fire-and-forget lanes, which resolve immediately).
-     */
-    submitResponseConfirmed?: (
-        input: EngageResponseInput,
-        attachments: EngageAttachmentDraft[],
-        opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
-    ) => Promise<void>;
-    trackEvent: (input: EngageEventInput) => void;
-    trackSurveyImpression?: (input: SurveyImpressionInput) => void;
-    /**
-     * Force-flush queued in-app events immediately (bypassing the batch threshold/timer).
-     * Called right after a TEST preview's impression/dismiss ACK so the backend consumes
-     * the one-shot preview row before the app can be backgrounded/killed — otherwise a
-     * still-`delivered` row re-serves on the next reopen. Optional: an older facade simply
-     * relies on the periodic flush (eventual consistency).
-     */
-    flushEvents?: () => void;
-    /**
-     * Submit a 1–5 app-store rating via the EXISTING rating lane (NOT
-     * submitResponse — D1 keeps app-ratings a distinct funnel). The provider
-     * passes a client `clientRatingId` for idempotency (D8). Optional so a host
-     * that never shows RATING_PROMPT need not supply it.
-     */
-    submitRating?: (input: {
-        rating: number;
-        comment?: string;
-        source?: 'in_app' | 'prompt' | 'manual';
-        clientRatingId?: string;
-    }) => unknown;
-    /**
-     * Emit a rating-funnel tracking fact (ratings-rebuild CONTRACT §1.2) — eligible/
-     * shown/dismissed/selected/redirect. NOT a campaign response (D1). Optional so an
-     * older facade still renders rating prompts (the funnel just goes uninstrumented).
-     */
-    emitRatingEvent?: (input: RatingFunnelEventInput) => void;
-    /**
-     * Trigger the native in-app review sheet (D5). Resolves `true` only when the OS
-     * flow ran/resolved after a positive route, so the provider emits
-     * `store_redirect_clicked` solely on a `true` result. Optional/fail-soft.
-     */
-    requestStoreReview?: () => Promise<boolean>;
-}
-
-/**
- * Host-app RATING_PROMPT routing config. The store deeplink is NEVER hardcoded —
- * the host supplies either a static `storeUrl` or an `onHighRating` callback (e.g.
- * `Linking.openURL(...)` / native `requestReview()`), and an `onLowRating` for the
- * feedback hand-off. The provider only decides WHICH callback to invoke.
- */
-export interface EngageRatingRouting extends RatingPromptConfig {
-    /** App-store deeplink opened on a high rating (host owns the navigation). */
-    storeUrl?: string;
-    /** Called on a high rating (>= threshold). Receives the resolved store URL if set. */
-    onHighRating?: (info: { rating: number; campaign: EngageCampaignConfig; storeUrl?: string }) => void;
-    /** Called on a low rating when routing to feedback (host opens its form). */
-    onLowRating?: (info: { rating: number; campaign: EngageCampaignConfig }) => void;
-}
-
-export interface ShowEngagePromptOptions {
-    /** Restrict to specific campaign types. Defaults to `['NPS']` (NPS-first slice). */
-    types?: EngageCampaignType[];
-    /** Match a campaign's `targetScreen` to the current screen. */
-    screen?: string;
-    /**
-     * Restrict to campaigns whose `trigger` equals this value (behavioral-trigger
-     * path, e.g. `'screen_exit'`). Omitted ⇒ trigger-agnostic (manual fire).
-     */
-    trigger?: string;
-    /** Event name for `custom_event` / `after_purchase` (matches `triggerConfig.event`). */
-    event?: string;
-    /** Action label for `failed_action` (matches `triggerConfig.action`). */
-    action?: string;
-    /** Fired `time_in_app` threshold, used to select only that configured timer. */
-    seconds?: number;
-    /** App/user context forwarded to the config fetch for server-side targeting. */
-    context?: EngageConfigContext;
-}
-
-export interface ShowInAppMessageOptions {
-    /** Match a message's `targetScreen` to the current screen. */
-    screen?: string;
-    /**
-     * Restrict to messages whose `trigger` equals this value (behavioral-trigger
-     * path, e.g. `'session_start'`). Omitted ⇒ trigger-agnostic (manual host call).
-     */
-    trigger?: string;
-    /** Fired business/custom event name, matched against `message.eventName`. */
-    event?: string;
-    /** Fired action value for forward-compatible action-specific messages. */
-    action?: string;
-    /** Fired `time_delay` threshold, used to select only that configured message. */
-    seconds?: number;
-    /** App/user context forwarded to the config fetch for server-side targeting. */
-    context?: EngageConfigContext;
-}
-
-/**
- * The host's deep-link sink for an in-app CTA tap. The SDK NEVER opens a URL — it
- * hands the resolved `deepLink` (and full message/cta) to the host, which decides
- * how to navigate (e.g. `Linking.openURL` / a router push). Only fired for a CTA
- * whose `action` resolves to a link with a `deepLink`.
- */
-export type InAppDeepLinkHandler = (info: {
-    message: InAppMessageConfig;
-    cta: NonNullable<InAppRenderSpec['cta']>;
-    deepLink: string;
-}) => void;
-
-/** Imperative controller a host app uses to trigger a prompt / in-app message. */
-export interface EngagePromptController {
-    /** Fetch config, pick an eligible campaign, and show it. Returns whether one was shown. */
-    showEngagePrompt: (options?: ShowEngagePromptOptions) => Promise<boolean>;
-    /** Dismiss the currently visible prompt (no response submitted). */
-    dismissEngagePrompt: () => void;
-    /**
-     * Fetch config, pick an eligible in-app message (`inAppMessages[]`), and show
-     * it. Returns whether one was shown. PRECEDENCE: a campaign prompt already on
-     * screen wins — an in-app message is NOT shown over it (see provider doc).
-     */
-    showInAppMessage: (options?: ShowInAppMessageOptions) => Promise<boolean>;
-    /** Dismiss the currently visible in-app message (emits a `dismiss` event). */
-    dismissInAppMessage: () => void;
-}
-
-const EngagePromptContext = createContext<EngagePromptController | null>(null);
-
-export interface EngagePromptProviderProps {
-    /** The SDK facade's `engage` namespace (e.g. `ScaleBun.engage`). */
-    engage: EngageRendererFacade;
-    /** Default campaign types to consider. Defaults to NPS-first. */
-    defaultTypes?: EngageCampaignType[];
-    /**
-     * RATING_PROMPT routing config (host-supplied). The app-store deeplink and
-     * feedback hand-off are NEVER hardcoded in the SDK — supplied here.
-     */
-    ratingRouting?: EngageRatingRouting;
-    /**
-     * Host sink for an in-app message CTA deep link. The SDK never opens URLs —
-     * it surfaces the resolved `deepLink` here for the host to navigate. Optional:
-     * a host that never uses link-action CTAs need not supply it.
-     */
-    onInAppDeepLink?: InAppDeepLinkHandler;
-    /**
-     * Required when a production gamified campaign is used. The SDK calls this
-     * only at play/load/check-in/quiz resolution time; the host's authenticated
-     * backend owns eligibility, granting, and the returned result.
-     */
-    onInAppGameRequest?: InAppGameRequestHandler;
-    /**
-     * DEV/TEST ONLY — poll interval (ms) for queued test previews while the app is
-     * already foregrounded. `checkForPreview` runs on mount + every AppState→active,
-     * which covers "reopen the app". But if you press "Send Test" while the app is
-     * ALREADY open and in the foreground, there is no background→foreground edge to
-     * trigger a refetch. Setting e.g. `previewPollMs={4000}` makes a warm, foreground
-     * app pick up a Send Test within a few seconds with no app switch. Leave UNSET in
-     * production (0/undefined ⇒ no polling — the foreground/cold-start fetch is enough).
-     */
-    previewPollMs?: number;
-    children: ReactNode;
-}
-
-const DEFAULT_TYPES: EngageCampaignType[] = ['NPS'];
-
-/**
- * Provider that mounts the shared overlay and exposes the imperative controller
- * via `useEngagePrompt()`.
- */
-export function EngagePromptProvider({
-    engage,
-    defaultTypes,
-    ratingRouting,
-    onInAppDeepLink,
-    onInAppGameRequest,
-    previewPollMs,
-    children,
-}: EngagePromptProviderProps): ReactElement {
-    const [active, setActive] = useState<EngageCampaignConfig | null>(null);
-    const [activeInApp, setActiveInApp] = useState<InAppMessageConfig | null>(null);
-    const [inlineFallbackMessageId, setInlineFallbackMessageId] = useState<string | null>(null);
-    const [inlinePlacementRevision, setInlinePlacementRevision] = useState(0);
-    const inlinePlacementRegistry = useMemo(createEngageInlinePlacementRegistry, []);
-    const shownInAppMessageIdRef = useRef<string | null>(null);
-    // Resolved A/B arm for the active in-app message (D8/J6). Held in a ref: it is
-    // render-stable metadata (the chosen `spec` drives the view, the `variant` id
-    // rides the lifecycle events) and must not perturb the precedence that keys off
-    // `activeInApp`. `null` when no message is active (or it has no experiment).
-    const activeInAppVariantRef = useRef<
-        { variant: InAppVariantId; spec: InAppRenderSpec } | null
-    >(null);
-    // Show-time screen of the currently-active campaign prompt (contract §1
-    // `screen`). Held in a ref alongside `active` — it is render-irrelevant
-    // metadata read only at submit, so it needs no re-render and must not perturb
-    // the campaign-vs-in-app precedence which keys off `active`/`activeInApp`.
-    const activeScreenRef = useRef<string | undefined>(undefined);
-    const surveyStartedRef = useRef<string | null>(null);
-    // [T1] Test previews bypass the throttle store and the backend re-serves them on
-    // EVERY config poll until TTL — great for "reopen the app and see it again", but it
-    // means a dismissed preview would re-appear on the next warm poll. This session set
-    // records previews the user already closed (dismiss/CTA) so we don't re-show the SAME
-    // one. It is in-memory only: a cold restart clears it, so reopening the app still
-    // shows the queued test (the intended QA behavior).
-    const consumedPreviewIds = useRef<Set<string>>(new Set());
-    // [T1] Persistent dedupe for ONE-SHOT test delivery — survives cold restarts (unlike
-    // consumedPreviewIds above). A testRunId is recorded here AFTER it actually renders, so
-    // reopening the app does NOT re-show a test the device already displayed. This is the
-    // fix for "close/open and the old test re-appears, and they stack up". Separate from the
-    // throttle store so production frequency caps never block a fresh test and vice-versa.
-    const seenTestsRef = useRef<EngageTestSeenStore | null>(null);
-    if (seenTestsRef.current === null) {
-        seenTestsRef.current = new EngageTestSeenStore();
-    }
-    // One persistent throttle store for the provider lifetime — SHARED by campaigns
-    // and in-app messages so both honor the same per-id frequency caps.
-    const storeRef = useRef<EngageThrottleStore | null>(null);
-    if (storeRef.current === null) {
-        storeRef.current = new EngageThrottleStore();
-    }
-    const types = defaultTypes ?? DEFAULT_TYPES;
-
-    // ─── Reusable submit state machine (Slice D5) ────────────────────────────
-    // ONE machine for EVERY question type. `responseIdRef` is the idempotency key,
-    // generated once per prompt and REUSED on retry so a re-send can't duplicate.
-    // `submitCtxRef` holds the campaign+result so retry re-runs the same submit.
-    const [submitStatus, setSubmitStatus] = useState<EngageSubmitStatus>({ phase: 'idle' });
-    const responseIdRef = useRef<string | null>(null);
-    const submitCtxRef = useRef<{ campaign: EngageCampaignConfig; result: EngagePromptResult } | null>(null);
-    const successTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-    const resetSubmit = useCallback((): void => {
-        if (successTimerRef.current) {
-            clearTimeout(successTimerRef.current);
-            successTimerRef.current = null;
-        }
-        responseIdRef.current = null;
-        submitCtxRef.current = null;
-        setSubmitStatus({ phase: 'idle' });
-    }, []);
-
-    // Single campaign tracking lane (mirrors trackInApp). `impression` on show,
-    // `completion` on submit, `dismiss` on close — the §2.5 analytics events that
-    // back the response-rate / completion KPIs (P3-e #2). Distinct from the local
-    // throttle store, which only counts impressions for frequency caps.
-    const trackCampaign = useCallback(
-        (campaign: EngageCampaignConfig, eventType: 'impression' | 'completion' | 'dismiss') => {
-            try {
-                engage.trackEvent({
-                    campaignId: campaign.id,
-                    channel: 'inapp',
-                    type: eventType,
-                    deviceId: getDeviceId(),
-                });
-            } catch (err) {
-                logger.debug('[Engage] trackEvent failed:', (err as Error)?.message);
-            }
-        },
-        [engage],
-    );
-
-    const trackSurveyStage = useCallback(
-        (campaign: EngageCampaignConfig, stage: 'shown' | 'started'): void => {
-            if (campaign.type === 'RATING_PROMPT' || campaign.type === 'RATINGS_PROMPT') return;
-            try {
-                engage.trackSurveyImpression?.({
-                    surveyId: campaign.id,
-                    stage,
-                    sessionId: currentSessionId(),
-                    deviceId: getDeviceId(),
-                    platform: currentPlatform(),
-                    appVersion: currentAppVersion(),
-                    screen: activeScreenRef.current,
-                });
-            } catch (err) {
-                logger.debug('[Engage] survey impression failed:', (err as Error)?.message);
-            }
-        },
-        [engage],
-    );
-
-    const isRatingType = (type: EngageCampaignType): boolean =>
-        type === 'RATING_PROMPT' || type === 'RATINGS_PROMPT';
-
-    // Rating-funnel emit lane (ratings-rebuild CONTRACT §1.2). Distinct from
-    // trackCampaign (the §2.5 in-app analytics lane) and from submitRating (the D1
-    // app-rating lane): these are dimensioned FACTS feeding the Overview funnel and
-    // are NEVER counted as responses. `stars` rides only on `rating_selected`.
-    const emitRatingFunnel = useCallback(
-        (
-            campaign: EngageCampaignConfig,
-            type: RatingFunnelEventType,
-            extra?: { stars?: number },
-        ): void => {
-            try {
-                engage.emitRatingEvent?.({
-                    type,
-                    sessionId: currentSessionId(),
-                    userId: engage.getIdentifiedUserId?.(),
-                    promptId: campaign.id,
-                    triggerId: campaign.trigger,
-                    ...(extra?.stars !== undefined ? { stars: extra.stars } : {}),
-                    dims: currentRatingDims(),
-                });
-            } catch (err) {
-                logger.debug('[Engage] emitRatingEvent failed:', (err as Error)?.message);
-            }
-        },
-        [engage],
-    );
-
-    const dismissEngagePrompt = useCallback((): void => {
-        setActive((current) => {
-            if (current) {
-                trackCampaign(current, 'dismiss');
-                // Rating funnel: a close without a selection is a funnel drop.
-                if (isRatingType(current.type)) emitRatingFunnel(current, 'rating_prompt_dismissed');
-            }
-            return null;
-        });
-        activeScreenRef.current = undefined;
-        surveyStartedRef.current = null;
-        resetSubmit();
-    }, [trackCampaign, resetSubmit, emitRatingFunnel]);
-
-    // The actual submit run — used by both the first submit and a retry. Reads
-    // `submitCtxRef` + `responseIdRef` so a retry re-sends with the SAME idempotency
-    // key. Resolves to `success` ONLY on confirmed persistence; `error` on failure.
-    const runSubmit = useCallback(async (): Promise<void> => {
-        const ctx = submitCtxRef.current;
-        if (!ctx) return;
-        const { campaign, result } = ctx;
-        const store = storeRef.current;
-        const responseId = responseIdRef.current ?? (responseIdRef.current = ratingUuid());
-
-        setSubmitStatus({ phase: 'submitting', stage: 'saving' });
-        try {
-            if (isRatingType(campaign.type)) {
-                // RATING_PROMPT submits via the EXISTING app-rating lane (D1), NOT
-                // submitResponse, with a client clientRatingId for idempotency. Awaited
-                // so the loading state reflects the real round-trip.
-                const rating = typeof result.score === 'number' ? result.score : 0;
-                await Promise.resolve(
-                    engage.submitRating?.({ rating, source: 'prompt', clientRatingId: responseId }),
-                );
-                // Funnel: user picked 1–5★ (carries stars). Emitted regardless of route.
-                emitRatingFunnel(campaign, 'rating_selected', { stars: rating });
-                // Routing decided by the view (`route`), executed against host-supplied
-                // callbacks/URL — the deeplink is never hardcoded.
-                if (result.route === 'store') {
-                    // D5: prefer the genuinely-native in-app review sheet. `store_redirect_clicked`
-                    // fires ONLY when an actual store route resolves (native review ran, or a
-                    // host-supplied deeplink/callback executed) — never speculatively.
-                    let redirected = false;
-                    if (engage.requestStoreReview) {
-                        redirected = await engage.requestStoreReview();
-                    }
-                    const storeUrl = campaign.storeUrl ?? ratingRouting?.storeUrl;
-                    if (ratingRouting?.onHighRating) {
-                        ratingRouting.onHighRating({ rating, campaign, storeUrl });
-                        redirected = true;
-                    } else if (!redirected && storeUrl) {
-                        redirected = await Linking.openURL(storeUrl).then(() => true).catch(() => false);
-                    }
-                    if (redirected) emitRatingFunnel(campaign, 'store_redirect_clicked');
-                } else if (result.route === 'feedback') {
-                    ratingRouting?.onLowRating?.({ rating, campaign });
-                }
-            } else {
-                // [v2] response context (contract §1): session linkage + originating
-                // screen + platform + app version. All optional; omitted when unresolved.
-                // We send ONLY the new response fact + the sessionId; replay/errors/network
-                // are NOT re-sent — the read side joins them by sessionId.
-                const input: EngageResponseInput = Array.isArray(result.answers)
-                    ? {
-                          surveyId: campaign.id,
-                          text: result.reason,
-                          answers: toWireAnswers(result.answers),
-                          deviceId: getDeviceId(),
-                          sessionId: currentSessionId(),
-                          screen: activeScreenRef.current,
-                          platform: currentPlatform(),
-                          appVersion: currentAppVersion(),
-                      }
-                    : {
-                          surveyId: campaign.id,
-                          score: result.score,
-                          text: result.reason,
-                          tags: result.tags,
-                          deviceId: getDeviceId(),
-                          sessionId: currentSessionId(),
-                          screen: activeScreenRef.current,
-                          platform: currentPlatform(),
-                          appVersion: currentAppVersion(),
-                      };
-
-                const drafts = result.attachments ?? [];
-                if (engage.submitResponseConfirmed) {
-                    // Confirmed lane: awaits real persistence (presign+PUT bytes → response
-                    // POST), reports stages, idempotent on responseId, throws on failure.
-                    await engage.submitResponseConfirmed(input, drafts, {
-                        responseId,
-                        onStage: (stage) => setSubmitStatus({ phase: 'submitting', stage }),
-                    });
-                } else if (drafts.length > 0 && engage.submitResponseWithAttachments) {
-                    // Fallback (older facade): fire-and-forget — resolves immediately.
-                    engage.submitResponseWithAttachments(input, drafts);
-                } else {
-                    engage.submitResponse(input);
-                }
-            }
-
-            store?.markCompleted(campaign.id);
-            trackCampaign(campaign, 'completion');
-            setSubmitStatus({ phase: 'success' });
-            // Brief success beat, then close + reset.
-            successTimerRef.current = setTimeout(() => {
-                setActive(null);
-                activeScreenRef.current = undefined;
-                resetSubmit();
-            }, 1100);
-        } catch (err) {
-            logger.warn('[Engage] submit failed:', (err as Error)?.message);
-            setSubmitStatus({ phase: 'error', message: (err as Error)?.message });
-        }
-    }, [engage, trackCampaign, ratingRouting, resetSubmit, emitRatingFunnel]);
-
-    const handleSubmit = useCallback(
-        (campaign: EngageCampaignConfig, result: EngagePromptResult): void => {
-            // Guard double-submit: ignore re-fires once a submit is in flight or done.
-            if (submitCtxRef.current && responseIdRef.current) return;
-            submitCtxRef.current = { campaign, result };
-            void runSubmit();
-        },
-        [runSubmit],
-    );
-
-    const closeAfterSubmit = useCallback((): void => {
-        setActive(null);
-        activeScreenRef.current = undefined;
-        resetSubmit();
-    }, [resetSubmit]);
-
-    const showEngagePrompt = useCallback(
-        async (options?: ShowEngagePromptOptions): Promise<boolean> => {
-            const store = storeRef.current;
-            if (!store) return false;
-            try {
-                const config = await engage.fetchConfig(options?.context);
-                if (!config || !Array.isArray(config.campaigns)) return false;
-
-                const campaign = selectCampaignToRender(config.campaigns, store, {
-                    // A behavioral-trigger fire (`options.trigger`) is type-agnostic:
-                    // the trigger itself selects the campaign, so don't layer the
-                    // NPS-first default on top (it would drop FEEDBACK/CSAT/etc.).
-                    // Manual fires keep the provider default unless overridden.
-                    types: options?.types ?? (options?.trigger ? undefined : types),
-                    screen: options?.screen,
-                    trigger: options?.trigger,
-                    seconds: options?.seconds,
-                    event: options?.event,
-                    action: options?.action,
-                });
-                if (!campaign) {
-                    logger.debug('[Engage] no eligible campaign to render');
-                    return false;
-                }
-
-                // Record the impression up front so throttle counts it even if the
-                // user backgrounds the app before submitting.
-                store.recordImpression(campaign.id);
-                // Emit the §2.5 impression event (P3-e #2) so the dashboard's
-                // response-rate / completion KPIs have a real denominator — the
-                // prompt path previously only counted impressions locally.
-                trackCampaign(campaign, 'impression');
-                // Rating funnel (CONTRACT §1.1): selection passed the throttle/anti-
-                // annoyance gate (→ eligible) and we are about to render (→ shown).
-                if (isRatingType(campaign.type)) {
-                    emitRatingFunnel(campaign, 'rating_prompt_eligible');
-                    emitRatingFunnel(campaign, 'rating_prompt_shown');
-                }
-                // Stamp the show-time screen alongside the active campaign so
-                // handleSubmit can attribute the response to its originating screen.
-                activeScreenRef.current = options?.screen;
-                surveyStartedRef.current = null;
-                trackSurveyStage(campaign, 'shown');
-                resetSubmit();
-                setActive(campaign);
-                return true;
-            } catch (err) {
-                logger.warn('[Engage] showEngagePrompt failed:', (err as Error)?.message);
-                return false;
-            }
-        },
-        [engage, types, trackCampaign, trackSurveyStage, emitRatingFunnel],
-    );
-
-    // ─── In-app message lifecycle (the second Engage family, §2.4/§2.5) ──────
-    // Reuses the SAME transport (`trackEvent`), the SAME throttle store, and the
-    // SAME provider — NOT a parallel provider. Events: impression on show, click
-    // on CTA tap, completion on a finished tour, dismiss on close/skip.
-
-    const trackInApp = useCallback(
-        (
-            message: InAppMessageConfig,
-            eventType:
-                | 'impression'
-                | 'completion'
-                | 'click'
-                | 'dismiss'
-                | 'interaction'
-                | 'render_degraded'
-                | 'render_failed'
-                | 'cta_open_failed',
-            extraMeta?: Record<string, unknown>,
-        ): void => {
-            try {
-                // A/B attribution (D8/J6): when the active message resolved to an
-                // experiment arm, tag every lifecycle event with the chosen variant
-                // via the existing optional `meta` field — NO event-schema change
-                // (EngageEventUpload already carries `meta`; the backend EngageEvent
-                // accepts it). Plain (non-experiment) messages send no variant key.
-                const variant = activeInAppVariantRef.current?.variant;
-                // [T1] Test-preview tagging: a preview-flagged message stamps
-                // `previewId` + `isTest` + `source` so (a) the backend CONSUMES the
-                // matching preview row on the impression and (b) production KPIs
-                // exclude the traffic. Normal campaign messages omit all of it.
-                const isPreview = message.preview === true || message.isTest === true;
-                const meta = {
-                    ...(variant ? { variant } : {}),
-                    // testRunId correlates a specific "Send Test" run to its render/click/
-                    // dismiss in the dashboard; rides the existing meta field (no schema churn).
-                    ...(message.testRunId ? { testRunId: message.testRunId } : {}),
-                    ...(extraMeta ?? {}),
-                };
-                engage.trackEvent({
-                    campaignId: message.id,
-                    channel: 'inapp',
-                    type: eventType,
-                    deviceId: getDeviceId(),
-                    ...(message.previewId ? { previewId: message.previewId } : {}),
-                    ...(isPreview ? { isTest: true, source: 'test_preview' } : {}),
-                    ...(variant ? { variantId: variant } : {}),
-                    ...(Object.keys(meta).length > 0 ? { meta } : {}),
-                });
-            } catch (err) {
-                logger.debug('[Engage] in-app trackEvent failed:', (err as Error)?.message);
-            }
-        },
-        [engage],
-    );
-
-    // [T1] In-app message actually mounted on screen. The impression event IS the test
-    // ACK to the backend (which consumes the preview row → 'rendered'). We ALSO persist the
-    // testRunId locally so a cold restart can't re-show it before the ACK is processed
-    // server-side — the one-shot guarantee survives a flaky/slow network.
-    const handleInAppShow = useCallback(
-        (message: InAppMessageConfig): void => {
-            // A slot can be replaced or degrade to an overlay while the same message
-            // remains active. Treat that as one mount lifecycle, not two impressions.
-            if (shownInAppMessageIdRef.current === message.id) return;
-            shownInAppMessageIdRef.current = message.id;
-            trackInApp(message, 'impression');
-            if (message.preview === true || message.isTest === true) {
-                const runId = message.testRunId ?? message.previewId ?? message.id;
-                seenTestsRef.current?.markSeen(runId);
-                // Eager-flush so the backend consumes the one-shot preview row NOW — a fast
-                // close→kill→reopen must not re-serve a still-`delivered` test.
-                engage.flushEvents?.();
-                logger.debug(`[Engage] test ${runId} render displayed — ACK sent (impression), flushed`);
-            }
-        },
-        [trackInApp, engage],
-    );
-
-    const finalizeInAppMessage = useCallback((eventType: 'dismiss' | 'completion'): void => {
-        setActiveInApp((current) => {
-            if (current) {
-                const isTest = current.preview === true || current.isTest === true;
-                const runId = current.testRunId ?? current.previewId ?? current.id;
-                logger.debug(`[Engage] in-app ${eventType}${isTest ? ` (test ${runId})` : ''}`);
-                trackInApp(current, eventType);
-                if (isTest) {
-                    consumedPreviewIds.current.add(current.previewId ?? current.id);
-                    seenTestsRef.current?.markSeen(runId);
-                    engage.flushEvents?.();
-                    logger.debug(`[Engage] test ${runId} ${eventType} persisted + ACK flushed`);
-                } else {
-                    storeRef.current?.markCompleted(current.id);
-                    engage.flushEvents?.();
-                    logger.debug(`[Engage] in-app ${current.id} ${eventType} — marked done on device`);
-                }
-            }
-            return null;
-        });
-        // Clear the resolved A/B arm after the lifecycle event has read it.
-        shownInAppMessageIdRef.current = null;
-        activeInAppVariantRef.current = null;
-    }, [trackInApp, engage]);
-
-    const dismissInAppMessage = useCallback((): void => {
-        finalizeInAppMessage('dismiss');
-    }, [finalizeInAppMessage]);
-
-    const completeInAppMessage = useCallback((): void => {
-        finalizeInAppMessage('completion');
-    }, [finalizeInAppMessage]);
-
-    const handleInAppCta = useCallback(
-        (message: InAppMessageConfig, cta: NonNullable<InAppRenderSpec['cta']>): void => {
-            if (shouldTrackInAppCta(cta)) trackInApp(message, 'click');
-            // Deep-link opening is the host's job — surface it, never open it here.
-            if (cta.action === 'link') {
-                if (!cta.deepLink) {
-                    // Misconfigured link CTA (no deepLink) — observable, not silent (T1 G17).
-                    logger.warn('[Engage] link CTA has no deepLink');
-                    trackInApp(message, 'cta_open_failed', { reason: 'missing_deeplink' });
-                } else if (!onInAppDeepLink) {
-                    // Host wired no deep-link sink — the link can't open. Diagnose it.
-                    logger.warn('[Engage] link CTA but no onInAppDeepLink handler supplied');
-                    trackInApp(message, 'cta_open_failed', { reason: 'no_handler' });
-                } else {
-                    try {
-                        onInAppDeepLink({ message, cta, deepLink: cta.deepLink });
-                    } catch (err) {
-                        logger.warn('[Engage] onInAppDeepLink threw:', (err as Error)?.message);
-                        trackInApp(message, 'cta_open_failed', {
-                            reason: (err as Error)?.message ?? 'handler_threw',
-                        });
-                    }
-                }
-            }
-            // A test preview the user acted on is done — don't re-show it next poll AND
-            // persist it durably (a CTA tap is as final as a close), then flush the ACK.
-            if (message.preview === true || message.isTest === true) {
-                const runId = message.testRunId ?? message.previewId ?? message.id;
-                consumedPreviewIds.current.add(message.previewId ?? message.id);
-                seenTestsRef.current?.markSeen(runId);
-                engage.flushEvents?.();
-                logger.debug(`[Engage] test ${runId} CTA — persisted locally + ACK flushed`);
-            } else {
-                // Production message: a CTA tap is as final as a close — don't re-show it.
-                storeRef.current?.markCompleted(message.id);
-                engage.flushEvents?.();
-                logger.debug(`[Engage] in-app ${message.id} CTA tapped — marked done on device`);
-            }
-            setActiveInApp(null);
-            // Any enabled click event above already read the arm; clear it now.
-            shownInAppMessageIdRef.current = null;
-            activeInAppVariantRef.current = null;
-        },
-        [trackInApp, onInAppDeepLink, engage],
-    );
-
-    // [T1] Pick the ONE test preview to render from a fetched config: drop any already
-    // displayed (persistent seen store) or closed-this-session, then take the LATEST by
-    // createdAt. One-shot + latest-only is what stops the "tests stack up 1,2,3…" bug.
-    const pickLatestPreview = useCallback(
-        (messages: InAppMessageConfig[]): InAppMessageConfig | null => {
-            const latest = selectLatestUnseenTest(messages, {
-                seen: (runId) => seenTestsRef.current?.has(runId) ?? false,
-                consumed: (key) => consumedPreviewIds.current.has(key),
-            });
-            if (latest) logger.debug(`[Engage] selected latest test ${testRunIdOf(latest)}`);
-            return latest;
-        },
-        [],
-    );
-
-    // [T1] Render a test preview IMMEDIATELY — bypassing trigger/throttle/schedule/
-    // sample/variant. No throttle write (a preview must stay re-showable until it is
-    // actually rendered + its impression consumes it server-side). Idempotent: if this
-    // exact preview is already on screen, don't re-mount (avoids a duplicate impression).
-    const showPreview = useCallback(
-        (preview: InAppMessageConfig): boolean => {
-            // PRECEDENCE: a campaign prompt owns the screen — defer (the backend re-serves
-            // the preview on every poll until TTL, so the next foreground retries).
-            if (active !== null) {
-                logger.debug('[Engage] campaign prompt active — preview deferred');
-                return false;
-            }
-            if (activeInApp?.id === preview.id) return true;
-            const runId = preview.testRunId ?? preview.previewId ?? preview.id;
-            // Already closed this preview this session — don't re-show on the next poll.
-            if (consumedPreviewIds.current.has(preview.previewId ?? preview.id)) {
-                return false;
-            }
-            // [T1] One-shot: already DISPLAYED on this device (persisted across restarts) —
-            // never re-show, even if the backend briefly re-serves a not-yet-ACKed row.
-            if (seenTestsRef.current?.has(runId)) {
-                logger.debug(`[Engage] test ${runId} already displayed on device — skip`);
-                return false;
-            }
-            activeInAppVariantRef.current = null;
-            setActiveInApp(preview);
-            logger.debug(`[Engage] test ${runId} render started`);
-            return true;
-        },
-        [active, activeInApp],
-    );
-
-    const showInAppMessage = useCallback(
-        async (options?: ShowInAppMessageOptions): Promise<boolean> => {
-            const store = storeRef.current;
-            if (!store) return false;
-            // PRECEDENCE: a campaign prompt on screen wins — never stack an in-app
-            // message over an open survey/NPS/rating prompt.
-            if (active !== null) {
-                logger.debug('[Engage] campaign prompt active — in-app message deferred');
-                return false;
-            }
-            try {
-                const config = await engage.fetchConfig(buildConfigContext(engage, options?.context));
-                if (!config || !Array.isArray(config.inAppMessages)) return false;
-
-                // [T1] A queued test preview wins immediately, bypassing throttle/variant.
-                // Pick the LATEST unseen one (one-shot dedupe) — never stack old tests.
-                const preview = pickLatestPreview(config.inAppMessages);
-                if (preview) return showPreview(preview);
-
-                // Normal selection runs over NON-preview messages only — a preview must
-                // never enter the throttle store (it would falsely cap a real campaign id).
-                const normal = config.inAppMessages.filter(
-                    (m) => !(m.preview === true || m.isTest === true),
-                );
-                const message = selectInAppToRender(normal, store, {
-                    screen: options?.screen,
-                    trigger: options?.trigger,
-                    seconds: options?.seconds,
-                    event: options?.event,
-                    action: options?.action,
-                });
-                if (!message) {
-                    logger.debug('[Engage] no eligible in-app message to render');
-                    return false;
-                }
-
-                // A/B variant selection (D8/J6): deterministically bucket this
-                // device into arm A (base spec) or B (experiment.variantB) BEFORE
-                // showing, so the impression event (and click/dismiss) attribute to
-                // the arm the user actually saw. Only retained for attribution when
-                // the message actually carries an enabled experiment; otherwise the
-                // resolved spec is just the base spec and no variant key is emitted.
-                const resolved = selectInAppVariant(message, getDeviceId());
-                activeInAppVariantRef.current = message.experiment?.enabled
-                    ? resolved
-                    : null;
-                // Record up front so the throttle counts it (impression also emitted
-                // by the view's onShow → trackEvent for the analytics lane). Pass the
-                // content revision so an edited campaign starts a fresh cap generation.
-                store.recordImpression(message.id, Date.now(), message.revision);
-                setActiveInApp(message);
-                return true;
-            } catch (err) {
-                logger.warn('[Engage] showInAppMessage failed:', (err as Error)?.message);
-                return false;
-            }
-        },
-        [engage, active, showPreview, pickLatestPreview],
-    );
-
-    // ─── Cold-start + foreground preview check (T1) ──────────────────────────
-    // "Send Test → reopen the app → see it immediately, EVERY time": the SDK fetches
-    // config (deviceId in context, HTTP cache-bypassed) on mount AND on every
-    // AppState→active, and renders any queued preview at once — no trigger, no throttle,
-    // no schedule. The backend keeps serving the preview on every poll until its TTL, so
-    // a tester sees it on each reopen (rendering records lifecycle but does not consume).
-    const checkForPreview = useCallback(async (): Promise<void> => {
-        if (active !== null) return;
-        try {
-            const config = await engage.fetchConfig(buildConfigContext(engage));
-            // One-shot + latest-only: render the newest test not already displayed.
-            const preview = pickLatestPreview(config?.inAppMessages ?? []);
-            if (preview) showPreview(preview);
-        } catch (err) {
-            logger.warn('[Engage] preview check failed:', (err as Error)?.message);
-        }
-    }, [engage, active, showPreview, pickLatestPreview]);
-
-    useEffect(() => {
-        // Drop stale seen-test entries (past TTL) so the persistent set stays bounded.
-        seenTestsRef.current?.prune();
-        void checkForPreview();
-        const onLifecycle = (state: string): void => {
-            if (state === 'active') void checkForPreview();
-        };
-        appLifecycle.addListener(onLifecycle);
-        return () => appLifecycle.removeListener(onLifecycle);
-    }, [checkForPreview]);
-
-    // DEV/TEST warm-foreground poll (T1): covers "Send Test while the app is already
-    // open" — no background→foreground edge fires, so without this you'd have to switch
-    // apps to see it. Only runs when the host opts in via `previewPollMs` (unset in prod).
-    useEffect(() => {
-        if (!previewPollMs || previewPollMs <= 0) return;
-        logger.debug(`[Engage] test-preview warm poll every ${previewPollMs}ms (dev)`);
-        const interval = setInterval(() => {
-            void checkForPreview();
-        }, previewPollMs);
-        return () => clearInterval(interval);
-    }, [previewPollMs, checkForPreview]);
-
-    // ─── Always-on behavioral triggers (P3-e #3 / Slice E) ───────────────────
-    // The trigger engine wires every behavioral trigger (session_start, app_open,
-    // screen_view/exit, time_in_app, n_sessions, after_purchase, before_logout,
-    // custom_event, failed_action, after_crash/js_error, network_error, slow_screen,
-    // and the native gesture triggers) to the SDK signals the app already produces.
-    // A fire first tries the survey/rating campaign path (showEngagePrompt); if no
-    // campaign matches, the SAME trigger drives an in-app message (showInAppMessage).
-    // Both families share the throttle store, so a behavioral fire never double-shows.
-    // The engine buffers events fired before the first config arrives and replays
-    // them once it does (late binding), honoring each trigger's remaining delay.
-    useEffect(() => {
-        return installEngageTriggerEngine({
-            fire: (options) => {
-                void (async () => {
-                    const shown = await showEngagePrompt(options);
-                    if (!shown && options.trigger) {
-                        await showInAppMessage({
-                            trigger: options.trigger,
-                            screen: options.screen,
-                            event: options.event,
-                            action: options.action,
-                            seconds: options.seconds,
-                        });
-                    }
-                })();
-            },
-            fetchConfig: () => engage.fetchConfig(buildConfigContext(engage)),
-        });
-    }, [showEngagePrompt, showInAppMessage, engage]);
-
-    const controller = useMemo<EngagePromptController>(
-        () => ({
-            showEngagePrompt,
-            dismissEngagePrompt,
-            showInAppMessage,
-            dismissInAppMessage,
-        }),
-        [showEngagePrompt, dismissEngagePrompt, showInAppMessage, dismissInAppMessage],
-    );
-
-    const activeInAppSpec = activeInAppVariantRef.current?.spec ?? activeInApp?.spec;
-    const activeInAppPresentation = activeInApp && activeInAppSpec
-        ? resolveInAppPresentation({
-              layout: activeInApp.layout,
-              variantKey: activeInApp.variantKey,
-              spec: activeInAppSpec,
-          })
-        : null;
-    // Route by the canonical mount, not a variant allow-list. This covers every
-    // current/future inline variant, including smart_inbox_message.
-    const routesToInlineSlot = activeInAppPresentation?.mountModel === 'inline';
-    const inlinePlacement = resolveEngageInlinePlacement(activeInAppSpec);
-
-    const handleActiveInAppShow = useCallback((): void => {
-        if (!activeInApp) return;
-        handleInAppShow(activeInApp);
-        const tourId = activeInApp.spec.ext?.coachTourId;
-        const first = Array.isArray(activeInApp.spec.ext?.steps) ? activeInApp.spec.ext?.steps[0] as Record<string, unknown> | undefined : undefined;
-        if (typeof tourId === 'string') {
-            engage.trackCoachmarkEvent?.('$coachmark_tour_started', { tourId });
-            engage.trackCoachmarkEvent?.('$coachmark_step_entered', {
-                tourId,
-                stepId: String(first?.id ?? first?.anchorKey ?? '1'),
-            });
-        }
-    }, [activeInApp, handleInAppShow, engage]);
-    const handleActiveInAppCta = useCallback((cta: NonNullable<InAppRenderSpec['cta']>): void => {
-        if (activeInApp) handleInAppCta(activeInApp, cta);
-    }, [activeInApp, handleInAppCta]);
-    const handleActiveInAppInteraction = useCallback((interaction: InAppMechanicInteraction): void => {
-        if (!activeInApp) return;
-        trackInApp(activeInApp, 'interaction', { interaction });
-        const tourId = activeInApp.spec.ext?.coachTourId;
-        if (typeof tourId !== 'string' || interaction.mechanic !== 'coachmark_spotlight') return;
-        const meta = interaction.meta ?? {};
-        const stepId = String(meta.anchorKey ?? meta.step ?? meta.toStep ?? 'unknown');
-        if (interaction.result === 'step_viewed' && interaction.phase !== 'started') {
-            engage.trackCoachmarkEvent?.('$coachmark_step_entered', { tourId, stepId });
-        } else if (interaction.phase === 'completed') {
-            engage.trackCoachmarkEvent?.('$coachmark_tour_completed', { tourId, stepId });
-        } else if (interaction.result === 'skipped') {
-            engage.trackCoachmarkEvent?.('$coachmark_tour_abandoned', { tourId, stepId });
-        }
-    }, [activeInApp, trackInApp, engage]);
-    const handleActiveInAppRenderError = useCallback((reason: string): void => {
-        if (activeInApp) {
-            trackInApp(activeInApp, 'render_failed', { reason });
-            const tourId = activeInApp.spec.ext?.coachTourId;
-            if (typeof tourId === 'string') {
-                const anchorKey = reason.startsWith('anchor_not_found:') ? reason.slice('anchor_not_found:'.length) : 'unknown';
-                engage.trackCoachmarkEvent?.('$coachmark_anchor_failed', {
-                    tourId,
-                    stepId: anchorKey,
-                    reason: reason.startsWith('anchor_not_found:') ? 'anchor_not_found' : reason,
-                });
-            }
-        }
-        shownInAppMessageIdRef.current = null;
-        activeInAppVariantRef.current = null;
-        setActiveInApp(null);
-    }, [activeInApp, trackInApp, engage]);
-
-    useEffect(() => {
-        if (!routesToInlineSlot || !inlinePlacement.placementKey) return;
-        return inlinePlacementRegistry.subscribe(inlinePlacement.placementKey, () => {
-            setInlinePlacementRevision((revision) => revision + 1);
-        });
-    }, [inlinePlacement.placementKey, inlinePlacementRegistry, routesToInlineSlot]);
-
-    useEffect(() => {
-        if (!activeInApp || active !== null || !routesToInlineSlot) {
-            setInlineFallbackMessageId(null);
-            return;
-        }
-
-        const messageId = activeInApp.id;
-        // Once this message has visibly degraded, keep it on that mount. Moving it
-        // into a late slot would create a second renderer and a misleading lifecycle.
-        if (inlineFallbackMessageId === messageId) return;
-        const reason = inlinePlacement.placementKey
-            ? `inline_placement_not_found:${inlinePlacement.placementKey}`
-            : 'missing_inline_placement_key';
-        const delivery: EngageInlineDelivery = {
-            message: activeInApp,
-            spec: activeInAppSpec,
-            onShow: handleActiveInAppShow,
-            onCta: handleActiveInAppCta,
-            onDismiss: dismissInAppMessage,
-            onComplete: completeInAppMessage,
-            onInteraction: handleActiveInAppInteraction,
-            onInAppGameRequest,
-            onRenderError: handleActiveInAppRenderError,
-        };
-        const delivered = inlinePlacementRegistry.deliver(
-            inlinePlacement.placementKey,
-            delivery,
-        );
-
-        if (delivered) {
-            setInlineFallbackMessageId(null);
-        } else {
-            inlinePlacementRegistry.clear(inlinePlacement.placementKey, messageId);
-            if (inlinePlacement.fallback === 'skip') {
-                setInlineFallbackMessageId(null);
-                handleActiveInAppRenderError(reason);
-            } else {
-                // Preserve the legacy visible behavior, but make the degradation observable.
-                trackInApp(activeInApp, 'render_degraded', {
-                    reason,
-                    placementKey: inlinePlacement.placementKey,
-                    fallback: 'overlay',
-                });
-                setInlineFallbackMessageId(messageId);
-            }
-        }
-
-        return () => inlinePlacementRegistry.clear(inlinePlacement.placementKey, messageId);
-    }, [
-        active,
-        activeInApp,
-        activeInAppSpec,
-        dismissInAppMessage,
-        completeInAppMessage,
-        handleActiveInAppCta,
-        handleActiveInAppInteraction,
-        handleActiveInAppRenderError,
-        handleActiveInAppShow,
-        inlinePlacement.fallback,
-        inlinePlacement.placementKey,
-        inlinePlacementRegistry,
-        inlineFallbackMessageId,
-        inlinePlacementRevision,
-        onInAppGameRequest,
-        routesToInlineSlot,
-        trackInApp,
-    ]);
-
-    const rootInAppVisible = activeInApp !== null &&
-        active === null &&
-        (!routesToInlineSlot || inlineFallbackMessageId === activeInApp.id);
-
-    return (
-        <EngageAnchorProvider>
-            <EngageInlinePlacementProvider registry={inlinePlacementRegistry}>
-                <EngagePromptContext.Provider value={controller}>
-            {children}
-            <EngagePromptView
-                campaign={active}
-                visible={active !== null}
-                rating={ratingRouting}
-                submitStatus={submitStatus}
-                onRetrySubmit={() => void runSubmit()}
-                onCloseSubmit={closeAfterSubmit}
-                onSubmit={(result) => {
-                    if (active) handleSubmit(active, result);
-                }}
-                onStart={() => {
-                    if (active && surveyStartedRef.current !== active.id) {
-                        surveyStartedRef.current = active.id;
-                        trackSurveyStage(active, 'started');
-                    }
-                }}
-                onDismiss={dismissEngagePrompt}
-            />
-            {/* In-app message overlay. PRECEDENCE: only visible when no campaign
-                prompt is on screen, so the two families never fight for the view. */}
-            <EngageInAppView
-                message={activeInApp}
-                visible={rootInAppVisible}
-                mountModelOverride={routesToInlineSlot && inlineFallbackMessageId === activeInApp?.id
-                    ? 'overlay'
-                    : undefined}
-                // Render the resolved A/B arm's content (D8/J6) when an experiment is
-                // active; undefined ⇒ the view falls back to the message's base spec.
-                spec={activeInAppVariantRef.current?.spec}
-                onShow={handleActiveInAppShow}
-                onCta={handleActiveInAppCta}
-                onDismiss={dismissInAppMessage}
-                onComplete={completeInAppMessage}
-                onInteraction={handleActiveInAppInteraction}
-                onInAppGameRequest={onInAppGameRequest}
-                onRenderError={handleActiveInAppRenderError}
-            />
-                </EngagePromptContext.Provider>
-            </EngageInlinePlacementProvider>
-        </EngageAnchorProvider>
-    );
-}
-
-/**
- * Hook a host app uses to trigger/dismiss the prompt:
- *   const { showEngagePrompt } = useEngagePrompt();
- *   showEngagePrompt({ types: ['NPS'] });
- */
-export function useEngagePrompt(): EngagePromptController {
-    const ctx = useContext(EngagePromptContext);
-    if (!ctx) {
-        // Fail-soft: a host that calls the hook outside the provider gets no-ops
-        // instead of a crash (matches the SDK's no-throw public-API style).
-        return {
-            showEngagePrompt: async () => {
-                logger.warn('[Engage] useEngagePrompt() called outside <EngagePromptProvider>');
-                return false;
-            },
-            dismissEngagePrompt: () => {},
-            showInAppMessage: async () => {
-                logger.warn('[Engage] useEngagePrompt() called outside <EngagePromptProvider>');
-                return false;
-            },
-            dismissInAppMessage: () => {},
-        };
-    }
-    return ctx;
-}
+/**
+ * ScaleBun SDK — Engage Prompt Provider (campaign renderer core, D4)
+ *
+ * Wraps the host app and owns the campaign-render lifecycle for the shared
+ * cross-platform JS overlay:
+ *   1. on a trigger (app-controlled via `showEngagePrompt()` and/or the campaign's
+ *      own `trigger` from config), calls `facade.engage.fetchConfig()`,
+ *   2. runs the throttle/decision core (`selectCampaignToRender`) to pick which
+ *      campaign — if any — is eligible, honoring frequency caps,
+ *   3. mounts the parameterized `EngagePromptView` (Open/Closed: NPS now,
+ *      ratings/feedback/survey later via the renderer registry),
+ *   4. on submit → `facade.engage.submitResponse({ surveyId, score, text })`
+ *      (transport stamps `responseId` UUID + `schemaVersion` per contract),
+ *      records the impression as completed, and emits an in-app dismiss/submit
+ *      tracking event,
+ *   5. on dismiss → `facade.engage.trackEvent` with a `dismiss` event.
+ *
+ * The provider depends only on the `engage` namespace shape — NOT the whole
+ * facade — so it stays decoupled and testable, and reuses the existing transport
+ * (no second HTTP path).
+ *
+ * IN-APP MESSAGES (the second Engage family, §2.4/§2.5) are surfaced by this SAME
+ * provider — NOT a parallel one. `showInAppMessage()` fetches the config, picks an
+ * eligible message from `inAppMessages[]` (shared throttle store), and mounts the
+ * config-driven `EngageInAppView` (banner/modal/overlay). Events: `impression` on
+ * show, `click` on CTA tap (the resolved deep link is surfaced to the host via
+ * `onInAppDeepLink` — the SDK never opens URLs), `dismiss` on close.
+ *
+ * PRECEDENCE (campaign vs in-app): a campaign prompt wins the screen. If a
+ * campaign prompt is already visible, `showInAppMessage()` is a no-op (returns
+ * false) and the mounted in-app view is hidden while a campaign is up, so the two
+ * families never fight for the screen.
+ */
+
+import React, {
+    createContext,
+    useContext,
+    useCallback,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+    type ReactNode,
+    type ReactElement,
+} from 'react';
+import { Linking, Platform } from 'react-native';
+import { logger } from '../../core/logger/internalLogger';
+import { installEngageTriggerEngine } from './engageTriggerEngine';
+import { appLifecycle } from '../../core/lifecycle/appLifecycle';
+import { getDeviceId } from '../../core/id/deviceId';
+import { ReplaySdk } from '../replay/public/api';
+import { SessionManager } from '../session/SessionManager';
+import {
+    EngagePromptView,
+    type EngagePromptResult,
+    type EngageSubmitStatus,
+    type RatingPromptConfig,
+} from './EngagePromptView';
+import { EngageInAppView, type InAppMechanicInteraction } from './EngageInAppView';
+import { EngageAnchorProvider } from './EngageAnchor';
+import {
+    EngageInlinePlacementProvider,
+    createEngageInlinePlacementRegistry,
+    resolveEngageInlinePlacement,
+    type EngageInlineDelivery,
+} from './EngageInlinePlacement';
+import { resolveInAppPresentation } from './engageVariantResolver';
+import { shouldTrackInAppCta } from './engageOutcome';
+import type { SubmitStage } from './EngageTransport';
+import {
+    EngageThrottleStore,
+    selectCampaignToRender,
+    selectInAppToRender,
+    selectInAppVariant,
+    selectLatestUnseenTest,
+    testRunIdOf,
+} from './engageThrottle';
+import { EngageTestSeenStore } from './engageTestSeenStore';
+import type {
+    EngageAttachmentDraft,
+    EngageCampaignConfig,
+    EngageCampaignType,
+    EngageConfigContext,
+    EngageConfigResponse,
+    EngageEventInput,
+    InAppGameRequestHandler,
+    EngageResponseInput,
+    InAppMessageConfig,
+    InAppRenderSpec,
+    InAppVariantId,
+    RatingFunnelEventDims,
+    RatingFunnelEventInput,
+    RatingFunnelEventType,
+    SurveyAnswer,
+    SurveyImpressionInput,
+} from './engageTypes';
+
+/** Client-generated UUID for app-rating idempotency (D8: `clientRatingId`). */
+function ratingUuid(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+
+/** Preserve a multi-question survey answer in the keyed wire shape (§1.4). */
+export function toWireAnswers(
+    answers: SurveyAnswer[],
+): { key: string; value: string | number | string[] }[] {
+    return answers.map((a) => ({
+        key: a.key,
+        value: a.value,
+    }));
+}
+
+/**
+ * Resolve the canonical session id for response linkage (contract §1/§7).
+ * Primary source is `SessionManager.currentSessionId` — the always-on analytics
+ * session id (`rs-…`) that the replay recording attaches to (and that `/sessions/:id`
+ * keys on). `ReplaySdk.sessionId` (the orchestrator's recording id) is only set
+ * while a recording is mid-flight and reads `null` at submit time, so it is a
+ * fallback, not the primary. Returns `undefined` (not `null`) so the optional wire
+ * field is simply omitted when no session is active.
+ */
+function currentSessionId(): string | undefined {
+    return (
+        SessionManager.getExistingInstance()?.currentSessionId ??
+        ReplaySdk.sessionId ??
+        undefined
+    );
+}
+
+/**
+ * The host app version for by-version analytics (contract §1). Read from the
+ * SAME synchronous source the SDK's rating lane already uses
+ * (`SessionManager.currentSessionMetadata.appVersion`, populated from native
+ * device info) — NOT hardcoded, and NOT the SDK build version. `undefined` when
+ * no session metadata is available yet, so the optional field is omitted.
+ */
+function currentAppVersion(): string | undefined {
+    return SessionManager.getExistingInstance()?.currentSessionMetadata?.appVersion ?? undefined;
+}
+
+/**
+ * Device platform as the `'android' | 'ios'` wire union (contract §1). Shared JS
+ * path — NOT platform-gated — so Android and iOS both stamp their own value.
+ * `Platform.OS` also yields `'windows' | 'macos' | 'web'`; those are out of the
+ * SDK's mobile scope and intentionally collapse to `undefined` (field omitted).
+ */
+function currentPlatform(): 'android' | 'ios' | undefined {
+    return Platform.OS === 'android' || Platform.OS === 'ios' ? Platform.OS : undefined;
+}
+
+/**
+ * Build the config-serve context (contract §1.3 query). ALWAYS carries `deviceId`
+ * — the backend keys per-device test previews on it, so omitting it would hide a
+ * "Send Test" preview from the very device it was queued for (T1). `platform`/
+ * `appVersion` ride along for server-side targeting; both honest, both omitted when
+ * unresolved. A caller-supplied `context` (manual show) overrides field-by-field.
+ */
+function buildConfigContext(
+    engage: EngageRendererFacade,
+    override?: EngageConfigContext,
+): EngageConfigContext {
+    const identifiedUserId = engage.getIdentifiedUserId?.();
+    return {
+        deviceId: getDeviceId(),
+        ...(currentPlatform() ? { platform: currentPlatform() } : {}),
+        ...(currentAppVersion() ? { appVersion: currentAppVersion() } : {}),
+        ...(identifiedUserId ? { endUserId: identifiedUserId } : {}),
+        ...override,
+    };
+}
+
+/**
+ * Build the rating-funnel breakdown dimensions (ratings-rebuild CONTRACT §1.2 `dims`)
+ * from the SAME live session metadata the response builder reads — NOT hardcoded.
+ * Only honest, present values are included; `country`/`locale`/`acquisitionSource`
+ * are intentionally omitted here (no on-device source yet) so the backend reports
+ * them as absent rather than fabricated.
+ */
+function currentRatingDims(): RatingFunnelEventDims {
+    const meta = SessionManager.getExistingInstance()?.currentSessionMetadata;
+    const platform = currentPlatform();
+    return {
+        ...(platform ? { platform } : {}),
+        ...(meta?.appVersion ? { appVersion: meta.appVersion } : {}),
+        ...(meta?.osVersion ? { osVersion: meta.osVersion } : {}),
+        ...(meta?.deviceModel ? { deviceModel: meta.deviceModel } : {}),
+    };
+}
+
+/**
+ * The slice of the SDK facade the renderer consumes (the `engage` namespace).
+ * Matching this shape — rather than importing the facade — keeps the renderer a
+ * pure consumer of the foundation transport and trivially testable.
+ */
+export interface EngageRendererFacade {
+    /** External user id last supplied through ScaleBun.identify(). */
+    getIdentifiedUserId?: () => string | undefined;
+    fetchConfig: (context?: EngageConfigContext) => Promise<EngageConfigResponse | null>;
+    trackCoachmarkEvent?: (name: string, properties: Record<string, unknown>) => void;
+    submitResponse: (input: EngageResponseInput) => void;
+    /**
+     * [P3-e] Submit a response with native attachments (screenshot/voice). Optional
+     * so a host wired to an older facade still renders prompts (media silently
+     * degrades to a plain response).
+     */
+    submitResponseWithAttachments?: (
+        input: EngageResponseInput,
+        attachments: EngageAttachmentDraft[],
+    ) => void;
+    /**
+     * [Slice D5] CONFIRMED submit used by the reusable submitting→success→error state
+     * machine: resolves only on real server persistence, rejects on failure, idempotent
+     * on `responseId`. Optional so an older facade still renders prompts (falls back to
+     * the fire-and-forget lanes, which resolve immediately).
+     */
+    submitResponseConfirmed?: (
+        input: EngageResponseInput,
+        attachments: EngageAttachmentDraft[],
+        opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
+    ) => Promise<void>;
+    trackEvent: (input: EngageEventInput) => void;
+    trackSurveyImpression?: (input: SurveyImpressionInput) => void;
+    /**
+     * Force-flush queued in-app events immediately (bypassing the batch threshold/timer).
+     * Called right after a TEST preview's impression/dismiss ACK so the backend consumes
+     * the one-shot preview row before the app can be backgrounded/killed — otherwise a
+     * still-`delivered` row re-serves on the next reopen. Optional: an older facade simply
+     * relies on the periodic flush (eventual consistency).
+     */
+    flushEvents?: () => void;
+    /**
+     * Submit a 1–5 app-store rating via the EXISTING rating lane (NOT
+     * submitResponse — D1 keeps app-ratings a distinct funnel). The provider
+     * passes a client `clientRatingId` for idempotency (D8). Optional so a host
+     * that never shows RATING_PROMPT need not supply it.
+     */
+    submitRating?: (input: {
+        rating: number;
+        comment?: string;
+        source?: 'in_app' | 'prompt' | 'manual';
+        clientRatingId?: string;
+    }) => unknown;
+    /**
+     * Emit a rating-funnel tracking fact (ratings-rebuild CONTRACT §1.2) — eligible/
+     * shown/dismissed/selected/redirect. NOT a campaign response (D1). Optional so an
+     * older facade still renders rating prompts (the funnel just goes uninstrumented).
+     */
+    emitRatingEvent?: (input: RatingFunnelEventInput) => void;
+    /**
+     * Trigger the native in-app review sheet (D5). Resolves `true` only when the OS
+     * flow ran/resolved after a positive route, so the provider emits
+     * `store_redirect_clicked` solely on a `true` result. Optional/fail-soft.
+     */
+    requestStoreReview?: () => Promise<boolean>;
+}
+
+/**
+ * Host-app RATING_PROMPT routing config. The store deeplink is NEVER hardcoded —
+ * the host supplies either a static `storeUrl` or an `onHighRating` callback (e.g.
+ * `Linking.openURL(...)` / native `requestReview()`), and an `onLowRating` for the
+ * feedback hand-off. The provider only decides WHICH callback to invoke.
+ */
+export interface EngageRatingRouting extends RatingPromptConfig {
+    /** App-store deeplink opened on a high rating (host owns the navigation). */
+    storeUrl?: string;
+    /** Called on a high rating (>= threshold). Receives the resolved store URL if set. */
+    onHighRating?: (info: { rating: number; campaign: EngageCampaignConfig; storeUrl?: string }) => void;
+    /** Called on a low rating when routing to feedback (host opens its form). */
+    onLowRating?: (info: { rating: number; campaign: EngageCampaignConfig }) => void;
+}
+
+export interface ShowEngagePromptOptions {
+    /** Restrict to specific campaign types. Defaults to `['NPS']` (NPS-first slice). */
+    types?: EngageCampaignType[];
+    /** Match a campaign's `targetScreen` to the current screen. */
+    screen?: string;
+    /**
+     * Restrict to campaigns whose `trigger` equals this value (behavioral-trigger
+     * path, e.g. `'screen_exit'`). Omitted ⇒ trigger-agnostic (manual fire).
+     */
+    trigger?: string;
+    /** Event name for `custom_event` / `after_purchase` (matches `triggerConfig.event`). */
+    event?: string;
+    /** Action label for `failed_action` (matches `triggerConfig.action`). */
+    action?: string;
+    /** Fired `time_in_app` threshold, used to select only that configured timer. */
+    seconds?: number;
+    /** App/user context forwarded to the config fetch for server-side targeting. */
+    context?: EngageConfigContext;
+}
+
+export interface ShowInAppMessageOptions {
+    /** Match a message's `targetScreen` to the current screen. */
+    screen?: string;
+    /**
+     * Restrict to messages whose `trigger` equals this value (behavioral-trigger
+     * path, e.g. `'session_start'`). Omitted ⇒ trigger-agnostic (manual host call).
+     */
+    trigger?: string;
+    /** Fired business/custom event name, matched against `message.eventName`. */
+    event?: string;
+    /** Fired action value for forward-compatible action-specific messages. */
+    action?: string;
+    /** Fired `time_delay` threshold, used to select only that configured message. */
+    seconds?: number;
+    /** App/user context forwarded to the config fetch for server-side targeting. */
+    context?: EngageConfigContext;
+}
+
+/**
+ * The host's deep-link sink for an in-app CTA tap. The SDK NEVER opens a URL — it
+ * hands the resolved `deepLink` (and full message/cta) to the host, which decides
+ * how to navigate (e.g. `Linking.openURL` / a router push). Only fired for a CTA
+ * whose `action` resolves to a link with a `deepLink`.
+ */
+export type InAppDeepLinkHandler = (info: {
+    message: InAppMessageConfig;
+    cta: NonNullable<InAppRenderSpec['cta']>;
+    deepLink: string;
+}) => void;
+
+/** Imperative controller a host app uses to trigger a prompt / in-app message. */
+export interface EngagePromptController {
+    /** Fetch config, pick an eligible campaign, and show it. Returns whether one was shown. */
+    showEngagePrompt: (options?: ShowEngagePromptOptions) => Promise<boolean>;
+    /** Dismiss the currently visible prompt (no response submitted). */
+    dismissEngagePrompt: () => void;
+    /**
+     * Fetch config, pick an eligible in-app message (`inAppMessages[]`), and show
+     * it. Returns whether one was shown. PRECEDENCE: a campaign prompt already on
+     * screen wins — an in-app message is NOT shown over it (see provider doc).
+     */
+    showInAppMessage: (options?: ShowInAppMessageOptions) => Promise<boolean>;
+    /** Dismiss the currently visible in-app message (emits a `dismiss` event). */
+    dismissInAppMessage: () => void;
+}
+
+const EngagePromptContext = createContext<EngagePromptController | null>(null);
+
+export interface EngagePromptProviderProps {
+    /** The SDK facade's `engage` namespace (e.g. `ScaleBun.engage`). */
+    engage: EngageRendererFacade;
+    /** Default campaign types to consider. Defaults to NPS-first. */
+    defaultTypes?: EngageCampaignType[];
+    /**
+     * RATING_PROMPT routing config (host-supplied). The app-store deeplink and
+     * feedback hand-off are NEVER hardcoded in the SDK — supplied here.
+     */
+    ratingRouting?: EngageRatingRouting;
+    /**
+     * Host sink for an in-app message CTA deep link. The SDK never opens URLs —
+     * it surfaces the resolved `deepLink` here for the host to navigate. Optional:
+     * a host that never uses link-action CTAs need not supply it.
+     */
+    onInAppDeepLink?: InAppDeepLinkHandler;
+    /**
+     * Required when a production gamified campaign is used. The SDK calls this
+     * only at play/load/check-in/quiz resolution time; the host's authenticated
+     * backend owns eligibility, granting, and the returned result.
+     */
+    onInAppGameRequest?: InAppGameRequestHandler;
+    /**
+     * DEV/TEST ONLY — poll interval (ms) for queued test previews while the app is
+     * already foregrounded. `checkForPreview` runs on mount + every AppState→active,
+     * which covers "reopen the app". But if you press "Send Test" while the app is
+     * ALREADY open and in the foreground, there is no background→foreground edge to
+     * trigger a refetch. Setting e.g. `previewPollMs={4000}` makes a warm, foreground
+     * app pick up a Send Test within a few seconds with no app switch. Leave UNSET in
+     * production (0/undefined ⇒ no polling — the foreground/cold-start fetch is enough).
+     */
+    previewPollMs?: number;
+    children: ReactNode;
+}
+
+const DEFAULT_TYPES: EngageCampaignType[] = ['NPS'];
+
+/**
+ * Provider that mounts the shared overlay and exposes the imperative controller
+ * via `useEngagePrompt()`.
+ */
+export function EngagePromptProvider({
+    engage,
+    defaultTypes,
+    ratingRouting,
+    onInAppDeepLink,
+    onInAppGameRequest,
+    previewPollMs,
+    children,
+}: EngagePromptProviderProps): ReactElement {
+    const [active, setActive] = useState<EngageCampaignConfig | null>(null);
+    const [activeInApp, setActiveInApp] = useState<InAppMessageConfig | null>(null);
+    const [inlineFallbackMessageId, setInlineFallbackMessageId] = useState<string | null>(null);
+    const [inlinePlacementRevision, setInlinePlacementRevision] = useState(0);
+    const inlinePlacementRegistry = useMemo(createEngageInlinePlacementRegistry, []);
+    const shownInAppMessageIdRef = useRef<string | null>(null);
+    // Resolved A/B arm for the active in-app message (D8/J6). Held in a ref: it is
+    // render-stable metadata (the chosen `spec` drives the view, the `variant` id
+    // rides the lifecycle events) and must not perturb the precedence that keys off
+    // `activeInApp`. `null` when no message is active (or it has no experiment).
+    const activeInAppVariantRef = useRef<
+        { variant: InAppVariantId; spec: InAppRenderSpec } | null
+    >(null);
+    // Show-time screen of the currently-active campaign prompt (contract §1
+    // `screen`). Held in a ref alongside `active` — it is render-irrelevant
+    // metadata read only at submit, so it needs no re-render and must not perturb
+    // the campaign-vs-in-app precedence which keys off `active`/`activeInApp`.
+    const activeScreenRef = useRef<string | undefined>(undefined);
+    const surveyStartedRef = useRef<string | null>(null);
+    // [T1] Test previews bypass the throttle store and the backend re-serves them on
+    // EVERY config poll until TTL — great for "reopen the app and see it again", but it
+    // means a dismissed preview would re-appear on the next warm poll. This session set
+    // records previews the user already closed (dismiss/CTA) so we don't re-show the SAME
+    // one. It is in-memory only: a cold restart clears it, so reopening the app still
+    // shows the queued test (the intended QA behavior).
+    const consumedPreviewIds = useRef<Set<string>>(new Set());
+    // [T1] Persistent dedupe for ONE-SHOT test delivery — survives cold restarts (unlike
+    // consumedPreviewIds above). A testRunId is recorded here AFTER it actually renders, so
+    // reopening the app does NOT re-show a test the device already displayed. This is the
+    // fix for "close/open and the old test re-appears, and they stack up". Separate from the
+    // throttle store so production frequency caps never block a fresh test and vice-versa.
+    const seenTestsRef = useRef<EngageTestSeenStore | null>(null);
+    if (seenTestsRef.current === null) {
+        seenTestsRef.current = new EngageTestSeenStore();
+    }
+    // One persistent throttle store for the provider lifetime — SHARED by campaigns
+    // and in-app messages so both honor the same per-id frequency caps.
+    const storeRef = useRef<EngageThrottleStore | null>(null);
+    if (storeRef.current === null) {
+        storeRef.current = new EngageThrottleStore();
+    }
+    const types = defaultTypes ?? DEFAULT_TYPES;
+
+    // ─── Reusable submit state machine (Slice D5) ────────────────────────────
+    // ONE machine for EVERY question type. `responseIdRef` is the idempotency key,
+    // generated once per prompt and REUSED on retry so a re-send can't duplicate.
+    // `submitCtxRef` holds the campaign+result so retry re-runs the same submit.
+    const [submitStatus, setSubmitStatus] = useState<EngageSubmitStatus>({ phase: 'idle' });
+    const responseIdRef = useRef<string | null>(null);
+    const submitCtxRef = useRef<{ campaign: EngageCampaignConfig; result: EngagePromptResult } | null>(null);
+    const successTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    const resetSubmit = useCallback((): void => {
+        if (successTimerRef.current) {
+            clearTimeout(successTimerRef.current);
+            successTimerRef.current = null;
+        }
+        responseIdRef.current = null;
+        submitCtxRef.current = null;
+        setSubmitStatus({ phase: 'idle' });
+    }, []);
+
+    // Single campaign tracking lane (mirrors trackInApp). `impression` on show,
+    // `completion` on submit, `dismiss` on close — the §2.5 analytics events that
+    // back the response-rate / completion KPIs (P3-e #2). Distinct from the local
+    // throttle store, which only counts impressions for frequency caps.
+    const trackCampaign = useCallback(
+        (campaign: EngageCampaignConfig, eventType: 'impression' | 'completion' | 'dismiss') => {
+            try {
+                engage.trackEvent({
+                    campaignId: campaign.id,
+                    channel: 'inapp',
+                    type: eventType,
+                    deviceId: getDeviceId(),
+                });
+            } catch (err) {
+                logger.debug('[Engage] trackEvent failed:', (err as Error)?.message);
+            }
+        },
+        [engage],
+    );
+
+    const trackSurveyStage = useCallback(
+        (campaign: EngageCampaignConfig, stage: 'shown' | 'started'): void => {
+            if (campaign.type === 'RATING_PROMPT' || campaign.type === 'RATINGS_PROMPT') return;
+            try {
+                engage.trackSurveyImpression?.({
+                    surveyId: campaign.id,
+                    stage,
+                    sessionId: currentSessionId(),
+                    deviceId: getDeviceId(),
+                    platform: currentPlatform(),
+                    appVersion: currentAppVersion(),
+                    screen: activeScreenRef.current,
+                });
+            } catch (err) {
+                logger.debug('[Engage] survey impression failed:', (err as Error)?.message);
+            }
+        },
+        [engage],
+    );
+
+    const isRatingType = (type: EngageCampaignType): boolean =>
+        type === 'RATING_PROMPT' || type === 'RATINGS_PROMPT';
+
+    // Rating-funnel emit lane (ratings-rebuild CONTRACT §1.2). Distinct from
+    // trackCampaign (the §2.5 in-app analytics lane) and from submitRating (the D1
+    // app-rating lane): these are dimensioned FACTS feeding the Overview funnel and
+    // are NEVER counted as responses. `stars` rides only on `rating_selected`.
+    const emitRatingFunnel = useCallback(
+        (
+            campaign: EngageCampaignConfig,
+            type: RatingFunnelEventType,
+            extra?: { stars?: number },
+        ): void => {
+            try {
+                engage.emitRatingEvent?.({
+                    type,
+                    sessionId: currentSessionId(),
+                    userId: engage.getIdentifiedUserId?.(),
+                    promptId: campaign.id,
+                    triggerId: campaign.trigger,
+                    ...(extra?.stars !== undefined ? { stars: extra.stars } : {}),
+                    dims: currentRatingDims(),
+                });
+            } catch (err) {
+                logger.debug('[Engage] emitRatingEvent failed:', (err as Error)?.message);
+            }
+        },
+        [engage],
+    );
+
+    const dismissEngagePrompt = useCallback((): void => {
+        setActive((current) => {
+            if (current) {
+                trackCampaign(current, 'dismiss');
+                // Rating funnel: a close without a selection is a funnel drop.
+                if (isRatingType(current.type)) emitRatingFunnel(current, 'rating_prompt_dismissed');
+            }
+            return null;
+        });
+        activeScreenRef.current = undefined;
+        surveyStartedRef.current = null;
+        resetSubmit();
+    }, [trackCampaign, resetSubmit, emitRatingFunnel]);
+
+    // The actual submit run — used by both the first submit and a retry. Reads
+    // `submitCtxRef` + `responseIdRef` so a retry re-sends with the SAME idempotency
+    // key. Resolves to `success` ONLY on confirmed persistence; `error` on failure.
+    const runSubmit = useCallback(async (): Promise<void> => {
+        const ctx = submitCtxRef.current;
+        if (!ctx) return;
+        const { campaign, result } = ctx;
+        const store = storeRef.current;
+        const responseId = responseIdRef.current ?? (responseIdRef.current = ratingUuid());
+
+        setSubmitStatus({ phase: 'submitting', stage: 'saving' });
+        try {
+            if (isRatingType(campaign.type)) {
+                // RATING_PROMPT submits via the EXISTING app-rating lane (D1), NOT
+                // submitResponse, with a client clientRatingId for idempotency. Awaited
+                // so the loading state reflects the real round-trip.
+                const rating = typeof result.score === 'number' ? result.score : 0;
+                await Promise.resolve(
+                    engage.submitRating?.({ rating, source: 'prompt', clientRatingId: responseId }),
+                );
+                // Funnel: user picked 1–5★ (carries stars). Emitted regardless of route.
+                emitRatingFunnel(campaign, 'rating_selected', { stars: rating });
+                // Routing decided by the view (`route`), executed against host-supplied
+                // callbacks/URL — the deeplink is never hardcoded.
+                if (result.route === 'store') {
+                    // D5: prefer the genuinely-native in-app review sheet. `store_redirect_clicked`
+                    // fires ONLY when an actual store route resolves (native review ran, or a
+                    // host-supplied deeplink/callback executed) — never speculatively.
+                    let redirected = false;
+                    if (engage.requestStoreReview) {
+                        redirected = await engage.requestStoreReview();
+                    }
+                    const storeUrl = campaign.storeUrl ?? ratingRouting?.storeUrl;
+                    if (ratingRouting?.onHighRating) {
+                        ratingRouting.onHighRating({ rating, campaign, storeUrl });
+                        redirected = true;
+                    } else if (!redirected && storeUrl) {
+                        redirected = await Linking.openURL(storeUrl).then(() => true).catch(() => false);
+                    }
+                    if (redirected) emitRatingFunnel(campaign, 'store_redirect_clicked');
+                } else if (result.route === 'feedback') {
+                    ratingRouting?.onLowRating?.({ rating, campaign });
+                }
+            } else {
+                // [v2] response context (contract §1): session linkage + originating
+                // screen + platform + app version. All optional; omitted when unresolved.
+                // We send ONLY the new response fact + the sessionId; replay/errors/network
+                // are NOT re-sent — the read side joins them by sessionId.
+                const input: EngageResponseInput = Array.isArray(result.answers)
+                    ? {
+                          surveyId: campaign.id,
+                          text: result.reason,
+                          answers: toWireAnswers(result.answers),
+                          deviceId: getDeviceId(),
+                          sessionId: currentSessionId(),
+                          screen: activeScreenRef.current,
+                          platform: currentPlatform(),
+                          appVersion: currentAppVersion(),
+                      }
+                    : {
+                          surveyId: campaign.id,
+                          score: result.score,
+                          text: result.reason,
+                          tags: result.tags,
+                          deviceId: getDeviceId(),
+                          sessionId: currentSessionId(),
+                          screen: activeScreenRef.current,
+                          platform: currentPlatform(),
+                          appVersion: currentAppVersion(),
+                      };
+
+                const drafts = result.attachments ?? [];
+                if (engage.submitResponseConfirmed) {
+                    // Confirmed lane: awaits real persistence (presign+PUT bytes → response
+                    // POST), reports stages, idempotent on responseId, throws on failure.
+                    await engage.submitResponseConfirmed(input, drafts, {
+                        responseId,
+                        onStage: (stage) => setSubmitStatus({ phase: 'submitting', stage }),
+                    });
+                } else if (drafts.length > 0 && engage.submitResponseWithAttachments) {
+                    // Fallback (older facade): fire-and-forget — resolves immediately.
+                    engage.submitResponseWithAttachments(input, drafts);
+                } else {
+                    engage.submitResponse(input);
+                }
+            }
+
+            store?.markCompleted(campaign.id);
+            trackCampaign(campaign, 'completion');
+            setSubmitStatus({ phase: 'success' });
+            // Brief success beat, then close + reset.
+            successTimerRef.current = setTimeout(() => {
+                setActive(null);
+                activeScreenRef.current = undefined;
+                resetSubmit();
+            }, 1100);
+        } catch (err) {
+            logger.warn('[Engage] submit failed:', (err as Error)?.message);
+            setSubmitStatus({ phase: 'error', message: (err as Error)?.message });
+        }
+    }, [engage, trackCampaign, ratingRouting, resetSubmit, emitRatingFunnel]);
+
+    const handleSubmit = useCallback(
+        (campaign: EngageCampaignConfig, result: EngagePromptResult): void => {
+            // Guard double-submit: ignore re-fires once a submit is in flight or done.
+            if (submitCtxRef.current && responseIdRef.current) return;
+            submitCtxRef.current = { campaign, result };
+            void runSubmit();
+        },
+        [runSubmit],
+    );
+
+    const closeAfterSubmit = useCallback((): void => {
+        setActive(null);
+        activeScreenRef.current = undefined;
+        resetSubmit();
+    }, [resetSubmit]);
+
+    const showEngagePrompt = useCallback(
+        async (options?: ShowEngagePromptOptions): Promise<boolean> => {
+            const store = storeRef.current;
+            if (!store) return false;
+            try {
+                const config = await engage.fetchConfig(options?.context);
+                if (!config || !Array.isArray(config.campaigns)) return false;
+
+                const campaign = selectCampaignToRender(config.campaigns, store, {
+                    // A behavioral-trigger fire (`options.trigger`) is type-agnostic:
+                    // the trigger itself selects the campaign, so don't layer the
+                    // NPS-first default on top (it would drop FEEDBACK/CSAT/etc.).
+                    // Manual fires keep the provider default unless overridden.
+                    types: options?.types ?? (options?.trigger ? undefined : types),
+                    screen: options?.screen,
+                    trigger: options?.trigger,
+                    seconds: options?.seconds,
+                    event: options?.event,
+                    action: options?.action,
+                });
+                if (!campaign) {
+                    logger.debug('[Engage] no eligible campaign to render');
+                    return false;
+                }
+
+                // Record the impression up front so throttle counts it even if the
+                // user backgrounds the app before submitting.
+                store.recordImpression(campaign.id);
+                // Emit the §2.5 impression event (P3-e #2) so the dashboard's
+                // response-rate / completion KPIs have a real denominator — the
+                // prompt path previously only counted impressions locally.
+                trackCampaign(campaign, 'impression');
+                // Rating funnel (CONTRACT §1.1): selection passed the throttle/anti-
+                // annoyance gate (→ eligible) and we are about to render (→ shown).
+                if (isRatingType(campaign.type)) {
+                    emitRatingFunnel(campaign, 'rating_prompt_eligible');
+                    emitRatingFunnel(campaign, 'rating_prompt_shown');
+                }
+                // Stamp the show-time screen alongside the active campaign so
+                // handleSubmit can attribute the response to its originating screen.
+                activeScreenRef.current = options?.screen;
+                surveyStartedRef.current = null;
+                trackSurveyStage(campaign, 'shown');
+                resetSubmit();
+                setActive(campaign);
+                return true;
+            } catch (err) {
+                logger.warn('[Engage] showEngagePrompt failed:', (err as Error)?.message);
+                return false;
+            }
+        },
+        [engage, types, trackCampaign, trackSurveyStage, emitRatingFunnel],
+    );
+
+    // ─── In-app message lifecycle (the second Engage family, §2.4/§2.5) ──────
+    // Reuses the SAME transport (`trackEvent`), the SAME throttle store, and the
+    // SAME provider — NOT a parallel provider. Events: impression on show, click
+    // on CTA tap, completion on a finished tour, dismiss on close/skip.
+
+    const trackInApp = useCallback(
+        (
+            message: InAppMessageConfig,
+            eventType:
+                | 'impression'
+                | 'completion'
+                | 'click'
+                | 'dismiss'
+                | 'interaction'
+                | 'render_degraded'
+                | 'render_failed'
+                | 'cta_open_failed',
+            extraMeta?: Record<string, unknown>,
+        ): void => {
+            try {
+                // A/B attribution (D8/J6): when the active message resolved to an
+                // experiment arm, tag every lifecycle event with the chosen variant
+                // via the existing optional `meta` field — NO event-schema change
+                // (EngageEventUpload already carries `meta`; the backend EngageEvent
+                // accepts it). Plain (non-experiment) messages send no variant key.
+                const variant = activeInAppVariantRef.current?.variant;
+                // [T1] Test-preview tagging: a preview-flagged message stamps
+                // `previewId` + `isTest` + `source` so (a) the backend CONSUMES the
+                // matching preview row on the impression and (b) production KPIs
+                // exclude the traffic. Normal campaign messages omit all of it.
+                const isPreview = message.preview === true || message.isTest === true;
+                const meta = {
+                    ...(variant ? { variant } : {}),
+                    // testRunId correlates a specific "Send Test" run to its render/click/
+                    // dismiss in the dashboard; rides the existing meta field (no schema churn).
+                    ...(message.testRunId ? { testRunId: message.testRunId } : {}),
+                    ...(extraMeta ?? {}),
+                };
+                engage.trackEvent({
+                    campaignId: message.id,
+                    channel: 'inapp',
+                    type: eventType,
+                    deviceId: getDeviceId(),
+                    ...(message.previewId ? { previewId: message.previewId } : {}),
+                    ...(isPreview ? { isTest: true, source: 'test_preview' } : {}),
+                    ...(variant ? { variantId: variant } : {}),
+                    ...(Object.keys(meta).length > 0 ? { meta } : {}),
+                });
+            } catch (err) {
+                logger.debug('[Engage] in-app trackEvent failed:', (err as Error)?.message);
+            }
+        },
+        [engage],
+    );
+
+    // [T1] In-app message actually mounted on screen. The impression event IS the test
+    // ACK to the backend (which consumes the preview row → 'rendered'). We ALSO persist the
+    // testRunId locally so a cold restart can't re-show it before the ACK is processed
+    // server-side — the one-shot guarantee survives a flaky/slow network.
+    const handleInAppShow = useCallback(
+        (message: InAppMessageConfig): void => {
+            // A slot can be replaced or degrade to an overlay while the same message
+            // remains active. Treat that as one mount lifecycle, not two impressions.
+            if (shownInAppMessageIdRef.current === message.id) return;
+            shownInAppMessageIdRef.current = message.id;
+            trackInApp(message, 'impression');
+            if (message.preview === true || message.isTest === true) {
+                const runId = message.testRunId ?? message.previewId ?? message.id;
+                seenTestsRef.current?.markSeen(runId);
+                // Eager-flush so the backend consumes the one-shot preview row NOW — a fast
+                // close→kill→reopen must not re-serve a still-`delivered` test.
+                engage.flushEvents?.();
+                logger.debug(`[Engage] test ${runId} render displayed — ACK sent (impression), flushed`);
+            }
+        },
+        [trackInApp, engage],
+    );
+
+    const finalizeInAppMessage = useCallback((eventType: 'dismiss' | 'completion'): void => {
+        setActiveInApp((current) => {
+            if (current) {
+                const isTest = current.preview === true || current.isTest === true;
+                const runId = current.testRunId ?? current.previewId ?? current.id;
+                logger.debug(`[Engage] in-app ${eventType}${isTest ? ` (test ${runId})` : ''}`);
+                trackInApp(current, eventType);
+                if (isTest) {
+                    consumedPreviewIds.current.add(current.previewId ?? current.id);
+                    seenTestsRef.current?.markSeen(runId);
+                    engage.flushEvents?.();
+                    logger.debug(`[Engage] test ${runId} ${eventType} persisted + ACK flushed`);
+                } else {
+                    storeRef.current?.markCompleted(current.id);
+                    engage.flushEvents?.();
+                    logger.debug(`[Engage] in-app ${current.id} ${eventType} — marked done on device`);
+                }
+            }
+            return null;
+        });
+        // Clear the resolved A/B arm after the lifecycle event has read it.
+        shownInAppMessageIdRef.current = null;
+        activeInAppVariantRef.current = null;
+    }, [trackInApp, engage]);
+
+    const dismissInAppMessage = useCallback((): void => {
+        finalizeInAppMessage('dismiss');
+    }, [finalizeInAppMessage]);
+
+    const completeInAppMessage = useCallback((): void => {
+        finalizeInAppMessage('completion');
+    }, [finalizeInAppMessage]);
+
+    const handleInAppCta = useCallback(
+        (message: InAppMessageConfig, cta: NonNullable<InAppRenderSpec['cta']>): void => {
+            if (shouldTrackInAppCta(cta)) trackInApp(message, 'click');
+            // Deep-link opening is the host's job — surface it, never open it here.
+            if (cta.action === 'link') {
+                if (!cta.deepLink) {
+                    // Misconfigured link CTA (no deepLink) — observable, not silent (T1 G17).
+                    logger.warn('[Engage] link CTA has no deepLink');
+                    trackInApp(message, 'cta_open_failed', { reason: 'missing_deeplink' });
+                } else if (!onInAppDeepLink) {
+                    // Host wired no deep-link sink — the link can't open. Diagnose it.
+                    logger.warn('[Engage] link CTA but no onInAppDeepLink handler supplied');
+                    trackInApp(message, 'cta_open_failed', { reason: 'no_handler' });
+                } else {
+                    try {
+                        onInAppDeepLink({ message, cta, deepLink: cta.deepLink });
+                    } catch (err) {
+                        logger.warn('[Engage] onInAppDeepLink threw:', (err as Error)?.message);
+                        trackInApp(message, 'cta_open_failed', {
+                            reason: (err as Error)?.message ?? 'handler_threw',
+                        });
+                    }
+                }
+            }
+            // A test preview the user acted on is done — don't re-show it next poll AND
+            // persist it durably (a CTA tap is as final as a close), then flush the ACK.
+            if (message.preview === true || message.isTest === true) {
+                const runId = message.testRunId ?? message.previewId ?? message.id;
+                consumedPreviewIds.current.add(message.previewId ?? message.id);
+                seenTestsRef.current?.markSeen(runId);
+                engage.flushEvents?.();
+                logger.debug(`[Engage] test ${runId} CTA — persisted locally + ACK flushed`);
+            } else {
+                // Production message: a CTA tap is as final as a close — don't re-show it.
+                storeRef.current?.markCompleted(message.id);
+                engage.flushEvents?.();
+                logger.debug(`[Engage] in-app ${message.id} CTA tapped — marked done on device`);
+            }
+            setActiveInApp(null);
+            // Any enabled click event above already read the arm; clear it now.
+            shownInAppMessageIdRef.current = null;
+            activeInAppVariantRef.current = null;
+        },
+        [trackInApp, onInAppDeepLink, engage],
+    );
+
+    // [T1] Pick the ONE test preview to render from a fetched config: drop any already
+    // displayed (persistent seen store) or closed-this-session, then take the LATEST by
+    // createdAt. One-shot + latest-only is what stops the "tests stack up 1,2,3…" bug.
+    const pickLatestPreview = useCallback(
+        (messages: InAppMessageConfig[]): InAppMessageConfig | null => {
+            const latest = selectLatestUnseenTest(messages, {
+                seen: (runId) => seenTestsRef.current?.has(runId) ?? false,
+                consumed: (key) => consumedPreviewIds.current.has(key),
+            });
+            if (latest) logger.debug(`[Engage] selected latest test ${testRunIdOf(latest)}`);
+            return latest;
+        },
+        [],
+    );
+
+    // [T1] Render a test preview IMMEDIATELY — bypassing trigger/throttle/schedule/
+    // sample/variant. No throttle write (a preview must stay re-showable until it is
+    // actually rendered + its impression consumes it server-side). Idempotent: if this
+    // exact preview is already on screen, don't re-mount (avoids a duplicate impression).
+    const showPreview = useCallback(
+        (preview: InAppMessageConfig): boolean => {
+            // PRECEDENCE: a campaign prompt owns the screen — defer (the backend re-serves
+            // the preview on every poll until TTL, so the next foreground retries).
+            if (active !== null) {
+                logger.debug('[Engage] campaign prompt active — preview deferred');
+                return false;
+            }
+            if (activeInApp?.id === preview.id) return true;
+            const runId = preview.testRunId ?? preview.previewId ?? preview.id;
+            // Already closed this preview this session — don't re-show on the next poll.
+            if (consumedPreviewIds.current.has(preview.previewId ?? preview.id)) {
+                return false;
+            }
+            // [T1] One-shot: already DISPLAYED on this device (persisted across restarts) —
+            // never re-show, even if the backend briefly re-serves a not-yet-ACKed row.
+            if (seenTestsRef.current?.has(runId)) {
+                logger.debug(`[Engage] test ${runId} already displayed on device — skip`);
+                return false;
+            }
+            activeInAppVariantRef.current = null;
+            setActiveInApp(preview);
+            logger.debug(`[Engage] test ${runId} render started`);
+            return true;
+        },
+        [active, activeInApp],
+    );
+
+    const showInAppMessage = useCallback(
+        async (options?: ShowInAppMessageOptions): Promise<boolean> => {
+            const store = storeRef.current;
+            if (!store) return false;
+            // PRECEDENCE: a campaign prompt on screen wins — never stack an in-app
+            // message over an open survey/NPS/rating prompt.
+            if (active !== null) {
+                logger.debug('[Engage] campaign prompt active — in-app message deferred');
+                return false;
+            }
+            try {
+                const config = await engage.fetchConfig(buildConfigContext(engage, options?.context));
+                if (!config || !Array.isArray(config.inAppMessages)) return false;
+
+                // [T1] A queued test preview wins immediately, bypassing throttle/variant.
+                // Pick the LATEST unseen one (one-shot dedupe) — never stack old tests.
+                const preview = pickLatestPreview(config.inAppMessages);
+                if (preview) return showPreview(preview);
+
+                // Normal selection runs over NON-preview messages only — a preview must
+                // never enter the throttle store (it would falsely cap a real campaign id).
+                const normal = config.inAppMessages.filter(
+                    (m) => !(m.preview === true || m.isTest === true),
+                );
+                const message = selectInAppToRender(normal, store, {
+                    screen: options?.screen,
+                    trigger: options?.trigger,
+                    seconds: options?.seconds,
+                    event: options?.event,
+                    action: options?.action,
+                });
+                if (!message) {
+                    logger.debug('[Engage] no eligible in-app message to render');
+                    return false;
+                }
+
+                // A/B variant selection (D8/J6): deterministically bucket this
+                // device into arm A (base spec) or B (experiment.variantB) BEFORE
+                // showing, so the impression event (and click/dismiss) attribute to
+                // the arm the user actually saw. Only retained for attribution when
+                // the message actually carries an enabled experiment; otherwise the
+                // resolved spec is just the base spec and no variant key is emitted.
+                const resolved = selectInAppVariant(message, getDeviceId());
+                activeInAppVariantRef.current = message.experiment?.enabled
+                    ? resolved
+                    : null;
+                // Record up front so the throttle counts it (impression also emitted
+                // by the view's onShow → trackEvent for the analytics lane). Pass the
+                // content revision so an edited campaign starts a fresh cap generation.
+                store.recordImpression(message.id, Date.now(), message.revision);
+                setActiveInApp(message);
+                return true;
+            } catch (err) {
+                logger.warn('[Engage] showInAppMessage failed:', (err as Error)?.message);
+                return false;
+            }
+        },
+        [engage, active, showPreview, pickLatestPreview],
+    );
+
+    // ─── Cold-start + foreground preview check (T1) ──────────────────────────
+    // "Send Test → reopen the app → see it immediately, EVERY time": the SDK fetches
+    // config (deviceId in context, HTTP cache-bypassed) on mount AND on every
+    // AppState→active, and renders any queued preview at once — no trigger, no throttle,
+    // no schedule. The backend keeps serving the preview on every poll until its TTL, so
+    // a tester sees it on each reopen (rendering records lifecycle but does not consume).
+    const checkForPreview = useCallback(async (): Promise<void> => {
+        if (active !== null) return;
+        try {
+            const config = await engage.fetchConfig(buildConfigContext(engage));
+            // One-shot + latest-only: render the newest test not already displayed.
+            const preview = pickLatestPreview(config?.inAppMessages ?? []);
+            if (preview) showPreview(preview);
+        } catch (err) {
+            logger.warn('[Engage] preview check failed:', (err as Error)?.message);
+        }
+    }, [engage, active, showPreview, pickLatestPreview]);
+
+    useEffect(() => {
+        // Drop stale seen-test entries (past TTL) so the persistent set stays bounded.
+        seenTestsRef.current?.prune();
+        void checkForPreview();
+        const onLifecycle = (state: string): void => {
+            if (state === 'active') void checkForPreview();
+        };
+        appLifecycle.addListener(onLifecycle);
+        return () => appLifecycle.removeListener(onLifecycle);
+    }, [checkForPreview]);
+
+    // DEV/TEST warm-foreground poll (T1): covers "Send Test while the app is already
+    // open" — no background→foreground edge fires, so without this you'd have to switch
+    // apps to see it. Only runs when the host opts in via `previewPollMs` (unset in prod).
+    useEffect(() => {
+        if (!previewPollMs || previewPollMs <= 0) return;
+        logger.debug(`[Engage] test-preview warm poll every ${previewPollMs}ms (dev)`);
+        const interval = setInterval(() => {
+            void checkForPreview();
+        }, previewPollMs);
+        return () => clearInterval(interval);
+    }, [previewPollMs, checkForPreview]);
+
+    // ─── Always-on behavioral triggers (P3-e #3 / Slice E) ───────────────────
+    // The trigger engine wires every behavioral trigger (session_start, app_open,
+    // screen_view/exit, time_in_app, n_sessions, after_purchase, before_logout,
+    // custom_event, failed_action, after_crash/js_error, network_error, slow_screen,
+    // and the native gesture triggers) to the SDK signals the app already produces.
+    // A fire first tries the survey/rating campaign path (showEngagePrompt); if no
+    // campaign matches, the SAME trigger drives an in-app message (showInAppMessage).
+    // Both families share the throttle store, so a behavioral fire never double-shows.
+    // The engine buffers events fired before the first config arrives and replays
+    // them once it does (late binding), honoring each trigger's remaining delay.
+    useEffect(() => {
+        return installEngageTriggerEngine({
+            fire: (options) => {
+                void (async () => {
+                    const shown = await showEngagePrompt(options);
+                    if (!shown && options.trigger) {
+                        await showInAppMessage({
+                            trigger: options.trigger,
+                            screen: options.screen,
+                            event: options.event,
+                            action: options.action,
+                            seconds: options.seconds,
+                        });
+                    }
+                })();
+            },
+            fetchConfig: () => engage.fetchConfig(buildConfigContext(engage)),
+        });
+    }, [showEngagePrompt, showInAppMessage, engage]);
+
+    const controller = useMemo<EngagePromptController>(
+        () => ({
+            showEngagePrompt,
+            dismissEngagePrompt,
+            showInAppMessage,
+            dismissInAppMessage,
+        }),
+        [showEngagePrompt, dismissEngagePrompt, showInAppMessage, dismissInAppMessage],
+    );
+
+    const activeInAppSpec = activeInAppVariantRef.current?.spec ?? activeInApp?.spec;
+    const activeInAppPresentation = activeInApp && activeInAppSpec
+        ? resolveInAppPresentation({
+              layout: activeInApp.layout,
+              variantKey: activeInApp.variantKey,
+              spec: activeInAppSpec,
+          })
+        : null;
+    // Route by the canonical mount, not a variant allow-list. This covers every
+    // current/future inline variant, including smart_inbox_message.
+    const routesToInlineSlot = activeInAppPresentation?.mountModel === 'inline';
+    const inlinePlacement = resolveEngageInlinePlacement(activeInAppSpec);
+
+    const handleActiveInAppShow = useCallback((): void => {
+        if (!activeInApp) return;
+        handleInAppShow(activeInApp);
+        const tourId = activeInApp.spec.ext?.coachTourId;
+        const first = Array.isArray(activeInApp.spec.ext?.steps) ? activeInApp.spec.ext?.steps[0] as Record<string, unknown> | undefined : undefined;
+        if (typeof tourId === 'string') {
+            engage.trackCoachmarkEvent?.('$coachmark_tour_started', { tourId });
+            engage.trackCoachmarkEvent?.('$coachmark_step_entered', {
+                tourId,
+                stepId: String(first?.id ?? first?.anchorKey ?? '1'),
+            });
+        }
+    }, [activeInApp, handleInAppShow, engage]);
+    const handleActiveInAppCta = useCallback((cta: NonNullable<InAppRenderSpec['cta']>): void => {
+        if (activeInApp) handleInAppCta(activeInApp, cta);
+    }, [activeInApp, handleInAppCta]);
+    const handleActiveInAppInteraction = useCallback((interaction: InAppMechanicInteraction): void => {
+        if (!activeInApp) return;
+        trackInApp(activeInApp, 'interaction', { interaction });
+        const tourId = activeInApp.spec.ext?.coachTourId;
+        if (typeof tourId !== 'string' || interaction.mechanic !== 'coachmark_spotlight') return;
+        const meta = interaction.meta ?? {};
+        const stepId = String(meta.anchorKey ?? meta.step ?? meta.toStep ?? 'unknown');
+        if (interaction.result === 'step_viewed' && interaction.phase !== 'started') {
+            engage.trackCoachmarkEvent?.('$coachmark_step_entered', { tourId, stepId });
+        } else if (interaction.phase === 'completed') {
+            engage.trackCoachmarkEvent?.('$coachmark_tour_completed', { tourId, stepId });
+        } else if (interaction.result === 'skipped') {
+            engage.trackCoachmarkEvent?.('$coachmark_tour_abandoned', { tourId, stepId });
+        }
+    }, [activeInApp, trackInApp, engage]);
+    const handleActiveInAppRenderError = useCallback((reason: string): void => {
+        if (activeInApp) {
+            trackInApp(activeInApp, 'render_failed', { reason });
+            const tourId = activeInApp.spec.ext?.coachTourId;
+            if (typeof tourId === 'string') {
+                const anchorKey = reason.startsWith('anchor_not_found:') ? reason.slice('anchor_not_found:'.length) : 'unknown';
+                engage.trackCoachmarkEvent?.('$coachmark_anchor_failed', {
+                    tourId,
+                    stepId: anchorKey,
+                    reason: reason.startsWith('anchor_not_found:') ? 'anchor_not_found' : reason,
+                });
+            }
+        }
+        shownInAppMessageIdRef.current = null;
+        activeInAppVariantRef.current = null;
+        setActiveInApp(null);
+    }, [activeInApp, trackInApp, engage]);
+
+    useEffect(() => {
+        if (!routesToInlineSlot || !inlinePlacement.placementKey) return;
+        return inlinePlacementRegistry.subscribe(inlinePlacement.placementKey, () => {
+            setInlinePlacementRevision((revision) => revision + 1);
+        });
+    }, [inlinePlacement.placementKey, inlinePlacementRegistry, routesToInlineSlot]);
+
+    useEffect(() => {
+        if (!activeInApp || active !== null || !routesToInlineSlot) {
+            setInlineFallbackMessageId(null);
+            return;
+        }
+
+        const messageId = activeInApp.id;
+        // Once this message has visibly degraded, keep it on that mount. Moving it
+        // into a late slot would create a second renderer and a misleading lifecycle.
+        if (inlineFallbackMessageId === messageId) return;
+        const reason = inlinePlacement.placementKey
+            ? `inline_placement_not_found:${inlinePlacement.placementKey}`
+            : 'missing_inline_placement_key';
+        const delivery: EngageInlineDelivery = {
+            message: activeInApp,
+            spec: activeInAppSpec,
+            onShow: handleActiveInAppShow,
+            onCta: handleActiveInAppCta,
+            onDismiss: dismissInAppMessage,
+            onComplete: completeInAppMessage,
+            onInteraction: handleActiveInAppInteraction,
+            onInAppGameRequest,
+            onRenderError: handleActiveInAppRenderError,
+        };
+        const delivered = inlinePlacementRegistry.deliver(
+            inlinePlacement.placementKey,
+            delivery,
+        );
+
+        if (delivered) {
+            setInlineFallbackMessageId(null);
+        } else {
+            inlinePlacementRegistry.clear(inlinePlacement.placementKey, messageId);
+            if (inlinePlacement.fallback === 'skip') {
+                setInlineFallbackMessageId(null);
+                handleActiveInAppRenderError(reason);
+            } else {
+                // Preserve the legacy visible behavior, but make the degradation observable.
+                trackInApp(activeInApp, 'render_degraded', {
+                    reason,
+                    placementKey: inlinePlacement.placementKey,
+                    fallback: 'overlay',
+                });
+                setInlineFallbackMessageId(messageId);
+            }
+        }
+
+        return () => inlinePlacementRegistry.clear(inlinePlacement.placementKey, messageId);
+    }, [
+        active,
+        activeInApp,
+        activeInAppSpec,
+        dismissInAppMessage,
+        completeInAppMessage,
+        handleActiveInAppCta,
+        handleActiveInAppInteraction,
+        handleActiveInAppRenderError,
+        handleActiveInAppShow,
+        inlinePlacement.fallback,
+        inlinePlacement.placementKey,
+        inlinePlacementRegistry,
+        inlineFallbackMessageId,
+        inlinePlacementRevision,
+        onInAppGameRequest,
+        routesToInlineSlot,
+        trackInApp,
+    ]);
+
+    const rootInAppVisible = activeInApp !== null &&
+        active === null &&
+        (!routesToInlineSlot || inlineFallbackMessageId === activeInApp.id);
+
+    return (
+        <EngageAnchorProvider>
+            <EngageInlinePlacementProvider registry={inlinePlacementRegistry}>
+                <EngagePromptContext.Provider value={controller}>
+            {children}
+            <EngagePromptView
+                campaign={active}
+                visible={active !== null}
+                rating={ratingRouting}
+                submitStatus={submitStatus}
+                onRetrySubmit={() => void runSubmit()}
+                onCloseSubmit={closeAfterSubmit}
+                onSubmit={(result) => {
+                    if (active) handleSubmit(active, result);
+                }}
+                onStart={() => {
+                    if (active && surveyStartedRef.current !== active.id) {
+                        surveyStartedRef.current = active.id;
+                        trackSurveyStage(active, 'started');
+                    }
+                }}
+                onDismiss={dismissEngagePrompt}
+            />
+            {/* In-app message overlay. PRECEDENCE: only visible when no campaign
+                prompt is on screen, so the two families never fight for the view. */}
+            <EngageInAppView
+                message={activeInApp}
+                visible={rootInAppVisible}
+                mountModelOverride={routesToInlineSlot && inlineFallbackMessageId === activeInApp?.id
+                    ? 'overlay'
+                    : undefined}
+                // Render the resolved A/B arm's content (D8/J6) when an experiment is
+                // active; undefined ⇒ the view falls back to the message's base spec.
+                spec={activeInAppVariantRef.current?.spec}
+                onShow={handleActiveInAppShow}
+                onCta={handleActiveInAppCta}
+                onDismiss={dismissInAppMessage}
+                onComplete={completeInAppMessage}
+                onInteraction={handleActiveInAppInteraction}
+                onInAppGameRequest={onInAppGameRequest}
+                onRenderError={handleActiveInAppRenderError}
+            />
+                </EngagePromptContext.Provider>
+            </EngageInlinePlacementProvider>
+        </EngageAnchorProvider>
+    );
+}
+
+/**
+ * Hook a host app uses to trigger/dismiss the prompt:
+ *   const { showEngagePrompt } = useEngagePrompt();
+ *   showEngagePrompt({ types: ['NPS'] });
+ */
+export function useEngagePrompt(): EngagePromptController {
+    const ctx = useContext(EngagePromptContext);
+    if (!ctx) {
+        // Fail-soft: a host that calls the hook outside the provider gets no-ops
+        // instead of a crash (matches the SDK's no-throw public-API style).
+        return {
+            showEngagePrompt: async () => {
+                logger.warn('[Engage] useEngagePrompt() called outside <EngagePromptProvider>');
+                return false;
+            },
+            dismissEngagePrompt: () => {},
+            showInAppMessage: async () => {
+                logger.warn('[Engage] useEngagePrompt() called outside <EngagePromptProvider>');
+                return false;
+            },
+            dismissInAppMessage: () => {},
+        };
+    }
+    return ctx;
+}