@scalebun/react-native 1.13.0 → 2.0.1

package/lib/typescript/specs/NativeScaleBunOta.d.ts

@@ -22,6 +22,16 @@ export interface Spec extends TurboModule {
      * the bundle URL at launch.
      */
     getActiveBundle(): string | null;
+    /**
+     * JSON array (string) of the trusted key IDs embedded in the app package, e.g.
+     * `["production-2026-01"]`. Reported on OTA check-in for SDK trust coverage
+     * (CICDPAGE §12) so the dashboard can measure key-rotation adoption. This is
+     * telemetry ONLY — the server never trusts a key because a device claims it.
+     * Empty array when no keys are embedded.
+     */
+    getTrustedKeyIds(): string;
+    /** JSON array of root/jailbreak indicator strings; [] when none found. */
+    getDeviceIntegrity(): string;
     /**
      * Returns JSON with current slot state:
      * { current: { bundleId, version, sha256, installedAt } | null,
@@ -77,28 +87,30 @@ export interface Spec extends TurboModule {
      */
     restartApp(): void;
     /**
-     * Verify a detached ed25519 signature in NATIVE code.
-     *
-     * Exists because the JS verifier runs inside the very bundle it protects —
-     * an attacker who lands one malicious bundle can neuter a JS check for every
-     * update after it. Platform crypto is outside the bundle's reach, and it also
-     * removes the runtime dependency on the optional @noble peers wherever the OS
-     * provides ed25519 (iOS 13+ CryptoKit everywhere; Android API 33+).
+     * Verify a SB-OTA-RSA-SHA256-V1 release envelope in NATIVE code, with no side
+     * effects. `envelopeJson` is the JSON `{ protocol, keyId, signedPayload,
+     * signature, downloadUrl? }` from the check response. Verification uses the
+     * trusted RSA public keys EMBEDDED in the app package (never a key from JS or
+     * the server) and platform `SHA256withRSA` (present on every supported API
+     * level — no API-33 floor).
      *
-     * All three arguments are lowercase hex, pre-validated by the JS caller:
-     * the 32-byte bundle SHA-256 (the signature is over its RAW BYTES, matching
-     * the CLI's signing contract), the 64-byte signature, the 32-byte public key.
-     *
-     * Resolves a verdict STRING, not a boolean, because "the signature is wrong"
-     * and "this OS cannot check" must never collapse into one value:
-     *   'valid'       — signature verifies under the key
-     *   'invalid'     — it does not; the caller must refuse the bundle
-     *   'unavailable' — this OS level has no ed25519 (Android < 33); the caller
-     *                   falls back to the JS verifier
-     * A rejected promise is machinery failure and the caller treats it as
-     * 'unavailable' — never as 'valid'.
+     * Resolves a verdict JSON string: `{ ok: boolean, code?: string, message?,
+     * keyId?, releaseId?, bundleId?, releaseSequence?, artifactSha256?,
+     * artifactSize?, resultArtifactSha256?, fingerprint? }`. A failed check is
+     * `ok:false` with a stable `code`; a rejected promise is machinery failure and
+     * the caller must treat it as a failure, never as valid.
+     */
+    verifyRelease(envelopeJson: string): Promise<string>;
+    /**
+     * Native-ENFORCED install: verify the RSA signature (as `verifyRelease`), then
+     * download the artifact, enforce the SIGNED size + SHA-256, and stage it into
+     * the `next` slot — all natively. JavaScript cannot stage bytes that were not
+     * proven authentic (once trusted keys are embedded, the legacy `stageBundle`
+     * path refuses). Does not activate; call `applyUpdate` to promote per the
+     * install mode. Resolves the same verdict JSON as `verifyRelease` (`ok:true`
+     * once staged).
      */
-    verifyEd25519(messageHex: string, signatureHex: string, publicKeyHex: string): Promise<string>;
+    verifyAndStageRelease(envelopeJson: string): Promise<string>;
 }
 /**
  * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.13.0",
+  "version": "2.0.1",
   "description": "React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -70,8 +70,6 @@
   },
   "devDependencies": {
     "@babel/preset-env": "^8.0.2",
-    "@noble/ed25519": "^3.1.0",
-    "@noble/hashes": "^2.3.0",
     "@react-native-community/eslint-config": "^3.2.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^25.3.3",
@@ -96,9 +94,7 @@
     "expo-router": ">=1.0.0",
     "react": ">=18.0.0",
     "react-native": ">=0.74.0",
-    "react-native-view-shot": ">=3.0.0",
-    "@noble/ed25519": ">=2.0.0",
-    "@noble/hashes": ">=2.0.0"
+    "react-native-view-shot": ">=3.0.0"
   },
   "peerDependenciesMeta": {
     "react-native-view-shot": {
@@ -109,19 +105,13 @@
     },
     "expo-router": {
       "optional": true
-    },
-    "@noble/ed25519": {
-      "optional": true
-    },
-    "@noble/hashes": {
-      "optional": true
     }
   },
   "dependencies": {
     "@babel/runtime": "^7.25.0",
     "@jridgewell/sourcemap-codec": "1.5.5",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@scalebun/cli": "^1.13.0"
+    "@scalebun/cli": "^2.0.1"
   },
   "codegenConfig": {
     "name": "ScaleBunSpec",

package/scalebun-react-native.podspec

@@ -13,6 +13,10 @@ Pod::Spec.new do |s|
   # Include .mm (ObjC++) for the New Architecture TurboModule providers added in
   # Phase 2, alongside the existing .h/.m/.swift sources.
   s.source_files = "ios/**/*.{h,m,mm,swift}"
