@scalebun-release/react-native 2.5.0

package/lib/typescript/features/engage/transcription/TranscriptionProvider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ScaleBun SDK — Transcription abstraction (Slice D3)
+ *
+ * A single seam so the speech→text engine is swappable WITHOUT touching callers
+ * (SOLID/DIP). Today the only implementation is on-device native STT (Android
+ * SpeechRecognizer / iOS Speech) — see `OnDeviceTranscriptionProvider`. A future
+ * backend engine (e.g. server Whisper) implements the same interface and is
+ * registered via `setTranscriptionProvider` — captureVoiceAttachment never changes.
+ *
+ * Transcription is a best-effort PREFILL: the user edits + explicitly approves the
+ * final wording before send, so an empty/unavailable result is non-fatal.
+ */
+/** Recorded clip handed to a provider for transcription. */
+export interface VoiceClip {
+    base64: string;
+    mime: string;
+    durationMs: number;
+    byteSize: number;
+    /** On-device native STT prefill produced during recording (may be empty). */
+    nativeTranscript?: string;
+    /** Whether the native STT engine produced a usable result. */
+    nativeAvailable?: boolean;
+}
+/** Result of transcribing a clip. */
+export interface TranscriptionResult {
+    /** Best-effort transcript text (may be empty — user edits/approves before send). */
+    transcript: string;
+    /** Whether a transcription engine produced a usable result. */
+    available: boolean;
+}
+/** The swap seam: any engine that turns a voice clip into text. */
+export interface TranscriptionProvider {
+    /** Stable id for diagnostics (e.g. 'on-device', 'backend-whisper'). */
+    readonly id: string;
+    transcribe(clip: VoiceClip): Promise<TranscriptionResult>;
+}
+/**
+ * Default engine: the native recorder already runs on-device STT during the
+ * recording and returns its prefill on stop, so this provider is a pass-through —
+ * no extra round-trip, no network, no creds. Swapping in a backend engine later
+ * means replacing this provider; the capture path is untouched.
+ */
+export declare class OnDeviceTranscriptionProvider implements TranscriptionProvider {
+    readonly id = "on-device";
+    transcribe(clip: VoiceClip): Promise<TranscriptionResult>;
+}
+/** Override the active engine (e.g. a backend transcriber). */
+export declare function setTranscriptionProvider(provider: TranscriptionProvider): void;
+/** The active engine — callers depend on this, never on a concrete impl. */
+export declare function getTranscriptionProvider(): TranscriptionProvider;
+//# sourceMappingURL=TranscriptionProvider.d.ts.map

package/lib/typescript/features/install-referrer/installReferrer.d.ts

@@ -0,0 +1,39 @@
+/** True when the native Install Referrer module is present (Android build). */
+export declare function isInstallReferrerAvailable(): boolean;
+/**
+ * Fetch the raw referrer string. Returns:
+ *   - a string (possibly `""` for an organic install) when the native service responded,
+ *   - `null` when the module is absent or the service errored (caller may retry later).
+ * Never throws.
+ */
+export declare function getInstallReferrer(): Promise<string | null>;
+export interface ParsedReferrer {
+    raw: string;
+    /** The ScaleBun click token (`scalebun_click_id`), or null if absent. */
+    clickId: string | null;
+    /** All referrer params, URL-decoded. */
+    params: Record<string, string>;
+}
+/**
+ * Parse a Play referrer string (`a=b&c=d`, URL-encoded) into params + the click id.
+ * Pure; returns null for empty/whitespace input.
+ */
+export declare function parseInstallReferrer(raw: string | null | undefined): ParsedReferrer | null;
+/**
+ * Orchestrates a once-per-install referrer capture. Dependency-injected so the
+ * facade wires real storage/tracker and tests wire fakes.
+ *
+ * Idempotency: `markCaptured` is called only after the native service actually
+ * responds (a string, even `""`). A `null` fetch (module absent / transient error)
+ * leaves the flag unset so a later launch can retry while the referrer is still
+ * available from Play.
+ */
+export interface InstallReferrerSink {
+    alreadyCaptured(): boolean;
+    markCaptured(): void;
+    setClickId(clickId: string): void;
+    emit(eventName: string, props: Record<string, unknown>): void;
+    fetch(): Promise<string | null>;
+}
+export declare function captureInstallReferrerOnce(sink: InstallReferrerSink): Promise<void>;
+//# sourceMappingURL=installReferrer.d.ts.map

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

