@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,414 @@
+/**
+ * ScaleBun SDK — Session Manager
+ *
+ * Central orchestrator for the unified session system.
+ * Manages session lifecycle, wires pipeline + capture + transport + sync.
+ *
+ * Architecture:
+ * - Singleton per debug session
+ * - Creates and owns JourneyEventPipeline, ReplayCaptureManager,
+ *   DesktopSessionTransport, SyncDecisionEngine
+ * - Receives events from ScaleBunDebugRoot (nav, interactions), DebugEventStream
+ *   (network, logs), and breadcrumbs
+ * - Coordinates crash anchoring across events AND frames
+ * - Auto-timeout via maxDurationMs
+ */
+import type { DebugTransport } from '../../debug/transport';
+import type { SessionMetadata, SessionReplayConfig, JourneyEventType, JourneyEventSeverity, JourneyEventSource, CrashAnchor, NativeSyncMetadata, SyncDecisionCallback } from './sessionTypes';
+import { type NativeCaptureFn } from './ReplayCaptureManager';
+import type { BackendSessionAdapter } from './BackendSessionAdapter';
+import { type InteractionStateStatus } from '../journey/interactionProtocol';
+export interface SessionManagerConfig {
+    sessionReplay?: Partial<SessionReplayConfig>;
+    syncPolicy?: SyncDecisionCallback;
+    /**
+     * Feature #4 (heatmaps): when true, tap/gesture coordinates are ALSO routed
+     * to the always-on analytics lane so coords are captured even when no replay
+     * recording is active. Additive — does NOT change replay-recording capture.
+     * Unset → false at this layer (safety floor for direct construction); the
+     * product default (true) is applied by ConfigSchema and passed in by the
+     * bootstrapper. See ConfigSchema.captureInteractionHeatmap.
+     */
+    captureInteractionHeatmap?: boolean;
+}
+export declare class SessionManager {
+    private desktopTransport;
+    private pipeline;
+    private captureManager;
+    private syncEngine;
+    private scrollTracker;
+    private _backendTransport;
+    private config;
+    /**
+     * Feature #4 (heatmaps): route tap/gesture coords to the always-on analytics
+     * lane even when no replay recording is active. Additive, opt-in (default off).
+     */
+    private _captureInteractionHeatmap;
+    private session;
+    private active;
+    private timeoutTimer;
+    private crashAnchors;
+    /** Tracks loading-start timestamps per screen for duration computation */
+    private loadingStartTimes;
+    /**
+     * Always-tracked current screen name.
+     * Updated by onScreenChange even when session is inactive, so that when
+     * startSession is called we know what screen the user is currently on and
+     * can emit the initial SCREEN_VIEW + navigation capture immediately.
+     * This is read-only metadata — does NOT produce events or frames while inactive.
+     */
+    private _lastKnownScreen;
+    /** When the current screen was entered — the basis for SCREEN_EXIT's measured dwellMs. */
+    private _screenEnteredAt;
+    /**
+     * Last screenshot-base dimensions reported by the native interaction tracker.
+     * Stored in JS-coordinate units (dp on Android, pt on iOS) — both are the same
+     * unit RN uses for pageX/pageY, so JS-fallback taps can divide directly without
+     * additional conversion. This is the EXACT base the native screenshot is captured
+     * in, and avoids using Dimensions.get('window') (which excludes system insets
+     * differently across devices and pushes markers ~10% off vertically).
+     */
+    private _lastNativeViewportJsUnits;
+    /**
+     * Exact-duplicate gesture suppression (QA: one physical tap recorded 2–3×).
+     *
+     * Measured in production data: the native tracker re-emitted the SAME tap — identical
+     * gestureType and identical coordinates to the SUB-PIXEL (e.g. x=466.962890625) — at
+     * 160–240ms gaps, sometimes twice. A human re-tap cannot reproduce a sub-pixel float
+     * exactly, so exact coordinate equality within the window is a safe discriminator: real
+     * double-taps land on at least slightly different pixels and pass through untouched.
+     * The pipeline's own 100ms dedup was too narrow for these; this window covers what was
+     * actually observed with margin. Sits at the ONE entry point every gesture source funnels
+     * through, so recording and analytics lanes are protected equally.
+     */
+    private _lastGestureSig;
+    private _lastGestureTs;
+    private static readonly GESTURE_DEDUP_WINDOW_MS;
+    private _nativeCapture;
+    private _rawTransport;
+    /** Memoized native file-outbox frame adapter (gated by the backend transport). */
+    private _outboxFrameCapture;
+    /** Unsubscribe from quotaState (released in resetInstance). */
+    private _quotaUnsub;
+    /** True while frame capture is paused by a `frames` quota block inside an active session. */
+    private _framesQuotaPaused;
+    /**
+     * Whether capture has run at all in the CURRENT session. Decides start() vs resume() when a
+     * frames block lifts: resume() continues the session's sequence, which is only right if this
+     * session already produced frames; a session that began blocked gets a clean start().
+     */
+    private _captureStartedThisSession;
+    constructor(debugTransport: DebugTransport | null, nativeCapture: NativeCaptureFn, managerConfig?: SessionManagerConfig);
+    /**
+     * Stop or resume frame capture for a `frames` quota block.
+     *
+     * Stopping goes through `captureManager.stop()` — every pending capture timer is cancelled and
+     * the generation bump discards captures already in flight. The adapter purges what was queued.
+     * The session itself keeps running: events, network and errors are governed by their own quotas.
+     */
+    private _onFramesQuota;
+    /**
+     * A wait the capture manager sat through becomes a pair of journey events.
+     *
+     * The frame it eventually takes shows the LOADED screen, which leaves the span between the
+     * tap and that frame unaccounted for — and the player resolves an unaccounted playhead to the
+     * previous frame, so it would show the screen the visitor had already left. These two events
+     * are what lets the timeline say "this screen was loading, for this long" instead, at roughly
+     * 1 KB against the ~56 KB a second screenshot would cost.
+     *
+     * `reason` rides on the payload rather than becoming a third event type: `timeout` and
+     * `network_idle` are the same interval with different endings, and a consumer that does not
+     * know about the distinction should still see the band.
+     */
+    private _wireLoadingIntervals;
+    static getInstance(debugTransport: DebugTransport | null, nativeCapture: NativeCaptureFn, config?: SessionManagerConfig): SessionManager;
+    static getExistingInstance(): SessionManager | null;
+    static resetInstance(): void;
+    /**
+     * Attach a backend transport for uploading replay data to the backend API.
+     * This is additive — the existing desktop transport remains active if present.
+     */
+    setBackendTransport(transport: BackendSessionAdapter): void;
+    /** Expose the backend transport so features can queue network/errors/performance. */
+    getBackendTransport(): BackendSessionAdapter | null;
+    /**
+     * Memoized native file-outbox frame adapter. Always injected into the capture
+     * manager; its readiness gate (backed by the backend transport) resolves false
+     * when the outbox flags are off / the binary is old, so capture transparently
+     * falls back to the legacy `captureScreenshot` path. The closure reads the
+     * backend transport lazily at capture time (it attaches after construction).
+     */
+    private _getOutboxFrameCapture;
+    /**
+     * Attach a desktop transport dynamically.
+     * Called when debug mode connects after SDK initialization.
+     */
+    setDesktopTransport(debugTransport: DebugTransport): void;
+    get isActive(): boolean;
+    get currentSessionId(): string | null;
+    get currentSessionMetadata(): SessionMetadata | null;
+    /**
+     * The active RECORDING session ID (`ses-xxx`), or null when no recording
+     * is in progress.
+     *
+     * This is the canonical field that DebugEventStream stamps into every
+     * outgoing event's `data.recordingSessionId`. It is the single source of
+     * truth for correlating network and performance events with the session
+     * that was active when they were captured.
+     *
+     * Distinct from the TRANSPORT session ID (`debug-xxx`) which lives on
+     * the wire envelope's top-level `sessionId` field and never changes.
+     */
+    get recordingSessionId(): string | null;
+    /**
+     * Update the native capture function at runtime.
+     * Called by ScaleBunDebugRoot once the root View ref is ready for ViewShot.
+     * Also updates the active session's capture manager if one exists.
+     */
+    setNativeCapture(captureFn: NativeCaptureFn): void;
+    /**
+     * Start a new session. Idempotent — no-op if already active.
+     */
+    startSession(metadata?: Partial<SessionMetadata>): void;
+    /**
+     * End the current session.
+     */
+    endSession(reason?: 'ended' | 'timeout'): void;
+    /**
+     * Resolve the dp-space base used to normalize JS-fallback tap coordinates.
+     *
+     * The screenshot is captured by native in the content-view at its physical
+     * pixel size. Normalized coords must divide by that SAME region (converted
+     * to dp, since pageX/pageY are dp). Using Dimensions.get('window') (or
+     * session.metadata, which is seeded from it) excludes system insets and is
+     * ~10% smaller than the content-view — pushing markers off. Preference order:
+     * native content-view (px→dp) → session metadata → payload → Dimensions.
+     */
+    private _resolveNormalizationBaseDp;
+    /**
+     * Inject/resolve normalized tap coordinates into a USER_ACTION payload, in place.
+     *
+     * Mutates `p` to carry normalizedX/Y (+ end coords for swipes/scrolls) so the
+     * heatmap can overlay them across viewport sizes. Returns true when the source
+     * already provided high-confidence / pre-computed normalized coords (native or
+     * JS-root-measured), false when this method JS-estimated them.
+     *
+     * Extracted from emitEvent so BOTH the replay-recording lane AND the always-on
+     * analytics lane (Feature #4) normalize identically — keeping the tap payload
+     * keys byte-for-byte the same on both routes.
+     */
+    private _normalizeInteractionPayload;
+    /**
+     * Feature #4 (heatmaps) — additive analytics emission.
+     *
+     * Routes a tap/gesture to the always-on ANALYTICS lane (BackendSessionAdapter
+     * .trackEvent) so coords are captured even when no replay recording is active.
+     *
+     * Strictly additive and isolated:
+     *   - Only runs when `_captureInteractionHeatmap` is ON (opt-in flag) AND a
+     *     backend analytics transport is attached AND no recording is active
+     *     (when active, the recording lane already emits the SAME USER_ACTION —
+     *     emitting here too would duplicate it).
+     *   - Reuses the EXACT recording payload shape (USER_ACTION + the same keys:
+     *     normalizedX, normalizedY, gestureType, screen, …) so the backend
+     *     aggregate reads them identically (no protocol/schema change).
+     *   - Normalizes via the same _normalizeInteractionPayload used by recording.
+     *   - Respects redaction: payload is passed through redactBody so any caller-
+     *     injected sensitive keys (e.g. a label) are stripped before transport.
+     *   - Never throws.
+     */
+    private _emitInteractionToAnalytics;
+    /**
+     * Emit a canonical event into the session pipeline.
+     * This is the primary entry point for all event sources.
+     */
+    emitEvent(type: JourneyEventType, opts?: {
+        subtype?: string;
+        severity?: JourneyEventSeverity;
+        screen?: string;
+        payload?: Record<string, unknown>;
+        correlationId?: string;
+        traceId?: string;
+        source?: JourneyEventSource;
+        journeyId?: string;
+        /** Original observation time; interaction capture may resolve asynchronously. */
+        timestamp?: number;
+    }): void;
+    /**
+     * Anchor a crash in the session context.
+     * Protects nearby events and frames from eviction.
+     */
+    anchorCrash(crashEventId: string): CrashAnchor | null;
+    /**
+     * Notify of a screen change. Called by ScaleBunDebugRoot via NavDetector.
+     */
+    /** The screen currently on top, or null before the first navigation is observed. */
+    getLastKnownScreen(): string | null;
+    onScreenChange(screenName: string): void;
+    /**
+     * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
+     * Also triggers frame capture for desktop-initiated recordings.
+     */
+    onUserAction(subtype: string, payload?: Record<string, unknown>, context?: {
+        screen?: string;
+        timestamp?: number;
+    }): void;
+    /**
+     * Detailed gesture detection — called by ScaleBunDebugRoot touch handlers.
+     * Emits a USER_ACTION event with gesture-specific subtype and payload.
+     */
+    onGestureDetected(gestureType: string, details?: {
+        x?: number;
+        y?: number;
+        endX?: number;
+        endY?: number;
+        duration?: number;
+        durationMs?: number;
+        direction?: string;
+        target?: string;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        pageX?: number;
+        pageY?: number;
+        locationX?: number;
+        locationY?: number;
+        normalizedX?: number;
+        normalizedY?: number;
+        normalizedEndX?: number;
+        normalizedEndY?: number;
+        confidence?: string;
+        coordinateSpace?: string;
+        source?: string;
+        normalizedPrecomputed?: boolean;
+        statusBarHeight?: number;
+        safeAreaTop?: number;
+        rootViewTop?: number;
+        rootViewLeft?: number;
+        rootViewWidth?: number;
+        rootViewHeight?: number;
+        windowWidth?: number;
+        windowHeight?: number;
+        screenshotCropTop?: number;
+        screenWidth?: number;
+        screenHeight?: number;
+        platform?: string;
+        interactionId?: string;
+        interactionProtocol?: number;
+        occurredAt?: number;
+        ui?: string;
+        stateStatus?: InteractionStateStatus;
+        targetId?: string;
+        screenName?: string;
+        emitAutomaticAnalytics?: boolean;
+        /**
+         * RN-6 — the native↔JS join's own verdict, and it MUST be declared here.
+         *
+         * This signature ENUMERATES its fields rather than spreading, and the only caller
+         * (ScaleBunDebugRoot's native listener) invokes it through `(sm as any)`. So a field
+         * added at the call site and not added here is dropped in silence, with no type
+         * error anywhere — which is precisely how these three nearly shipped as a no-op.
+         *
+         * 'exact' = one JS start was clearly closest. 'ambiguous' = two were within
+         * CORRELATION_MARGIN_MS of each other, so target/ui/screenName were deliberately
+         * withheld rather than guessed. 'none' = no start within tolerance, meaning the JS
+         * handler never fired. The last two are kept distinct because they have different
+         * fixes and collapsing them would hide which is happening in production.
+         */
+        correlation?: 'exact' | 'ambiguous' | 'none';
+        correlationDeltaMs?: number | null;
+        correlationRunnerUpDeltaMs?: number | null;
+        /**
+         * RN-1/RN-2 — which kind of identity `targetId` is. Declared here for the same reason as
+         * the correlation fields above: this signature enumerates, and its only caller goes
+         * through `(sm as any)`, so an undeclared field is dropped in silence.
+         */
+        targetSource?: 'testID' | 'path' | 'component' | 'none';
+        /** RN-8: where the screen name came from. Declared here because this signature enumerates. */
+        screenSource?: 'manual' | 'navigation' | 'none';
+        /**
+         * RN-13: the target control's rectangle in capture-base fractions. Declared here because
+         * this signature ENUMERATES — the sixth field to need it, after three correlation fields,
+         * targetSource and screenSource.
+         */
+        targetRect?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /**
+         * RN-3: content offset of the nearest ancestor scroller. Declared here because this
+         * signature ENUMERATES — the seventh field to need it.
+         */
+        scrollX?: number;
+        scrollY?: number;
+        scrollSource?: 'wrapper' | 'native' | 'none';
+        /**
+         * RN-4: list row identity. Declared here because this signature ENUMERATES — the eighth
+         * and ninth fields to need it.
+         */
+        itemKey?: string;
+        itemIndex?: number;
+        /**
+         * RN-15: tap position within the target control. Declared here because this signature
+         * ENUMERATES — the tenth and eleventh fields to need it.
+         */
+        localU?: number;
+        localV?: number;
+        /**
+         * Native scroll chain at touch-down (innermost first, capture pixels), the device pixel
+         * density, and the tap-contract version. Declared here because this signature ENUMERATES.
+         */
+        scrollContext?: import('../journey/nativeScroll').NativeScrollEntry[];
+        pixelDensity?: number;
+        heatmapSchemaVersion?: number;
+    }): void;
+    /**
+     * Manual frame capture — triggered by Desktop "Capture Step" button.
+     */
+    captureManualFrame(): Promise<{
+        frameId?: string;
+    } | null>;
+    /**
+     * Notify of app lifecycle change.
+     */
+    onLifecycleChange(state: 'foreground' | 'background'): void;
+    /**
+     * Notify of a scroll event from a scrollable surface (ScaleBunScrollView).
+     * Delegates to ScrollTracker for accumulation and settle detection.
+     */
+    onScrollEvent(contentOffsetX: number, contentOffsetY: number): void;
+    /**
+     * Notify that a screen has started loading.
+     * Explicit instrumentation — NOT auto-called on screen entry.
+     * Call from app code: ScaleBun.markLoadingStarted('ScreenName')
+     */
+    onLoadingStarted(screenName: string): void;
+    /**
+     * Notify that a screen has finished loading.
+     * Explicit instrumentation — call from app code.
+     * Triggers a 'screen_loaded' frame capture for the settled state.
+     */
+    onLoadingCompleted(screenName: string): void;
+    /**
+     * App network activity, forwarded to replay capture so a frame can wait for the screen's
+     * data instead of photographing the wait. Called by NetworkFeature, which has already
+     * excluded this SDK's own uploads and third-party beacons.
+     *
+     * Deliberately NOT gated on `this.active`: the counter must stay balanced across a session
+     * boundary. Dropping the `end` of a request whose `start` was counted would leave replay
+     * believing the app is permanently loading, and a session can start or stop mid-request.
+     * The capture manager ignores the signal when it is not capturing anyway.
+     */
+    onNetworkActivity(phase: 'start' | 'end'): void;
+    /**
+     * Override the sync policy. SDK-owned — native only provides metadata.
+     */
+    setSyncPolicy(policy: SyncDecisionCallback): void;
+    /**
+     * Provide native-gathered sync metadata for the current session.
+     * Does NOT make the sync decision — that stays in SDK's SyncDecisionEngine.
+     */
+    setNativeSyncMetadata(metadata: NativeSyncMetadata): void;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * ScaleBun SDK — Sync Decision Engine
+ *
+ * Evaluates session sync eligibility. This engine OWNS the policy —
+ * native layers only gather metadata and expose callback hooks.
+ *
+ * Default behavior in desktop mode: always eligible.
+ * Host apps can provide a custom SyncDecisionCallback for advanced logic.
+ */
+import type { SyncCandidate, SyncDecision, SyncDecisionCallback, NativeSyncMetadata, SessionMetadata } from './sessionTypes';
+export declare class SyncDecisionEngine {
+    private _policy;
+    constructor(customPolicy?: SyncDecisionCallback);
+    /**
+     * Replace the sync policy callback.
+     * Used by host apps to provide custom eligibility logic.
+     */
+    setPolicy(policy: SyncDecisionCallback): void;
+    /**
+     * Evaluate whether a session should be synced.
+     * Native metadata is merged into the candidate before evaluation.
+     *
+     * @param candidate - Session metadata + stats
+     * @param nativeMetadata - Optional metadata gathered by native layer
+     */
+    evaluate(candidate: SyncCandidate, nativeMetadata?: NativeSyncMetadata): SyncDecision;
+    /**
+     * Build a SyncCandidate from session state.
+     * Convenience helper to avoid constructing the object manually.
+     */
+    static buildCandidate(sessionId: string, metadata: SessionMetadata, eventCount: number, frameCount: number, durationMs: number, hasCrash: boolean, hasError: boolean, nativeMetadata?: NativeSyncMetadata): SyncCandidate;
+}
+//# sourceMappingURL=SyncDecisionEngine.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * SHOULD THIS TAP BE LINKED TO THIS KEYFRAME?
+ *
+ * A tap is stamped with the last keyframe of its screen (≤10 s old). Once frames carry the scroll
+ * containers visible in them, that link can be CHECKED instead of assumed: a tap made after the list
+ * was scrolled is not a tap on the picture taken before the scroll, and linking the two presents a
+ * different row as the one that was tapped.
+ *
+ *   'linked'      the frame shows the tap's scroll container at the same offset (±4), or the tap was
+ *                 not in a scroll container
+ *   'unverified'  the tap was in a container but the frame carries no scroll record (older native
+ *                 build) — linked, and marked so a reader knows it was not checked
+ *   'scroll_moved' the frame shows the container at another offset, or does not show it: NOT linked
+ *   'none'        there was no fresh keyframe of this screen
+ */
+export type FrameLink = 'linked' | 'unverified' | 'scroll_moved' | 'none';
+export declare const FRAME_OFFSET_TOL = 4;
+interface ScrollEntryLike {
+    containerTag?: number | null;
+    offsetX?: number;
+    offsetY?: number;
+}
+export declare function frameLinkVerdict(frame: {
+    scrollState?: ScrollEntryLike[];
+} | null | undefined, tapScroll: unknown): FrameLink;
+export {};
+//# sourceMappingURL=frameLink.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * A FRAME'S SCROLL STATE — every visible scroll container at the moment the screenshot was taken.
+ *
+ * A frame that carries only width/height cannot say whether a tap belongs on it: a tap inside a
+ * list scrolled 900px lands on different content than the same point on a frame taken at offset 0.
+ * Native reads the visible scroll containers on the main thread immediately before the pixels
+ * (Android ScrollContextProbe.snapshot, iOS ScreenshotCaptureManager.visibleScrollState), with the
+ * same keys as a tap's `scrollContext`, so a tap is compatible with a frame when its container
+ * reports the same offset in both.
+ *
+ * Units follow the tap on each platform: Android capture-view pixels, iOS points.
+ *
+ * `undefined` = not measured (old native binary, or a snapshot that failed). `[]` = measured and
+ * no scroll container was on screen. The two are never collapsed: an absent measurement must not
+ * read as "nothing scrolls here".
+ */
+import { type NativeScrollEntry } from '../journey/nativeScroll';
+export type FrameScrollEntry = NativeScrollEntry;
+/** Same cap as the native side and the backend DTO. */
+export declare const MAX_FRAME_SCROLL_ENTRIES = 4;
+/**
+ * Keep only well-formed entries (finite offsets; other numeric fields dropped unless finite),
+ * at most 4. A non-array is "not measured" and stays undefined; a malformed payload must never
+ * become a fabricated offset.
+ */
+export declare function sanitizeFrameScrollState(raw: unknown): FrameScrollEntry[] | undefined;
+//# sourceMappingURL=frameScrollState.d.ts.map

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

@@ -0,0 +1,23 @@
+/**
+ * ScaleBun SDK — Unified Session Feature
+ *
+ * Public API surface for the unified session system.
+ * Re-exports all domain types, contracts, configs, and constants.
+ */
+export type { Session, SessionMetadata, SessionStatus, JourneyEvent, JourneyEventType, JourneyEventSeverity, JourneyEventSource, ReplayFrame, CaptureReason, SessionArtifactIndex, CrashAnchor, } from './sessionTypes';
+export type { CaptureMode, ReplayQuality, SessionReplayConfig, PrivacyPolicy, } from './sessionTypes';
+export { DEFAULT_SESSION_REPLAY_CONFIG, QUALITY_PRESETS, } from './sessionTypes';
+export type { TransportState, SessionTransport, } from './sessionTypes';
+export type { SyncState, SyncCandidate, SyncDecision, SyncDecisionCallback, NativeSyncMetadata, } from './sessionTypes';
+export type { NativeFrameResult, NativeDeviceMetadata, } from './sessionTypes';
+export { FrameRetentionPriority, getFrameRetentionPriority, EventRetentionPriority, getEventRetentionPriority, } from './sessionTypes';
+export { SESSION_EVENTS } from './sessionTypes';
+export { SessionManager } from './SessionManager';
+export type { SessionManagerConfig } from './SessionManager';
+export { JourneyEventPipeline } from './JourneyEventPipeline';
+export type { EventEmitCallback } from './JourneyEventPipeline';
+export { ReplayCaptureManager } from './ReplayCaptureManager';
+export type { NativeCaptureFn, FrameEmitCallback } from './ReplayCaptureManager';
+export { DesktopSessionTransport } from './DesktopSessionTransport';
+export { SyncDecisionEngine } from './SyncDecisionEngine';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * ScaleBun SDK — Native Frame Capture
+ *
+ * Provides the callback for the SessionManager to request screenshots
+ * from the native layer (PixelCopy on Android, UIWindow on iOS).
+ */
+import { type PlatformOS } from '../../core/context/device';
+export declare const nativeCapture: (sessionId: string, reason: string, _quality: any) => Promise<{
+    scrollState?: import("../journey/nativeScroll").NativeScrollEntry[] | undefined;
+    base64: string;
+    width: number;
+    height: number;
+    byteSize: number;
+    format: string;
+    frameHash: string | undefined;
+    platform: PlatformOS;
+} | null>;
+//# sourceMappingURL=nativeCapture.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * ScaleBun SDK — Native File-Outbox Frame Capture Adapter
+ *
+ * Wraps the native staged-frame bridge for ReplayCaptureManager. The capture step
+ * captures + masks + encodes natively and STAGES the image (no upload marker), so
+ * the JS orchestrator keeps full ownership of sequencing / keyframe-delta /
+ * change-detection. The orchestrator then commits (writes JS-authoritative meta →
+ * uploadable) or discards (suppressed) the staged frame.
+ *
+ * No frame bytes/base64 ever cross the bridge on this path — capture returns
+ * metadata + a native content hash only.
+ *
+ * Every method is no-throw and gated by a readiness check so that with the flag
+ * off (or an old native binary) `capture` returns null and ReplayCaptureManager
+ * transparently falls back to the legacy `captureScreenshot` path.
+ */
+import type { OutboxFrameCapture } from './ReplayCaptureManager';
+/** Build the adapter. `ensureReady` resolves false when the native outbox is off. */
+export declare function makeOutboxFrameCapture(ensureReady: () => Promise<boolean>): OutboxFrameCapture;
+//# sourceMappingURL=outboxFrameCapture.d.ts.map