@scalebun/react-native 1.13.0 → 2.0.1

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

@@ -12,7 +12,6 @@ var _OtaEventEmitter = require("./OtaEventEmitter");
 var _geoCountry = require("./geoCountry");
 var _deviceAttributes = require("./deviceAttributes");
 var _installationId = require("../../core/id/installationId");
-var _signature = require("./signature");
 var _environment = require("./environment");
 var _retry = require("./retry");
 var _StorageBackend = require("../../storage/StorageBackend");
@@ -120,12 +119,12 @@ async function deliverOtaEvents(params) {
       })
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    __DEV__ && _internalLogger.logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
+    _internalLogger.logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
   } catch (err) {
     // Failed delivery must not fail the update — but the events must not be
     // lost either: requeue so the next sync retries them.
     for (const e of events) _OtaEventEmitter.otaEventEmitter.emit(e);
-    __DEV__ && _internalLogger.logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
+    _internalLogger.logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
   }
 }
 
@@ -145,6 +144,8 @@ class OtaOrchestrator {
     return this.currentBundle;
   }
   isRestartRequiredState = false;
+  /** Root/jailbreak indicators observed at init; empty when none found. */
+  integrityIndicators = [];
   healthyTimer = null;
   bootGuardConfig = {};
   environment = null;
@@ -155,9 +156,10 @@ class OtaOrchestrator {
   /**
    * Initialize the orchestrator. Checks for boot-guard recovery state.
    *
-   * `signature` is optional: an app that has not adopted signing keeps working
-   * on SHA-256 integrity alone. Once a public key IS configured, a bundle that
-   * cannot be verified is refused rather than installed (OTA-03).
+   * Signature enforcement is no longer a JS concern: signed releases are
+   * verified and staged in NATIVE code against RSA keys embedded in the app
+   * package (SB-OTA-RSA-SHA256-V1), and unsigned releases keep working on
+   * SHA-256 integrity alone. There is nothing for the host to configure here.
    */
   init(config) {
     (0, _crashSafe.noThrow)(() => {
@@ -170,7 +172,6 @@ class OtaOrchestrator {
       // them. Config is still refreshed so late signature setup works.
       if (this.initialized) {
         this.bootGuardConfig = config ?? this.bootGuardConfig;
-        this.signatureConfig = config?.signature ?? this.signatureConfig;
         return;
       }
       if (!_NativeScaleBunOta.default) {
@@ -200,13 +201,30 @@ class OtaOrchestrator {
         // We cannot see which form the host used — the identity check after
         // restart is what proves it — but naming the right fix up front turns
         // a confusing silent failure into a one-line correction.
-        __DEV__ && _internalLogger.logger.debug('[OTA] React Native >= 0.82 detected. The only valid Android integration is ' + 'getDefaultReactHost(..., jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(ctx)) — ' + 'ReactNativeHost and its getJSBundleFile() override no longer exist.');
+        _internalLogger.logger.debug('[OTA] React Native >= 0.82 detected. The only valid Android integration is ' + 'getDefaultReactHost(..., jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(ctx)) — ' + 'ReactNativeHost and its getJSBundleFile() override no longer exist.');
       }
       this.initialized = true;
       this.enabled = true;
+
+      // Device integrity signal.
+      //
+      // Reported, not enforced. Root defeats any check made from inside the app,
+      // so this is not a boundary — it is context. It tells an operator that a
+      // device's OTA slot is writable by other processes, which is what makes the
+      // launch-time hash re-check in SlotManager meaningful rather than paranoid.
+      // A host app that wants to withhold updates on such devices can read
+      // `deviceIntegrityIndicators()` and decide for itself.
+      try {
+        const raw = _NativeScaleBunOta.default?.getDeviceIntegrity?.();
+        this.integrityIndicators = raw ? JSON.parse(raw) : [];
+        if (this.integrityIndicators.length > 0) {
+          _internalLogger.logger.warn(`[OTA] Device integrity indicators present: ${this.integrityIndicators.join(', ')}. ` + 'Updates still install and are still signature-verified, but an installed ' + 'bundle on this device can be modified by other privileged processes.');
+        }
+      } catch {
+        this.integrityIndicators = [];
+      }
       this.bootGuardConfig = config ?? {};
-      this.signatureConfig = config?.signature;
-      __DEV__ && _internalLogger.logger.debug(`[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` + `${this.environment.bridgeless ? ', bridgeless' : ''}` + `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`);
+      _internalLogger.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.
       //
@@ -237,6 +255,22 @@ class OtaOrchestrator {
 
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
+
+      // Boot-guard health is a LOCAL fact: this process booted from the staged
+      // bundle and did not crash. The heartbeat used to start only on the
+      // `action === 'NONE'` branch of sync(), so confirming a good bundle needed
+      // a successful network round-trip that returned exactly that answer — a
+      // device offline, rate-limited, or still being offered an update could
+      // never clear its marker, and the guard reverted a bundle that was working.
+      //
+      // It runs HERE, last, and is handed the slot state that was already read.
+      // Starting it earlier made it call getSlotState() itself, and that read is
+      // consume-on-read for the revert record — it swallowed the revert before
+      // checkBootGuardRecovery() could name the bundle that failed, so a
+      // crash-rollback went unreported. It also read bootGuardConfig before
+      // init() had assigned it, so healthyAfterMs silently fell back to the
+      // default.
+      this.startBootGuardHeartbeat(slotState);
     });
   }
 
@@ -275,7 +309,7 @@ class OtaOrchestrator {
           releaseId: record.releaseId ?? undefined,
           sha256: record.sha256
         };
-        __DEV__ && _internalLogger.logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
+        _internalLogger.logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
         return;
       }
 
@@ -285,7 +319,7 @@ class OtaOrchestrator {
       this.currentBundle = {
         sha256: current.sha256
       };
-      __DEV__ && _internalLogger.logger.debug(`[OTA] Running an OTA bundle (sha ${String(current.sha256).slice(0, 12)}…) with no local install record.`);
+      _internalLogger.logger.debug(`[OTA] Running an OTA bundle (sha ${String(current.sha256).slice(0, 12)}…) with no local install record.`);
     } catch {
       // Slot state unreadable — treat as factory bundle.
     }
@@ -333,7 +367,7 @@ class OtaOrchestrator {
     // this bundle" and answers by serving the same bundle again, forever.
     if (!record.identityToken) return;
     if (running === record.identityToken) {
-      __DEV__ && _internalLogger.logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      _internalLogger.logger.debug('[OTA] Install verified — running bundle matches what was installed.');
       this.retireIdentityToken(record);
       return;
     }
@@ -466,6 +500,14 @@ class OtaOrchestrator {
   isEnabled() {
     return this.enabled;
   }
+
+  /**
+   * Root/jailbreak indicators detected on this device, as stable reason strings.
+   * Empty means nothing was detected — not proof the device is clean.
+   */
+  deviceIntegrityIndicators() {
+    return [...this.integrityIndicators];
+  }
   isRestartRequired() {
     return this.isRestartRequiredState;
   }
@@ -485,12 +527,27 @@ class OtaOrchestrator {
       // OTA has no bundle for a non-mobile target; claiming Android there would install the wrong one.
       const mobileOS = (0, _device.resolveMobileOS)();
       if (!mobileOS) throw new Error('OTA is not supported on this platform');
+      // SDK trust coverage (CICDPAGE §12): report which trusted key IDs are
+      // embedded in this binary so the dashboard can measure key-rotation
+      // adoption. Telemetry only — the server never trusts a key a device claims.
+      // Defensive: optional native method, never let it break a check.
+      let trustedKeyIds;
+      try {
+        const raw = _NativeScaleBunOta.default?.getTrustedKeyIds?.();
+        if (raw) {
+          const arr = JSON.parse(raw);
+          if (Array.isArray(arr) && arr.length) trustedKeyIds = arr.slice(0, 16);
+        }
+      } catch {
+        /* trust reporting is best-effort — never break the update check */
+      }
       const payload = {
         appVersion: requestParams.appVersion,
         platform: mobileOS,
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
         currentBundleHash: this.currentBundle?.sha256,
+        trustedKeyIds,
         channelName: requestParams.channelName,
         // Host-supplied country wins; otherwise the cached edge-Worker lookup
         // fills in (see geoCountry.ts). Undefined when neither knows — the
@@ -558,7 +615,7 @@ class OtaOrchestrator {
           error: 'OTA native module disabled or missing'
         };
       }
-      __DEV__ && _internalLogger.logger.debug('[OTA] Sync started…');
+      _internalLogger.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
@@ -577,7 +634,7 @@ class OtaOrchestrator {
       }
       const checkRes = await this.checkForUpdate(params);
       if (checkRes.action === 'NONE') {
-        __DEV__ && _internalLogger.logger.debug('[OTA] App is up to date');
+        _internalLogger.logger.debug('[OTA] App is up to date');
         // If we booted from an OTA bundle and it's healthy, clear the boot guard
         this.startBootGuardHeartbeat();
         return {
@@ -624,31 +681,18 @@ class OtaOrchestrator {
         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
-      // staging would mean writing unverified code to the slot directory first.
-      const signatureOutcome = await (0, _signature.verifyBundleSignature)(bundle.sha256, bundle.signature, this.signatureConfig);
-      if (!signatureOutcome.ok) {
-        _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
-          releaseId: bundle.releaseId,
-          error: `Signature check failed: ${signatureOutcome.reason}`,
-          version: bundle.version
-        });
-        return {
-          status: 'ERROR',
-          error: `Bundle signature check failed (${signatureOutcome.reason})`,
-          bundle
-        };
-      }
-
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
+      // Authenticity is enforced NATIVELY now (see the envelope branch below):
+      // SHA-256 proves the bytes arrived intact, and for signed releases the
+      // RSA signature — checked in native code against keys embedded in the app
+      // package — proves they came from you. JS neither pins keys nor verifies
+      // signatures.
       _OtaEventEmitter.otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
         releaseId: bundle.releaseId,
         version: bundle.version
       });
       const downloadStart = Date.now();
-      __DEV__ && _internalLogger.logger.debug(`[OTA] Downloading update v${bundle.version}…`);
+      _internalLogger.logger.debug(`[OTA] Downloading update v${bundle.version}…`);
 
       // Live progress: native tick → DOWNLOAD_PROGRESS (feeds useOtaUpdate) →
       // throttled POST to the live tracker. `bundle.size` is the authoritative
@@ -696,46 +740,94 @@ class OtaOrchestrator {
         }
       });
       let staged = false;
-
-      // Sprint 7: Try patch first if offered, fall back to full bundle
-      if (bundle.patch && _NativeScaleBunOta.default.stagePatch) {
-        __DEV__ && _internalLogger.logger.debug(`[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` + `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`);
+      if (bundle.envelope) {
+        // ── NATIVE-ENFORCED VERIFY + STAGE (SB-OTA-RSA-SHA256-V1) ───────────
+        // Hand the whole envelope to native code, which verifies the RSA
+        // signature against the keys EMBEDDED in the app package, then downloads
+        // the artifact, enforces the SIGNED size + SHA-256, and stages it into
+        // the `next` slot — all outside JS. JavaScript never stages bytes it has
+        // not proven authentic. No patch path here: a signed offer is always a
+        // full verified download (native patch is a documented follow-up).
+        const envelopeJson = JSON.stringify({
+          ...bundle.envelope,
+          downloadUrl: bundle.url
+        });
+        let verdict;
         try {
-          staged = await _NativeScaleBunOta.default.stagePatch(bundle.patch.url, bundle.patch.sha256, bundle.sha256 // expected full-bundle hash after patching
-          );
-          if (staged) {
-            patchUsed = true;
-            __DEV__ && _internalLogger.logger.debug('[OTA] Patch applied successfully');
-          } else {
-            _internalLogger.logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
-          }
-        } catch (patchErr) {
-          _internalLogger.logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
+          const verdictJson = await _NativeScaleBunOta.default.verifyAndStageRelease(envelopeJson);
+          verdict = JSON.parse(verdictJson);
+        } catch (err) {
+          // A rejected promise (or an unparseable verdict) is machinery failure,
+          // never a valid result — treat it as a hard failure.
+          verdict = {
+            ok: false,
+            code: 'verify_stage_threw',
+            message: err?.message ?? String(err)
+          };
         }
-      }
+        if (!verdict.ok) {
+          unsubscribeProgress();
+          postProgress(0, 'FAILED');
+          _internalLogger.logger.error(`[OTA] Native verify/stage refused the release: ${verdict.code ?? 'unknown'}` + `${verdict.message ? ` — ${verdict.message}` : ''}`);
+          _OtaEventEmitter.otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+            releaseId: bundle.releaseId,
+            // `error` is mapped onto the wire `errorCode` by deliverOtaEvents —
+            // carry the stable native verdict code there.
+            error: verdict.code ?? 'verify_and_stage_release_failed',
+            version: bundle.version
+          });
+          return {
+            status: 'ERROR',
+            error: `Release verification failed (${verdict.code ?? 'unknown'})`,
+            bundle
+          };
+        }
+        staged = true;
+      } else {
+        // ── LEGACY / UNSIGNED (SHA-256 integrity only) ─────────────────────
+        // No envelope means the app embeds no trusted keys and the release is
+        // unsigned: keep the pre-RSA behaviour so those apps still update.
 
-      // Full-bundle fallback (or primary path when no patch is available).
-      // Retried with backoff: on a mobile network a transient drop mid-download
-      // is the common case, and previously one failure meant waiting for the
-      // next cold start — often hours away, sometimes never.
-      if (!staged) {
-        try {
-          staged = await (0, _retry.retryWithBackoff)(async () => {
-            const ok = await _NativeScaleBunOta.default.stageBundle(bundle.url, bundle.sha256);
-            if (!ok) {
-              // Native returns a bare boolean, so a hash mismatch and a
-              // dropped connection are indistinguishable here. Retrying a
-              // genuine mismatch a couple of times is cheap; not retrying a
-              // dropped connection costs the whole update.
-              throw new Error('stageBundle returned false');
+        // Sprint 7: Try patch first if offered, fall back to full bundle
+        if (bundle.patch && _NativeScaleBunOta.default.stagePatch) {
+          _internalLogger.logger.debug(`[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` + `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`);
+          try {
+            staged = await _NativeScaleBunOta.default.stagePatch(bundle.patch.url, bundle.patch.sha256, bundle.sha256 // expected full-bundle hash after patching
+            );
+            if (staged) {
+              patchUsed = true;
+              _internalLogger.logger.debug('[OTA] Patch applied successfully');
+            } else {
+              _internalLogger.logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
             }
-            return ok;
-          }, {
-            label: `download v${bundle.version}`,
-            attempts: 3
-          });
-        } catch {
-          staged = false;
+          } catch (patchErr) {
+            _internalLogger.logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
+          }
+        }
+
+        // Full-bundle fallback (or primary path when no patch is available).
+        // Retried with backoff: on a mobile network a transient drop mid-download
+        // is the common case, and previously one failure meant waiting for the
+        // next cold start — often hours away, sometimes never.
+        if (!staged) {
+          try {
+            staged = await (0, _retry.retryWithBackoff)(async () => {
+              const ok = await _NativeScaleBunOta.default.stageBundle(bundle.url, bundle.sha256);
+              if (!ok) {
+                // Native returns a bare boolean, so a hash mismatch and a
+                // dropped connection are indistinguishable here. Retrying a
+                // genuine mismatch a couple of times is cheap; not retrying a
+                // dropped connection costs the whole update.
+                throw new Error('stageBundle returned false');
+              }
+              return ok;
+            }, {
+              label: `download v${bundle.version}`,
+              attempts: 3
+            });
+          } catch {
+            staged = false;
+          }
         }
       }
       unsubscribeProgress();
@@ -795,7 +887,7 @@ class OtaOrchestrator {
         releaseId: bundle.releaseId,
         version: bundle.version
       });
-      __DEV__ && _internalLogger.logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
+      _internalLogger.logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
       // Deliver telemetry BEFORE a restart tears the JS runtime down —
       // an INSTALLED event queued but not sent would vanish with the process.
@@ -841,7 +933,7 @@ class OtaOrchestrator {
    * native boot-guard marker. If JS crashes before the timer fires, the
    * marker stays set and native code reverts on next cold start.
    */
-  startBootGuardHeartbeat() {
+  startBootGuardHeartbeat(preRead) {
     if (!_NativeScaleBunOta.default) return;
 
     // Cancel any existing timer
@@ -850,20 +942,23 @@ class OtaOrchestrator {
       this.healthyTimer = null;
     }
     try {
-      const stateJson = _NativeScaleBunOta.default.getSlotState();
-      const state = JSON.parse(stateJson);
+      // getSlotState() is CONSUME-ON-READ for the revert record, so a caller that
+      // has already read it passes the parsed result down rather than letting
+      // this read again and swallow a rollback. `null` is a real answer (module
+      // absent or payload unreadable) — only `undefined` means "nobody read it".
+      const state = preRead !== undefined ? preRead : JSON.parse(_NativeScaleBunOta.default.getSlotState());
 
       // Only run the heartbeat if boot-guard marker is present
       // (meaning we're running from a freshly-applied OTA bundle)
-      if (!state.bootMarkerPresent) {
+      if (!state?.bootMarkerPresent) {
         return;
       }
       const healthyMs = this.bootGuardConfig.healthyAfterMs ?? DEFAULT_HEALTHY_AFTER_MS;
-      __DEV__ && _internalLogger.logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
+      _internalLogger.logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
       this.healthyTimer = setTimeout(() => {
         (0, _crashSafe.noThrow)(() => {
           _NativeScaleBunOta.default?.markHealthy();
-          __DEV__ && _internalLogger.logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
+          _internalLogger.logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
 
           // The honest activation signal. INSTALLED is emitted optimistically,
@@ -918,11 +1013,11 @@ class OtaOrchestrator {
             /* the restart below makes cleanup moot */
           }
           this.resumeRestartArmed = false;
-          __DEV__ && _internalLogger.logger.info('[OTA] App resumed — activating the staged update now');
+          _internalLogger.logger.info('[OTA] App resumed — activating the staged update now');
           this.restart();
         }
       });
-      __DEV__ && _internalLogger.logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
+      _internalLogger.logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
     } catch {
       // AppState unavailable (tests, exotic hosts): the update still activates
       // on the next cold start, which is the documented fallback behaviour.
@@ -942,7 +1037,7 @@ class OtaOrchestrator {
    */
   restart() {
     (0, _crashSafe.noThrow)(() => {
-      __DEV__ && _internalLogger.logger.info('[OTA] Triggering app restart…');
+      _internalLogger.logger.info('[OTA] Triggering app restart…');
       if (_NativeScaleBunOta.default && typeof _NativeScaleBunOta.default.restartApp === 'function') {
         _NativeScaleBunOta.default.restartApp();
       } else if (_reactNative.DevSettings && typeof _reactNative.DevSettings.reload === 'function') {

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

@@ -959,6 +959,69 @@ class SessionManager {
       state_status: stateStatus,
       ui: details?.ui,
       target_id: details?.targetId,
+      /**
+       * RN-6 — shipped with the row so the join is auditable instead of assumed.
+       *
+       * Without it, an interaction with no `target_id` is ambiguous in the worst way:
+       * it could mean the control genuinely had no identity, or that the correlation
+       * refused and the identity exists but could not be attributed. Those are
+       * different defects with different owners, and the accounting lane cannot give
+       * an honest unplaceable REASON without knowing which.
+       *
+       * Undefined on the JS-fallback path (no native event, so nothing was joined),
+       * which is itself the correct answer there rather than a fabricated 'exact'.
+       */
+      correlation: details?.correlation,
+      correlation_delta_ms: details?.correlationDeltaMs,
+      correlation_runner_up_delta_ms: details?.correlationRunnerUpDeltaMs,
+      /**
+       * RN-1/RN-2 — stored alongside `target_id` so a reader can tell an authored
+       * identifier from a structural inference. 'path' means the app authored no testID
+       * and the identity was derived from component names, which is useful but will
+       * change under refactoring; a dashboard that presents the two identically invites
+       * someone to trust a key that is about to move.
+       */
+      target_source: details?.targetSource,
+      /**
+       * RN-8 — stored so "13.8% of interactions have a screen" becomes answerable.
+       * 'none' means the app instrumented nothing the SDK could see; 'manual' means a
+       * <ScaleBunScreen> beacon; 'navigation' means the React Navigation hook. Three
+       * different owners behind one number that today has none.
+       */
+      screen_source: details?.screenSource,
+      /**
+       * RN-13 — what makes "the heat is on this control" checkable instead of assumed.
+       * Absent when the control could not be measured synchronously, which is a fact worth
+       * storing: an unmeasurable control and a mis-placed tap are different findings.
+       */
+      target_rect: details?.targetRect,
+      /**
+       * RN-3 — the backend already reads scrollX/scrollY off the payload into the fact
+       * table's own columns (it has done since the web SDK, which sends `sx`/`sy`), so
+       * these need no migration. Mobile simply never sent them.
+       *
+       * `scroll_source` says whether an offset was available at all: 'none' means the app
+       * uses a plain <ScrollView> rather than the SDK's wrapper, which is a coverage gap in
+       * the integration and not a tap at the top of a list.
+       */
+      scrollX: details?.scrollX,
+      scrollY: details?.scrollY,
+      scroll_source: details?.scrollSource,
+      /**
+       * RN-4 — what stops a recycled native view merging two different rows into one
+       * hotspot. The key is the app's own keyExtractor output, so it is stable across
+       * scrolling and across sessions; the index is carried so a recycled slot (same index,
+       * different key) can be proven rather than inferred.
+       */
+      item_key: details?.itemKey,
+      item_index: details?.itemIndex,
+      /**
+       * RN-15 — where in the control, not just which control. Turns "they tapped Add to
+       * Cart" into "they tapped its left edge", which is what tells you whether a hit area
+       * is right. Outside 0..1 is a hitSlop tap and is kept as such.
+       */
+      local_u: details?.localU,
+      local_v: details?.localV,
       gestureType,
       x: details?.x,
       y: details?.y,