@@ -0,0 +1,49 @@
+/**
+ * ScaleBun SDK — ScaleBunDebugRoot
+ *
+ * Root wrapper component that provides:
+ * 1. Native screenshot capture wiring (via bridgeAdapter)
+ * 2. Navigation detection integration
+ * 3. Lightweight gesture capture layer
+ * 4. Emits EVENT_DEBUG_READY on mount
+ *
+ * Usage in demo app:
+ *   <ScaleBunDebugRoot>
+ *     <App />
+ *   </ScaleBunDebugRoot>
+ *
+ * Also provides:
+ *   <ScaleBunScreen name="..." /> — Screen beacon component
+ *   useScaleBunScreen("name")    — Screen beacon hook
+ *
+ * IMPORTANT: All heavy imports (JourneyManager, etc.) are LAZY
+ * to avoid pulling in native module dependencies at load time.
+ */
+import React, { type ReactNode } from 'react';
+interface ScaleBunDebugRootProps {
+    children: ReactNode;
+    /** Optional: pass a React Navigation ref for auto-detection */
+    navigationRef?: any;
+    /** Internal bridge used by ScaleBunProvider's zero-instrumentation event lane. */
+    captureAutomaticInteractions?: boolean;
+    /** Avoid the legacy-wrapper warning when composed by ScaleBunProvider. */
+    suppressDeprecationWarning?: boolean;
+}
+export declare function ScaleBunDebugRoot({ children, navigationRef, captureAutomaticInteractions, suppressDeprecationWarning, }: ScaleBunDebugRootProps): React.JSX.Element;
+interface ScaleBunScreenProps {
+    name: string;
+}
+/**
+ * Screen beacon component — registers the current screen name.
+ * Place it at the top of each screen component:
+ *   <ScaleBunScreen name="HomeScreen" />
+ */
+export declare function ScaleBunScreen({ name }: ScaleBunScreenProps): null;
+/**
+ * Screen beacon hook — registers the current screen name.
+ * Use in screen components:
+ *   useScaleBunScreen("HomeScreen");
+ */
+export declare function useScaleBunScreen(name: string): void;
+export {};
+//# sourceMappingURL=ScaleBunDebugRoot.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * ScaleBun SDK — ScaleBunFlatList
+ *
+ * Instrumented FlatList wrapper for scroll tracking.
+ * Uses `renderScrollComponent` to inject ScaleBunScrollView so that all
+ * scroll events from the FlatList flow through the SessionManager's
+ * ScrollTracker for settle detection and post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunFlatList } from 'scalebun-react-native';
+ *
+ *   <ScaleBunFlatList data={data} renderItem={renderItem} />
+ *
+ * This component is transparent — it passes all props through to the
+ * underlying FlatList and does NOT consume or interfere with any scroll events.
+ */
+import React from 'react';
+import { FlatList, type FlatListProps } from 'react-native';
+export declare const ScaleBunFlatList: <T>(props: FlatListProps<T> & React.RefAttributes<FlatList<T>>) => React.ReactElement;
+//# sourceMappingURL=ScaleBunFlatList.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * `<ScaleBunImpression>` — the mobile counterpart to web's `[data-scalebun-track-impression]`.
+ *
+ * Wrap anything whose "was it actually seen" matters (a promo card, a feed item, an upsell) and it
+ * emits `element_viewed` once, after it has been at least half on screen for a moment. Opt-in for the
+ * same reason the web marker is: the SDK cannot know which of a thousand views deserve an event, and
+ * guessing would bury the ones that do.
+ *
+ * ```tsx
+ * <ScaleBunImpression name="summer_promo" properties={{ slot: 'home_hero' }}>
+ *   <PromoCard />
+ * </ScaleBunImpression>
+ * ```
+ *
+ * All the geometry lives in `impression.ts` — this file is the shell that measures and schedules.
+ */
+import React from 'react';
+import { type ViewProps } from 'react-native';
+export interface ScaleBunImpressionProps extends ViewProps {
+    /** What was seen. This is the grouping key on the dashboard, so keep it stable. */
+    name: string;
+    /** Extra dimensions to slice by (slot, position, campaign…). No user content, please. */
+    properties?: Record<string, unknown>;
+    /** Re-arm when the underlying content changes — required for RECYCLED list rows, which keep the
+     *  same component instance while showing different items. */
+    resetKey?: string | number;
+    children?: React.ReactNode;
+}
+export declare function ScaleBunImpression({ name, properties, resetKey, children, onLayout, ...rest }: ScaleBunImpressionProps): React.JSX.Element;
+//# sourceMappingURL=ScaleBunImpression.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * ScaleBun SDK — ScaleBunScrollView
+ *
+ * Instrumented ScrollView wrapper for scroll tracking.
+ * Feeds scroll events from actual scrollable surfaces into the SessionManager's
+ * ScrollTracker for proper settle detection, metadata accumulation, and
+ * post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunScrollView } from 'scalebun-react-native';
+ *
+ *   <ScaleBunScrollView style={{flex: 1}}>
+ *     {children}
+ *   </ScaleBunScrollView>
+ *
+ * Also works with FlatList / SectionList via renderScrollComponent:
+ *   <FlatList renderScrollComponent={props => <ScaleBunScrollView {...props} />} />
+ *
+ * This component is transparent — it passes all props through to the underlying
+ * ScrollView and does NOT consume or interfere with any scroll events.
+ */
+import React from 'react';
+import { ScrollView, type ScrollViewProps } from 'react-native';
+export declare const ScaleBunScrollView: React.ForwardRefExoticComponent<ScrollViewProps & React.RefAttributes<ScrollView>>;
+//# sourceMappingURL=ScaleBunScrollView.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * ScaleBun SDK — ScaleBunSectionList
+ *
+ * Instrumented SectionList wrapper for scroll tracking.
+ * Uses `renderScrollComponent` to inject ScaleBunScrollView so that all
+ * scroll events from the SectionList flow through the SessionManager's
+ * ScrollTracker for settle detection and post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunSectionList } from 'scalebun-react-native';
+ *
+ *   <ScaleBunSectionList sections={sections} renderItem={renderItem} />
+ *
+ * This component is transparent — it passes all props through to the
+ * underlying SectionList and does NOT consume or interfere with any scroll events.
+ */
+import React from 'react';
+import { SectionList, type SectionListProps } from 'react-native';
+export declare const ScaleBunSectionList: <T, S = any>(props: SectionListProps<T, S> & React.RefAttributes<SectionList<T, S>>) => React.ReactElement;
+//# sourceMappingURL=ScaleBunSectionList.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/calibrationContext.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ScaleBun SDK — Calibration Context (diagnostic-only)
+ *
+ * Lets a calibration screen stamp the *expected* target for the next gesture
+ * event so the SDK and dashboard can compare expected vs. captured coordinates.
+ *
+ * Pure observability: SessionManager merges these fields into the gesture
+ * payload but does NOT use them to adjust normalization, offsets, or marker
+ * placement. They flow through unchanged for the dashboard to display.
+ *
+ * TTL guards against a stale calibration target leaking onto a non-calibration
+ * gesture (e.g., the user taps a real button shortly after a calibration tap).
+ */
+export interface CalibrationTarget {
+    targetId: string;
+    expectedNX: number;
+    expectedNY: number;
+    setAt: number;
+}
+export declare function setCalibrationTarget(target: {
+    targetId: string;
+    expectedNX: number;
+    expectedNY: number;
+}): void;
+export declare function consumeCalibrationTarget(): CalibrationTarget | null;
+//# sourceMappingURL=calibrationContext.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * ScaleBun SDK — Gesture Buffer
+ *
+ * Ring buffer of recent gesture events with time-windowed matching.
+ * Used by JourneyManager to match desktop-requested gesture mode
+ * with the most recent matching gesture on the device.
+ */
+import type { GestureEvent, GestureMode } from './journeyTypes';
+export declare class GestureBuffer {
+    private buffer;
+    private maxSize;
+    constructor(maxSize?: number);
+    /** Push a gesture event into the buffer */
+    push(gesture: GestureEvent): void;
+    /**
+     * Find the most recent gesture matching the given type within the time window.
+     * Returns null if no match found.
+     */
+    matchRecent(type: GestureMode, windowMs?: number): GestureEvent | null;
+    /** Get all gestures within a time window */
+    getRecent(windowMs?: number): GestureEvent[];
+    /** Clear the buffer */
+    clear(): void;
+    /** Get current buffer size */
+    get size(): number;
+}
+//# sourceMappingURL=gestureBuffer.d.ts.map

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

