@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/engage/engageTriggerEngine.ts

@@ -1,335 +1,350 @@
-import { logger } from '../../core/logger/internalLogger';
-import { appLifecycle } from '../../core/lifecycle/appLifecycle';
-import { AutoScreenDetector } from '../navigation/AutoScreenDetector';
-import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
-import { engageSignals, type SdkSignal } from './engageSignals';
-import { installEngageShakeBridge } from './engageShakeBridge';
-import type { EngageConfigResponse } from './engageTypes';
-import type { ShowEngagePromptOptions } from './EngagePromptProvider';
-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: EngageConfigResponse | null,
-    trigger?: string,
-): number {
-    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;
-}
-
-export interface EngageTriggerEngineDeps {
-    /** Fire a behavioral trigger through the shared prompt path. */
-    fire: (options: ShowEngagePromptOptions) => void;
-    /** Fetch the current Engage config (for threshold-aware triggers). */
-    fetchConfig: () => Promise<EngageConfigResponse | null>;
-    storage?: StorageBackend;
-}
-
-function isNetworkError(payload?: Record<string, unknown>): boolean {
-    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?: Record<string, unknown>): boolean {
-    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: EngageTriggerEngineDeps): () => void {
-    const storage = deps.storage ?? createStorageBackend();
-    const teardown: Array<() => void> = [];
-    // `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<ReturnType<typeof setTimeout>>();
-    const lateTimers = new Set<ReturnType<typeof setTimeout>>();
-
-    const fire = (options: ShowEngagePromptOptions): void => {
-        try {
-            deps.fire(options);
-        } catch (err) {
-            logger.debug('[Engage] trigger fire failed:', (err as Error)?.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: EngageConfigResponse | null = null;
-    let configReady = false;
-    const recent: Array<{ options: ShowEngagePromptOptions; at: number }> = [];
-
-    const ensureConfig = async (): Promise<EngageConfigResponse | null> => {
-        if (cachedConfig) return cachedConfig;
-        const cfg = await deps.fetchConfig();
-        if (cfg && Array.isArray(cfg.campaigns)) cachedConfig = cfg;
-        return cfg;
-    };
-
-    const schedule = (options: ShowEngagePromptOptions, delayMs: number): void => {
-        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: ShowEngagePromptOptions): void => {
-        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: string | null = 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 }: SdkSignal): void => {
-        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 = (): void => {
-        for (const t of timers) clearTimeout(t);
-        timers.clear();
-    };
-    const scheduleTimeInApp = async (): Promise<void> => {
-        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): s is number => typeof s === 'number' && s >= 0);
-            const messageSeconds = (config?.inAppMessages ?? [])
-                .filter((message) => message.trigger === 'time_delay')
-                .map((message) => message.delaySeconds)
-                .filter((seconds): seconds is number => 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: string): void => {
-        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): s is number => typeof s === 'number');
-            if (targets.includes(next)) fire({ trigger: 'n_sessions' });
-        } catch (err) {
-            logger.debug('[Engage] n_sessions check failed:', (err as Error)?.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<void>((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
-            }
-        }
-    };
-}
+import { logger } from '../../core/logger/internalLogger';
+import { appLifecycle } from '../../core/lifecycle/appLifecycle';
+import { AutoScreenDetector } from '../navigation/AutoScreenDetector';
+import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
+import { engageSignals, type SdkSignal } from './engageSignals';
+import { installEngageShakeBridge } from './engageShakeBridge';
+import type { EngageConfigResponse } from './engageTypes';
+import type { ShowEngagePromptOptions } from './EngagePromptProvider';
+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: EngageConfigResponse | null,
+    trigger?: string,
+): number {
+    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;
+}
+
+export interface EngageTriggerEngineDeps {
+    /** Fire a behavioral trigger through the shared prompt path. */
+    fire: (options: ShowEngagePromptOptions) => void;
+    /** Fetch the current Engage config (for threshold-aware triggers). */
+    fetchConfig: () => Promise<EngageConfigResponse | null>;
+    storage?: StorageBackend;
+}
+
+function isNetworkError(payload?: Record<string, unknown>): boolean {
+    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?: Record<string, unknown>): boolean {
+    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: EngageTriggerEngineDeps): () => void {
+    const storage = deps.storage ?? createStorageBackend();
+    const teardown: Array<() => void> = [];
+    // `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<ReturnType<typeof setTimeout>>();
+    const lateTimers = new Set<ReturnType<typeof setTimeout>>();
+
+    const fire = (options: ShowEngagePromptOptions): void => {
+        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') {
+                logger.debug(
+                    `[Engage] trigger suppressed (app ${appLifecycle.getCurrentState()}): ${options.trigger ?? 'manual'}`,
+                );
+                return;
+            }
+            logger.debug(
+                `[Engage] trigger fire: ${options.trigger ?? 'manual'}` +
+                    (options.screen ? ` screen=${options.screen}` : ''),
+            );
+            deps.fire(options);
+        } catch (err) {
+            logger.debug('[Engage] trigger fire failed:', (err as Error)?.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: EngageConfigResponse | null = null;
+    let configReady = false;
+    const recent: Array<{ options: ShowEngagePromptOptions; at: number }> = [];
+
+    const ensureConfig = async (): Promise<EngageConfigResponse | null> => {
+        if (cachedConfig) return cachedConfig;
+        const cfg = await deps.fetchConfig();
+        if (cfg && Array.isArray(cfg.campaigns)) cachedConfig = cfg;
+        return cfg;
+    };
+
+    const schedule = (options: ShowEngagePromptOptions, delayMs: number): void => {
+        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: ShowEngagePromptOptions): void => {
+        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: string | null = 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 }: SdkSignal): void => {
+        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 = (): void => {
+        for (const t of timers) clearTimeout(t);
+        timers.clear();
+    };
+    const scheduleTimeInApp = async (): Promise<void> => {
+        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): s is number => typeof s === 'number' && s >= 0);
+            const messageSeconds = (config?.inAppMessages ?? [])
+                .filter((message) => message.trigger === 'time_delay')
+                .map((message) => message.delaySeconds)
+                .filter((seconds): seconds is number => 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: string): void => {
+        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): s is number => typeof s === 'number');
+            if (targets.includes(next)) fire({ trigger: 'n_sessions' });
+        } catch (err) {
+            logger.debug('[Engage] n_sessions check failed:', (err as Error)?.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<void>((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
+            }
+        }
+    };
+}