@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/session/SessionManager.ts

@@ -1,1209 +1,1248 @@
-/**
- * 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 { 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';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-/**
- * Max analytics-lane heatmap interactions emitted per foreground (analytics
- * session) window. Bounds ingest volume now that capture defaults ON; enough to
- * resolve hotspot density, the long tail is dropped (drop-newest beyond cap).
- */
-const HEATMAP_MAX_INTERACTIONS_PER_WINDOW = 200;
-
-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;
-    /**
-     * Sampling cap for the analytics-lane heatmap emission. Now that capture is
-     * ON by default, an unbounded one-event-per-gesture stream could materially
-     * inflate ingest volume. We cap emitted interactions per analytics-session
-     * window (finalize-scoped per foreground): the first N gestures define the
-     * hotspot shape; the long tail is dropped. Resets when the window changes.
-     */
-    private _heatmapWindowSessionId: string | null = null;
-    private _heatmapWindowCount = 0;
-
-    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;
-
-    private _nativeCapture: NativeCaptureFn;
-    private _rawTransport: DebugTransport | null;
-    /** Memoized native file-outbox frame adapter (gated by the backend transport). */
-    private _outboxFrameCapture: OutboxFrameCapture | null = null;
-
-    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);
-        });
-    }
-
-    // ─── 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 = 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;
-        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);
-        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;
-            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) {
-                logger.debug('[SessionManager] Session already active, skipping start');
-                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);
-            });
-
-            // 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: {
-                    platform: (() => {
-                        try {
-                            const { Platform } = require('react-native');
-                            return Platform.OS === 'ios' ? 'ios' : 'android';
-                        } catch { return 'android'; }
-                    })(), // Real OS; enriched by native device info when available
-                    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
-            this.captureManager.start();
-
-            // Set timeout
-            if (this.config.maxDurationMs > 0) {
-                this.timeoutTimer = setTimeout(() => {
-                    logger.debug('[SessionManager] Session timeout reached');
-                    this.endSession('timeout');
-                }, this.config.maxDurationMs);
-            }
-
-            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)
-
-            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 : '';
-            if (typeof p.viewportWidth === 'number' && p.viewportWidth > 0
-                && typeof p.viewportHeight === 'number' && p.viewportHeight > 0) {
-                if (cs.endsWith('-px')) {
-                    try {
-                        const { PixelRatio } = require('react-native');
-                        const density = PixelRatio.get();
-                        if (density > 0) {
-                            this._lastNativeViewportJsUnits = {
-                                width: p.viewportWidth / density,
-                                height: p.viewportHeight / density,
-                                space: 'native-content-view-dp',
-                            };
-                        }
-                    } catch { /* no-throw */ }
-                } 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 {
-            // 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>): void {
-        if (!this._captureInteractionHeatmap) return;
-        if (this.active) return; // recording lane already carries this tap
-        const adapter = this._backendTransport;
-        if (!adapter) return;
-
-        // Per-foreground sampling cap. Reset the counter when the analytics
-        // session window rolls over, then drop anything past the cap.
-        const windowId = adapter.analyticsSessionId ?? '';
-        if (windowId !== this._heatmapWindowSessionId) {
-            this._heatmapWindowSessionId = windowId;
-            this._heatmapWindowCount = 0;
-        }
-        if (this._heatmapWindowCount >= HEATMAP_MAX_INTERACTIONS_PER_WINDOW) return;
-        this._heatmapWindowCount++;
-
-        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>;
-
-            const event: JourneyEvent = {
-                eventId: generateEventId(),
-                // sessionId is (re)stamped by the analytics lane at flush time.
-                sessionId: adapter.analyticsSessionId ?? '',
-                ts: Date.now(),
-                type: 'USER_ACTION',
-                subtype: `gesture:${gestureType}`,
-                screen: this._lastKnownScreen ?? undefined,
-                payload: safePayload,
-                source: 'user',
-            };
-            adapter.trackEvent(event);
-        } catch (err) {
-            logger.error('[SessionManager] heatmap analytics emit failed:', err);
-        }
-    }
-
-    /**
-     * 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;
-        },
-    ): 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);
-
-                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,
-                    };
-                    // eslint-disable-next-line no-console
-                    console.log('[TapDiag]', JSON.stringify(diag));
-                } catch { /* no-throw */ }
-            }
-
-            const event = this.pipeline.emit(type, opts);
-
-            // 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);
-
-            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>): void {
-        if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
-        this.emitEvent('USER_ACTION', {
-            subtype,
-            screen: this._lastKnownScreen ?? undefined,
-            payload,
-            source: 'user',
-        });
-        // 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;
-    }): void {
-        // 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 payload: Record<string, unknown> = {
-            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.
-        this._emitInteractionToAnalytics(gestureType, { ...payload });
-
-        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);
-    }
-
-    /**
-     * 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);
-    }
-
-    // ─── 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)}`;
-}
+/**
+ * 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 { 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';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Max analytics-lane heatmap interactions emitted per foreground (analytics
+ * session) window. Bounds ingest volume now that capture defaults ON; enough to
+ * resolve hotspot density, the long tail is dropped (drop-newest beyond cap).
+ */
+const HEATMAP_MAX_INTERACTIONS_PER_WINDOW = 200;
+
+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;
+    /**
+     * Sampling cap for the analytics-lane heatmap emission. Now that capture is
+     * ON by default, an unbounded one-event-per-gesture stream could materially
+     * inflate ingest volume. We cap emitted interactions per analytics-session
+     * window (finalize-scoped per foreground): the first N gestures define the
+     * hotspot shape; the long tail is dropped. Resets when the window changes.
+     */
+    private _heatmapWindowSessionId: string | null = null;
+    private _heatmapWindowCount = 0;
+
+    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;
+
+    private _nativeCapture: NativeCaptureFn;
+    private _rawTransport: DebugTransport | null;
+    /** Memoized native file-outbox frame adapter (gated by the backend transport). */
+    private _outboxFrameCapture: OutboxFrameCapture | null = null;
+
+    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);
+        });
+    }
+
+    // ─── 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 = 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;
+        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);
+        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;
+            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) {
+                logger.debug('[SessionManager] Session already active, skipping start');
+                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);
+            });
+
+            // 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
+            this.captureManager.start();
+
+            // Set timeout
+            if (this.config.maxDurationMs > 0) {
+                this.timeoutTimer = setTimeout(() => {
+                    logger.debug('[SessionManager] Session timeout reached');
+                    this.endSession('timeout');
+                }, this.config.maxDurationMs);
+            }
+
+            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)
+
+            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 : '';
+            if (typeof p.viewportWidth === 'number' && p.viewportWidth > 0
+                && typeof p.viewportHeight === 'number' && p.viewportHeight > 0) {
+                if (cs.endsWith('-px')) {
+                    try {
+                        const { PixelRatio } = require('react-native');
+                        const density = PixelRatio.get();
+                        if (density > 0) {
+                            this._lastNativeViewportJsUnits = {
+                                width: p.viewportWidth / density,
+                                height: p.viewportHeight / density,
+                                space: 'native-content-view-dp',
+                            };
+                        }
+                    } catch { /* no-throw */ }
+                } 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 {
+            // 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>): void {
+        if (!this._captureInteractionHeatmap) return;
+        if (this.active) return; // recording lane already carries this tap
+        const adapter = this._backendTransport;
+        if (!adapter) return;
+
+        // Per-foreground sampling cap. Reset the counter when the analytics
+        // session window rolls over, then drop anything past the cap.
+        const windowId = adapter.analyticsSessionId ?? '';
+        if (windowId !== this._heatmapWindowSessionId) {
+            this._heatmapWindowSessionId = windowId;
+            this._heatmapWindowCount = 0;
+        }
+        if (this._heatmapWindowCount >= HEATMAP_MAX_INTERACTIONS_PER_WINDOW) return;
+        this._heatmapWindowCount++;
+
+        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: Date.now(),
+                type: 'USER_ACTION',
+                subtype: `gesture:${gestureType}`,
+                screen: this._lastKnownScreen ?? undefined,
+                payload: safePayload,
+                source: 'user',
+            };
+            adapter.trackEvent(event);
+        } catch (err) {
+            logger.error('[SessionManager] heatmap analytics emit failed:', err);
+        }
+    }
+
+    /**
+     * 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;
+        },
+    ): 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);
+
+                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,
+                    };
+                    // eslint-disable-next-line no-console
+                    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.
+             */
+            const framedOpts =
+                type === 'USER_ACTION'
+                    ? {
+                          ...opts,
+                          frameId: this.captureManager?.currentKeyframe(
+                              opts?.screen ?? this._lastKnownScreen ?? undefined,
+                          )?.frameId,
+                      }
+                    : opts;
+
+            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);
+
+            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>): void {
+        if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
+        this.emitEvent('USER_ACTION', {
+            subtype,
+            screen: this._lastKnownScreen ?? undefined,
+            payload,
+            source: 'user',
+        });
+        // 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;
+    }): void {
+        // 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 payload: Record<string, unknown> = {
+            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.
+        this._emitInteractionToAnalytics(gestureType, { ...payload });
+
+        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);
+    }
+
+    /**
+     * 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);
+    }
+
+    // ─── 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)}`;
+}