@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,74 @@
+/**
+ * ScaleBun SDK — Journey Event Pipeline
+ *
+ * Bounded ring buffer for session events with:
+ * - Configurable max capacity
+ * - Backpressure: drops lowest-priority events when full
+ * - Crash-adjacent/error events are preserved over generic events
+ * - Canonical event creation with deduplication
+ * - Event emission callback for transport
+ */
+import type { JourneyEvent, JourneyEventType, JourneyEventSeverity, JourneyEventSource, SessionArtifactIndex, CrashAnchor } from './sessionTypes';
+export type EventEmitCallback = (event: JourneyEvent) => void;
+interface PipelineConfig {
+    maxEventCount: number;
+    /** Window for crash anchoring: how many events either side of a crash to protect */
+    crashAnchorWindow: number;
+    /** Minimum ms between identical events to avoid rapid-fire duplicates */
+    dedupeWindowMs: number;
+}
+export declare class JourneyEventPipeline {
+    private events;
+    private config;
+    private sessionId;
+    private onEmit;
+    /** Set of eventIds that are crash-anchored (never drop) */
+    private protectedEventIds;
+    /** Track last event type+subtype+ts+confidence for dedup */
+    private lastEventKey;
+    private lastEventTs;
+    private lastEventConfidence;
+    constructor(sessionId: string, config?: Partial<PipelineConfig>);
+    /** Set the callback invoked when an event is added */
+    setEmitCallback(cb: EventEmitCallback): void;
+    /** Get all events (read-only snapshot) */
+    getEvents(): readonly JourneyEvent[];
+    /** Current event count */
+    get count(): number;
+    /**
+     * Create and add a canonical event.
+     * Handles deduplication, retention, and emission.
+     */
+    emit(type: JourneyEventType, opts?: {
+        subtype?: string;
+        severity?: JourneyEventSeverity;
+        screen?: string;
+        payload?: Record<string, unknown>;
+        correlationId?: string;
+        traceId?: string;
+        source?: JourneyEventSource;
+        journeyId?: string;
+        /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
+        frameId?: string;
+        timestamp?: number;
+    }): JourneyEvent | null;
+    /**
+     * Anchor a crash event — protect nearby events from eviction.
+     */
+    anchorCrash(crashEventId: string): CrashAnchor;
+    /**
+     * Build the event portion of the artifact index.
+     */
+    buildEventRefs(): Pick<SessionArtifactIndex, 'eventRefs' | 'networkRefs' | 'logRefs'>;
+    /** Clear all events (used on session end) */
+    clear(): void;
+    private _replaceLastEvent;
+    private _addEvent;
+    /**
+     * Evict the oldest event with the lowest retention priority,
+     * skipping crash-anchored/protected events.
+     */
+    private _evictLowestPriority;
+}
+export {};
+//# sourceMappingURL=JourneyEventPipeline.d.ts.map

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

