@scalebun/react-native 1.10.7 → 1.11.0

package/ios/Capture/InteractionTracker.swift

@@ -17,8 +17,8 @@ class InteractionTracker: NSObject, UIGestureRecognizerDelegate {
 
     private var touchDownLocation: CGPoint = .zero
     private var touchDownTime: TimeInterval = 0
-    private var lastEmitTime: TimeInterval = 0
-    private let throttleInterval: TimeInterval = 0.15
+    private var touchInteractionId = ""
+    private var lastEmittedInteractionId = ""
 
     func attach(to window: UIWindow, sendEvent: @escaping (String, [String: Any]) -> Void) {
         guard !isActive else { return }
@@ -29,6 +29,7 @@ class InteractionTracker: NSObject, UIGestureRecognizerDelegate {
             onBegan: { [weak self] location in
                 self?.touchDownLocation = location
                 self?.touchDownTime = Date().timeIntervalSince1970
+                self?.touchInteractionId = "ixn-i-\(UUID().uuidString.lowercased())"
             },
             onEnded: { [weak self] location in
                 self?.handleTouchEnded(at: location, in: window)
@@ -55,8 +56,8 @@ class InteractionTracker: NSObject, UIGestureRecognizerDelegate {
 
     private func handleTouchEnded(at location: CGPoint, in window: UIWindow) {
         let now = Date().timeIntervalSince1970
-        guard now - lastEmitTime >= throttleInterval else { return }
-        lastEmitTime = now
+        guard touchInteractionId != lastEmittedInteractionId else { return }
+        lastEmittedInteractionId = touchInteractionId
 
         let durationMs = (now - touchDownTime) * 1000
         let dx = location.x - touchDownLocation.x
@@ -104,6 +105,9 @@ class InteractionTracker: NSObject, UIGestureRecognizerDelegate {
 
         let event: [String: Any] = [
             "gestureType": gestureType,
+            "interactionId": touchInteractionId,
+            "interactionProtocol": 1,
+            "occurredAt": touchDownTime * 1000,
             "rawX": downInCapture.x,
             "rawY": downInCapture.y,
             "normalizedX": nX,

package/lib/commonjs/analytics/EventTracker.js

@@ -103,7 +103,7 @@ class EventTracker {
     this.started = true;
     if (this.cfg.automaticEventTracking) {
       this.automaticEventsUnsubscribe = (0, _automaticEvents.subscribeAutomaticEvents)(event => {
-        this.track(event.name, event.properties);
+        this.track(event.name, event.properties, event.timestamp);
       });
     }
     if (this.cfg.autoLifecycleEvents) {
@@ -226,9 +226,9 @@ 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 */}
@@ -365,7 +365,7 @@ class EventTracker {
 
   // ─── internals ─────────────────────────────────────────────────────────────
 
-  buildEnvelope(eventName, properties) {
+  buildEnvelope(eventName, properties, timestamp) {
     const ctx = this.cfg.context ?? {};
     let canonicalSessionId;
     try {
@@ -376,7 +376,7 @@ 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 ?? (0, _device.resolveEventPlatform)(),
       installation_id: this.installationId,

package/lib/commonjs/analytics/automaticEvents.js

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

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

@@ -7,7 +7,12 @@ exports.SDK_VERSION = void 0;
 /**
  * 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.
  */
-const SDK_VERSION = exports.SDK_VERSION = '1.10.7';
+const SDK_VERSION = exports.SDK_VERSION = '1.11.0';
 //# sourceMappingURL=version.js.map

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

@@ -8,9 +8,9 @@ exports.ScaleBunScreen = ScaleBunScreen;
 exports.useScaleBunScreen = useScaleBunScreen;
 var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
-var _automaticEvents = require("../../analytics/automaticEvents");
 var _touchTarget = require("./touchTarget");
 var _device = require("../../core/context/device");
+var _interactionProtocol = require("./interactionProtocol");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
@@ -264,7 +264,9 @@ function ScaleBunDebugRoot({
   // and forwards them to SessionManager as USER_ACTION events.
   const lastNativeTouchTsRef = (0, _react.useRef)(0);
   const nativeTrackingConfirmedRef = (0, _react.useRef)(false);
-  const pendingJsEmitRef = (0, _react.useRef)(null);
+  const touchStartRef = (0, _react.useRef)(null);
+  const interactionStartsRef = (0, _react.useRef)([]);
+  const pendingJsEmitsRef = (0, _react.useRef)(new Map());
   (0, _react.useEffect)(() => {
     let subscription = null;
     try {
@@ -276,11 +278,15 @@ 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 = (0, _interactionProtocol.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
@@ -302,6 +308,15 @@ function ScaleBunDebugRoot({
             _diagWinH = _d.height;
           } catch {/* no-throw */}
           sm.onGestureDetected(event.gestureType || 'tap', {
+            interactionId: event.interactionId || start?.interactionId || (0, _interactionProtocol.generateInteractionId)(),
+            interactionProtocol: event.interactionProtocol || _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
@@ -331,11 +346,12 @@ 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 = (0, _react.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
@@ -379,11 +395,37 @@ function ScaleBunDebugRoot({
   const handleTouchStart = e => {
     try {
       const touch = e.nativeEvent;
-      touchStartRef.current = {
+      const target = (0, _touchTarget.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: (0, _interactionProtocol.generateInteractionId)(),
+        occurredAt: Date.now(),
         x: touch.pageX,
         y: touch.pageY,
-        ts: Date.now()
+        locationX: touch.locationX,
+        locationY: touch.locationY,
+        target: (0, _touchTarget.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 => {
@@ -422,15 +464,23 @@ 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 = (0, _touchTarget.describeTouchTarget)((0, _touchTarget.resolveTouchTarget)(e));
+      const tapped = start?.target ?? (0, _touchTarget.describeTouchTarget)((0, _touchTarget.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 ?? (0, _interactionProtocol.generateInteractionId)(),
+        interactionProtocol: _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
       };
@@ -442,8 +492,8 @@ 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;
@@ -475,7 +525,7 @@ 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
@@ -494,52 +544,6 @@ 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 */}
-        (0, _automaticEvents.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
@@ -549,18 +553,11 @@ 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 */}
       }
@@ -575,7 +572,7 @@ 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
@@ -588,11 +585,9 @@ 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 {
@@ -616,6 +611,7 @@ 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 */}
@@ -730,25 +726,6 @@ 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/commonjs/features/journey/interactionProtocol.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.INTERACTION_PROTOCOL_VERSION = void 0;
+exports.automaticInteractionProperties = automaticInteractionProperties;
+exports.generateInteractionId = generateInteractionId;
+exports.nearestInteractionStart = nearestInteractionStart;
+/** One physical interaction, shared by replay and analytics projections. */
+const INTERACTION_PROTOCOL_VERSION = exports.INTERACTION_PROTOCOL_VERSION = 1;
+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. */
+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. */
+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/commonjs/features/journey/uiState.js

@@ -82,6 +82,13 @@ 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/commonjs/features/session/JourneyEventPipeline.js

@@ -70,26 +70,27 @@ 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/commonjs/features/session/SessionManager.js

@@ -17,6 +17,8 @@ var _bridgeAdapter = require("../replay/bridge/adapters/bridgeAdapter");
 var _redaction = require("../../debug/redaction");
 var _calibrationContext = require("../journey/calibrationContext");
 var _device = require("../../core/context/device");
+var _automaticEvents = require("../../analytics/automaticEvents");
+var _interactionProtocol = require("../journey/interactionProtocol");
 /**
  * ScaleBun SDK — Session Manager
  *
@@ -35,12 +37,6 @@ var _device = require("../../core/context/device");
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-/**
- * Max analytics-lane heatmap interactions emitted per foreground (analytics
- * session) window. Bounds ingest volume now that capture defaults ON; enough to
- * resolve hotspot density, the long tail is dropped (drop-newest beyond cap).
- */
-const HEATMAP_MAX_INTERACTIONS_PER_WINDOW = 200;
 // ─── Singleton ──────────────────────────────────────────────────────────────
 
 let _instance = null;
@@ -56,15 +52,6 @@ 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;
@@ -666,21 +653,11 @@ 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);
@@ -707,16 +684,18 @@ class SessionManager {
         eventId: (0, _sessionId.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) {
       _internalLogger.logger.error('[SessionManager] heatmap analytics emit failed:', err);
+      return false;
     }
   }
 
@@ -936,13 +915,14 @@ 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).
@@ -957,7 +937,8 @@ 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
@@ -969,7 +950,15 @@ 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 ?? (0, _interactionProtocol.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 ?? _interactionProtocol.INTERACTION_PROTOCOL_VERSION,
+      state_status: stateStatus,
+      ui: details?.ui,
+      target_id: details?.targetId,
       gestureType,
       x: details?.x,
       y: details?.y,
@@ -1014,9 +1003,16 @@ 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 = (0, _redaction.redactBody)(payload);
+        (0, _automaticEvents.emitAutomaticEvent)('element_interacted', (0, _interactionProtocol.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
@@ -1026,7 +1022,10 @@ 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
+    });
   }
 
   /**