@scalebun-release/react-native 2.5.0

package/src/features/session/SessionManager.ts

@@ -0,0 +1,1687 @@
+/**
+ * ScaleBun SDK — Session Manager
+ *
+ * Central orchestrator for the unified session system.
+ * Manages session lifecycle, wires pipeline + capture + transport + sync.
+ *
+ * Architecture:
+ * - Singleton per debug session
+ * - Creates and owns JourneyEventPipeline, ReplayCaptureManager,
+ *   DesktopSessionTransport, SyncDecisionEngine
+ * - Receives events from ScaleBunDebugRoot (nav, interactions), DebugEventStream
+ *   (network, logs), and breadcrumbs
+ * - Coordinates crash anchoring across events AND frames
+ * - Auto-timeout via maxDurationMs
+ */
+
+import { frameLinkVerdict } from './frameLink';
+import { logger } from '../../core/logger/internalLogger';
+import type { DebugTransport } from '../../debug/transport';
+import type {
+    Session,
+    SessionMetadata,
+    SessionReplayConfig,
+    JourneyEventType,
+    JourneyEventSeverity,
+    JourneyEventSource,
+    CrashAnchor,
+    NativeSyncMetadata,
+    SyncDecisionCallback,
+} from './sessionTypes';
+import { DEFAULT_SESSION_REPLAY_CONFIG } from './sessionTypes';
+import { JourneyEventPipeline } from './JourneyEventPipeline';
+import { ReplayCaptureManager, type NativeCaptureFn, type OutboxFrameCapture } from './ReplayCaptureManager';
+import { makeOutboxFrameCapture } from './outboxFrameCapture';
+import { DesktopSessionTransport } from './DesktopSessionTransport';
+import { SyncDecisionEngine } from './SyncDecisionEngine';
+import { ScrollTracker, type ScrollMetadata } from './ScrollTracker';
+import type { BackendSessionAdapter } from './BackendSessionAdapter';
+import type { JourneyEvent } from './sessionTypes';
+import { generateEventId } from '../replay/core/ids/sessionId';
+import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
+import { redactBody } from '../../debug/redaction';
+import { consumeCalibrationTarget } from '../journey/calibrationContext';
+import { resolvePlatformOS } from '../../core/context/device';
+import { emitAutomaticEvent } from '../../analytics/automaticEvents';
+import { checkViewport } from './viewportPlausibility';
+import { quotaState } from '../../config/quotaState';
+import {
+    INTERACTION_PROTOCOL_VERSION,
+    automaticInteractionProperties,
+    generateInteractionId,
+    type InteractionStateStatus,
+} from '../journey/interactionProtocol';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface SessionManagerConfig {
+    sessionReplay?: Partial<SessionReplayConfig>;
+    syncPolicy?: SyncDecisionCallback;
+    /**
+     * Feature #4 (heatmaps): when true, tap/gesture coordinates are ALSO routed
+     * to the always-on analytics lane so coords are captured even when no replay
+     * recording is active. Additive — does NOT change replay-recording capture.
+     * Unset → false at this layer (safety floor for direct construction); the
+     * product default (true) is applied by ConfigSchema and passed in by the
+     * bootstrapper. See ConfigSchema.captureInteractionHeatmap.
+     */
+    captureInteractionHeatmap?: boolean;
+}
+
+// ─── Singleton ──────────────────────────────────────────────────────────────
+
+let _instance: SessionManager | null = null;
+
+// ─── Session Manager ────────────────────────────────────────────────────────
+
+export class SessionManager {
+    private desktopTransport: DesktopSessionTransport | null = null;
+    private pipeline: JourneyEventPipeline;
+    private captureManager: ReplayCaptureManager;
+    private syncEngine: SyncDecisionEngine;
+    private scrollTracker: ScrollTracker | null = null;
+    private _backendTransport: BackendSessionAdapter | null = null;
+    private config: SessionReplayConfig;
+    /**
+     * Feature #4 (heatmaps): route tap/gesture coords to the always-on analytics
+     * lane even when no replay recording is active. Additive, opt-in (default off).
+     */
+    private _captureInteractionHeatmap = false;
+    private session: Session | null = null;
+    private active = false;
+    private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+    private crashAnchors: CrashAnchor[] = [];
+    /** Tracks loading-start timestamps per screen for duration computation */
+    private loadingStartTimes = new Map<string, number>();
+    /**
+     * Always-tracked current screen name.
+     * Updated by onScreenChange even when session is inactive, so that when
+     * startSession is called we know what screen the user is currently on and
+     * can emit the initial SCREEN_VIEW + navigation capture immediately.
+     * This is read-only metadata — does NOT produce events or frames while inactive.
+     */
+    private _lastKnownScreen: string | null = null;
+    /** When the current screen was entered — the basis for SCREEN_EXIT's measured dwellMs. */
+    private _screenEnteredAt: number | null = null;
+
+    /**
+     * Last screenshot-base dimensions reported by the native interaction tracker.
+     * Stored in JS-coordinate units (dp on Android, pt on iOS) — both are the same
+     * unit RN uses for pageX/pageY, so JS-fallback taps can divide directly without
+     * additional conversion. This is the EXACT base the native screenshot is captured
+     * in, and avoids using Dimensions.get('window') (which excludes system insets
+     * differently across devices and pushes markers ~10% off vertically).
+     */
+    private _lastNativeViewportJsUnits: { width: number; height: number; space: string } | null = null;
+
+    /**
+     * Exact-duplicate gesture suppression (QA: one physical tap recorded 2–3×).
+     *
+     * Measured in production data: the native tracker re-emitted the SAME tap — identical
+     * gestureType and identical coordinates to the SUB-PIXEL (e.g. x=466.962890625) — at
+     * 160–240ms gaps, sometimes twice. A human re-tap cannot reproduce a sub-pixel float
+     * exactly, so exact coordinate equality within the window is a safe discriminator: real
+     * double-taps land on at least slightly different pixels and pass through untouched.
+     * The pipeline's own 100ms dedup was too narrow for these; this window covers what was
+     * actually observed with margin. Sits at the ONE entry point every gesture source funnels
+     * through, so recording and analytics lanes are protected equally.
+     */
+    private _lastGestureSig: string | null = null;
+    private _lastGestureTs = 0;
+    private static readonly GESTURE_DEDUP_WINDOW_MS = 400;
+
+    private _nativeCapture: NativeCaptureFn;
+    private _rawTransport: DebugTransport | null;
+    /** Memoized native file-outbox frame adapter (gated by the backend transport). */
+    private _outboxFrameCapture: OutboxFrameCapture | null = null;
+    /** Unsubscribe from quotaState (released in resetInstance). */
+    private _quotaUnsub: (() => void) | null = null;
+    /** True while frame capture is paused by a `frames` quota block inside an active session. */
+    private _framesQuotaPaused = false;
+    /**
+     * Whether capture has run at all in the CURRENT session. Decides start() vs resume() when a
+     * frames block lifts: resume() continues the session's sequence, which is only right if this
+     * session already produced frames; a session that began blocked gets a clean start().
+     */
+    private _captureStartedThisSession = false;
+
+    constructor(
+        debugTransport: DebugTransport | null,
+        nativeCapture: NativeCaptureFn,
+        managerConfig?: SessionManagerConfig,
+    ) {
+        this._rawTransport = debugTransport;
+        this._nativeCapture = nativeCapture;
+
+        // Merge config with defaults
+        this.config = {
+            ...DEFAULT_SESSION_REPLAY_CONFIG,
+            ...managerConfig?.sessionReplay,
+            privacyPolicy: {
+                ...DEFAULT_SESSION_REPLAY_CONFIG.privacyPolicy,
+                ...managerConfig?.sessionReplay?.privacyPolicy,
+            },
+        };
+
+        // Create subsystems
+        this.desktopTransport = debugTransport ? new DesktopSessionTransport(debugTransport) : null;
+
+        this.pipeline = new JourneyEventPipeline('', {
+            maxEventCount: this.config.maxEventCount,
+        });
+
+        this.captureManager = new ReplayCaptureManager(
+            '',
+            this.config,
+            nativeCapture,
+            this._getOutboxFrameCapture(),
+        );
+
+        this._captureInteractionHeatmap = managerConfig?.captureInteractionHeatmap === true;
+
+        this.syncEngine = new SyncDecisionEngine(managerConfig?.syncPolicy);
+
+        // Wire pipeline → transport (desktop + optional backend)
+        this.pipeline.setEmitCallback((event) => {
+            this.desktopTransport?.sendEvent(event);
+            this._backendTransport?.sendEvent(event);
+        });
+
+        // Wire capture → transport (desktop + optional backend)
+        this.captureManager.setFrameEmitCallback((frame, imageData) => {
+            this.desktopTransport?.sendFrame(frame, imageData);
+            this._backendTransport?.sendFrame(frame, imageData);
+        });
+
+        this._wireLoadingIntervals();
+
+        // Per-feature quota (contract v1): a `frames` block stops capture NOW (not just upload), and
+        // its end resumes capture in the SAME session starting from a fresh keyframe.
+        this._quotaUnsub = quotaState.subscribe((feature, blocked) => {
+            if (feature === 'frames') this._onFramesQuota(blocked);
+        });
+    }
+
+    /**
+     * Stop or resume frame capture for a `frames` quota block.
+     *
+     * Stopping goes through `captureManager.stop()` — every pending capture timer is cancelled and
+     * the generation bump discards captures already in flight. The adapter purges what was queued.
+     * The session itself keeps running: events, network and errors are governed by their own quotas.
+     */
+    private _onFramesQuota(blocked: boolean): void {
+        try {
+            if (blocked) {
+                if (this.active && !this._framesQuotaPaused) {
+                    this.captureManager.stop('quota_pause');
+                    this._framesQuotaPaused = true;
+                    logger.warn('[SessionManager] Replay frames quota exceeded — frame capture stopped');
+                }
+                return;
+            }
+            if (!this._framesQuotaPaused) return;
+            this._framesQuotaPaused = false;
+            if (!this.active) return;
+            if (this._captureStartedThisSession) {
+                this.captureManager.resume();
+            } else {
+                this.captureManager.start(); // fresh per-session state: sequence 0, keyframe first
+                this._captureStartedThisSession = true;
+            }
+            // A keyframe right away: the frames before the pause were discarded, so without one the
+            // replay would show nothing until the next navigation/interaction capture.
+            this.captureManager.captureManual('manual').catch(() => { });
+            __DEV__ && logger.info('[SessionManager] Replay frames quota lifted — capture resumed with a keyframe');
+        } catch (err) {
+            logger.warn('[SessionManager] frames quota transition failed:', err);
+        }
+    }
+
+    /**
+     * A wait the capture manager sat through becomes a pair of journey events.
+     *
+     * The frame it eventually takes shows the LOADED screen, which leaves the span between the
+     * tap and that frame unaccounted for — and the player resolves an unaccounted playhead to the
+     * previous frame, so it would show the screen the visitor had already left. These two events
+     * are what lets the timeline say "this screen was loading, for this long" instead, at roughly
+     * 1 KB against the ~56 KB a second screenshot would cost.
+     *
+     * `reason` rides on the payload rather than becoming a third event type: `timeout` and
+     * `network_idle` are the same interval with different endings, and a consumer that does not
+     * know about the distinction should still see the band.
+     */
+    private _wireLoadingIntervals(): void {
+        this.captureManager.setLoadingIntervalCallback((phase, screen, detail) => {
+            if (phase === 'start') {
+                this.emitEvent('LOADING_STARTED', {
+                    screen,
+                    payload: { screen, source: 'replay-hold' },
+                    source: 'sdk',
+                });
+                return;
+            }
+            this.emitEvent('LOADING_COMPLETED', {
+                screen,
+                payload: {
+                    screen,
+                    durationMs: detail.durationMs,
+                    reason: detail.reason,
+                    source: 'replay-hold',
+                },
+                source: 'sdk',
+            });
+        });
+    }
+
+    // ─── Singleton Access ───────────────────────────────────────────────
+
+    static getInstance(
+        debugTransport: DebugTransport | null,
+        nativeCapture: NativeCaptureFn,
+        config?: SessionManagerConfig,
+    ): SessionManager {
+        if (!_instance) {
+            _instance = new SessionManager(debugTransport, nativeCapture, config);
+        }
+        return _instance;
+    }
+
+    static getExistingInstance(): SessionManager | null {
+        return _instance;
+    }
+
+    static resetInstance(): void {
+        if (_instance) {
+            _instance.endSession();
+            _instance._quotaUnsub?.();
+            _instance._quotaUnsub = null;
+        }
+        _instance = null;
+    }
+
+    /**
+     * Attach a backend transport for uploading replay data to the backend API.
+     * This is additive — the existing desktop transport remains active if present.
+     */
+    setBackendTransport(transport: BackendSessionAdapter): void {
+        this._backendTransport = transport;
+        // A session whose START the backend refused for quota has no row and never will: end the
+        // recording instead of capturing into a transport that drops everything for it.
+        transport.setSessionRefusedHandler?.((sessionId) => {
+            if (this.active && this.currentSessionId === sessionId) this.endSession();
+        });
+        __DEV__ && logger.info('[SessionManager] Backend transport attached (replay → backend upload enabled)');
+    }
+
+    /** Expose the backend transport so features can queue network/errors/performance. */
+    getBackendTransport(): BackendSessionAdapter | null {
+        return this._backendTransport;
+    }
+
+    /**
+     * Memoized native file-outbox frame adapter. Always injected into the capture
+     * manager; its readiness gate (backed by the backend transport) resolves false
+     * when the outbox flags are off / the binary is old, so capture transparently
+     * falls back to the legacy `captureScreenshot` path. The closure reads the
+     * backend transport lazily at capture time (it attaches after construction).
+     */
+    private _getOutboxFrameCapture(): OutboxFrameCapture {
+        if (!this._outboxFrameCapture) {
+            this._outboxFrameCapture = makeOutboxFrameCapture(
+                () => this._backendTransport?.ensureNativeOutboxReady() ?? Promise.resolve(false),
+            );
+        }
+        return this._outboxFrameCapture;
+    }
+
+    /**
+     * Attach a desktop transport dynamically.
+     * Called when debug mode connects after SDK initialization.
+     */
+    setDesktopTransport(debugTransport: DebugTransport): void {
+        this.desktopTransport = new DesktopSessionTransport(debugTransport);
+        __DEV__ && logger.info('[SessionManager] Desktop transport attached');
+    }
+
+    // ─── Session Lifecycle ──────────────────────────────────────────────
+
+    get isActive(): boolean {
+        return this.active;
+    }
+
+    get currentSessionId(): string | null {
+        return this.session?.sessionId ?? null;
+    }
+
+    get currentSessionMetadata(): SessionMetadata | null {
+        return this.session?.metadata ?? null;
+    }
+
+    /**
+     * The active RECORDING session ID (`ses-xxx`), or null when no recording
+     * is in progress.
+     *
+     * This is the canonical field that DebugEventStream stamps into every
+     * outgoing event's `data.recordingSessionId`. It is the single source of
+     * truth for correlating network and performance events with the session
+     * that was active when they were captured.
+     *
+     * Distinct from the TRANSPORT session ID (`debug-xxx`) which lives on
+     * the wire envelope's top-level `sessionId` field and never changes.
+     */
+    get recordingSessionId(): string | null {
+        return this.active ? (this.session?.sessionId ?? null) : null;
+    }
+
+    /**
+     * Update the native capture function at runtime.
+     * Called by ScaleBunDebugRoot once the root View ref is ready for ViewShot.
+     * Also updates the active session's capture manager if one exists.
+     */
+    setNativeCapture(captureFn: NativeCaptureFn): void {
+        this._nativeCapture = captureFn;
+        // Hot-swap into active capture manager if session is running
+        if (this.active && this.captureManager) {
+            (this.captureManager as any).nativeCapture = captureFn;
+            __DEV__ && logger.info('[SessionManager] Capture function updated (hot-swap)');
+        }
+    }
+
+    /**
+     * Start a new session. Idempotent — no-op if already active.
+     */
+    startSession(metadata?: Partial<SessionMetadata>): void {
+        try {
+            if (this.active) {
+                __DEV__ && logger.debug('[SessionManager] Session already active, skipping start');
+                return;
+            }
+
+            // Quota (contract v1): a `sessions` block stops NEW sessions. Adopting an analytics
+            // session that is already open is not a new session, so that path stays allowed; minting
+            // a fresh recording id to post a new INGESTION_START is not.
+            if (this._backendTransport && !this._backendTransport.analyticsSessionId && quotaState.isBlocked('sessions')) {
+                logger.warn('[SessionManager] Session not started — sessions quota exceeded');
+                return;
+            }
+
+            // One-row merge: adopt the always-on analytics ingestion id as this
+            // recording session's id when the backend (SaaS) lane has one open.
+            // This threads the analytics id through the pipeline + capture manager
+            // below, so every frame/event body carries it AND it becomes
+            // currentSessionId at sendSessionStart — keeping endpoint id == body id
+            // while attaching frames/journey to the single analytics row (no second
+            // INGESTION_START). Legacy/no-clientKey mode has no analytics id → mint
+            // a fresh recording id and post to /replay/... as before.
+            const sessionId = this._backendTransport?.analyticsSessionId ?? generateSessionId();
+
+            // Create fresh subsystems for this session
+            this.pipeline = new JourneyEventPipeline(sessionId, {
+                maxEventCount: this.config.maxEventCount,
+            });
+            this.pipeline.setEmitCallback((event) => {
+                this.desktopTransport?.sendEvent(event);
+                this._backendTransport?.sendEvent(event);
+            });
+
+            this.captureManager = new ReplayCaptureManager(
+                sessionId,
+                this.config,
+                this._nativeCapture,
+                this._getOutboxFrameCapture(),
+            );
+            this.captureManager.setFrameEmitCallback((frame, imageData) => {
+                this.desktopTransport?.sendFrame(frame, imageData);
+                this._backendTransport?.sendFrame(frame, imageData);
+            });
+
+            // A NEW capture manager starts with no callbacks. Frame emission is re-wired above;
+            // loading intervals have to be re-wired here for the same reason, or every session
+            // after the first records frames and silently stops recording the waits between them.
+            this._wireLoadingIntervals();
+
+            // Create scroll tracker — wired to emit events + trigger capture on settle
+            this.scrollTracker = new ScrollTracker((scrollMeta: ScrollMetadata) => {
+                if (!this.active) return;
+
+                // Synthesize representative coordinates for the scroll.
+                // ScrollTracker only knows content deltas — it has no absolute touch
+                // point — but the dashboard CorrelationEngine DROPS any interaction
+                // without x/y, and the replay overlay draws scroll/swipe as an arrow
+                // that needs normalizedEnd coords. Without this, ScaleBunScrollView scrolls
+                // were invisible AND uncounted. Anchor the gesture at screen center and
+                // extend by the finger displacement (opposite the content offset delta),
+                // matching the finger-path convention native swipes already use.
+                const vw = this.session?.metadata?.screenWidth ?? 0;
+                const vh = this.session?.metadata?.screenHeight ?? 0;
+                const coords: Record<string, number | boolean> = {};
+                if (vw > 0 && vh > 0) {
+                    const cx = vw / 2;
+                    const cy = vh / 2;
+                    const ex = Math.max(0, Math.min(vw, cx - scrollMeta.totalDeltaX));
+                    const ey = Math.max(0, Math.min(vh, cy - scrollMeta.totalDeltaY));
+                    coords.x = cx;
+                    coords.y = cy;
+                    coords.endX = ex;
+                    coords.endY = ey;
+                    coords.normalizedX = cx / vw;
+                    coords.normalizedY = cy / vh;
+                    coords.normalizedEndX = ex / vw;
+                    coords.normalizedEndY = ey / vh;
+                    coords.viewportWidth = vw;
+                    coords.viewportHeight = vh;
+                    coords.normalizedPrecomputed = true;
+                }
+
+                // Emit gesture:scroll event.
+                // emitEvent() triggers captureManager.onScrollSettle() internally
+                // for USER_ACTION events with gestureType='scroll' — no explicit call needed.
+                this.emitEvent('USER_ACTION', {
+                    subtype: 'gesture:scroll',
+                    payload: {
+                        gestureType: 'scroll',
+                        totalDeltaX: scrollMeta.totalDeltaX,
+                        totalDeltaY: scrollMeta.totalDeltaY,
+                        dominantDirection: scrollMeta.dominantDirection,
+                        direction: scrollMeta.dominantDirection,
+                        durationMs: scrollMeta.durationMs,
+                        startTs: scrollMeta.startTs,
+                        endTs: scrollMeta.endTs,
+                        confidence: 'high',
+                        ...coords,
+                    },
+                    source: 'user',
+                });
+            });
+
+            this.crashAnchors = [];
+            this.loadingStartTimes.clear();
+
+            // Build session object
+            this.session = {
+                sessionId,
+                deviceId: this._rawTransport?.deviceId ?? 'unknown',
+                startedAt: Date.now(),
+                status: 'active',
+                metadata: {
+                    // The real Platform.OS. This used to be a ternary whose else-branch was 'android'
+                    // and whose catch was ALSO 'android' — so a macOS session, a Windows session, and
+                    // a failure to load react-native at all were reported identically, as Android.
+                    // Enriched by native device info when the bridge answers.
+                    platform: resolvePlatformOS(),
+                    buildType: __DEV__ ? 'debug' : 'release',
+                    ...metadata,
+                    // Capture window dp dims here so emitEvent() can normalize coords
+                    // without re-querying Dimensions on every gesture event.
+                    ...(() => {
+                        if (metadata?.screenWidth && metadata?.screenHeight) return {};
+                        try {
+                            const { Dimensions } = require('react-native');
+                            const dims = Dimensions.get('window');
+                            if (dims.width > 0 && dims.height > 0) {
+                                return { screenWidth: dims.width, screenHeight: dims.height };
+                            }
+                        } catch { /* no-throw */ }
+                        return {};
+                    })(),
+                },
+                transportState: 'local',
+                syncState: 'pending-evaluation',
+                artifactIndex: {
+                    frameRefs: [],
+                    eventRefs: [],
+                    networkRefs: [],
+                    logRefs: [],
+                    crashAnchors: [],
+                },
+            };
+
+            this.active = true;
+
+            // Enrich the live session metadata with native device info (appVersion,
+            // deviceModel, osVersion, …) so synchronous consumers — e.g. the engage
+            // response builder reading `currentSessionMetadata.appVersion` — see real
+            // values rather than the platform-only subset known at create time. The
+            // session-start metadata above is the fallback when the bridge is
+            // unavailable (old native binary). Fire-and-forget, never throws.
+            Promise.resolve()
+                .then(() => bridgeAdapter.getDeviceInfo())
+                .then(info => {
+                    const s = this.session;
+                    if (!info || !s) return;
+                    const m = s.metadata;
+                    s.metadata = {
+                        ...m,
+                        appVersion: info.appVersion ?? m.appVersion,
+                        appName: info.appName ?? m.appName,
+                        bundleId: info.bundleId ?? m.bundleId,
+                        osVersion: info.osVersion ?? m.osVersion,
+                        deviceModel: info.deviceModel ?? m.deviceModel,
+                    };
+                })
+                .catch(() => {
+                    /* no-throw: metadata-only fallback */
+                });
+
+            // Notify transport (desktop + optional backend)
+            this.desktopTransport?.sendSessionStart(this.session);
+            this._backendTransport?.sendSessionStart(this.session);
+
+            // Emit SESSION_STARTED event
+            this.pipeline.emit('SESSION_STARTED', {
+                payload: { sessionId },
+                source: 'system',
+            });
+
+            // Start capture manager — unless the `frames` quota is spent, in which case the session
+            // runs without frame capture and resumes it (with a keyframe) when the block lifts.
+            if (quotaState.isBlocked('frames')) {
+                this._framesQuotaPaused = true;
+                this._captureStartedThisSession = false;
+                logger.warn('[SessionManager] Replay frames quota exceeded — session started without frame capture');
+            } else {
+                this._framesQuotaPaused = false;
+                this._captureStartedThisSession = true;
+                this.captureManager.start();
+            }
+
+            // Set timeout
+            if (this.config.maxDurationMs > 0) {
+                this.timeoutTimer = setTimeout(() => {
+                    __DEV__ && logger.debug('[SessionManager] Session timeout reached');
+                    this.endSession('timeout');
+                }, this.config.maxDurationMs);
+            }
+
+            __DEV__ && logger.info(`[SessionManager] Session started: ${sessionId}`);
+
+            // ── Replay initial screen ──────────────────────────────────────
+            // If the user was already on a screen before pressing Record
+            // (typical: app mounted → screen hook fired → screen tracked),
+            // emit the initial SCREEN_VIEW now so the session captures the
+            // starting screen and triggers the first navigation frame.
+            if (this._lastKnownScreen) {
+                this.emitEvent('SCREEN_VIEW', {
+                    screen: this._lastKnownScreen,
+                    subtype: this._lastKnownScreen,
+                    source: 'sdk',
+                });
+            }
+        } catch (err) {
+            logger.error('[SessionManager] Failed to start session:', err);
+        }
+    }
+
+    /**
+     * End the current session.
+     */
+    endSession(reason: 'ended' | 'timeout' = 'ended'): void {
+        // Fully idempotent — safe to call multiple times
+        if (!this.active) {
+            return;
+        }
+
+        // Disable collection FIRST to prevent any re-entrant emission during teardown
+        this.active = false;
+
+        // Guard: session must exist (should always be true if active was true)
+        if (!this.session) return;
+
+        try {
+
+            // Clear timeout
+            if (this.timeoutTimer) {
+                clearTimeout(this.timeoutTimer);
+                this.timeoutTimer = null;
+            }
+
+            // Dispose scroll tracker — cancels pending settle timer
+            if (this.scrollTracker) {
+                this.scrollTracker.dispose();
+                this.scrollTracker = null;
+            }
+
+            // Clear loading state
+            this.loadingStartTimes.clear();
+
+            // Emit SESSION_ENDED event
+            this.pipeline.emit('SESSION_ENDED', {
+                payload: { reason },
+                source: 'system',
+            });
+
+            // Stop capture — this cancels ALL pending timers and increments generation
+            this.captureManager.stop();
+
+            // Build final artifact index
+            const eventRefs = this.pipeline.buildEventRefs();
+            this.session.artifactIndex = {
+                ...eventRefs,
+                frameRefs: this.captureManager.getFrameRefs(),
+                crashAnchors: this.crashAnchors,
+            };
+
+            // Finalize session
+            this.session.endedAt = Date.now();
+            this.session.status = reason === 'timeout' ? 'timeout' : 'ended';
+
+            // Run sync evaluation
+            const hasCrash = this.crashAnchors.length > 0;
+            const hasError = this.pipeline.getEvents().some(
+                e => e.type === 'ERROR_CAPTURED',
+            );
+
+            const candidate = SyncDecisionEngine.buildCandidate(
+                this.session.sessionId,
+                this.session.metadata,
+                this.pipeline.count,
+                this.captureManager.count,
+                (this.session.endedAt - this.session.startedAt),
+                hasCrash,
+                hasError,
+            );
+
+            const decision = this.syncEngine.evaluate(candidate);
+            this.session.syncState = decision.shouldSync ? 'eligible' : 'ineligible';
+
+            // Notify transport (desktop + optional backend)
+            this.desktopTransport?.sendSessionEnd(this.session);
+            this._backendTransport?.sendSessionEnd(this.session);
+
+            // Clean up
+            this.pipeline.clear();
+            this.captureManager.clear();
+            // (this.active already set to false above)
+
+            __DEV__ && logger.info(
+                `[SessionManager] Session ended: ${this.session.sessionId} ` +
+                `(${reason}, sync=${decision.shouldSync}, priority=${decision.priority})`,
+            );
+        } catch (err) {
+            logger.error('[SessionManager] Failed to end session:', err);
+            // active is already false — no further cleanup needed
+        }
+    }
+
+    // ─── Event Emission ─────────────────────────────────────────────────
+
+    /**
+     * Resolve the dp-space base used to normalize JS-fallback tap coordinates.
+     *
+     * The screenshot is captured by native in the content-view at its physical
+     * pixel size. Normalized coords must divide by that SAME region (converted
+     * to dp, since pageX/pageY are dp). Using Dimensions.get('window') (or
+     * session.metadata, which is seeded from it) excludes system insets and is
+     * ~10% smaller than the content-view — pushing markers off. Preference order:
+     * native content-view (px→dp) → session metadata → payload → Dimensions.
+     */
+    private _resolveNormalizationBaseDp(
+        p: Record<string, any>,
+    ): { width: number; height: number; space: string } | null {
+        // Native screenshot-base size in JS-coordinate units (dp on Android, pt on iOS).
+        // This is the EXACT region the native screenshot was captured in, so JS-fallback
+        // taps (pageX/pageY in dp/pt) divide directly into the same coord space the
+        // marker overlay uses on the dashboard. Highest priority — session metadata
+        // and Dimensions.get('window') report the app window which excludes system
+        // insets differently across devices and pushes markers off vertically.
+        if (this._lastNativeViewportJsUnits) {
+            return {
+                width: this._lastNativeViewportJsUnits.width,
+                height: this._lastNativeViewportJsUnits.height,
+                space: this._lastNativeViewportJsUnits.space,
+            };
+        }
+
+        const mw = this.session?.metadata?.screenWidth;
+        const mh = this.session?.metadata?.screenHeight;
+        if (mw && mh) return { width: mw, height: mh, space: 'session-metadata-dp' };
+
+        if (typeof p.viewportWidth === 'number' && p.viewportWidth > 0
+            && typeof p.viewportHeight === 'number' && p.viewportHeight > 0) {
+            return { width: p.viewportWidth, height: p.viewportHeight, space: 'payload-viewport-dp' };
+        }
+
+        try {
+            const { Dimensions } = require('react-native');
+            const dims = Dimensions.get('window');
+            if (dims.width > 0 && dims.height > 0) {
+                return { width: dims.width, height: dims.height, space: 'root-view-dp' };
+            }
+        } catch { /* no-throw */ }
+
+        return null;
+    }
+
+    /**
+     * Inject/resolve normalized tap coordinates into a USER_ACTION payload, in place.
+     *
+     * Mutates `p` to carry normalizedX/Y (+ end coords for swipes/scrolls) so the
+     * heatmap can overlay them across viewport sizes. Returns true when the source
+     * already provided high-confidence / pre-computed normalized coords (native or
+     * JS-root-measured), false when this method JS-estimated them.
+     *
+     * Extracted from emitEvent so BOTH the replay-recording lane AND the always-on
+     * analytics lane (Feature #4) normalize identically — keeping the tap payload
+     * keys byte-for-byte the same on both routes.
+     */
+    private _normalizeInteractionPayload(p: Record<string, unknown>): boolean {
+        // If native tracker already provided high-confidence normalized coords,
+        // OR the JS path measured the root-view rect and precomputed normalized
+        // coords against it, do not overwrite them with JS estimation.
+        const hasNormalizedXY = typeof p.normalizedX === 'number'
+            && typeof p.normalizedY === 'number';
+        const alreadyNormalized = hasNormalizedXY
+            && (p.confidence === 'high' || p.normalizedPrecomputed === true);
+
+        if (alreadyNormalized) {
+            // Cache the native screenshot base in JS-coordinate units (dp/pt)
+            // so subsequent JS-fallback taps normalize against the same region
+            // the screenshot was captured from. Android sends px (suffix -px),
+            // iOS sends pt (suffix -pt). Both are converted to the unit RN
+            // pageX/pageY use, so JS taps divide directly with no extra math.
+            const cs = typeof p.coordinateSpace === 'string' ? p.coordinateSpace : '';
+
+            /**
+             * TRUST, BUT CHECK. `confidence: 'high'` means the NATIVE layer measured it — not that
+             * the number is right. One production device reports a content view of 288x448 px while
+             * telling us its layout width is 434.7dp, an implied density of 0.663 that no screen
+             * has. Cached unchecked, that wrong base then normalised every tap in the session and
+             * became the screenshot's coordinate space too.
+             *
+             * `windowWidth` and `density` are attached here so the check has both sides of the
+             * invariant and so the BACKEND can re-derive the same verdict from the stored payload —
+             * see `viewportPlausibility.ts` for the rule and the 56-device measurement behind it.
+             */
+            let density = 0;
+            let windowWidth = 0;
+            try {
+                const { PixelRatio, Dimensions } = require('react-native');
+                density = PixelRatio.get();
+                windowWidth = Dimensions.get('window').width;
+            } catch { /* no-throw */ }
+
+            const check = checkViewport({
+                viewportWidth: typeof p.viewportWidth === 'number' ? p.viewportWidth : null,
+                viewportHeight: typeof p.viewportHeight === 'number' ? p.viewportHeight : null,
+                windowWidth: windowWidth > 0 ? windowWidth : null,
+                coordinateSpace: cs,
+                density: density > 0 ? density : null,
+            });
+            p.viewportCheck = check.verdict;
+            if (check.reason) p.viewportCheckReason = check.reason;
+            if (check.impliedDensity != null) p.impliedDensity = check.impliedDensity;
+
+            if (typeof p.viewportWidth === 'number' && p.viewportWidth > 0
+                && typeof p.viewportHeight === 'number' && p.viewportHeight > 0
+                && check.verdict !== 'implausible') {
+                if (cs.endsWith('-px')) {
+                    if (density > 0) {
+                        this._lastNativeViewportJsUnits = {
+                            width: p.viewportWidth / density,
+                            height: p.viewportHeight / density,
+                            space: 'native-content-view-dp',
+                        };
+                    }
+                } else if (cs.endsWith('-pt')) {
+                    // iOS already in pt — same unit as RN pageX/pageY
+                    this._lastNativeViewportJsUnits = {
+                        width: p.viewportWidth,
+                        height: p.viewportHeight,
+                        space: 'native-window-pt',
+                    };
+                }
+            } else if (check.verdict === 'implausible') {
+                /**
+                 * The native base is unusable, so fall back to the window and RE-NORMALISE.
+                 *
+                 * The coordinates already on the payload were divided by the bad base, so leaving
+                 * them would keep every tap in the wrong place — the point of rejecting the base is
+                 * to stop using it, including for the numbers already computed from it. The
+                 * original is kept under `rejectedViewportW/H` so the device stays diagnosable
+                 * from stored data instead of needing the handset.
+                 */
+                p.rejectedViewportWidth = p.viewportWidth;
+                p.rejectedViewportHeight = p.viewportHeight;
+                this._lastNativeViewportJsUnits = null;
+
+                /**
+                 * The window, taken DIRECTLY — not via `_resolveNormalizationBaseDp`.
+                 *
+                 * That helper would walk its priority list and land straight back on the rejected
+                 * number: its third branch reads `p.viewportWidth` off this very payload, and its
+                 * second reads `session.metadata.screenWidth`, which on a device that misreports
+                 * its content view has no reason to be any more trustworthy. Rejecting a source and
+                 * then re-selecting it through a helper is how a fix becomes a no-op.
+                 *
+                 * `Dimensions.get('window')` is the measurement the invariant just CONFIRMED is
+                 * sound — on the failing device its 434.7dp is exactly right for a 1440px screen —
+                 * so it is the one source that has earned being the fallback here.
+                 */
+                let winW = 0;
+                let winH = 0;
+                try {
+                    const { Dimensions } = require('react-native');
+                    const d = Dimensions.get('window');
+                    winW = d.width;
+                    winH = d.height;
+                } catch { /* no-throw */ }
+
+                const rx = typeof p.x === 'number' ? p.x : undefined;
+                const ry = typeof p.y === 'number' ? p.y : undefined;
+                if (winW > 0 && winH > 0) {
+                    // `x`/`y` arrived in the REJECTED space (px), so they have to be converted into
+                    // the window's unit before dividing, or the normalisation is wrong a second time.
+                    const rejW = typeof p.rejectedViewportWidth === 'number' ? p.rejectedViewportWidth : 0;
+                    const rejH = typeof p.rejectedViewportHeight === 'number' ? p.rejectedViewportHeight : 0;
+                    if (rx !== undefined && ry !== undefined && rejW > 0 && rejH > 0) {
+                        // Scale-free: the tap's POSITION within the rejected frame is still the best
+                        // estimate of where the finger was, even though the frame's absolute size was
+                        // nonsense. Re-express it against the window instead of re-dividing raw px.
+                        const nx = Math.max(0, Math.min(1, rx / rejW));
+                        const ny = Math.max(0, Math.min(1, ry / rejH));
+                        p.normalizedX = nx;
+                        p.normalizedY = ny;
+                        p.x = nx * winW;
+                        p.y = ny * winH;
+                    }
+                    p.viewportWidth = winW;
+                    p.viewportHeight = winH;
+                    p.coordinateSpace = 'window-fallback-dp';
+                    p.confidence = 'derived';
+                }
+            }
+        } else {
+            // Resolve the normalization base (in dp). Priority:
+            //   1. session metadata screen size
+            //   2. native content-view size (px → dp via PixelRatio) — matches screenshot
+            //   3. payload viewport
+            //   4. Dimensions.get('window') — last resort (excludes insets, ~10% off)
+            const base = this._resolveNormalizationBaseDp(p);
+
+            const x = typeof p.x === 'number' ? p.x : undefined;
+            const y = typeof p.y === 'number' ? p.y : undefined;
+            if (x !== undefined && y !== undefined && base) {
+                p.normalizedX = Math.max(0, Math.min(1, x / base.width));
+                p.normalizedY = Math.max(0, Math.min(1, y / base.height));
+                p.viewportWidth = base.width;
+                p.viewportHeight = base.height;
+                p.coordinateSpace = base.space;
+            }
+
+            const endX = typeof p.endX === 'number' ? p.endX : undefined;
+            const endY = typeof p.endY === 'number' ? p.endY : undefined;
+            if (endX !== undefined && endY !== undefined && base) {
+                p.normalizedEndX = Math.max(0, Math.min(1, endX / base.width));
+                p.normalizedEndY = Math.max(0, Math.min(1, endY / base.height));
+            }
+        }
+
+        return alreadyNormalized;
+    }
+
+    /**
+     * Feature #4 (heatmaps) — additive analytics emission.
+     *
+     * Routes a tap/gesture to the always-on ANALYTICS lane (BackendSessionAdapter
+     * .trackEvent) so coords are captured even when no replay recording is active.
+     *
+     * Strictly additive and isolated:
+     *   - Only runs when `_captureInteractionHeatmap` is ON (opt-in flag) AND a
+     *     backend analytics transport is attached AND no recording is active
+     *     (when active, the recording lane already emits the SAME USER_ACTION —
+     *     emitting here too would duplicate it).
+     *   - Reuses the EXACT recording payload shape (USER_ACTION + the same keys:
+     *     normalizedX, normalizedY, gestureType, screen, …) so the backend
+     *     aggregate reads them identically (no protocol/schema change).
+     *   - Normalizes via the same _normalizeInteractionPayload used by recording.
+     *   - Respects redaction: payload is passed through redactBody so any caller-
+     *     injected sensitive keys (e.g. a label) are stripped before transport.
+     *   - Never throws.
+     */
+    private _emitInteractionToAnalytics(
+        gestureType: string,
+        payload: Record<string, unknown>,
+        occurredAt: number,
+        screenName?: string,
+    ): boolean {
+        if (!this._captureInteractionHeatmap) return false;
+        if (this.active) return false; // recording lane already carries this tap
+        const adapter = this._backendTransport;
+        if (!adapter) return false;
+
+        try {
+            // Normalize coords in place (same logic as the recording lane).
+            this._normalizeInteractionPayload(payload);
+
+            // Respect redaction before handing to transport. redactBody returns a
+            // new object and strips known-sensitive keys; coords/gesture survive.
+            const safePayload = redactBody(payload) as Record<string, unknown>;
+
+            /**
+             * NO `frameId` HERE, and it is not an oversight.
+             *
+             * This method is guarded by `if (this.active) return;` — it runs ONLY when no replay
+             * recording is active, which is precisely when no screenshots are being captured.
+             * There is no frame on screen to point at, so an analytics-lane tap can never be
+             * attributed to a visual state.
+             *
+             * That makes it a permanent property of this lane rather than a gap to close later,
+             * and the dashboard has to account for it: these taps live in the heatmap grid
+             * alongside recorded ones, so a state filter necessarily covers a subset of the
+             * traffic. `heat:screen-coverage` reports that subset's size per app for exactly this
+             * reason.
+             */
+            const event: JourneyEvent = {
+                eventId: generateEventId(),
+                // sessionId is (re)stamped by the analytics lane at flush time.
+                sessionId: adapter.analyticsSessionId ?? '',
+                ts: occurredAt,
+                type: 'USER_ACTION',
+                subtype: `gesture:${gestureType}`,
+                screen: screenName ?? this._lastKnownScreen ?? undefined,
+                payload: safePayload,
+                source: 'user',
+            };
+            adapter.trackEvent(event);
+            return true;
+        } catch (err) {
+            logger.error('[SessionManager] heatmap analytics emit failed:', err);
+            return false;
+        }
+    }
+
+    /**
+     * Emit a canonical event into the session pipeline.
+     * This is the primary entry point for all event sources.
+     */
+    emitEvent(
+        type: JourneyEventType,
+        opts?: {
+            subtype?: string;
+            severity?: JourneyEventSeverity;
+            screen?: string;
+            payload?: Record<string, unknown>;
+            correlationId?: string;
+            traceId?: string;
+            source?: JourneyEventSource;
+            journeyId?: string;
+            /** Original observation time; interaction capture may resolve asynchronously. */
+            timestamp?: number;
+        },
+    ): void {
+        if (!this.active) return;
+
+        try {
+            // Pre-process USER_ACTION events to inject normalized coordinates for heatmap readiness
+            if (type === 'USER_ACTION' && opts?.payload) {
+                const p = opts.payload;
+
+                const alreadyNormalized = this._normalizeInteractionPayload(p);
+
+                __DEV__ && logger.debug(
+                    `[TapAccuracy] sink platform=${p.platform ?? '?'} space=${p.coordinateSpace ?? '?'} ` +
+                    `source=${alreadyNormalized ? (p.confidence === 'high' ? 'native-high' : 'js-precomputed') : 'js-estimated'} ` +
+                    `norm=(${p.normalizedX},${p.normalizedY}) base=(${p.viewportWidth}x${p.viewportHeight})`,
+                );
+
+                // ─── Diagnostic: merge calibration expected target (if a calibration
+                // screen stamped it within the TTL) and emit ONE unified [TapDiag]
+                // JSON object per gesture. Observability only — no math runs here.
+                const cal = consumeCalibrationTarget();
+                if (cal) {
+                    p.expectedTargetId = cal.targetId;
+                    p.expectedNX = cal.expectedNX;
+                    p.expectedNY = cal.expectedNY;
+                }
+
+                try {
+                    const meta = this.session?.metadata as any | undefined;
+                    const diag = {
+                        tag: 'TapDiag',
+                        side: 'sdk',
+                        platform: p.platform ?? null,
+                        coordinateSource: alreadyNormalized
+                            ? (p.confidence === 'high' ? 'native-high' : 'js-precomputed')
+                            : 'js-estimated',
+                        coordinateSpace: p.coordinateSpace ?? null,
+                        targetId: p.expectedTargetId ?? p.target ?? null,
+                        expectedNX: p.expectedNX ?? null,
+                        expectedNY: p.expectedNY ?? null,
+                        rawX: p.x ?? null,
+                        rawY: p.y ?? null,
+                        pageX: p.pageX ?? null,
+                        pageY: p.pageY ?? null,
+                        locationX: p.locationX ?? null,
+                        locationY: p.locationY ?? null,
+                        normalizedX: p.normalizedX ?? null,
+                        normalizedY: p.normalizedY ?? null,
+                        viewportWidth: p.viewportWidth ?? null,
+                        viewportHeight: p.viewportHeight ?? null,
+                        rootViewWidth: p.rootViewWidth ?? null,
+                        rootViewHeight: p.rootViewHeight ?? null,
+                        rootViewLeft: p.rootViewLeft ?? null,
+                        rootViewTop: p.rootViewTop ?? null,
+                        screenWidth: p.screenWidth ?? meta?.screenWidth ?? null,
+                        screenHeight: p.screenHeight ?? meta?.screenHeight ?? null,
+                        windowWidth: p.windowWidth ?? null,
+                        windowHeight: p.windowHeight ?? null,
+                        statusBarHeight: p.statusBarHeight ?? null,
+                        safeAreaTop: p.safeAreaTop ?? null,
+                        timestamp: Date.now(),
+                        confidence: p.confidence ?? null,
+                        source: p.source ?? null,
+                    };
+                    // Dev-only diagnostic echo. Must NOT emit in release: the console
+                    // capture integration (captureConsoleLogs) would otherwise forward
+                    // one [TapDiag] line per tap into the customer-facing Logs lane and
+                    // bury their own logs. Sibling [TapAccuracy] log above is __DEV__-gated
+                    // for the same reason; the heatmap/replay data flows through the
+                    // interaction pipeline, not this echo, so gating it loses nothing.
+                    // eslint-disable-next-line no-console
+                    if (__DEV__) console.log('[TapDiag]', JSON.stringify(diag));
+                } catch { /* no-throw */ }
+            }
+
+            /**
+             * Which frame was on screen when this happened.
+             *
+             * Resolved BEFORE `pipeline.emit`, and deliberately before the capture triggers
+             * below: those capture the frame that shows the RESULT of the interaction, and a tap
+             * belongs to the state it was made IN, not the one it produced. Reading after them
+             * would attribute every tap to its own consequence.
+             *
+             * USER_ACTION only. A SCREEN_VIEW's frame is the screen being left, which is
+             * misleading rather than useful, and no consumer asks for it.
+             *
+             * `currentKeyframe` returns null unless the frame is from this same screen and still
+             * fresh — see its contract. Null is the common, correct answer and stays absent on
+             * the event rather than becoming a default.
+             */
+            /**
+             * The keyframe is LINKED only when it can show this tap: a tap made after the list was
+             * scrolled is not a tap on the picture taken before it (frameLink.ts). The verdict and the
+             * frame's age ride on the payload, so a missing or unverified link is visible, not silent.
+             */
+            let framedOpts: (typeof opts & { frameId?: string }) | undefined = opts;
+            if (type === 'USER_ACTION') {
+                const kf = this.captureManager?.currentKeyframe(opts?.screen ?? this._lastKnownScreen ?? undefined);
+                const link = frameLinkVerdict(kf, opts?.payload?.['scroll_context']);
+                const at = typeof opts?.timestamp === 'number' ? opts.timestamp : Date.now();
+                framedOpts = {
+                    ...opts,
+                    frameId: kf && (link === 'linked' || link === 'unverified') ? kf.frameId : undefined,
+                    payload: {
+                        ...(opts?.payload ?? {}),
+                        frame_link: link,
+                        ...(kf ? { frame_age_ms: Math.max(0, at - kf.capturedAt) } : {}),
+                    },
+                };
+            }
+
+            const event = this.pipeline.emit(type, framedOpts);
+
+            // Trigger capture on screen view or interaction
+            if (event) {
+                if (type === 'SCREEN_VIEW' && opts?.screen) {
+                    this.captureManager.onScreenChange(opts.screen);
+                } else if (type === 'USER_ACTION') {
+                    // Extract interaction coordinates from the gesture payload
+                    // so the captured frame carries tap location metadata.
+                    const p = opts?.payload;
+                    const x = typeof p?.x === 'number' ? p.x : undefined;
+                    const y = typeof p?.y === 'number' ? p.y : undefined;
+                    const gestureType = typeof p?.gestureType === 'string' ? p.gestureType : undefined;
+
+                    // Scroll gestures use onScrollSettle (which debounces into a single
+                    // capture). Using onInteraction for scroll would produce a DUPLICATE
+                    // screenshot alongside the ScrollTracker's onScrollSettle call.
+                    if (gestureType === 'scroll') {
+                        this.captureManager.onScrollSettle(opts?.screen ?? this._lastKnownScreen ?? undefined);
+                    } else {
+                        let interactionPoint: import('./sessionTypes').ReplayFrame['interactionPoint'];
+                        if (x !== undefined && y !== undefined && gestureType) {
+                            interactionPoint = {
+                                x,
+                                y,
+                                normalizedX: typeof p?.normalizedX === 'number' ? p.normalizedX : undefined,
+                                normalizedY: typeof p?.normalizedY === 'number' ? p.normalizedY : undefined,
+                                screenWidth: this.session?.metadata?.screenWidth ?? 0,
+                                screenHeight: this.session?.metadata?.screenHeight ?? 0,
+                                viewportWidth: typeof p?.viewportWidth === 'number' ? p.viewportWidth : undefined,
+                                viewportHeight: typeof p?.viewportHeight === 'number' ? p.viewportHeight : undefined,
+                                gestureType,
+                                endX: typeof p?.endX === 'number' ? p.endX : undefined,
+                                endY: typeof p?.endY === 'number' ? p.endY : undefined,
+                                normalizedEndX: typeof p?.normalizedEndX === 'number' ? p.normalizedEndX : undefined,
+                                normalizedEndY: typeof p?.normalizedEndY === 'number' ? p.normalizedEndY : undefined,
+                                durationMs: typeof p?.durationMs === 'number' ? p.durationMs : undefined,
+                                direction: typeof p?.direction === 'string' ? p.direction : undefined,
+                            };
+                        }
+
+                        this.captureManager.onInteraction(interactionPoint);
+                    }
+                }
+            }
+        } catch (err) {
+            logger.error('[SessionManager] emitEvent failed:', err);
+        }
+    }
+
+    /**
+     * Anchor a crash in the session context.
+     * Protects nearby events and frames from eviction.
+     */
+    anchorCrash(crashEventId: string): CrashAnchor | null {
+        if (!this.active) return null;
+
+        try {
+            // Anchor events
+            const anchor = this.pipeline.anchorCrash(crashEventId);
+
+            // Anchor frames (protect frames near the crash timestamp)
+            const crashEvent = this.pipeline.getEvents().find(
+                e => e.eventId === crashEventId,
+            );
+            if (crashEvent) {
+                const protectedFrameIds = this.captureManager.protectFramesNearCrash(crashEvent.ts);
+                anchor.nearbyFrameIds = protectedFrameIds;
+            }
+
+            // Capture an error-context frame
+            this.captureManager.captureManual('error-context').catch(() => { });
+
+            this.crashAnchors.push(anchor);
+
+            __DEV__ && logger.debug(
+                `[SessionManager] Crash anchored: ${crashEventId}, ` +
+                `protected ${anchor.nearbyEventIds.length} events, ` +
+                `${anchor.nearbyFrameIds.length} frames`,
+            );
+
+            return anchor;
+        } catch (err) {
+            logger.error('[SessionManager] anchorCrash failed:', err);
+            return null;
+        }
+    }
+
+    // ─── Navigation / Screen Integration ────────────────────────────────
+
+    /**
+     * Notify of a screen change. Called by ScaleBunDebugRoot via NavDetector.
+     */
+    /** The screen currently on top, or null before the first navigation is observed. */
+    getLastKnownScreen(): string | null {
+        return this._lastKnownScreen;
+    }
+
+    onScreenChange(screenName: string): void {
+        // Always track the current screen — even when inactive.
+        // This allows startSession to emit the initial SCREEN_VIEW for
+        // the screen that was already mounted before Record was pressed.
+        const previous = this._lastKnownScreen;
+        const enteredAt = this._screenEnteredAt;
+        this._lastKnownScreen = screenName;
+        this._screenEnteredAt = Date.now();
+
+        if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
+
+        // SCREEN_EXIT for the screen being left, carrying its dwell time.
+        //
+        // The exit was previously detectable ONLY inside the Engage trigger engine and never became an
+        // event, so time-on-screen had to be inferred from the gap to the NEXT SCREEN_VIEW — which is
+        // wrong whenever the app backgrounds in between, and impossible for the last screen of a
+        // session. Emitting it here makes dwell a measured value rather than a derived guess.
+        if (previous && previous !== screenName && enteredAt != null) {
+            this.emitEvent('SCREEN_EXIT', {
+                screen: previous,
+                subtype: previous,
+                source: 'sdk',
+                payload: { dwellMs: Math.max(0, Date.now() - enteredAt), to: screenName },
+            });
+        }
+
+        this.emitEvent('SCREEN_VIEW', {
+            screen: screenName,
+            subtype: screenName,
+            source: 'sdk',
+            ...(previous && previous !== screenName ? { payload: { from: previous } } : {}),
+        });
+    }
+
+    /**
+     * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
+     * Also triggers frame capture for desktop-initiated recordings.
+     */
+    onUserAction(
+        subtype: string,
+        payload?: Record<string, unknown>,
+        context?: { screen?: string; timestamp?: number },
+    ): void {
+        if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
+        this.emitEvent('USER_ACTION', {
+            subtype,
+            screen: context?.screen ?? this._lastKnownScreen ?? undefined,
+            payload,
+            source: 'user',
+            timestamp: context?.timestamp,
+        });
+        // NOTE: Do NOT call captureManager.onInteraction() here.
+        // emitEvent() already triggers onInteraction() for USER_ACTION events (line ~405).
+        // Calling it again here caused DUPLICATE frame captures per gesture.
+    }
+
+    /**
+     * Detailed gesture detection — called by ScaleBunDebugRoot touch handlers.
+     * Emits a USER_ACTION event with gesture-specific subtype and payload.
+     */
+    onGestureDetected(gestureType: string, details?: {
+        x?: number;
+        y?: number;
+        endX?: number;
+        endY?: number;
+        duration?: number;
+        durationMs?: number;
+        direction?: string;
+        target?: string;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        pageX?: number;
+        pageY?: number;
+        locationX?: number;
+        locationY?: number;
+        normalizedX?: number;
+        normalizedY?: number;
+        normalizedEndX?: number;
+        normalizedEndY?: number;
+        confidence?: string;
+        coordinateSpace?: string;
+        source?: string;
+        // Pre-computed normalization flag — set by JS fallback when it normalized
+        // against the measured root-view rect (the exact view the screenshot captures).
+        // Without this flag, SessionManager.emitEvent would overwrite the pre-computed
+        // values via _resolveNormalizationBaseDp using a potentially-different base.
+        normalizedPrecomputed?: boolean;
+        // Diagnostic fields used by the dashboard to verify capture-space alignment.
+        statusBarHeight?: number;
+        safeAreaTop?: number;
+        rootViewTop?: number;
+        rootViewLeft?: number;
+        rootViewWidth?: number;
+        rootViewHeight?: number;
+        windowWidth?: number;
+        windowHeight?: number;
+        screenshotCropTop?: number;
+        screenWidth?: number;
+        screenHeight?: number;
+        platform?: string;
+        interactionId?: string;
+        interactionProtocol?: number;
+        occurredAt?: number;
+        ui?: string;
+        stateStatus?: InteractionStateStatus;
+        targetId?: string;
+        screenName?: string;
+        emitAutomaticAnalytics?: boolean;
+        /**
+         * RN-6 — the native↔JS join's own verdict, and it MUST be declared here.
+         *
+         * This signature ENUMERATES its fields rather than spreading, and the only caller
+         * (ScaleBunDebugRoot's native listener) invokes it through `(sm as any)`. So a field
+         * added at the call site and not added here is dropped in silence, with no type
+         * error anywhere — which is precisely how these three nearly shipped as a no-op.
+         *
+         * 'exact' = one JS start was clearly closest. 'ambiguous' = two were within
+         * CORRELATION_MARGIN_MS of each other, so target/ui/screenName were deliberately
+         * withheld rather than guessed. 'none' = no start within tolerance, meaning the JS
+         * handler never fired. The last two are kept distinct because they have different
+         * fixes and collapsing them would hide which is happening in production.
+         */
+        correlation?: 'exact' | 'ambiguous' | 'none';
+        correlationDeltaMs?: number | null;
+        correlationRunnerUpDeltaMs?: number | null;
+        /**
+         * RN-1/RN-2 — which kind of identity `targetId` is. Declared here for the same reason as
+         * the correlation fields above: this signature enumerates, and its only caller goes
+         * through `(sm as any)`, so an undeclared field is dropped in silence.
+         */
+        targetSource?: 'testID' | 'path' | 'component' | 'none';
+        /** RN-8: where the screen name came from. Declared here because this signature enumerates. */
+        screenSource?: 'manual' | 'navigation' | 'none';
+        /**
+         * RN-13: the target control's rectangle in capture-base fractions. Declared here because
+         * this signature ENUMERATES — the sixth field to need it, after three correlation fields,
+         * targetSource and screenSource.
+         */
+        targetRect?: { x: number; y: number; width: number; height: number };
+        /**
+         * RN-3: content offset of the nearest ancestor scroller. Declared here because this
+         * signature ENUMERATES — the seventh field to need it.
+         */
+        scrollX?: number;
+        scrollY?: number;
+        scrollSource?: 'wrapper' | 'native' | 'none';
+        /**
+         * RN-4: list row identity. Declared here because this signature ENUMERATES — the eighth
+         * and ninth fields to need it.
+         */
+        itemKey?: string;
+        itemIndex?: number;
+        /**
+         * RN-15: tap position within the target control. Declared here because this signature
+         * ENUMERATES — the tenth and eleventh fields to need it.
+         */
+        localU?: number;
+        localV?: number;
+        /**
+         * Native scroll chain at touch-down (innermost first, capture pixels), the device pixel
+         * density, and the tap-contract version. Declared here because this signature ENUMERATES.
+         */
+        scrollContext?: import('../journey/nativeScroll').NativeScrollEntry[];
+        pixelDensity?: number;
+        heatmapSchemaVersion?: number;
+    }): void {
+        // Exact-duplicate suppression — see _lastGestureSig. Signature is the gesture type plus
+        // raw coordinates verbatim; String() keeps undefined coords distinct from 0 (a payload
+        // with no coords never collides with a real origin tap).
+        const suppliedInteractionId = details?.interactionId;
+        const dedupSig = suppliedInteractionId
+            ? `id:${suppliedInteractionId}`
+            : `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
+        const nowTs = Date.now();
+        if (
+            dedupSig === this._lastGestureSig &&
+            nowTs - this._lastGestureTs <= SessionManager.GESTURE_DEDUP_WINDOW_MS
+        ) {
+            this._lastGestureTs = nowTs; // a burst of 3 stays suppressed even if gaps chain past the window
+            return;
+        }
+        this._lastGestureSig = dedupSig;
+        this._lastGestureTs = nowTs;
+
+        // Build the canonical gesture payload ONCE so the recording lane and the
+        // (additive) analytics lane carry byte-identical keys (normalizedX/Y,
+        // gestureType, etc.). Same object shape that was previously inlined.
+        const interactionId = suppliedInteractionId ?? generateInteractionId();
+        const occurredAt = details?.occurredAt ?? Date.now();
+        const stateStatus = details?.stateStatus ?? (details?.ui ? 'captured_nonempty' : 'not_captured');
+        const payload: Record<string, unknown> = {
+            interaction_id: interactionId,
+            interaction_protocol: details?.interactionProtocol ?? INTERACTION_PROTOCOL_VERSION,
+            state_status: stateStatus,
+            ui: details?.ui,
+            target_id: details?.targetId,
+            /**
+             * RN-6 — shipped with the row so the join is auditable instead of assumed.
+             *
+             * Without it, an interaction with no `target_id` is ambiguous in the worst way:
+             * it could mean the control genuinely had no identity, or that the correlation
+             * refused and the identity exists but could not be attributed. Those are
+             * different defects with different owners, and the accounting lane cannot give
+             * an honest unplaceable REASON without knowing which.
+             *
+             * Undefined on the JS-fallback path (no native event, so nothing was joined),
+             * which is itself the correct answer there rather than a fabricated 'exact'.
+             */
+            correlation: details?.correlation,
+            correlation_delta_ms: details?.correlationDeltaMs,
+            correlation_runner_up_delta_ms: details?.correlationRunnerUpDeltaMs,
+            /**
+             * RN-1/RN-2 — stored alongside `target_id` so a reader can tell an authored
+             * identifier from a structural inference. 'path' means the app authored no testID
+             * and the identity was derived from component names, which is useful but will
+             * change under refactoring; a dashboard that presents the two identically invites
+             * someone to trust a key that is about to move.
+             */
+            target_source: details?.targetSource,
+            /**
+             * RN-8 — stored so "13.8% of interactions have a screen" becomes answerable.
+             * 'none' means the app instrumented nothing the SDK could see; 'manual' means a
+             * <ScaleBunScreen> beacon; 'navigation' means the React Navigation hook. Three
+             * different owners behind one number that today has none.
+             */
+            screen_source: details?.screenSource,
+            /**
+             * RN-13 — what makes "the heat is on this control" checkable instead of assumed.
+             * Absent when the control could not be measured synchronously, which is a fact worth
+             * storing: an unmeasurable control and a mis-placed tap are different findings.
+             */
+            target_rect: details?.targetRect,
+            /**
+             * RN-3 — the backend already reads scrollX/scrollY off the payload into the fact
+             * table's own columns (it has done since the web SDK, which sends `sx`/`sy`), so
+             * these need no migration. Mobile simply never sent them.
+             *
+             * `scroll_source` says whether an offset was available at all: 'none' means the app
+             * uses a plain <ScrollView> rather than the SDK's wrapper, which is a coverage gap in
+             * the integration and not a tap at the top of a list.
+             */
+            scrollX: details?.scrollX,
+            scrollY: details?.scrollY,
+            scroll_source: details?.scrollSource,
+            /**
+             * Every scroll container under the finger at touch-down, innermost first, in the
+             * capture view's pixel space (native probe). The single scrollX/Y above is the
+             * innermost; the chain is what lets a nested list be placed without guessing.
+             */
+            scroll_context: details?.scrollContext,
+            pixel_density: details?.pixelDensity,
+            heatmap_schema_version: details?.heatmapSchemaVersion,
+            /**
+             * RN-4 — what stops a recycled native view merging two different rows into one
+             * hotspot. The key is the app's own keyExtractor output, so it is stable across
+             * scrolling and across sessions; the index is carried so a recycled slot (same index,
+             * different key) can be proven rather than inferred.
+             */
+            item_key: details?.itemKey,
+            item_index: details?.itemIndex,
+            /**
+             * RN-15 — where in the control, not just which control. Turns "they tapped Add to
+             * Cart" into "they tapped its left edge", which is what tells you whether a hit area
+             * is right. Outside 0..1 is a hitSlop tap and is kept as such.
+             */
+            local_u: details?.localU,
+            local_v: details?.localV,
+            gestureType,
+            x: details?.x,
+            y: details?.y,
+            endX: details?.endX,
+            endY: details?.endY,
+            duration: details?.duration ?? details?.durationMs,
+            durationMs: details?.durationMs ?? details?.duration,
+            direction: details?.direction,
+            target: details?.target,
+            viewportWidth: details?.viewportWidth,
+            viewportHeight: details?.viewportHeight,
+            pageX: details?.pageX,
+            pageY: details?.pageY,
+            locationX: details?.locationX,
+            locationY: details?.locationY,
+            // Native / JS-precomputed coords — passed through without overwriting
+            normalizedX: details?.normalizedX,
+            normalizedY: details?.normalizedY,
+            normalizedEndX: details?.normalizedEndX,
+            normalizedEndY: details?.normalizedEndY,
+            confidence: details?.confidence,
+            coordinateSpace: details?.coordinateSpace,
+            source: details?.source,
+            normalizedPrecomputed: details?.normalizedPrecomputed,
+            statusBarHeight: details?.statusBarHeight,
+            safeAreaTop: details?.safeAreaTop,
+            rootViewTop: details?.rootViewTop,
+            rootViewLeft: details?.rootViewLeft,
+            rootViewWidth: details?.rootViewWidth,
+            rootViewHeight: details?.rootViewHeight,
+            windowWidth: details?.windowWidth,
+            windowHeight: details?.windowHeight,
+            screenshotCropTop: details?.screenshotCropTop,
+            screenWidth: details?.screenWidth,
+            screenHeight: details?.screenHeight,
+            platform: details?.platform,
+        };
+
+        // ── Feature #4 (heatmaps): additive analytics emission ──
+        // When NOT recording, route the tap to the always-on analytics lane so
+        // heatmaps still get coords (opt-in via captureInteractionHeatmap). No-op
+        // when the flag is OFF, no backend transport is attached, or recording is
+        // active (the recording path below already carries this tap). Uses a fresh
+        // payload clone so analytics normalization never mutates the recording one.
+        const analyticsReplayCarrier = this._emitInteractionToAnalytics(
+            gestureType,
+            { ...payload },
+            occurredAt,
+            details?.screenName,
+        );
+        const replayCarrier = !!this._backendTransport && (this.active || analyticsReplayCarrier);
+        if (details?.emitAutomaticAnalytics) {
+            try {
+                const safePayload = redactBody(payload) as Record<string, unknown>;
+                emitAutomaticEvent(
+                    'element_interacted',
+                    automaticInteractionProperties(
+                        safePayload,
+                        details?.screenName ?? this._lastKnownScreen ?? undefined,
+                        replayCarrier,
+                    ),
+                    occurredAt,
+                );
+            } catch { /* automatic projection must never affect interaction capture */ }
+        }
+
+        if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
+        // The subtype becomes `ReplayEvent.label`, which is what the Events explorer GROUPS BY. Naming
+        // the tapped control here is what splits taps per control instead of collapsing every tap in the
+        // app into one `gesture:tap` row. Falls back to the bare gesture when nothing identified the
+        // target, so behaviour is unchanged for taps that cannot be resolved.
+        //
+        // ⚠️ `gestureType` also travels in the payload, and the backend's `resolveGesture` reads THAT
+        // first — so enriching the label cannot change heatmap gesture classification.
+        const target = typeof details?.target === 'string' ? details.target.trim() : '';
+        this.onUserAction(
+            target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`,
+            payload,
+            { screen: details?.screenName, timestamp: occurredAt },
+        );
+    }
+
+    /**
+     * Manual frame capture — triggered by Desktop "Capture Step" button.
+     */
+    async captureManualFrame(): Promise<{ frameId?: string } | null> {
+        if (!this.active || !this.captureManager) return null; // No capture when recording is OFF
+        const frame = await this.captureManager.captureManual('manual');
+        return frame ? { frameId: frame.frameId } : null;
+    }
+
+    /**
+     * Notify of app lifecycle change.
+     */
+    onLifecycleChange(state: 'foreground' | 'background'): void {
+        this.emitEvent(
+            state === 'foreground' ? 'APP_FOREGROUND' : 'APP_BACKGROUND',
+            { source: 'system' },
+        );
+    }
+
+    // ─── Scroll Integration ─────────────────────────────────────────────
+
+    /**
+     * Notify of a scroll event from a scrollable surface (ScaleBunScrollView).
+     * Delegates to ScrollTracker for accumulation and settle detection.
+     */
+    onScrollEvent(contentOffsetX: number, contentOffsetY: number): void {
+        if (!this.active) return;
+        this.scrollTracker?.onScrollEvent(contentOffsetX, contentOffsetY);
+    }
+
+    // ─── Loading State Integration ──────────────────────────────────────
+
+    /**
+     * Notify that a screen has started loading.
+     * Explicit instrumentation — NOT auto-called on screen entry.
+     * Call from app code: ScaleBun.markLoadingStarted('ScreenName')
+     */
+    onLoadingStarted(screenName: string): void {
+        if (!this.active) return;
+
+        this.loadingStartTimes.set(screenName, Date.now());
+
+        this.emitEvent('LOADING_STARTED', {
+            screen: screenName,
+            subtype: screenName,
+            payload: { screen: screenName },
+            source: 'sdk',
+        });
+    }
+
+    /**
+     * Notify that a screen has finished loading.
+     * Explicit instrumentation — call from app code.
+     * Triggers a 'screen_loaded' frame capture for the settled state.
+     */
+    onLoadingCompleted(screenName: string): void {
+        if (!this.active) return;
+
+        const startTime = this.loadingStartTimes.get(screenName);
+        const durationMs = startTime ? Date.now() - startTime : undefined;
+        this.loadingStartTimes.delete(screenName);
+
+        this.emitEvent('LOADING_COMPLETED', {
+            screen: screenName,
+            subtype: screenName,
+            payload: {
+                screen: screenName,
+                durationMs,
+            },
+            source: 'sdk',
+        });
+
+        // Capture the settled loaded screen
+        this.captureManager.onLoadingEnd(screenName);
+    }
+
+    /**
+     * App network activity, forwarded to replay capture so a frame can wait for the screen's
+     * data instead of photographing the wait. Called by NetworkFeature, which has already
+     * excluded this SDK's own uploads and third-party beacons.
+     *
+     * Deliberately NOT gated on `this.active`: the counter must stay balanced across a session
+     * boundary. Dropping the `end` of a request whose `start` was counted would leave replay
+     * believing the app is permanently loading, and a session can start or stop mid-request.
+     * The capture manager ignores the signal when it is not capturing anyway.
+     */
+    onNetworkActivity(phase: 'start' | 'end'): void {
+        try {
+            this.captureManager.onNetworkActivity(phase);
+        } catch {
+            // Advisory signal — it must never take down a network request.
+        }
+    }
+
+    // ─── Sync Policy ────────────────────────────────────────────────────
+
+    /**
+     * Override the sync policy. SDK-owned — native only provides metadata.
+     */
+    setSyncPolicy(policy: SyncDecisionCallback): void {
+        this.syncEngine.setPolicy(policy);
+    }
+
+    /**
+     * Provide native-gathered sync metadata for the current session.
+     * Does NOT make the sync decision — that stays in SDK's SyncDecisionEngine.
+     */
+    setNativeSyncMetadata(metadata: NativeSyncMetadata): void {
+        // Stored for use at session end evaluation
+        if (this.session) {
+            (this.session as any)._nativeSyncMetadata = metadata;
+        }
+    }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function generateSessionId(): string {
+    return `ses-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+}