@@ -0,0 +1,40 @@
+/**
+ * ScaleBun SDK — Gesture Detector
+ *
+ * Lightweight gesture detection using RN touch/scroll events.
+ * Feeds detected gestures into the GestureBuffer.
+ *
+ * Detection strategy:
+ * - Uses global touch responder events (non-brittle, no monkey-patching)
+ * - Back button via BackHandler
+ * - Text input via global event listener
+ */
+import type { TargetDescriptor } from './journeyTypes';
+import { GestureBuffer } from './gestureBuffer';
+export declare class GestureDetector {
+    private buffer;
+    private teardownFns;
+    private installed;
+    private touchStartTime;
+    private touchStartX;
+    private touchStartY;
+    private lastTapTime;
+    constructor(buffer: GestureBuffer);
+    /** Install gesture detection listeners. Idempotent. */
+    install(): void;
+    /** Record a touch event from the ScaleBunDebugRoot gesture layer */
+    handleTouchStart(x: number, y: number, target?: TargetDescriptor): void;
+    /** Record touch end from the ScaleBunDebugRoot gesture layer */
+    handleTouchEnd(x: number, y: number, target?: TargetDescriptor): void;
+    /** Record a scroll event from ScrollView/FlatList */
+    handleScroll(direction: 'up' | 'down' | 'left' | 'right', target?: TargetDescriptor): void;
+    /** Record a text input event */
+    handleTextInput(textLength: number, fieldId?: string): void;
+    /** Record a navigation event */
+    handleNavigation(screenName: string): void;
+    /** Teardown all listeners */
+    teardown(): void;
+    private _installBackHandler;
+    private _getSwipeDirection;
+}
+//# sourceMappingURL=gestureDetector.d.ts.map

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

