@scalebun/react-native 1.10.7 → 1.11.0

package/lib/module/analytics/EventTracker.js

@@ -98,7 +98,7 @@ export class EventTracker {
     this.started = true;
     if (this.cfg.automaticEventTracking) {
       this.automaticEventsUnsubscribe = subscribeAutomaticEvents(event => {
-        this.track(event.name, event.properties);
+        this.track(event.name, event.properties, event.timestamp);
       });
     }
     if (this.cfg.autoLifecycleEvents) {
@@ -221,9 +221,9 @@ export class EventTracker {
 
   // ─── tracking ────────────────────────────────────────────────────────────
 
-  track(eventName, properties) {
+  track(eventName, properties, timestamp) {
     try {
-      this.enqueue(this.buildEnvelope(eventName, properties));
+      this.enqueue(this.buildEnvelope(eventName, properties, timestamp));
       try {
         this.cfg.onEvent?.(eventName);
       } catch {/* no-throw */}
@@ -360,7 +360,7 @@ export class EventTracker {
 
   // ─── internals ─────────────────────────────────────────────────────────────
 
-  buildEnvelope(eventName, properties) {
+  buildEnvelope(eventName, properties, timestamp) {
     const ctx = this.cfg.context ?? {};
     let canonicalSessionId;
     try {
@@ -371,7 +371,7 @@ export class EventTracker {
     const env = {
       event_id: uuid(),
       event_name: eventName,
-      event_time: Date.now(),
+      event_time: timestamp ?? Date.now(),
       app_id: this.cfg.appId,
       platform: this.cfg.platform ?? resolveEventPlatform(),
       installation_id: this.installationId,

package/lib/module/analytics/automaticEvents.js

@@ -19,10 +19,11 @@ function compactProperties(properties) {
   }
   return out;
 }
-export function emitAutomaticEvent(name, properties) {
+export function emitAutomaticEvent(name, properties, timestamp) {
   const event = {
     name,
-    properties: compactProperties(properties)
+    properties: compactProperties(properties),
+    timestamp
   };
   if (listeners.size === 0) {
     pending.push(event);

package/lib/module/core/constants/version.js

@@ -1,7 +1,12 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export const SDK_VERSION = '1.10.7';
+export const SDK_VERSION = '1.11.0';
 //# sourceMappingURL=version.js.map

package/lib/module/features/journey/ScaleBunDebugRoot.js

@@ -22,9 +22,9 @@
 
 import React, { useEffect, useRef, createContext, useContext } from 'react';
 import { View, NativeEventEmitter, NativeModules } from 'react-native';
-import { emitAutomaticEvent } from '../../analytics/automaticEvents';
 import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
 import { resolvePlatformOS } from '../../core/context/device';
+import { INTERACTION_PROTOCOL_VERSION, generateInteractionId, nearestInteractionStart } from './interactionProtocol';
 
 // ─── Lazy imports to avoid native module cascade at load time ────────────────
 // We only import TYPE references at the top level; actual modules are require()'d
@@ -256,7 +256,9 @@ export function ScaleBunDebugRoot({
   // and forwards them to SessionManager as USER_ACTION events.
   const lastNativeTouchTsRef = useRef(0);
   const nativeTrackingConfirmedRef = useRef(false);
-  const pendingJsEmitRef = useRef(null);
+  const touchStartRef = useRef(null);
+  const interactionStartsRef = useRef([]);
+  const pendingJsEmitsRef = useRef(new Map());
   useEffect(() => {
     let subscription = null;
     try {
@@ -268,11 +270,15 @@ export function ScaleBunDebugRoot({
           // Record timestamp to suppress duplicate JS touch events
           lastNativeTouchTsRef.current = Date.now();
           nativeTrackingConfirmedRef.current = true;
-
-          // Cancel any pending JS emission — native event wins
-          if (pendingJsEmitRef.current !== null) {
-            clearTimeout(pendingJsEmitRef.current);
-            pendingJsEmitRef.current = null;
+          const nativeOccurredAt = typeof event.occurredAt === 'number' ? event.occurredAt : (typeof event.timestamp === 'number' ? event.timestamp : Date.now()) - (typeof event.durationMs === 'number' ? event.durationMs : 0);
+          const start = nearestInteractionStart(interactionStartsRef.current, nativeOccurredAt);
+
+          // Cancel only this physical touch's fallback. A single timer used to cancel a
+          // previous rapid tap and silently lose it on devices without native tracking.
+          if (start) {
+            const pending = pendingJsEmitsRef.current.get(start.interactionId);
+            if (pending !== undefined) clearTimeout(pending);
+            pendingJsEmitsRef.current.delete(start.interactionId);
           }
           const {
             SessionManager
@@ -294,6 +300,15 @@ export function ScaleBunDebugRoot({
             _diagWinH = _d.height;
           } catch {/* no-throw */}
           sm.onGestureDetected(event.gestureType || 'tap', {
+            interactionId: event.interactionId || start?.interactionId || generateInteractionId(),
+            interactionProtocol: event.interactionProtocol || INTERACTION_PROTOCOL_VERSION,
+            occurredAt: nativeOccurredAt,
+            ui: start?.ui,
+            stateStatus: start?.stateStatus ?? 'not_captured',
+            target: start?.target,
+            targetId: start?.targetId,
+            screenName: start?.screenName,
+            emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
             x: event.rawX,
             y: event.rawY,
             // Use the actual native end coords when present, not the down
@@ -323,11 +338,12 @@ export function ScaleBunDebugRoot({
       try {
         subscription?.remove();
       } catch {/* no-throw */}
+      for (const timer of pendingJsEmitsRef.current.values()) clearTimeout(timer);
+      pendingJsEmitsRef.current.clear();
     };
-  }, []);
+  }, [captureAutomaticInteractions]);
 
   // ─── Touch Tracking State ───────────────────────────────────────────
-  const touchStartRef = useRef(null);
 
   // On-screen rect of the root view — the EXACT view the native screenshot
   // captures. Normalizing pageX/pageY against this rect makes JS-fallback taps
@@ -371,11 +387,37 @@ export function ScaleBunDebugRoot({
   const handleTouchStart = e => {
     try {
       const touch = e.nativeEvent;
-      touchStartRef.current = {
+      const target = resolveTouchTarget(e);
+      let ui;
+      let screenName;
+      try {
+        const {
+          uiStateSignature
+        } = require('./uiState');
+        ui = uiStateSignature();
+      } catch {/* no-throw */}
+      try {
+        const {
+          AutoScreenDetector
+        } = require('../navigation/AutoScreenDetector');
+        screenName = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+      } catch {/* no-throw */}
+      const start = {
+        interactionId: generateInteractionId(),
+        occurredAt: Date.now(),
         x: touch.pageX,
         y: touch.pageY,
-        ts: Date.now()
+        locationX: touch.locationX,
+        locationY: touch.locationY,
+        target: describeTouchTarget(target),
+        targetId: target?.testID,
+        screenName,
+        ui,
+        stateStatus: ui ? 'captured_nonempty' : 'not_instrumented',
+        emitAutomaticAnalytics: captureAutomaticInteractions
       };
+      touchStartRef.current = start;
+      interactionStartsRef.current = interactionStartsRef.current.filter(candidate => start.occurredAt - candidate.occurredAt < 5000).concat(start).slice(-8);
     } catch {/* no-throw */}
   };
   const handleTouchEnd = e => {
@@ -414,15 +456,23 @@ export function ScaleBunDebugRoot({
       // WHAT was tapped, resolved from the React fiber on the touch event. Without this the tap
       // carries only coordinates, so every tap in the app groups into one row per gesture type.
       // Defensive by construction — returns undefined rather than throwing (see touchTarget.ts).
-      const tapped = describeTouchTarget(resolveTouchTarget(e));
+      const tapped = start?.target ?? describeTouchTarget(resolveTouchTarget(e));
       const gestureDetails = {
         target: tapped,
-        x: touch.pageX,
-        y: touch.pageY,
-        pageX: touch.pageX,
-        pageY: touch.pageY,
-        locationX: touch.locationX,
-        locationY: touch.locationY,
+        interactionId: start?.interactionId ?? generateInteractionId(),
+        interactionProtocol: INTERACTION_PROTOCOL_VERSION,
+        occurredAt: start?.occurredAt ?? Date.now(),
+        ui: start?.ui,
+        stateStatus: start?.stateStatus ?? 'not_captured',
+        targetId: start?.targetId,
+        screenName: start?.screenName,
+        emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
+        x: start?.x ?? touch.pageX,
+        y: start?.y ?? touch.pageY,
+        pageX: start?.x ?? touch.pageX,
+        pageY: start?.y ?? touch.pageY,
+        locationX: start?.locationX ?? touch.locationX,
+        locationY: start?.locationY ?? touch.locationY,
         viewportWidth: vpW > 0 ? vpW : undefined,
         viewportHeight: vpH > 0 ? vpH : undefined
       };
@@ -434,8 +484,8 @@ export function ScaleBunDebugRoot({
       // measureInWindow returns rootRect.y = statusBarHeight, so subtracting it
       // double-counts the status bar and pushes every marker upward.
       if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
-        const nx = Math.max(0, Math.min(1, touch.pageX / rootRect.w));
-        const ny = Math.max(0, Math.min(1, touch.pageY / rootRect.h));
+        const nx = Math.max(0, Math.min(1, (start?.x ?? touch.pageX) / rootRect.w));
+        const ny = Math.max(0, Math.min(1, (start?.y ?? touch.pageY) / rootRect.h));
         gestureDetails.normalizedX = nx;
         gestureDetails.normalizedY = ny;
         gestureDetails.normalizedPrecomputed = true;
@@ -467,7 +517,7 @@ export function ScaleBunDebugRoot({
         const dx = touch.pageX - start.x;
         const dy = touch.pageY - start.y;
         const dist = Math.sqrt(dx * dx + dy * dy);
-        const duration = Date.now() - start.ts;
+        const duration = Date.now() - start.occurredAt;
         gestureDetails.duration = duration;
         if (dist >= 15) {
           // Movement gesture: swipe or scroll
@@ -486,52 +536,6 @@ export function ScaleBunDebugRoot({
           gestureType = 'long_press';
         }
       }
-      const targetInfo = _extractTarget(e);
-      gestureDetails.target = targetInfo?.testId || targetInfo?.accessibilityLabel;
-      if (captureAutomaticInteractions) {
-        let screen;
-        try {
-          const {
-            AutoScreenDetector
-          } = require('../navigation/AutoScreenDetector');
-          screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-        } catch {/* no-throw */}
-        /**
-         * UI STATE, read HERE and not later.
-         *
-         * A tap belongs to the surface that was on screen when the finger landed: tapping the
-         * filter button while the sheet is DOWN belongs to `closed`, because that is what the
-         * user was looking at when they reached for it. Reading it after the handler has run
-         * moves every "open the thing" tap into the state it created — the one state it
-         * certainly does not belong to.
-         *
-         * Declared-only on this platform (see uiState.ts): absent means not captured, which
-         * the dashboard keeps distinct from "nothing was open".
-         */
-        let ui;
-        try {
-          const {
-            uiStateSignature
-          } = require('./uiState');
-          ui = uiStateSignature();
-        } catch {/* no-throw: a tap must never be lost to state capture */}
-        emitAutomaticEvent('element_interacted', {
-          gesture_type: gestureType,
-          screen_name: screen,
-          /* THIS MAP ENUMERATES. A field added to the payload and forgotten here reaches the
-             backend as undefined with no error anywhere — the recurring defect class in this
-             codebase. `ui` is the key the grid aggregate reads for state, byte-identical to
-             the web SDK's, so one dashboard control queries both platforms. */
-          ui,
-          // testID/nativeID is an author-controlled stable identifier.
-          // Accessibility labels and rendered text are deliberately omitted.
-          target_id: targetInfo?.testId,
-          normalized_x: gestureDetails.normalizedX,
-          normalized_y: gestureDetails.normalizedY,
-          direction: gestureDetails.direction,
-          duration_ms: gestureDetails.duration
-        });
-      }
 
       // Feed the Engage gesture detector (rage_tap / dead_tap) — only committed
       // taps, not swipes/scrolls/long-presses. Pure JS, cross-platform; emits the
@@ -541,18 +545,11 @@ export function ScaleBunDebugRoot({
           const {
             gestureTriggerDetector
           } = require('../engage/gestureTriggerDetector');
-          let screen;
-          try {
-            const {
-              AutoScreenDetector
-            } = require('../navigation/AutoScreenDetector');
-            screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-          } catch {/* no-throw */}
           gestureTriggerDetector.recordTap({
-            x: touch.pageX,
-            y: touch.pageY,
-            hasTarget: !!(targetInfo?.testId || targetInfo?.accessibilityLabel),
-            screen
+            x: start?.x ?? touch.pageX,
+            y: start?.y ?? touch.pageY,
+            hasTarget: !!(start?.targetId || start?.target),
+            screen: start?.screenName
           });
         } catch {/* no-throw */}
       }
@@ -567,7 +564,7 @@ export function ScaleBunDebugRoot({
       // screenshot capture view). Three-tier suppression:
       //   1. Native confirmed active → skip JS entirely (native handles all touches)
       //   2. Native event within 300ms → skip (existing dedup)
-      //   3. First touch (native not yet confirmed) → defer 200ms to let native arrive
+      //   3. First touch (native not yet confirmed) → defer 600ms to let native arrive
       const sinceNative = Date.now() - lastNativeTouchTsRef.current;
       if (nativeTrackingConfirmedRef.current) {
         // Native tracker is active — skip JS path entirely
@@ -580,11 +577,9 @@ export function ScaleBunDebugRoot({
         const capturedDetails = {
           ...gestureDetails
         };
-        if (pendingJsEmitRef.current !== null) {
-          clearTimeout(pendingJsEmitRef.current);
-        }
-        pendingJsEmitRef.current = setTimeout(() => {
-          pendingJsEmitRef.current = null;
+        const interactionId = capturedDetails.interactionId;
+        const timer = setTimeout(() => {
+          pendingJsEmitsRef.current.delete(interactionId);
           if (nativeTrackingConfirmedRef.current) return;
           try {
             const {
@@ -608,6 +603,7 @@ export function ScaleBunDebugRoot({
           // devices with no native tracker at all it merely delays a background emission,
           // which nothing user-visible waits on.
         }, 600);
+        pendingJsEmitsRef.current.set(interactionId, timer);
       }
       touchStartRef.current = null;
     } catch {/* no-throw */}
@@ -722,25 +718,6 @@ export function useScaleBunScreen(name) {
   }, [name, manager]);
 }
 
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-function _extractTarget(e) {
-  try {
-    const target = e?.target;
-    if (!target) return undefined;
-
-    // React Native nativeEvent target properties
-    const props = target._internalFiberInstanceHandleDEV?.memoizedProps ?? {};
-    return {
-      testId: props.testID || props.nativeID || undefined,
-      accessibilityLabel: props.accessibilityLabel || undefined,
-      text: undefined
-    };
-  } catch {
-    return undefined;
-  }
-}
-
 // ─── Styles ─────────────────────────────────────────────────────────────────
 // IMPORTANT: Do NOT use StyleSheet.create() here.
 // In RN 0.84 bridgeless mode, StyleSheet.create() calls

package/lib/module/features/journey/interactionProtocol.js

@@ -0,0 +1,38 @@
+/** One physical interaction, shared by replay and analytics projections. */
+export const INTERACTION_PROTOCOL_VERSION = 1;
+export function generateInteractionId() {
+  return `ixj-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Match a native bridge event to the JS evidence sampled at the same finger-down. */
+export function nearestInteractionStart(starts, occurredAt, toleranceMs = 1500) {
+  let best;
+  let bestDelta = toleranceMs + 1;
+  for (const start of starts) {
+    const delta = Math.abs(start.occurredAt - occurredAt);
+    if (delta < bestDelta) {
+      best = start;
+      bestDelta = delta;
+    }
+  }
+  return bestDelta <= toleranceMs ? best : undefined;
+}
+
+/** Analytics is a projection of the same evidence; no second click is invented. */
+export function automaticInteractionProperties(payload, screenName, canonicalMirror) {
+  return {
+    gesture_type: payload.gestureType,
+    screen_name: screenName,
+    interaction_id: payload.interaction_id,
+    interaction_protocol: payload.interaction_protocol,
+    state_status: payload.state_status,
+    ui: payload.ui,
+    target_id: payload.target_id,
+    normalized_x: payload.normalizedX,
+    normalized_y: payload.normalizedY,
+    direction: payload.direction,
+    duration_ms: payload.durationMs,
+    canonical_mirror: canonicalMirror || undefined
+  };
+}
+//# sourceMappingURL=interactionProtocol.js.map

package/lib/module/features/journey/uiState.js

@@ -74,6 +74,13 @@ export function uiStateSignature() {
   if (!declared.size) return undefined;
   /* SORTED, or the same surface produces different signatures depending on the order the host happened
      to declare things in, and every count fragments into several that mean nothing. */
-  return [...declared.keys()].sort().map(k => `${k}:${declared.get(k)}`).join(';').slice(0, 96);
+  const pairs = [...declared.keys()].sort().map(k => `${k}:${declared.get(k)}`);
+  let signature = '';
+  for (const pair of pairs) {
+    const next = signature ? `${signature};${pair}` : pair;
+    if (next.length > 96) break;
+    signature = next;
+  }
+  return signature || undefined;
 }
 //# sourceMappingURL=uiState.js.map

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

@@ -65,26 +65,27 @@ export class JourneyEventPipeline {
   emit(type, opts) {
     try {
       const key = `${type}:${opts?.subtype ?? ''}`;
-      const now = Date.now();
-      if (key === this.lastEventKey && now - this.lastEventTs < this.config.dedupeWindowMs) {
+      const receivedAt = Date.now();
+      const occurredAt = opts?.timestamp ?? receivedAt;
+      if (key === this.lastEventKey && receivedAt - this.lastEventTs < this.config.dedupeWindowMs) {
         // Within dedup window — allow high-confidence native events to
         // REPLACE a prior low-confidence JS event for the same gesture.
         // This prevents the race where JS fires first and the pipeline
         // drops the native event that has more accurate coordinates.
         const incomingConfidence = opts?.payload?.confidence;
         if (incomingConfidence === 'high' && this.lastEventConfidence !== 'high') {
-          this._replaceLastEvent(key, now, opts);
+          this._replaceLastEvent(key, receivedAt, opts);
         }
         return null;
       }
       this.lastEventKey = key;
-      this.lastEventTs = now;
+      this.lastEventTs = receivedAt;
       this.lastEventConfidence = opts?.payload?.confidence ?? null;
       const event = {
         eventId: generateEventId(),
         sessionId: this.sessionId,
         journeyId: opts?.journeyId,
-        ts: now,
+        ts: occurredAt,
         type,
         subtype: opts?.subtype,
         severity: opts?.severity ?? inferSeverity(type),

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

@@ -27,15 +27,11 @@ 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 { INTERACTION_PROTOCOL_VERSION, automaticInteractionProperties, generateInteractionId } from '../journey/interactionProtocol';
 
 // ─── 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;
 // ─── Singleton ──────────────────────────────────────────────────────────────
 
 let _instance = null;
@@ -51,15 +47,6 @@ export class SessionManager {
    * 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.
-   */
-  _heatmapWindowSessionId = null;
-  _heatmapWindowCount = 0;
   session = null;
   active = false;
   timeoutTimer = null;
@@ -661,21 +648,11 @@ export class SessionManager {
    *     injected sensitive keys (e.g. a label) are stripped before transport.
    *   - Never throws.
    */
-  _emitInteractionToAnalytics(gestureType, payload) {
-    if (!this._captureInteractionHeatmap) return;
-    if (this.active) return; // recording lane already carries this tap
+  _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;
-
-    // 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++;
+    if (!adapter) return false;
     try {
       // Normalize coords in place (same logic as the recording lane).
       this._normalizeInteractionPayload(payload);
@@ -702,16 +679,18 @@ export class SessionManager {
         eventId: generateEventId(),
         // sessionId is (re)stamped by the analytics lane at flush time.
         sessionId: adapter.analyticsSessionId ?? '',
-        ts: Date.now(),
+        ts: occurredAt,
         type: 'USER_ACTION',
         subtype: `gesture:${gestureType}`,
-        screen: this._lastKnownScreen ?? undefined,
+        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;
     }
   }
 
@@ -931,13 +910,14 @@ export class SessionManager {
    * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
    * Also triggers frame capture for desktop-initiated recordings.
    */
-  onUserAction(subtype, payload) {
+  onUserAction(subtype, payload, context) {
     if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
     this.emitEvent('USER_ACTION', {
       subtype,
-      screen: this._lastKnownScreen ?? undefined,
+      screen: context?.screen ?? this._lastKnownScreen ?? undefined,
       payload,
-      source: 'user'
+      source: 'user',
+      timestamp: context?.timestamp
     });
     // NOTE: Do NOT call captureManager.onInteraction() here.
     // emitEvent() already triggers onInteraction() for USER_ACTION events (line ~405).
@@ -952,7 +932,8 @@ export class SessionManager {
     // 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 dedupSig = `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
+    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
@@ -964,7 +945,15 @@ export class SessionManager {
     // 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,
       gestureType,
       x: details?.x,
       y: details?.y,
@@ -1009,9 +998,16 @@ export class SessionManager {
     // 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, {
+    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
@@ -1021,7 +1017,10 @@ export class SessionManager {
     // ⚠️ `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);
+    this.onUserAction(target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`, payload, {
+      screen: details?.screenName,
+      timestamp: occurredAt
+    });
   }
 
   /**

package/lib/typescript/analytics/EventTracker.d.ts

@@ -125,7 +125,7 @@ export declare class EventTracker {
      * Persisted so it survives the click→install→open gap. Call BEFORE start() ideally.
      */
     setAttributionClickId(clickId: string): void;
-    track(eventName: string, properties?: Record<string, any>): void;
+    track(eventName: string, properties?: Record<string, any>, timestamp?: number): void;
     trackPurchase(input: {
         revenue: number;
         currency: string;

package/lib/typescript/analytics/automaticEvents.d.ts

@@ -18,9 +18,11 @@ export type AutomaticEventName = 'app_foregrounded' | 'app_backgrounded' | 'scre
 export interface AutomaticEvent {
     name: AutomaticEventName;
     properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
 }
 type AutomaticEventListener = (event: AutomaticEvent) => void;
-export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>): void;
+export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>, timestamp?: number): void;
 export declare function subscribeAutomaticEvents(listener: AutomaticEventListener): () => void;
 /** Test-only reset; intentionally not exported from the package entry point. */
 export declare function resetAutomaticEventsForTests(): void;

package/lib/typescript/core/constants/version.d.ts

@@ -1,7 +1,12 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export declare const SDK_VERSION = "1.10.7";
+export declare const SDK_VERSION = "1.11.0";
 //# sourceMappingURL=version.d.ts.map