@scalebun/react-native 2.0.0 → 2.0.2

package/ios/ReplaySdk.swift

@@ -1,4 +1,5 @@
 import Foundation
+import React
 import UIKit
 
 /// Main ReplaySdk native module (RCTEventEmitter subclass).
@@ -32,12 +33,57 @@ class ReplaySdk: RCTEventEmitter {
     }
 
     /// Attach native touch tracking to the key window.
-    /// Called from initialize() after a short delay to ensure the window is ready.
+    ///
+    /// RETRIED, AND RE-ATTACHED ON FOREGROUND — because the previous one-shot version is the most
+    /// likely explanation for iOS capturing coordinates on 0.4% of interactions where Android
+    /// manages 15.3%.
+    ///
+    /// It ran exactly once, 500 ms after `initialize()`. If `getKeyWindow()` returned nil at that
+    /// instant it logged a warning and never tried again, so native touch tracking was off for the
+    /// WHOLE app session. A cold start behind a heavy JS bundle, a slow device, or a scene-based
+    /// app whose key window is not the one that existed at +500 ms — any of those and no touch is
+    /// ever tracked. Losing that race once lost it permanently.
+    ///
+    /// Android never had the problem because it attaches from a lifecycle hook
+    /// (`ReplaySdkModule.onHostResume`), so every foreground corrects an attach that was too early.
+    /// This mirrors that: bounded retries for the cold-start race, plus a foreground observer that
+    /// attaches if a previous attempt never succeeded. `attach` is idempotent —
+    /// `guard !isActive else { return }` — so a redundant call costs nothing and cannot install a
+    /// second gesture recognizer.
+    ///
+    /// WHAT THIS DOES NOT FIX, stated because that same guard is why: a key window that CHANGES
+    /// after a successful attach. `attach` returns early on `isActive` without comparing the
+    /// window, so the tracker stays bound to the original one and the foreground observer cannot
+    /// help. That needs a detach-and-rebind inside `InteractionTracker`, which is a larger change
+    /// than the race this addresses. The cold-start race is the dominant cause — it costs the whole
+    /// session every time it is lost — and it is fixed here; the window-change case remains open.
     private func activateNativeTracking() {
+        scheduleAttach(attemptsRemaining: 10)
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(reattachNativeTracking),
+            name: UIApplication.didBecomeActiveNotification,
+            object: nil
+        )
+    }
+
+    /// Try to attach, and try again shortly if there is no key window yet.
+    ///
+    /// Ten attempts at 500 ms covers about five seconds of startup, which is far longer than a
+    /// window takes to appear and short enough that a genuinely window-less process stops asking.
+    /// The last failure is logged at warn so a host that never gets tracking is told, rather than
+    /// discovering it as an empty heatmap.
+    private func scheduleAttach(attemptsRemaining: Int) {
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
             guard let self = self else { return }
             guard let window = Self.getKeyWindow() else {
-                ReplayLogger.warn("Native tracking: no key window available")
+                if attemptsRemaining > 1 {
+                    self.scheduleAttach(attemptsRemaining: attemptsRemaining - 1)
+                } else {
+                    ReplayLogger.warn(
+                        "Native tracking: no key window after repeated attempts — touch capture is off"
+                    )
+                }
                 return
             }
             self.interactionTracker.attach(to: window, sendEvent: { [weak self] name, payload in
@@ -46,6 +92,23 @@ class ReplaySdk: RCTEventEmitter {
         }
     }
 
+    /// Re-attach when the app becomes active, mirroring Android's `onHostResume`.
+    @objc private func reattachNativeTracking() {
+        guard let window = Self.getKeyWindow() else { return }
+        interactionTracker.attach(to: window, sendEvent: { [weak self] name, payload in
+            self?.sendEvent(withName: name, body: payload)
+        })
+    }
+
+    /// Matches what the other two observer-registering modules here do
+    /// (`SessionManager`, `ScaleBunProfilerModule`). A native module usually outlives the app's
+    /// interesting lifetime and selector observers have been zeroing-weak since iOS 9, so this is
+    /// hygiene rather than a crash fix — but being the one file that registers and never removes is
+    /// how a convention quietly stops being one.
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
     private static func getKeyWindow() -> UIWindow? {
         return WindowResolver.keyWindow()
     }

package/lib/commonjs/bootstrap/SDKBootstrapper.js

@@ -80,6 +80,15 @@ class SDKBootstrapper {
     // apiBaseUrl is LOCKED: whatever an integrator passed (or the schema default) is
     // discarded here so the SDK can never be repointed away from the ScaleBun cloud.
     // Change DEFAULT_API_BASE_URL at build time to target a different backend.
+    // Say so when we discard it. The value was accepted by the schema, silently
+    // overwritten here, and the SDK then talked to a different server than the
+    // integrator configured — with no log, no warning, and no error. Someone
+    // pointing the SDK at a staging or local backend would watch requests arrive
+    // at production and have nothing to go on.
+    const requestedApiBaseUrl = rawConfig?.apiBaseUrl;
+    if (typeof requestedApiBaseUrl === 'string' && requestedApiBaseUrl && requestedApiBaseUrl !== _endpoints.DEFAULT_API_BASE_URL) {
+      _internalLogger.logger.warn(`[ScaleBun] Ignoring apiBaseUrl '${requestedApiBaseUrl}' — the endpoint is ` + `locked at build time and this build targets ${_endpoints.DEFAULT_API_BASE_URL}. To ` + `target another backend, change DEFAULT_API_BASE_URL in the SDK source and ` + `rebuild.`);
+    }
     this.config.apiBaseUrl = _endpoints.DEFAULT_API_BASE_URL;
     // Explicit logLevel wins; otherwise debug:true implies verbose 'debug'.
     if (this.config.logLevel) {
@@ -319,6 +328,27 @@ class SDKBootstrapper {
     await this.featureRegistry.initializeAll(featureContext);
 
     // ── Session Replay Initialization (Core) ───────────────
+    /**
+    * RN-3 zero-config scroll instrumentation, opt-in.
+    *
+    * Placed before replay init because it patches a module export and must be in place before the
+    * host renders its first scroll view. Reports rather than assumes: the equivalent React
+    * Navigation hook once claimed success it had not verified and left a whole pipeline silently
+    * empty, so a failure here is said out loud with a reason an integrator can act on.
+    */
+    if (this.config.autoInstrumentScrollViews === true) {
+      try {
+        const {
+          autoInstrumentScrollViews
+        } = require('../features/journey/autoInstrumentScroll');
+        const outcome = autoInstrumentScrollViews();
+        if (!outcome.installed) {
+          _internalLogger.logger.warn('[Bootstrap] autoInstrumentScrollViews was requested but could not be ' + 'installed: ' + outcome.reason + ' — taps will carry no content depth.');
+        } else {
+          __DEV__ && _internalLogger.logger.debug('[Bootstrap] ScrollView auto-instrumentation installed');
+        }
+      } catch {/* no-throw */}
+    }
     if (features.replay !== false) {
       try {
         __DEV__ && _internalLogger.logger.debug('[Bootstrap] Initializing unified SessionManager');

package/lib/commonjs/core/config/schema.js

@@ -275,6 +275,22 @@ const SHAPE = {
     }
   },
   captureInteractionHeatmap: bool(true),
+  /**
+   * RN-3 zero-config: patch React Native's ScrollView export so EVERY scroll view reports its
+   * offset, not just ones wrapped in ScaleBunScrollView.
+   *
+   * DEFAULT FALSE, unlike captureInteractionHeatmap above, and the difference is deliberate.
+   * That flag changes what the SDK records about the host; this one changes what the HOST
+   * RENDERS — every scroll view in the app, including ones inside third-party libraries the app
+   * did not write, starts routing through an SDK component. The failure mode is not a wrong
+   * number in a dashboard, it is the host's UI behaving differently because an analytics SDK
+   * replaced a primitive. That is a decision an integrator makes deliberately, not one they
+   * discover afterwards.
+   *
+   * With it off, a plain <ScrollView> yields no content depth and the tap says so
+   * (scroll_source: 'none') rather than defaulting its offset to 0.
+   */
+  autoInstrumentScrollViews: bool(false),
   // Opt-in: intercept console.* and ship the lines to the Diagnose → Logs lane in SaaS
   // mode. OFF by default — console output can carry PII/secrets and adds ingest volume,
   // so capturing it is the host's explicit choice, not a silent default. When true and a

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

@@ -14,5 +14,5 @@ exports.SDK_VERSION = void 0;
  * 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 = '2.0.0';
+const SDK_VERSION = exports.SDK_VERSION = '2.0.2';
 //# sourceMappingURL=version.js.map

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

@@ -9,6 +9,8 @@ exports.useScaleBunScreen = useScaleBunScreen;
 var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
 var _touchTarget = require("./touchTarget");
+var _targetGeometry = require("./targetGeometry");
+var _scrollContext = require("./scrollContext");
 var _device = require("../../core/context/device");
 var _interactionProtocol = require("./interactionProtocol");
 var _jsxRuntime = require("react/jsx-runtime");
@@ -50,6 +52,15 @@ function getBootstrap() {
 
 const JourneyContext = /*#__PURE__*/(0, _react.createContext)(null);
 
+/**
+ * Floor on how often a UI-state change may request a screenshot.
+ *
+ * One frame per second is far finer than any state a person perceives changing, and far coarser
+ * than a render loop — which is the case that matters, because a host may legitimately declare
+ * state from inside render and an oscillating dimension would otherwise capture continuously.
+ */
+const UI_STATE_CAPTURE_MIN_INTERVAL_MS = 1000;
+
 // ─── ScaleBunDebugRoot ───────────────────────────────────────────────────────────
 
 function ScaleBunDebugRoot({
@@ -259,6 +270,54 @@ function ScaleBunDebugRoot({
     };
   }, [navigationRef]);
 
+  /**
+   * RN-11 — CAPTURE A FRAME WHEN THE UI CHANGES SHAPE.
+   *
+   * A declared state used to have no picture of its own. Nothing captured on `setUiState`, so a
+   * state's visual existed only if a screenshot happened to be taken for another reason — a
+   * navigation, a timer, or the interaction capture that fires AFTER the touch and therefore
+   * photographs the outcome. A drawer could be recorded as open with no frame showing it open,
+   * or with the frame of the screen that replaced it.
+   *
+   * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER; none of them means
+   * "the UI changed shape". This routes through the MANUAL path, which is the only one reachable
+   * from JS. A dedicated native reason would let the backend tell a state capture from a
+   * developer-requested one, and that is a native change on both platforms — worth doing, not
+   * doable from here.
+   *
+   * RATE LIMITED, and the limit is not politeness. A screenshot is expensive, and while
+   * `uiState` already collapses redundant declarations, a genuinely oscillating dimension (a
+   * spinner toggling, a live-updating badge) would otherwise capture continuously. One frame per
+   * second is far finer than any state a person can perceive changing and far coarser than a
+   * render loop.
+   *
+   * Requests only; never awaits and never throws. If the session is not recording,
+   * `captureManualFrame` declines and the state simply has no frame — which is the honest
+   * outcome and is exactly what the analytics-only lane already reports elsewhere.
+   */
+  (0, _react.useEffect)(() => {
+    let lastCaptureTs = 0;
+    const {
+      onUiStateChange
+    } = require('./uiState');
+    const unsubscribe = onUiStateChange(() => {
+      const now = Date.now();
+      if (now - lastCaptureTs < UI_STATE_CAPTURE_MIN_INTERVAL_MS) return;
+      lastCaptureTs = now;
+      try {
+        const {
+          SessionManager
+        } = require('../session/SessionManager');
+        const sm = SessionManager.getExistingInstance();
+        if (sm && typeof sm.captureManualFrame === 'function') {
+          /* Fire and forget: the tap that follows must not wait on a screenshot. */
+          void sm.captureManualFrame();
+        }
+      } catch {/* no-throw */}
+    });
+    return unsubscribe;
+  }, []);
+
   // ─── Native Interaction Listener ────────────────────────────────────
   // Receives high-confidence ScaleBunNativeInteraction events from the native tracker
   // and forwards them to SessionManager as USER_ACTION events.
@@ -279,7 +338,27 @@ function ScaleBunDebugRoot({
           lastNativeTouchTsRef.current = Date.now();
           nativeTrackingConfirmedRef.current = true;
           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);
+          /**
+           * RN-6 — correlate, then CONSUME. See interactionProtocol.ts for why
+           * the join is on time at all, and why a refusal is the important part.
+           *
+           * Pruning first is part of the correctness, not tidying: a start older
+           * than the tolerance can never be paired, but while it sits in the list
+           * it is still counted by the ambiguity test, so a stale entry can turn a
+           * clear pairing into a refusal — and the list only grows.
+           */
+          (0, _interactionProtocol.pruneInteractionStarts)(interactionStartsRef.current, nativeOccurredAt);
+          const correlation = (0, _interactionProtocol.correlateInteraction)(interactionStartsRef.current, nativeOccurredAt);
+          const start = correlation.start;
+          /**
+           * ONE-TO-ONE. Without removing the matched start, a second native event
+           * arriving within the window claims the SAME js evidence, so one tap's
+           * target is stamped onto another tap that never had one — a duplicate
+           * identity that reads as two genuine interactions on the same control.
+           */
+          if (correlation.index >= 0) {
+            interactionStartsRef.current.splice(correlation.index, 1);
+          }
 
           // 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.
@@ -311,11 +390,62 @@ function ScaleBunDebugRoot({
             interactionId: event.interactionId || start?.interactionId || (0, _interactionProtocol.generateInteractionId)(),
             interactionProtocol: event.interactionProtocol || _interactionProtocol.INTERACTION_PROTOCOL_VERSION,
             occurredAt: nativeOccurredAt,
+            /**
+             * RN-6 — THESE FIVE FIELDS ARE THE ONLY ONES THE JOIN CARRIES, AND
+             * THEREFORE THE ONLY ONES A BAD JOIN CAN FALSIFY.
+             *
+             * Coordinates below come from native and are right regardless. So a
+             * mispairing does not produce visibly broken data: it produces heat
+             * in the correct position attributed to the wrong control, in the
+             * wrong UI state, on the wrong screen. Every field is individually
+             * well-formed and nothing downstream can tell.
+             *
+             * When the correlation is not 'exact' they are left UNDEFINED rather
+             * than filled from a best guess. An interaction with no target is
+             * honest and visibly incomplete — the accounting lane can count it as
+             * unplaceable and say why. An interaction with the WRONG target is
+             * indistinguishable from a correct one and silently corrupts every
+             * aggregate it enters. `null` is not `0`, and a guess is not a
+             * measurement.
+             */
             ui: start?.ui,
             stateStatus: start?.stateStatus ?? 'not_captured',
             target: start?.target,
             targetId: start?.targetId,
+            targetSource: start?.targetSource,
             screenName: start?.screenName,
+            screenSource: start?.screenSource ?? 'none',
+            targetRect: start?.targetRect,
+            /**
+             * RN-15 — WHERE IN THE CONTROL, computed where both halves exist: the
+             * point comes from the native event and the rect was measured at
+             * finger-down, in the same capture base. Pairing them here rather than
+             * downstream stops anything later reaching for a different rect.
+             */
+            ...(() => {
+              const lp = (0, _targetGeometry.localPoint)(start?.targetRect ?? null, event.normalizedX, event.normalizedY);
+              return lp ? {
+                localU: lp.u,
+                localV: lp.v
+              } : {};
+            })(),
+            scrollX: start?.scrollX,
+            scrollY: start?.scrollY,
+            scrollSource: start?.scrollSource ?? 'none',
+            itemKey: start?.itemKey,
+            itemIndex: start?.itemIndex,
+            /**
+             * The join's own verdict, shipped with the row so it is auditable
+             * rather than a claim made in a comment. 'ambiguous' and 'none' are
+             * deliberately distinguished: 'none' means the JS handler never fired
+             * (a real capture gap on this platform), 'ambiguous' means it fired
+             * more than once too close together to attribute. Those have
+             * different fixes, and collapsing them would hide which one is
+             * actually happening in production.
+             */
+            correlation: correlation.outcome,
+            correlationDeltaMs: correlation.deltaMs,
+            correlationRunnerUpDeltaMs: correlation.runnerUpDeltaMs,
             emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
             x: event.rawX,
             y: event.rawY,
@@ -398,6 +528,16 @@ function ScaleBunDebugRoot({
       const target = (0, _touchTarget.resolveTouchTarget)(e);
       let ui;
       let screenName;
+      /**
+       * RN-8 — WHERE the screen name came from, carried with the interaction.
+       *
+       * Production shows 13.8% of Android interactions with a screen and 0.5% on iOS, and
+       * those figures cannot distinguish three unrelated causes: nothing was instrumented,
+       * a manual beacon was instrumented but never reached interactions, or auto-detection
+       * ran and failed. Each has a different owner. Recording the source turns one
+       * unactionable percentage into three answerable ones.
+       */
+      let screenSource = 'none';
       try {
         const {
           uiStateSignature
@@ -408,7 +548,12 @@ function ScaleBunDebugRoot({
         const {
           AutoScreenDetector
         } = require('../navigation/AutoScreenDetector');
-        screenName = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+        const detector = AutoScreenDetector.getInstance();
+        screenName = detector.getCurrentScreen() || undefined;
+        /* Read from the SAME call site as the name, so the two can never describe
+           different moments — the detector is polled and its answer can change between
+           two reads a few milliseconds apart. */
+        screenSource = screenName ? detector.getCurrentScreenSource() : 'none';
       } catch {/* no-throw */}
       const start = {
         interactionId: (0, _interactionProtocol.generateInteractionId)(),
@@ -417,9 +562,93 @@ function ScaleBunDebugRoot({
         y: touch.pageY,
         locationX: touch.locationX,
         locationY: touch.locationY,
+        /**
+         * RN-1 + RN-2 — the identity that is persisted, and it is now code-derived.
+         *
+         * `describeTouchTarget` returns `testID` -> structural path -> component name,
+         * and never a caption or an accessibilityLabel. Before RN-2 it preferred free
+         * text, so this line was writing user data ("Pay EGP 1,442", an order row
+         * labelled with an email address, a contact's name) into the analytics store —
+         * and, because `target` is an aggregation key, splitting one button into one
+         * bucket per person at the same time.
+         *
+         * `targetId` used to be `target?.testID` alone, which is `undefined` in the
+         * overwhelming majority of apps — no testIDs authored — so the field the
+         * backend keys on was empty almost always. It now falls back to the structural
+         * path, with `targetSource` recording WHICH it got.
+         */
         target: (0, _touchTarget.describeTouchTarget)(target),
-        targetId: target?.testID,
+        targetId: (0, _touchTarget.targetIdentity)(target).id,
+        /**
+         * WHICH KIND of identity this is, because they are not equally trustworthy: a
+         * `testID` is a promise from the app's authors that this control is this
+         * control; a `path` is an inference that breaks when the tree is refactored.
+         * Without this the accounting lane cannot distinguish "the control had no
+         * identity" from "the identity is a structural guess", and both would render
+         * as an equally confident target.
+         */
+        targetSource: (0, _touchTarget.targetIdentity)(target).source,
+        /* RN-4 — row identity from the app's own keyExtractor; see touchTarget.ts. */
+        itemKey: target?.itemKey,
+        itemIndex: target?.itemIndex,
+        /**
+         * RN-13 — the control's rectangle, so `heat ∈ target` is decidable.
+         *
+         * Read SYNCHRONOUSLY here, in the same tick as the touch, and normalized against
+         * the SAME measured root the tap's own coordinates use. Both halves matter:
+         *
+         *   - A callback measurement (`measureInWindow`) would resolve after this handler
+         *     returns, so the rect attached to a tap could be the previous tap's, with
+         *     nothing afterwards able to tell. `targetGeometry` refuses to guess: it reads
+         *     now or reports null.
+         *   - Normalizing against a window size instead of the root view is off by the
+         *     status bar on most devices, which would read as "the heat is just outside
+         *     the button" everywhere rather than as a measurement bug.
+         *
+         * `measureRoot()` is called first because the cached root rect is populated
+         * asynchronously at mount; without it the first taps of a session normalize
+         * against nothing and get a null rect for a reason that has nothing to do with
+         * the control.
+         */
+        /**
+         * RN-3 — WHERE IN THE CONTENT, not just where on the glass.
+         *
+         * Two taps at the same screen coordinate one viewport apart are two different
+         * controls. Without an offset they merge into one hotspot, and the heatmap shows
+         * heavy engagement at a position where, in content terms, nothing in particular
+         * is. The offset is also a CACHE dimension — two scroll states of one route must
+         * not share a backdrop — so its absence corrupts the picture as well as the count.
+         *
+         * `ancestors` is innermost-first, so this takes the NEAREST scroller that has a
+         * recorded position: a tap inside a horizontal carousel belongs to the carousel's
+         * content, not to how far the page behind it had scrolled.
+         *
+         * Null when no ancestor has one — never zero. Zero is a real scroll position (the
+         * top of a list), and reporting it for "unknown" would place every unmeasured tap
+         * at the top of its content, indistinguishable from a genuine tap there.
+         */
+        ...(() => {
+          const hit = (0, _scrollContext.nearestRecordedOffset)((target?.ancestors ?? []).map(n => (0, _scrollContext.nativeTagOf)(n)));
+          return hit ? {
+            scrollX: hit.x,
+            scrollY: hit.y,
+            scrollSource: 'wrapper'
+          } : {
+            scrollSource: 'none'
+          };
+        })(),
+        targetRect: (() => {
+          measureRoot();
+          const root = rootRectRef.current;
+          /* null -> undefined: the context field is optional, and an explicit null would
+             serialise as a JSON null claiming "measured, and it was nothing". */
+          return (0, _targetGeometry.normalizeRect)((0, _targetGeometry.readRectSync)(target?.node), root ? {
+            w: root.w,
+            h: root.h
+          } : null) ?? undefined;
+        })(),
         screenName,
+        screenSource,
         ui,
         stateStatus: ui ? 'captured_nonempty' : 'not_instrumented',
         emitAutomaticAnalytics: captureAutomaticInteractions
@@ -464,7 +693,21 @@ 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 = start?.target ?? (0, _touchTarget.describeTouchTarget)((0, _touchTarget.resolveTouchTarget)(e));
+      /**
+       * Resolved ONCE, so `target` and `targetId` cannot disagree about the same tap.
+       *
+       * The previous shape called `resolveTouchTarget(e)` inline for `target` while
+       * `targetId` came only from `start` — so on the fallback path (no JS start, or a
+       * refused correlation) the tap carried a description with NO id, and the two fields
+       * were computed from different sources. Anything joining on `targetId` therefore
+       * saw nothing for a tap that visibly had a target.
+       */
+      const freshTarget = start ? null : (0, _touchTarget.resolveTouchTarget)(e);
+      const tapped = start?.target ?? (0, _touchTarget.describeTouchTarget)(freshTarget);
+      const identity = start ? {
+        id: start.targetId,
+        source: start.targetSource
+      } : (0, _touchTarget.targetIdentity)(freshTarget);
       const gestureDetails = {
         target: tapped,
         interactionId: start?.interactionId ?? (0, _interactionProtocol.generateInteractionId)(),
@@ -472,8 +715,16 @@ function ScaleBunDebugRoot({
         occurredAt: start?.occurredAt ?? Date.now(),
         ui: start?.ui,
         stateStatus: start?.stateStatus ?? 'not_captured',
-        targetId: start?.targetId,
+        targetId: identity.id,
+        targetSource: identity.source,
         screenName: start?.screenName,
+        screenSource: start?.screenSource ?? 'none',
+        targetRect: start?.targetRect,
+        scrollX: start?.scrollX,
+        scrollY: start?.scrollY,
+        scrollSource: start?.scrollSource ?? 'none',
+        itemKey: start?.itemKey,
+        itemIndex: start?.itemIndex,
         emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
         x: start?.x ?? touch.pageX,
         y: start?.y ?? touch.pageY,
@@ -496,6 +747,19 @@ function ScaleBunDebugRoot({
         const ny = Math.max(0, Math.min(1, (start?.y ?? touch.pageY) / rootRect.h));
         gestureDetails.normalizedX = nx;
         gestureDetails.normalizedY = ny;
+        /**
+         * RN-15 on the JS-fallback lane.
+         *
+         * Computed here rather than in the literal above because that is where nx/ny first
+         * exist. The rect is the SAME one the native lane uses, so one physical tap yields
+         * the same local position whichever lane captured it — two lanes disagreeing about
+         * where in a control a tap landed would be worse than neither reporting it.
+         */
+        const lp = (0, _targetGeometry.localPoint)(start?.targetRect ?? null, nx, ny);
+        if (lp) {
+          gestureDetails.localU = lp.u;
+          gestureDetails.localV = lp.v;
+        }
         gestureDetails.normalizedPrecomputed = true;
         gestureDetails.viewportWidth = rootRect.w;
         gestureDetails.viewportHeight = rootRect.h;
@@ -679,6 +943,30 @@ function useScaleBunScreen(name) {
       }
     } catch {/* no-throw */}
 
+    /**
+     * RN-8 — TELL THE DETECTOR TOO, because interactions read their screen from IT.
+     *
+     * This hook fed SessionManager, PerformanceFeature, ProfilerFeature and JourneyManager
+     * — four consumers — and never `AutoScreenDetector`. But `handleTouchStart` resolves an
+     * interaction's `screenName` from `AutoScreenDetector.getCurrentScreen()`, so a
+     * manually-instrumented app produced perfectly-named SCREEN_VIEW events while every TAP
+     * carried no screen at all. `setManualScreen` existed and was called only by tests.
+     *
+     * That is the whole story for apps the auto-hook cannot help: expo-router, a custom
+     * navigator, anything not `@react-navigation/native`. The documented manual escape hatch
+     * did not reach the one field that partitions every heatmap.
+     *
+     * Requires the last-writer-wins fix in `_currentScreen()` to be useful: under the
+     * previous rule a manual screen was readable for only 2000 ms, so wiring this alone
+     * would have handed interactions a name that expired before most taps happened.
+     */
+    try {
+      const {
+        AutoScreenDetector
+      } = require('../navigation/AutoScreenDetector');
+      AutoScreenDetector.getInstance().setManualScreen(name);
+    } catch {/* no-throw */}
+
     // Feed PerformanceFeature (screen context for perf metrics)
     // NOTE: Only sets screen identity. Does NOT call markScreenLoadStart/End.
     // AutoScreenLoadCollector handles timing independently via rAF + InteractionManager.

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

@@ -59,6 +59,34 @@ const ScaleBunScrollView = exports.ScaleBunScrollView = /*#__PURE__*/_react.defa
       }
     } catch {/* no-throw */}
 
+    /**
+     * RN-3 — record WHERE THIS scroller sits, keyed by its own native tag, so a later
+     * tap can say which content was under the finger.
+     *
+     * OUTSIDE the `isActive` guard above, deliberately. That guard is correct for the
+     * gesture tracker, which produces scroll EVENTS and should only do so while
+     * recording. This is a different thing: it is the position a tap needs in order to
+     * be placed in content rather than on glass, and a tap is captured on the always-on
+     * analytics lane even when no recording is active. Gating this the same way would
+     * make content depth absent in exactly the sessions the heatmap is built from.
+     *
+     * The tag is taken from the EVENT's target rather than from this component's ref,
+     * so it identifies the scroller that actually moved. With nested scrollers the
+     * event may come from an inner one, and keying by the wrapper would file the
+     * carousel's offset under the list.
+     */
+    try {
+      const {
+        recordScrollOffset,
+        nativeTagOf
+      } = require('./scrollContext');
+      const {
+        contentOffset,
+        target
+      } = event.nativeEvent;
+      recordScrollOffset(typeof target === 'number' ? target : nativeTagOf(target), contentOffset.x, contentOffset.y);
+    } catch {/* no-throw */}
+
     // Forward to user's onScroll handler
     if (userOnScroll) {
       userOnScroll(event);