+  # XCTest files ship with the SDK source but must NOT compile into the pod (they
+  # import XCTest and belong in a host app's test target). See the run
+  # instructions in ScaleBunOtaVerifierTests.swift (PROMPT §23).
+  s.exclude_files = "ios/**/*Tests.swift"
 
   # Define a clang module so the generated Swift interop header
   # (`scalebun_react_native-Swift.h`) is emitted and importable from a host

package/src/bootstrap/SDKBootstrapper.ts

@@ -91,6 +91,24 @@ export 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 as any)?.apiBaseUrl;
+        if (
+          typeof requestedApiBaseUrl === 'string' &&
+          requestedApiBaseUrl &&
+          requestedApiBaseUrl !== DEFAULT_API_BASE_URL
+        ) {
+          logger.warn(
+            `[ScaleBun] Ignoring apiBaseUrl '${requestedApiBaseUrl}' — the endpoint is ` +
+              `locked at build time and this build targets ${DEFAULT_API_BASE_URL}. To ` +
+              `target another backend, change DEFAULT_API_BASE_URL in the SDK source and ` +
+              `rebuild.`,
+          );
+        }
         this.config.apiBaseUrl = DEFAULT_API_BASE_URL;
         // Explicit logLevel wins; otherwise debug:true implies verbose 'debug'.
         if (this.config.logLevel) {
@@ -340,6 +358,28 @@ export 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) {
+                    logger.warn(
+                        '[Bootstrap] autoInstrumentScrollViews was requested but could not be ' +
+                            'installed: ' + outcome.reason + ' — taps will carry no content depth.',
+                    );
+                } else {
+                    __DEV__ && logger.debug('[Bootstrap] ScrollView auto-instrumentation installed');
+                }
+            } catch { /* no-throw */ }
+        }
         if (features.replay !== false) {
             try {
                 __DEV__ && logger.debug('[Bootstrap] Initializing unified SessionManager');

package/src/core/config/schema.ts

@@ -188,6 +188,22 @@ const SHAPE: Record<string, Field> = {
         },
     },
     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
@@ -201,12 +217,9 @@ const SHAPE: Record<string, Field> = {
             enabled: bool(false),
             checkOnForeground: bool(true),
             channelOverride: { kind: 'str', opt: true },
-            publicSigningKey: { kind: 'str', opt: true },
-            // Rotation support: several pinned keys, any of which may verify a
-            // bundle. Ship a build pinning [old, new], re-sign server-side with
-            // new, drop old next release — no emergency store submission when a
-            // key must be replaced. Merged with publicSigningKey by the facade.
-            publicSigningKeys: { kind: 'strArr', opt: true },
+            // No signing-key fields: signed releases are verified natively against
+            // RSA keys embedded in the app package (SB-OTA-RSA-SHA256-V1). JS must
+            // not supply a trusted key.
             mandatoryBlocksUi: bool(false),
         },
     },
@@ -399,15 +412,14 @@ export interface ScaleBunConfig {
         redactBodies?: boolean;
     };
     captureInteractionHeatmap: boolean;
+    /** RN-3 zero-config scroll instrumentation. OFF by default — it changes what the HOST renders. */
+    autoInstrumentScrollViews: boolean;
     /** Opt-in: capture console.* into the Logs lane in SaaS mode. Default false. */
     captureConsoleLogs: boolean;
     ota?: {
         enabled: boolean;
         checkOnForeground: boolean;
         channelOverride?: string;
-        publicSigningKey?: string;
-        /** Additional pinned keys for rotation; unioned with publicSigningKey. */
-        publicSigningKeys?: string[];
         mandatoryBlocksUi: boolean;
     };
 }

