@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,360 @@
+import { logger } from '../../core/logger/internalLogger';
+import { appLifecycle } from '../../core/lifecycle/appLifecycle';
+import { AutoScreenDetector } from '../navigation/AutoScreenDetector';
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { engageSignals } from './engageSignals';
+import { installEngageShakeBridge } from './engageShakeBridge';
+import { normalizeInAppTrigger } from './engageThrottle';
+
+// ─── Engage behavioral-trigger engine (P3-e #3 / Slice E) ─────────────────────
+// One place that turns SDK signals the app ALREADY produces into behavioral
+// trigger fires. Reuse-before-build: it subscribes to existing producers
+// (AutoScreenDetector, appLifecycle, and the `track()` event funnel via
+// engageSignals) — it does NOT add a parallel capture pipeline. Every fire goes
+// through the same `showEngagePrompt({ trigger })` path, so the throttle store and
+// campaign selection are unchanged.
+//
+// Trigger → producer map (13 JS-reusable triggers; the 3 native gesture triggers
+// — rage_tap, dead_tap, shake_device — emit into the SAME `$gesture` signal lane):
+//   screen_view / screen_exit          ← AutoScreenDetector.onScreenChange
+//   time_in_app                        ← appLifecycle foreground timer (config seconds)
+//   n_sessions                         ← persisted per-launch session counter
+//   after_purchase                     ← track('purchase' | '$purchase')
+//   before_logout                      ← track('$clear_user')
+//   custom_event                       ← any app track(name) (matched by triggerConfig.event)
+//   failed_action                      ← track('$failed_action', { action })
+//   after_crash / js_error             ← track('$crash') (js_error when source is 'js'|'handled')
+//   network_error                      ← track('$network_request') with error/4xx/5xx
+//   slow_screen                        ← track('$perf_event') slow/frozen
+//   rage_tap / dead_tap / shake_device ← track('$gesture', { gesture })  [native E4]
+
+const SESSION_COUNT_KEY = 'scalebun.engage.sessionCount';
+const TIME_IN_APP_PRESETS = [5, 10, 30]; // §2.10.3 presets; fallback when config omits seconds
+
+// Late-binding (recent-event replay) tuning. session_start (and any signal) can
+// fire before the FIRST config GET resolves — e.g. a cold start while offline.
+// Such fires are buffered and replayed once config arrives, honoring each
+// trigger's REMAINING delay (so "show 5s after session_start" still lands at the
+// right moment, not 5s after the network recovers).
+const RECENT_TTL_MS = 60_000; // buffered events older than this are dropped, not replayed
+const RECENT_MAX = 30; // ring-buffer cap
+const CONFIG_PROBE_ATTEMPTS = 6; // retry the first config fetch until it arrives
+const CONFIG_PROBE_BACKOFF_MS = 1500;
+
+/**
+ * Largest authored "delay after trigger" (seconds → ms) among the campaigns and
+ * in-app messages bound to `trigger`. Drives how long the engine waits after a
+ * trigger fires before showing. 0 when nothing for that trigger declares a delay.
+ */
+function delayMsForTrigger(config, trigger) {
+  if (!trigger || !config) return 0;
+  let maxSeconds = 0;
+  for (const c of config.campaigns ?? []) {
+    if (c.trigger === trigger && typeof c.triggerConfig?.delaySeconds === 'number') {
+      maxSeconds = Math.max(maxSeconds, c.triggerConfig.delaySeconds);
+    }
+  }
+  for (const m of config.inAppMessages ?? []) {
+    if (m.trigger !== 'time_delay' && normalizeInAppTrigger(m.trigger) === normalizeInAppTrigger(trigger) && typeof m.delaySeconds === 'number') {
+      maxSeconds = Math.max(maxSeconds, m.delaySeconds);
+    }
+  }
+  return Math.max(0, maxSeconds) * 1000;
+}
+function isNetworkError(payload) {
+  if (!payload) return false;
+  const status = typeof payload.status === 'number' ? payload.status : undefined;
+  return !!payload.error || status === 0 || status !== undefined && status >= 400;
+}
+function isSlowPerf(payload) {
+  const t = payload?.perfType;
+  return t === 'frozen_frame' || t === 'slow_frame' || t === 'slow_screen' || t === 'screen_load';
+}
+
+/**
+ * Wire every JS-reusable behavioral trigger to its existing producer. Returns a
+ * teardown that detaches all subscriptions/timers.
+ */
+export function installEngageTriggerEngine(deps) {
+  const storage = deps.storage ?? createStorageBackend();
+  const teardown = [];
+  // `timers`: time_in_app timers, reset (cleared) on every foreground reschedule
+  // and on background. `lateTimers`: delay-honoring dispatch fires + the config
+  // probe backoff — these must SURVIVE a foreground reschedule (clearTimers), so
+  // they live in their own set cleared only at teardown.
+  const timers = new Set();
+  const lateTimers = new Set();
+  const fire = options => {
+    try {
+      // A fire while the app is not foregrounded renders behind the lock
+      // screen (or into a backgrounded activity), records the impression,
+      // and permanently consumes a showOnce campaign that no human saw.
+      // Found live: a cold start with the screen off burned both a survey
+      // and an in-app message before the phone was ever unlocked.
+      if (appLifecycle.getCurrentState() !== 'active') {
+        __DEV__ && logger.debug(`[Engage] trigger suppressed (app ${appLifecycle.getCurrentState()}): ${options.trigger ?? 'manual'}`);
+        return;
+      }
+      __DEV__ && logger.debug(`[Engage] trigger fire: ${options.trigger ?? 'manual'}` + (options.screen ? ` screen=${options.screen}` : ''));
+      deps.fire(options);
+    } catch (err) {
+      __DEV__ && logger.debug('[Engage] trigger fire failed:', err?.message);
+    }
+  };
+
+  // ── Config cache + late-binding ring buffer ───────────────────────────
+  // One memoized config fetch feeds delay lookup AND the threshold triggers
+  // (time_in_app / n_sessions), so a cold start makes ~1 config GET, not three.
+  let cachedConfig = null;
+  let configReady = false;
+  const recent = [];
+  const ensureConfig = async () => {
+    if (cachedConfig) return cachedConfig;
+    const cfg = await deps.fetchConfig();
+    if (cfg && Array.isArray(cfg.campaigns)) cachedConfig = cfg;
+    return cfg;
+  };
+  const schedule = (options, delayMs) => {
+    if (delayMs <= 0) {
+      fire(options);
+      return;
+    }
+    const t = setTimeout(() => {
+      lateTimers.delete(t);
+      fire(options);
+    }, delayMs);
+    lateTimers.add(t);
+  };
+
+  // Every behavioral fire routes through dispatch: before the first config is
+  // ready it is BUFFERED (so an offline cold start doesn't silently lose it);
+  // afterwards it is scheduled directly, honoring the trigger's authored delay.
+  const dispatch = options => {
+    if (!configReady) {
+      recent.push({
+        options,
+        at: Date.now()
+      });
+      if (recent.length > RECENT_MAX) recent.shift();
+      return;
+    }
+    schedule(options, delayMsForTrigger(cachedConfig, options.trigger));
+  };
+
+  // ── Screen view / exit ────────────────────────────────────────────────
+  const detector = AutoScreenDetector.getInstance();
+  let prevScreen = null;
+  teardown.push(detector.onScreenChange(screenName => {
+    const exited = prevScreen;
+    prevScreen = screenName;
+    dispatch({
+      trigger: 'screen_view',
+      screen: screenName
+    });
+    if (exited && exited !== screenName) {
+      dispatch({
+        trigger: 'screen_exit',
+        screen: exited
+      });
+    }
+  }));
+
+  // ── Event funnel (track) ──────────────────────────────────────────────
+  const onSignal = ({
+    name,
+    payload
+  }) => {
+    switch (name) {
+      case '$crash':
+        {
+          dispatch({
+            trigger: 'after_crash'
+          });
+          // js_error = any JS-origin error (uncaught `js` OR a `handled`
+          // captureError) — distinct from a `native` crash, which only
+          // drives after_crash.
+          const source = typeof payload?.source === 'string' ? payload.source : undefined;
+          if (source === 'js' || source === 'handled') dispatch({
+            trigger: 'js_error'
+          });
+          return;
+        }
+      case '$network_request':
+        {
+          if (isNetworkError(payload)) dispatch({
+            trigger: 'network_error'
+          });
+          return;
+        }
+      case '$perf_event':
+        {
+          if (isSlowPerf(payload)) dispatch({
+            trigger: 'slow_screen'
+          });
+          return;
+        }
+      case '$clear_user':
+        {
+          dispatch({
+            trigger: 'before_logout'
+          });
+          return;
+        }
+      case '$failed_action':
+        {
+          const action = typeof payload?.action === 'string' ? payload.action : undefined;
+          dispatch({
+            trigger: 'failed_action',
+            action
+          });
+          return;
+        }
+      case '$gesture':
+        {
+          const gesture = typeof payload?.gesture === 'string' ? payload.gesture : undefined;
+          if (gesture === 'rage_tap' || gesture === 'dead_tap' || gesture === 'shake_device') {
+            dispatch({
+              trigger: gesture
+            });
+          }
+          return;
+        }
+      default:
+        {
+          // App-defined custom events (non-reserved). Drive custom_event,
+          // matched by triggerConfig.event; 'purchase' also drives after_purchase.
+          if (name.startsWith('$')) return;
+          dispatch({
+            trigger: 'custom_event',
+            event: name
+          });
+          if (name.toLowerCase() === 'purchase') dispatch({
+            trigger: 'after_purchase'
+          });
+        }
+    }
+  };
+  teardown.push(engageSignals.subscribe(onSignal));
+
+  // ── shake_device (native accelerometer) ───────────────────────────────
+  // rage_tap / dead_tap feed `$gesture` from the JS touch layer; shake_device
+  // feeds the same lane from the native ScaleBunEngage shake detector. Fail-soft.
+  teardown.push(installEngageShakeBridge());
+
+  // ── time_in_app ───────────────────────────────────────────────────────
+  const clearTimers = () => {
+    for (const t of timers) clearTimeout(t);
+    timers.clear();
+  };
+  const scheduleTimeInApp = async () => {
+    clearTimers();
+    let secondsList = TIME_IN_APP_PRESETS;
+    try {
+      const config = await ensureConfig();
+      const campaignSeconds = (config?.campaigns ?? []).filter(c => c.trigger === 'time_in_app').map(c => c.triggerConfig?.seconds).filter(s => typeof s === 'number' && s >= 0);
+      const messageSeconds = (config?.inAppMessages ?? []).filter(message => message.trigger === 'time_delay').map(message => message.delaySeconds).filter(seconds => typeof seconds === 'number' && seconds >= 0);
+      const configured = [...campaignSeconds, ...messageSeconds];
+      if (configured.length > 0) secondsList = Array.from(new Set(configured));
+    } catch {
+      // fall back to presets
+    }
+    for (const seconds of secondsList) {
+      const t = setTimeout(() => {
+        timers.delete(t);
+        fire({
+          trigger: 'time_in_app',
+          seconds
+        });
+      }, seconds * 1000);
+      timers.add(t);
+    }
+  };
+  let hasOpened = false;
+  const onLifecycle = state => {
+    if (state === 'active') {
+      void scheduleTimeInApp();
+      dispatch({
+        trigger: hasOpened ? 'app_foreground' : 'app_open'
+      });
+      hasOpened = true;
+    } else {
+      clearTimers();
+      if (state === 'background') dispatch({
+        trigger: 'app_background'
+      });
+    }
+  };
+  appLifecycle.addListener(onLifecycle);
+  teardown.push(() => appLifecycle.removeListener(onLifecycle));
+  if (appLifecycle.getCurrentState() === 'active') onLifecycle('active');
+  teardown.push(clearTimers);
+  teardown.push(() => {
+    for (const t of lateTimers) clearTimeout(t);
+    lateTimers.clear();
+  });
+
+  // ── n_sessions ────────────────────────────────────────────────────────
+  // One engine install == one app session. Bump the persisted counter, then
+  // fire n_sessions if any campaign targets exactly this session number.
+  void (async () => {
+    const current = parseInt(storage.get(SESSION_COUNT_KEY) ?? '0', 10) || 0;
+    const next = current + 1;
+    storage.set(SESSION_COUNT_KEY, String(next));
+    try {
+      const config = await ensureConfig();
+      const targets = (config?.campaigns ?? []).filter(c => c.trigger === 'n_sessions').map(c => c.triggerConfig?.sessions).filter(s => typeof s === 'number');
+      if (targets.includes(next)) fire({
+        trigger: 'n_sessions'
+      });
+    } catch (err) {
+      __DEV__ && logger.debug('[Engage] n_sessions check failed:', err?.message);
+    }
+  })();
+
+  // ── session_start (first-class) + late-binding replay ─────────────────
+  // One engine install == one session begin. Fire session_start through the
+  // SAME dispatch path so a `session_start`-triggered campaign/in-app message
+  // shows on launch. It is BUFFERED until the first config arrives, then
+  // replayed honoring its remaining delay — so a cold start (even briefly
+  // offline) never silently drops it.
+  dispatch({
+    trigger: 'session_start'
+  });
+  void (async () => {
+    for (let attempt = 0; attempt < CONFIG_PROBE_ATTEMPTS; attempt++) {
+      try {
+        if (await ensureConfig()) break;
+      } catch {
+        // retry
+      }
+      await new Promise(resolve => {
+        const t = setTimeout(() => {
+          lateTimers.delete(t);
+          resolve();
+        }, CONFIG_PROBE_BACKOFF_MS);
+        lateTimers.add(t);
+      });
+    }
+    if (!cachedConfig) return; // config never arrived this session → buffered events expire
+    configReady = true;
+    const now = Date.now();
+    const pending = recent.splice(0); // consume the buffer exactly once
+    for (const e of pending) {
+      const age = now - e.at;
+      if (age > RECENT_TTL_MS) continue; // too stale to be relevant → drop
+      // Honor the REMAINING delay: intended show time was (fired-at + delay).
+      const remaining = delayMsForTrigger(cachedConfig, e.options.trigger) - age;
+      schedule(e.options, remaining);
+    }
+  })();
+  return () => {
+    for (const t of teardown) {
+      try {
+        t();
+      } catch {
+        // best-effort teardown
+      }
+    }
+  };
+}
+//# sourceMappingURL=engageTriggerEngine.js.map

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

