@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,161 @@
+/**
+ * ScaleBun SDK — Journey Types & Config
+ *
+ * Shared type definitions for the Journey Recorder + Runner feature.
+ * Config is supplied via enableDebug({ journey: { ... } }).
+ */
+export type GestureMode = 'TAP' | 'DOUBLE_TAP' | 'LONG_PRESS' | 'SWIPE' | 'SCROLL' | 'TYPE' | 'BACK' | 'NAV';
+export type StepStatus = 'PASS' | 'FAIL' | 'SKIP' | 'PENDING';
+export type NavMode = 'react-navigation' | 'expo-router' | 'beacon' | 'unknown';
+export interface JourneyScreenshotConfig {
+    mode?: 'onDemand' | 'periodic';
+    periodicMs?: number;
+    maxWidth?: number;
+    maxImageKB?: number;
+    format?: 'webp' | 'jpeg';
+}
+export interface JourneyGestureConfig {
+    bufferSize?: number;
+    matchWindowMs?: number;
+}
+export interface JourneyNavConfig {
+    autoDetect?: boolean;
+    allowBeaconFallback?: boolean;
+}
+export interface JourneyConfig {
+    enabled?: boolean;
+    autoStart?: boolean;
+    screenshots?: JourneyScreenshotConfig;
+    gestures?: JourneyGestureConfig;
+    nav?: JourneyNavConfig;
+}
+export declare const DEFAULT_JOURNEY_CONFIG: Required<JourneyConfig>;
+export interface GestureEvent {
+    type: GestureMode;
+    timestamp: number;
+    target?: TargetDescriptor;
+    /** Swipe/scroll direction */
+    direction?: 'up' | 'down' | 'left' | 'right';
+    /** Start/end coordinates for swipe */
+    startCoords?: {
+        x: number;
+        y: number;
+    };
+    endCoords?: {
+        x: number;
+        y: number;
+    };
+    /** Duration of the gesture in ms */
+    durationMs?: number;
+    /** For TYPE: length of text (redacted) */
+    textLength?: number;
+    /** For TYPE: field identifier */
+    fieldId?: string;
+}
+export interface TargetDescriptor {
+    testId?: string;
+    accessibilityLabel?: string;
+    role?: string;
+    text?: string;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface JourneyStep {
+    stepIndex: number;
+    gestureType: GestureMode;
+    target?: TargetDescriptor;
+    screenName: string;
+    screenshotId?: string;
+    screenshotMeta?: {
+        width: number;
+        height: number;
+        mime: string;
+        byteSize: number;
+    };
+    timestamp: number;
+    label?: string;
+    note?: string;
+    /** Set when no matching gesture was found */
+    captureOnly?: boolean;
+    captureOnlyReason?: string;
+}
+export interface SavedJourney {
+    journeyId: string;
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    steps: JourneyStep[];
+    metadata: {
+        platform?: string;
+        screenWidth?: number;
+        screenHeight?: number;
+        navMode?: NavMode;
+    };
+}
+export interface RunStepResult {
+    stepIndex: number;
+    status: StepStatus;
+    reason?: string;
+    screenshotId?: string;
+    screenshotMeta?: JourneyStep['screenshotMeta'];
+    executedAt: number;
+}
+export interface DebugReadyPayload {
+    journeyEnabled: boolean;
+    canScreenshot: boolean;
+    navMode: NavMode;
+    sdkVersion: string;
+}
+export interface CurrentScreenPayload {
+    screenName: string;
+    stack?: string[];
+}
+export interface RecordingStatePayload {
+    on: boolean;
+    journeyTempId?: string;
+}
+export interface StepRecordedPayload {
+    journeyTempId: string;
+    step: JourneyStep;
+}
+export interface JourneySavedPayload {
+    journeyId: string;
+    name: string;
+}
+export interface RunStartedPayload {
+    journeyId: string;
+    runId: string;
+}
+export interface RunStepStatusPayload {
+    runId: string;
+    stepIndex: number;
+    status: StepStatus;
+    reason?: string;
+    screenshotId?: string;
+    screenshotMeta?: JourneyStep['screenshotMeta'];
+}
+export interface RunFinishedPayload {
+    runId: string;
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        durationMs: number;
+    };
+}
+export interface RegisteredTarget {
+    id: string;
+    press?: () => void;
+    setValue?: (value: string) => void;
+    scrollTo?: (options: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }) => void;
+}
+//# sourceMappingURL=journeyTypes.d.ts.map

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

