@scalebun-release/react-native 2.5.0

package/lib/commonjs/features/session/ReplayCaptureManager.js

@@ -0,0 +1,1253 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ReplayCaptureManager = void 0;
+var _internalLogger = require("../../core/logger/internalLogger");
+var _sessionTypes = require("./sessionTypes");
+/**
+ * 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
+ */
+
+// ─── 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+// ─── 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.
+ */
+
+/** JS-authoritative frame metadata written to the outbox on commit. */
+
+/**
+ * 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.
+ */
+
+// ─── 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.
+ */
+
+/**
+ * Reasons that always bypass semantic dedup.
+ * These are explicit user/system requests that should ALWAYS produce a frame.
+ */
+const BYPASS_DEDUP_REASONS = 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 = new Set(['interaction', 'navigation', 'scroll', 'screen_loaded']);
+
+// ─── Manager ────────────────────────────────────────────────────────────────
+
+class ReplayCaptureManager {
+  /** Optional native file-outbox path. When ready, frames stage→commit natively. */
+
+  onFrameEmit = null;
+  onLoadingInterval = null;
+  frames = [];
+  /** Set of frameIds near crashes — never evict */
+  protectedFrameIds = new Set();
+  frequencyTimer = null;
+  capturing = false;
+  currentScreen = null;
+  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.
+   */
+  _inFlightRequests = 0;
+  _lastRequestStartTs = 0;
+  _lastRequestEndTs = 0;
+
+  /** Epoch ms past which a capture held for loading fires regardless. 0 when nothing is held. */
+  pendingInteractionDeadline = 0;
+  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.
+  activityTimer = null;
+  activityGen = -1;
+  activityWindowEnd = 0;
+  activitySamples = 0;
+  activityUnchangedStreak = 0;
+  activityMinuteStart = 0;
+  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.
+   */
+  navHoldStartedAt = 0;
+  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.
+   */
+  captureGeneration = 0;
+
+  /**
+   * Tracked navigation capture timeout.
+   * Cancelled on stop() and on each new onScreenChange() call (debounce).
+   */
+  pendingNavTimeout = null;
+  /** Screen associated with the pending navigation capture */
+  pendingNavScreen = null;
+
+  /**
+   * Tracked scroll settle capture timeout.
+   * Cancelled on stop().
+   */
+  pendingScrollTimeout = null;
+
+  /**
+   * Tracked loading end capture timeout.
+   * Cancelled on stop().
+   */
+  pendingLoadingTimeout = null;
+  /** Screen associated with the pending loading capture */
+  pendingLoadingScreen = 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.
+   */
+  pendingInteractionTimeout = null;
+  /** Interaction point metadata held while pending (carried to nav if absorbed) */
+  pendingInteractionPoint = undefined;
+  /** Screen at the time the pending interaction was created */
+  pendingInteractionScreen = 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.
+   */
+  lastCompletedInteraction = 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.
+   */
+  _inFlightInteractionScreen = undefined;
+  _inFlightInteractionPoint = undefined;
+  _suppressInFlightInteraction = false;
+
+  /**
+   * Last completed capture intent — used for semantic dedup.
+   * Captures with the same reason + screen within SAME_INTENT_COOLDOWN_MS are suppressed.
+   */
+  lastCaptureIntent = null;
+
+  // ── P2-0/1/5 capture state ──────────────────────────────────────────
+  /** P2-0: monotonic per-session sequence; first emitted frame is 1. */
+  _sequenceCounter = 0;
+  /** P2-1: hash of the last EMITTED frame, for visual change detection. */
+  _lastFrameHash = null;
+  /** P2-1/5: wall-clock of the last emitted keyframe (heartbeat base). */
+  _lastKeyframeTs = 0;
+  /** Scroll containers visible in the last keyframe (native), so a tap's link to it can be checked. */
+  _lastKeyframeScroll = undefined;
+  /** P2-5: frameId of the last emitted keyframe — delta base reference. */
+  _lastKeyframeId = 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.
+   */
+  _lastKeyframeScreen = null;
+  /** P2-5: emitted frames since the last keyframe (keyframe-interval guard). */
+  _framesSinceKeyframe = 0;
+  constructor(sessionId, config, nativeCapture, outboxCapture) {
+    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, maxAgeMs = 10_000, now = Date.now()) {
+    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) {
+    this.onFrameEmit = cb;
+  }
+
+  /** Set the callback that turns a held wait into LOADING_STARTED / LOADING_COMPLETED events. */
+  setLoadingIntervalCallback(cb) {
+    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.
+   */
+  _openHold(lane, screen) {
+    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.
+   */
+  _closeHold(lane, reason) {
+    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() {
+    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__ && _internalLogger.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() {
+    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__ && _internalLogger.logger.debug(`[ReplayCaptureManager] Resumed (mode=${this.config.captureMode})`);
+  }
+  get isCapturing() {
+    return this.capturing;
+  }
+  _startFrequencyTimer() {
+    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__ && _internalLogger.logger.debug(`[ReplayCaptureManager] Frequency mode: every ${intervalMs}ms`);
+  }
+
+  /** Stop capture — cancels ALL pending timers and increments generation */
+  stop(reason = 'session_end') {
+    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__ && _internalLogger.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) {
+    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.)
+   */
+  _loadingHoldMs(triggeredAt, deadline) {
+    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) {
+    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;
+      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__ && _internalLogger.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__ && _internalLogger.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__ && _internalLogger.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 = () => {
+        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) {
+    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__ && _internalLogger.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 = () => {
+      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) {
+    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) {
+    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__ && _internalLogger.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) {
+    return this.triggerCapture(reason, this.currentScreen ?? undefined);
+  }
+
+  /** Protect frames near a crash from eviction */
+  protectFramesNearCrash(crashTimestamp, windowMs = 10_000) {
+    const protectedIds = [];
+    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() {
+    return this.frames;
+  }
+
+  /** Get frame IDs for artifact index */
+  getFrameRefs() {
+    return this.frames.map(f => f.frameId);
+  }
+
+  /** Current frame count */
+  get count() {
+    return this.frames.length;
+  }
+
+  /** Clear all frames */
+  clear() {
+    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.
+   */
+  async triggerCapture(reason, screenName, interactionPoint) {
+    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__ && _internalLogger.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 = null;
+      if (this.outboxCapture) {
+        staged = await this.outboxCapture.capture(this.sessionId, screen, reason);
+      }
+      const usedStaged = staged !== null;
+      let result;
+      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 = () => {
+        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__ && _internalLogger.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__ && _internalLogger.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__ && _internalLogger.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__ && _internalLogger.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 = 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 = {
+        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 = {
+          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__ && _internalLogger.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;
+      }
+      _internalLogger.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.
+   */
+  _openActivityWindow(gen) {
+    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);
+  }
+  async _activityTick() {
+    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.
+   */
+  _evictLowestPriorityFrame() {
+    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 = (0, _sessionTypes.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 ────────────────────────────────────────────────────────
+
+  _isExcludedScreen(screenName) {
+    return this.config.privacyPolicy.captureExclusions.includes(screenName);
+  }
+}
+
+// ─── Utils ──────────────────────────────────────────────────────────────────
+exports.ReplayCaptureManager = ReplayCaptureManager;
+function generateFrameId() {
+  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) {
+  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)}`;
+}
+//# sourceMappingURL=ReplayCaptureManager.js.map