@scalebun/react-native 1.13.0 → 2.0.1

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

@@ -9,33 +9,166 @@
  * WHY THE FIBER. There is no DOM. The only place a tapped view's identity exists in JS is the React
  * fiber hanging off the touch event (`_targetInst`), which carries `memoizedProps` — where
  * `accessibilityLabel` and `testID` live. This is a React internal, so every access is defensive and
- * the whole thing degrades to `null` rather than throwing: a analytics label is never worth a crash.
+ * the whole thing degrades to `null` rather than throwing: an analytics label is never worth a crash.
  *
- * IDENTITY PREFERENCE, strongest first:
- *   1. `accessibilityLabel` — authored to describe the control, and already required for a11y.
- *   2. `testID` — authored to identify the control, stable across copy changes.
- *   3. a literal string child — the button's visible caption.
- *   4. the nearest named component — coarse, but far better than nothing.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
+ * RN-2 — THE IDENTITY LADDER USED TO CAPTURE USER TEXT, AND THAT IS A PRIVACY DEFECT, NOT A
+ * TRADE-OFF.
+ *
+ * The previous preference order was:
+ *
+ *   1. accessibilityLabel   2. testID   3. a literal string child   4. nearest component
+ *
+ * Ranks 1 and 3 are FREE TEXT authored for humans, and in a real app they routinely contain user
+ * data. An accessible order row is labelled "Order 1042 for mohamed@scalebun.com". A pay button
+ * reads "Pay EGP 1,442". A contact row's caption is a person's name. Rank 1 was preferred over
+ * `testID`, so the leakiest source won whenever it existed.
+ *
+ * Two separate harms, and the second is easy to miss:
+ *
+ *   PRIVACY. `describeTouchTarget`'s output is persisted as the interaction's `target`. So names,
+ *   email addresses and amounts were being written into an analytics store, under a field nobody
+ *   would think to audit for PII. The same product already found 27 rows in `replay_events`
+ *   carrying email addresses through a different route; this was a second one.
+ *
+ *   CORRECTNESS. `target` is an AGGREGATION KEY. Keyed on text that varies per user, a single
+ *   button produces one bucket per person — so the grouping this feature exists to provide is
+ *   destroyed precisely in the screens that matter most. A leaky key is also a useless key.
+ *
+ * SO THE LADDER IS NOW DERIVED FROM CODE, NEVER FROM CONTENT:
+ *
+ *   1. `testID`     — authored to identify, stable across copy edits, and by convention never
+ *                     user data. The strongest signal and now the first.
+ *   2. `path`       — the component-name chain from the tapped node upward, e.g.
+ *                     `CartScreen>OrderRow>Pressable`. Structural: it changes when the code
+ *                     changes, not when the data does. This is what makes the ladder useful in
+ *                     the overwhelming majority of apps, which have no testIDs — without it,
+ *                     removing free text would have meant removing identity.
+ *   3. `component`  — the nearest named component alone. Coarse, but a code identifier.
+ *
+ * Free text is still RESOLVABLE, because a team that has audited its own labels may legitimately
+ * want them, but it is opt-in per call (`includeText`) and it is NEVER what
+ * `describeTouchTarget` returns. Default-off matters more than the option: a default that leaks
+ * is a leak, whatever the documentation says.
+ *
+ * WHY THIS SHIPS WITH RN-1 (persistence) RATHER THAN AFTER IT. RN-1 makes the resolved target
+ * actually reach the backend. Landing that first would persist the leaky ladder and create a
+ * historical PII problem to clean up; landing the sanitised ladder first and persistence second
+ * leaves a window where the feature looks broken. They are one change.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
  */
 export interface TouchTarget {
-    accessibilityLabel?: string;
+    /** Authored identifier. Safe to persist and to aggregate on. */
     testID?: string;
-    text?: string;
+    /**
+     * Structural path of component names, tapped node first, e.g. `Pressable<OrderRow<CartScreen`.
+     * Derived from the code's shape, so it never contains user data.
+     */
+    path?: string;
+    /** Nearest named component. A code identifier, safe. */
     component?: string;
+    /**
+     * FREE TEXT — may contain user data. Populated ONLY when `includeText` is requested, and never
+     * returned by `describeTouchTarget`. Treat as unsafe to persist without an audit.
+     */
+    accessibilityLabel?: string;
+    /** FREE TEXT — the visible caption. Same warning as `accessibilityLabel`. */
+    text?: string;
+    /**
+     * RN-13 — the host node the IDENTITY was taken from, so a rect read off it describes the
+     * same element the tap was attributed to.
+     *
+     * This is the reason the node is captured during the identity walk rather than by a second,
+     * independent walk: two walks can disagree about which ancestor is "the control", and a rect
+     * belonging to a different element than the name is worse than no rect at all — it would make
+     * `heat ∈ target` answer confidently about the wrong box.
+     *
+     * Deliberately NOT serialisable and never persisted. Callers read a rectangle off it and
+     * discard it; nothing downstream should hold a React internal.
+     */
+    node?: unknown;
+    /**
+     * RN-3 — every ancestor host instance from the tapped node upward, INNERMOST FIRST.
+     *
+     * Collected on the identity walk rather than by a second traversal, for the same reason the
+     * rect's node is: two walks can disagree about the chain, and attributing a tap to the wrong
+     * scroller's offset places it by how far a DIFFERENT container had scrolled. Order is the
+     * contract — `nearestRecordedOffset` takes the first ancestor that has an offset, because that
+     * is the scroller the content under the finger actually moved with.
+     *
+     * Like `node`, these are React internals: read a native tag off them and discard.
+     */
+    ancestors?: unknown[];
+    /**
+     * RN-4 — the list row's own identity, for FREE.
+     *
+     * MEASURED BEFORE IT WAS DESIGNED, because the obvious fix was to make every app author a
+     * testID per row and that would have been a large, permanent burden on every integration. It is
+     * unnecessary. React Native's `VirtualizedList` builds each cell as
+     *
+     *     const key = VirtualizedList._keyExtractor(item, ii, this.props);   // line 797
+     *     <CellRenderer cellKey={key} index={ii} key={key} ... />            // line 817
+     *
+     * so the app's OWN `keyExtractor` output — which every correct list already provides, because
+     * React requires keys — sits on the cell fiber as an ordinary prop. The walk that resolves
+     * identity already passes that fiber and simply never read it.
+     *
+     * `cellKey` is preferred over the fiber's `key` field: it is the same value, but reached
+     * through `memoizedProps` like every other prop this module reads, rather than through a React
+     * internal whose exposure is not part of any contract.
+     *
+     * WHY THIS MATTERS MORE THAN AN ORDINARY LABEL. A virtualised list REUSES native views: row 40
+     * scrolls into the view row 1 vacated. Without the cell key those two taps share a native
+     * identity and a screen position, so they merge — one hotspot on a row nobody in particular
+     * tapped. `itemIndex` is carried alongside precisely so the recycling is visible: the same index
+     * with a different key is a recycled slot, and that is a fact worth being able to prove rather
+     * than infer.
+     */
+    itemKey?: string;
+    /** The cell's position in the list at render time. See `itemKey` for why both are kept. */
+    itemIndex?: number;
+}
+/** Where a resolved identity came from — so a consumer can tell an authored id from a guess. */
+export type TargetIdentitySource = 'testID' | 'path' | 'component' | 'none';
+export interface ResolveTouchTargetOptions {
+    /** How far up the tree to look. */
+    maxDepth?: number;
+    /**
+     * Collect `accessibilityLabel` and the visible caption.
+     *
+     * OFF BY DEFAULT AND MEANT TO STAY THAT WAY. Turning it on means user-authored text may be
+     * carried out of the app, so it belongs to a team that has audited its own labels — not to a
+     * default. Even when on, the text is never used as the identity.
+     */
+    includeText?: boolean;
 }
 /**
  * Walk up from the touched fiber collecting the best identity available.
  *
- * Keeps walking after a hit so a wrapper's `testID` can still be picked up when the leaf only had text,
- * but stops as soon as BOTH an accessibilityLabel and a testID are known — nothing above can improve on
- * that pair.
+ * Keeps walking after a hit so a wrapper's `testID` can still be picked up when the leaf had none,
+ * and stops as soon as a `testID` is known AND the path is full — nothing above can improve on that.
  */