@@ -0,0 +1,48 @@
+/**
+ * Impressions — "this element was actually seen".
+ *
+ * THE GAP. Web has had `$impression` via an IntersectionObserver on `[data-scalebun-track-impression]`
+ * since A2; mobile had no equivalent, so feed, carousel and list analytics ("was the promo ever on
+ * screen before they bounced?") were impossible. React Native has no IntersectionObserver, and there is
+ * no way for the SDK to observe an arbitrary host view without being mounted inside it — so, exactly
+ * like web, this is OPT-IN: the host marks what it wants counted.
+ *
+ * WHY THE MATH IS HERE. The viewability rule is pure geometry, and geometry is the part that is easy to
+ * get subtly wrong (a view scrolled half off the top is not "seen"). Keeping it in a plain function
+ * means it is unit-testable without a renderer, and the component around it stays a thin shell.
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Fraction of `el` that lies inside `viewport`, 0–1. Zero for degenerate or off-screen rects. */
+export declare function visibleFraction(el: Rect, viewport: Rect): number;
+/** The share of an element that must be on screen before it counts as seen. Matches web's threshold. */
+export declare const IMPRESSION_THRESHOLD = 0.5;
+/** How long it must stay that visible. A view flicking past during a fling was never really seen. */
+export declare const IMPRESSION_DWELL_MS = 250;
+export declare function isViewable(el: Rect, viewport: Rect, threshold?: number): boolean;
+/**
+ * Tracks one element's viewability over time and decides when to fire.
+ *
+ * Fires AT MOST ONCE per instance — an impression is "was this seen", not "how many times did it cross
+ * the line", and a list that scrolls back and forth would otherwise inflate the count several-fold.
+ * Time is injected so the dwell rule can be tested without waiting.
+ */
+export declare class ImpressionTracker {
+    private readonly onImpression;
+    private readonly threshold;
+    private readonly dwellMs;
+    private visibleSince;
+    private fired;
+    constructor(onImpression: (dwellMs: number) => void, threshold?: number, dwellMs?: number);
+    /** Feed a measurement. Safe to call as often as layout/scroll produces one. */
+    update(el: Rect, viewport: Rect, now: number): void;
+    /** True once this element has been counted. */
+    get hasFired(): boolean;
+    /** Forget the element entirely — used when a recycled list row is bound to new content. */
+    reset(): void;
+}
+//# sourceMappingURL=impression.d.ts.map

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