@@ -0,0 +1,391 @@
+/**
+ * ScaleBun SDK — Replay Capture Manager
+ *
+ * Orchestration-only component for frame capture:
+ * - Decides WHEN to capture (navigation, interaction, scroll, loading, frequency triggers)
+ * - Delegates ALL frame capture to native engines via sessionReplayAdapter
+ * - NEVER performs screenshot logic itself
+ * - If native capture unavailable, returns null and logs warning
+ * - Manages frame retention with crash-adjacent priority
+ * - Uses session-bound generation guard to invalidate stale async work
+ * - All pending timers are cancelled on stop()
+ *
+ * Semantic Capture Coordination:
+ * - Tracks the last completed capture's reason + screen to prevent semantic duplicates
+ * - Navigation supersedes pending interaction for the SAME screen (interaction is already
+ *   visually represented by the navigation frame)
+ * - Loading completion for the SAME screen coalesces with a pending navigation capture
+ *   by cancelling the navigation capture (loading's delayed capture shows the final state)
+ * - Scroll captures have per-cycle identity and do not conflict with navigation/loading
+ * - Manual and error-context captures ALWAYS bypass coordination (explicit intent)
+ * - Genuinely distinct states (different screens, different reasons after settle) are never deduped
+ */
+import type { ReplayFrame, CaptureReason, ReplayQuality, SessionReplayConfig, NativeFrameResult } from './sessionTypes';
+import type { PlatformOS } from '../../core/context/device';
+import type { FrameScrollEntry } from './frameScrollState';
+/**
+ * Native capture function provided by the adapter layer.
+ * Calls the platform native engine (PixelCopy on Android, UIWindow on iOS).
+ * Returns null if native capture is unavailable.
+ */
+export type NativeCaptureFn = (sessionId: string, reason: string, quality: ReplayQuality) => Promise<NativeFrameResult | null>;
+export type FrameEmitCallback = (frame: ReplayFrame, imageData: string) => void;
+/**
+ * How a wait ended. Named for what was OBSERVED, not for what it probably meant.
+ *
+ * `network_idle` is the only one that says the screen arrived, and even that is an inference from
+ * quiet rather than a look at the pixels. `timeout` is its opposite and must never be collapsed
+ * into it: the cap expired with requests still outstanding, so the screen was still loading when
+ * we gave up waiting and photographed it anyway. A band drawn from a `timeout` is evidence of a
+ * slow or stuck screen; one drawn from `network_idle` is evidence of an ordinary load.
+ */
+export type LoadingEndReason = 'network_idle' | 'timeout' | 'superseded' | 'session_end'
+/** Capture paused mid-session by a `frames` quota block — the session did NOT end. */
+ | 'quota_pause';
+/**
+ * Reports a wait the capture manager sat through, so it can be recorded as a journey event.
+ * Two calls per wait — one `start`, one `end` — and NO calls at all when nothing was held,
+ * which is the common case and the reason this costs almost nothing.
+ */
+export type LoadingIntervalCallback = (phase: 'start' | 'end', screen: string | undefined, detail: {
+    durationMs?: number;
+    reason?: LoadingEndReason;
+}) => void;
+/**
+ * Metadata returned by a native STAGED capture-to-file. The image bytes are
+ * already written to the native outbox (staged, not yet uploadable) — they NEVER
+ * cross the bridge. `frameHash` is a native content hash so JS change-detection
+ * works without base64.
+ */
+export interface StagedFrameResult {
+    frameId: string;
+    width: number;
+    height: number;
+    byteSize: number;
+    format: string;
+    contentType: string;
+    frameHash: string;
+    masked: boolean;
+    timestamp: number;
+    platform: PlatformOS;
+    /** Sanitized visible scroll containers at capture time; undefined = not measured. */
+    scrollState?: FrameScrollEntry[];
+}
+/** JS-authoritative frame metadata written to the outbox on commit. */
+export interface OutboxFrameMeta {
+    frameId: string;
+    sessionId: string;
+    timestamp: number;
+    sequenceNumber: number;
+    frameType: 'keyframe' | 'delta';
+    baseFrameId?: string;
+    screenName: string;
+    trigger: string;
+    format: string;
+    contentType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    masked: boolean;
+    /** Visible scroll containers at capture time — the native uploader forwards it verbatim. */
+    scrollState?: FrameScrollEntry[];
+}
+/**
+ * Native file-outbox frame capture. `capture` stages an image and returns metadata
+ * only (or null when the outbox is off / capture fails → caller falls back to the
+ * legacy native capture). `commit` writes the JS-decided meta (making the frame
+ * uploadable); `discard` drops a staged frame the orchestrator suppressed.
+ */
+export interface OutboxFrameCapture {
+    capture(sessionId: string, screenName: string | undefined, trigger: string): Promise<StagedFrameResult | null>;
+    commit(meta: OutboxFrameMeta): Promise<boolean>;
+    discard(sessionId: string, frameId: string): Promise<void>;
+}
+export declare class ReplayCaptureManager {
+    private sessionId;
+    private config;
+    private nativeCapture;
+    /** Optional native file-outbox path. When ready, frames stage→commit natively. */
+    private outboxCapture;
+    private onFrameEmit;
+    private onLoadingInterval;
+    private frames;
+    /** Set of frameIds near crashes — never evict */
+    private protectedFrameIds;
+    private frequencyTimer;
+    private capturing;
+    private currentScreen;
+    private lastInteractionCapture;
+    /**
+     * App network activity, as reported by the interceptors (SDK uploads and third-party
+     * beacons are filtered out upstream — see NetworkFeature). This is the only evidence the
+     * capture manager has that a screen is still waiting for something, and it is used for
+     * nothing but deciding WHEN to take the frame it was already going to take.
+     *
+     * Zero when network monitoring is disabled, which makes every hold below evaluate to "fire
+     * now" — the deferral costs nothing and changes nothing when there is no signal to act on.
+     */
+    private _inFlightRequests;
+    private _lastRequestStartTs;
+    private _lastRequestEndTs;
+    /** Epoch ms past which a capture held for loading fires regardless. 0 when nothing is held. */
+    private pendingInteractionDeadline;
+    private pendingNavDeadline;
+    private activityTimer;
+    private activityGen;
+    private activityWindowEnd;
+    private activitySamples;
+    private activityUnchangedStreak;
+    private activityMinuteStart;
+    private activityMinuteCount;
+    /**
+     * When each lane's hold began, or 0 when that lane is not holding.
+     *
+     * ── WHY THE WAIT IS RECORDED AND NOT JUST WAITED OUT ──────────────────────────────────────
+     *
+     * Deferring the capture makes the replay show the loaded screen, which is the right picture —
+     * but between the tap and that frame the player has nothing, and `frameAt` resolves a playhead
+     * to the last frame at or before it. So the gap renders as the PREVIOUS screen, and the replay
+     * quietly asserts the visitor was still looking at it while they were in fact watching this one
+     * load. That is the same defect as a recording gap rendered as idle time: the reader cannot
+     * tell "nothing happened" from "we did not photograph it".
+     *
+     * The alternative — keep the skeleton frame as well — costs a whole mobile screenshot (~56 KB
+     * measured) against ~1 KB for the pair of events below, on a screen load where 37% of this
+     * product's loads would qualify. So the wait is recorded as an INTERVAL and the picture is not
+     * duplicated: the player draws the span, the operator sees that the screen was loading and for
+     * how long, and no frame claims to be something it is not.
+     */
+    private navHoldStartedAt;
+    private interactionHoldStartedAt;
+    /**
+     * Session-bound generation counter.
+     * Incremented on stop(). All async capture work checks this before AND after
+     * native capture to ensure stale callbacks from a previous session lifecycle
+     * do not emit frames into a new session.
+     */
+    private captureGeneration;
+    /**
+     * Tracked navigation capture timeout.
+     * Cancelled on stop() and on each new onScreenChange() call (debounce).
+     */
+    private pendingNavTimeout;
+    /** Screen associated with the pending navigation capture */
+    private pendingNavScreen;
+    /**
+     * Tracked scroll settle capture timeout.
+     * Cancelled on stop().
+     */
+    private pendingScrollTimeout;
+    /**
+     * Tracked loading end capture timeout.
+     * Cancelled on stop().
+     */
+    private pendingLoadingTimeout;
+    /** Screen associated with the pending loading capture */
+    private pendingLoadingScreen;
+    /**
+     * Pending interaction capture timeout.
+     * When a tap/gesture occurs, the capture is DEFERRED by INTERACTION_SETTLE_MS.
+     * If onScreenChange fires within that window (tap caused navigation), the
+     * pending interaction is cancelled and its tap metadata is carried forward
+     * to the navigation capture — ensuring the destination screen is captured
+     * instead of a stale pre-navigation screenshot.
+     * If no navigation follows, the interaction capture fires normally.
+     */
+    private pendingInteractionTimeout;
+    /** Interaction point metadata held while pending (carried to nav if absorbed) */
+    private pendingInteractionPoint;
+    /** Screen at the time the pending interaction was created */
+    private pendingInteractionScreen;
+    /**
+     * Late absorption tracking.
+     * After an interaction capture fires, store its metadata so that
+     * a delayed onScreenChange can retroactively evict the stale frame
+     * and carry the tap metadata forward to the navigation capture.
+     */
+    private lastCompletedInteraction;
+    /**
+     * In-flight interaction tracking.
+     * Set when triggerCapture('interaction') starts the async native call and cleared
+     * when it completes. If onScreenChange fires for a DIFFERENT screen while a capture
+     * is in-flight, the capture is suppressed — the navigation frame is the correct state.
+     * Covers the race window between pendingInteractionTimeout firing and native returning,
+     * which neither pending-absorption nor late-absorption can reach.
+     */
+    private _inFlightInteractionScreen;
+    private _inFlightInteractionPoint;
+    private _suppressInFlightInteraction;
+    /**
+     * Last completed capture intent — used for semantic dedup.
+     * Captures with the same reason + screen within SAME_INTENT_COOLDOWN_MS are suppressed.
+     */
+    private lastCaptureIntent;
+    /** P2-0: monotonic per-session sequence; first emitted frame is 1. */
+    private _sequenceCounter;
+    /** P2-1: hash of the last EMITTED frame, for visual change detection. */
+    private _lastFrameHash;
+    /** P2-1/5: wall-clock of the last emitted keyframe (heartbeat base). */
+    private _lastKeyframeTs;
+    /** Scroll containers visible in the last keyframe (native), so a tap's link to it can be checked. */
+    private _lastKeyframeScroll;
+    /** P2-5: frameId of the last emitted keyframe — delta base reference. */
+    private _lastKeyframeId;
+    /**
+     * Screen the last emitted keyframe was captured on.
+     *
+     * Tracked alongside the id purely so `currentKeyframe()` can refuse to hand a frame to an
+     * event on a different screen. The id and timestamp alone cannot answer that, and a frame
+     * from the previous screen is worse than none — it attaches a tap to a photograph of
+     * somewhere else, which every layer downstream would then present with full confidence.
+     */
+    private _lastKeyframeScreen;
+    /** P2-5: emitted frames since the last keyframe (keyframe-interval guard). */
+    private _framesSinceKeyframe;
+    constructor(sessionId: string, config: SessionReplayConfig, nativeCapture: NativeCaptureFn, outboxCapture?: OutboxFrameCapture | null);
+    /**
+     * The keyframe that is still showing, or null.
+     *
+     * Answers "which picture was the user looking at" for an event that is about to be emitted,
+     * so a tap can carry the id of the frame it happened ON. Read-only; captures nothing.
+     *
+     * TWO CONDITIONS, both refusals rather than approximations:
+     *
+     *   SAME SCREEN. A keyframe from the previous screen is not what the user was looking at.
+     *   Navigation evicts the pending capture rather than re-pointing it, so after a screen
+     *   change the newest keyframe genuinely belongs to somewhere else.
+     *
+     *   STILL FRESH. A screen mutates constantly — a list loads, a banner rotates, a sheet is
+     *   dismissed. Past `maxAgeMs` the stored picture stops being evidence of what is on screen,
+     *   and stale evidence presented as current is the failure mode this whole feature exists to
+     *   avoid. 10 s is deliberately conservative: the capture manager already photographs on
+     *   interaction, navigation and scroll settle, so a genuinely active screen refreshes well
+     *   inside it, and a screen quiet for longer than that is one nobody is interacting with.
+     *
+     * Returning null is a correct, common answer and downstream MUST treat it as "not captured"
+     * rather than as a default.
+     */
+    currentKeyframe(screenName?: string, maxAgeMs?: number, now?: number): {
+        frameId: string;
+        screen: string | null;
+        capturedAt: number;
+        scrollState?: FrameScrollEntry[];
+    } | null;
+    /** Set callback for when a frame is captured */
+    setFrameEmitCallback(cb: FrameEmitCallback): void;
+    /** Set the callback that turns a held wait into LOADING_STARTED / LOADING_COMPLETED events. */
+    setLoadingIntervalCallback(cb: LoadingIntervalCallback): void;
+    /**
+     * Open a wait on one lane. Idempotent per lane: a hold is re-checked every NETWORK_QUIET_MS
+     * while it lasts, and each re-check must not open a new interval.
+     */
+    private _openHold;
+    /**
+     * Close a wait, if one is open on that lane.
+     *
+     * EVERY path that abandons a pending capture calls this, because an interval with no end is
+     * a claim the player cannot draw and cannot disprove — it would either render as an
+     * open-ended band running to the end of the session, or be dropped, and neither is what
+     * happened. `superseded` and `session_end` exist precisely so those paths have something
+     * truthful to say rather than staying silent.
+     */
+    private _closeHold;
+    /** Start capture according to configured mode */
+    start(): void;
+    /**
+     * Resume capture WITHIN the same session after a pause (a `frames` quota block that lifted).
+     *
+     * Differs from `start()` on purpose: the sequence counter is KEPT, so frames after the pause
+     * continue the session's ordering instead of restarting at 0 and colliding with frames already
+     * stored. The keyframe base is FORGOTTEN, because every frame captured before the pause that was
+     * still queued was discarded — a delta against it would be unplayable. The next frame is
+     * therefore a keyframe.
+     */
+    resume(): void;
+    get isCapturing(): boolean;
+    private _startFrequencyTimer;
+    /** Stop capture — cancels ALL pending timers and increments generation */
+    stop(reason?: LoadingEndReason): void;
+    /**
+     * Report app network activity. Called by NetworkFeature for requests the app itself made —
+     * SDK telemetry uploads and third-party beacons are excluded there, and must stay excluded:
+     * this SDK uploads frames, so counting its own traffic would mean a screen never goes quiet.
+     *
+     * Advisory only. It never causes a capture, it only decides when one that was already going
+     * to happen actually fires. A missed or duplicated call therefore costs a slightly early or
+     * slightly late frame, never a wrong or an extra one — which is why it is deliberately a
+     * counter and not a per-request registry.
+     */
+    onNetworkActivity(phase: 'start' | 'end'): void;
+    /**
+     * How much longer a capture triggered at `triggeredAt` should wait for the screen's data,
+     * or 0 to fire now.
+     *
+     * The question is not "is the app busy" but "is the app still fetching what this tap asked
+     * for". So a request that was already running when the tap happened does not hold anything:
+     * a background poll or an in-progress upload would otherwise hold every capture to the cap
+     * and make the replay LATE instead of empty, which is not an improvement. Only activity that
+     * began at or after the trigger counts.
+     *
+     * (A poll whose next tick happens to land just after the tap is indistinguishable from a
+     * fetch the tap caused, and will hold. That is bounded by the cap and produces a frame of a
+     * settled screen either way, so it is accepted rather than guessed at.)
+     */
+    private _loadingHoldMs;
+    /** Notify of a screen change — triggers cancellable delayed capture */
+    onScreenChange(screenName: string): void;
+    /**
+     * Notify of a user interaction — deferred capture with navigation absorption.
+     *
+     * Instead of capturing immediately (which would snapshot the OLD screen
+     * when the tap causes navigation), the capture is deferred by
+     * INTERACTION_SETTLE_MS. If onScreenChange fires within that window,
+     * the pending interaction is absorbed into the navigation capture.
+     * If no navigation follows, the interaction capture fires normally.
+     */
+    onInteraction(interactionPoint?: ReplayFrame['interactionPoint']): void;
+    /** Notify of scroll settle — triggers delayed capture for post-scroll state */
+    onScrollSettle(screenName?: string): void;
+    /** Notify of loading end — captures the settled loaded screen */
+    onLoadingEnd(screenName?: string): void;
+    /** Manual capture trigger (e.g. error-context) */
+    captureManual(reason: CaptureReason): Promise<ReplayFrame | null>;
+    /** Protect frames near a crash from eviction */
+    protectFramesNearCrash(crashTimestamp: number, windowMs?: number): string[];
+    /** Get all frames (read-only snapshot) */
+    getFrames(): readonly ReplayFrame[];
+    /** Get frame IDs for artifact index */
+    getFrameRefs(): string[];
+    /** Current frame count */
+    get count(): number;
+    /** Clear all frames */
+    clear(): void;
+    /**
+     * Trigger a frame capture via native engine.
+     * This method ONLY orchestrates — native does the real work.
+     *
+     * Semantic dedup: if the last completed capture has the same reason + screen
+     * and happened within SAME_INTENT_COOLDOWN_MS, the capture is suppressed.
+     * Bypass reasons (manual, error-context, frequency) skip this check entirely.
+     *
+     * Session-bound generation guard: captures the generation counter before
+     * starting the async native capture and verifies it hasn't changed after.
+     * If it has, the capture result is silently discarded — the session that
+     * requested it no longer exists.
+     */
+    private triggerCapture;
+    /**
+     * (Re)open the sampling window after a semantic frame. Only in `interactions` mode: `frequency`
+     * already samples on its own timer, and `navigation` mode is the deliberately minimal one. Needs
+     * change detection — without it every sample would upload, which is the old cost.
+     */
+    private _openActivityWindow;
+    private _activityTick;
+    /**
+     * Evict the frame with the lowest retention priority.
+     * Crash-adjacent and error-context frames are NEVER evicted before generic frames.
+     */
+    private _evictLowestPriorityFrame;
+    private _isExcludedScreen;
+}
+//# sourceMappingURL=ReplayCaptureManager.d.ts.map

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