-export declare function resolveTouchTarget(event: unknown, maxDepth?: number): TouchTarget | null;
+export declare function resolveTouchTarget(event: unknown, optsOrMaxDepth?: ResolveTouchTargetOptions | number): TouchTarget | null;
 /**
- * One short human label for the tapped thing, or undefined when nothing identified it.
+ * One short, STABLE, non-identifying label for the tapped thing.
  *
- * This is what ends up grouping the Events explorer, so it must be STABLE: a11y label and testID are
- * authored and rarely change, whereas visible text moves with copy edits — hence the ordering.
+ * This is what ends up grouping the Events explorer and what gets persisted as the interaction's
+ * target, so it must satisfy two constraints at once: stable across copy edits, and free of user
+ * data. Both rule out visible text, which is why the free-text fields are not consulted here even
+ * when they have been resolved — see the RN-2 note in the header.
  */
 export declare function describeTouchTarget(t: TouchTarget | null): string | undefined;
+/**
+ * The identity plus WHERE IT CAME FROM.
+ *
+ * A consumer cannot treat an authored `testID` and a structural `path` as equally trustworthy: the
+ * first is a promise from the app's authors that this control is this control, the second is an
+ * inference that breaks when the tree is refactored. Returning the source lets the accounting lane
+ * say WHY a tap could not be attributed, instead of reporting a missing target and leaving the
+ * reader to guess whether the control had no identity or the walk failed.
+ */
+export declare function targetIdentity(t: TouchTarget | null): {
+    id?: string;
+    source: TargetIdentitySource;
+};
 //# sourceMappingURL=touchTarget.d.ts.map

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