@@ -0,0 +1,159 @@
+/** One physical interaction, shared by replay and analytics projections. */
+export declare const INTERACTION_PROTOCOL_VERSION = 1;
+export type InteractionStateStatus = 'captured_empty' | 'captured_nonempty' | 'not_captured' | 'not_instrumented';
+export interface InteractionStartContext {
+    interactionId: string;
+    occurredAt: number;
+    x: number;
+    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 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/journeyManager.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ScaleBun SDK — Journey Manager
+ *
+ * Core orchestrator for journey recording and running.
+ * Coordinates gesture buffer, nav detector, screenshot helper,
+ * and transport to implement the full journey lifecycle.
+ */
+import type { DebugTransport } from '../../debug/transport';
+import type { JourneyConfig, JourneyStep } from './journeyTypes';
+import { GestureDetector } from './gestureDetector';
+import { NavDetector } from './navDetector';
+import { ScreenshotHelper } from './screenshotHelper';
+export declare class JourneyManager {
+    private transport;
+    private config;
+    private gestureBuffer;
+    private gestureDetector;
+    private navDetector;
+    private screenshotHelper;
+    private _isRecording;
+    private _journeyTempId;
+    private _steps;
+    private _stepIndex;
+    private _isRunning;
+    private _runId;
+    private _stopRunFlag;
+    private static _instance;
+    constructor(transport: DebugTransport, config?: JourneyConfig);
+    /** Singleton factory — idempotent */
+    static getInstance(transport: DebugTransport, config?: JourneyConfig): JourneyManager;
+    /** Reset singleton (for teardown) */
+    static resetInstance(): void;
+    get isRecording(): boolean;
+    get isRunning(): boolean;
+    get steps(): JourneyStep[];
+    get currentScreen(): string;
+    get detector(): GestureDetector;
+    get nav(): NavDetector;
+    get screenshot(): ScreenshotHelper;
+    /** Initialize the journey system. Called by ScaleBunDebugRoot on mount. */
+    initialize(rootRef?: any): void;
+    startRecording(): void;
+    stopRecording(): void;
+    /** Capture a step — matches gesture from buffer + takes screenshot */
+    captureStep(gestureMode: string, label?: string, note?: string): Promise<{
+        success: boolean;
+        data?: Record<string, unknown>;
+        error?: string;
+    }>;
+    saveJourney(name: string, journeyId?: string): Promise<{
+        success: boolean;
+        data?: Record<string, unknown>;
+        error?: string;
+    }>;
+    runJourney(journeyData: any, options?: any): Promise<void>;
+    stopRun(): void;
+    teardown(): void;
+    private _emitDebugReady;
+    private _emitEvent;
+    private _generateId;
+}
+//# sourceMappingURL=journeyManager.d.ts.map