package/src/core/constants/version.ts

@@ -8,4 +8,4 @@
  * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
  * version was introduced to solve.
  */
-export const SDK_VERSION = '1.13.0';
+export const SDK_VERSION = '2.0.1';

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -28,12 +28,15 @@ import React, {
     type ReactNode,
 } from 'react';
 import { View, NativeEventEmitter, NativeModules } from 'react-native';
-import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
+import { resolveTouchTarget, describeTouchTarget, targetIdentity } from './touchTarget';
+import { localPoint, normalizeRect, readRectSync, type NormalizedRect } from './targetGeometry';
+import { nativeTagOf, nearestRecordedOffset } from './scrollContext';
 import { resolvePlatformOS } from '../../core/context/device';
 import {
     INTERACTION_PROTOCOL_VERSION,
     generateInteractionId,
-    nearestInteractionStart,
+    correlateInteraction,
+    pruneInteractionStarts,
     type InteractionStartContext,
 } from './interactionProtocol';
 
@@ -53,6 +56,15 @@ function getBootstrap() {
 
 const JourneyContext = createContext<any>(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 ───────────────────────────────────────────────────────────
 
 interface ScaleBunDebugRootProps {
@@ -275,6 +287,50 @@ export 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.
+     */
+    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 as any).captureManualFrame === 'function') {
+                    /* Fire and forget: the tap that follows must not wait on a screenshot. */
+                    void (sm as any).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.
@@ -301,7 +357,30 @@ export function ScaleBunDebugRoot({
                             ? event.occurredAt
                             : (typeof event.timestamp === 'number' ? event.timestamp : Date.now()) -
                               (typeof event.durationMs === 'number' ? event.durationMs : 0);
-                    const start = 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.
+                     */
+                    pruneInteractionStarts(interactionStartsRef.current, nativeOccurredAt);
+                    const correlation = 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.
@@ -330,11 +409,63 @@ export function ScaleBunDebugRoot({
                         interactionId: event.interactionId || start?.interactionId || generateInteractionId(),
                         interactionProtocol: event.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 = 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,
@@ -411,13 +542,28 @@ export function ScaleBunDebugRoot({
             const target = resolveTouchTarget(e);
             let ui: string | undefined;
             let screenName: string | undefined;
+            /**
+             * 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: 'manual' | 'navigation' | 'none' = 'none';
             try {
                 const { uiStateSignature } = require('./uiState');
                 ui = uiStateSignature();
             } catch { /* no-throw */ }
             try {
                 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: TouchStartContext = {
                 interactionId: generateInteractionId(),
@@ -426,9 +572,88 @@ export 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: describeTouchTarget(target),
-                targetId: target?.testID,
+                targetId: 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: 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 = nearestRecordedOffset(
+                        (target?.ancestors ?? []).map((n) => nativeTagOf(n)),
+                    );
+                    return hit
+                        ? { scrollX: hit.x, scrollY: hit.y, scrollSource: 'wrapper' as const }
+                        : { scrollSource: 'none' as const };
+                })(),
+                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 normalizeRect(readRectSync(target?.node), root ? { w: root.w, h: root.h } : null) ?? undefined;
+                })(),
                 screenName,
+                screenSource,
                 ui,
                 stateStatus: ui ? 'captured_nonempty' : 'not_instrumented',
                 emitAutomaticAnalytics: captureAutomaticInteractions,
@@ -473,7 +698,20 @@ export function ScaleBunDebugRoot({
             // WHAT was tapped, resolved from the React fiber on the touch event. Without this the tap
             // carries only coordinates, so every tap in the app groups into one row per gesture type.
             // Defensive by construction — returns undefined rather than throwing (see touchTarget.ts).
-            const tapped = start?.target ?? describeTouchTarget(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 : resolveTouchTarget(e);
+            const tapped = start?.target ?? describeTouchTarget(freshTarget);
+            const identity = start
+                ? { id: start.targetId, source: start.targetSource }
+                : targetIdentity(freshTarget);
 
             const gestureDetails: any = {
                 target: tapped,
@@ -482,8 +720,16 @@ export 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,
@@ -506,6 +752,19 @@ export 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 = 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;
@@ -695,6 +954,28 @@ export function useScaleBunScreen(name: string): void {
             }
         } 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.