@@ -0,0 +1,48 @@
+/**
+ * ScaleBun SDK — Scroll Tracker
+ *
+ * Dedicated scroll tracking with settle detection.
+ * Tied to actual scrollable surfaces (ScrollView/FlatList/SectionList)
+ * via the ScaleBunScrollView wrapper — NOT root-level touch tracking.
+ *
+ * Behavior:
+ * - Accumulates scroll delta from onScroll events
+ * - Applies minimum threshold (30px) to filter tiny incidental movements
+ * - Uses 250ms idle window to determine scroll end (settle detection)
+ * - On settle: invokes callback with structured metadata
+ * - Session-bound: dispose() cancels all pending timers
+ * - Resets between scroll gestures
+ */
+export interface ScrollMetadata {
+    totalDeltaX: number;
+    totalDeltaY: number;
+    dominantDirection: 'up' | 'down' | 'left' | 'right';
+    startTs: number;
+    endTs: number;
+    durationMs: number;
+}
+export type ScrollSettleCallback = (metadata: ScrollMetadata) => void;
+export declare class ScrollTracker {
+    private onSettle;
+    private totalDeltaX;
+    private totalDeltaY;
+    private startTs;
+    private lastEventTs;
+    private tracking;
+    private previousOffsetX;
+    private previousOffsetY;
+    private hasBaseline;
+    private settleTimer;
+    private disposed;
+    constructor(onSettle: ScrollSettleCallback);
+    /**
+     * Called by ScaleBunScrollView on each scroll event.
+     * Computes delta from content offset changes and accumulates.
+     */
+    onScrollEvent(contentOffsetX: number, contentOffsetY: number): void;
+    /** Cancel all pending state. Called on session end. */
+    dispose(): void;
+    private _onSettle;
+    private _resetGesture;
+}
+//# sourceMappingURL=ScrollTracker.d.ts.map