@scalebun/react-native 1.0.1 → 1.0.2

package/src/features/session/sessionTypes.ts

@@ -1,491 +1,491 @@
-/**
- * ScaleBun SDK — Unified Session Domain Model
- *
- * Single source of truth for event types, frame types, session lifecycle,
- * transport contracts, sync contracts, capture configuration, and artifact indexing.
- *
- * Architecture rules:
- * - imageRef in ReplayFrame is an artifact reference (ID/path), NOT base64.
- *   Base64 is transport-layer detail only.
- * - SyncDecisionEngine in the SDK owns sync policy; native only gathers metadata.
- * - Frame capture is native-only (PixelCopy on Android, UIWindow on iOS).
- *   No JS screenshot fallback for session replay.
- * - Frame retention prefers crash-adjacent/error-context frames over generic old frames.
- */
-
-// ─── Session ────────────────────────────────────────────────────────────────
-
-export type SessionStatus = 'active' | 'ended' | 'timeout';
-
-export interface SessionMetadata {
-    appName?: string;
-    appVersion?: string;
-    bundleId?: string;
-    platform?: 'android' | 'ios' | 'web';
-    osVersion?: string;
-    deviceModel?: string;
-    deviceName?: string;
-    screenWidth?: number;
-    screenHeight?: number;
-    buildType?: 'debug' | 'release';
-}
-
-export interface Session {
-    sessionId: string;
-    deviceId: string;
-    startedAt: number;
-    endedAt?: number;
-    status: SessionStatus;
-    metadata: SessionMetadata;
-    transportState: TransportState;
-    syncState: SyncState;
-    artifactIndex: SessionArtifactIndex;
-}
-
-// ─── Journey Event ──────────────────────────────────────────────────────────
-
-export type JourneyEventType =
-    | 'SESSION_STARTED'
-    | 'SESSION_ENDED'
-    | 'APP_FOREGROUND'
-    | 'APP_BACKGROUND'
-    | 'SCREEN_VIEW'
-    /** Leaving a screen, carrying the MEASURED dwell time — see SessionManager.onScreenChange. */
-    | 'SCREEN_EXIT'
-    | 'USER_ACTION'
-    | 'NETWORK_REQUEST_STARTED'
-    | 'NETWORK_REQUEST_COMPLETED'
-    | 'NETWORK_REQUEST_FAILED'
-    | 'LOG_EMITTED'
-    | 'ERROR_CAPTURED'
-    | 'CRASH_CAPTURED'
-    | 'REPLAY_FRAME_CAPTURED'
-    | 'LOADING_STARTED'
-    | 'LOADING_COMPLETED';
-
-export type JourneyEventSeverity = 'info' | 'warning' | 'error' | 'fatal';
-export type JourneyEventSource = 'sdk' | 'native' | 'user' | 'system';
-
-export interface JourneyEvent {
-    eventId: string;
-    sessionId: string;
-    /** If this event belongs to a recorded journey */
-    journeyId?: string;
-    ts: number;
-    type: JourneyEventType;
-    /** Subtype for further classification (e.g. 'TAP', 'SWIPE', 'console.error') */
-    subtype?: string;
-    severity?: JourneyEventSeverity;
-    /** Screen name at time of event */
-    screen?: string;
-    payload?: Record<string, unknown>;
-    /** Links related events (e.g. network request start → complete) */
-    correlationId?: string;
-    /** Distributed trace ID */
-    traceId?: string;
-    source?: JourneyEventSource;
-}
-
-// ─── Replay Frame ───────────────────────────────────────────────────────────
-
-/**
- * imageRef is an ARTIFACT REFERENCE (opaque ID/path), not raw base64.
- * Base64 content is a transport/storage detail resolved separately.
- * This keeps the domain model transport-agnostic.
- */
-export interface ReplayFrame {
-    frameId: string;
-    sessionId: string;
-    ts: number;
-    /** Monotonic per-session sequence (P2-0). Assigned in JS, starts at 1, +1 per emitted frame. */
-    sequenceNumber: number;
-    /** Keyframe (full image) or delta (changed regions vs baseFrameId). P2-5. */
-    frameType: 'keyframe' | 'delta';
-    /** frameId of the keyframe a delta is encoded against; undefined for keyframes. P2-5. */
-    baseFrameId?: string;
-    /** Artifact reference — resolved to actual data by transport/storage layer */
-    imageRef: string;
-    width: number;
-    height: number;
-    /** Encoded image byte size (real value from native), 0 if unknown. */
-    byteSize?: number;
-    /** Image encoding from native ('avif' | 'webp' | 'jpeg' | 'png'). P2-2 fallback chain. */
-    format?: string;
-    quality: ReplayQuality;
-    captureReason: CaptureReason;
-    /** Native-only capture — JS never captures frames */
-    sourcePlatform: 'android' | 'ios';
-    redactionState?: 'none' | 'text-masked' | 'full';
-    /** Screen name at capture time — for frame-to-screen correlation */
-    screen?: string;
-    /** Interaction point metadata — populated when captureReason is 'interaction' */
-    interactionPoint?: {
-        /** Tap/gesture X coordinate in device pixels */
-        x: number;
-        /** Tap/gesture Y coordinate in device pixels */
-        y: number;
-        /** Normalized X (0 to 1) for safe heatmap overlay across different viewport sizes */
-        normalizedX?: number;
-        /** Normalized Y (0 to 1) for safe heatmap overlay across different viewport sizes */
-        normalizedY?: number;
-        /** Device screen width at capture time */
-        screenWidth: number;
-        /** Device screen height at capture time */
-        screenHeight: number;
-        /** Actual viewport width at capture time, equivalent to screenWidth in most cases */
-        viewportWidth?: number;
-        /** Actual viewport height at capture time, equivalent to screenHeight in most cases */
-        viewportHeight?: number;
-        /** Gesture type: tap, long_press, swipe, scroll */
-        gestureType: string;
-        /** For swipes/scrolls: End X coordinate */
-        endX?: number;
-        /** For swipes/scrolls: End Y coordinate */
-        endY?: number;
-        /** For swipes/scrolls: Normalized End X */
-        normalizedEndX?: number;
-        /** For swipes/scrolls: Normalized End Y */
-        normalizedEndY?: number;
-        /** Duration of gesture if tracked */
-        durationMs?: number;
-        /** Gesture direction: up, down, left, right */
-        direction?: string;
-    };
-}
-
-export type CaptureReason =
-    | 'navigation'
-    | 'interaction'
-    | 'frequency'
-    | 'manual'
-    | 'error-context'
-    | 'scroll'
-    | 'screen_loaded';
-
-// ─── Session Artifact Index ─────────────────────────────────────────────────
-
-export interface CrashAnchor {
-    crashEventId: string;
-    /** Event IDs within ±N of the crash */
-    nearbyEventIds: string[];
-    /** Frame IDs within ±N of the crash */
-    nearbyFrameIds: string[];
-    timestamp: number;
-}
-
-export interface SessionArtifactIndex {
-    /** Frame IDs in chronological order */
-    frameRefs: string[];
-    /** Event IDs in chronological order */
-    eventRefs: string[];
-    /** Event IDs where type is NETWORK_REQUEST_* */
-    networkRefs: string[];
-    /** Event IDs where type is LOG_EMITTED */
-    logRefs: string[];
-    /** Crash/error anchors with nearby context */
-    crashAnchors: CrashAnchor[];
-    /** Future: artifact upload references for remote dashboard */
-    uploadRefs?: string[];
-}
-
-// ─── Capture Configuration ──────────────────────────────────────────────────
-
-/** When to capture frames */
-export type CaptureMode = 'navigation' | 'interactions' | 'frequency';
-
-/** Frame quality presets — maps to native JPEG compression */
-export type ReplayQuality = 'high' | 'normal' | 'low' | 'grayscale';
-
-/** Quality preset → concrete capture parameters (used by native engines) */
-export const QUALITY_PRESETS: Record<ReplayQuality, { maxWidth: number; jpegQuality: number }> = {
-    high: { maxWidth: 0, jpegQuality: 90 }, // 0 = full width
-    normal: { maxWidth: 720, jpegQuality: 70 },
-    low: { maxWidth: 480, jpegQuality: 40 },
-    grayscale: { maxWidth: 720, jpegQuality: 60 }, // native applies grayscale conversion
-};
-
-export interface PrivacyPolicy {
-    redactTextInputs: boolean;
-    redactImages: boolean;
-    /** TestIDs to completely exclude from capture */
-    blockTestIds: string[];
-    /** Screen names to exclude from replay capture */
-    captureExclusions: string[];
-}
-
-export interface SessionReplayConfig {
-    captureMode: CaptureMode;
-    quality: ReplayQuality;
-    /** Used with 'frequency' mode. Minimum 500ms. */
-    intervalMs: number;
-    includeNetworkLogs: boolean;
-    includeSdkLogs: boolean;
-    includeUserSteps: boolean;
-    /** Max frames before dropping old (prefers keeping crash-adjacent) */
-    maxFrames: number;
-    /** Max events before dropping old (prefers keeping crash-adjacent) */
-    maxEventCount: number;
-    /** Auto-end session after this duration */
-    maxDurationMs: number;
-    privacyPolicy: PrivacyPolicy;
-
-    // ── P2 capture knobs (all tunable; see P2_CONTRACT.md §5) ──
-    /** P2-1: suppress visually-unchanged consecutive frames. Default true. */
-    changeDetection?: boolean;
-    /** P2-1: 0 = exact-hash match; >0 = perceptual distance threshold (native). Default 0. */
-    changeSensitivity?: number;
-    /** P2-1 heartbeat: force a keyframe even if unchanged after this many ms, so static
-     *  periods still have a frame AND deltas always have a fresh base. Default 5000. */
-    maxKeyframeIntervalMs?: number;
-    /** P2-2: native encode preference order; first that succeeds on-device wins. */
-    frameFormatPreference?: Array<'avif' | 'webp' | 'jpeg'>;
-    /** P2-2: lossy encoder quality 0..100. Default 55. */
-    frameQuality?: number;
-    /** P2-5: emit deltas between keyframes. Default false (keyframe-only when off). */
-    deltaEncoding?: boolean;
-    /** P2-5: force a keyframe every N frames so a dropped base strands < N-1 deltas. Default 10. */
-    deltaKeyframeInterval?: number;
-}
-
-export const DEFAULT_SESSION_REPLAY_CONFIG: SessionReplayConfig = {
-    captureMode: 'navigation',
-    quality: 'normal',
-    intervalMs: 2000,
-    includeNetworkLogs: true,
-    includeSdkLogs: false,
-    includeUserSteps: true,
-    maxFrames: 200,
-    maxEventCount: 1000,
-    maxDurationMs: 10 * 60 * 1000, // 10 minutes
-    privacyPolicy: {
-        redactTextInputs: true,
-        redactImages: false,
-        blockTestIds: [],
-        captureExclusions: [],
-    },
-    // P2 capture knobs
-    changeDetection: true,
-    changeSensitivity: 0,
-    maxKeyframeIntervalMs: 5000,
-    frameFormatPreference: ['avif', 'webp', 'jpeg'],
-    frameQuality: 55,
-    deltaEncoding: false,
-    deltaKeyframeInterval: 10,
-};
-
-// ─── Transport Contracts ────────────────────────────────────────────────────
-
-export type TransportState =
-    | 'local'
-    | 'pending-sync'
-    | 'syncing'
-    | 'synced'
-    | 'failed';
-
-/**
- * SessionTransport abstraction.
- * DesktopSessionTransport implements this now.
- * RemoteDashboardSessionTransport will implement this later.
- * Core session logic never knows transport details.
- */
-export interface SessionTransport {
-    sendSessionStart(session: Session): void;
-    sendSessionEnd(session: Session): void;
-    sendEvent(event: JourneyEvent): void;
-    /**
-     * Send a replay frame. The transport is responsible for resolving
-     * imageRef → actual content (base64, URL, etc.) at the transport boundary.
-     * @param frame - frame metadata (imageRef is artifact reference)
-     * @param imageData - raw image data (base64) for transport serialization
-     */
-    sendFrame(frame: ReplayFrame, imageData: string): void;
-}
-
-// ─── Sync Decision Contracts ────────────────────────────────────────────────
-
-export type SyncState =
-    | 'eligible'
-    | 'ineligible'
-    | 'pending-evaluation'
-    | 'opted-out';
-
-/**
- * Metadata gathered by NATIVE layer, passed to SDK for sync decision.
- * Native only gathers; SDK's SyncDecisionEngine owns the eligibility policy.
- */
-export interface NativeSyncMetadata {
-    deviceModel: string;
-    osVersion: string;
-    batteryLevel?: number;
-    batteryCharging?: boolean;
-    networkType?: 'wifi' | 'cellular' | 'ethernet' | 'none' | 'unknown';
-    isMeteredNetwork?: boolean;
-    availableMemoryMb?: number;
-    thermalState?: 'nominal' | 'fair' | 'serious' | 'critical';
-}
-
-/**
- * Candidate presented to SyncDecisionEngine for eligibility evaluation.
- */
-export interface SyncCandidate {
-    sessionId: string;
-    metadata: SessionMetadata;
-    nativeMetadata?: NativeSyncMetadata;
-    eventCount: number;
-    frameCount: number;
-    durationMs: number;
-    hasCrash: boolean;
-    hasError: boolean;
-}
-
-export interface SyncDecision {
-    shouldSync: boolean;
-    reason: string;
-    priority: 'high' | 'normal' | 'low';
-}
-
-/**
- * Callback type for custom sync eligibility evaluation.
- * The SDK provides a default implementation; host apps can override.
- */
-export type SyncDecisionCallback = (candidate: SyncCandidate) => SyncDecision;
-
-// ─── Native Capture Result ──────────────────────────────────────────────────
-
-/**
- * Result returned by native capture engine.
- * base64 is transient — used at the transport boundary, NOT stored in domain as imageRef.
- */
-export interface NativeFrameResult {
-    base64: string;
-    width: number;
-    height: number;
-    /** Byte size of the compressed image */
-    byteSize: number;
-    /** Platform that performed the capture */
-    platform: 'android' | 'ios';
-    /** Actual on-device encoding after the AVIF->WebP->JPEG fallback (P2-2). */
-    format?: string;
-    /** Optional native frame hash for change detection (P2-1). JS falls back to hashing base64. */
-    frameHash?: string;
-}
-
-/**
- * Native device/session metadata result.
- */
-export interface NativeDeviceMetadata {
-    deviceModel: string;
-    osVersion: string;
-    screenWidth: number;
-    screenHeight: number;
-    platform: 'android' | 'ios';
-    appName?: string;
-    appVersion?: string;
-    bundleId?: string;
-    buildType?: 'debug' | 'release';
-}
-
-// ─── Frame Retention Policy ─────────────────────────────────────────────────
-
-/**
- * Priority levels for frame retention when buffer is full.
- * Higher priority frames are kept longer.
- *
- * CRASH_ADJACENT and ERROR_CONTEXT frames are NEVER dropped before
- * generic NAVIGATION/INTERACTION/FREQUENCY frames.
- */
-export enum FrameRetentionPriority {
-    /** Lowest: regular periodic captures */
-    FREQUENCY = 0,
-    /** Low: regular navigation frames */
-    NAVIGATION = 1,
-    /** Medium: interaction-triggered frames */
-    INTERACTION = 2,
-    /** Medium-high: manually triggered captures */
-    MANUAL = 3,
-    /** High: captured in response to an error event */
-    ERROR_CONTEXT = 4,
-    /** Highest: adjacent to a crash event — never drop before others */
-    CRASH_ADJACENT = 5,
-}
-
-/** Map CaptureReason → retention priority */
-export function getFrameRetentionPriority(reason: CaptureReason): FrameRetentionPriority {
-    switch (reason) {
-        case 'error-context': return FrameRetentionPriority.ERROR_CONTEXT;
-        case 'manual': return FrameRetentionPriority.MANUAL;
-        case 'interaction': return FrameRetentionPriority.INTERACTION;
-        case 'screen_loaded': return FrameRetentionPriority.INTERACTION; // Same priority as interaction
-        case 'scroll': return FrameRetentionPriority.INTERACTION;
-        case 'navigation': return FrameRetentionPriority.NAVIGATION;
-        case 'frequency': return FrameRetentionPriority.FREQUENCY;
-    }
-}
-
-// ─── Session Protocol Event Names ───────────────────────────────────────────
-
-export const SESSION_EVENTS = {
-    SESSION_START: 'session:start',
-    SESSION_END: 'session:end',
-    EVENT: 'session:event',
-    FRAME: 'session:frame',
-} as const;
-
-// ─── Event Retention Policy ─────────────────────────────────────────────────
-
-/**
- * Priority levels for event retention when buffer is full.
- * Crash/error events are NEVER dropped before generic events.
- */
-export enum EventRetentionPriority {
-    LOG = 0,
-    NETWORK = 1,
-    LIFECYCLE = 2,
-    SCREEN_VIEW = 3,
-    USER_ACTION = 4,
-    ERROR = 5,
-    CRASH = 6,
-}
-
-/** Map JourneyEventType → retention priority */
-export function getEventRetentionPriority(type: JourneyEventType): EventRetentionPriority {
-    switch (type) {
-        case 'LOG_EMITTED': return EventRetentionPriority.LOG;
-        case 'NETWORK_REQUEST_STARTED':
-        case 'NETWORK_REQUEST_COMPLETED':
-        case 'NETWORK_REQUEST_FAILED': return EventRetentionPriority.NETWORK;
-        case 'APP_FOREGROUND':
-        case 'APP_BACKGROUND':
-        case 'SESSION_STARTED':
-        case 'SESSION_ENDED':
-        case 'LOADING_STARTED':
-        case 'LOADING_COMPLETED': return EventRetentionPriority.LIFECYCLE;
-        // An exit is the other half of a view and carries the dwell time, so it retains together with
-        // it — dropping exits first would leave entries whose duration can never be recovered.
-        case 'SCREEN_VIEW':
-        case 'SCREEN_EXIT': return EventRetentionPriority.SCREEN_VIEW;
-        case 'USER_ACTION':
-        case 'REPLAY_FRAME_CAPTURED': return EventRetentionPriority.USER_ACTION;
-        case 'ERROR_CAPTURED': return EventRetentionPriority.ERROR;
-        case 'CRASH_CAPTURED': return EventRetentionPriority.CRASH;
-    }
-}
-
-// ─── Re-exports from contracts ──────────────────────────────────────────────
-// Pure types are now canonical in @scalebun/sdk-contracts.
-// Runtime values (enums, constants, functions) remain here.
-export type {
-    Session as ContractSession,
-    SessionMetadata as ContractSessionMetadata,
-    SessionStatus as ContractSessionStatus,
-    JourneyEvent as ContractJourneyEvent,
-    JourneyEventType as ContractJourneyEventType,
-    ReplayFrame as ContractReplayFrame,
-    CaptureReason as ContractCaptureReason,
-    SessionReplayConfig as ContractSessionReplayConfig,
-    SessionTransport as ContractSessionTransport,
-    SyncCandidate as ContractSyncCandidate,
-    SyncDecision as ContractSyncDecision,
-    NativeFrameResult as ContractNativeFrameResult,
-    NativeDeviceMetadata as ContractNativeDeviceMetadata,
-} from '../../vendor/sdk-contracts';
+/**
+ * ScaleBun SDK — Unified Session Domain Model
+ *
+ * Single source of truth for event types, frame types, session lifecycle,
+ * transport contracts, sync contracts, capture configuration, and artifact indexing.
+ *
+ * Architecture rules:
+ * - imageRef in ReplayFrame is an artifact reference (ID/path), NOT base64.
+ *   Base64 is transport-layer detail only.
+ * - SyncDecisionEngine in the SDK owns sync policy; native only gathers metadata.
+ * - Frame capture is native-only (PixelCopy on Android, UIWindow on iOS).
+ *   No JS screenshot fallback for session replay.
+ * - Frame retention prefers crash-adjacent/error-context frames over generic old frames.
+ */
+
+// ─── Session ────────────────────────────────────────────────────────────────
+
+export type SessionStatus = 'active' | 'ended' | 'timeout';
+
+export interface SessionMetadata {
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    platform?: 'android' | 'ios' | 'web';
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    buildType?: 'debug' | 'release';
+}
+
+export interface Session {
+    sessionId: string;
+    deviceId: string;
+    startedAt: number;
+    endedAt?: number;
+    status: SessionStatus;
+    metadata: SessionMetadata;
+    transportState: TransportState;
+    syncState: SyncState;
+    artifactIndex: SessionArtifactIndex;
+}
+
+// ─── Journey Event ──────────────────────────────────────────────────────────
+
+export type JourneyEventType =
+    | 'SESSION_STARTED'
+    | 'SESSION_ENDED'
+    | 'APP_FOREGROUND'
+    | 'APP_BACKGROUND'
+    | 'SCREEN_VIEW'
+    /** Leaving a screen, carrying the MEASURED dwell time — see SessionManager.onScreenChange. */
+    | 'SCREEN_EXIT'
+    | 'USER_ACTION'
+    | 'NETWORK_REQUEST_STARTED'
+    | 'NETWORK_REQUEST_COMPLETED'
+    | 'NETWORK_REQUEST_FAILED'
+    | 'LOG_EMITTED'
+    | 'ERROR_CAPTURED'
+    | 'CRASH_CAPTURED'
+    | 'REPLAY_FRAME_CAPTURED'
+    | 'LOADING_STARTED'
+    | 'LOADING_COMPLETED';
+
+export type JourneyEventSeverity = 'info' | 'warning' | 'error' | 'fatal';
+export type JourneyEventSource = 'sdk' | 'native' | 'user' | 'system';
+
+export interface JourneyEvent {
+    eventId: string;
+    sessionId: string;
+    /** If this event belongs to a recorded journey */
+    journeyId?: string;
+    ts: number;
+    type: JourneyEventType;
+    /** Subtype for further classification (e.g. 'TAP', 'SWIPE', 'console.error') */
+    subtype?: string;
+    severity?: JourneyEventSeverity;
+    /** Screen name at time of event */
+    screen?: string;
+    payload?: Record<string, unknown>;
+    /** Links related events (e.g. network request start → complete) */
+    correlationId?: string;
+    /** Distributed trace ID */
+    traceId?: string;
+    source?: JourneyEventSource;
+}
+
+// ─── Replay Frame ───────────────────────────────────────────────────────────
+
+/**
+ * imageRef is an ARTIFACT REFERENCE (opaque ID/path), not raw base64.
+ * Base64 content is a transport/storage detail resolved separately.
+ * This keeps the domain model transport-agnostic.
+ */
+export interface ReplayFrame {
+    frameId: string;
+    sessionId: string;
+    ts: number;
+    /** Monotonic per-session sequence (P2-0). Assigned in JS, starts at 1, +1 per emitted frame. */
+    sequenceNumber: number;
+    /** Keyframe (full image) or delta (changed regions vs baseFrameId). P2-5. */
+    frameType: 'keyframe' | 'delta';
+    /** frameId of the keyframe a delta is encoded against; undefined for keyframes. P2-5. */
+    baseFrameId?: string;
+    /** Artifact reference — resolved to actual data by transport/storage layer */
+    imageRef: string;
+    width: number;
+    height: number;
+    /** Encoded image byte size (real value from native), 0 if unknown. */
+    byteSize?: number;
+    /** Image encoding from native ('avif' | 'webp' | 'jpeg' | 'png'). P2-2 fallback chain. */
+    format?: string;
+    quality: ReplayQuality;
+    captureReason: CaptureReason;
+    /** Native-only capture — JS never captures frames */
+    sourcePlatform: 'android' | 'ios';
+    redactionState?: 'none' | 'text-masked' | 'full';
+    /** Screen name at capture time — for frame-to-screen correlation */
+    screen?: string;
+    /** Interaction point metadata — populated when captureReason is 'interaction' */
+    interactionPoint?: {
+        /** Tap/gesture X coordinate in device pixels */
+        x: number;
+        /** Tap/gesture Y coordinate in device pixels */
+        y: number;
+        /** Normalized X (0 to 1) for safe heatmap overlay across different viewport sizes */
+        normalizedX?: number;
+        /** Normalized Y (0 to 1) for safe heatmap overlay across different viewport sizes */
+        normalizedY?: number;
+        /** Device screen width at capture time */
+        screenWidth: number;
+        /** Device screen height at capture time */
+        screenHeight: number;
+        /** Actual viewport width at capture time, equivalent to screenWidth in most cases */
+        viewportWidth?: number;
+        /** Actual viewport height at capture time, equivalent to screenHeight in most cases */
+        viewportHeight?: number;
+        /** Gesture type: tap, long_press, swipe, scroll */
+        gestureType: string;
+        /** For swipes/scrolls: End X coordinate */
+        endX?: number;
+        /** For swipes/scrolls: End Y coordinate */
+        endY?: number;
+        /** For swipes/scrolls: Normalized End X */
+        normalizedEndX?: number;
+        /** For swipes/scrolls: Normalized End Y */
+        normalizedEndY?: number;
+        /** Duration of gesture if tracked */
+        durationMs?: number;
+        /** Gesture direction: up, down, left, right */
+        direction?: string;
+    };
+}
+
+export type CaptureReason =
+    | 'navigation'
+    | 'interaction'
+    | 'frequency'
+    | 'manual'
+    | 'error-context'
+    | 'scroll'
+    | 'screen_loaded';
+
+// ─── Session Artifact Index ─────────────────────────────────────────────────
+
+export interface CrashAnchor {
+    crashEventId: string;
+    /** Event IDs within ±N of the crash */
+    nearbyEventIds: string[];
+    /** Frame IDs within ±N of the crash */
+    nearbyFrameIds: string[];
+    timestamp: number;
+}
+
+export interface SessionArtifactIndex {
+    /** Frame IDs in chronological order */
+    frameRefs: string[];
+    /** Event IDs in chronological order */
+    eventRefs: string[];
+    /** Event IDs where type is NETWORK_REQUEST_* */
+    networkRefs: string[];
+    /** Event IDs where type is LOG_EMITTED */
+    logRefs: string[];
+    /** Crash/error anchors with nearby context */
+    crashAnchors: CrashAnchor[];
+    /** Future: artifact upload references for remote dashboard */
+    uploadRefs?: string[];
+}
+
+// ─── Capture Configuration ──────────────────────────────────────────────────
+
+/** When to capture frames */
+export type CaptureMode = 'navigation' | 'interactions' | 'frequency';
+
+/** Frame quality presets — maps to native JPEG compression */
+export type ReplayQuality = 'high' | 'normal' | 'low' | 'grayscale';
+
+/** Quality preset → concrete capture parameters (used by native engines) */
+export const QUALITY_PRESETS: Record<ReplayQuality, { maxWidth: number; jpegQuality: number }> = {
+    high: { maxWidth: 0, jpegQuality: 90 }, // 0 = full width
+    normal: { maxWidth: 720, jpegQuality: 70 },
+    low: { maxWidth: 480, jpegQuality: 40 },
+    grayscale: { maxWidth: 720, jpegQuality: 60 }, // native applies grayscale conversion
+};
+
+export interface PrivacyPolicy {
+    redactTextInputs: boolean;
+    redactImages: boolean;
+    /** TestIDs to completely exclude from capture */
+    blockTestIds: string[];
+    /** Screen names to exclude from replay capture */
+    captureExclusions: string[];
+}
+
+export interface SessionReplayConfig {
+    captureMode: CaptureMode;
+    quality: ReplayQuality;
+    /** Used with 'frequency' mode. Minimum 500ms. */
+    intervalMs: number;
+    includeNetworkLogs: boolean;
+    includeSdkLogs: boolean;
+    includeUserSteps: boolean;
+    /** Max frames before dropping old (prefers keeping crash-adjacent) */
+    maxFrames: number;
+    /** Max events before dropping old (prefers keeping crash-adjacent) */
+    maxEventCount: number;
+    /** Auto-end session after this duration */
+    maxDurationMs: number;
+    privacyPolicy: PrivacyPolicy;
+
+    // ── P2 capture knobs (all tunable; see P2_CONTRACT.md §5) ──
+    /** P2-1: suppress visually-unchanged consecutive frames. Default true. */
+    changeDetection?: boolean;
+    /** P2-1: 0 = exact-hash match; >0 = perceptual distance threshold (native). Default 0. */
+    changeSensitivity?: number;
+    /** P2-1 heartbeat: force a keyframe even if unchanged after this many ms, so static
+     *  periods still have a frame AND deltas always have a fresh base. Default 5000. */
+    maxKeyframeIntervalMs?: number;
+    /** P2-2: native encode preference order; first that succeeds on-device wins. */
+    frameFormatPreference?: Array<'avif' | 'webp' | 'jpeg'>;
+    /** P2-2: lossy encoder quality 0..100. Default 55. */
+    frameQuality?: number;
+    /** P2-5: emit deltas between keyframes. Default false (keyframe-only when off). */
+    deltaEncoding?: boolean;
+    /** P2-5: force a keyframe every N frames so a dropped base strands < N-1 deltas. Default 10. */
+    deltaKeyframeInterval?: number;
+}
+
+export const DEFAULT_SESSION_REPLAY_CONFIG: SessionReplayConfig = {
+    captureMode: 'navigation',
+    quality: 'normal',
+    intervalMs: 2000,
+    includeNetworkLogs: true,
+    includeSdkLogs: false,
+    includeUserSteps: true,
+    maxFrames: 200,
+    maxEventCount: 1000,
+    maxDurationMs: 10 * 60 * 1000, // 10 minutes
+    privacyPolicy: {
+        redactTextInputs: true,
+        redactImages: false,
+        blockTestIds: [],
+        captureExclusions: [],
+    },
+    // P2 capture knobs
+    changeDetection: true,
+    changeSensitivity: 0,
+    maxKeyframeIntervalMs: 5000,
+    frameFormatPreference: ['avif', 'webp', 'jpeg'],
+    frameQuality: 55,
+    deltaEncoding: false,
+    deltaKeyframeInterval: 10,
+};
+
+// ─── Transport Contracts ────────────────────────────────────────────────────
+
+export type TransportState =
+    | 'local'
+    | 'pending-sync'
+    | 'syncing'
+    | 'synced'
+    | 'failed';
+
+/**
+ * SessionTransport abstraction.
+ * DesktopSessionTransport implements this now.
+ * RemoteDashboardSessionTransport will implement this later.
+ * Core session logic never knows transport details.
+ */
+export interface SessionTransport {
+    sendSessionStart(session: Session): void;
+    sendSessionEnd(session: Session): void;
+    sendEvent(event: JourneyEvent): void;
+    /**
+     * Send a replay frame. The transport is responsible for resolving
+     * imageRef → actual content (base64, URL, etc.) at the transport boundary.
+     * @param frame - frame metadata (imageRef is artifact reference)
+     * @param imageData - raw image data (base64) for transport serialization
+     */
+    sendFrame(frame: ReplayFrame, imageData: string): void;
+}
+
+// ─── Sync Decision Contracts ────────────────────────────────────────────────
+
+export type SyncState =
+    | 'eligible'
+    | 'ineligible'
+    | 'pending-evaluation'
+    | 'opted-out';
+
+/**
+ * Metadata gathered by NATIVE layer, passed to SDK for sync decision.
+ * Native only gathers; SDK's SyncDecisionEngine owns the eligibility policy.
+ */
+export interface NativeSyncMetadata {
+    deviceModel: string;
+    osVersion: string;
+    batteryLevel?: number;
+    batteryCharging?: boolean;
+    networkType?: 'wifi' | 'cellular' | 'ethernet' | 'none' | 'unknown';
+    isMeteredNetwork?: boolean;
+    availableMemoryMb?: number;
+    thermalState?: 'nominal' | 'fair' | 'serious' | 'critical';
+}
+
+/**
+ * Candidate presented to SyncDecisionEngine for eligibility evaluation.
+ */
+export interface SyncCandidate {
+    sessionId: string;
+    metadata: SessionMetadata;
+    nativeMetadata?: NativeSyncMetadata;
+    eventCount: number;
+    frameCount: number;
+    durationMs: number;
+    hasCrash: boolean;
+    hasError: boolean;
+}
+
+export interface SyncDecision {
+    shouldSync: boolean;
+    reason: string;
+    priority: 'high' | 'normal' | 'low';
+}
+
+/**
+ * Callback type for custom sync eligibility evaluation.
+ * The SDK provides a default implementation; host apps can override.
+ */
+export type SyncDecisionCallback = (candidate: SyncCandidate) => SyncDecision;
+
+// ─── Native Capture Result ──────────────────────────────────────────────────
+
+/**
+ * Result returned by native capture engine.
+ * base64 is transient — used at the transport boundary, NOT stored in domain as imageRef.
+ */
+export interface NativeFrameResult {
+    base64: string;
+    width: number;
+    height: number;
+    /** Byte size of the compressed image */
+    byteSize: number;
+    /** Platform that performed the capture */
+    platform: 'android' | 'ios';
+    /** Actual on-device encoding after the AVIF->WebP->JPEG fallback (P2-2). */
+    format?: string;
+    /** Optional native frame hash for change detection (P2-1). JS falls back to hashing base64. */
+    frameHash?: string;
+}
+
+/**
+ * Native device/session metadata result.
+ */
+export interface NativeDeviceMetadata {
+    deviceModel: string;
+    osVersion: string;
+    screenWidth: number;
+    screenHeight: number;
+    platform: 'android' | 'ios';
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    buildType?: 'debug' | 'release';
+}
+
+// ─── Frame Retention Policy ─────────────────────────────────────────────────
+
+/**
+ * Priority levels for frame retention when buffer is full.
+ * Higher priority frames are kept longer.
+ *
+ * CRASH_ADJACENT and ERROR_CONTEXT frames are NEVER dropped before
+ * generic NAVIGATION/INTERACTION/FREQUENCY frames.
+ */
+export enum FrameRetentionPriority {
+    /** Lowest: regular periodic captures */
+    FREQUENCY = 0,
+    /** Low: regular navigation frames */
+    NAVIGATION = 1,
+    /** Medium: interaction-triggered frames */
+    INTERACTION = 2,
+    /** Medium-high: manually triggered captures */
+    MANUAL = 3,
+    /** High: captured in response to an error event */
+    ERROR_CONTEXT = 4,
+    /** Highest: adjacent to a crash event — never drop before others */
+    CRASH_ADJACENT = 5,
+}
+
+/** Map CaptureReason → retention priority */
+export function getFrameRetentionPriority(reason: CaptureReason): FrameRetentionPriority {
+    switch (reason) {
+        case 'error-context': return FrameRetentionPriority.ERROR_CONTEXT;
+        case 'manual': return FrameRetentionPriority.MANUAL;
+        case 'interaction': return FrameRetentionPriority.INTERACTION;
+        case 'screen_loaded': return FrameRetentionPriority.INTERACTION; // Same priority as interaction
+        case 'scroll': return FrameRetentionPriority.INTERACTION;
+        case 'navigation': return FrameRetentionPriority.NAVIGATION;
+        case 'frequency': return FrameRetentionPriority.FREQUENCY;
+    }
+}
+
+// ─── Session Protocol Event Names ───────────────────────────────────────────
+
+export const SESSION_EVENTS = {
+    SESSION_START: 'session:start',
+    SESSION_END: 'session:end',
+    EVENT: 'session:event',
+    FRAME: 'session:frame',
+} as const;
+
+// ─── Event Retention Policy ─────────────────────────────────────────────────
+
+/**
+ * Priority levels for event retention when buffer is full.
+ * Crash/error events are NEVER dropped before generic events.
+ */
+export enum EventRetentionPriority {
+    LOG = 0,
+    NETWORK = 1,
+    LIFECYCLE = 2,
+    SCREEN_VIEW = 3,
+    USER_ACTION = 4,
+    ERROR = 5,
+    CRASH = 6,
+}
+
+/** Map JourneyEventType → retention priority */
+export function getEventRetentionPriority(type: JourneyEventType): EventRetentionPriority {
+    switch (type) {
+        case 'LOG_EMITTED': return EventRetentionPriority.LOG;
+        case 'NETWORK_REQUEST_STARTED':
+        case 'NETWORK_REQUEST_COMPLETED':
+        case 'NETWORK_REQUEST_FAILED': return EventRetentionPriority.NETWORK;
+        case 'APP_FOREGROUND':
+        case 'APP_BACKGROUND':
+        case 'SESSION_STARTED':
+        case 'SESSION_ENDED':
+        case 'LOADING_STARTED':
+        case 'LOADING_COMPLETED': return EventRetentionPriority.LIFECYCLE;
+        // An exit is the other half of a view and carries the dwell time, so it retains together with
+        // it — dropping exits first would leave entries whose duration can never be recovered.
+        case 'SCREEN_VIEW':
+        case 'SCREEN_EXIT': return EventRetentionPriority.SCREEN_VIEW;
+        case 'USER_ACTION':
+        case 'REPLAY_FRAME_CAPTURED': return EventRetentionPriority.USER_ACTION;
+        case 'ERROR_CAPTURED': return EventRetentionPriority.ERROR;
+        case 'CRASH_CAPTURED': return EventRetentionPriority.CRASH;
+    }
+}
+
+// ─── Re-exports from contracts ──────────────────────────────────────────────
+// Pure types are now canonical in @scalebun/sdk-contracts.
+// Runtime values (enums, constants, functions) remain here.
+export type {
+    Session as ContractSession,
+    SessionMetadata as ContractSessionMetadata,
+    SessionStatus as ContractSessionStatus,
+    JourneyEvent as ContractJourneyEvent,
+    JourneyEventType as ContractJourneyEventType,
+    ReplayFrame as ContractReplayFrame,
+    CaptureReason as ContractCaptureReason,
+    SessionReplayConfig as ContractSessionReplayConfig,
+    SessionTransport as ContractSessionTransport,
+    SyncCandidate as ContractSyncCandidate,
+    SyncDecision as ContractSyncDecision,
+    NativeFrameResult as ContractNativeFrameResult,
+    NativeDeviceMetadata as ContractNativeDeviceMetadata,
+} from '../../vendor/sdk-contracts';