@xhub-short/core 0.1.0-beta.11 → 0.1.0-beta.12

package/dist/index.d.ts

@@ -1,7 +1,314 @@
-import { VideoItem, IDataSource, IStorage, PrefetchCacheData, IAnalytics, ILogger, ISessionStorage, SessionSnapshot, INetworkAdapter, IVideoLoader, IPosterLoader, VideoSource, IInteraction, CommentItem, ReplyItem, ICommentAdapter, InternalLogger, CommentAuthor } from '@xhub-short/contracts';
+import { INetworkAdapter, IVideoLoader, IPosterLoader, ILogger, VideoSource, VideoItem, IDataSource, IStorage, PrefetchCacheData, IAnalytics, ISessionStorage, SessionSnapshot, IInteraction, CommentItem, ReplyItem, ICommentAdapter, InternalLogger, CommentAuthor, PlaylistData, ContentItem, PlaylistSummary, IPlaylistDataSource } from '@xhub-short/contracts';
 export { SessionSnapshot } from '@xhub-short/contracts';
 import { StoreApi } from 'zustand/vanilla';
 
+/**
+ * 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;
+    /**
+     * Internal helper to preload a single video
+     */
+    private preloadOne;
+    /**
+     * Execute poster preloading for given indices
+     */
+    private executePreloadPosters;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+}
+
 /**
  * Feed state for zustand store
  */