@@ -0,0 +1,110 @@
+/**
+ * ScaleBun SDK — Engage Surface Wire Types (foundation)
+ *
+ * Typed DTOs for the 7-screen Engage surface transport lanes, mirrored from the
+ * FROZEN `engage-build/CONTRACT.md` v1 (§1.3 config-serve, §1.4 response upload,
+ * §2.2 device-token registration, §2.4 in-app config, §2.5 event upload).
+ *
+ * All shared wire structures carry an explicit integer version (`configVersion`
+ * or `schemaVersion`) per D9. v1 freeze: `configVersion = 1`. Response schema is
+ * now `schemaVersion = 2` (P0): `EngageResponse` gained the OPTIONAL, ADDITIVE
+ * fields `screen` / `platform` / `appVersion` (`sessionId` already existed and is
+ * now populated). v1 payloads still validate — every new field is optional — and
+ * consumers MUST tolerate unknown fields/higher versions by ignoring them (D9).
+ *
+ * Render/overlay is OUT OF SCOPE for this stage — the shared cross-platform JS
+ * overlay (D4) consumes `fetchEngageConfig()` in a later slice.
+ */
+
+/** Schema/config version constant (D9). v2 = additive feedback-response fields (P0). */
+export const ENGAGE_SCHEMA_VERSION = 2;
+
+// ─── §1.3 Config-serve payload (backend → SDK) ───────────────────────────────
+
+/** One answer in a multi-question SURVEY response (mirrors §1.4 `answers[]`). */
+
+// ─── §2.4 In-app message config (rides the SAME config lane) ──────────────────
+
+/** URL-backed assets lifted from the normalized in-app payload for SDK rendering. */
+
+/**
+ * Authored size of a campaign's primary hero/poster media.
+ *
+ * The value is carried additively at `spec.ext.mediaSize`. Missing, `auto`, and
+ * unknown values preserve each renderer's historical dimensions.
+ */
+
+/** Semantic artwork options for the authored terminal result/confirmation card. */
+
+/** Normalized action authored for the terminal result/confirmation button. */
+
+/**
+ * Presentation-only terminal card configuration.
+ *
+ * This must never carry a game result. Reward identity/value remains exclusively
+ * in `InAppGameOutcome`, returned by the host's authenticated backend.
+ */
+
+/** Open variant payload with shared cross-variant conventions typed explicitly. */
+
+/** An authored in-app action. Coachmark steps reuse the same click contract. */
+
+/** One ordered stop in a `coachmark_spotlight` tour (`spec.ext.steps`). */
+
+/**
+ * Optional A/B experiment carried on an in-app campaign config (D8/J6). When
+ * `enabled`, the SDK deterministically buckets the current user/device into
+ * variant `A` (the message's base `spec`) or variant `B` (`variantB`), where
+ * `split` is the integer percentage (0–100) of traffic routed to variant B.
+ * Absent/`enabled:false` ⇒ everyone sees the base `spec` (no experiment).
+ * Additive + optional — older configs (no `experiment`) are unaffected.
+ */
+
+/** Resolved experiment arm for the current user/device (client-side selection). */
+
+// ─── Customer-owned gamified result contract ──────────────────────────────────────
+
+/** Variants whose result/state must be resolved by the host app's backend. */
+
+/** Discriminated request passed to `onInAppGameRequest`. */
+
+/** Presentation-safe result returned after the customer's backend grants/reserves it. */
+
+/** A host can return `unavailable`, or throw; both produce the same retry-safe UI. */
+
+/** Optional app/user context for server-side targeting/throttle (§1.3 query). */
+
+// ─── §1.4 Response payload (SDK → backend) ───────────────────────────────────
+
+// ─── Rating-funnel event lane (ratings-rebuild CONTRACT §1.1–1.2) ────────────
+// First-class, dimensioned, deduped tracking facts feeding the Overview funnel.
+// NOT a campaign response (D1) — these never count as a "rating response".
+
+/** Closed, ordered funnel enum (CONTRACT §1.1). Producers never emit outside it. */
+
+/** Per-event breakdown dimensions (CONTRACT §1.2 `dims`). All optional/honest. */
+
+/** What a caller raises (no eventId/ts — the transport stamps those, D8). */
+
+/** Wire shape after the transport stamps the idempotency key + client clock. */
+
+// ─── §P3-e Feedback attachments (screenshot + voice) ─────────────────────────
+
+/** Raw attachment captured on-device, before upload (carries bytes + dimensions). */
+
+/** Attachment metadata sent on the response after the bytes are PUT to storage. */
+
+/** Presign response item (backend → SDK). */
+
+/** Caller-supplied response input — `responseId`/`schemaVersion`/`clientTs` stamped by transport. */
+
+// ─── §2.5 Tracking-event upload (SDK → backend, in-app legs) ─────────────────
+
+/** Caller-supplied event input — `eventId`/`schemaVersion`/`timestamp` stamped by transport. */
+
+// ─── §2.2 Device-token registration (SDK → backend, push) ────────────────────
+
+/** Caller-supplied token input — `schemaVersion`/`tokenStatus` stamped by transport. */
+
+// ─── Batched upload envelopes (mirror the existing ingestion lane shapes) ─────
+//# sourceMappingURL=engageTypes.js.map

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