@@ -0,0 +1,47 @@
+/**
+ * SCROLL FIELDS FOR ONE TAP — the JS wrapper's offset when present, else the native probe's.
+ *
+ * Production had 0 of ~55,000 mobile taps with a scroll offset: offsets were only recorded by the
+ * SDK's own ScrollView/FlatList wrappers, and apps use the stock components. The native trackers
+ * now read every scroll container under the finger at ACTION_DOWN (Android ScrollContextProbe),
+ * with no wrapper, in the capture view's pixel space — the same space as the tap's x/y.
+ *
+ * Precedence: the innermost NATIVE entry (`'native'`, capture-view pixels, the same space as x/y)
+ * first; the JS wrapper's offset (`'wrapper'`, layout points) only when native had none. `'none'`
+ * still means no scroll container was under the finger — which, unlike
+ * before, is now a statement about the layout rather than about the integration.
+ */
+/** Current version of the mobile heatmap tap contract. Bump when a field's meaning changes. */
+export declare const HEATMAP_SCHEMA_VERSION = 2;
+export interface NativeScrollEntry {
+    containerTag?: number;
+    kind?: string;
+    horizontal?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    contentWidth?: number;
+    contentHeight?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+}
+interface StartLike {
+    scrollX?: number;
+    scrollY?: number;
+    scrollSource?: string;
+}
+interface NativeEventLike {
+    scrollContext?: unknown;
+    pixelDensity?: unknown;
+}
+/** Keep only well-formed entries: a malformed native payload must never become a fabricated offset. */
+export declare function sanitizeScrollContext(raw: unknown): NativeScrollEntry[];
+export declare function scrollFields(start: StartLike | null | undefined, event: NativeEventLike | null | undefined): {
+    scrollX?: number;
+    scrollY?: number;
+    scrollSource: 'wrapper' | 'native' | 'none';
+    scrollContext?: NativeScrollEntry[];
+    pixelDensity?: number;
+    heatmapSchemaVersion: number;
+};
+export {};
+//# sourceMappingURL=nativeScroll.d.ts.map

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

@@ -0,0 +1,42 @@
+/**
+ * ScaleBun SDK — Navigation Detector
+ *
+ * Layered detection strategy:
+ * 1. React Navigation — detect via @react-navigation/native
+ * 2. Expo Router — detect via expo-router
+ * 3. Screen Beacon — fallback via useScaleBunScreen() / <ScaleBunScreen>
+ */
+import type { NavMode, CurrentScreenPayload } from './journeyTypes';
+export type ScreenChangeCallback = (screenName: string, stack?: string[]) => void;
+export declare class NavDetector {
+    private _navMode;
+    private _currentScreen;
+    private _stack;
+    private _listeners;
+    private _installed;
+    private _teardownFns;
+    get navMode(): NavMode;
+    get currentScreen(): string;
+    get stack(): string[];
+    /** Install detection. Call after mount. Idempotent. */
+    install(config: {
+        autoDetect?: boolean;
+        allowBeaconFallback?: boolean;
+    }): void;
+    /** Set screen name (used by Screen Beacon hook/component) */
+    setScreen(name: string): void;
+    /** Subscribe to screen changes */
+    onScreenChange(callback: ScreenChangeCallback): () => void;
+    /** Get current screen payload for protocol */
+    getCurrentPayload(): CurrentScreenPayload;
+    /** Teardown listeners */
+    teardown(): void;
+    private _tryReactNavigation;
+    private _tryExpoRouter;
+    /** Called when React Navigation state changes */
+    handleNavigationStateChange(state: any): void;
+    private _extractCurrentRoute;
+    private _extractStack;
+    private _notifyListeners;
+}
+//# sourceMappingURL=navDetector.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * ScaleBun SDK — Screenshot Helper
+ *
+ * On-demand screenshot capture with compression.
+ * Falls back gracefully if react-native-view-shot is not available.
+ */
+import type { JourneyScreenshotConfig } from './journeyTypes';
+export interface ScreenshotResult {
+    base64: string;
+    width: number;
+    height: number;
+    mime: string;
+    byteSize: number;
+}
+export declare class ScreenshotHelper {
+    private config;
+    private _canCapture;
+    private _rootRef;
+    constructor(config?: JourneyScreenshotConfig);
+    get canCapture(): boolean;
+    /** Set the root ref for capturing (from ScaleBunDebugRoot) */
+    setRootRef(ref: any): void;
+    /**
+     * Capture a screenshot. Returns null with reason if capture fails.
+     */
+    capture(): Promise<{
+        result: ScreenshotResult | null;
+        error?: string;
+    }>;
+    private _detectCapability;
+    private _getCaptureRef;
+}
+//# sourceMappingURL=screenshotHelper.d.ts.map

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

