@scalebun-release/react-native 2.5.0

package/src/features/session/ReplayCaptureManager.ts

@@ -0,0 +1,1401 @@
+/**
+ * ScaleBun SDK — Replay Capture Manager
+ *
+ * Orchestration-only component for frame capture:
+ * - Decides WHEN to capture (navigation, interaction, scroll, loading, frequency triggers)
+ * - Delegates ALL frame capture to native engines via sessionReplayAdapter
+ * - NEVER performs screenshot logic itself
+ * - If native capture unavailable, returns null and logs warning
+ * - Manages frame retention with crash-adjacent priority
+ * - Uses session-bound generation guard to invalidate stale async work
+ * - All pending timers are cancelled on stop()
+ *
+ * Semantic Capture Coordination:
+ * - Tracks the last completed capture's reason + screen to prevent semantic duplicates
+ * - Navigation supersedes pending interaction for the SAME screen (interaction is already
+ *   visually represented by the navigation frame)
+ * - Loading completion for the SAME screen coalesces with a pending navigation capture
+ *   by cancelling the navigation capture (loading's delayed capture shows the final state)
+ * - Scroll captures have per-cycle identity and do not conflict with navigation/loading
+ * - Manual and error-context captures ALWAYS bypass coordination (explicit intent)
+ * - Genuinely distinct states (different screens, different reasons after settle) are never deduped
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import type {
+    ReplayFrame,
+    CaptureMode,
+    CaptureReason,
+    ReplayQuality,
+    SessionReplayConfig,
+    PrivacyPolicy,
+    NativeFrameResult,
+} from './sessionTypes';
+import {
+    FrameRetentionPriority,
+    getFrameRetentionPriority,
+    QUALITY_PRESETS,
+} from './sessionTypes';
+import type { PlatformOS } from '../../core/context/device';
+import type { FrameScrollEntry } from './frameScrollState';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Native capture function provided by the adapter layer.
+ * Calls the platform native engine (PixelCopy on Android, UIWindow on iOS).
+ * Returns null if native capture is unavailable.
+ */
+export type NativeCaptureFn = (
+    sessionId: string,
+    reason: string,
+    quality: ReplayQuality,
+) => Promise<NativeFrameResult | null>;
+
+export type FrameEmitCallback = (frame: ReplayFrame, imageData: string) => void;
+
+/**
+ * How a wait ended. Named for what was OBSERVED, not for what it probably meant.
+ *
+ * `network_idle` is the only one that says the screen arrived, and even that is an inference from
+ * quiet rather than a look at the pixels. `timeout` is its opposite and must never be collapsed
+ * into it: the cap expired with requests still outstanding, so the screen was still loading when
+ * we gave up waiting and photographed it anyway. A band drawn from a `timeout` is evidence of a
+ * slow or stuck screen; one drawn from `network_idle` is evidence of an ordinary load.
+ */
+export type LoadingEndReason =
+    | 'network_idle'
+    | 'timeout'
+    | 'superseded'
+    | 'session_end'
+    /** Capture paused mid-session by a `frames` quota block — the session did NOT end. */
+    | 'quota_pause';
+
+/**
+ * Reports a wait the capture manager sat through, so it can be recorded as a journey event.
+ * Two calls per wait — one `start`, one `end` — and NO calls at all when nothing was held,
+ * which is the common case and the reason this costs almost nothing.
+ */
+export type LoadingIntervalCallback = (
+    phase: 'start' | 'end',
+    screen: string | undefined,
+    detail: { durationMs?: number; reason?: LoadingEndReason },
+) => void;
+
+// ─── Native File-Outbox staged capture ───────────────────────────────────────
+
+/**
+ * Metadata returned by a native STAGED capture-to-file. The image bytes are
+ * already written to the native outbox (staged, not yet uploadable) — they NEVER
+ * cross the bridge. `frameHash` is a native content hash so JS change-detection
+ * works without base64.
+ */
+export interface StagedFrameResult {
+    frameId: string;
+    width: number;
+    height: number;
+    byteSize: number;
+    format: string;
+    contentType: string;
+    frameHash: string;
+    masked: boolean;
+    timestamp: number;
+    // Widened: frames now carry the REAL Platform.OS instead of being relabelled 'android'.
+    platform: PlatformOS;
+    /** Sanitized visible scroll containers at capture time; undefined = not measured. */
+    scrollState?: FrameScrollEntry[];
+}
+
+/** JS-authoritative frame metadata written to the outbox on commit. */
+export interface OutboxFrameMeta {
+    frameId: string;
+    sessionId: string;
+    timestamp: number;
+    sequenceNumber: number;
+    frameType: 'keyframe' | 'delta';
+    baseFrameId?: string;
+    screenName: string;
+    trigger: string;
+    format: string;
+    contentType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    masked: boolean;
+    /** Visible scroll containers at capture time — the native uploader forwards it verbatim. */
+    scrollState?: FrameScrollEntry[];
+}
+
+/**
+ * Native file-outbox frame capture. `capture` stages an image and returns metadata
+ * only (or null when the outbox is off / capture fails → caller falls back to the
+ * legacy native capture). `commit` writes the JS-decided meta (making the frame
+ * uploadable); `discard` drops a staged frame the orchestrator suppressed.
+ */
+export interface OutboxFrameCapture {
+    capture(
+        sessionId: string,
+        screenName: string | undefined,
+        trigger: string,
+    ): Promise<StagedFrameResult | null>;
+    commit(meta: OutboxFrameMeta): Promise<boolean>;
+    discard(sessionId: string, frameId: string): Promise<void>;
+}
+
+// ─── Capture Intent ─────────────────────────────────────────────────────────
+
+/**
+ * Represents the semantic identity of a completed capture.
+ * Used for dedup: two captures with the same intent fingerprint
+ * represent the same visual state and should not produce two frames.
+ */
+interface CaptureIntent {
+    reason: CaptureReason;
+    screen: string | undefined;
+    ts: number;
+}
+
+/**
+ * Reasons that always bypass semantic dedup.
+ * These are explicit user/system requests that should ALWAYS produce a frame.
+ */
+const BYPASS_DEDUP_REASONS: Set<CaptureReason> = new Set([
+    'manual',
+    'error-context',
+    'frequency',
+]);
+
+/**
+ * Minimum time (ms) between captures of the same semantic intent
+ * (same reason + same screen). Secondary heuristic only — the primary
+ * check is semantic (reason + screen identity).
+ */
+const SAME_INTENT_COOLDOWN_MS = 300;
+
+/**
+ * Time (ms) to defer an interaction capture before finalizing.
+ * If onScreenChange fires within this window (i.e. the tap caused navigation),
+ * the interaction capture is cancelled and absorbed into the navigation capture.
+ * If no navigation follows, the interaction captures normally after this delay.
+ * 200ms is long enough for most React navigation timings but short enough to feel instant.
+ */
+const INTERACTION_SETTLE_MS = 200;
+
+/**
+ * Grace window (ms) AFTER an interaction capture has already fired.
+ * If onScreenChange fires to a DIFFERENT screen within this window,
+ * the stale interaction frame is retroactively evicted and its tap
+ * metadata is carried forward to the navigation capture.
+ * Handles the intermittent case where navigation takes >INTERACTION_SETTLE_MS.
+ */
+const LATE_ABSORPTION_GRACE_MS = 400;
+
+/**
+ * ── WAITING FOR THE DATA, RATHER THAN PHOTOGRAPHING THE WAIT ────────────────────────────────────
+ *
+ * In `interactions` capture mode the only frames that exist are the ones a tap or a navigation
+ * produces, and both fire on a short render-settle timer. A screen that fetches anything therefore
+ * gets photographed mid-flight: the skeleton, the spinner, the empty list — and then nothing until
+ * the next tap, because nothing else triggers a capture. The replay is a sequence of loading
+ * states, which is exactly the complaint.
+ *
+ * The obvious fix — capture again when the data lands — doubles the frames for every screen that
+ * loads anything, which is the cost `interactions` mode was chosen to avoid. So the capture is
+ * DEFERRED instead of repeated: while the app has a request in flight the pending capture waits,
+ * and it fires once the network goes quiet and the render that follows has settled. One frame per
+ * interaction, as before; taken when there is something to see.
+ *
+ * `NETWORK_QUIET_MS` is the pause after the LAST response before the screen is considered
+ * arrived — long enough for the app to parse the body and re-render, short enough not to be felt.
+ * `LOADING_DEFER_CAP_MS` bounds the whole wait: past it we capture whatever is on screen, because
+ * a request that never returns is itself the thing worth seeing, and an unbounded defer would mean
+ * a tap that produced no frame at all.
+ */
+const NETWORK_QUIET_MS = 300;
+const LOADING_DEFER_CAP_MS = 4_000;
+
+/**
+ * Activity sampling — the motion BETWEEN interaction frames, without a standing timer.
+ *
+ * `interactions` mode emits one frame per tap / navigation / scroll-settle / load. Everything that
+ * moves after that frame — a sheet sliding in, a list populating, a toast, a carousel settling — has
+ * no frame until the next touch, so replays play as a slideshow (median gap 1.34s, p90 5.8s on prod,
+ * 2026-09-23). The old `frequency` mode fixed that by sampling forever, which is the cost this mode
+ * exists to avoid.
+ *
+ * Instead, each semantic frame opens a short WINDOW. Inside it the screen is sampled every
+ * ACTIVITY_SAMPLE_INTERVAL_MS through the `frequency` lane, which already carries change detection
+ * (P2-1 below): a sample whose hash matches the last frame is discarded from the outbox before it is
+ * ever uploaded. The window closes at whichever comes first — its length, ACTIVITY_MAX_SAMPLES
+ * emitted, or ACTIVITY_SETTLED_STREAK unchanged samples in a row (the screen stopped moving). An idle
+ * screen therefore uploads ZERO extra frames, and a busy one at most ACTIVITY_MAX_SAMPLES per semantic
+ * frame. ACTIVITY_MAX_PER_MINUTE bounds a pathological screen (an endless animation under constant
+ * tapping).
+ *
+ * Samples are encoded at the SAME quality as every other frame, deliberately: the native frameHash
+ * is FNV-1a over the ENCODED bytes, so a lighter sample of an unchanged screen would hash differently
+ * from the frame before it and upload anyway — defeating the whole gate.
+ *
+ * The first sample lands AFTER LATE_ABSORPTION_GRACE_MS on purpose: a sample clears the
+ * late-absorption tracker, and must not do so while a tap → navigation can still claim it.
+ */
+const ACTIVITY_SAMPLE_INTERVAL_MS = 500;
+const ACTIVITY_WINDOW_MS = 2_500;
+const ACTIVITY_MAX_SAMPLES = 3;
+const ACTIVITY_SETTLED_STREAK = 2;
+const ACTIVITY_MAX_PER_MINUTE = 30;
+/** Semantic captures that open a sampling window. Samples themselves never do. */
+const ACTIVITY_OPENERS: ReadonlySet<CaptureReason> = new Set<CaptureReason>([
+    'interaction',
+    'navigation',
+    'scroll',
+    'screen_loaded',
+]);
+
+// ─── Manager ────────────────────────────────────────────────────────────────
+
+export class ReplayCaptureManager {
+    private sessionId: string;
+    private config: SessionReplayConfig;
+    private nativeCapture: NativeCaptureFn;
+    /** Optional native file-outbox path. When ready, frames stage→commit natively. */
+    private outboxCapture: OutboxFrameCapture | null;
+    private onFrameEmit: FrameEmitCallback | null = null;
+    private onLoadingInterval: LoadingIntervalCallback | null = null;
+
+    private frames: ReplayFrame[] = [];
+    /** Set of frameIds near crashes — never evict */
+    private protectedFrameIds = new Set<string>();
+    private frequencyTimer: ReturnType<typeof setInterval> | null = null;
+    private capturing = false;
+    private currentScreen: string | null = null;
+    private lastInteractionCapture = 0;
+
+    /**
+     * App network activity, as reported by the interceptors (SDK uploads and third-party
+     * beacons are filtered out upstream — see NetworkFeature). This is the only evidence the
+     * capture manager has that a screen is still waiting for something, and it is used for
+     * nothing but deciding WHEN to take the frame it was already going to take.
+     *
+     * Zero when network monitoring is disabled, which makes every hold below evaluate to "fire
+     * now" — the deferral costs nothing and changes nothing when there is no signal to act on.
+     */
+    private _inFlightRequests = 0;
+    private _lastRequestStartTs = 0;
+    private _lastRequestEndTs = 0;
+
+    /** Epoch ms past which a capture held for loading fires regardless. 0 when nothing is held. */
+    private pendingInteractionDeadline = 0;
+    private pendingNavDeadline = 0;
+    // Activity sampling (see ACTIVITY_SAMPLE_INTERVAL_MS). The window is owned by the capture
+    // generation it was opened in: stop() bumps the generation, so a tick that outlives it no-ops.
+    private activityTimer: ReturnType<typeof setTimeout> | null = null;
+    private activityGen = -1;
+    private activityWindowEnd = 0;
+    private activitySamples = 0;
+    private activityUnchangedStreak = 0;
+    private activityMinuteStart = 0;
+    private activityMinuteCount = 0;
+
+    /**
+     * When each lane's hold began, or 0 when that lane is not holding.
+     *
+     * ── WHY THE WAIT IS RECORDED AND NOT JUST WAITED OUT ──────────────────────────────────────
+     *
+     * Deferring the capture makes the replay show the loaded screen, which is the right picture —
+     * but between the tap and that frame the player has nothing, and `frameAt` resolves a playhead
+     * to the last frame at or before it. So the gap renders as the PREVIOUS screen, and the replay
+     * quietly asserts the visitor was still looking at it while they were in fact watching this one
+     * load. That is the same defect as a recording gap rendered as idle time: the reader cannot
+     * tell "nothing happened" from "we did not photograph it".
+     *
+     * The alternative — keep the skeleton frame as well — costs a whole mobile screenshot (~56 KB
+     * measured) against ~1 KB for the pair of events below, on a screen load where 37% of this
+     * product's loads would qualify. So the wait is recorded as an INTERVAL and the picture is not
+     * duplicated: the player draws the span, the operator sees that the screen was loading and for
+     * how long, and no frame claims to be something it is not.
+     */
+    private navHoldStartedAt = 0;
+    private interactionHoldStartedAt = 0;
+
+    /**
+     * Session-bound generation counter.
+     * Incremented on stop(). All async capture work checks this before AND after
+     * native capture to ensure stale callbacks from a previous session lifecycle
+     * do not emit frames into a new session.
+     */
+    private captureGeneration = 0;
+
+    /**
+     * Tracked navigation capture timeout.
+     * Cancelled on stop() and on each new onScreenChange() call (debounce).
+     */
+    private pendingNavTimeout: ReturnType<typeof setTimeout> | null = null;
+    /** Screen associated with the pending navigation capture */
+    private pendingNavScreen: string | null = null;
+
+    /**
+     * Tracked scroll settle capture timeout.
+     * Cancelled on stop().
+     */
+    private pendingScrollTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    /**
+     * Tracked loading end capture timeout.
+     * Cancelled on stop().
+     */
+    private pendingLoadingTimeout: ReturnType<typeof setTimeout> | null = null;
+    /** Screen associated with the pending loading capture */
+    private pendingLoadingScreen: string | null = null;
+
+    /**
+     * Pending interaction capture timeout.
+     * When a tap/gesture occurs, the capture is DEFERRED by INTERACTION_SETTLE_MS.
+     * If onScreenChange fires within that window (tap caused navigation), the
+     * pending interaction is cancelled and its tap metadata is carried forward
+     * to the navigation capture — ensuring the destination screen is captured
+     * instead of a stale pre-navigation screenshot.
+     * If no navigation follows, the interaction capture fires normally.
+     */
+    private pendingInteractionTimeout: ReturnType<typeof setTimeout> | null = null;
+    /** Interaction point metadata held while pending (carried to nav if absorbed) */
+    private pendingInteractionPoint: ReplayFrame['interactionPoint'] | undefined = undefined;
+    /** Screen at the time the pending interaction was created */
+    private pendingInteractionScreen: string | undefined = undefined;
+
+    /**
+     * Late absorption tracking.
+     * After an interaction capture fires, store its metadata so that
+     * a delayed onScreenChange can retroactively evict the stale frame
+     * and carry the tap metadata forward to the navigation capture.
+     */
+    private lastCompletedInteraction: {
+        frameId: string;
+        screen: string | undefined;
+        interactionPoint: ReplayFrame['interactionPoint'] | undefined;
+        ts: number;
+    } | null = null;
+
+    /**
+     * In-flight interaction tracking.
+     * Set when triggerCapture('interaction') starts the async native call and cleared
+     * when it completes. If onScreenChange fires for a DIFFERENT screen while a capture
+     * is in-flight, the capture is suppressed — the navigation frame is the correct state.
+     * Covers the race window between pendingInteractionTimeout firing and native returning,
+     * which neither pending-absorption nor late-absorption can reach.
+     */
+    private _inFlightInteractionScreen: string | undefined = undefined;
+    private _inFlightInteractionPoint: ReplayFrame['interactionPoint'] | undefined = undefined;
+    private _suppressInFlightInteraction = false;
+
+    /**
+     * Last completed capture intent — used for semantic dedup.
+     * Captures with the same reason + screen within SAME_INTENT_COOLDOWN_MS are suppressed.
+     */
+    private lastCaptureIntent: CaptureIntent | null = null;
+
+    // ── P2-0/1/5 capture state ──────────────────────────────────────────
+    /** P2-0: monotonic per-session sequence; first emitted frame is 1. */
+    private _sequenceCounter = 0;
+    /** P2-1: hash of the last EMITTED frame, for visual change detection. */
+    private _lastFrameHash: string | null = null;
+    /** P2-1/5: wall-clock of the last emitted keyframe (heartbeat base). */
+    private _lastKeyframeTs = 0;
+    /** Scroll containers visible in the last keyframe (native), so a tap's link to it can be checked. */
+    private _lastKeyframeScroll: FrameScrollEntry[] | undefined = undefined;
+    /** P2-5: frameId of the last emitted keyframe — delta base reference. */
+    private _lastKeyframeId: string | null = null;
+    /**
+     * Screen the last emitted keyframe was captured on.
+     *
+     * Tracked alongside the id purely so `currentKeyframe()` can refuse to hand a frame to an
+     * event on a different screen. The id and timestamp alone cannot answer that, and a frame
+     * from the previous screen is worse than none — it attaches a tap to a photograph of
+     * somewhere else, which every layer downstream would then present with full confidence.
+     */
+    private _lastKeyframeScreen: string | null = null;
+    /** P2-5: emitted frames since the last keyframe (keyframe-interval guard). */
+    private _framesSinceKeyframe = 0;
+
+    constructor(
+        sessionId: string,
+        config: SessionReplayConfig,
+        nativeCapture: NativeCaptureFn,
+        outboxCapture?: OutboxFrameCapture | null,
+    ) {
+        this.sessionId = sessionId;
+        this.config = config;
+        this.nativeCapture = nativeCapture;
+        this.outboxCapture = outboxCapture ?? null;
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────
+
+    /**
+     * The keyframe that is still showing, or null.
+     *
+     * Answers "which picture was the user looking at" for an event that is about to be emitted,
+     * so a tap can carry the id of the frame it happened ON. Read-only; captures nothing.
+     *
+     * TWO CONDITIONS, both refusals rather than approximations:
+     *
+     *   SAME SCREEN. A keyframe from the previous screen is not what the user was looking at.
+     *   Navigation evicts the pending capture rather than re-pointing it, so after a screen
+     *   change the newest keyframe genuinely belongs to somewhere else.
+     *
+     *   STILL FRESH. A screen mutates constantly — a list loads, a banner rotates, a sheet is
+     *   dismissed. Past `maxAgeMs` the stored picture stops being evidence of what is on screen,
+     *   and stale evidence presented as current is the failure mode this whole feature exists to
+     *   avoid. 10 s is deliberately conservative: the capture manager already photographs on
+     *   interaction, navigation and scroll settle, so a genuinely active screen refreshes well
+     *   inside it, and a screen quiet for longer than that is one nobody is interacting with.
+     *
+     * Returning null is a correct, common answer and downstream MUST treat it as "not captured"
+     * rather than as a default.
+     */
+    currentKeyframe(
+        screenName?: string,
+        maxAgeMs = 10_000,
+        now: number = Date.now(),
+    ): { frameId: string; screen: string | null; capturedAt: number; scrollState?: FrameScrollEntry[] } | null {
+        if (!this._lastKeyframeId || this._lastKeyframeTs <= 0) return null;
+        if (now - this._lastKeyframeTs > maxAgeMs) return null;
+        // Compared only when the caller knows its screen. An event with no screen cannot be shown
+        // to belong to this frame, so it does not get one.
+        if (!screenName || this._lastKeyframeScreen !== screenName) return null;
+        return {
+            frameId: this._lastKeyframeId,
+            screen: this._lastKeyframeScreen,
+            capturedAt: this._lastKeyframeTs,
+            ...(this._lastKeyframeScroll ? { scrollState: this._lastKeyframeScroll } : {}),
+        };
+    }
+
+    /** Set callback for when a frame is captured */
+    setFrameEmitCallback(cb: FrameEmitCallback): void {
+        this.onFrameEmit = cb;
+    }
+
+    /** Set the callback that turns a held wait into LOADING_STARTED / LOADING_COMPLETED events. */
+    setLoadingIntervalCallback(cb: LoadingIntervalCallback): void {
+        this.onLoadingInterval = cb;
+    }
+
+    /**
+     * Open a wait on one lane. Idempotent per lane: a hold is re-checked every NETWORK_QUIET_MS
+     * while it lasts, and each re-check must not open a new interval.
+     */
+    private _openHold(lane: 'nav' | 'interaction', screen: string | undefined): void {
+        const started = lane === 'nav' ? this.navHoldStartedAt : this.interactionHoldStartedAt;
+        if (started) return;
+        const now = Date.now();
+        if (lane === 'nav') this.navHoldStartedAt = now;
+        else this.interactionHoldStartedAt = now;
+        try {
+            this.onLoadingInterval?.('start', screen, {});
+        } catch {
+            // Recording the wait must never break the capture it is describing.
+        }
+    }
+
+    /**
+     * Close a wait, if one is open on that lane.
+     *
+     * EVERY path that abandons a pending capture calls this, because an interval with no end is
+     * a claim the player cannot draw and cannot disprove — it would either render as an
+     * open-ended band running to the end of the session, or be dropped, and neither is what
+     * happened. `superseded` and `session_end` exist precisely so those paths have something
+     * truthful to say rather than staying silent.
+     */
+    private _closeHold(lane: 'nav' | 'interaction', reason: LoadingEndReason): void {
+        const started = lane === 'nav' ? this.navHoldStartedAt : this.interactionHoldStartedAt;
+        if (!started) return;
+        if (lane === 'nav') this.navHoldStartedAt = 0;
+        else this.interactionHoldStartedAt = 0;
+        const screen = lane === 'nav' ? this.pendingNavScreen ?? undefined : this.pendingInteractionScreen;
+        try {
+            this.onLoadingInterval?.('end', screen ?? this.currentScreen ?? undefined, {
+                durationMs: Date.now() - started,
+                reason,
+            });
+        } catch {
+            // As above — advisory.
+        }
+    }
+
+    /** Start capture according to configured mode */
+    start(): void {
+        if (this.capturing) return;
+        this.capturing = true;
+
+        // P2-0/1/5: reset per-session capture state so sequence + keyframe tracking
+        // start clean for this session lifecycle.
+        this._sequenceCounter = 0;
+        this._lastFrameHash = null;
+        this._lastKeyframeTs = 0;
+        this._lastKeyframeId = null;
+        this._lastKeyframeScreen = null;
+        this._lastKeyframeScroll = undefined;
+        this._framesSinceKeyframe = 0;
+
+        this._startFrequencyTimer();
+
+        __DEV__ && logger.debug(`[ReplayCaptureManager] Started (mode=${this.config.captureMode})`);
+    }
+
+    /**
+     * Resume capture WITHIN the same session after a pause (a `frames` quota block that lifted).
+     *
+     * Differs from `start()` on purpose: the sequence counter is KEPT, so frames after the pause
+     * continue the session's ordering instead of restarting at 0 and colliding with frames already
+     * stored. The keyframe base is FORGOTTEN, because every frame captured before the pause that was
+     * still queued was discarded — a delta against it would be unplayable. The next frame is
+     * therefore a keyframe.
+     */
+    resume(): void {
+        if (this.capturing) return;
+        this.capturing = true;
+        this._lastFrameHash = null;
+        this._lastKeyframeTs = 0;
+        this._lastKeyframeId = null;
+        this._lastKeyframeScreen = null;
+        this._lastKeyframeScroll = undefined;
+        this._framesSinceKeyframe = 0;
+        this._startFrequencyTimer();
+        __DEV__ && logger.debug(`[ReplayCaptureManager] Resumed (mode=${this.config.captureMode})`);
+    }
+
+    get isCapturing(): boolean {
+        return this.capturing;
+    }
+
+    private _startFrequencyTimer(): void {
+        if (this.config.captureMode !== 'frequency') return;
+        if (this.frequencyTimer) clearInterval(this.frequencyTimer);
+        const intervalMs = Math.max(500, this.config.intervalMs);
+        this.frequencyTimer = setInterval(() => {
+            this.triggerCapture('frequency').catch(() => { });
+        }, intervalMs);
+        __DEV__ && logger.debug(`[ReplayCaptureManager] Frequency mode: every ${intervalMs}ms`);
+    }
+
+    /** Stop capture — cancels ALL pending timers and increments generation */
+    stop(reason: LoadingEndReason = 'session_end'): void {
+        this.capturing = false;
+
+        // Increment generation — invalidates ALL in-flight async captures
+        this.captureGeneration++;
+
+        // Cancel frequency timer
+        if (this.frequencyTimer) {
+            clearInterval(this.frequencyTimer);
+            this.frequencyTimer = null;
+        }
+
+        // Cancel pending navigation capture
+        if (this.pendingNavTimeout) {
+            clearTimeout(this.pendingNavTimeout);
+            // Closed BEFORE the screen is cleared — the interval is about that screen, and an
+            // end reported against `null` would file the wait on whatever came next.
+            this._closeHold('nav', reason);
+            this.pendingNavTimeout = null;
+            this.pendingNavScreen = null;
+        }
+
+        // Cancel pending scroll capture
+        if (this.pendingScrollTimeout) {
+            clearTimeout(this.pendingScrollTimeout);
+            this.pendingScrollTimeout = null;
+        }
+
+        // Cancel pending loading capture
+        if (this.pendingLoadingTimeout) {
+            clearTimeout(this.pendingLoadingTimeout);
+            this.pendingLoadingTimeout = null;
+            this.pendingLoadingScreen = null;
+        }
+
+        // Cancel pending interaction capture
+        if (this.pendingInteractionTimeout) {
+            clearTimeout(this.pendingInteractionTimeout);
+            this._closeHold('interaction', reason);
+            this.pendingInteractionTimeout = null;
+            this.pendingInteractionPoint = undefined;
+            this.pendingInteractionScreen = undefined;
+        }
+
+        // Clear late absorption tracking
+        this.lastCompletedInteraction = null;
+
+        // Clear loading-hold deadlines
+        this.pendingNavDeadline = 0;
+        this.pendingInteractionDeadline = 0;
+        this._inFlightRequests = 0;
+
+        // Clear in-flight interaction tracking
+        this._inFlightInteractionScreen = undefined;
+        this._inFlightInteractionPoint = undefined;
+        this._suppressInFlightInteraction = false;
+
+        // Clear dedup state
+        this.lastCaptureIntent = null;
+
+        __DEV__ && logger.debug('[ReplayCaptureManager] Stopped (all timers cancelled, generation incremented)');
+    }
+
+    /**
+     * Report app network activity. Called by NetworkFeature for requests the app itself made —
+     * SDK telemetry uploads and third-party beacons are excluded there, and must stay excluded:
+     * this SDK uploads frames, so counting its own traffic would mean a screen never goes quiet.
+     *
+     * Advisory only. It never causes a capture, it only decides when one that was already going
+     * to happen actually fires. A missed or duplicated call therefore costs a slightly early or
+     * slightly late frame, never a wrong or an extra one — which is why it is deliberately a
+     * counter and not a per-request registry.
+     */
+    onNetworkActivity(phase: 'start' | 'end'): void {
+        const now = Date.now();
+        if (phase === 'start') {
+            this._inFlightRequests++;
+            this._lastRequestStartTs = now;
+            return;
+        }
+        // Floored at zero: an 'end' with no matching 'start' (an interceptor installed mid-flight)
+        // must not drive the count negative and wedge every later hold.
+        this._inFlightRequests = Math.max(0, this._inFlightRequests - 1);
+        this._lastRequestEndTs = now;
+    }
+
+    /**
+     * How much longer a capture triggered at `triggeredAt` should wait for the screen's data,
+     * or 0 to fire now.
+     *
+     * The question is not "is the app busy" but "is the app still fetching what this tap asked
+     * for". So a request that was already running when the tap happened does not hold anything:
+     * a background poll or an in-progress upload would otherwise hold every capture to the cap
+     * and make the replay LATE instead of empty, which is not an improvement. Only activity that
+     * began at or after the trigger counts.
+     *
+     * (A poll whose next tick happens to land just after the tap is indistinguishable from a
+     * fetch the tap caused, and will hold. That is bounded by the cap and produces a frame of a
+     * settled screen either way, so it is accepted rather than guessed at.)
+     */
+    private _loadingHoldMs(triggeredAt: number, deadline: number): number {
+        const now = Date.now();
+        if (now >= deadline) return 0;
+        if (this._lastRequestStartTs < triggeredAt) return 0;
+        // Still fetching — re-check on the quiet interval rather than waiting for the deadline,
+        // so the frame lands promptly once the last response arrives.
+        //
+        // The count is only trusted while it is CORROBORATED by a recent start. A request whose
+        // terminal event never arrives (an interceptor installed mid-flight, a socket the
+        // platform tears down silently) would otherwise leave the counter permanently above zero
+        // and hold every future capture to the cap — turning a fix for empty frames into a
+        // guaranteed four-second delay on all of them. Treating a stale count as zero fails
+        // towards today's behaviour, which is the safe direction.
+        const countIsStale = now - this._lastRequestStartTs > LOADING_DEFER_CAP_MS;
+        if (this._inFlightRequests > 0 && !countIsStale) {
+            return Math.min(NETWORK_QUIET_MS, deadline - now);
+        }
+        const quietFor = now - this._lastRequestEndTs;
+        if (quietFor >= NETWORK_QUIET_MS) return 0;
+        return Math.min(NETWORK_QUIET_MS - quietFor, deadline - now);
+    }
+
+    /** Notify of a screen change — triggers cancellable delayed capture */
+    onScreenChange(screenName: string): void {
+        this.currentScreen = screenName;
+
+        if (!this.capturing) return;
+        if (this._isExcludedScreen(screenName)) return;
+
+        if (this.config.captureMode === 'navigation' || this.config.captureMode === 'interactions') {
+            // Cancel any previous pending navigation capture (debounce rapid navigations)
+            if (this.pendingNavTimeout) {
+                clearTimeout(this.pendingNavTimeout);
+                this._closeHold('nav', 'superseded');
+                this.pendingNavTimeout = null;
+                this.pendingNavScreen = null;
+            }
+
+            // Cancel any pending scroll capture — scroll on the old screen is now obsolete
+            if (this.pendingScrollTimeout) {
+                clearTimeout(this.pendingScrollTimeout);
+                this.pendingScrollTimeout = null;
+            }
+
+            // Cancel pending loading capture ONLY if it was for a DIFFERENT screen.
+            if (this.pendingLoadingTimeout && this.pendingLoadingScreen !== screenName) {
+                clearTimeout(this.pendingLoadingTimeout);
+                this.pendingLoadingTimeout = null;
+                this.pendingLoadingScreen = null;
+            }
+
+            // ── Absorb pending interaction if tap caused this navigation ──────
+            // If a tap was pending and the screen changed (tap → navigation),
+            // cancel the stale interaction capture and carry its tap metadata
+            // forward into the navigation capture.
+            let absorbedInteractionPoint: ReplayFrame['interactionPoint'] | undefined;
+            if (this.pendingInteractionTimeout) {
+                clearTimeout(this.pendingInteractionTimeout);
+                // The tap's own wait ended here, unresolved — the visitor left for another screen
+                // before it arrived. That is a real outcome and is recorded as one.
+                this._closeHold('interaction', 'superseded');
+                absorbedInteractionPoint = this.pendingInteractionPoint;
+                this.pendingInteractionTimeout = null;
+                this.pendingInteractionPoint = undefined;
+                this.pendingInteractionScreen = undefined;
+                __DEV__ && logger.debug(
+                    `[ReplayCaptureManager] Pending interaction absorbed by navigation to ${screenName}`,
+                );
+            }
+
+            // ── Late absorption: retroactively evict stale interaction frame ──
+            // If an interaction capture ALREADY completed (settle window expired)
+            // but navigation arrives within the grace window to a DIFFERENT screen,
+            // the interaction frame is stale (captured old screen). Evict it and
+            // carry its tap metadata forward to the navigation capture.
+            if (
+                !absorbedInteractionPoint &&
+                this.lastCompletedInteraction &&
+                this.lastCompletedInteraction.screen !== screenName &&
+                (Date.now() - this.lastCompletedInteraction.ts) < LATE_ABSORPTION_GRACE_MS
+            ) {
+                const stale = this.lastCompletedInteraction;
+                absorbedInteractionPoint = stale.interactionPoint;
+                // Evict the stale frame from the frames list
+                this.frames = this.frames.filter(f => f.frameId !== stale.frameId);
+                __DEV__ && logger.debug(
+                    `[ReplayCaptureManager] Late absorption: evicted stale interaction frame ` +
+                    `${stale.frameId} on ${stale.screen}, navigation to ${screenName}`,
+                );
+                this.lastCompletedInteraction = null;
+            }
+
+            // ── In-flight interaction suppression ─────────────────────────
+            // If a native interaction capture started (settle timer already fired)
+            // but hasn't returned yet, suppress it — the navigation represents
+            // the correct visual state. Carry the tap point forward if available.
+            if (
+                !absorbedInteractionPoint &&
+                this._inFlightInteractionScreen !== undefined &&
+                this._inFlightInteractionScreen !== screenName
+            ) {
+                this._suppressInFlightInteraction = true;
+                if (this._inFlightInteractionPoint) {
+                    absorbedInteractionPoint = this._inFlightInteractionPoint;
+                }
+                __DEV__ && logger.debug(
+                    `[ReplayCaptureManager] In-flight interaction suppressed by navigation to ${screenName}`,
+                );
+            }
+
+            // Track which screen this nav capture is for
+            this.pendingNavScreen = screenName;
+
+            // Brief delay to allow the new screen to render (but stay snappy), then — if the new
+            // screen set off a fetch — hold until it arrives. The capture stays PENDING while it
+            // waits, rather than becoming a second stage, so every cancellation above (a further
+            // navigation, stop(), a loading marker for this screen) still reaches it.
+            const navTriggeredAt = Date.now();
+            this.pendingNavDeadline = navTriggeredAt + LOADING_DEFER_CAP_MS;
+            const fireNav = (): void => {
+                this.pendingNavTimeout = null;
+                const hold = this._loadingHoldMs(navTriggeredAt, this.pendingNavDeadline);
+                if (hold > 0) {
+                    this._openHold('nav', screenName);
+                    this.pendingNavTimeout = setTimeout(fireNav, hold);
+                    return;
+                }
+                // Past the deadline with requests still outstanding means the screen had NOT
+                // arrived — we stopped waiting, it did not finish. The two must stay distinct.
+                this._closeHold(
+                    'nav',
+                    Date.now() >= this.pendingNavDeadline && this._inFlightRequests > 0
+                        ? 'timeout'
+                        : 'network_idle',
+                );
+                this.pendingNavScreen = null;
+                this.pendingNavDeadline = 0;
+                // Pass absorbed interaction point so the nav frame carries tap metadata
+                this.triggerCapture('navigation', screenName, absorbedInteractionPoint).catch(() => { });
+            };
+            this.pendingNavTimeout = setTimeout(fireNav, 150);
+        }
+    }
+
+    /**
+     * Notify of a user interaction — deferred capture with navigation absorption.
+     *
+     * Instead of capturing immediately (which would snapshot the OLD screen
+     * when the tap causes navigation), the capture is deferred by
+     * INTERACTION_SETTLE_MS. If onScreenChange fires within that window,
+     * the pending interaction is absorbed into the navigation capture.
+     * If no navigation follows, the interaction capture fires normally.
+     */
+    onInteraction(interactionPoint?: ReplayFrame['interactionPoint']): void {
+        if (!this.capturing) return;
+        if (this.currentScreen && this._isExcludedScreen(this.currentScreen)) return;
+
+        // Throttle: prevent duplicate captures from rapid gestures (500ms)
+        const now = Date.now();
+        if (now - this.lastInteractionCapture < 500) return;
+        this.lastInteractionCapture = now;
+
+        const screen = this.currentScreen ?? undefined;
+
+        // Semantic dedup: if a navigation capture is pending for the SAME screen,
+        // the navigation frame will represent the post-interaction state.
+        if (this.pendingNavTimeout && this.pendingNavScreen === screen) {
+            __DEV__ && logger.debug('[ReplayCaptureManager] Interaction suppressed — navigation pending for same screen');
+            return;
+        }
+
+        // Cancel any previous pending interaction (rapid tap replacement)
+        if (this.pendingInteractionTimeout) {
+            clearTimeout(this.pendingInteractionTimeout);
+            this._closeHold('interaction', 'superseded');
+        }
+
+        // Defer the interaction capture to allow navigation to absorb it
+        this.pendingInteractionScreen = screen;
+        this.pendingInteractionPoint = interactionPoint;
+        this.pendingInteractionDeadline = now + LOADING_DEFER_CAP_MS;
+        const fireInteraction = (): void => {
+            this.pendingInteractionTimeout = null;
+            // The tap opened a sheet, a tab, a filter — anything that fetches. Keep waiting, and
+            // keep the capture PENDING while we do: a navigation arriving now must still be able
+            // to absorb it, which it cannot do once triggerCapture has been called.
+            const hold = this._loadingHoldMs(now, this.pendingInteractionDeadline);
+            if (hold > 0) {
+                this._openHold('interaction', this.pendingInteractionScreen);
+                this.pendingInteractionTimeout = setTimeout(fireInteraction, hold);
+                return;
+            }
+            this._closeHold(
+                'interaction',
+                Date.now() >= this.pendingInteractionDeadline && this._inFlightRequests > 0
+                    ? 'timeout'
+                    : 'network_idle',
+            );
+            const captureScreen = this.pendingInteractionScreen;
+            const capturePoint = this.pendingInteractionPoint;
+            this.pendingInteractionScreen = undefined;
+            this.pendingInteractionPoint = undefined;
+            this.pendingInteractionDeadline = 0;
+            // No navigation followed → capture the interaction on the current screen
+            this.triggerCapture('interaction', captureScreen, capturePoint).catch(() => { });
+        };
+        this.pendingInteractionTimeout = setTimeout(fireInteraction, INTERACTION_SETTLE_MS);
+    }
+
+    /** Notify of scroll settle — triggers delayed capture for post-scroll state */
+    onScrollSettle(screenName?: string): void {
+        if (!this.capturing) return;
+
+        // Cancel any previous pending scroll capture
+        if (this.pendingScrollTimeout) {
+            clearTimeout(this.pendingScrollTimeout);
+            this.pendingScrollTimeout = null;
+        }
+
+        // Small delay to let post-scroll rendering settle
+        this.pendingScrollTimeout = setTimeout(() => {
+            this.pendingScrollTimeout = null;
+            this.triggerCapture('scroll', screenName ?? this.currentScreen ?? undefined).catch(() => { });
+        }, 150);
+    }
+
+    /** Notify of loading end — captures the settled loaded screen */
+    onLoadingEnd(screenName?: string): void {
+        if (!this.capturing) return;
+
+        const screen = screenName ?? this.currentScreen ?? undefined;
+
+        // Cancel any previous pending loading capture for ANY screen
+        if (this.pendingLoadingTimeout) {
+            clearTimeout(this.pendingLoadingTimeout);
+            this.pendingLoadingTimeout = null;
+            this.pendingLoadingScreen = null;
+        }
+
+        // If a navigation capture is pending for the SAME screen, cancel it.
+        // The loading-end capture represents the final settled state and supersedes
+        // the initial navigation capture (which would show loading/skeleton UI).
+        if (this.pendingNavTimeout && this.pendingNavScreen === screen) {
+            clearTimeout(this.pendingNavTimeout);
+            this._closeHold('nav', 'superseded');
+            this.pendingNavTimeout = null;
+            this.pendingNavScreen = null;
+            __DEV__ && logger.debug('[ReplayCaptureManager] Navigation capture cancelled — loading-end supersedes for same screen');
+        }
+
+        // Track which screen this loading capture is for
+        this.pendingLoadingScreen = screen ?? null;
+
+        // Slight delay to allow the loaded content to render
+        this.pendingLoadingTimeout = setTimeout(() => {
+            this.pendingLoadingTimeout = null;
+            this.pendingLoadingScreen = null;
+            this.triggerCapture('screen_loaded', screen).catch(() => { });
+        }, 200);
+    }
+
+    /** Manual capture trigger (e.g. error-context) */
+    async captureManual(reason: CaptureReason): Promise<ReplayFrame | null> {
+        return this.triggerCapture(reason, this.currentScreen ?? undefined);
+    }
+
+    /** Protect frames near a crash from eviction */
+    protectFramesNearCrash(crashTimestamp: number, windowMs: number = 10_000): string[] {
+        const protectedIds: string[] = [];
+        for (const frame of this.frames) {
+            if (Math.abs(frame.ts - crashTimestamp) <= windowMs) {
+                this.protectedFrameIds.add(frame.frameId);
+                protectedIds.push(frame.frameId);
+            }
+        }
+        return protectedIds;
+    }
+
+    /** Get all frames (read-only snapshot) */
+    getFrames(): readonly ReplayFrame[] {
+        return this.frames;
+    }
+
+    /** Get frame IDs for artifact index */
+    getFrameRefs(): string[] {
+        return this.frames.map(f => f.frameId);
+    }
+
+    /** Current frame count */
+    get count(): number {
+        return this.frames.length;
+    }
+
+    /** Clear all frames */
+    clear(): void {
+        this.frames = [];
+        this.protectedFrameIds.clear();
+    }
+
+    // ─── Core Capture ───────────────────────────────────────────────────
+
+    /**
+     * Trigger a frame capture via native engine.
+     * This method ONLY orchestrates — native does the real work.
+     *
+     * Semantic dedup: if the last completed capture has the same reason + screen
+     * and happened within SAME_INTENT_COOLDOWN_MS, the capture is suppressed.
+     * Bypass reasons (manual, error-context, frequency) skip this check entirely.
+     *
+     * Session-bound generation guard: captures the generation counter before
+     * starting the async native capture and verifies it hasn't changed after.
+     * If it has, the capture result is silently discarded — the session that
+     * requested it no longer exists.
+     */
+    private async triggerCapture(
+        reason: CaptureReason,
+        screenName?: string,
+        interactionPoint?: ReplayFrame['interactionPoint'],
+    ): Promise<ReplayFrame | null> {
+        if (!this.capturing) return null;
+
+        // ── Semantic dedup check ────────────────────────────────────────
+        if (!BYPASS_DEDUP_REASONS.has(reason) && this.lastCaptureIntent) {
+            const last = this.lastCaptureIntent;
+            const sameScreen = last.screen === screenName;
+            const sameReason = last.reason === reason;
+            const withinCooldown = (Date.now() - last.ts) < SAME_INTENT_COOLDOWN_MS;
+
+            // Same reason + same screen within cooldown → semantic duplicate
+            if (sameReason && sameScreen && withinCooldown) {
+                __DEV__ && logger.debug(
+                    `[ReplayCaptureManager] Semantic dedup: ${reason}@${screenName} suppressed ` +
+                    `(same intent within ${SAME_INTENT_COOLDOWN_MS}ms)`,
+                );
+                return null;
+            }
+        }
+
+        // Capture generation at call time
+        const gen = this.captureGeneration;
+
+        // ── In-flight interaction tracking ─────────────────────────────
+        // Mark this capture as in-flight so onScreenChange can suppress it
+        // if navigation arrives before the native callback returns.
+        if (reason === 'interaction') {
+            this._inFlightInteractionScreen = screenName;
+            this._inFlightInteractionPoint = interactionPoint;
+            this._suppressInFlightInteraction = false;
+        }
+
+        try {
+            // ── Capture path selection ──────────────────────────────────────
+            // Prefer the native file-outbox staged path when ready: it captures +
+            // masks + encodes natively and STAGES the image (bytes never cross the
+            // bridge). If the outbox is off / unavailable / the staged capture fails,
+            // fall back to the legacy native capture (base64 → JS upload). All
+            // orchestration below (dedup, change-detection, keyframe/delta, sequencing)
+            // is identical for both paths.
+            const screen = screenName ?? this.currentScreen ?? undefined;
+            let staged: StagedFrameResult | null = null;
+            if (this.outboxCapture) {
+                staged = await this.outboxCapture.capture(this.sessionId, screen, reason);
+            }
+            const usedStaged = staged !== null;
+
+            let result: NativeFrameResult | null;
+            if (staged) {
+                result = {
+                    base64: '', // bytes stay native on the outbox path — never bridged
+                    width: staged.width,
+                    height: staged.height,
+                    byteSize: staged.byteSize,
+                    format: staged.format,
+                    frameHash: staged.frameHash,
+                    platform: staged.platform,
+                    ...(staged.scrollState ? { scrollState: staged.scrollState } : {}),
+                };
+            } else {
+                result = await this.nativeCapture(this.sessionId, reason, this.config.quality);
+            }
+
+            // Drop a staged frame if any guard below rejects it (keeps the outbox clean).
+            const discardStaged = (): void => {
+                if (usedStaged && staged) {
+                    this.outboxCapture?.discard(this.sessionId, staged.frameId).catch(() => { });
+                }
+            };
+
+            // ── In-flight suppression check ─────────────────────────────
+            // Clear in-flight tracking first (before any early returns).
+            if (reason === 'interaction') {
+                this._inFlightInteractionScreen = undefined;
+                this._inFlightInteractionPoint = undefined;
+                if (this._suppressInFlightInteraction) {
+                    this._suppressInFlightInteraction = false;
+                    discardStaged();
+                    __DEV__ && logger.debug('[ReplayCaptureManager] In-flight interaction suppressed — navigation arrived during capture');
+                    return null;
+                }
+            }
+
+            // Generation guard: if session was stopped/restarted during async capture,
+            // discard the result to prevent stale frames
+            if (gen !== this.captureGeneration) {
+                discardStaged();
+                __DEV__ && logger.debug('[ReplayCaptureManager] Stale capture discarded (generation mismatch)');
+                return null;
+            }
+
+            if (!this.capturing) {
+                discardStaged();
+                return null;
+            }
+
+            if (!result) {
+                // Native capture unavailable — log warning, return null
+                // NO JS fallback — this is by design
+                __DEV__ && logger.debug('[ReplayCaptureManager] Native capture returned null — frame not captured');
+                return null;
+            }
+
+            // ── P2-1: change-triggered capture + heartbeat keyframe ─────────
+            // Visual suppression applies ONLY to the periodic 'frequency' lane — the
+            // sole source of redundant, visually-identical consecutive frames during
+            // static viewing (the −40–60% lever). Semantic captures (navigation /
+            // interaction / scroll / screen_loaded) are already change-driven and are
+            // handled by the semantic dedup above, so they always emit — visual-hashing
+            // them risks dropping a meaningful frame whose pixels happen to match.
+            // manual / error-context are explicit intent and likewise always emit.
+            // The heartbeat (maxKeyframeIntervalMs) forces a keyframe even when nothing
+            // changed, so static periods still have a frame AND deltas keep a fresh base.
+            // Suppressed frames do NOT consume a sequence number.
+            const now = Date.now();
+            const hash = result.frameHash ?? hashBase64(result.base64);
+            const explicit = reason === 'manual' || reason === 'error-context';
+            const maxKf = this.config.maxKeyframeIntervalMs ?? 5000;
+            const heartbeatDue = (now - this._lastKeyframeTs) >= maxKf;
+            const changed = hash !== this._lastFrameHash;
+            const changeDetection = this.config.changeDetection !== false;
+            if (changeDetection && reason === 'frequency' && !changed && !heartbeatDue) {
+                discardStaged();
+                __DEV__ && logger.debug('[ReplayCaptureManager] Change-trigger suppressed identical frequency frame');
+                return null;
+            }
+
+            // ── P2-5: keyframe vs delta decision ────────────────────────────
+            // Force a keyframe when: delta encoding is off, no base exists yet, the
+            // heartbeat is due, the keyframe-interval elapsed, or this is an explicit
+            // capture (full frame is safest). Otherwise emit a delta against the last
+            // keyframe. NOTE: real delta-byte encoding is native (pixel ops); JS owns
+            // the decision/tagging — see P2_CONTRACT.md §3/§6.
+            const deltaOn = this.config.deltaEncoding === true;
+            const kfInterval = this.config.deltaKeyframeInterval ?? 10;
+            const mustKeyframe =
+                !deltaOn ||
+                this._lastKeyframeId === null ||
+                heartbeatDue ||
+                explicit ||
+                this._framesSinceKeyframe >= kfInterval;
+            const frameType: 'keyframe' | 'delta' = mustKeyframe ? 'keyframe' : 'delta';
+            const baseFrameId = frameType === 'delta' ? this._lastKeyframeId ?? undefined : undefined;
+
+            // Build frame with artifact reference and screen context.
+            // On the native-outbox staged path the image is ALREADY written to disk
+            // under the native-assigned frameId; reuse it so commitOutboxFrame's
+            // lookup resolves (minting a fresh id here makes the staged image
+            // "missing" at commit → the frame is silently dropped → zero frames).
+            // Legacy (base64) path has no staged file, so mint a new id.
+            const frameId = staged?.frameId ?? generateFrameId();
+
+            // Fill interactionPoint screen dimensions from the capture result.
+            // interactionPoint may come from an absorbed pending interaction
+            // (tap → navigation), so attach it regardless of capture reason.
+            const resolvedInteraction = interactionPoint
+                ? { ...interactionPoint, screenWidth: result.width, screenHeight: result.height }
+                : undefined;
+
+            const frame: ReplayFrame = {
+                frameId,
+                sessionId: this.sessionId,
+                ts: now,
+                sequenceNumber: ++this._sequenceCounter,
+                frameType,
+                ...(baseFrameId ? { baseFrameId } : {}),
+                imageRef: frameId, // Artifact ref — transport resolves to actual content
+                width: result.width,
+                height: result.height,
+                byteSize: result.byteSize ?? 0,
+                format: result.format ?? 'jpeg',
+                quality: this.config.quality,
+                captureReason: reason,
+                sourcePlatform: result.platform,
+                screen: screenName ?? this.currentScreen ?? undefined,
+                // Scroll offsets read natively beside these pixels — undefined when not measured.
+                ...(result.scrollState ? { scrollState: result.scrollState } : {}),
+                // Attach interaction point if this was an interaction-driven capture
+                ...(resolvedInteraction ? { interactionPoint: resolvedInteraction } : {}),
+            };
+
+            // ── Record capture intent for dedup ─────────────────────────
+            this.lastCaptureIntent = {
+                reason,
+                screen: screenName,
+                ts: Date.now(),
+            };
+
+            // Enforce frame limit with priority-based eviction
+            if (this.frames.length >= this.config.maxFrames) {
+                this._evictLowestPriorityFrame();
+            }
+
+            this.frames.push(frame);
+
+            // ── P2-1/5: commit change-detection + keyframe tracking ─────────
+            this._lastFrameHash = hash;
+            if (frameType === 'keyframe') {
+                this._lastKeyframeId = frameId;
+                this._lastKeyframeTs = now;
+                this._lastKeyframeScreen = screenName ?? null;
+                this._lastKeyframeScroll = frame.scrollState;
+                this._framesSinceKeyframe = 0;
+            } else {
+                this._framesSinceKeyframe++;
+            }
+
+            // ── Deliver the frame ───────────────────────────────────────────
+            // Staged (native outbox) path: commit JS-authoritative metadata so the
+            // native uploader owns delivery. Do NOT also emit base64 to the JS
+            // transport — that would double-upload the frame. If commit fails the
+            // image is left staged (no meta) and swept as an orphan on next recover().
+            // Legacy path: emit base64 to the JS transport as before.
+            if (usedStaged && staged) {
+                const meta: OutboxFrameMeta = {
+                    frameId: frame.frameId,
+                    sessionId: this.sessionId,
+                    timestamp: frame.ts,
+                    sequenceNumber: frame.sequenceNumber,
+                    frameType,
+                    ...(baseFrameId ? { baseFrameId } : {}),
+                    screenName: frame.screen ?? 'unknown',
+                    trigger: reason,
+                    format: staged.format,
+                    contentType: staged.contentType,
+                    width: staged.width,
+                    height: staged.height,
+                    sizeBytes: staged.byteSize,
+                    masked: staged.masked,
+                    ...(staged.scrollState ? { scrollState: staged.scrollState } : {}),
+                };
+                try {
+                    const committed = await this.outboxCapture?.commit(meta);
+                    if (!committed) {
+                        __DEV__ && logger.debug('[ReplayCaptureManager] Outbox commit failed — frame staged but not uploadable');
+                    }
+                } catch {
+                    // Commit failure must not crash capture; orphan is swept later.
+                }
+            } else {
+                // Emit to transport — pass base64 as transport-layer data (not domain)
+                try {
+                    this.onFrameEmit?.(frame, result.base64);
+                } catch {
+                    // Transport emission must not crash capture
+                }
+            }
+
+            // ── Track completed interaction for late absorption ──────────
+            // If this was an interaction capture, record its metadata so that
+            // a delayed onScreenChange can retroactively evict it if navigation
+            // follows within LATE_ABSORPTION_GRACE_MS.
+            if (reason === 'interaction') {
+                this.lastCompletedInteraction = {
+                    frameId: frame.frameId,
+                    screen: frame.screen,
+                    interactionPoint: frame.interactionPoint,
+                    ts: Date.now(),
+                };
+            } else {
+                // Non-interaction captures clear the tracker — no late absorption needed
+                this.lastCompletedInteraction = null;
+            }
+
+            if (ACTIVITY_OPENERS.has(reason)) this._openActivityWindow(gen);
+
+            return frame;
+        } catch (err) {
+            // Clear in-flight tracking on error too
+            if (reason === 'interaction') {
+                this._inFlightInteractionScreen = undefined;
+                this._inFlightInteractionPoint = undefined;
+                this._suppressInFlightInteraction = false;
+            }
+            logger.error('[ReplayCaptureManager] Capture failed:', err);
+            return null;
+        }
+    }
+
+    // ─── Activity Sampling ──────────────────────────────────────────────
+
+    /**
+     * (Re)open the sampling window after a semantic frame. Only in `interactions` mode: `frequency`
+     * already samples on its own timer, and `navigation` mode is the deliberately minimal one. Needs
+     * change detection — without it every sample would upload, which is the old cost.
+     */
+    private _openActivityWindow(gen: number): void {
+        if (this.config.captureMode !== 'interactions') return;
+        if (this.config.activitySampling === false || this.config.changeDetection === false) return;
+        if (!this.capturing || gen !== this.captureGeneration) return;
+        this.activityGen = gen;
+        this.activityWindowEnd = Date.now() + ACTIVITY_WINDOW_MS;
+        this.activitySamples = 0;
+        this.activityUnchangedStreak = 0;
+        if (this.activityTimer) clearTimeout(this.activityTimer);
+        this.activityTimer = setTimeout(() => { void this._activityTick(); }, ACTIVITY_SAMPLE_INTERVAL_MS);
+    }
+
+    private async _activityTick(): Promise<void> {
+        this.activityTimer = null;
+        const gen = this.activityGen;
+        if (!this.capturing || gen !== this.captureGeneration) return;
+        const now = Date.now();
+        if (now >= this.activityWindowEnd) return;
+        if (this.currentScreen && this._isExcludedScreen(this.currentScreen)) return;
+
+        // A semantic capture is about to produce the real frame — let it; it reopens the window.
+        const semanticPending =
+            this.pendingInteractionTimeout !== null ||
+            this.pendingNavTimeout !== null ||
+            this.pendingScrollTimeout !== null ||
+            this.pendingLoadingTimeout !== null;
+
+        if (!semanticPending) {
+            if (now - this.activityMinuteStart >= 60_000) {
+                this.activityMinuteStart = now;
+                this.activityMinuteCount = 0;
+            }
+            if (this.activityMinuteCount >= ACTIVITY_MAX_PER_MINUTE) return;
+
+            // null = unchanged (discarded natively, never uploaded) or failed — either way the
+            // screen gave us nothing new, which is what "settled" means here.
+            const frame = await this.triggerCapture('frequency', this.currentScreen ?? undefined);
+            if (gen !== this.captureGeneration || gen !== this.activityGen) return;
+            if (frame) {
+                this.activitySamples++;
+                this.activityMinuteCount++;
+                this.activityUnchangedStreak = 0;
+            } else {
+                this.activityUnchangedStreak++;
+            }
+            if (this.activitySamples >= ACTIVITY_MAX_SAMPLES) return;
+            if (this.activityUnchangedStreak >= ACTIVITY_SETTLED_STREAK) return;
+        }
+
+        if (Date.now() + ACTIVITY_SAMPLE_INTERVAL_MS > this.activityWindowEnd) return;
+        this.activityTimer = setTimeout(() => { void this._activityTick(); }, ACTIVITY_SAMPLE_INTERVAL_MS);
+    }
+
+    // ─── Frame Retention ────────────────────────────────────────────────
+
+    /**
+     * Evict the frame with the lowest retention priority.
+     * Crash-adjacent and error-context frames are NEVER evicted before generic frames.
+     */
+    private _evictLowestPriorityFrame(): void {
+        let lowestIdx = -1;
+        let lowestPriority = Infinity;
+        let oldestTs = Infinity;
+
+        for (let i = 0; i < this.frames.length; i++) {
+            const frame = this.frames[i];
+            // Never evict protected (crash-adjacent) frames
+            if (this.protectedFrameIds.has(frame.frameId)) continue;
+
+            const priority = getFrameRetentionPriority(frame.captureReason);
+            if (priority < lowestPriority || (priority === lowestPriority && frame.ts < oldestTs)) {
+                lowestPriority = priority;
+                lowestIdx = i;
+                oldestTs = frame.ts;
+            }
+        }
+
+        if (lowestIdx >= 0) {
+            this.frames.splice(lowestIdx, 1);
+        } else {
+            // All protected — drop oldest anyway
+            this.frames.shift();
+        }
+    }
+
+    // ─── Helpers ────────────────────────────────────────────────────────
+
+    private _isExcludedScreen(screenName: string): boolean {
+        return this.config.privacyPolicy.captureExclusions.includes(screenName);
+    }
+}
+
+// ─── Utils ──────────────────────────────────────────────────────────────────
+
+function generateFrameId(): string {
+    return `frm-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+}
+
+/**
+ * P2-1 change detection: cheap, allocation-light FNV-1a over the base64 string.
+ * Exact-hash only — a perceptual/near-identical match is a native concern (the
+ * native layer may supply `frameHash`; this is the JS fallback). Sampling every
+ * Nth char keeps it O(1)-ish on large frames while still being change-sensitive.
+ */
+function hashBase64(b64: string): string {
+    let h = 0x811c9dc5;
+    const len = b64.length;
+    const step = len > 4096 ? Math.ceil(len / 4096) : 1;
+    for (let i = 0; i < len; i += step) {
+        h ^= b64.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    // Fold in length so same-prefix different-length frames don't collide.
+    return `${(h >>> 0).toString(36)}-${len.toString(36)}`;
+}