@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/engage/engageThrottle.ts

@@ -1,440 +1,478 @@
-/**
- * ScaleBun SDK — Engage Prompt Throttle + Decision Logic
- *
- * Pure, presentation-free logic that the shared cross-platform JS overlay (D4)
- * uses to decide WHICH campaign (if any) to render from a fetched
- * `EngageConfigResponse`, honoring each campaign's `throttle`/`Throttle` rules
- * (§1.3) so a user is never re-prompted on every render.
- *
- * State (per-campaign impression count + last-shown timestamp) is persisted via
- * the same synchronous KV backend used for the device id, so frequency capping
- * survives app restarts. No React, no `any`, no network — this is the testable
- * core of the renderer's Open/Closed decision seam.
- */
-
-import { logger } from '../../core/logger/internalLogger';
-import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
-import type {
-    EngageCampaignConfig,
-    InAppMessageConfig,
-    InAppRenderSpec,
-    InAppVariantId,
-    Throttle,
-} from './engageTypes';
-
-/** Persisted frequency-capping state for a single campaign. */
-export interface CampaignThrottleState {
-    /** Number of times this campaign has been shown (impressions). */
-    impressions: number;
-    /** Epoch ms of the last impression — drives `cooldownHours`. */
-    lastShownAt: number;
-    /** Set once a response was submitted — hard stop for `showOnce`. */
-    completed: boolean;
-    /**
-     * Content revision this state was recorded against. When the live config carries
-     * a NEWER revision (author changed the campaign's design/content/type), the prior
-     * impression/showOnce/cooldown state is stale and must NOT suppress the updated
-     * message — see `passesThrottle`. Absent on legacy state ⇒ revision check is skipped.
-     */
-    revision?: string;
-}
-
-const STORAGE_PREFIX = 'scalebun_engage_throttle:';
-
-/**
- * Persistent, restart-surviving store for per-campaign throttle state. Backed by
- * the shared first-party StorageBackend (durable native store, memory only as an
- * emergency fallback), so frequency caps hold across sessions exactly like the
- * device id.
- */
-export class EngageThrottleStore {
-    private readonly backend: StorageBackend;
-
-    constructor(backend: StorageBackend = createStorageBackend()) {
-        this.backend = backend;
-    }
-
-    private keyFor(campaignId: string): string {
-        return `${STORAGE_PREFIX}${campaignId}`;
-    }
-
-    /** Read the persisted state for a campaign (zeroed default when absent). */
-    get(campaignId: string): CampaignThrottleState {
-        try {
-            const raw = this.backend.get(this.keyFor(campaignId));
-            if (raw) {
-                const parsed = JSON.parse(raw) as Partial<CampaignThrottleState>;
-                return {
-                    impressions: typeof parsed.impressions === 'number' ? parsed.impressions : 0,
-                    lastShownAt: typeof parsed.lastShownAt === 'number' ? parsed.lastShownAt : 0,
-                    completed: parsed.completed === true,
-                    revision: typeof parsed.revision === 'string' ? parsed.revision : undefined,
-                };
-            }
-        } catch (err) {
-            logger.debug('[Engage] throttle state read failed:', (err as Error)?.message);
-        }
-        return { impressions: 0, lastShownAt: 0, completed: false };
-    }
-
-    /** Delete one campaign's persisted throttle state (debug/dev reset, or per-id clear). */
-    clearOne(campaignId: string): void {
-        try {
-            this.backend.delete(this.keyFor(campaignId));
-        } catch (err) {
-            logger.debug('[Engage] throttle clearOne failed:', (err as Error)?.message);
-        }
-    }
-
-    /**
-     * Delete ALL persisted in-app/campaign throttle state (every `scalebun_engage_throttle:*`
-     * key). Backs the public `ScaleBun.engage.resetInAppState()` debug reset — clears
-     * dismissed/impression/cooldown/showOnce so a tester sees messages again WITHOUT an
-     * uninstall. Does NOT touch the device id (a separate key) — identity is preserved.
-     */
-    clearAll(): number {
-        let n = 0;
-        try {
-            for (const key of this.backend.getAllKeys()) {
-                if (key.startsWith(STORAGE_PREFIX)) {
-                    this.backend.delete(key);
-                    n += 1;
-                }
-            }
-        } catch (err) {
-            logger.debug('[Engage] throttle clearAll failed:', (err as Error)?.message);
-        }
-        return n;
-    }
-
-    private write(campaignId: string, state: CampaignThrottleState): void {
-        try {
-            this.backend.set(this.keyFor(campaignId), JSON.stringify(state));
-        } catch (err) {
-            logger.debug('[Engage] throttle state write failed:', (err as Error)?.message);
-        }
-    }
-
-    /**
-     * Record that a campaign was shown (bumps impressions + last-shown time). When a
-     * `revision` is supplied and differs from the stored one, the prior counters are a
-     * stale (pre-edit) generation and reset to a single fresh impression — so changing a
-     * campaign's content never inherits the old cap.
-     */
-    recordImpression(campaignId: string, now: number = Date.now(), revision?: string): void {
-        const prev = this.get(campaignId);
-        const fresh = revision !== undefined && prev.revision !== undefined && prev.revision !== revision;
-        this.write(campaignId, {
-            impressions: fresh ? 1 : prev.impressions + 1,
-            lastShownAt: now,
-            completed: fresh ? false : prev.completed,
-            revision: revision ?? prev.revision,
-        });
-    }
-
-    /** Mark a campaign as completed (response submitted) — a hard `showOnce` stop. */
-    markCompleted(campaignId: string, now: number = Date.now()): void {
-        const prev = this.get(campaignId);
-        this.write(campaignId, {
-            impressions: prev.impressions,
-            lastShownAt: prev.lastShownAt || now,
-            completed: true,
-        });
-    }
-}
-
-/** Deterministic 0–99 bucket for a string seed (stable across sessions/devices). */
-function stableBucket(seed: string): number {
-    let hash = 0;
-    for (let i = 0; i < seed.length; i += 1) {
-        hash = (hash * 31 + seed.charCodeAt(i)) | 0;
-    }
-    return Math.abs(hash) % 100;
-}
-
-/** Deterministic 0–99 bucket for `samplePct` gating (stable per campaign id). */
-function sampleBucket(campaignId: string): number {
-    return stableBucket(campaignId);
-}
-
-/**
- * Shared frequency-cap predicate for any throttled Engage surface (campaigns AND
- * in-app messages share the `Throttle` shape + persisted `CampaignThrottleState`).
- * Pure: no side effects. `id` is used only for the stable `samplePct` bucket.
- */
-function passesThrottle(
-    id: string,
-    throttle: Throttle | undefined,
-    state: CampaignThrottleState,
-    now: number,
-    revision?: string,
-): boolean {
-    // Revision invalidation: if the live config carries a newer revision than the one
-    // the persisted state was recorded against, the campaign's content/design changed —
-    // the old impression/showOnce/cooldown counters are stale and must not suppress the
-    // updated message. Treat it as never-shown. (Legacy state with no revision is
-    // unaffected — the check only fires when BOTH sides carry a revision.)
-    if (revision !== undefined && state.revision !== undefined && state.revision !== revision) {
-        return true;
-    }
-    if (!throttle) {
-        // No throttle config: still respect a prior completion so we never loop.
-        return !state.completed;
-    }
-
-    // showOnce: never re-show after a successful submit, or after first impression.
-    if (throttle.showOnce && (state.completed || state.impressions >= 1)) {
-        return false;
-    }
-
-    // maxImpressions: hard cap on how many times we render.
-    if (typeof throttle.maxImpressions === 'number' && state.impressions >= throttle.maxImpressions) {
-        return false;
-    }
-
-    // cooldownHours: enforce a quiet window since the last impression.
-    if (typeof throttle.cooldownHours === 'number' && state.lastShownAt > 0) {
-        const elapsedMs = now - state.lastShownAt;
-        if (elapsedMs < throttle.cooldownHours * 60 * 60 * 1000) {
-            return false;
-        }
-    }
-
-    // samplePct: include only a stable percentage slice of users/campaigns.
-    if (typeof throttle.samplePct === 'number' && throttle.samplePct < 100) {
-        if (sampleBucket(id) >= Math.max(0, throttle.samplePct)) {
-            return false;
-        }
-    }
-
-    // A completed surface without showOnce is still done — don't re-show.
-    return !state.completed;
-}
-
-/**
- * Decide whether a single campaign is eligible to show right now, given its
- * `throttle` rules and the persisted impression state. Pure: no side effects.
- */
-export function isCampaignEligible(
-    campaign: EngageCampaignConfig,
-    state: CampaignThrottleState,
-    now: number = Date.now(),
-): boolean {
-    if (!campaign.enabled) return false;
-    return passesThrottle(campaign.id, campaign.throttle, state, now);
-}
-
-/**
- * Decide whether a single in-app message is eligible to show right now. In-app
- * messages have no `enabled` flag (the config-serve lane only returns active ones,
- * §2.4) — eligibility is purely the SHARED throttle/frequency-cap rules. So an
- * impression-capped message is never re-shown, exactly like a campaign.
- */
-export function isInAppEligible(
-    message: InAppMessageConfig,
-    state: CampaignThrottleState,
-    now: number = Date.now(),
-): boolean {
-    return passesThrottle(message.id, message.throttle, state, now, message.revision);
-}
-
-/**
- * Pick the FIRST eligible campaign from a config payload, optionally filtered by
- * a campaign type whitelist (e.g. `['NPS']` for the NPS-first slice) and/or a
- * `targetScreen`. This is the renderer's config→render decision: config drives
- * which prompt shows, throttle decides whether it shows at all.
- */
-export function selectCampaignToRender(
-    campaigns: EngageCampaignConfig[],
-    store: EngageThrottleStore,
-    options: {
-        types?: EngageCampaignConfig['type'][];
-        screen?: string;
-        /**
-         * When set, only campaigns whose `trigger` equals this value match — the
-         * behavioral-trigger path (e.g. `'screen_exit'`). Omitted ⇒ trigger-agnostic
-         * (the manual `showEngagePrompt()` path fires any eligible campaign).
-         */
-        trigger?: string;
-        /**
-         * Event name for the `custom_event` trigger (and `after_purchase`). When set,
-         * only campaigns whose `triggerConfig.event` matches are eligible.
-         */
-        event?: string;
-        /**
-         * Action label for the `failed_action` trigger (Payment/Login/…). When set,
-         * only campaigns whose `triggerConfig.action` matches are eligible.
-         */
-        action?: string;
-        /** Exact fired `time_in_app` timer threshold. */
-        seconds?: number;
-        now?: number;
-    } = {},
-): EngageCampaignConfig | null {
-    const now = options.now ?? Date.now();
-    for (const campaign of campaigns) {
-        if (options.types && !options.types.includes(campaign.type)) continue;
-        if (options.trigger && campaign.trigger !== options.trigger) continue;
-        if (options.screen && campaign.targetScreen && campaign.targetScreen !== options.screen) {
-            continue;
-        }
-        // Event/action targeting: a configured target must match the fired value.
-        // Unconfigured campaigns (no triggerConfig.event/action) stay trigger-agnostic.
-        if (options.event && campaign.triggerConfig?.event && campaign.triggerConfig.event !== options.event) {
-            continue;
-        }
-        if (options.action && campaign.triggerConfig?.action && campaign.triggerConfig.action !== options.action) {
-            continue;
-        }
-        if (
-            options.trigger === 'time_in_app' &&
-            typeof options.seconds === 'number' &&
-            typeof campaign.triggerConfig?.seconds === 'number' &&
-            campaign.triggerConfig.seconds !== options.seconds
-        ) continue;
-        if (isCampaignEligible(campaign, store.get(campaign.id), now)) {
-            return campaign;
-        }
-    }
-    return null;
-}
-
-/**
- * Pick the FIRST eligible in-app message from a config payload (`inAppMessages[]`,
- * §2.4), optionally filtered by `targetScreen`. Mirrors `selectCampaignToRender`:
- * config drives which message shows, the SHARED throttle decides whether it shows
- * at all (an impression-capped message isn't reshown).
- */
-export function selectInAppToRender(
-    messages: InAppMessageConfig[],
-    store: EngageThrottleStore,
-    options: {
-        screen?: string;
-        trigger?: string;
-        event?: string;
-        action?: string;
-        seconds?: number;
-        now?: number;
-    } = {},
-): InAppMessageConfig | null {
-    const now = options.now ?? Date.now();
-    for (const message of messages) {
-        // Behavioral-trigger path: only messages whose `trigger` matches the fired
-        // trigger are eligible. A message with no configured trigger is manual-only
-        // (never auto-fired). When `options.trigger` is omitted (manual call), any
-        // eligible message qualifies — preserving the existing host-driven behavior.
-        if (
-            options.trigger &&
-            normalizeInAppTrigger(message.trigger) !== normalizeInAppTrigger(options.trigger)
-        ) {
-            continue;
-        }
-        const targetScreen = message.targetScreen ?? message.screenName;
-        if (options.screen && targetScreen && targetScreen !== options.screen) {
-            continue;
-        }
-        if (options.event && message.eventName && message.eventName !== options.event) continue;
-        const actionName = (message as InAppMessageConfig & { action?: string }).action;
-        if (options.action && actionName && actionName !== options.action) continue;
-        if (
-            normalizeInAppTrigger(options.trigger) === 'time_in_app' &&
-            message.trigger === 'time_delay' &&
-            typeof options.seconds === 'number' &&
-            message.delaySeconds !== options.seconds
-        ) continue;
-        if (isInAppEligible(message, store.get(message.id), now)) {
-            return message;
-        }
-    }
-    return null;
-}
-
-/** Dashboard trigger aliases normalized onto the SDK signal names. */
-export function normalizeInAppTrigger(trigger?: string): string | undefined {
-    switch (trigger) {
-        case 'event':
-        case 'custom':
-            return 'custom_event';
-        case 'time_delay':
-            return 'time_in_app';
-        default:
-            return trigger;
-    }
-}
-
-/** Resolve the one-shot dedupe key for a test preview (testRunId → previewId → id). */
-export function testRunIdOf(message: InAppMessageConfig): string {
-    return message.testRunId ?? message.previewId ?? message.id;
-}
-
-/**
- * [T1] Pure one-shot test-preview selection — the testable core of the renderer's
- * "show the latest UNSEEN test, never re-show a dismissed/displayed one" rule.
- *
- * From a fetched config's messages it:
- *   1. keeps only test previews (`preview` / `isTest`),
- *   2. de-dupes by `testRunId` (the SAME run served twice collapses to one),
- *   3. drops any already DISPLAYED-or-DISMISSED run (persistent `seen`, survives cold
- *      restart) or closed-this-session run (`consumed`, in-memory),
- *   4. returns the LATEST remaining by `createdAt` (so old tests never stack up).
- *
- * `seen`/`consumed` are injected predicates (the provider passes its persistent
- * `EngageTestSeenStore` and its session `Set`), so this stays React-free and unit-
- * testable. Returns `null` when nothing eligible remains.
- */
-export function selectLatestUnseenTest(
-    messages: InAppMessageConfig[],
-    deps: { seen: (runId: string) => boolean; consumed: (key: string) => boolean },
-): InAppMessageConfig | null {
-    const previews = messages.filter((m) => m.preview === true || m.isTest === true);
-    if (previews.length === 0) return null;
-    // De-dupe by testRunId first so a config that (wrongly) serves the same run twice
-    // can never enqueue it twice — keep the first occurrence.
-    const byRun = new Map<string, InAppMessageConfig>();
-    for (const m of previews) {
-        const runId = testRunIdOf(m);
-        if (!byRun.has(runId)) byRun.set(runId, m);
-    }
-    const eligible = [...byRun.values()].filter((m) => {
-        const runId = testRunIdOf(m);
-        if (deps.seen(runId)) return false;
-        if (deps.consumed(m.previewId ?? m.id)) return false;
-        return true;
-    });
-    if (eligible.length === 0) return null;
-    return eligible.sort(
-        (a, b) =>
-            new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime(),
-    )[0];
-}
-
-/**
- * Resolve the A/B experiment arm for an in-app message (D8/J6). Minimal,
- * deterministic, side-effect-free — NOT a general experimentation framework.
- *
- * - No experiment, disabled, or no `variantB` ⇒ variant `A` (the base `spec`).
- * - Otherwise the user/device is bucketed 0–99 by a STABLE hash of
- *   `messageId + ':' + deviceId`, so the same device always sees the same arm
- *   for a given message (and the message id salts the hash so a device is not
- *   pinned to the same arm across every experiment). Buckets `< split` get
- *   variant B; the rest get variant A. `split<=0`⇒all A, `split>=100`⇒all B.
- *
- * Returns both the chosen `variant` id (for event attribution) and the `spec`
- * to render, so callers never re-derive which arm won.
- */
-export function selectInAppVariant(
-    message: InAppMessageConfig,
-    deviceId: string,
-): { variant: InAppVariantId; spec: InAppRenderSpec } {
-    const exp = message.experiment;
-    if (!exp || !exp.enabled || !exp.variantB) {
-        return { variant: 'A', spec: message.spec };
-    }
-    const split = Math.max(0, Math.min(100, exp.split));
-    if (split <= 0) return { variant: 'A', spec: message.spec };
-    if (split >= 100) return { variant: 'B', spec: exp.variantB };
-    const bucket = stableBucket(`${message.id}:${deviceId}`);
-    return bucket < split
-        ? { variant: 'B', spec: exp.variantB }
-        : { variant: 'A', spec: message.spec };
-}
+/**
+ * ScaleBun SDK — Engage Prompt Throttle + Decision Logic
+ *
+ * Pure, presentation-free logic that the shared cross-platform JS overlay (D4)
+ * uses to decide WHICH campaign (if any) to render from a fetched
+ * `EngageConfigResponse`, honoring each campaign's `throttle`/`Throttle` rules
+ * (§1.3) so a user is never re-prompted on every render.
+ *
+ * State (per-campaign impression count + last-shown timestamp) is persisted via
+ * the same synchronous KV backend used for the device id, so frequency capping
+ * survives app restarts. No React, no `any`, no network — this is the testable
+ * core of the renderer's Open/Closed decision seam.
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
+import type {
+    EngageCampaignConfig,
+    InAppMessageConfig,
+    InAppRenderSpec,
+    InAppVariantId,
+    Throttle,
+} from './engageTypes';
+
+/** Persisted frequency-capping state for a single campaign. */
+export interface CampaignThrottleState {
+    /** Number of times this campaign has been shown (impressions). */
+    impressions: number;
+    /** Epoch ms of the last impression — drives `cooldownHours`. */
+    lastShownAt: number;
+    /** Set once a response was submitted — hard stop for `showOnce`. */
+    completed: boolean;
+    /**
+     * Content revision this state was recorded against. When the live config carries
+     * a NEWER revision (author changed the campaign's design/content/type), the prior
+     * impression/showOnce/cooldown state is stale and must NOT suppress the updated
+     * message — see `passesThrottle`. Absent on legacy state ⇒ revision check is skipped.
+     */
+    revision?: string;
+}
+
+const STORAGE_PREFIX = 'scalebun_engage_throttle:';
+
+/**
+ * Persistent, restart-surviving store for per-campaign throttle state. Backed by
+ * the shared first-party StorageBackend (durable native store, memory only as an
+ * emergency fallback), so frequency caps hold across sessions exactly like the
+ * device id.
+ */
+export class EngageThrottleStore {
+    private readonly backend: StorageBackend;
+    /**
+     * Shows in THIS session, backing `maxImpressionsPerSession`.
+     *
+     * Deliberately in-memory rather than persisted: on mobile a session is an app run, and this
+     * store is constructed once per provider mount, so the map's lifetime already is the session's.
+     * Persisting it would outlive the session it is meant to bound.
+     */
+    private readonly sessionShows = new Map<string, number>();
+
+    constructor(backend: StorageBackend = createStorageBackend()) {
+        this.backend = backend;
+    }
+
+    /** How many times this surface has been shown in the current session. */
+    sessionShowCount(campaignId: string): number {
+        return this.sessionShows.get(campaignId) ?? 0;
+    }
+
+    private keyFor(campaignId: string): string {
+        return `${STORAGE_PREFIX}${campaignId}`;
+    }
+
+    /** Read the persisted state for a campaign (zeroed default when absent). */
+    get(campaignId: string): CampaignThrottleState {
+        try {
+            const raw = this.backend.get(this.keyFor(campaignId));
+            if (raw) {
+                const parsed = JSON.parse(raw) as Partial<CampaignThrottleState>;
+                return {
+                    impressions: typeof parsed.impressions === 'number' ? parsed.impressions : 0,
+                    lastShownAt: typeof parsed.lastShownAt === 'number' ? parsed.lastShownAt : 0,
+                    completed: parsed.completed === true,
+                    revision: typeof parsed.revision === 'string' ? parsed.revision : undefined,
+                };
+            }
+        } catch (err) {
+            logger.debug('[Engage] throttle state read failed:', (err as Error)?.message);
+        }
+        return { impressions: 0, lastShownAt: 0, completed: false };
+    }
+
+    /** Delete one campaign's persisted throttle state (debug/dev reset, or per-id clear). */
+    clearOne(campaignId: string): void {
+        try {
+            this.backend.delete(this.keyFor(campaignId));
+        } catch (err) {
+            logger.debug('[Engage] throttle clearOne failed:', (err as Error)?.message);
+        }
+    }
+
+    /**
+     * Delete ALL persisted in-app/campaign throttle state (every `scalebun_engage_throttle:*`
+     * key). Backs the public `ScaleBun.engage.resetInAppState()` debug reset — clears
+     * dismissed/impression/cooldown/showOnce so a tester sees messages again WITHOUT an
+     * uninstall. Does NOT touch the device id (a separate key) — identity is preserved.
+     */
+    clearAll(): number {
+        let n = 0;
+        try {
+            for (const key of this.backend.getAllKeys()) {
+                if (key.startsWith(STORAGE_PREFIX)) {
+                    this.backend.delete(key);
+                    n += 1;
+                }
+            }
+        } catch (err) {
+            logger.debug('[Engage] throttle clearAll failed:', (err as Error)?.message);
+        }
+        return n;
+    }
+
+    private write(campaignId: string, state: CampaignThrottleState): void {
+        try {
+            this.backend.set(this.keyFor(campaignId), JSON.stringify(state));
+        } catch (err) {
+            logger.debug('[Engage] throttle state write failed:', (err as Error)?.message);
+        }
+    }
+
+    /**
+     * Record that a campaign was shown (bumps impressions + last-shown time). When a
+     * `revision` is supplied and differs from the stored one, the prior counters are a
+     * stale (pre-edit) generation and reset to a single fresh impression — so changing a
+     * campaign's content never inherits the old cap.
+     */
+    recordImpression(campaignId: string, now: number = Date.now(), revision?: string): void {
+        const prev = this.get(campaignId);
+        const fresh = revision !== undefined && prev.revision !== undefined && prev.revision !== revision;
+        this.write(campaignId, {
+            impressions: fresh ? 1 : prev.impressions + 1,
+            lastShownAt: now,
+            completed: fresh ? false : prev.completed,
+            revision: revision ?? prev.revision,
+        });
+        // A new revision is a new design: its session count starts over with its durable counters.
+        this.sessionShows.set(campaignId, fresh ? 1 : this.sessionShowCount(campaignId) + 1);
+    }
+
+    /**
+     * Mark a campaign as completed (response submitted, or an in-app message closed) — a hard stop.
+     *
+     * The `revision` MUST be carried through. This wrote the record without one, which silently
+     * disabled the revision check in `passesThrottle` for the rest of that campaign's life on the
+     * device: that check only fires when BOTH the live config and the stored state carry a revision,
+     * so a state stamped `undefined` can never be invalidated. The result was the exact opposite of
+     * the web bug — once a user closed an in-app message, editing the campaign could never bring the
+     * new version back to them. Callers that know the served revision pass it; legacy callers that
+     * don't keep whatever was already stored rather than erasing it.
+     */
+    markCompleted(campaignId: string, now: number = Date.now(), revision?: string): void {
+        const prev = this.get(campaignId);
+        this.write(campaignId, {
+            impressions: prev.impressions,
+            lastShownAt: prev.lastShownAt || now,
+            completed: true,
+            revision: revision ?? prev.revision,
+        });
+    }
+}
+
+/** Deterministic 0–99 bucket for a string seed (stable across sessions/devices). */
+function stableBucket(seed: string): number {
+    let hash = 0;
+    for (let i = 0; i < seed.length; i += 1) {
+        hash = (hash * 31 + seed.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash) % 100;
+}
+
+/** Deterministic 0–99 bucket for `samplePct` gating (stable per campaign id). */
+function sampleBucket(campaignId: string): number {
+    return stableBucket(campaignId);
+}
+
+/**
+ * Shared frequency-cap predicate for any throttled Engage surface (campaigns AND
+ * in-app messages share the `Throttle` shape + persisted `CampaignThrottleState`).
+ * Pure: no side effects. `id` is used only for the stable `samplePct` bucket.
+ */
+function passesThrottle(
+    id: string,
+    throttle: Throttle | undefined,
+    state: CampaignThrottleState,
+    now: number,
+    revision?: string,
+    sessionShows = 0,
+): boolean {
+    // Revision invalidation: if the live config carries a newer revision than the one
+    // the persisted state was recorded against, the campaign's content/design changed —
+    // the old impression/showOnce/cooldown counters are stale and must not suppress the
+    // updated message. Treat it as never-shown. (Legacy state with no revision is
+    // unaffected — the check only fires when BOTH sides carry a revision.)
+    if (revision !== undefined && state.revision !== undefined && state.revision !== revision) {
+        return true;
+    }
+    if (!throttle) {
+        // No throttle config: still respect a prior completion so we never loop.
+        return !state.completed;
+    }
+
+    // showOnce: never re-show after a successful submit, or after first impression.
+    if (throttle.showOnce && (state.completed || state.impressions >= 1)) {
+        return false;
+    }
+
+    // maxImpressions: hard cap on how many times we render.
+    if (typeof throttle.maxImpressions === 'number' && state.impressions >= throttle.maxImpressions) {
+        return false;
+    }
+
+    // maxImpressionsPerSession: cap within this app run, under any lifetime cap above.
+    if (
+        typeof throttle.maxImpressionsPerSession === 'number' &&
+        throttle.maxImpressionsPerSession > 0 &&
+        sessionShows >= throttle.maxImpressionsPerSession
+    ) {
+        return false;
+    }
+
+    // cooldownHours: enforce a quiet window since the last impression.
+    if (typeof throttle.cooldownHours === 'number' && state.lastShownAt > 0) {
+        const elapsedMs = now - state.lastShownAt;
+        if (elapsedMs < throttle.cooldownHours * 60 * 60 * 1000) {
+            return false;
+        }
+    }
+
+    // samplePct: include only a stable percentage slice of users/campaigns.
+    if (typeof throttle.samplePct === 'number' && throttle.samplePct < 100) {
+        if (sampleBucket(id) >= Math.max(0, throttle.samplePct)) {
+            return false;
+        }
+    }
+
+    // A completed surface without showOnce is still done — don't re-show.
+    return !state.completed;
+}
+
+/**
+ * Decide whether a single campaign is eligible to show right now, given its
+ * `throttle` rules and the persisted impression state. Pure: no side effects.
+ */
+export function isCampaignEligible(
+    campaign: EngageCampaignConfig,
+    state: CampaignThrottleState,
+    now: number = Date.now(),
+    sessionShows = 0,
+): boolean {
+    if (!campaign.enabled) return false;
+    return passesThrottle(campaign.id, campaign.throttle, state, now, undefined, sessionShows);
+}
+
+/**
+ * Decide whether a single in-app message is eligible to show right now. In-app
+ * messages have no `enabled` flag (the config-serve lane only returns active ones,
+ * §2.4) — eligibility is purely the SHARED throttle/frequency-cap rules. So an
+ * impression-capped message is never re-shown, exactly like a campaign.
+ */
+export function isInAppEligible(
+    message: InAppMessageConfig,
+    state: CampaignThrottleState,
+    now: number = Date.now(),
+    sessionShows = 0,
+): boolean {
+    return passesThrottle(message.id, message.throttle, state, now, message.revision, sessionShows);
+}
+
+/**
+ * Pick the FIRST eligible campaign from a config payload, optionally filtered by
+ * a campaign type whitelist (e.g. `['NPS']` for the NPS-first slice) and/or a
+ * `targetScreen`. This is the renderer's config→render decision: config drives
+ * which prompt shows, throttle decides whether it shows at all.
+ */
+export function selectCampaignToRender(
+    campaigns: EngageCampaignConfig[],
+    store: EngageThrottleStore,
+    options: {
+        types?: EngageCampaignConfig['type'][];
+        screen?: string;
+        /**
+         * When set, only campaigns whose `trigger` equals this value match — the
+         * behavioral-trigger path (e.g. `'screen_exit'`). Omitted ⇒ trigger-agnostic
+         * (the manual `showEngagePrompt()` path fires any eligible campaign).
+         */
+        trigger?: string;
+        /**
+         * Event name for the `custom_event` trigger (and `after_purchase`). When set,
+         * only campaigns whose `triggerConfig.event` matches are eligible.
+         */
+        event?: string;
+        /**
+         * Action label for the `failed_action` trigger (Payment/Login/…). When set,
+         * only campaigns whose `triggerConfig.action` matches are eligible.
+         */
+        action?: string;
+        /** Exact fired `time_in_app` timer threshold. */
+        seconds?: number;
+        now?: number;
+    } = {},
+): EngageCampaignConfig | null {
+    const now = options.now ?? Date.now();
+    for (const campaign of campaigns) {
+        if (options.types && !options.types.includes(campaign.type)) continue;
+        if (options.trigger && campaign.trigger !== options.trigger) continue;
+        if (options.screen && campaign.targetScreen && campaign.targetScreen !== options.screen) {
+            continue;
+        }
+        // Event/action targeting: a configured target must match the fired value.
+        // Unconfigured campaigns (no triggerConfig.event/action) stay trigger-agnostic.
+        if (options.event && campaign.triggerConfig?.event && campaign.triggerConfig.event !== options.event) {
+            continue;
+        }
+        if (options.action && campaign.triggerConfig?.action && campaign.triggerConfig.action !== options.action) {
+            continue;
+        }
+        if (
+            options.trigger === 'time_in_app' &&
+            typeof options.seconds === 'number' &&
+            typeof campaign.triggerConfig?.seconds === 'number' &&
+            campaign.triggerConfig.seconds !== options.seconds
+        ) continue;
+        if (isCampaignEligible(campaign, store.get(campaign.id), now, store.sessionShowCount(campaign.id))) {
+            return campaign;
+        }
+    }
+    return null;
+}
+
+/**
+ * Pick the FIRST eligible in-app message from a config payload (`inAppMessages[]`,
+ * §2.4), optionally filtered by `targetScreen`. Mirrors `selectCampaignToRender`:
+ * config drives which message shows, the SHARED throttle decides whether it shows
+ * at all (an impression-capped message isn't reshown).
+ */
+export function selectInAppToRender(
+    messages: InAppMessageConfig[],
+    store: EngageThrottleStore,
+    options: {
+        screen?: string;
+        trigger?: string;
+        event?: string;
+        action?: string;
+        seconds?: number;
+        now?: number;
+    } = {},
+): InAppMessageConfig | null {
+    const now = options.now ?? Date.now();
+    for (const message of messages) {
+        // Behavioral-trigger path: only messages whose `trigger` matches the fired
+        // trigger are eligible. A message with no configured trigger is manual-only
+        // (never auto-fired). When `options.trigger` is omitted (manual call), any
+        // eligible message qualifies — preserving the existing host-driven behavior.
+        if (
+            options.trigger &&
+            normalizeInAppTrigger(message.trigger) !== normalizeInAppTrigger(options.trigger)
+        ) {
+            continue;
+        }
+        const targetScreen = message.targetScreen ?? message.screenName;
+        if (options.screen && targetScreen && targetScreen !== options.screen) {
+            continue;
+        }
+        if (options.event && message.eventName && message.eventName !== options.event) continue;
+        const actionName = (message as InAppMessageConfig & { action?: string }).action;
+        if (options.action && actionName && actionName !== options.action) continue;
+        if (
+            normalizeInAppTrigger(options.trigger) === 'time_in_app' &&
+            message.trigger === 'time_delay' &&
+            typeof options.seconds === 'number' &&
+            message.delaySeconds !== options.seconds
+        ) continue;
+        if (isInAppEligible(message, store.get(message.id), now, store.sessionShowCount(message.id))) {
+            return message;
+        }
+    }
+    return null;
+}
+
+/** Dashboard trigger aliases normalized onto the SDK signal names. */
+export function normalizeInAppTrigger(trigger?: string): string | undefined {
+    switch (trigger) {
+        case 'event':
+        case 'custom':
+            return 'custom_event';
+        case 'time_delay':
+            return 'time_in_app';
+        default:
+            return trigger;
+    }
+}
+
+/** Resolve the one-shot dedupe key for a test preview (testRunId → previewId → id). */
+export function testRunIdOf(message: InAppMessageConfig): string {
+    return message.testRunId ?? message.previewId ?? message.id;
+}
+
+/**
+ * [T1] Pure one-shot test-preview selection — the testable core of the renderer's
+ * "show the latest UNSEEN test, never re-show a dismissed/displayed one" rule.
+ *
+ * From a fetched config's messages it:
+ *   1. keeps only test previews (`preview` / `isTest`),
+ *   2. de-dupes by `testRunId` (the SAME run served twice collapses to one),
+ *   3. drops any already DISPLAYED-or-DISMISSED run (persistent `seen`, survives cold
+ *      restart) or closed-this-session run (`consumed`, in-memory),
+ *   4. returns the LATEST remaining by `createdAt` (so old tests never stack up).
+ *
+ * `seen`/`consumed` are injected predicates (the provider passes its persistent
+ * `EngageTestSeenStore` and its session `Set`), so this stays React-free and unit-
+ * testable. Returns `null` when nothing eligible remains.
+ */
+export function selectLatestUnseenTest(
+    messages: InAppMessageConfig[],
+    deps: { seen: (runId: string) => boolean; consumed: (key: string) => boolean },
+): InAppMessageConfig | null {
+    const previews = messages.filter((m) => m.preview === true || m.isTest === true);
+    if (previews.length === 0) return null;
+    // De-dupe by testRunId first so a config that (wrongly) serves the same run twice
+    // can never enqueue it twice — keep the first occurrence.
+    const byRun = new Map<string, InAppMessageConfig>();
+    for (const m of previews) {
+        const runId = testRunIdOf(m);
+        if (!byRun.has(runId)) byRun.set(runId, m);
+    }
+    const eligible = [...byRun.values()].filter((m) => {
+        const runId = testRunIdOf(m);
+        if (deps.seen(runId)) return false;
+        if (deps.consumed(m.previewId ?? m.id)) return false;
+        return true;
+    });
+    if (eligible.length === 0) return null;
+    return eligible.sort(
+        (a, b) =>
+            new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime(),
+    )[0];
+}
+
+/**
+ * Resolve the A/B experiment arm for an in-app message (D8/J6). Minimal,
+ * deterministic, side-effect-free — NOT a general experimentation framework.
+ *
+ * - No experiment, disabled, or no `variantB` ⇒ variant `A` (the base `spec`).
+ * - Otherwise the user/device is bucketed 0–99 by a STABLE hash of
+ *   `messageId + ':' + deviceId`, so the same device always sees the same arm
+ *   for a given message (and the message id salts the hash so a device is not
+ *   pinned to the same arm across every experiment). Buckets `< split` get
+ *   variant B; the rest get variant A. `split<=0`⇒all A, `split>=100`⇒all B.
+ *
+ * Returns both the chosen `variant` id (for event attribution) and the `spec`
+ * to render, so callers never re-derive which arm won.
+ */
+export function selectInAppVariant(
+    message: InAppMessageConfig,
+    deviceId: string,
+): { variant: InAppVariantId; spec: InAppRenderSpec } {
+    const exp = message.experiment;
+    if (!exp || !exp.enabled || !exp.variantB) {
+        return { variant: 'A', spec: message.spec };
+    }
+    const split = Math.max(0, Math.min(100, exp.split));
+    if (split <= 0) return { variant: 'A', spec: message.spec };
+    if (split >= 100) return { variant: 'B', spec: exp.variantB };
+    const bucket = stableBucket(`${message.id}:${deviceId}`);
+    return bucket < split
+        ? { variant: 'B', spec: exp.variantB }
+        : { variant: 'A', spec: message.spec };
+}