@scalebun-release/react-native 2.5.0

package/lib/module/features/engage/EngagePromptProvider.js

@@ -0,0 +1,1054 @@
+/**
+ * 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 } 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 } from './EngagePromptView';
+import { EngageInAppView } from './EngageInAppView';
+import { EngageAnchorProvider } from './EngageAnchor';
+import { EngageInlinePlacementProvider, createEngageInlinePlacementRegistry, resolveEngageInlinePlacement } from './EngageInlinePlacement';
+import { resolveInAppPresentation } from './engageVariantResolver';
+import { shouldTrackInAppCta } from './engageOutcome';
+import { EngageThrottleStore, selectCampaignToRender, selectInAppToRender, selectInAppVariant, selectLatestUnseenTest, testRunIdOf } from './engageThrottle';
+import { EngageTestSeenStore } from './engageTestSeenStore';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Client-generated UUID for app-rating idempotency (D8: `clientRatingId`). */
+function ratingUuid() {
+  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) {
+  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() {
+  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() {
+  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() {
+  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, override) {
+  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() {
+  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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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`.
+ */
+
+/** Imperative controller a host app uses to trigger a prompt / in-app message. */
+
+const EngagePromptContext = /*#__PURE__*/createContext(null);
+const DEFAULT_TYPES = ['NPS'];
+
+/**
+ * Provider that mounts the shared overlay and exposes the imperative controller
+ * via `useEngagePrompt()`.
+ */
+export function EngagePromptProvider({
+  engage,
+  defaultTypes,
+  ratingRouting,
+  onInAppDeepLink,
+  onInAppGameRequest,
+  previewPollMs,
+  children
+}) {
+  const [active, setActive] = useState(null);
+  const [activeInApp, setActiveInApp] = useState(null);
+  const [inlineFallbackMessageId, setInlineFallbackMessageId] = useState(null);
+  const [inlinePlacementRevision, setInlinePlacementRevision] = useState(0);
+  const inlinePlacementRegistry = useMemo(createEngageInlinePlacementRegistry, []);
+  const shownInAppMessageIdRef = useRef(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(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(undefined);
+  const surveyStartedRef = useRef(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(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(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(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({
+    phase: 'idle'
+  });
+  const responseIdRef = useRef(null);
+  const submitCtxRef = useRef(null);
+  const successTimerRef = useRef(null);
+  const resetSubmit = useCallback(() => {
+    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, eventType) => {
+    try {
+      engage.trackEvent({
+        campaignId: campaign.id,
+        channel: 'inapp',
+        type: eventType,
+        deviceId: getDeviceId()
+      });
+    } catch (err) {
+      __DEV__ && logger.debug('[Engage] trackEvent failed:', err?.message);
+    }
+  }, [engage]);
+  const trackSurveyStage = useCallback((campaign, stage) => {
+    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) {
+      __DEV__ && logger.debug('[Engage] survey impression failed:', err?.message);
+    }
+  }, [engage]);
+  const isRatingType = type => 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, type, extra) => {
+    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) {
+      __DEV__ && logger.debug('[Engage] emitRatingEvent failed:', err?.message);
+    }
+  }, [engage]);
+  const dismissEngagePrompt = useCallback(() => {
+    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 () => {
+    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 = 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 ?? [];
+
+        /**
+         * Bug-report lane — opt in per campaign via `fileAsBugReport`.
+         *
+         * A FEEDBACK campaign fired by `shake_device` is almost always "something is
+         * broken", not "how do you feel", and those are different products: a bug report
+         * gets a status, a priority and an assignee on /diagnose/bug-reports, while a survey
+         * response is counted in aggregate and cannot be triaged.
+         *
+         * Routed INSTEAD of submitResponse rather than in addition — a dual write would
+         * create two rows for one submission and double-count the campaign on the Engage
+         * side.
+         *
+         * `responseId` doubles as the idempotency key so a retried submit cannot file the
+         * same report twice (BugReport.clientReportId is @unique).
+         *
+         * Falls through to the normal lane when the host facade predates `reportBugDetailed`
+         * — an older app bundling a newer config degrades to existing behaviour instead of
+         * dropping the user's report on the floor.
+         */
+        const bugLane = campaign.fileAsBugReport && typeof engage.reportBugDetailed === 'function' ? engage.reportBugDetailed : null;
+        if (bugLane) {
+          const outcome = await bugLane({
+            message: result.reason ?? '',
+            title: campaign.name,
+            clientReportId: responseId
+          });
+          // Surface a refusal as a throw so the existing retry/error UI handles it; a
+          // silent success here would tell the user their report was filed when it wasn't.
+          if (outcome && typeof outcome === 'object' && 'e' in outcome) {
+            throw new Error(`bug report failed: ${outcome.e}`);
+          }
+        } else 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?.message);
+      setSubmitStatus({
+        phase: 'error',
+        message: err?.message
+      });
+    }
+  }, [engage, trackCampaign, ratingRouting, resetSubmit, emitRatingFunnel]);
+  const handleSubmit = useCallback((campaign, result) => {
+    // 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(() => {
+    setActive(null);
+    activeScreenRef.current = undefined;
+    resetSubmit();
+  }, [resetSubmit]);
+  const showEngagePrompt = useCallback(async options => {
+    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) {
+        // Name the inputs so a silent mismatch (wrong trigger name, throttle
+        // suppression, type filter) is diagnosable from device logs alone.
+        __DEV__ && logger.debug(`[Engage] no eligible campaign to render (trigger=${options?.trigger ?? '—'} ` + `candidates=${config.campaigns.length} ` + `[${config.campaigns.map(c => `${c.type}:${c.trigger ?? '—'}`).join(', ')}])`);
+        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?.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, eventType, extraMeta) => {
+    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) {
+      __DEV__ && logger.debug('[Engage] in-app trackEvent failed:', err?.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 => {
+    // 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?.();
+      __DEV__ && logger.debug(`[Engage] test ${runId} render displayed — ACK sent (impression), flushed`);
+    }
+  }, [trackInApp, engage]);
+  const finalizeInAppMessage = useCallback(eventType => {
+    setActiveInApp(current => {
+      if (current) {
+        const isTest = current.preview === true || current.isTest === true;
+        const runId = current.testRunId ?? current.previewId ?? current.id;
+        __DEV__ && 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?.();
+          __DEV__ && logger.debug(`[Engage] test ${runId} ${eventType} persisted + ACK flushed`);
+        } else {
+          // Stamp the SERVED revision: without it the completion can never be invalidated,
+          // and an edited campaign would never return to a device that closed the old one.
+          storeRef.current?.markCompleted(current.id, Date.now(), current.revision);
+          engage.flushEvents?.();
+          __DEV__ && 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(() => {
+    finalizeInAppMessage('dismiss');
+  }, [finalizeInAppMessage]);
+  const completeInAppMessage = useCallback(() => {
+    finalizeInAppMessage('completion');
+  }, [finalizeInAppMessage]);
+  const handleInAppCta = useCallback((message, cta) => {
+    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?.message);
+          trackInApp(message, 'cta_open_failed', {
+            reason: err?.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?.();
+      __DEV__ && 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, Date.now(), message.revision);
+      engage.flushEvents?.();
+      __DEV__ && 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 => {
+    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 => {
+    // 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) {
+      __DEV__ && 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)) {
+      __DEV__ && logger.debug(`[Engage] test ${runId} already displayed on device — skip`);
+      return false;
+    }
+    activeInAppVariantRef.current = null;
+    setActiveInApp(preview);
+    __DEV__ && logger.debug(`[Engage] test ${runId} render started`);
+    return true;
+  }, [active, activeInApp]);
+  const showInAppMessage = useCallback(async options => {
+    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) {
+      __DEV__ && 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) {
+        __DEV__ && 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?.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 () => {
+    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?.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 => {
+      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;
+    __DEV__ && 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(() => ({
+    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(() => {
+    if (!activeInApp) return;
+    handleInAppShow(activeInApp);
+    const tourId = activeInApp.spec.ext?.coachTourId;
+    const first = Array.isArray(activeInApp.spec.ext?.steps) ? activeInApp.spec.ext?.steps[0] : 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 => {
+    if (activeInApp) handleInAppCta(activeInApp, cta);
+  }, [activeInApp, handleInAppCta]);
+  const handleActiveInAppInteraction = useCallback(interaction => {
+    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 => {
+    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 = {
+      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 /*#__PURE__*/_jsx(EngageAnchorProvider, {
+    children: /*#__PURE__*/_jsx(EngageInlinePlacementProvider, {
+      registry: inlinePlacementRegistry,
+      children: /*#__PURE__*/_jsxs(EngagePromptContext.Provider, {
+        value: controller,
+        children: [children, /*#__PURE__*/_jsx(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
+        }), /*#__PURE__*/_jsx(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
+        })]
+      })
+    })
+  });
+}
+
+/**
+ * Hook a host app uses to trigger/dismiss the prompt:
+ *   const { showEngagePrompt } = useEngagePrompt();
+ *   showEngagePrompt({ types: ['NPS'] });
+ */
+export function useEngagePrompt() {
+  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;
+}
+//# sourceMappingURL=EngagePromptProvider.js.map