@scalebun/react-native 1.10.7 → 1.11.1

package/lib/module/features/ota/OtaOrchestrator.js

@@ -84,6 +84,11 @@ async function deliverOtaEvents(params) {
     kind: 'ota_event',
     type: e.type,
     bundleId: e.bundleId,
+    // Without this the backend stored a null releaseId on every row it ingested,
+    // while serving the release id on every check — so the delivery funnel could
+    // only ever be grouped by bundle, and a bundle re-promoted under a second
+    // release merged the two into one indistinguishable series.
+    releaseId: e.releaseId,
     installationId: params.installationId,
     // OTA bundles are compiled per platform, so this genuinely is ios|android. Narrowed via
     // resolveMobileOS so a non-mobile RN target is skipped rather than served an Android bundle.
@@ -121,7 +126,6 @@ async function deliverOtaEvents(params) {
 /** Boot-guard configuration */
 
 const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 export class OtaOrchestrator {
   enabled = false;
   currentBundle = null;
@@ -198,22 +202,35 @@ export class OtaOrchestrator {
       this.signatureConfig = config?.signature;
       __DEV__ && logger.debug(`[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` + `${this.environment.bridgeless ? ', bridgeless' : ''}` + `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`);
 
+      // ONE read of the slot state, shared by both boot-time consumers.
+      //
+      // `getSlotState()` is CONSUME-ON-READ for the revert record: both native
+      // implementations delete it as they serialise, so that a rollback is
+      // reported exactly once instead of on every launch forever. Calling it
+      // twice therefore means the second caller never sees the revert — which is
+      // precisely what happened, since hydration ran first and swallowed it. It
+      // is also a blocking synchronous bridge call, so one read is cheaper.
+      const slotState = this.readSlotState();
+
       // Rehydrate which bundle we are running from the native slot state.
       // Without this `currentBundle` stays null for the whole process after a
       // restart, so every check reported no current bundle and the backend had
       // no way to know what the device was actually on.
-      this.hydrateCurrentBundleFromSlots();
+      this.hydrateCurrentBundleFromSlots(slotState);
 
       // Warm the device-country cache (edge Worker lookup) so checks can carry
       // a country when the API itself sits behind no geo-stamping CDN.
       // Fire-and-forget and failure-soft — a check without a country is valid.
       void prefetchDeviceCountry();
 
+      // Check if the boot guard fired on this launch (native reverted before JS
+      // loaded). BEFORE the identity check, because both read the install record
+      // and the identity check retires it — a revert must get its chance to name
+      // the bundle that failed while the record still describes it.
+      this.checkBootGuardRecovery(slotState);
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
-
-      // Check if the boot guard fired on this launch (native reverted before JS loaded)
-      this.checkBootGuardRecovery();
     });
   }
 
@@ -221,10 +238,20 @@ export class OtaOrchestrator {
    * Read the active slot back into `currentBundle` so the next check reports
    * what this device is genuinely running.
    */
-  hydrateCurrentBundleFromSlots() {
-    if (!NativeScaleBunOta) return;
+  /**
+   * Parse the native slot state once. Returns null when the module is absent or
+   * the payload is unreadable — every caller treats that as "factory bundle".
+   */
+  readSlotState() {
+    if (!NativeScaleBunOta) return null;
+    try {
+      return JSON.parse(NativeScaleBunOta.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+  hydrateCurrentBundleFromSlots(state) {
     try {
-      const state = JSON.parse(NativeScaleBunOta.getSlotState());
       const current = state?.current;
       if (!current?.sha256) return;
 
@@ -239,6 +266,7 @@ export class OtaOrchestrator {
         this.currentBundle = {
           id: record.bundleId,
           version: record.version,
+          releaseId: record.releaseId ?? undefined,
           sha256: record.sha256
         };
         __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
@@ -275,37 +303,42 @@ export class OtaOrchestrator {
   verifyRunningBundleIdentity() {
     if (!this.currentBundle) return;
     const running = readRunningBundleMarker();
-    const expected = this.readInstallExpectation();
+    const record = this.readInstallRecord();
+
+    // No record at all — installed by an SDK that predates install records, or
+    // local storage was cleared. NOTHING can be concluded here and nothing is
+    // reported: the marker is a random per-publish token, never the bundle id,
+    // so comparing the two would flag a false mismatch on every healthy launch.
+    if (!record) return;
 
-    // Stale record from an earlier install — the slot has moved on since.
-    if (expected && expected.bundleId !== this.currentBundle.id) {
+    // The record describes a bundle that is no longer the active one (a revert,
+    // or a bundle staged by another path). It cannot verify this launch, and
+    // keeping it would make the next launch mis-report what is running.
+    if (record.sha256 !== this.currentBundle.sha256) {
       this.clearInstallExpectation();
       return;
     }
-    if (expected) {
-      if (running === expected.identityToken) {
-        // Proven: the bundle we installed is the bundle executing.
-        __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
-        this.clearInstallExpectation();
-        return;
-      }
-      logger.error(`[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` + `carries a known identity marker, but the running bundle reports ` + `${running ?? 'no marker at all'}. The app is executing different code than the slot ` + 'manager believes. Check that the host app resolves the OTA bundle path at launch ' + '(see the ScaleBunOta integration for your React Native version).');
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `install_not_effective — expected ${expected.identityToken}, running ${running ?? 'none'}`
-      });
-      // Deliberately NOT cleared: the condition is still true on the next boot
-      // and should keep reporting until the integration is fixed. Clearing here
-      // would make a permanently broken install look like a one-off.
+
+    // Already proven on an earlier launch. The token is retired once verified
+    // while the REST of the record stays — it is also the sha256 -> bundleId map
+    // that `hydrateCurrentBundleFromSlots` reads to report what this device is
+    // running. Wiping the whole record here is what made every launch after the
+    // first send `currentBundleId: undefined`, which the server reads as "not on
+    // this bundle" and answers by serving the same bundle again, forever.
+    if (!record.identityToken) return;
+    if (running === record.identityToken) {
+      __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      this.retireIdentityToken(record);
       return;
     }
-    if (running && running !== this.currentBundle.id) {
-      // No recorded expectation (installed by an older SDK), but the running
-      // marker disagrees with the active slot outright. Still conclusive.
-      logger.error(`[OTA] BUNDLE MISMATCH — slot says ${this.currentBundle.id} is active but the ` + `running bundle identifies as ${running}.`);
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `bundle_identity_mismatch — running ${running}`
-      });
-    }
+    logger.error(`[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` + `carries a known identity marker, but the running bundle reports ` + `${running ?? 'no marker at all'}. The app is executing different code than the slot ` + 'manager believes. Check that the host app resolves the OTA bundle path at launch ' + '(see the ScaleBunOta integration for your React Native version).');
+    otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
+      releaseId: this.currentBundle.releaseId,
+      error: `install_not_effective — expected ${record.identityToken}, running ${running ?? 'none'}`
+    });
+    // Deliberately NOT retired: the condition is still true on the next boot and
+    // should keep reporting until the integration is fixed. Retiring the token
+    // here would make a permanently broken install look like a one-off.
   }
 
   // ── Install expectation ────────────────────────────────────────────────────
@@ -319,6 +352,11 @@ export class OtaOrchestrator {
       this.storage().set(OtaOrchestrator.INSTALL_EXPECTATION_KEY, JSON.stringify({
         bundleId: bundle.id,
         version: bundle.version,
+        // Carried so telemetry emitted on a LATER launch (a boot-guard
+        // rollback, an ineffective install) can still be attributed to the
+        // release, not merely the bundle. The check response is long gone by
+        // then; this record is the only thing that remembers.
+        releaseId: bundle.releaseId ?? null,
         // The join key back to the native slot, which records sha256 and
         // nothing else identifying.
         sha256: bundle.sha256,
@@ -338,12 +376,28 @@ export class OtaOrchestrator {
       return null;
     }
   }
-  readInstallExpectation() {
-    const record = this.readInstallRecord();
-    return record && record.identityToken ? {
-      bundleId: record.bundleId,
-      identityToken: record.identityToken
-    } : null;
+
+  /**
+   * Drop the identity token once the install has been proven, keeping the rest
+   * of the record.
+   *
+   * The record does two jobs: it proves an install took effect (once), and it
+   * maps the native slot's sha256 back to a bundle id (for the life of that
+   * bundle). Only the first job is finished after a successful verification, so
+   * only the token is retired.
+   */
+  retireIdentityToken(record) {
+    try {
+      this.storage().set(OtaOrchestrator.INSTALL_EXPECTATION_KEY, JSON.stringify({
+        bundleId: record.bundleId,
+        version: record.version,
+        releaseId: record.releaseId ?? null,
+        sha256: record.sha256,
+        identityToken: null
+      }));
+    } catch {
+      /* non-fatal */
+    }
   }
   clearInstallExpectation() {
     try {
@@ -362,17 +416,43 @@ export class OtaOrchestrator {
    * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
    * and no 'current' OTA bundle, the native layer already reverted.
    */
-  checkBootGuardRecovery() {
-    if (!NativeScaleBunOta) return;
+  checkBootGuardRecovery(state) {
     try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
-      if (state.bootGuardReverted) {
-        logger.warn('[OTA] Boot guard fired — app was reverted to previous bundle');
-        otaEventEmitter.emitSimple('AUTO_ROLLBACK', state.previous?.bundleId ?? 'unknown', {
-          reason: 'boot_guard_crash_loop_detected'
+      if (!state?.bootGuardReverted) return;
+
+      // WHICH bundle was rolled back, and it has to come from the install
+      // record. The obvious source — `state.previous` — is wrong twice over:
+      // slot meta.json carries only `{sha256, installedAt}` so it has no bundle
+      // id to read, and `revert()` deletes the previous slot as its last step,
+      // so by the time this runs there is no previous meta at all. The event
+      // therefore reported `bundleId: 'unknown'` on every rollback, and the
+      // backend drops any ota_event whose bundleId does not resolve to a bundle
+      // the app owns — so the crash-guard's own rollback signal never arrived.
+      //
+      // Native now stamps the sha256 of the bundle it reverted AWAY FROM into
+      // the revert record; the install record maps that back to a bundle id.
+      const record = this.readInstallRecord();
+      const revertedSha = state.bootGuardRevertedSha256;
+      const matchesRecord = !!record && (!revertedSha || record.sha256 === revertedSha);
+
+      // Report the reason native actually determined — a hash mismatch and a
+      // crash loop are different incidents and were being collapsed into one.
+      const reason = state.bootGuardRevertReason || 'boot_crash_guard';
+      if (matchesRecord && record) {
+        logger.warn(`[OTA] Boot guard fired — reverted away from bundle ${record.bundleId} ` + `(v${record.version}); reason: ${reason}`);
+        otaEventEmitter.emitSimple('AUTO_ROLLBACK', record.bundleId, {
+          releaseId: record.releaseId ?? undefined,
+          version: record.version,
+          reason
         });
+        // The record describes a bundle this device is no longer running.
+        this.clearInstallExpectation();
+        return;
       }
+
+      // No usable record (older SDK, cleared storage). Say so rather than
+      // emitting an event the server is obliged to discard.
+      logger.warn(`[OTA] Boot guard fired (reason: ${reason}) but the rolled-back bundle could not be ` + 'identified locally — no install record. The rollback is not reported to the server.');
     } catch {
       // Slot state parsing failed — non-fatal
     }
@@ -473,6 +553,22 @@ export class OtaOrchestrator {
         };
       }
       __DEV__ && logger.debug('[OTA] Sync started…');
+
+      // The funnel's denominator, for devices already on an OTA bundle. Emitted
+      // before the request, so a check that fails outright still counts as a
+      // check — the only CHECK rows before this came from a server-side geo
+      // side-effect that is skipped whenever the request carries no country.
+      //
+      // Only when a current bundle is known: every ota_event must name a bundle
+      // the app owns or the server drops it, and a device still on the binary's
+      // factory bundle has no such id to give. Those devices are counted
+      // server-side when they are offered something.
+      if (this.currentBundle?.id) {
+        otaEventEmitter.emitSimple('CHECK', this.currentBundle.id, {
+          releaseId: this.currentBundle.releaseId,
+          version: this.currentBundle.version
+        });
+      }
       const checkRes = await this.checkForUpdate(params);
       if (checkRes.action === 'NONE') {
         __DEV__ && logger.debug('[OTA] App is up to date');
@@ -486,7 +582,9 @@ export class OtaOrchestrator {
       // Handle server-initiated rollback (Sprint 4)
       if (checkRes.action === 'ROLLBACK') {
         logger.warn('[OTA] Server requested ROLLBACK — reverting to previous bundle');
-        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown');
+        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown', {
+          releaseId: this.currentBundle?.releaseId
+        });
         const reverted = await NativeScaleBunOta.revertToPrevious();
         if (reverted) {
           this.currentBundle = null;
@@ -511,6 +609,15 @@ export class OtaOrchestrator {
       const bundle = checkRes.bundle;
       let patchUsed = false;
 
+      // The offer itself. Everything downstream (download, install, activation)
+      // is a conversion against this, so without it the top of the funnel was
+      // unmeasurable and a rollout that never reached devices looked identical
+      // to one whose devices all declined to download.
+      otaEventEmitter.emitSimple('OFFERED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version
+      });
+
       // ── VERIFY AUTHENTICITY (OTA-03) ─────────────────────────────────────
       // Before anything touches the disk. SHA-256 proves the bytes arrived
       // intact; only the signature proves they came from you. Checking after
@@ -518,6 +625,7 @@ export class OtaOrchestrator {
       const signatureOutcome = await verifyBundleSignature(bundle.sha256, bundle.signature, this.signatureConfig);
       if (!signatureOutcome.ok) {
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: `Signature check failed: ${signatureOutcome.reason}`,
           version: bundle.version
         });
@@ -530,6 +638,7 @@ export class OtaOrchestrator {
 
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
       otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       const downloadStart = Date.now();
@@ -628,6 +737,7 @@ export class OtaOrchestrator {
         postProgress(0, 'FAILED');
         logger.error('[OTA] Staging bundle failed after retries');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Staging failed — SHA-256 mismatch or download error',
           version: bundle.version
         });
@@ -640,6 +750,7 @@ export class OtaOrchestrator {
       postProgress(bundle.size, 'COMPLETED');
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version,
         durationMs: downloadDuration,
         patchUsed
@@ -651,6 +762,7 @@ export class OtaOrchestrator {
       if (!applied) {
         logger.error('[OTA] Applying update failed');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Atomic slot swap failed',
           version: bundle.version
         });
@@ -674,6 +786,7 @@ export class OtaOrchestrator {
       // it is skipped when there is no marker to compare.
       this.recordInstallExpectation(bundle);
       otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version
       });
       __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
@@ -746,6 +859,19 @@ export class OtaOrchestrator {
           NativeScaleBunOta?.markHealthy();
           __DEV__ && logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
+
+          // The honest activation signal. INSTALLED is emitted optimistically,
+          // BEFORE the bundle has ever executed, so counting it as adoption
+          // credits bundles that were installed and then crash-reverted. This
+          // fires only once the bundle has actually booted and survived.
+          const running = this.currentBundle;
+          if (running?.id) {
+            otaEventEmitter.emitSimple('BOOT_SUCCESS', running.id, {
+              releaseId: running.releaseId,
+              version: running.version,
+              durationMs: healthyMs
+            });
+          }
         });
       }, healthyMs);
     } catch {

package/lib/module/features/ota/OtaTypes.js

@@ -1,2 +1,2 @@
-
+export {};
 //# sourceMappingURL=OtaTypes.js.map

package/lib/module/features/ota/useOtaUpdate.js

@@ -60,7 +60,13 @@ export function useOtaUpdate(options) {
     setIsSyncing(true);
     setDownloadProgress(0);
     try {
-      const result = await otaOrchestrator.sync(options);
+      // Read through the ref, not the closed-over `options`. The dependency list
+      // below cannot name the targeting fields (`attributes` and `segmentIds` are
+      // fresh object/array identities on every render, so listing them would
+      // rebuild this callback each time), which left a host that changed
+      // `channelName` or `lifecycleStage` syncing against the values captured on
+      // first render. The ref is assigned on every render, so it is always current.
+      const result = await otaOrchestrator.sync(optionsRef.current);
       setSyncResult(result);
 
       // Handle mandatory update blocking
@@ -71,7 +77,10 @@ export function useOtaUpdate(options) {
     } finally {
       setIsSyncing(false);
     }
-  }, [options.apiUrl, options.clientKey, options.appVersion, options.installationId, options.autoRestart]);
+    // Empty: everything this reads comes from `optionsRef`, so the callback has a
+    // stable identity and never needs rebuilding. A host can safely pass it to a
+    // memoised child or an effect dependency list.
+  }, []);
   const restart = useCallback(() => {
     setMandatoryUpdatePending(false);
     otaOrchestrator.restart();

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
+    });
   }
 
   /**