@@ -50,4 +50,43 @@ export declare function clearUiState(name?: string): void;
  * open"; on RN there is nothing to look at, so the honest answer is silence.
  */
 export declare function uiStateSignature(): string | undefined;
+/**
+ * RN-11 — TELL SOMEONE THE STATE CHANGED, so a frame can exist for it.
+ *
+ * THE GAP. Declaring a state used to mutate a Map and nothing else. Nothing captured a frame, so
+ * the visual for a declared state existed only if a screenshot happened to be taken for some other
+ * reason — a navigation, a timer, or the interaction capture that fires AFTER the touch and
+ * photographs the outcome. A state could therefore be recorded as a fact with no picture of it
+ * anywhere, or with a picture of the state that replaced it.
+ *
+ * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER. None of them is "the
+ * UI changed shape", which is exactly the moment a heatmap needs a frame.
+ *
+ * FIRING ON A REAL CHANGE ONLY, AND WHY THAT IS THE SDK'S JOB. The advice above says to call
+ * `setUiState` when the state changes rather than on every render — but that is advice to the
+ * host, not a guarantee. A component that declares its state inside render is ordinary React, and
+ * trusting the caller would mean a screenshot per render: a performance disaster in exactly the
+ * apps that instrument most carefully. So a redundant set — same dimension, same value — is now a
+ * no-op, and the change test lives here where it cannot be got wrong by a host.
+ *
+ * COALESCED, because a transition usually declares several dimensions in one tick ("drawer:open"
+ * and "overlay:visible" belong to one visual change). Notifying per call would capture the
+ * intermediate shapes, which are states the user never saw.
+ *
+ * The listener is deliberately NOT given the signature. A subscriber that wants it calls
+ * `uiStateSignature()` at the moment it acts, which is the value that will actually be attached
+ * to the next tap; handing over a snapshot invites acting on a state that has already moved on.
+ */
+export type UiStateChangeListener = () => void;
+/**
+ * Subscribe to declared-state changes. Returns an unsubscribe.
+ *
+ * Registration is idempotent per function reference, so a component that re-subscribes on every
+ * render does not accumulate listeners — a leak that would only show up in long sessions.
+ */
+export declare function onUiStateChange(listener: UiStateChangeListener): () => void;
+/** Drop every listener and any pending notification. For teardown between sessions. */
+export declare function resetUiStateListeners(): void;
+/** For assertions that a re-subscribing caller has not leaked. */
+export declare function uiStateListenerCount(): number;
 //# sourceMappingURL=uiState.d.ts.map

