@xhub-short/core 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,1466 @@
+import { VideoItem, IDataSource, IAnalytics, ILogger, ISessionStorage, SessionSnapshot, INetworkAdapter, IVideoLoader, IPosterLoader, VideoSource, IInteraction } from '@xhub-short/contracts';
+export { SessionSnapshot } from '@xhub-short/contracts';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Feed state for zustand store
+ */
+interface FeedState {
+    /** Normalized video data - Map for O(1) lookup */
+    itemsById: Map<string, VideoItem>;
+    /** Ordered list of video IDs for rendering */
+    displayOrder: string[];
+    /** Initial loading state */
+    loading: boolean;
+    /** Loading more (pagination) state */
+    loadingMore: boolean;
+    /** Error state */
+    error: FeedError | null;
+    /** Cursor for pagination */
+    cursor: string | null;
+    /** Whether more items can be loaded */
+    hasMore: boolean;
+    /** Whether data is stale and needs revalidation */
+    isStale: boolean;
+    /** Last successful fetch timestamp */
+    lastFetchTime: number | null;
+}
+/**
+ * Feed error with additional context
+ */
+interface FeedError {
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVER_ERROR' | 'UNKNOWN';
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Whether error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * FeedManager configuration
+ */
+interface FeedConfig {
+    /** Page size for pagination (default: 10) */
+    pageSize?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms (default: 1000) */
+    retryBaseDelay?: number;
+    /** Stale time in ms - data older than this will be revalidated (default: 5 minutes) */
+    staleTime?: number;
+    /** Whether to enable SWR pattern (default: true) */
+    enableSWR?: boolean;
+    /**
+     * Maximum number of videos to keep in memory cache
+     * When exceeded, older videos will be evicted (LRU policy)
+     * @default 100
+     */
+    maxCacheSize?: number;
+    /**
+     * Whether to enable automatic garbage collection
+     * @default true
+     */
+    enableGC?: boolean;
+}
+/**
+ * Default feed configuration
+ */
+declare const DEFAULT_FEED_CONFIG: Required<FeedConfig>;
+
+/**
+ * FeedManager - Manages video feed data with zustand/vanilla store
+ *
+ * Features:
+ * - Data normalization (Map for O(1) lookup + ordered IDs)
+ * - Deduplication
+ * - Race condition protection
+ * - Request deduplication (prevents duplicate API calls)
+ * - Exponential backoff retry
+ * - SWR pattern support
+ * - Garbage Collection (LRU eviction when cache exceeds maxCacheSize)
+ *
+ * @example
+ * ```typescript
+ * const feedManager = new FeedManager(dataSource, { pageSize: 10 });
+ *
+ * // Subscribe to state changes
+ * feedManager.store.subscribe((state) => console.log(state));
+ *
+ * // Load initial data
+ * await feedManager.loadInitial();
+ *
+ * // Load more
+ * await feedManager.loadMore();
+ * ```
+ */
+declare class FeedManager {
+    private readonly dataSource;
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<FeedState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Abort controller for cancelling in-flight requests */
+    private abortController;
+    /**
+     * Request deduplication: Map of cursor → in-flight Promise
+     * Prevents duplicate API calls for the same cursor
+     */
+    private inFlightRequests;
+    /**
+     * LRU tracking: Map of videoId → lastAccessTime
+     * Used for garbage collection
+     */
+    private accessOrder;
+    constructor(dataSource: IDataSource, config?: FeedConfig);
+    /**
+     * Load initial feed data
+     *
+     * Implements SWR pattern:
+     * 1. If cached data exists, show it immediately
+     * 2. If data is stale (>staleTime), revalidate in background
+     * 3. If no cached data, fetch from network
+     *
+     * Request Deduplication:
+     * - If a request for the same cursor is already in-flight, returns the existing Promise
+     * - Prevents duplicate API calls from rapid UI interactions
+     */
+    loadInitial(): Promise<void>;
+    /**
+     * Internal: Execute load initial logic
+     */
+    private executeLoadInitial;
+    /**
+     * Load more videos (pagination)
+     *
+     * Features:
+     * - Race condition protection (prevents concurrent calls)
+     * - Request deduplication (prevents duplicate API calls for same cursor)
+     * - Exponential backoff retry on failure
+     */
+    loadMore(): Promise<void>;
+    /**
+     * Internal: Execute load more logic
+     */
+    private executeLoadMore;
+    /**
+     * Revalidate feed data in background (SWR pattern)
+     *
+     * Used when cached data is stale but still shown to user
+     */
+    revalidate(): Promise<void>;
+    /**
+     * Get a video by ID
+     * Also updates LRU access time for garbage collection
+     */
+    getVideo(id: string): VideoItem | undefined;
+    /**
+     * Get ordered list of videos
+     */
+    getVideos(): VideoItem[];
+    /**
+     * Update a video in the feed (for optimistic updates)
+     */
+    updateVideo(id: string, updates: Partial<VideoItem>): void;
+    /**
+     * Check if data is stale and needs revalidation
+     */
+    isStale(): boolean;
+    /**
+     * Reset feed state
+     */
+    reset(): void;
+    /**
+     * Cancel any pending requests
+     */
+    cancelPendingRequests(): void;
+    /**
+     * Destroy the manager and cleanup
+     */
+    destroy(): void;
+    /**
+     * Fetch with exponential backoff retry
+     */
+    private fetchWithRetry;
+    /**
+     * Add videos with deduplication
+     * Triggers garbage collection if cache exceeds maxCacheSize
+     */
+    private addVideos;
+    /**
+     * Merge videos (for SWR revalidation)
+     * Updates existing videos, adds new ones at the beginning
+     */
+    private mergeVideos;
+    /**
+     * Handle and categorize errors
+     */
+    private handleError;
+    /**
+     * Categorize error for better error handling
+     */
+    private categorizeError;
+    /**
+     * Sleep utility for retry delays
+     */
+    private sleep;
+    /**
+     * Run garbage collection using LRU (Least Recently Used) policy
+     *
+     * When cache size exceeds maxCacheSize:
+     * 1. Sort videos by last access time (oldest first)
+     * 2. Evict oldest videos until cache is within limit
+     * 3. Keep videos that are currently in viewport (most recent in displayOrder)
+     *
+     * @returns Number of evicted items
+     */
+    private runGarbageCollection;
+    /**
+     * Manually trigger garbage collection
+     * Useful for debugging or when memory pressure is detected
+     *
+     * @returns Number of evicted items
+     */
+    forceGarbageCollection(): number;
+    /**
+     * Get current cache statistics
+     * Useful for debugging and monitoring
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        utilizationPercent: number;
+        oldestAccessTime: number | null;
+        newestAccessTime: number | null;
+    };
+}
+
+/**
+ * Player status enum - represents the current state of the player
+ */
+declare enum PlayerStatus {
+    /** Initial state - no video loaded */
+    IDLE = "idle",
+    /** Loading video resources */
+    LOADING = "loading",
+    /** Video is playing */
+    PLAYING = "playing",
+    /** Video is paused */
+    PAUSED = "paused",
+    /** Buffering due to network/resource constraints */
+    BUFFERING = "buffering",
+    /** Error occurred */
+    ERROR = "error"
+}
+/**
+ * Player error with context
+ */
+interface PlayerError {
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'MEDIA_ERROR' | 'NETWORK_ERROR' | 'DECODE_ERROR' | 'NOT_SUPPORTED' | 'UNKNOWN';
+    /** Whether the error is recoverable */
+    recoverable: boolean;
+    /** Original error if available */
+    originalError?: Error;
+}
+/**
+ * Player state for zustand store
+ */
+interface PlayerState {
+    /** Current player status */
+    status: PlayerStatus;
+    /** Currently loaded video */
+    currentVideo: VideoItem | null;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Video duration in seconds */
+    duration: number;
+    /** Buffered percentage (0-100) */
+    buffered: number;
+    /** Volume level (0-1) */
+    volume: number;
+    /** Whether video is muted */
+    muted: boolean;
+    /** Playback rate (1 = normal) */
+    playbackRate: number;
+    /** Loop count - how many times video has looped */
+    loopCount: number;
+    /** Total watch time in seconds for current video */
+    watchTime: number;
+    /** Error state */
+    error: PlayerError | null;
+    /** Whether video has ended */
+    ended: boolean;
+}
+/**
+ * PlayerEngine configuration
+ */
+interface PlayerConfig {
+    /** Auto-play when video is loaded (default: true) */
+    autoplay?: boolean;
+    /** Default volume (default: 1) */
+    defaultVolume?: number;
+    /** Default muted state (default: true for mobile) */
+    defaultMuted?: boolean;
+    /** Enable looping (default: true for short videos) */
+    loop?: boolean;
+    /** Analytics adapter for tracking */
+    analytics?: IAnalytics;
+    /** Logger adapter */
+    logger?: ILogger;
+    /** Watch time threshold for analytics (seconds) (default: 3) */
+    watchTimeThreshold?: number;
+    /** Completion threshold percentage (default: 90) */
+    completionThreshold?: number;
+    /** Circuit Breaker configuration */
+    circuitBreaker?: CircuitBreakerConfig;
+}
+/**
+ * Default player configuration
+ */
+declare const DEFAULT_PLAYER_CONFIG: Required<Omit<PlayerConfig, 'analytics' | 'logger' | 'circuitBreaker'>>;
+/**
+ * Player events for external listening
+ */
+type PlayerEvent = {
+    type: 'statusChange';
+    status: PlayerStatus;
+    previousStatus: PlayerStatus;
+} | {
+    type: 'timeUpdate';
+    currentTime: number;
+    duration: number;
+} | {
+    type: 'seek';
+    time: number;
+} | {
+    type: 'ended';
+    loopCount: number;
+    watchTime: number;
+} | {
+    type: 'error';
+    error: PlayerError;
+} | {
+    type: 'videoChange';
+    video: VideoItem | null;
+} | {
+    type: 'circuitOpened';
+    consecutiveErrors: number;
+    lastError: PlayerError;
+} | {
+    type: 'circuitHalfOpen';
+} | {
+    type: 'circuitClosed';
+    reason: 'success' | 'manual';
+} | {
+    type: 'loadRejected';
+    reason: 'circuit_open';
+};
+/**
+ * Player event listener
+ */
+type PlayerEventListener = (event: PlayerEvent) => void;
+/**
+ * Circuit Breaker state
+ *
+ * - CLOSED: Normal operation, allow load()
+ * - OPEN: Reject load(), return cached error (circuit tripped)
+ * - HALF_OPEN: Allow 1 try, success→CLOSED, fail→OPEN
+ */
+declare enum CircuitState {
+    /** Normal operation - allow video loading */
+    CLOSED = "closed",
+    /** Circuit tripped - reject video loading */
+    OPEN = "open",
+    /** Testing state - allow one request to test recovery */
+    HALF_OPEN = "half_open"
+}
+/**
+ * Circuit Breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Number of consecutive recoverable errors to trip the circuit
+     * @default 3
+     */
+    consecutiveErrorThreshold?: number;
+    /**
+     * Time in ms before transitioning from OPEN to HALF_OPEN
+     * @default 30000 (30 seconds)
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Number of successful loads needed to close the circuit from HALF_OPEN
+     * @default 1
+     */
+    successThreshold?: number;
+    /**
+     * Enable circuit breaker (default: true)
+     * Set to false to disable circuit breaker behavior
+     */
+    enabled?: boolean;
+}
+/**
+ * Circuit Breaker internal state
+ */
+interface CircuitBreakerState {
+    /** Current circuit state */
+    state: CircuitState;
+    /** Number of consecutive recoverable errors */
+    consecutiveErrors: number;
+    /** Number of successful loads in HALF_OPEN state */
+    halfOpenSuccesses: number;
+    /** Timestamp when circuit was opened (for reset timeout) */
+    openedAt: number | null;
+    /** Last error that caused the circuit to open */
+    lastError: PlayerError | null;
+}
+
+/**
+ * PlayerEngine - Video player state machine with zustand/vanilla store
+ *
+ * Features:
+ * - Guarded state transitions (only valid transitions allowed)
+ * - Watch time tracking
+ * - Loop count tracking
+ * - Analytics integration
+ * - Event system for external listeners
+ *
+ * @example
+ * ```typescript
+ * const player = new PlayerEngine({ analytics, logger });
+ *
+ * // Subscribe to state changes
+ * player.store.subscribe((state) => console.log(state.status));
+ *
+ * // Load and play a video
+ * player.load(videoItem);
+ *
+ * // Control playback
+ * player.play();
+ * player.pause();
+ * player.seek(10);
+ * ```
+ */
+declare class PlayerEngine {
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<PlayerState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Circuit Breaker configuration */
+    private readonly circuitBreakerConfig;
+    /** Analytics adapter */
+    private readonly analytics?;
+    /** Logger adapter */
+    private readonly logger?;
+    /** Event listeners */
+    private readonly eventListeners;
+    /** Watch time tracking interval */
+    private watchTimeInterval;
+    /** Last status for tracking transitions */
+    private lastStatus;
+    /** Circuit Breaker state */
+    private circuitBreaker;
+    /** Circuit Breaker reset timer */
+    private circuitResetTimer;
+    constructor(config?: PlayerConfig);
+    /**
+     * Load a video and prepare for playback
+     *
+     * @returns true if load was initiated, false if rejected (circuit open or invalid state)
+     */
+    load(video: VideoItem): boolean;
+    /**
+     * Called when video is ready to play (after loading)
+     */
+    onReady(): boolean;
+    /**
+     * Start or resume playback
+     */
+    play(): boolean;
+    /**
+     * Pause playback
+     */
+    pause(): boolean;
+    /**
+     * Seek to a specific time
+     *
+     * Emits a 'seek' event that VideoPlayer listens to
+     * to apply the seek to the actual video element.
+     */
+    seek(time: number): boolean;
+    /**
+     * Set volume
+     */
+    setVolume(volume: number): void;
+    /**
+     * Toggle mute
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Set playback rate
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Handle time update from video element
+     */
+    onTimeUpdate(currentTime: number): void;
+    /**
+     * Handle duration change from video element
+     *
+     * Called when video metadata is loaded and actual duration is available.
+     * This may differ from the API-provided duration in VideoItem.
+     *
+     * @param duration - Actual video duration in seconds from video element
+     */
+    onDurationChange(duration: number): void;
+    /**
+     * Handle buffering start
+     */
+    onBuffering(): boolean;
+    /**
+     * Handle buffering end
+     */
+    onBufferingEnd(): boolean;
+    /**
+     * Handle buffer progress update
+     */
+    onBufferProgress(bufferedPercent: number): void;
+    /**
+     * Handle video ended
+     */
+    onEnded(): void;
+    /**
+     * Handle video error
+     */
+    onError(error: Error, mediaError?: MediaError): void;
+    /**
+     * Reset player to initial state
+     */
+    reset(): void;
+    /**
+     * Destroy player and cleanup
+     */
+    destroy(): void;
+    /**
+     * Add event listener
+     */
+    addEventListener(listener: PlayerEventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    removeEventListener(listener: PlayerEventListener): void;
+    /**
+     * Get current status
+     */
+    getStatus(): PlayerStatus;
+    /**
+     * Get current video
+     */
+    getCurrentVideo(): VideoItem | null;
+    /**
+     * Check if playing
+     */
+    isPlaying(): boolean;
+    /**
+     * Check if paused
+     */
+    isPaused(): boolean;
+    /**
+     * Attempt to transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+    /**
+     * Start watch time tracking
+     */
+    private startWatchTimeTracking;
+    /**
+     * Stop watch time tracking
+     */
+    private stopWatchTimeTracking;
+    /**
+     * Track completion analytics
+     */
+    private trackCompletion;
+    /**
+     * Categorize media error
+     */
+    private categorizeError;
+    /**
+     * Get current circuit breaker state
+     */
+    getCircuitBreakerState(): CircuitBreakerState;
+    /**
+     * Check if circuit breaker is open (blocking loads)
+     */
+    isCircuitOpen(): boolean;
+    /**
+     * Manually reset circuit breaker to CLOSED state
+     * Useful for user-triggered retry after showing error UI
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Check if circuit breaker allows load operation
+     * Also handles OPEN → HALF_OPEN transition based on timeout
+     */
+    private checkCircuitBreaker;
+    /**
+     * Record a recoverable error for circuit breaker tracking
+     */
+    private recordCircuitBreakerError;
+    /**
+     * Record a successful load for circuit breaker tracking
+     */
+    private recordCircuitBreakerSuccess;
+    /**
+     * Trip the circuit breaker (CLOSED/HALF_OPEN → OPEN)
+     */
+    private tripCircuit;
+    /**
+     * Transition from OPEN to HALF_OPEN
+     */
+    private transitionToHalfOpen;
+    /**
+     * Close the circuit breaker (HALF_OPEN → CLOSED)
+     */
+    private closeCircuit;
+    /**
+     * Schedule automatic transition from OPEN to HALF_OPEN
+     */
+    private scheduleHalfOpenTransition;
+    /**
+     * Clear circuit reset timer
+     */
+    private clearCircuitResetTimer;
+}
+
+/**
+ * Check if a state transition is valid
+ */
+declare function isValidTransition(from: PlayerStatus, to: PlayerStatus): boolean;
+/**
+ * Check if player is in a "active" state (can receive playback commands)
+ */
+declare function isActiveState(status: PlayerStatus): boolean;
+/**
+ * Check if player can start playback
+ */
+declare function canPlay(status: PlayerStatus): boolean;
+/**
+ * Check if player can pause
+ */
+declare function canPause(status: PlayerStatus): boolean;
+/**
+ * Check if player can seek
+ */
+declare function canSeek(status: PlayerStatus): boolean;
+
+/**
+ * Lifecycle state for zustand store
+ */
+interface LifecycleState {
+    /** Whether manager is initialized */
+    isInitialized: boolean;
+    /** Whether there's a pending save operation */
+    isSaving: boolean;
+    /** Whether there's a pending restore operation */
+    isRestoring: boolean;
+    /** Last saved timestamp */
+    lastSavedAt: number | null;
+    /** Last restored timestamp */
+    lastRestoredAt: number | null;
+    /** Whether the restored snapshot needs revalidation */
+    needsRevalidation: boolean;
+    /** Current visibility state */
+    visibilityState: DocumentVisibilityState;
+}
+/**
+ * Restore result
+ */
+interface RestoreResult {
+    /** Whether restore was successful */
+    success: boolean;
+    /** Restored snapshot data (null if no valid snapshot) */
+    snapshot: SessionSnapshot | null;
+    /** Whether the restored data is stale and needs revalidation */
+    needsRevalidation: boolean;
+    /** Reason for failure (if any) */
+    reason?: 'no_snapshot' | 'expired' | 'invalid' | 'error';
+    /** Playback time in seconds (only present if restorePlaybackPosition config is enabled) */
+    playbackTime?: number;
+    /** Video ID that was playing (only present if restorePlaybackPosition config is enabled) */
+    currentVideoId?: string;
+}
+/**
+ * LifecycleManager configuration
+ */
+interface LifecycleConfig {
+    /** Storage adapter for persistence */
+    storage?: ISessionStorage;
+    /** Logger adapter */
+    logger?: ILogger;
+    /** Snapshot expiry time in ms (default: 24 hours) */
+    snapshotExpiryMs?: number;
+    /** Revalidation threshold in ms (default: 5 minutes) */
+    revalidationThresholdMs?: number;
+    /** Auto-save on visibility change (default: true) */
+    autoSaveOnHidden?: boolean;
+    /**
+     * Enable restoring video playback position (default: false)
+     * When enabled, saves and restores the exact playback time (seconds)
+     * so video can seek() to the exact position user was watching
+     */
+    restorePlaybackPosition?: boolean;
+    /** SDK version for compatibility */
+    version?: string;
+}
+/**
+ * Default lifecycle configuration
+ */
+declare const DEFAULT_LIFECYCLE_CONFIG: Required<Omit<LifecycleConfig, 'storage' | 'logger'>>;
+/**
+ * Lifecycle events for external listening
+ */
+type LifecycleEvent = {
+    type: 'saveStart';
+} | {
+    type: 'saveComplete';
+    timestamp: number;
+} | {
+    type: 'saveFailed';
+    error: Error;
+} | {
+    type: 'restoreStart';
+} | {
+    type: 'restoreComplete';
+    result: RestoreResult;
+} | {
+    type: 'visibilityChange';
+    state: DocumentVisibilityState;
+};
+/**
+ * Lifecycle event listener
+ */
+type LifecycleEventListener = (event: LifecycleEvent) => void;
+
+/**
+ * LifecycleManager - Handles session persistence and restoration
+ *
+ * Strategy: "State Persistence, DOM Destruction"
+ * - Save snapshot to storage when user leaves
+ * - Restore state from storage when user returns
+ * - Video DOM nodes are destroyed to free RAM
+ *
+ * Features:
+ * - Auto-save on visibility change (optional)
+ * - Snapshot expiry (24 hours default)
+ * - Stale data detection for revalidation
+ * - Event system for UI coordination
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = new LifecycleManager({ storage, logger });
+ *
+ * // Initialize and attempt restore
+ * const result = await lifecycle.initialize();
+ * if (result.success) {
+ *   feedManager.restoreFromSnapshot(result.snapshot);
+ *   if (result.needsRevalidation) {
+ *     feedManager.revalidate();
+ *   }
+ * }
+ *
+ * // Save snapshot before leaving
+ * lifecycle.saveSnapshot({
+ *   items: feedManager.getVideos(),
+ *   cursor: feedManager.store.getState().cursor,
+ *   focusedIndex: resourceGovernor.store.getState().focusedIndex,
+ * });
+ * ```
+ */
+declare class LifecycleManager {
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<LifecycleState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Storage adapter */
+    private readonly storage?;
+    /** Logger adapter */
+    private readonly logger?;
+    /** Event listeners */
+    private readonly eventListeners;
+    /** Visibility change handler reference (for cleanup) */
+    private visibilityHandler?;
+    /** Pending save data (for debouncing) */
+    private pendingSaveData?;
+    constructor(config?: LifecycleConfig);
+    /**
+     * Initialize lifecycle manager and attempt to restore session
+     */
+    initialize(): Promise<RestoreResult>;
+    /**
+     * Destroy lifecycle manager and cleanup
+     */
+    destroy(): void;
+    /**
+     * Restore session from storage
+     */
+    restoreSession(): Promise<RestoreResult>;
+    /**
+     * Save session snapshot to storage
+     *
+     * @param data - Snapshot data to save
+     * @param data.playbackTime - Current video playback position (only saved if restorePlaybackPosition config is enabled)
+     * @param data.currentVideoId - Current video ID (only saved if restorePlaybackPosition config is enabled)
+     */
+    saveSnapshot(data: {
+        items: VideoItem[];
+        cursor: string | null;
+        focusedIndex: number;
+        scrollPosition?: number;
+        /** Current video playback time in seconds (only used when restorePlaybackPosition is enabled) */
+        playbackTime?: number;
+        /** Current video ID (only used when restorePlaybackPosition is enabled) */
+        currentVideoId?: string;
+    }): Promise<boolean>;
+    /**
+     * Clear saved snapshot
+     */
+    clearSnapshot(): Promise<void>;
+    /**
+     * Mark that pending data should be saved (for use with debouncing)
+     *
+     * @param data - Data to save when flush is called
+     */
+    setPendingSave(data: Omit<SessionSnapshot, 'savedAt' | 'version'>): void;
+    /**
+     * Check if restorePlaybackPosition config is enabled
+     * SDK can use this to decide whether to collect playbackTime
+     */
+    isPlaybackPositionRestoreEnabled(): boolean;
+    /**
+     * Flush pending save (called on visibility hidden)
+     */
+    flushPendingSave(): Promise<void>;
+    /**
+     * Handle visibility state change
+     */
+    onVisibilityChange(state: DocumentVisibilityState): void;
+    /**
+     * Get current visibility state
+     */
+    getVisibilityState(): DocumentVisibilityState;
+    /**
+     * Add event listener
+     */
+    addEventListener(listener: LifecycleEventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    removeEventListener(listener: LifecycleEventListener): void;
+    /**
+     * Setup visibility change listener
+     */
+    private setupVisibilityListener;
+    /**
+     * Validate snapshot data
+     */
+    private validateSnapshot;
+    /**
+     * Check if snapshot is stale (needs revalidation)
+     */
+    private isSnapshotStale;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+}
+
+/**
+ * Network type for prefetch strategy
+ * Simplified from contracts NetworkType for prefetch decisions
+ */
+type NetworkType = 'wifi' | 'cellular' | 'offline';
+/**
+ * Map contracts NetworkType to simplified NetworkType
+ */
+declare function mapNetworkType(type: string): NetworkType;
+/**
+ * Resource state for zustand store
+ */
+interface ResourceState {
+    /** Currently allocated video slot indices (max 3) */
+    activeAllocations: Set<number>;
+    /** Queue of indices to preload */
+    preloadQueue: number[];
+    /** Currently focused/playing video index */
+    focusedIndex: number;
+    /** Current network type */
+    networkType: NetworkType;
+    /** Total number of items in feed (for bounds checking) */
+    totalItems: number;
+    /** Whether resource governor is active */
+    isActive: boolean;
+    /** Whether preloading is throttled due to scroll thrashing */
+    isThrottled: boolean;
+    /** Indices currently being preloaded */
+    preloadingIndices: Set<number>;
+}
+/**
+ * Allocation result returned by requestAllocation
+ */
+interface AllocationResult {
+    /** Indices that should mount video elements */
+    toMount: number[];
+    /** Indices that should unmount video elements */
+    toUnmount: number[];
+    /** Currently active allocations after this operation */
+    activeAllocations: number[];
+    /** Whether focus change was successful */
+    success: boolean;
+}
+/**
+ * Prefetch configuration by network type
+ */
+interface PrefetchConfig {
+    /** Number of posters to prefetch ahead (default: wifi=5, cellular=3, offline=1) */
+    posterCount: number;
+    /** Number of video segments to prefetch (default: wifi=2, cellular=1, offline=0) */
+    videoSegmentCount: number;
+    /** Whether to prefetch video at all (default: true for wifi/cellular) */
+    prefetchVideo: boolean;
+}
+/**
+ * Scroll thrashing configuration
+ * Prevents excessive preloading when user scrolls too fast
+ */
+interface ScrollThrashingConfig {
+    /** Time window to measure scroll rate (ms) - default: 1000 */
+    windowMs: number;
+    /** Max focus changes allowed in window before throttling - default: 3 */
+    maxChangesInWindow: number;
+    /** Cooldown time after throttle before resuming preload (ms) - default: 500 */
+    cooldownMs: number;
+}
+/**
+ * ResourceGovernor configuration
+ */
+interface ResourceConfig {
+    /** Maximum video DOM nodes (default: 3) */
+    maxAllocations?: number;
+    /** Focus debounce time in ms (default: 150) */
+    focusDebounceMs?: number;
+    /** Prefetch configuration overrides by network type */
+    prefetch?: Partial<Record<NetworkType, Partial<PrefetchConfig>>>;
+    /** Scroll thrashing configuration */
+    scrollThrashing?: Partial<ScrollThrashingConfig>;
+    /** Network adapter for detecting connection type */
+    networkAdapter?: INetworkAdapter;
+    /** Video loader adapter for preloading video data */
+    videoLoader?: IVideoLoader;
+    /** Poster loader adapter for preloading thumbnails */
+    posterLoader?: IPosterLoader;
+    /** Logger adapter */
+    logger?: ILogger;
+}
+/**
+ * Default prefetch configuration by network type
+ */
+declare const DEFAULT_PREFETCH_CONFIG: Record<NetworkType, PrefetchConfig>;
+/**
+ * Default resource configuration
+ */
+declare const DEFAULT_RESOURCE_CONFIG: Required<Omit<ResourceConfig, 'networkAdapter' | 'videoLoader' | 'posterLoader' | 'logger' | 'prefetch' | 'scrollThrashing'>> & {
+    prefetch: Record<NetworkType, PrefetchConfig>;
+    scrollThrashing: ScrollThrashingConfig;
+};
+/**
+ * Resource events for external listening
+ */
+type ResourceEvent = {
+    type: 'allocationChange';
+    toMount: number[];
+    toUnmount: number[];
+} | {
+    type: 'focusChange';
+    index: number;
+    previousIndex: number;
+} | {
+    type: 'networkChange';
+    networkType: NetworkType;
+} | {
+    type: 'prefetchRequest';
+    indices: number[];
+};
+/**
+ * Resource event listener
+ */
+type ResourceEventListener = (event: ResourceEvent) => void;
+
+/**
+ * Video source getter function type
+ * ResourceGovernor needs this to get video sources for preloading
+ */
+type VideoSourceGetter = (index: number) => {
+    id: string;
+    source: VideoSource;
+    poster?: string;
+} | null;
+/**
+ * ResourceGovernor - Manages video DOM allocation and prefetch strategy
+ *
+ * Features:
+ * - Sliding window allocation (max 3 video DOM nodes)
+ * - Focus debouncing for smooth swipe
+ * - Network-aware prefetch strategy
+ * - Event system for UI synchronization
+ *
+ * Memory Strategy:
+ * - Only 3 video elements exist in DOM at any time
+ * - Sliding window: [previous, current, next]
+ * - When user scrolls, we unmount far elements and mount new ones
+ *
+ * @example
+ * ```typescript
+ * const governor = new ResourceGovernor({ maxAllocations: 3 });
+ *
+ * // Initialize with feed size
+ * governor.setTotalItems(20);
+ * governor.activate();
+ *
+ * // Handle scroll/swipe
+ * governor.setFocusedIndex(5); // Debounced
+ *
+ * // Listen to allocation changes
+ * governor.addEventListener((event) => {
+ *   if (event.type === 'allocationChange') {
+ *     event.toMount.forEach(i => mountVideoAt(i));
+ *     event.toUnmount.forEach(i => unmountVideoAt(i));
+ *   }
+ * });
+ * ```
+ */
+declare class ResourceGovernor {
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<ResourceState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Network adapter */
+    private readonly networkAdapter?;
+    /** Video loader adapter for preloading video data */
+    private readonly videoLoader?;
+    /** Poster loader adapter for preloading thumbnails */
+    private readonly posterLoader?;
+    /** Logger adapter */
+    private readonly logger?;
+    /** Event listeners */
+    private readonly eventListeners;
+    /** Focus debounce timer */
+    private focusDebounceTimer;
+    /** Pending focused index (before debounce completes) */
+    private pendingFocusedIndex;
+    /** Network change unsubscribe function */
+    private networkUnsubscribe?;
+    /** Video source getter (injected via setVideoSourceGetter) */
+    private videoSourceGetter?;
+    /** Scroll thrashing detection - timestamps of recent focus changes */
+    private focusChangeTimestamps;
+    /** Scroll thrashing cooldown timer */
+    private thrashingCooldownTimer;
+    constructor(config?: ResourceConfig);
+    /**
+     * Activate the resource governor
+     * Starts network monitoring and performs initial allocation
+     */
+    activate(): Promise<void>;
+    /**
+     * Deactivate the resource governor
+     * Stops network monitoring and clears allocations
+     */
+    deactivate(): void;
+    /**
+     * Destroy the resource governor
+     */
+    destroy(): void;
+    /**
+     * Set total number of items in feed
+     */
+    setTotalItems(count: number): void;
+    /**
+     * Set focused index with debouncing
+     * This is called during scroll/swipe
+     */
+    setFocusedIndex(index: number): void;
+    /**
+     * Set focused index immediately (skip debounce)
+     * Use this for programmatic navigation, not scroll
+     */
+    setFocusedIndexImmediate(index: number): void;
+    /**
+     * Request allocation for given indices
+     * Returns what needs to be mounted/unmounted
+     */
+    requestAllocation(indices: number[]): AllocationResult;
+    /**
+     * Get current active allocations
+     */
+    getActiveAllocations(): number[];
+    /**
+     * Check if an index is currently allocated
+     */
+    isAllocated(index: number): boolean;
+    /**
+     * Get current network type
+     */
+    getNetworkType(): NetworkType;
+    /**
+     * Get prefetch configuration for current network
+     */
+    getPrefetchConfig(): PrefetchConfig;
+    /**
+     * Set video source getter function
+     * This is called by SDK to provide video data for preloading
+     *
+     * @param getter - Function that returns video info for a given index
+     */
+    setVideoSourceGetter(getter: VideoSourceGetter): void;
+    /**
+     * Check if preloading is currently throttled due to scroll thrashing
+     */
+    isPreloadThrottled(): boolean;
+    /**
+     * Get indices currently being preloaded
+     */
+    getPreloadingIndices(): number[];
+    /**
+     * Manually trigger preload for specific indices
+     * Respects throttling and network conditions
+     */
+    triggerPreload(indices: number[]): Promise<void>;
+    /**
+     * Add event listener
+     */
+    addEventListener(listener: ResourceEventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    removeEventListener(listener: ResourceEventListener): void;
+    /**
+     * Initialize network detection
+     */
+    private initializeNetwork;
+    /**
+     * Perform allocation for a given focused index
+     */
+    private performAllocation;
+    /**
+     * Update prefetch queue based on current state
+     */
+    private updatePrefetchQueue;
+    /**
+     * Track focus change timestamp for scroll thrashing detection
+     */
+    private trackFocusChange;
+    /**
+     * Cancel all in-progress preloads
+     */
+    private cancelAllPreloads;
+    /**
+     * Execute video preloading for given indices
+     */
+    private executePreload;
+    /**
+     * Execute poster preloading for given indices
+     */
+    private executePreloadPosters;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+}
+
+/**
+ * Calculate sliding window allocation around focused index
+ *
+ * The sliding window strategy:
+ * - Always allocate focused index (current video)
+ * - Allocate previous index (for scroll up)
+ * - Allocate next index (for scroll down)
+ * - Total max 3 allocations
+ *
+ * @param focusedIndex Current focused video index
+ * @param totalItems Total number of items in feed
+ * @param maxAllocations Maximum allocations allowed (default: 3)
+ * @returns Array of indices that should be allocated
+ */
+declare function calculateWindowIndices(focusedIndex: number, totalItems: number, maxAllocations?: number): number[];
+/**
+ * Calculate prefetch indices beyond the window
+ *
+ * @param focusedIndex Current focused video index
+ * @param totalItems Total number of items in feed
+ * @param prefetchCount Number of items to prefetch ahead
+ * @param windowIndices Currently allocated window indices
+ * @returns Array of indices to prefetch (posters)
+ */
+declare function calculatePrefetchIndices(focusedIndex: number, totalItems: number, prefetchCount: number, windowIndices: number[]): number[];
+/**
+ * Compute allocation changes between current and desired state
+ *
+ * @param currentAllocations Current active allocations
+ * @param desiredAllocations Desired allocations based on new focus
+ * @returns AllocationResult with toMount and toUnmount arrays
+ */
+declare function computeAllocationChanges(currentAllocations: Set<number>, desiredAllocations: number[]): Omit<AllocationResult, 'success'>;
+
+/**
+ * Types of optimistic actions
+ */
+type ActionType = 'like' | 'unlike' | 'follow' | 'unfollow';
+/**
+ * Pending optimistic action
+ */
+interface PendingAction {
+    /** Unique action ID */
+    id: string;
+    /** Action type */
+    type: ActionType;
+    /** Target video ID */
+    videoId: string;
+    /** Data to rollback to on failure */
+    rollbackData: Partial<VideoItem>;
+    /** Timestamp when action was initiated */
+    timestamp: number;
+    /** Current status */
+    status: 'pending' | 'success' | 'failed';
+    /** Number of retry attempts */
+    retryCount: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Optimistic state for zustand store
+ */
+interface OptimisticState {
+    /** Map of pending actions by ID */
+    pendingActions: Map<string, PendingAction>;
+    /** Queue of failed actions for retry */
+    failedQueue: string[];
+    /** Whether there are any pending actions */
+    hasPending: boolean;
+    /** Whether retry is in progress */
+    isRetrying: boolean;
+}
+/**
+ * OptimisticManager configuration
+ */
+interface OptimisticConfig {
+    /** Interaction adapter for API calls */
+    interaction?: IInteraction;
+    /** FeedManager for updating video state */
+    feedManager?: FeedManager;
+    /** Logger adapter */
+    logger?: ILogger;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in ms (default: 1000) */
+    retryDelayMs?: number;
+    /** Whether to auto-retry failed actions (default: true) */
+    autoRetry?: boolean;
+}
+/**
+ * Default optimistic configuration
+ */
+declare const DEFAULT_OPTIMISTIC_CONFIG: Required<Omit<OptimisticConfig, 'interaction' | 'feedManager' | 'logger'>>;
+/**
+ * Optimistic events for external listening
+ */
+type OptimisticEvent = {
+    type: 'actionStart';
+    action: PendingAction;
+} | {
+    type: 'actionSuccess';
+    action: PendingAction;
+} | {
+    type: 'actionFailed';
+    action: PendingAction;
+    error: Error;
+} | {
+    type: 'actionRollback';
+    action: PendingAction;
+} | {
+    type: 'retryStart';
+    actionId: string;
+} | {
+    type: 'retryExhausted';
+    action: PendingAction;
+};
+/**
+ * Optimistic event listener
+ */
+type OptimisticEventListener = (event: OptimisticEvent) => void;
+
+/**
+ * OptimisticManager - Handles optimistic UI updates with rollback
+ *
+ * Pattern:
+ * 1. User action (like) -> Update UI immediately
+ * 2. Call API in background
+ * 3. On success -> Keep UI state, remove pending action
+ * 4. On error -> Rollback to previous state
+ *
+ * Features:
+ * - Immediate UI feedback
+ * - Automatic rollback on failure
+ * - Retry queue for failed actions
+ * - Prevents duplicate pending actions
+ *
+ * @example
+ * ```typescript
+ * const optimistic = new OptimisticManager({
+ *   interaction,
+ *   feedManager,
+ *   logger,
+ * });
+ *
+ * // User taps like button
+ * await optimistic.like(videoId);
+ *
+ * // User taps follow button
+ * await optimistic.follow(videoId);
+ * ```
+ */
+declare class OptimisticManager {
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<OptimisticState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Interaction adapter */
+    private readonly interaction?;
+    /** Feed manager for updating video state */
+    private readonly feedManager?;
+    /** Logger adapter */
+    private readonly logger?;
+    /** Event listeners */
+    private readonly eventListeners;
+    /** Retry timer */
+    private retryTimer;
+    constructor(config?: OptimisticConfig);
+    /**
+     * Like a video with optimistic update
+     */
+    like(videoId: string): Promise<boolean>;
+    /**
+     * Unlike a video with optimistic update
+     */
+    unlike(videoId: string): Promise<boolean>;
+    /**
+     * Toggle like state (like if not liked, unlike if liked)
+     */
+    toggleLike(videoId: string): Promise<boolean>;
+    /**
+     * Follow a video author with optimistic update
+     */
+    follow(videoId: string): Promise<boolean>;
+    /**
+     * Unfollow a video author with optimistic update
+     */
+    unfollow(videoId: string): Promise<boolean>;
+    /**
+     * Toggle follow state
+     */
+    toggleFollow(videoId: string): Promise<boolean>;
+    /**
+     * Get all pending actions
+     */
+    getPendingActions(): PendingAction[];
+    /**
+     * Check if there's a pending action for a video
+     */
+    hasPendingAction(videoId: string, type?: ActionType): boolean;
+    /**
+     * Get failed actions queue
+     */
+    getFailedQueue(): PendingAction[];
+    /**
+     * Manually retry failed actions
+     */
+    retryFailed(): Promise<void>;
+    /**
+     * Clear all failed actions
+     */
+    clearFailed(): void;
+    /**
+     * Reset manager state
+     */
+    reset(): void;
+    /**
+     * Destroy manager and cleanup
+     */
+    destroy(): void;
+    /**
+     * Add event listener
+     */
+    addEventListener(listener: OptimisticEventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    removeEventListener(listener: OptimisticEventListener): void;
+    /**
+     * Perform an optimistic action
+     */
+    private performAction;
+    /**
+     * Create rollback data based on action type
+     */
+    private createRollbackData;
+    /**
+     * Apply optimistic update to feed
+     */
+    private applyOptimisticUpdate;
+    /**
+     * Apply rollback
+     */
+    private applyRollback;
+    /**
+     * Add pending action to store
+     */
+    private addPendingAction;
+    /**
+     * Mark action as success
+     */
+    private markActionSuccess;
+    /**
+     * Mark action as failed
+     */
+    private markActionFailed;
+    /**
+     * Retry a failed action
+     */
+    private retryAction;
+    /**
+     * Execute API call based on action type
+     */
+    private executeApiCall;
+    /**
+     * Schedule retry of failed actions
+     */
+    private scheduleRetry;
+    /**
+     * Cancel retry timer
+     */
+    private cancelRetryTimer;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+}
+
+export { type ActionType, type AllocationResult, DEFAULT_FEED_CONFIG, DEFAULT_LIFECYCLE_CONFIG, DEFAULT_OPTIMISTIC_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_PREFETCH_CONFIG, DEFAULT_RESOURCE_CONFIG, type FeedConfig, type FeedError, FeedManager, type FeedState, type LifecycleConfig, type LifecycleEvent, type LifecycleEventListener, LifecycleManager, type LifecycleState, type NetworkType, type OptimisticConfig, type OptimisticEvent, type OptimisticEventListener, OptimisticManager, type OptimisticState, type PendingAction, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PrefetchConfig, type ResourceConfig, type ResourceEvent, type ResourceEventListener, ResourceGovernor, type ResourceState, type RestoreResult, calculatePrefetchIndices, calculateWindowIndices, canPause, canPlay, canSeek, computeAllocationChanges, isActiveState, isValidTransition, mapNetworkType };