@@ -148,7 +455,8 @@ declare const DEFAULT_PREFETCH_CACHE_CONFIG: PrefetchCacheConfig;
  * ```
  */
 declare class FeedManager {
-    private readonly dataSource;
+    private dataSource;
+    private readonly logger?;
     /** Zustand vanilla store - Single Source of Truth */
     readonly store: StoreApi<FeedState>;
     /** Resolved configuration */
@@ -169,7 +477,12 @@ declare class FeedManager {
      * Used for garbage collection
      */
     private accessOrder;
-    constructor(dataSource: IDataSource, config?: FeedConfig, storage?: IStorage, prefetchConfig?: Partial<PrefetchCacheConfig>);
+    /**
+     * Track videos that have already triggered predictive preload
+     * to avoid duplicate requests.
+     */
+    private preloadedVideoIds;
+    constructor(dataSource: IDataSource, config?: FeedConfig, storage?: IStorage, prefetchConfig?: Partial<PrefetchCacheConfig>, logger?: ILogger | undefined);
     /** Static memory cache for explicit prefetching */
     private static globalMemoryCache;
     /**
@@ -189,6 +502,21 @@ declare class FeedManager {
      * Clear prefetch cache
      */
     static clearPrefetchCache(): void;
+    /**
+     * Get current data source
+     */
+    getDataSource(): IDataSource;
+    /**
+     * Update data source dynamically
+     * Used for switching between Recommendation and Playlist modes
+     *
+     * @param dataSource - New data source adapter
+     * @param options - Options for state transition
+     */
+    setDataSource(dataSource: IDataSource, options?: {
+        /** Whether to reset the feed state immediately */
+        reset?: boolean;
+    }): void;
     /**
      * Load initial feed data
      *
@@ -201,7 +529,9 @@ declare class FeedManager {
      * - 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>;
+    loadInitial(options?: {
+        replace?: boolean;
+    }): Promise<void>;
     /**
      * Internal: Execute load initial logic
      */
@@ -225,6 +555,15 @@ declare class FeedManager {
      * Used when cached data is stale but still shown to user
      */
     revalidate(): Promise<void>;
+    /**
+     * Handle playback progress and trigger predictive preloading
+     *
+     * @param videoId - ID of the currently playing video
+     * @param progress - Current playback progress (0-1)
+     * @param governor - Resource governor to trigger preload
+     * @param threshold - Progress threshold to trigger preload (default: 0.2)
+     */
+    handlePlaybackProgress(videoId: string, progress: number, governor: ResourceGovernor, threshold?: number): void;
     /**
      * Get a video by ID
      * Also updates LRU access time for garbage collection
@@ -238,6 +577,10 @@ declare class FeedManager {
      * Update a video in the feed (for optimistic updates)
      */
     updateVideo(id: string, updates: Partial<VideoItem>): void;
+    /**
+     * Replace all items in the feed (e.g. for Playlist synchronization)
+     */
+    replaceItems(items: VideoItem[]): void;
     /**
      * Remove an item from the feed
      *
@@ -820,606 +1163,307 @@ declare class PlayerEngine {
      */
     private trackCompletion;
     /**
-     * Track when user leaves current video (scrolls to next video)
-     * Sends final analytics event before video change
-     */
-    private trackLeaveVideo;
-    /**
-     * 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;
-    /** Captured video frame at playback position (base64 JPEG, only present if restorePlaybackPosition is enabled) */
-    restoreFrame?: 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)
-     * @param data.restoreFrame - Captured video frame at playback position (only saved if restorePlaybackPosition is enabled)
+     * Track when user leaves current video (scrolls to next video)
+     * Sends final analytics event before video change
      */
-    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;
-        /** Captured video frame at playback position (only used when restorePlaybackPosition is enabled) */
-        restoreFrame?: string;
-    }): Promise<boolean>;
+    private trackLeaveVideo;
     /**
-     * Clear saved snapshot
+     * Categorize media error
      */
-    clearSnapshot(): Promise<void>;
+    private categorizeError;
     /**
-     * Mark that pending data should be saved (for use with debouncing)
-     *
-     * @param data - Data to save when flush is called
+     * Get current circuit breaker state
      */
-    setPendingSave(data: Omit<SessionSnapshot, 'savedAt' | 'version'>): void;
+    getCircuitBreakerState(): CircuitBreakerState;
     /**
-     * Check if restorePlaybackPosition config is enabled
-     * SDK can use this to decide whether to collect playbackTime
+     * Check if circuit breaker is open (blocking loads)
      */
-    isPlaybackPositionRestoreEnabled(): boolean;
+    isCircuitOpen(): boolean;
     /**
-     * Flush pending save (called on visibility hidden)
+     * Manually reset circuit breaker to CLOSED state
+     * Useful for user-triggered retry after showing error UI
      */
-    flushPendingSave(): Promise<void>;
+    resetCircuitBreaker(): void;
     /**
-     * Handle visibility state change
+     * Check if circuit breaker allows load operation
+     * Also handles OPEN → HALF_OPEN transition based on timeout
      */
-    onVisibilityChange(state: DocumentVisibilityState): void;
+    private checkCircuitBreaker;
     /**
-     * Get current visibility state
+     * Record a recoverable error for circuit breaker tracking
      */
-    getVisibilityState(): DocumentVisibilityState;
+    private recordCircuitBreakerError;
     /**
-     * Add event listener
+     * Record a successful load for circuit breaker tracking
      */
-    addEventListener(listener: LifecycleEventListener): () => void;
+    private recordCircuitBreakerSuccess;
     /**
-     * Remove event listener
+     * Trip the circuit breaker (CLOSED/HALF_OPEN → OPEN)
      */
-    removeEventListener(listener: LifecycleEventListener): void;
+    private tripCircuit;
     /**
-     * Setup visibility change listener
+     * Transition from OPEN to HALF_OPEN
      */
-    private setupVisibilityListener;
+    private transitionToHalfOpen;
     /**
-     * Validate snapshot data
+     * Close the circuit breaker (HALF_OPEN → CLOSED)
      */
-    private validateSnapshot;
+    private closeCircuit;
     /**
-     * Check if snapshot is stale (needs revalidation)
+     * Schedule automatic transition from OPEN to HALF_OPEN
      */
-    private isSnapshotStale;
+    private scheduleHalfOpenTransition;
     /**
-     * Emit event to all listeners
+     * Clear circuit reset timer
      */
-    private emitEvent;
+    private clearCircuitResetTimer;
 }
 
 /**
- * Network type for prefetch strategy
- * Simplified from contracts NetworkType for prefetch decisions
+ * Check if a state transition is valid
  */
-type NetworkType = 'wifi' | 'cellular' | 'offline';
+declare function isValidTransition(from: PlayerStatus, to: PlayerStatus): boolean;
 /**
- * Map contracts NetworkType to simplified NetworkType
+ * Check if player is in a "active" state (can receive playback commands)
  */
-declare function mapNetworkType(type: string): NetworkType;
+declare function isActiveState(status: PlayerStatus): boolean;
 /**
- * Resource state for zustand store
+ * Check if player can start playback
  */
-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>;
-}
+declare function canPlay(status: PlayerStatus): boolean;
 /**
- * Allocation result returned by requestAllocation
+ * Check if player can pause
  */
-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;
-}
+declare function canPause(status: PlayerStatus): boolean;
 /**
- * Prefetch configuration by network type
+ * Check if player can seek
  */
-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;
+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;
 }
 /**
- * Scroll thrashing configuration
- * Prevents excessive preloading when user scrolls too fast
+ * Restore result
  */
-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;
+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;
+    /** Captured video frame at playback position (base64 JPEG, only present if restorePlaybackPosition is enabled) */
+    restoreFrame?: string;
 }
 /**
- * ResourceGovernor configuration
+ * LifecycleManager 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;
+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 prefetch configuration by network type
- */
-declare const DEFAULT_PREFETCH_CONFIG: Record<NetworkType, PrefetchConfig>;
-/**
- * Default resource configuration
+ * Default lifecycle configuration
  */
-declare const DEFAULT_RESOURCE_CONFIG: Required<Omit<ResourceConfig, 'networkAdapter' | 'videoLoader' | 'posterLoader' | 'logger' | 'prefetch' | 'scrollThrashing'>> & {
-    prefetch: Record<NetworkType, PrefetchConfig>;
-    scrollThrashing: ScrollThrashingConfig;
-};
+declare const DEFAULT_LIFECYCLE_CONFIG: Required<Omit<LifecycleConfig, 'storage' | 'logger'>>;
 /**
- * Resource events for external listening
+ * Lifecycle events for external listening
  */
-type ResourceEvent = {
-    type: 'allocationChange';
-    toMount: number[];
-    toUnmount: number[];
+type LifecycleEvent = {
+    type: 'saveStart';
 } | {
-    type: 'focusChange';
-    index: number;
-    previousIndex: number;
+    type: 'saveComplete';
+    timestamp: number;
 } | {
-    type: 'networkChange';
-    networkType: NetworkType;
+    type: 'saveFailed';
+    error: Error;
 } | {
-    type: 'prefetchRequest';
-    indices: number[];
+    type: 'restoreStart';
+} | {
+    type: 'restoreComplete';
+    result: RestoreResult;
+} | {
+    type: 'visibilityChange';
+    state: DocumentVisibilityState;
 };
 /**
- * Resource event listener
+ * Lifecycle event listener
  */
-type ResourceEventListener = (event: ResourceEvent) => void;
+type LifecycleEventListener = (event: LifecycleEvent) => 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
+ * LifecycleManager - Handles session persistence and restoration
  *
- * Features:
- * - Sliding window allocation (max 3 video DOM nodes)
- * - Focus debouncing for smooth swipe
- * - Network-aware prefetch strategy
- * - Event system for UI synchronization
+ * 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
  *
- * 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
+ * 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 governor = new ResourceGovernor({ maxAllocations: 3 });
- *
- * // Initialize with feed size
- * governor.setTotalItems(20);
- * governor.activate();
- *
- * // Handle scroll/swipe
- * governor.setFocusedIndex(5); // Debounced
+ * const lifecycle = new LifecycleManager({ storage, logger });
  *
- * // Listen to allocation changes
- * governor.addEventListener((event) => {
- *   if (event.type === 'allocationChange') {
- *     event.toMount.forEach(i => mountVideoAt(i));
- *     event.toUnmount.forEach(i => unmountVideoAt(i));
+ * // 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 ResourceGovernor {
+declare class LifecycleManager {
     /** Zustand vanilla store - Single Source of Truth */
-    readonly store: StoreApi<ResourceState>;
+    readonly store: StoreApi<LifecycleState>;
     /** 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?;
+    /** Storage adapter */
+    private readonly storage?;
     /** 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>;
+    /** Visibility change handler reference (for cleanup) */
+    private visibilityHandler?;
+    /** Pending save data (for debouncing) */
+    private pendingSaveData?;
+    constructor(config?: LifecycleConfig);
     /**
-     * Deactivate the resource governor
-     * Stops network monitoring and clears allocations
+     * Initialize lifecycle manager and attempt to restore session
      */
-    deactivate(): void;
+    initialize(): Promise<RestoreResult>;
     /**
-     * Destroy the resource governor
+     * Destroy lifecycle manager and cleanup
      */
     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
+     * Restore session from storage
      */
-    getActiveAllocations(): number[];
+    restoreSession(): Promise<RestoreResult>;
     /**
-     * Check if an index is currently allocated
+     * 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)
+     * @param data.restoreFrame - Captured video frame at playback position (only saved if restorePlaybackPosition is enabled)
      */
-    isAllocated(index: number): boolean;
+    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;
+        /** Captured video frame at playback position (only used when restorePlaybackPosition is enabled) */
+        restoreFrame?: string;
+    }): Promise<boolean>;
     /**
-     * Get current network type
+     * Clear saved snapshot
      */
-    getNetworkType(): NetworkType;
+    clearSnapshot(): Promise<void>;
     /**
-     * Get prefetch configuration for current network
+     * Mark that pending data should be saved (for use with debouncing)
+     *
+     * @param data - Data to save when flush is called
      */
-    getPrefetchConfig(): PrefetchConfig;
+    setPendingSave(data: Omit<SessionSnapshot, 'savedAt' | 'version'>): void;
     /**
-     * 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
+     * Check if restorePlaybackPosition config is enabled
+     * SDK can use this to decide whether to collect playbackTime
      */
-    setVideoSourceGetter(getter: VideoSourceGetter): void;
+    isPlaybackPositionRestoreEnabled(): boolean;
     /**
-     * Check if preloading is currently throttled due to scroll thrashing
+     * Flush pending save (called on visibility hidden)
      */
-    isPreloadThrottled(): boolean;
+    flushPendingSave(): Promise<void>;
     /**
-     * Get indices currently being preloaded
+     * Handle visibility state change
      */
-    getPreloadingIndices(): number[];
+    onVisibilityChange(state: DocumentVisibilityState): void;
     /**
-     * Manually trigger preload for specific indices
-     * Respects throttling and network conditions
+     * Get current visibility state
      */
-    triggerPreload(indices: number[]): Promise<void>;
+    getVisibilityState(): DocumentVisibilityState;
     /**
      * Add event listener
      */
-    addEventListener(listener: ResourceEventListener): () => void;
+    addEventListener(listener: LifecycleEventListener): () => 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;
+    removeEventListener(listener: LifecycleEventListener): void;
     /**
-     * Track focus change timestamp for scroll thrashing detection
+     * Setup visibility change listener
      */
-    private trackFocusChange;
+    private setupVisibilityListener;
     /**
-     * Cancel all in-progress preloads
+     * Validate snapshot data
      */
-    private cancelAllPreloads;
+    private validateSnapshot;
     /**
-     * Execute video preloading for given indices
+     * Check if snapshot is stale (needs revalidation)
      */
-    private executePreload;
+    private isSnapshotStale;
     /**
-     * Execute poster preloading for given indices
+     * Create session snapshot from data
      */
-    private executePreloadPosters;
+    private createSnapshot;
     /**
      * Emit event to all listeners
      */
@@ -1959,4 +2003,152 @@ declare class CommentManager {
     private createError;
 }
 
-export { type ActionType, type AllocationResult, type CommentError, CommentManager, type CommentManagerConfig, type CommentManagerState, DEFAULT_COMMENT_MANAGER_CONFIG, DEFAULT_FEED_CONFIG, DEFAULT_LIFECYCLE_CONFIG, DEFAULT_OPTIMISTIC_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_PREFETCH_CACHE_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 OptimisticComment, type OptimisticConfig, type OptimisticEvent, type OptimisticEventListener, OptimisticManager, type OptimisticReply, type OptimisticState, type PendingAction, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PrefetchCacheConfig, type PrefetchConfig, type ResourceConfig, type ResourceEvent, type ResourceEventListener, ResourceGovernor, type ResourceState, type RestoreResult, type VideoCommentState, calculatePrefetchIndices, calculateWindowIndices, canPause, canPlay, canSeek, computeAllocationChanges, createInitialCommentState, createInitialVideoCommentState, isActiveState, isValidTransition, mapNetworkType };
+/**
+ * Playlist state for zustand store
+ */
+interface PlaylistState {
+    /** Currently loaded playlist metadata */
+    playlist: PlaylistData | null;
+    /** Current active item index */
+    currentIndex: number;
+    /** List of items in the playlist (shortcut to playlist.items) */
+    items: ContentItem[];
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * Configuration for PlaylistManager
+ */
+interface PlaylistConfig {
+    /**
+     * Number of items to keep full metadata for around the current index
+     * @default 10
+     */
+    metadataWindowSize?: number;
+}
+/**
+ * Actions for PlaylistManager
+ */
+interface PlaylistActions {
+    /** Load a playlist by ID */
+    loadPlaylist: (id: string) => Promise<void>;
+    /** Set a playlist directly */
+    setPlaylist: (playlist: PlaylistData) => void;
+    /** Navigate to next item */
+    next: () => void;
+    /** Navigate to previous item */
+    prev: () => void;
+    /** Jump to specific index */
+    jumpTo: (index: number) => void;
+    /** Reset state */
+    reset: () => void;
+}
+/**
+ * State for PlaylistCollectionManager
+ */
+interface PlaylistCollectionState {
+    /** Array of playlist summaries */
+    playlists: PlaylistSummary[];
+    /** Whether loading is in progress */
+    loading: boolean;
+    /** Current pagination cursor */
+    cursor: string | null;
+    /** Whether more items can be loaded */
+    hasMore: boolean;
+    /** Error state */
+    error: Error | null;
+}
+
+/**
+ * PlaylistManager - Manages playlist state and navigation
+ *
+ * Features:
+ * - Tracks current playlist and active index
+ * - Provides navigation actions (next, prev, jumpTo)
+ * - Uses vanilla Zustand store for state management
+ */
+declare class PlaylistManager {
+    private readonly dataSource?;
+    private readonly governor?;
+    /** Zustand vanilla store */
+    readonly store: StoreApi<PlaylistState>;
+    /** Resolved configuration */
+    private readonly config;
+    /**
+     * Internal cache of full metadata items.
+     * Items in store.items may be minified to save memory.
+     */
+    private fullMetadataItems;
+    /** Unsubscribe from governor events */
+    private governorUnsubscribe?;
+    constructor(dataSource?: IPlaylistDataSource | undefined, config?: PlaylistConfig, governor?: ResourceGovernor | undefined);
+    /**
+     * Load a playlist by ID
+     */
+    loadPlaylist(id: string): Promise<void>;
+    /**
+     * Set playlist data directly
+     */
+    setPlaylist(playlist: PlaylistData): void;
+    /**
+     * Navigate to next item
+     */
+    next(): void;
+    /**
+     * Navigate to previous item
+     */
+    prev(): void;
+    /**
+     * Jump to specific index
+     */
+    jumpTo(index: number): void;
+    /**
+     * Reset state
+     */
+    reset(): void;
+    /**
+     * Destroy the manager
+     */
+    destroy(): void;
+    /**
+     * Update the sliding window of full metadata items.
+     * Items outside the window are minified to save memory.
+     */
+    private updateMetadataWindow;
+    /**
+     * Create a minified version of a ContentItem to save memory.
+     * Keeps only essential fields for identification and basic UI.
+     */
+    private minifyItem;
+}
+
+/**
+ * PlaylistCollectionManager - Manages the discovery of playlists.
+ *
+ * Responsibilities:
+ * - Fetching playlist summaries from DataSource
+ * - Handling pagination and cursor management
+ * - Maintaining loading and error states
+ */
+declare class PlaylistCollectionManager {
+    private readonly dataSource?;
+    /** Zustand vanilla store */
+    readonly store: StoreApi<PlaylistCollectionState>;
+    constructor(dataSource?: IPlaylistDataSource | undefined);
+    /**
+     * Load more playlists (pagination)
+     */
+    loadMore(): Promise<void>;
+    /**
+     * Refresh the collection (reset and re-fetch)
+     */
+    refresh(): Promise<void>;
+    /**
+     * Reset the store to initial state
+     */
+    reset(): void;
+}
+
+export { type ActionType, type AllocationResult, type CommentError, CommentManager, type CommentManagerConfig, type CommentManagerState, DEFAULT_COMMENT_MANAGER_CONFIG, DEFAULT_FEED_CONFIG, DEFAULT_LIFECYCLE_CONFIG, DEFAULT_OPTIMISTIC_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_PREFETCH_CACHE_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 OptimisticComment, type OptimisticConfig, type OptimisticEvent, type OptimisticEventListener, OptimisticManager, type OptimisticReply, type OptimisticState, type PendingAction, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PlaylistActions, PlaylistCollectionManager, type PlaylistCollectionState, PlaylistManager, type PlaylistState, type PrefetchCacheConfig, type PrefetchConfig, type ResourceConfig, type ResourceEvent, type ResourceEventListener, ResourceGovernor, type ResourceState, type RestoreResult, type VideoCommentState, calculatePrefetchIndices, calculateWindowIndices, canPause, canPlay, canSeek, computeAllocationChanges, createInitialCommentState, createInitialVideoCommentState, isActiveState, isValidTransition, mapNetworkType };