@scalebun/react-native 2.0.0 → 2.0.2

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 = "2.0.0";
+export declare const SDK_VERSION = "2.0.2";
 //# 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

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