@@ -0,0 +1,135 @@
+/** The 18 renderer families in the canonical in-app registry. */
+
+/** Interactive renderer families kept for the existing mechanic-only API. */
+
+/** How the SDK host physically attaches a presentation. */
+
+/** The original seven-layout transport contract used for graceful degradation. */
+
+/**
+ * Compact, runtime-safe projection of the canonical 100-row dashboard registry.
+ * It intentionally carries only data needed for SDK dispatch and degradation.
+ */
+const VARIANT_GROUPS = [["modal", "overlay", "modal", "classic_modal rich_modal media_modal split_modal confirmation_modal center_drawer referral_invite calendar_picker_offer waitlist_joiner exit_intent_rescue welcome_back_card feature_discovery renewal_reminder trial_conversion price_drop_alert back_in_stock reorder_reminder location_based_prompt time_of_day_offer weather_based_card vip_unlock loyalty_tier_upgrade personal_finance_insight security_alert permissions_primer app_review_ask ai_assistant_nudge webinar_registration appointment_booker chat_handoff_prompt rich_form_modal document_upload_prompt multi_cta_decision_hub smart_segment_preview geo_fenced_arrival_card"], ["sheet", "sheet", "bottom_sheet", "bottom_sheet peek_card coupon_wallet upgrade_nudger cart_recovery browse_recovery cross_sell_recommendation personalized_digest compare_plans_sheet support_escalation id_verification_sheet consent_center checkout_accelerator bundle_builder"], ["bannerToast", "banner", "top_banner", "top_banner sticky_header_bar live_event_banner"], ["bannerToast", "banner", "bottom_banner", "bottom_banner sticky_footer_bar"], ["bannerToast", "toast", "toast", "toast snackbar_cta"], ["bannerToast", "toast", "bottom_banner", "social_proof_popup"], ["fullscreen", "fullscreen", "fullscreen", "full_screen_takeover editorial_full_screen dynamic_paywall"], ["anchored", "anchored", "tooltip", "tooltip coachmark_spotlight fab_prompt"], ["modal", "overlay", "tooltip", "mini_popover"], ["anchored", "bubble", "modal", "floating_bubble"], ["inline", "inline", "modal", "inline_card embedded_panel empty_state_prompt smart_inbox_message"], ["multiStepSheet", "sheet", "bottom_sheet", "multi_step_bottom_sheet"], ["sideSheet", "sheet", "bottom_sheet", "side_sheet"], ["spinWheel", "overlay", "modal", "spin_wheel"], ["scratchReveal", "overlay", "modal", "scratch_card mystery_box"], ["slotReward", "overlay", "modal", "slot_reward"], ["carouselDeck", "overlay", "modal", "carousel_story swipe_deck"], ["countdown", "overlay", "modal", "countdown_offer"], ["questionFlow", "overlay", "modal", "poll_card quiz_card product_finder rating_request"], ["questionFlow", "sheet", "bottom_sheet", "survey_sheet nps_prompt preferences_picker feedback_capture"], ["questionFlow", "banner", "bottom_banner", "emoji_reaction_bar"], ["checklistProgress", "overlay", "modal", "progress_unlock streak_reward daily_check_in goal_tracker community_challenge"], ["checklistProgress", "fullscreen", "fullscreen", "first_session_onboarding guided_setup_wizard"], ["checklistProgress", "sheet", "bottom_sheet", "interactive_checklist"], ["qrNfc", "overlay", "modal", "nfc_qr_prompt wallet_pass_offer"], ["videoCommerce", "overlay", "modal", "video_commerce_card"], ["celebration", "overlay", "modal", "milestone_celebration"], ["celebration", "fullscreen", "fullscreen", "celebration_confetti_full_screen"]];
+export const IN_APP_VARIANT_PRESENTATIONS = Object.freeze(Object.fromEntries(VARIANT_GROUPS.flatMap(([archetype, mountModel, legacyLayout, keys]) => keys.split(" ").map(key => [key, Object.freeze({
+  archetype,
+  mountModel,
+  legacyLayout
+})]))));
+const LAYOUT_PRESENTATIONS = {
+  modal: {
+    archetype: "modal",
+    mountModel: "overlay",
+    legacyLayout: "modal"
+  },
+  fullscreen: {
+    archetype: "fullscreen",
+    mountModel: "fullscreen",
+    legacyLayout: "fullscreen"
+  },
+  bottom_sheet: {
+    archetype: "sheet",
+    mountModel: "sheet",
+    legacyLayout: "bottom_sheet"
+  },
+  top_banner: {
+    archetype: "bannerToast",
+    mountModel: "banner",
+    legacyLayout: "top_banner"
+  },
+  bottom_banner: {
+    archetype: "bannerToast",
+    mountModel: "banner",
+    legacyLayout: "bottom_banner"
+  },
+  tooltip: {
+    archetype: "anchored",
+    mountModel: "anchored",
+    legacyLayout: "tooltip"
+  },
+  toast: {
+    archetype: "bannerToast",
+    mountModel: "toast",
+    legacyLayout: "toast"
+  }
+};
+function previewVariantKey(message) {
+  const value = message.spec.variantKey;
+  return typeof value === "string" ? value : undefined;
+}
+function fromCanonicalKey(key, source, fallback) {
+  const definition = IN_APP_VARIANT_PRESENTATIONS[key];
+  return definition ? {
+    ...definition,
+    variantKey: key,
+    source,
+    fallback
+  } : null;
+}
+function fromLayout(message, reason, requestedKey) {
+  const wireLayout = message.layout;
+  const layout = wireLayout === "banner" ? "top_banner" : Object.prototype.hasOwnProperty.call(LAYOUT_PRESENTATIONS, wireLayout) ? wireLayout : "modal";
+  return {
+    ...LAYOUT_PRESENTATIONS[layout],
+    variantKey: null,
+    source: "layout",
+    fallback: {
+      reason,
+      ...(requestedKey === undefined ? {} : {
+        requestedKey
+      }),
+      degraded: true
+    }
+  };
+}
+
+/**
+ * Resolve canonical identity first, retaining explicit metadata whenever a
+ * preview/legacy compatibility lane or graceful layout degradation was used.
+ */
+export function resolveInAppPresentation(message) {
+  if (message.variantKey !== undefined) {
+    return fromCanonicalKey(message.variantKey, "variantKey", null) ?? fromLayout(message, "unknown_variant_key", message.variantKey);
+  }
+  const previewKey = previewVariantKey(message);
+  if (previewKey !== undefined) {
+    return fromCanonicalKey(previewKey, "spec.variantKey", {
+      reason: "preview_variant_key",
+      degraded: false
+    }) ?? fromLayout(message, "unknown_preview_variant_key", previewKey);
+  }
+  if (message.spec.archetype !== undefined) {
+    return fromCanonicalKey(message.spec.archetype, "spec.archetype", {
+      reason: "legacy_archetype",
+      degraded: false
+    }) ?? fromLayout(message, "unknown_legacy_archetype", message.spec.archetype);
+  }
+  return fromLayout(message, "missing_variant_key");
+}
+const MECHANIC_FAMILIES = ["spinWheel", "scratchReveal", "slotReward", "carouselDeck", "countdown", "questionFlow", "checklistProgress", "qrNfc", "videoCommerce", "celebration"];
+function mechanicForKey(key) {
+  const archetype = IN_APP_VARIANT_PRESENTATIONS[key]?.archetype;
+  return archetype && MECHANIC_FAMILIES.includes(archetype) ? archetype : null;
+}
+
+/**
+ * Resolve an in-app config to an interactive mechanic family.
+ *
+ * A present top-level `variantKey` remains authoritative. Older previews may
+ * carry the canonical key in `spec.variantKey`; hand-authored legacy payloads
+ * may instead use `spec.archetype`. `checklist_progress` remains a legacy-only
+ * alias and is deliberately absent from the canonical 100-key map.
+ */
+export function resolveInAppMechanic(message) {
+  if (message.variantKey !== undefined) {
+    return mechanicForKey(message.variantKey);
+  }
+  const specVariantKey = message.spec.variantKey;
+  if (typeof specVariantKey === "string") {
+    return mechanicForKey(specVariantKey);
+  }
+  const legacyArchetype = message.spec.archetype;
+  if (legacyArchetype === "checklist_progress") return "checklistProgress";
+  return legacyArchetype ? mechanicForKey(legacyArchetype) : null;
+}
+//# sourceMappingURL=engageVariantResolver.js.map