@scalebun-release/react-native 2.5.0

package/lib/module/features/session/SessionManager.js

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