package/lib/typescript/features/navigation/AutoScreenDetector.d.ts

@@ -30,6 +30,15 @@ export declare class AutoScreenDetector {
     private _manualScreen;
     private _manualScreenTs;
     private _autoScreen;
+    /**
+     * When `_autoScreen` was last written.
+     *
+     * Needed so `getCurrentScreen()` can prefer whichever source spoke MOST RECENTLY.
+     * Without a timestamp the only comparison available was "is the manual value still
+     * fresh", which is a different question and gave the wrong answer — see the note on
+     * `_currentScreen()`.
+     */
+    private _autoScreenTs;
     /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
     private _autoVisitSig;
     private _navigationRef;
@@ -72,8 +81,19 @@ export declare class AutoScreenDetector {
      */
     setNativeScreen(name: string): void;
     /**
-     * Check if a manual screen is currently active.
-     * Used by auto-detection to yield to manual overrides.
+     * Should a WRITER defer to the manual screen right now?
+     *
+     * THIS IS A PRECEDENCE GATE, NOT A VALIDITY TEST, and conflating the two was a real
+     * bug. Its job is what the cooldown constant says: for a short window after a manual
+     * beacon fires, an auto source must not overwrite it — the poller runs every 1500 ms
+     * and would otherwise clobber a fresh declaration with whatever it inferred.
+     *
+     * `getCurrentScreen()` used to reuse this as "is the manual screen still the current
+     * screen", which made a declared screen READABLE for only 2000 ms. Nothing called
+     * `setManualScreen` in production, so the effect was latent — but the moment the
+     * `<ScaleBunScreen>` beacon was wired to it (RN-8), every tap more than two seconds
+     * after a screen mounted would have lost its name, which is very nearly every tap. A
+     * fix that introduced that would have been worse than the gap it closed.
      */
     isManualScreenActive(): boolean;
     /**
@@ -144,6 +164,32 @@ export declare class AutoScreenDetector {
     teardown(): void;
     /** Get the current best-known screen name */
     getCurrentScreen(): string | null;
+    /**
+     * WHERE the current screen name came from, or 'none'.
+     *
+     * Recorded on every interaction (RN-8) so low screen coverage is DIAGNOSABLE rather
+     * than merely visible. Production shows 13.8% of Android interactions carrying a
+     * screen and 0.5% on iOS, and those numbers cannot today distinguish three different
+     * causes: the app never instrumented anything, the app instrumented manually and the
+     * value never reached interactions, or auto-detection ran and failed. Those have
+     * different owners and different fixes, and guessing between them is how a P0 stays
+     * open.
+     */
+    getCurrentScreenSource(): 'manual' | 'navigation' | 'none';
+    /**
+     * LAST WRITER WINS between the manual beacon and auto-detection.
+     *
+     * A screen declared by `<ScaleBunScreen name>` stays current until something else
+     * declares a different one — that is what mounting a screen means. It does not
+     * expire, which is the correction here: the previous rule returned the manual name
+     * only while it was under 2000 ms old and then silently fell back to the auto value,
+     * which in a manually-instrumented app is `null`.
+     *
+     * Comparing timestamps rather than hard-coding a priority also handles the real
+     * interleaving: an app can use React Navigation for most screens AND drop a manual
+     * beacon on one modal, and whichever spoke last is the truth.
+     */
+    private _currentScreen;
     private _emitScreenChange;
 }
 export {};

package/lib/typescript/features/network/index.d.ts

@@ -13,6 +13,24 @@ export interface NetworkMonitoringOptions {
     redactNetwork?: boolean;
     /** SDK backend base URL — used to filter out SDK's own upload calls from capture */
     sdkBaseUrl?: string;
+    /**
+     * Never capture requests whose URL matches (substring or RegExp).
+     *
+     * Parity with the web SDK, which has had this since F-NET. Mobile had no way to exclude a
+     * URL at all, so an app that wanted one endpoint out of its replays had no answer.
+     */
+    denyUrls?: (string | RegExp)[];
+    /**
+     * Keep known telemetry beacons: analytics collectors, ad pixels, IP-enrichment calls.
+     *
+     * Default false — they are dropped before capture. They are not the app, they cost the
+     * device real battery and cellular data to upload, and a beacon that fails counts against
+     * the SESSION HEALTH score. Matching is by hostname only, never by path, so an app route
+     * called /collect is never touched. See features/network/thirdParty.ts.
+     */
+    captureThirdParty?: boolean;
+    /** Replace the built-in beacon host list wholesale. Comma-joined hostname suffixes. */
+    thirdPartyHosts?: string;
 }
 export declare function installNetworkMonitoring(onEvent: (data: any) => void, options?: NetworkMonitoringOptions): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/features/network/thirdParty.d.ts

@@ -0,0 +1,65 @@
+/**
+ * THIRD-PARTY BEACON HOSTS — the one list, and the one matcher, for every layer that drops them.
+ *
+ * WHAT THIS IS FOR
+ * A session on an instrumented site spends most of its network tab on traffic the app did not
+ * meaningfully make: analytics collectors, ad pixels, IP-enrichment calls, tag managers. It is
+ * captured, uploaded, stored and rendered, and none of it answers a question anyone asks a session
+ * replay. One real sign-in screen was 27 requests, most of them beacons.
+ *
+ * It is not only clutter. Session health scores `failedRequests` and `slowRequests`, so a tracker
+ * killed by an ad blocker (a transport error) or one that is simply slow moves a number that is
+ * supposed to describe the APP. That is the part that makes this a correctness fix rather than a
+ * tidy-up.
+ *
+ * WHY HOSTS ONLY, NEVER PATHS
+ * The obvious rules from looking at a network tab are `/collect`, `/p`, `/api/v2/pixel`. Every one
+ * of them is a path that a customer's own API is allowed to have, and dropping a real API call is
+ * far worse than keeping a beacon: the noise is visible and annoying, the missing request is
+ * invisible and misleading. So matching is on the HOSTNAME, with a dot boundary, and a request to
+ * `/collect` on the app's own origin is kept — correctly.
+ *
+ * WHY IT IS A SUFFIX LIST AND NOT A REGEX
+ * Two reasons, both practical. It is applied inside an SDK whose eager bundle is measured in bytes,
+ * and a comma-joined string of suffixes compresses to almost nothing next to an equivalent pattern
+ * source. And it has to be COPIED, byte for byte, into the React Native SDK and into the backend's
+ * ingest path — a list with no syntax is a list that cannot drift in meaning between three
+ * languages' worth of tooling. `third-party:parity` hashes all three copies.
+ *
+ * ZERO IMPORTS, DELIBERATELY. That is what makes the byte-identical copy possible. If an edit here
+ * ever needs an import, the parity gate is the thing that will say so — keep the module pure rather
+ * than weakening the gate.
+ *
+ * WHAT IS DELIBERATELY NOT ON THE LIST
+ * The rule is: a host whose ONLY purpose is to receive telemetry. Everything else stays, because a
+ * dropped request is invisible and a kept one is merely noisy.
+ *
+ *   - Feature-flag and experiment services (LaunchDarkly, Optimizely, Split). Their RESPONSES
+ *     change what the app does, so a failed flag fetch is an application incident and the single
+ *     most useful request in the session.
+ *   - Chat and support widgets (Intercom, Zendesk, Drift). A broken widget is a broken feature the
+ *     user can see.
+ *   - `facebook.com` as a whole. `graph.facebook.com` is an API real apps call; only the pixel
+ *     delivery hosts are listed.
+ *   - CDNs of any kind, even ones that mostly serve tags: they also serve application assets, and
+ *     dropping them would hide a real asset failure.
+ *
+ * When in doubt, leave it out. `denyUrls` stays the per-app escape hatch in both SDKs, and it can
+ * do what this list will not.
+ */
+/**
+ * Known telemetry, advertising and enrichment endpoints, as hostname suffixes.
+ *
+ * One comma-joined string rather than an array: identical meaning, materially smaller once gzipped,
+ * and it keeps the copy in three repos a single line to compare by eye.
+ */
+export declare const THIRD_PARTY_BEACON_HOSTS: string;
+/**
+ * True when `url` is addressed to a known beacon host.
+ *
+ * Deliberately total: an unparseable or relative URL is NOT third party. A relative URL is
+ * same-origin by definition — the app's own call — and guessing on garbage input would drop real
+ * requests for no benefit.
+ */
+export declare function isThirdPartyBeacon(url: string, hosts?: string): boolean;
+//# sourceMappingURL=thirdParty.d.ts.map

package/lib/typescript/features/ota/OtaOrchestrator.d.ts

@@ -1,5 +1,4 @@
 import type { OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
-import { type SignatureConfig } from './signature';
 export interface SyncResult {
     status: 'UP_TO_DATE' | 'UPDATE_INSTALLED' | 'ROLLED_BACK' | 'ERROR';
     bundle?: OtaBundlePayload;
@@ -35,9 +34,10 @@ export declare class OtaOrchestrator {
      */
     getCurrentBundle(): OtaBundlePayload | null;
     private isRestartRequiredState;
+    /** Root/jailbreak indicators observed at init; empty when none found. */
+    private integrityIndicators;
     private healthyTimer;
     private bootGuardConfig;
-    private signatureConfig;
     private environment;
     /** One-time boot checks have run in this process (init is idempotent). */
     private initialized;
@@ -45,13 +45,12 @@ export declare 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?: BootGuardConfig & {
-        signature?: SignatureConfig;
-    }): void;
+    init(config?: BootGuardConfig): void;
     /**
      * Read the active slot back into `currentBundle` so the next check reports
      * what this device is genuinely running.
@@ -100,6 +99,11 @@ export declare class OtaOrchestrator {
      */
     private checkBootGuardRecovery;
     isEnabled(): boolean;
+    /**
+     * Root/jailbreak indicators detected on this device, as stable reason strings.
+     * Empty means nothing was detected — not proof the device is clean.
+     */
+    deviceIntegrityIndicators(): string[];
     isRestartRequired(): boolean;
     /**
      * Perform an OTA check against the backend endpoint.

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -51,6 +51,11 @@ export interface OtaCheckRequest {
     installationId: string;
     currentBundleId?: string;
     currentBundleHash?: string;
+    /**
+     * Trusted key IDs embedded in this app binary, for SDK trust coverage
+     * (CICDPAGE §12). Telemetry only — never a source of server-side trust.
+     */
+    trustedKeyIds?: string[];
     /** Channel to pull from. Omitted means `default`. */
     channelName?: string;
     /** ISO 3166-1 alpha-2. The server fills this from the edge when absent. */
@@ -93,6 +98,23 @@ export interface OtaBundlePayload {
     size: number;
     sha256: string;
     signature?: string;
+    /**
+     * SB-OTA-RSA-SHA256-V1 release envelope. Present on signed releases; carries
+     * the protocol id, the id of the trusted RSA key the release was signed with,
+     * the canonical signed payload, and its signature. When present, the SDK hands
+     * the whole envelope to the native module (`verifyAndStageRelease`), which
+     * verifies the signature against the RSA public keys EMBEDDED in the app
+     * package and then downloads + integrity-checks + stages the artifact — JS
+     * never stages bytes it has not proven authentic, and never pins or verifies a
+     * key itself. Absent on legacy/unsigned releases, which fall back to
+     * `stageBundle` on SHA-256 integrity alone.
+     */
+    envelope?: {
+        protocol: string;
+        keyId: string;
+        signedPayload: string;
+        signature: string;
+    };
     isMandatory: boolean;
     /**
      * How to activate the bundle after install:

package/lib/typescript/features/session/SessionManager.d.ts

@@ -268,6 +268,61 @@ export declare class SessionManager {
         targetId?: string;
         screenName?: string;
         emitAutomaticAnalytics?: boolean;
+        /**
+         * RN-6 — the native↔JS join's own verdict, and it MUST be declared here.
+         *
+         * This signature ENUMERATES its fields rather than spreading, and the only caller
+         * (ScaleBunDebugRoot's native listener) invokes it through `(sm as any)`. So a field
+         * added at the call site and not added here is dropped in silence, with no type
+         * error anywhere — which is precisely how these three nearly shipped as a no-op.
+         *
+         * 'exact' = one JS start was clearly closest. 'ambiguous' = two were within
+         * CORRELATION_MARGIN_MS of each other, so target/ui/screenName were deliberately
+         * withheld rather than guessed. 'none' = no start within tolerance, meaning the JS
+         * handler never fired. The last two are kept distinct because they have different
+         * fixes and collapsing them would hide which is happening in production.
+         */
+        correlation?: 'exact' | 'ambiguous' | 'none';
+        correlationDeltaMs?: number | null;
+        correlationRunnerUpDeltaMs?: number | null;
+        /**
+         * RN-1/RN-2 — which kind of identity `targetId` is. Declared here for the same reason as
+         * the correlation fields above: this signature enumerates, and its only caller goes
+         * through `(sm as any)`, so an undeclared field is dropped in silence.
+         */
+        targetSource?: 'testID' | 'path' | 'component' | 'none';
+        /** RN-8: where the screen name came from. Declared here because this signature enumerates. */
+        screenSource?: 'manual' | 'navigation' | 'none';
+        /**
+         * RN-13: the target control's rectangle in capture-base fractions. Declared here because
+         * this signature ENUMERATES — the sixth field to need it, after three correlation fields,
+         * targetSource and screenSource.
+         */
+        targetRect?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /**
+         * RN-3: content offset of the nearest ancestor scroller. Declared here because this
+         * signature ENUMERATES — the seventh field to need it.
+         */
+        scrollX?: number;
+        scrollY?: number;
+        scrollSource?: 'wrapper' | 'none';
+        /**
+         * RN-4: list row identity. Declared here because this signature ENUMERATES — the eighth
+         * and ninth fields to need it.
+         */
+        itemKey?: string;
+        itemIndex?: number;
+        /**
+         * RN-15: tap position within the target control. Declared here because this signature
+         * ENUMERATES — the tenth and eleventh fields to need it.
+         */
+        localU?: number;
+        localV?: number;
     }): void;
     /**
      * Manual frame capture — triggered by Desktop "Capture Step" button.

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -69,17 +69,11 @@ declare 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.
      */
     private _maybeStartOta;
     /** Guards against overlapping config-driven OTA checks. */

package/lib/typescript/public/types.d.ts

@@ -287,6 +287,16 @@ export interface SimplifiedInitConfig {
     appId?: string;
     /** SDK client key (SaaS mode). Also used to authenticate the envelope lane. */
     clientKey?: string;
+    /**
+     * Patch React Native's ScrollView export so every scroll view reports its scroll offset,
+     * giving taps their content depth without the app swapping to ScaleBunScrollView.
+     *
+     * OFF BY DEFAULT because it changes what the host renders, not merely what the SDK records:
+     * every scroll view in the app — including ones inside libraries you did not write — routes
+     * through an SDK wrapper. Turn it on deliberately. With it off, taps on a plain ScrollView
+     * report no content depth and say so, rather than reporting a fabricated offset of 0.
+     */
+    autoInstrumentScrollViews?: boolean;
     /** Platform OVERRIDE — auto-detected from Platform.OS when omitted (integrations should omit it). */
     platform?: 'ios' | 'android' | 'web' | 'react_native';
     /**