@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/session/ReplayCaptureManager.ts

@@ -1,946 +1,998 @@
-/**
- * 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';
-
-// ─── 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;
-
-// ─── 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;
-    platform: 'android' | 'ios';
-}
-
-/** 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;
-}
-
-/**
- * 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;
-
-// ─── 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 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;
-
-    /**
-     * 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;
-    /** P2-5: frameId of the last emitted keyframe — delta base reference. */
-    private _lastKeyframeId: 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 ─────────────────────────────────────────────────────
-
-    /** Set callback for when a frame is captured */
-    setFrameEmitCallback(cb: FrameEmitCallback): void {
-        this.onFrameEmit = cb;
-    }
-
-    /** 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._framesSinceKeyframe = 0;
-
-        // Start frequency timer if in frequency mode
-        if (this.config.captureMode === 'frequency') {
-            const intervalMs = Math.max(500, this.config.intervalMs);
-            this.frequencyTimer = setInterval(() => {
-                this.triggerCapture('frequency').catch(() => { });
-            }, intervalMs);
-            logger.debug(`[ReplayCaptureManager] Frequency mode: every ${intervalMs}ms`);
-        }
-
-        logger.debug(`[ReplayCaptureManager] Started (mode=${this.config.captureMode})`);
-    }
-
-    /** Stop capture — cancels ALL pending timers and increments generation */
-    stop(): 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);
-            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.pendingInteractionTimeout = null;
-            this.pendingInteractionPoint = undefined;
-            this.pendingInteractionScreen = undefined;
-        }
-
-        // Clear late absorption tracking
-        this.lastCompletedInteraction = null;
-
-        // Clear in-flight interaction tracking
-        this._inFlightInteractionScreen = undefined;
-        this._inFlightInteractionPoint = undefined;
-        this._suppressInFlightInteraction = false;
-
-        // Clear dedup state
-        this.lastCaptureIntent = null;
-
-        logger.debug('[ReplayCaptureManager] Stopped (all timers cancelled, generation incremented)');
-    }
-
-    /** 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.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);
-                absorbedInteractionPoint = this.pendingInteractionPoint;
-                this.pendingInteractionTimeout = null;
-                this.pendingInteractionPoint = undefined;
-                this.pendingInteractionScreen = undefined;
-                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);
-                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;
-                }
-                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)
-            this.pendingNavTimeout = setTimeout(() => {
-                this.pendingNavTimeout = null;
-                this.pendingNavScreen = null;
-                // Pass absorbed interaction point so the nav frame carries tap metadata
-                this.triggerCapture('navigation', screenName, absorbedInteractionPoint).catch(() => { });
-            }, 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) {
-            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);
-        }
-
-        // Defer the interaction capture to allow navigation to absorb it
-        this.pendingInteractionScreen = screen;
-        this.pendingInteractionPoint = interactionPoint;
-        this.pendingInteractionTimeout = setTimeout(() => {
-            this.pendingInteractionTimeout = null;
-            const captureScreen = this.pendingInteractionScreen;
-            const capturePoint = this.pendingInteractionPoint;
-            this.pendingInteractionScreen = undefined;
-            this.pendingInteractionPoint = undefined;
-            // No navigation followed → capture the interaction on the current screen
-            this.triggerCapture('interaction', captureScreen, capturePoint).catch(() => { });
-        }, 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.pendingNavTimeout = null;
-            this.pendingNavScreen = null;
-            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) {
-                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,
-                };
-            } 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();
-                    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();
-                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
-                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();
-                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,
-                // 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._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,
-                };
-                try {
-                    const committed = await this.outboxCapture?.commit(meta);
-                    if (!committed) {
-                        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;
-            }
-
-            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;
-        }
-    }
-
-    // ─── 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)}`;
-}
+/**
+ * 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';
+
+// ─── 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;
+
+// ─── 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;
+}
+
+/** 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;
+}
+
+/**
+ * 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;
+
+// ─── 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 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;
+
+    /**
+     * 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;
+    /** 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 } | 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,
+        };
+    }
+
+    /** Set callback for when a frame is captured */
+    setFrameEmitCallback(cb: FrameEmitCallback): void {
+        this.onFrameEmit = cb;
+    }
+
+    /** 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._framesSinceKeyframe = 0;
+
+        // Start frequency timer if in frequency mode
+        if (this.config.captureMode === 'frequency') {
+            const intervalMs = Math.max(500, this.config.intervalMs);
+            this.frequencyTimer = setInterval(() => {
+                this.triggerCapture('frequency').catch(() => { });
+            }, intervalMs);
+            logger.debug(`[ReplayCaptureManager] Frequency mode: every ${intervalMs}ms`);
+        }
+
+        logger.debug(`[ReplayCaptureManager] Started (mode=${this.config.captureMode})`);
+    }
+
+    /** Stop capture — cancels ALL pending timers and increments generation */
+    stop(): 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);
+            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.pendingInteractionTimeout = null;
+            this.pendingInteractionPoint = undefined;
+            this.pendingInteractionScreen = undefined;
+        }
+
+        // Clear late absorption tracking
+        this.lastCompletedInteraction = null;
+
+        // Clear in-flight interaction tracking
+        this._inFlightInteractionScreen = undefined;
+        this._inFlightInteractionPoint = undefined;
+        this._suppressInFlightInteraction = false;
+
+        // Clear dedup state
+        this.lastCaptureIntent = null;
+
+        logger.debug('[ReplayCaptureManager] Stopped (all timers cancelled, generation incremented)');
+    }
+
+    /** 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.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);
+                absorbedInteractionPoint = this.pendingInteractionPoint;
+                this.pendingInteractionTimeout = null;
+                this.pendingInteractionPoint = undefined;
+                this.pendingInteractionScreen = undefined;
+                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);
+                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;
+                }
+                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)
+            this.pendingNavTimeout = setTimeout(() => {
+                this.pendingNavTimeout = null;
+                this.pendingNavScreen = null;
+                // Pass absorbed interaction point so the nav frame carries tap metadata
+                this.triggerCapture('navigation', screenName, absorbedInteractionPoint).catch(() => { });
+            }, 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) {
+            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);
+        }
+
+        // Defer the interaction capture to allow navigation to absorb it
+        this.pendingInteractionScreen = screen;
+        this.pendingInteractionPoint = interactionPoint;
+        this.pendingInteractionTimeout = setTimeout(() => {
+            this.pendingInteractionTimeout = null;
+            const captureScreen = this.pendingInteractionScreen;
+            const capturePoint = this.pendingInteractionPoint;
+            this.pendingInteractionScreen = undefined;
+            this.pendingInteractionPoint = undefined;
+            // No navigation followed → capture the interaction on the current screen
+            this.triggerCapture('interaction', captureScreen, capturePoint).catch(() => { });
+        }, 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.pendingNavTimeout = null;
+            this.pendingNavScreen = null;
+            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) {
+                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,
+                };
+            } 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();
+                    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();
+                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
+                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();
+                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,
+                // 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._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,
+                };
+                try {
+                    const committed = await this.outboxCapture?.commit(meta);
+                    if (!committed) {
+                        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;
+            }
+
+            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;
+        }
+    }
+
+    // ─── 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)}`;
+}