@scalebun/react-native 1.0.2 → 1.0.4

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

@@ -1,17 +1,17 @@
-/**
- * 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
+/**
+ * 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';
@@ -26,13 +26,14 @@ 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).
+/**
+ * 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;
 // ─── Singleton ──────────────────────────────────────────────────────────────
@@ -45,17 +46,17 @@ 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).
+  /**
+   * 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;
-  /**
-   * 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.
+  /**
+   * 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.
    */
   _heatmapWindowSessionId = null;
   _heatmapWindowCount = 0;
@@ -65,24 +66,24 @@ export class SessionManager {
   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.
+  /**
+   * 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).
+  /**
+   * 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;
   /** Memoized native file-outbox frame adapter (gated by the backend transport). */
@@ -141,9 +142,9 @@ export class SessionManager {
     _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.
+  /**
+   * 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;
@@ -155,12 +156,12 @@ export class SessionManager {
     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).
+  /**
+   * 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) {
@@ -169,9 +170,9 @@ export class SessionManager {
     return this._outboxFrameCapture;
   }
 
-  /**
-   * Attach a desktop transport dynamically.
-   * Called when debug mode connects after SDK initialization.
+  /**
+   * Attach a desktop transport dynamically.
+   * Called when debug mode connects after SDK initialization.
    */
   setDesktopTransport(debugTransport) {
     this.desktopTransport = new DesktopSessionTransport(debugTransport);
@@ -190,26 +191,26 @@ export class SessionManager {
     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.
+  /**
+   * 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.
+  /**
+   * 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;
@@ -220,8 +221,8 @@ export class SessionManager {
     }
   }
 
-  /**
-   * Start a new session. Idempotent — no-op if already active.
+  /**
+   * Start a new session. Idempotent — no-op if already active.
    */
   startSession(metadata) {
     try {
@@ -317,17 +318,11 @@ export class SessionManager {
         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
+          // 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
@@ -424,8 +419,8 @@ export class SessionManager {
     }
   }
 
-  /**
-   * End the current session.
+  /**
+   * End the current session.
    */
   endSession(reason = 'ended') {
     // Fully idempotent — safe to call multiple times
@@ -502,15 +497,15 @@ export class SessionManager {
 
   // ─── 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.
+  /**
+   * 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).
@@ -556,17 +551,17 @@ export class SessionManager {
     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.
+  /**
+   * 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,
@@ -631,24 +626,24 @@ export class SessionManager {
     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.
+  /**
+   * 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) {
     if (!this._captureInteractionHeatmap) return;
@@ -672,6 +667,21 @@ export class SessionManager {
       // 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.
@@ -689,9 +699,9 @@ export class SessionManager {
     }
   }
 
-  /**
-   * Emit a canonical event into the session pipeline.
-   * This is the primary entry point for all event sources.
+  /**
+   * 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;
@@ -750,7 +760,27 @@ export class SessionManager {
           console.log('[TapDiag]', JSON.stringify(diag));
         } catch {/* no-throw */}
       }
-      const event = this.pipeline.emit(type, opts);
+
+      /**
+       * 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) {
@@ -799,9 +829,9 @@ export class SessionManager {
     }
   }
 
-  /**
-   * Anchor a crash in the session context.
-   * Protects nearby events and frames from eviction.
+  /**
+   * Anchor a crash in the session context.
+   * Protects nearby events and frames from eviction.
    */
   anchorCrash(crashEventId) {
     if (!this.active) return null;
@@ -829,8 +859,8 @@ export class SessionManager {
 
   // ─── Navigation / Screen Integration ────────────────────────────────
 
-  /**
-   * Notify of a screen change. Called by ScaleBunDebugRoot via NavDetector.
+  /**
+   * Notify of a screen change. Called by ScaleBunDebugRoot via NavDetector.
    */
   /** The screen currently on top, or null before the first navigation is observed. */
   getLastKnownScreen() {
@@ -875,9 +905,9 @@ export class SessionManager {
     });
   }
 
-  /**
-   * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
-   * Also triggers frame capture for desktop-initiated recordings.
+  /**
+   * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
+   * Also triggers frame capture for desktop-initiated recordings.
    */
   onUserAction(subtype, payload) {
     if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
@@ -892,9 +922,9 @@ export class SessionManager {
     // 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.
+  /**
+   * Detailed gesture detection — called by ScaleBunDebugRoot touch handlers.
+   * Emits a USER_ACTION event with gesture-specific subtype and payload.
    */
   onGestureDetected(gestureType, details) {
     // Build the canonical gesture payload ONCE so the recording lane and the
@@ -960,8 +990,8 @@ export class SessionManager {
     this.onUserAction(target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`, payload);
   }
 
-  /**
-   * Manual frame capture — triggered by Desktop "Capture Step" button.
+  /**
+   * Manual frame capture — triggered by Desktop "Capture Step" button.
    */
   async captureManualFrame() {
     if (!this.active || !this.captureManager) return null; // No capture when recording is OFF
@@ -971,8 +1001,8 @@ export class SessionManager {
     } : null;
   }
 
-  /**
-   * Notify of app lifecycle change.
+  /**
+   * Notify of app lifecycle change.
    */
   onLifecycleChange(state) {
     this.emitEvent(state === 'foreground' ? 'APP_FOREGROUND' : 'APP_BACKGROUND', {
@@ -982,9 +1012,9 @@ export class SessionManager {
 
   // ─── Scroll Integration ─────────────────────────────────────────────
 
-  /**
-   * Notify of a scroll event from a scrollable surface (ScaleBunScrollView).
-   * Delegates to ScrollTracker for accumulation and settle detection.
+  /**
+   * 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;
@@ -993,10 +1023,10 @@ export class SessionManager {
 
   // ─── 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')
+  /**
+   * 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;
@@ -1011,10 +1041,10 @@ export class SessionManager {
     });
   }
 
-  /**
-   * Notify that a screen has finished loading.
-   * Explicit instrumentation — call from app code.
-   * Triggers a 'screen_loaded' frame capture for the settled state.
+  /**
+   * 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;
@@ -1037,16 +1067,16 @@ export class SessionManager {
 
   // ─── Sync Policy ────────────────────────────────────────────────────
 
-  /**
-   * Override the sync policy. SDK-owned — native only provides metadata.
+  /**
+   * 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.
+  /**
+   * 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