@scalebun/react-native 1.13.0 → 2.0.1

package/lib/module/public/ScaleBunFacade.js

@@ -169,7 +169,7 @@ class ScaleBunFacade {
           const realQueue = coreContainer.get('PersistentQueue');
           const buffered = this._preInitBuffer.popBatch(this._preInitBuffer.length());
           if (buffered.length > 0) {
-            __DEV__ && logger.debug(`[ScaleBun] Draining ${buffered.length} pre-init events into persistent queue`);
+            logger.debug(`[ScaleBun] Draining ${buffered.length} pre-init events into persistent queue`);
             for (const envelope of buffered) {
               realQueue.add(envelope);
             }
@@ -209,17 +209,11 @@ class ScaleBunFacade {
   /**
    * Boot the OTA orchestrator when the init config asks for it.
    *
-   * `publicSigningKey` / `publicSigningKeys` are honoured here so signature
-   * enforcement is reachable from configuration alone. The list form exists
-   * for key ROTATION: a build pinning [old, new] keeps verifying while the
-   * server moves to the new key, so replacing a key never needs an emergency
-   * store release. Both fields merge (deduplicated) into one pinned set.
-   *
-   * Verification comes from `ota.verifySignature` when supplied, else the
-   * built-in @noble-based verifier (optional peers). Pinning keys with
-   * NEITHER available is fail-CLOSED by design (signature.ts) — an update
-   * that cannot be verified is not installed. We say that out loud rather
-   * than letting the app discover it as a silent no-update condition.
+   * Signature enforcement is no longer configured from JS. Signed releases are
+   * verified and staged in NATIVE code against RSA keys embedded in the app
+   * package (SB-OTA-RSA-SHA256-V1); unsigned releases keep working on SHA-256
+   * integrity. There are no signing-key or `verifySignature` options to pass
+   * through — the host embeds its trusted keys natively.
    */
   _maybeStartOta(rawConfig) {
     const ota = rawConfig?.ota;
@@ -231,42 +225,12 @@ class ScaleBunFacade {
       const {
         otaOrchestrator
       } = require('../features/ota/OtaOrchestrator');
-      const rawSingle = ota.publicSigningKey;
-      const rawList = ota.publicSigningKeys;
-      const publicKeys = Array.from(new Set([...(typeof rawSingle === 'string' && rawSingle ? [rawSingle] : []), ...(Array.isArray(rawList) ? rawList : [])].filter(k => typeof k === 'string' && k.trim().length > 0)));
-      // Signing was REQUESTED if a usable key exists, or the host passed a
-      // keys array at all — an empty one included. `publicSigningKeys: []`
-      // is a broken attempt to enable signing, and it must flow through to
-      // signature.ts's fail-closed handling, not silently disable signing.
-      const signingRequested = publicKeys.length > 0 || Array.isArray(rawList);
-      const verifier = ota.verifySignature;
-      if (signingRequested && typeof verifier !== 'function') {
-        // A host verifier is optional since the built-in one landed — the
-        // old unconditional warning here told every correctly-configured
-        // app that its updates would be rejected. Warn only when neither
-        // verifier can actually be resolved.
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const {
-          getBuiltinVerifier
-        } = require('../features/ota/crypto/builtinVerifier');
-        if (!getBuiltinVerifier()) {
-          logger.warn('[ScaleBun] A signing key is pinned but no signature verifier is available. ' + 'Signature checking is fail-closed: updates will be REJECTED until one exists. ' + 'Install the optional peers `@noble/ed25519` + `@noble/hashes` (no further ' + 'code needed), or supply `ota.verifySignature`.');
-        }
-      }
       // `healthyAfterMs` is the field BootGuardConfig actually declares.
       // This passed `healthyTimeoutMs`, which nothing reads, so a host that
       // tuned the boot-guard window silently got the 10s default instead.
       // Both spellings are accepted so the older one keeps working.
       const healthyAfterMs = typeof ota.healthyAfterMs === 'number' ? ota.healthyAfterMs : typeof ota.healthyTimeoutMs === 'number' ? ota.healthyTimeoutMs : undefined;
       otaOrchestrator.init({
-        ...(signingRequested ? {
-          signature: {
-            // Single key stays a plain string — the shape every
-            // existing consumer and test already handles.
-            publicKey: publicKeys.length === 1 ? publicKeys[0] : publicKeys,
-            verifier
-          }
-        } : {}),
         ...(healthyAfterMs !== undefined ? {
           healthyAfterMs
         } : {})
@@ -333,7 +297,9 @@ class ScaleBunFacade {
       }
       const clientKey = this._clientKey;
       const apiUrl = this._apiBaseUrl;
-      if (!clientKey || !apiUrl) return;
+      if (!clientKey || !apiUrl) {
+        return;
+      }
       this._otaCheckInFlight = true;
       try {
         const info = await bridgeAdapter.getDeviceInfo();
@@ -390,7 +356,7 @@ class ScaleBunFacade {
       if (!dbgConfig) return;
       dbgConfig.__skipDeprecationWarning = true;
       this.enableDebug(dbgConfig);
-      __DEV__ && logger.info('[ScaleBun] Debug auto-connected via init({ debug }).');
+      logger.info('[ScaleBun] Debug auto-connected via init({ debug }).');
     } catch (err) {
       logger.warn('[ScaleBun] Auto debug connection failed:', err?.message);
     }
@@ -407,7 +373,7 @@ class ScaleBunFacade {
       const apiBaseUrl = this._apiBaseUrl;
       if (!enabled || !appId || !clientKey || !apiBaseUrl) {
         if (enabled && !appId) {
-          __DEV__ && logger.info('[ScaleBun] Envelope event tracking disabled — no appId in init config.');
+          logger.info('[ScaleBun] Envelope event tracking disabled — no appId in init config.');
         }
         return;
       }
@@ -459,7 +425,7 @@ class ScaleBunFacade {
         onEvent: (eventName, revenue) => this._skanManager?.onEvent(eventName, revenue)
       });
       this._eventTracker.start();
-      __DEV__ && logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
+      logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
 
       // Complete the device context from the native bridge.
       //
@@ -1141,7 +1107,7 @@ class ScaleBunFacade {
       const cfg = await (this._getEngageTransport()?.fetchEngageConfig(context) ?? Promise.resolve(null));
       const messages = cfg?.inAppMessages ?? [];
       const previews = messages.filter(m => m.preview === true || m.isTest === true);
-      __DEV__ && logger.info(`[Engage] debugFetchInAppMessages → ${messages.length} message(s), ${previews.length} test preview(s)`);
+      logger.info(`[Engage] debugFetchInAppMessages → ${messages.length} message(s), ${previews.length} test preview(s)`);
       return messages;
     },
     /** Upload a survey/NPS/feedback response (idempotent, rides the outbox). */
@@ -1426,7 +1392,7 @@ class ScaleBunFacade {
         logger.warn('SDK not initialized. Event dropped:', name);
         return;
       }
-      __DEV__ && logger.debug('Tracking event:', name);
+      logger.debug('Tracking event:', name);
 
       // Fan this event out to the Engage trigger engine. Same single funnel,
       // extra observer — lets behavioral triggers (custom_event, failed_action,
@@ -1599,7 +1565,7 @@ class ScaleBunFacade {
         await Promise.all([this._eventTracker?.flush() ?? Promise.resolve(), adapter?.flushAnalytics() ?? Promise.resolve()]);
         return;
       }
-      __DEV__ && logger.debug('Flushing events from persistent queue...');
+      logger.debug('Flushing events from persistent queue...');
       const httpClient = coreContainer.get('HttpClient');
       await flushQueue(this._getQueue(), httpClient, getDeviceId());
     });
@@ -1622,9 +1588,9 @@ class ScaleBunFacade {
       const bootstrapPerfFeature = _getPerformanceFeature();
       if (bootstrapPerfFeature) {
         this._performanceFeature = bootstrapPerfFeature;
-        __DEV__ && logger.debug('Performance feature linked from bootstrap');
+        logger.debug('Performance feature linked from bootstrap');
       }
-      __DEV__ && logger.info('Debug enabled');
+      logger.info('Debug enabled');
     });
   }
 
@@ -1776,14 +1742,14 @@ class ScaleBunFacade {
         return false;
       }
       sm.startSession(metadata);
-      __DEV__ && logger.info('session.start() ✅ sessionId:', sm.currentSessionId);
+      logger.info('session.start() ✅ sessionId:', sm.currentSessionId);
       return true;
     },
     end: reason => {
       const sm = SessionManager.getExistingInstance();
       if (!sm || !sm.isActive) return false;
       sm.endSession(reason);
-      __DEV__ && logger.info('session.end() ✅');
+      logger.info('session.end() ✅');
       return true;
     },
     emitEvent: (type, data) => {
@@ -1841,7 +1807,7 @@ class ScaleBunFacade {
         ...this._privacyConfig,
         ...config
       };
-      __DEV__ && logger.debug('[report] Privacy config updated');
+      logger.debug('[report] Privacy config updated');
     },
     /** Set branding for exported reports. */
     setBranding: config => {
@@ -1849,7 +1815,7 @@ class ScaleBunFacade {
         ...this._brandingConfig,
         ...config
       };
-      __DEV__ && logger.debug('[report] Branding config updated');
+      logger.debug('[report] Branding config updated');
     },
     /** Get current privacy config. */
     getPrivacy: () => ({
@@ -1904,9 +1870,9 @@ class ScaleBunFacade {
           AutoScreenDetector
         } = require('../features/navigation/AutoScreenDetector');
         AutoScreenDetector.getInstance().setNavigationRef(ref);
-        __DEV__ && logger.info('[ScaleBun] Navigation ref set → auto screen detection active');
+        logger.info('[ScaleBun] Navigation ref set → auto screen detection active');
       } catch (err) {
-        __DEV__ && logger.debug('[ScaleBun] Navigation ref stashed (detector not ready):', err?.message);
+        logger.debug('[ScaleBun] Navigation ref stashed (detector not ready):', err?.message);
       }
     });
   }

package/lib/typescript/core/config/schema.d.ts

@@ -86,15 +86,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/lib/typescript/core/constants/version.d.ts

@@ -8,5 +8,5 @@
  * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
  * version was introduced to solve.
  */
-export declare const SDK_VERSION = "1.13.0";
+export declare const SDK_VERSION = "2.0.1";
 //# sourceMappingURL=version.d.ts.map

package/lib/typescript/features/journey/autoInstrumentScroll.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RN-3, ZERO-CONFIG — make every ScrollView report its offset, not just the wrapped ones.
+ *
+ * THE PROBLEM THIS SOLVES. Scroll offsets reach the SDK from `ScaleBunScrollView` and nowhere
+ * else, so an app using React Native's own `<ScrollView>` — which is most apps — produces taps
+ * with no content depth at all. Two taps at the same screen coordinate one viewport apart then
+ * merge into one hotspot, and the heatmap shows heavy engagement at a position where, in content
+ * terms, nothing in particular is. Asking every integration to swap its scroll views is a real
+ * migration cost and will never reach the long tail.
+ *
+ * WHY IT IS OFF BY DEFAULT, and why that is not timidity. This patches React Native's own module
+ * exports. Every scroll view in the host app — including ones inside third-party libraries the
+ * app did not write — starts routing through an SDK component. The failure mode of getting that
+ * wrong 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 with their eyes open,
+ * not a default they discover afterwards.
+ *
+ * THE PRECEDENT, AND ITS LESSON. The SDK already patches `@react-navigation/native` this way
+ * (`AutoScreenDetector._autoHookReactNavigation`). That hook shipped BROKEN: it assigned to module
+ * exports that are getters, which throws in strict mode, inside a `catch` that discarded the
+ * error. It reported success, captured no ref, and the whole screen-name pipeline stayed empty
+ * with nothing to indicate it. So this uses the same defence that fixed it — define the property
+ * rather than assign to it, then READ IT BACK — and refuses to claim success it has not verified.
+ *
+ * WHAT IT DELIBERATELY DOES NOT PATCH. `FlatList` and `SectionList` render a `ScrollView`
+ * internally, so patching that one export covers them without touching three. Fewer patch points
+ * is fewer ways to be wrong, and RN-4's row identity comes off the fiber regardless of which
+ * component rendered it.
+ */
+interface PatchResult {
+    /** True only when the replacement was verified by reading it back. */
+    installed: boolean;
+    /** Why not, when it did not install — for a diagnostic the host can act on. */
+    reason?: string;
+}
+/**
+ * Patch React Native's `ScrollView` export so every scroll view reports its offset.
+ *
+ * Idempotent, no-throw, and honest about failure: returns `installed: false` with a reason rather
+ * than claiming a success it did not verify.
+ */
+export declare function autoInstrumentScrollViews(): PatchResult;
+/** Test seam: forget that the patch ran, so a suite can exercise it more than once. */
+export declare function resetAutoInstrumentForTests(): void;
+export {};
+//# sourceMappingURL=autoInstrumentScroll.d.ts.map

package/lib/typescript/features/journey/interactionProtocol.d.ts

@@ -8,14 +8,152 @@ export interface InteractionStartContext {
     y: number;
     target?: string;
     targetId?: string;
+    /**
+     * WHICH kind of identity `targetId` is: an authored `testID`, a structural component path, or
+     * a bare component name.
+     *
+     * Carried because they are not equally trustworthy — a testID is a promise from the app's
+     * authors, a path is an inference that breaks when the tree is refactored — and a consumer
+     * that cannot tell them apart renders a refactor-fragile guess as a confident target.
+     */
+    targetSource?: 'testID' | 'path' | 'component' | 'none';
     screenName?: string;
+    /** RN-8: where `screenName` came from, so low coverage is diagnosable rather than merely visible. */
+    screenSource?: 'manual' | 'navigation' | 'none';
+    /**
+     * RN-13: the target control's rectangle as fractions of the capture base, or undefined when it
+     * could not be measured synchronously. Comparable to the tap's own normalized point, which is
+     * what makes 'heat is on this control' checkable rather than assumed.
+     */
+    targetRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * RN-3: the content offset of the nearest ancestor scroller at finger-down, so two taps at the
+     * same screen coordinate one viewport apart do not merge. Absent when no ancestor reported one
+     * — never defaulted to 0, which is a real scroll position (the top of a list).
+     */
+    scrollX?: number;
+    scrollY?: number;
+    /** Whether a scroll offset was available at all. 'none' means no wrapped scroller was an ancestor. */
+    scrollSource?: 'wrapper' | 'none';
+    /**
+     * RN-4: the list row's key, taken from the app's own `keyExtractor` via the cell's `cellKey`
+     * prop. Distinguishes two taps that share a RECYCLED native view — the same slot showing a
+     * different row after scrolling — which would otherwise merge into one hotspot.
+     */
+    itemKey?: string;
+    /** The row's index at render time. Same index + different key = a recycled slot. */
+    itemIndex?: number;
+    /**
+     * RN-15: the tap's position INSIDE the target control — (0,0) its top-left, (1,1) its
+     * bottom-right. Resolution-independent, so one control is one distribution across every device
+     * size rather than a separate cloud of heat per screen width.
+     *
+     * NOT clamped. A value outside 0..1 means the tap landed outside the control's visual box and
+     * was still attributed to it, which is what `hitSlop` does — and a control whose taps cluster
+     * outside its own bounds is drawn too small, which is a finding rather than noise.
+     */
+    localU?: number;
+    localV?: number;
     ui?: string;
     stateStatus: InteractionStateStatus;
     emitAutomaticAnalytics: boolean;
 }
 export declare function generateInteractionId(): string;
+/**
+ * RN-6 — THE CORRELATION CONTRACT.
+ *
+ * WHAT IS BEING JOINED, AND WHY IT IS HARD. A physical tap is observed twice: natively, by
+ * a window callback that sees ACTION_DOWN/UP and produces the coordinates; and in JS, by a
+ * capture-phase touch handler that produces the IDENTITY — which control was hit, what UI
+ * state was declared, which screen. Both sides mint their own id and neither can derive
+ * the other's: native builds `ixn-a-<process nonce>-<MotionEvent ts>` from a clock JS
+ * cannot read, and JS builds `ixj-<Date.now()>-<random>`. So the two observations have to
+ * be JOINED, and the only shared quantity is time.
+ *
+ * WHY THE OLD JOIN WAS DANGEROUS RATHER THAN MERELY APPROXIMATE. It took whichever start
+ * was nearest in time within ±1500 ms and used it unconditionally. The fields it carries
+ * across are `target`, `targetId`, `ui`, `stateStatus` and `screenName`; the coordinates
+ * come from the native side and are always right. So a wrong pairing does not produce
+ * obviously broken data — it produces heat in the CORRECT position attributed to the
+ * WRONG control, in the wrong UI state, on the wrong screen. Nothing downstream can
+ * detect that, because every field is individually well-formed.
+ *
+ * 1500 ms is a very long time on a touch surface. A deliberate double-tap is 150–300 ms
+ * apart; an impatient tapper is faster. So "nearest within 1500 ms" routinely had more
+ * than one candidate, and picked one with no record that it had a choice.
+ *
+ * WHAT THIS REPLACES IT WITH — three outcomes instead of one, and a refusal:
+ *
+ *   'exact'      one candidate is clearly closest: the runner-up is at least
+ *                `marginMs` further away. The join is used.
+ *   'ambiguous'  two candidates are within `marginMs` of each other, so choosing
+ *                between them is a coin flip. The join is REFUSED and the caller must
+ *                emit the interaction WITHOUT js-derived identity. A tap with no target
+ *                is honest and visibly incomplete; a tap with the wrong target is
+ *                indistinguishable from a correct one and corrupts every aggregate it
+ *                enters.
+ *   'none'       nothing within tolerance. Same refusal, different reason — worth
+ *                separating because 'none' means the JS handler never fired (a real
+ *                capture gap) while 'ambiguous' means it fired too often to attribute.
+ *
+ * It also reports `deltaMs` and `runnerUpDeltaMs` so the outcome is auditable after the
+ * fact rather than being a claim this comment makes.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: use position to disambiguate. The native event carries
+ * raw px in the capture view and normalized 0..1 coordinates; the JS start carries its own
+ * x/y in a different space (dp in the root view). Comparing them needs a proven scale
+ * factor between the two, and getting it wrong would REJECT valid pairings — strictly
+ * worse than today. That calibration needs a device run, so it is a follow-up, not a
+ * guess made here.
+ */
+export type CorrelationOutcome = 'exact' | 'ambiguous' | 'none';
+export interface CorrelationResult<T> {
+    /** Present only when `outcome` is 'exact'. Never a best-guess. */
+    start?: T;
+    /** Index into the input array, so the caller can consume it. -1 unless 'exact'. */
+    index: number;
+    outcome: CorrelationOutcome;
+    /** Distance to the chosen (or best rejected) candidate; null when there was none. */
+    deltaMs: number | null;
+    /** Distance to the second candidate — what makes 'ambiguous' auditable. */
+    runnerUpDeltaMs: number | null;
+}
+/**
+ * How far apart a native event and a JS start may be and still be the same touch.
+ *
+ * Unchanged at 1500 ms from the previous implementation, deliberately: narrowing it is a
+ * separate, measurable decision about how late the JS handler can run on a slow device,
+ * and bundling it into this change would make any regression impossible to attribute.
+ */
+export declare const CORRELATION_TOLERANCE_MS = 1500;
+/**
+ * How much closer the winner must be than the runner-up to count as identified.
+ *
+ * 100 ms because that is comfortably below the fastest deliberate double-tap (~150 ms):
+ * when two candidate starts are within 100 ms of each other in distance, the native event
+ * sits effectively between them and the "nearest" one is a coin flip.
+ */
+export declare const CORRELATION_MARGIN_MS = 100;
 /** Match a native bridge event to the JS evidence sampled at the same finger-down. */
-export declare function nearestInteractionStart<T extends InteractionStartContext>(starts: readonly T[], occurredAt: number, toleranceMs?: number): T | undefined;
+export declare function correlateInteraction<T extends InteractionStartContext>(starts: readonly T[], occurredAt: number, toleranceMs?: number, marginMs?: number): CorrelationResult<T>;
+/**
+ * Drop starts that can no longer match anything, in place.
+ *
+ * WHY IT MATTERS BEYOND MEMORY. A start older than the tolerance is unreachable, but while
+ * it sits in the list it is still a CANDIDATE for the ambiguity test — so a stale entry can
+ * turn a perfectly clear pairing into a refusal, and an accumulating list makes that more
+ * likely the longer a session runs. Pruning is therefore part of the correctness of the
+ * join, not housekeeping.
+ *
+ * Mutates rather than returning a copy because the caller holds it in a ref that the native
+ * listener and the touch handler both read.
+ */
+export declare function pruneInteractionStarts<T extends InteractionStartContext>(starts: T[], now: number, toleranceMs?: number): number;
 /** Analytics is a projection of the same evidence; no second click is invented. */
 export declare function automaticInteractionProperties(payload: Record<string, unknown>, screenName: string | undefined, canonicalMirror: boolean): Record<string, unknown>;
 //# sourceMappingURL=interactionProtocol.d.ts.map

package/lib/typescript/features/journey/scrollContext.d.ts

@@ -0,0 +1,85 @@
+/**
+ * RN-3 — WHERE IN THE CONTENT A TAP HAPPENED, not just where on the glass.
+ *
+ * THE DEFECT. A tap carries screen coordinates. Two taps at the SAME screen coordinate, one
+ * viewport apart in a scrolling list, are two different controls — and with no scroll offset they
+ * are indistinguishable, so they merge into one hotspot. The heatmap then shows heavy engagement
+ * at a position where, in content terms, nothing in particular is.
+ *
+ * That is not a rendering nicety. Scroll offset is a PLACEMENT dimension (which content was under
+ * the finger) and a CACHE dimension (two states of one route that must not share a backdrop), so
+ * its absence corrupts both the aggregate and the picture drawn beneath it.
+ *
+ * WHY A REGISTRY RATHER THAN A SINGLE NUMBER. `ScrollTracker` already accumulates
+ * `previousOffsetX/Y`, but as ONE global pair with no idea which scroller moved. A screen with a
+ * vertical list containing a horizontal carousel has two scrollers, and whichever fired last
+ * overwrites the other — so the vertical position of a tap inside the carousel is whatever the
+ * carousel's horizontal offset happened to leave behind. A single global scrollY cannot express a
+ * nested scroller, and silently reports a wrong number rather than none.
+ *
+ * So offsets are keyed by the scroller's NATIVE TAG, which is the one identity both ends of this
+ * can see: the wrapper holds a ref to its own ScrollView, and the touch handler's fiber walk
+ * passes the same host instances on its way up. Matching on anything else — a name, an index, a
+ * generated id — would require the two sides to agree on a convention, and a convention that can
+ * drift is a join that can silently attach the wrong scroller's offset.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: guess. If no ancestor of the tapped node has a recorded
+ * offset, the answer is null, not zero. Zero is a real scroll position — the top of a list — and
+ * reporting it for "we do not know" would place every unmeasured tap at the top of its content,
+ * which is both wrong and indistinguishable from a genuine tap there.
+ *
+ * KNOWN LIMIT, stated because it bounds what this can deliver: offsets only arrive from
+ * `ScaleBunScrollView`, which an app has to opt into. A plain `<ScrollView>` reports nothing, so
+ * `scrollSource` is `'none'` and the tap has no content depth. Making it automatic means patching
+ * React Native's own exports — the SDK already does that for `@react-navigation/native` — and that
+ * is a decision with a much larger blast radius, not one to make silently inside a data fix.
+ */
+export interface ScrollOffset {
+    x: number;
+    y: number;
+    /** When it was recorded; used only to expire entries, never reported. */
+    at: number;
+}
+/**
+ * How long a recorded offset stays usable.
+ *
+ * A scroller that has not moved in this long may well have been unmounted — a list on a screen the
+ * user left — and its stale offset must not be attached to a tap on a DIFFERENT screen that happens
+ * to reuse the same native tag. Tags are recycled by the platform, which makes this a correctness
+ * bound rather than a memory one.
+ *
+ * Five minutes is far longer than any plausible gap between scrolling a list and tapping in it,
+ * and far shorter than a session.
+ */
+export declare const SCROLL_OFFSET_TTL_MS: number;
+/**
+ * The native tag of a host instance, across the shapes React Native has used.
+ *
+ * Fabric exposes `__nativeTag`; the old architecture used `_nativeTag`. Probing both means this
+ * keeps working on either architecture, and returns null rather than throwing on anything else —
+ * a scroll offset is never worth a crash.
+ */
+export declare function nativeTagOf(node: unknown): number | null;
+/** Record where a scroller currently sits. Called on every scroll event of a wrapped scroller. */
+export declare function recordScrollOffset(tag: number | null, x: number, y: number, now?: number): void;
+/**
+ * The offset of the NEAREST ancestor scroller that has one, given the tapped node's ancestor tags
+ * ordered innermost first.
+ *
+ * Nearest wins because that is the scroller the content under the finger actually moved with. A
+ * tap inside a horizontal carousel inside a vertical list belongs to the carousel's content
+ * position; attributing it to the outer list would place it by how far the PAGE had scrolled,
+ * which is the merge this whole module exists to prevent.
+ *
+ * Returns null when no ancestor has a recorded offset — never a zero.
+ */
+export declare function nearestRecordedOffset(ancestorTags: readonly (number | null)[], now?: number): {
+    x: number;
+    y: number;
+    tag: number;
+} | null;
+/** Forget everything. Called between sessions so one recording cannot inherit another's scrollers. */
+export declare function clearScrollOffsets(): void;
+/** How many scrollers are currently tracked — for the leak assertion in tests. */
+export declare function trackedScrollerCount(): number;
+//# sourceMappingURL=scrollContext.d.ts.map

package/lib/typescript/features/journey/targetGeometry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * RN-13 — THE TARGET'S RECTANGLE, without which "placed on Add to Cart" is unprovable.
+ *
+ * WHAT IS MISSING WITHOUT IT. A tap carries a point and an identity. That is enough to say "this
+ * tap resolved to the control named `checkout-cta`" and NOT enough to say the heat is actually ON
+ * that control — those are different claims, and only the second is what a heatmap draws. With no
+ * rect, an off-by-a-status-bar coordinate transform, a stale layout, or a mispaired identity all
+ * produce output that looks correct: a marker somewhere on the screen, labelled with a real
+ * control's name. The rect is what makes `heat ∈ target` decidable rather than assumed, which is
+ * why the plan moved this to P0 and ships it WITH semantic identity rather than after.
+ *
+ * WHY A SYNCHRONOUS MEASUREMENT IS THE WHOLE DESIGN CONSTRAINT. The tap handler runs synchronously
+ * and the interaction is emitted shortly after. React Native's classic measurement APIs
+ * (`measure`, `measureInWindow`) are CALLBACK-based, so a rect requested at finger-down arrives
+ * after the handler has returned and possibly after the event has been emitted. An implementation
+ * built on them would attach whichever rect happened to have resolved in time — sometimes the
+ * right one, sometimes the previous tap's, with no way to tell the two apart afterwards. That is
+ * the failure this module refuses to have.
+ *
+ * The New Architecture's host components expose `unstable_getBoundingClientRect()`, which returns
+ * a DOMRect SYNCHRONOUSLY. So the rect is either read in the same tick as the touch, or it is
+ * null. There is no third option and no best-effort.
+ *
+ * THE `unstable_` PREFIX IS LOAD-BEARING and is why every access here is a probe rather than a
+ * call. The method may be renamed when it stabilises, may be absent on the old architecture
+ * entirely, and may throw on a node that has been unmounted between the touch and the read. Each
+ * of those degrades to `null` — the SDK reports that it could not measure, which is a fact, rather
+ * than a rectangle it invented, which would be indistinguishable from a measured one.
+ */
+/** A rectangle in the same coordinate space as `pageX`/`pageY`: the RN root view. */
+export interface ElementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A rectangle expressed as fractions of the capture base, directly comparable to a tap's normalized point. */
+export interface NormalizedRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Read a node's rectangle synchronously, or return null.
+ *
+ * Both spellings are probed: `unstable_getBoundingClientRect` is what React Native 0.81 ships, and
+ * the unprefixed name is what it becomes if the API stabilises. Probing for both means the day it
+ * is renamed the SDK keeps working instead of silently losing geometry — and silently is exactly
+ * how it would go, because a missing rect is a legitimate outcome that produces no error.
+ */
+export declare function readRectSync(node: unknown): ElementRect | null;
+/**
+ * Express a rect as fractions of the capture base, so it is comparable to the tap's normalized point.
+ *
+ * WHY THIS SHARES THE TAP'S BASE AND NOT A WINDOW SIZE. The tap is normalized against the measured
+ * ROOT VIEW — the exact view the screenshot captures — precisely because `Dimensions.get('window')`
+ * excludes system insets differently across devices and pushes markers about 10% off vertically.
+ * A rect normalized against a different base than the point it will be compared with produces a
+ * containment test that is wrong by that same offset, which would read as "the heat is just outside
+ * the button" on every device with a status bar. Same base, or no rect.
+ *
+ * Values are NOT clamped to 0..1. A control genuinely extending past the capture base (a row
+ * scrolled half off-screen) has a rect that runs past the edge, and clamping it would silently
+ * enlarge the containment test — turning a tap that missed the visible part of a control into a hit.
+ */
+export declare function normalizeRect(rect: ElementRect | null, base: {
+    w: number;
+    h: number;
+} | null): NormalizedRect | null;
+/**
+ * WHERE IN THE CONTROL the tap landed — RN-15.
+ *
+ * `u` and `v` are the tap's position as fractions of the target's own box: (0,0) is its top-left,
+ * (1,1) its bottom-right, (0.5,0.5) dead centre. This is what turns "they tapped Add to Cart" into
+ * "they tapped the left edge of Add to Cart", which is the difference between knowing a control is
+ * used and knowing whether its hit area is right.
+ *
+ * RESOLUTION-INDEPENDENT BY CONSTRUCTION, which is the point on mobile. A screen-space heatmap
+ * aggregates a control differently on every device size, so a button that sits at 40% width on a
+ * phone and 25% on a tablet produces two clouds of heat that never combine. Local coordinates are
+ * the same numbers on both, so one control is one distribution regardless of what it is rendered on.
+ *
+ * DELIBERATELY NOT CLAMPED, and this is the interesting part rather than an oversight. A value
+ * outside 0..1 means the tap landed OUTSIDE the control's visual box and was still attributed to
+ * it — which is exactly what `hitSlop` does, and it is real: `hitSlop={24}` makes a control
+ * respond to touches two dozen points beyond its own edge. Clamping would erase the one signal
+ * that distinguishes "tapped the button" from "tapped near the button and the button took it",
+ * and that distinction is a design finding: a control whose taps cluster outside its own bounds is
+ * drawn too small.
+ *
+ * Returns null, not a centre, when either input is missing. A fabricated (0.5, 0.5) would sit in
+ * the middle of every distribution and look exactly like a deliberate central tap.
+ */
+export declare function localPoint(rect: NormalizedRect | null, nx: number | null | undefined, ny: number | null | undefined): {
+    u: number;
+    v: number;
+} | null;
+/**
+ * Is the tap's normalized point inside the target's normalized rect?
+ *
+ * THE PREDICATE THE WHOLE MODULE EXISTS FOR. A heatmap that draws a marker labelled with a
+ * control's name is asserting this, and until now nothing checked it.
+ *
+ * Edges are INCLUSIVE. A tap on a button's exact border is a tap on the button — exclusive edges
+ * would report a sliver of every control as a miss, and at the resolution these coordinates carry
+ * that sliver is not a real distinction.
+ *
+ * Returns null, not false, when either input is missing. "The point is outside the control" and
+ * "we could not measure the control" are different findings with different fixes, and collapsing
+ * them into `false` would make an unmeasurable control look like a placement failure.
+ */
+export declare function containsNormalizedPoint(rect: NormalizedRect | null, nx: number | null | undefined, ny: number | null | undefined): boolean | null;
+//# sourceMappingURL=targetGeometry.d.ts.map