@@ -0,0 +1,49 @@
+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,126 @@
+/**
+ * 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;
+}
+/**
+ * THE PUBLIC HOST INSTANCE behind whatever a fiber's `stateNode` is.
+ *
+ * A host fiber's `stateNode` is NOT the object refs receive. On the New Architecture (Fabric) it is
+ * the renderer's internal `{ node, canonical }` wrapper, and the methods live one level down on
+ * `canonical.publicInstance` (ReactFabric renderer: `getPublicInstance`). Handed the wrapper, every
+ * probe below found nothing, so `target_rect` — and `local_u/v` derived from it — were null on 100%
+ * of production taps from v2.0.1 onward (legarage: RN 0.78.3, New Architecture) with no error
+ * anywhere. The scroll-ancestor lookup read its native tag off the same wrapper and failed the same
+ * way. On the old architecture the stateNode IS the public instance, so it is returned unchanged.
+ */
+export declare function publicHostInstance(node: unknown): unknown;
+/**
+ * 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/targetRegistry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ScaleBun SDK — Target Registry
+ *
+ * Registry for deterministic replay targets.
+ * Apps register interactive elements with handlers for replay execution.
+ */
+import type { RegisteredTarget } from './journeyTypes';
+/**
+ * Register a target element for deterministic journey replay.
+ * During replay, the runner can call press/setValue/scrollTo directly.
+ */
+export declare function registerTarget(target: RegisteredTarget): () => void;
+/**
+ * Find a registered target by ID.
+ * @internal
+ */
+export declare function findTarget(id: string): RegisteredTarget | undefined;
+/**
+ * Check if a target is registered.
+ * @internal
+ */
+export declare function hasTarget(id: string): boolean;
+/**
+ * Get all registered target IDs.
+ * @internal
+ */
+export declare function getRegisteredTargetIds(): string[];
+//# sourceMappingURL=targetRegistry.d.ts.map

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

@@ -0,0 +1,174 @@
+/**
+ * Resolve WHAT was tapped, from a React Native touch event.
+ *
+ * THE GAP THIS CLOSES. Native taps carried coordinates, a gesture type and a screen — but no identity
+ * for the thing touched. Every tap in the app therefore arrived as `gesture:tap`, so the Events explorer
+ * showed one undifferentiated row per gesture type no matter how many different buttons users pressed.
+ * Web has had element text since day one; mobile had nothing to group by.
+ *
+ * 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: an analytics label is never worth a crash.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
+ * 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 {
+    /** Authored identifier. Safe to persist and to aggregate on. */
+    testID?: 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 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, optsOrMaxDepth?: ResolveTouchTargetOptions | number): TouchTarget | null;
+/**
+ * One short, STABLE, non-identifying label for the tapped thing.
+ *
+ * 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