@xhub-short/core 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/index.d.ts

@@ -1,14 +1,321 @@
-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, ContentItem, IDataSource, IStorage, VideoItem, PrefetchCacheData, IAnalytics, ISessionStorage, SessionSnapshot, IInteraction, CommentItem, ReplyItem, ICommentAdapter, InternalLogger, CommentAuthor, PlaylistData, 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
  */
 interface FeedState {
-    /** Normalized video data - Map for O(1) lookup */
-    itemsById: Map<string, VideoItem>;
-    /** Ordered list of video IDs for rendering */
+    /** Normalized content data - Map for O(1) lookup */
+    itemsById: Map<string, ContentItem>;
+    /** Ordered list of content IDs for rendering */
     displayOrder: string[];
     /** Initial loading state */
     loading: boolean;
@@ -53,8 +360,8 @@ interface FeedConfig {
     /** 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)
+     * Maximum number of items to keep in memory cache
+     * When exceeded, older items will be evicted (LRU policy)
      * @default 100
      */
     maxCacheSize?: number;
@@ -92,11 +399,14 @@ interface PrefetchCacheConfig {
      */
     enabled: boolean;
     /**
-     * Maximum number of videos to cache
+     * Maximum number of items to cache
      * Higher = more instant content, but more storage
-     * @default 10
      */
-    maxVideos: number;
+    maxItems: number;
+    /**
+     * @deprecated Use maxItems instead. Will be removed in v3.0
+     */
+    maxVideos?: number;
     /**
      * Storage key for prefetch cache
      * @default 'sv-prefetch-cache'
@@ -104,8 +414,8 @@ interface PrefetchCacheConfig {
     storageKey: string;
     /**
      * Enable dynamic cache eviction
-     * When user scrolls past cached videos, remove them from cache
-     * Prevents user from rewatching same videos on reload
+     * When user scrolls past cached items, remove them from cache
+     * Prevents user from rewatching same items on reload
      * @default true
      */
     enableDynamicEviction: boolean;
@@ -122,7 +432,7 @@ interface PrefetchCacheConfig {
 declare const DEFAULT_PREFETCH_CACHE_CONFIG: PrefetchCacheConfig;
 
 /**
- * FeedManager - Manages video feed data with zustand/vanilla store
+ * FeedManager - Manages content feed data with zustand/vanilla store
  *
  * Features:
  * - Data normalization (Map for O(1) lookup + ordered IDs)
@@ -148,7 +458,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 +480,52 @@ declare class FeedManager {
      * Used for garbage collection
      */
     private accessOrder;
-    constructor(dataSource: IDataSource, config?: FeedConfig, storage?: IStorage, prefetchConfig?: Partial<PrefetchCacheConfig>);
+    /**
+     * Track items that have already triggered predictive preload
+     * to avoid duplicate requests.
+     */
+    private preloadedItemIds;
+    /**
+     * Recommend feed snapshot — preserved when switching to playlist mode.
+     * Stored here (not in React refs) because FeedManager is a singleton
+     * that survives component remounts caused by conditional rendering.
+     */
+    private recommendSnapshot;
+    constructor(dataSource: IDataSource, config?: FeedConfig, storage?: IStorage, prefetchConfig?: Partial<PrefetchCacheConfig>, logger?: ILogger | undefined);
+    /** Static memory cache for explicit prefetching */
+    private static globalMemoryCache;
+    /**
+     * Prefetch feed data and store in global memory cache
+     *
+     * @param dataSource - Data source to fetch from
+     * @param options - Prefetch options
+     */
+    static prefetch(dataSource: IDataSource, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * Check if prefetch cache exists and is valid
+     */
+    static hasPrefetchCache(): boolean;
+    /**
+     * 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
      *
@@ -182,7 +538,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
      */
@@ -207,18 +565,59 @@ declare class FeedManager {
      */
     revalidate(): Promise<void>;
     /**
-     * Get a video by ID
-     * Also updates LRU access time for garbage collection
+     * Handle playback progress and trigger predictive preloading
+     *
+     * @param itemId - ID of the currently playing item
+     * @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(itemId: string, progress: number, governor: ResourceGovernor, threshold?: number): void;
+    getItem(id: string): ContentItem | undefined;
+    /**
+     * Get ordered list of items
+     */
+    getItems(): ContentItem[];
+    /**
+     * Update an item in the feed (for optimistic updates)
+     */
+    updateItem(id: string, updates: Partial<ContentItem>): void;
+    /**
+     * Replace all items in the feed (e.g. for Playlist synchronization)
+     */
+    replaceItems(items: ContentItem[]): void;
+    /**
+     * @deprecated Use getItem instead
      */
     getVideo(id: string): VideoItem | undefined;
     /**
-     * Get ordered list of videos
+     * @deprecated Use getItems instead
      */
     getVideos(): VideoItem[];
     /**
-     * Update a video in the feed (for optimistic updates)
+     * @deprecated Use updateItem instead
      */
     updateVideo(id: string, updates: Partial<VideoItem>): void;
+    /**
+     * Remove an item from the feed
+     *
+     * Used for:
+     * - Report: Remove reported content from feed
+     * - Not Interested: Remove content user doesn't want to see
+     *
+     * @param id - Content ID to remove
+     * @returns true if item was removed, false if not found
+     *
+     * @example
+     * ```typescript
+     * // User reports a content item
+     * const wasRemoved = feedManager.removeItem(itemId);
+     * if (wasRemoved) {
+     *   // Navigate to next item
+     * }
+     * ```
+     */
+    removeItem(id: string): boolean;
     /**
      * Check if data is stale and needs revalidation
      */
@@ -241,20 +640,37 @@ declare class FeedManager {
      * Used by LifecycleManager to restore state without API call.
      * This bypasses normal data flow for state restoration.
      *
-     * @param items - Video items from snapshot
+     * @param items - Content items from snapshot
      * @param cursor - Pagination cursor from snapshot
      * @param options - Additional hydration options
      */
-    hydrateFromSnapshot(items: VideoItem[], cursor: string | null, options?: {
-        /** Whether to mark data as stale for background revalidation */
-        markAsStale?: boolean;
-    }): void;
+    hydrateFromSnapshot(items: ContentItem[], cursor: string | null, options?: {
+        /** Whether to mark data as stale for background revalidation */
+        markAsStale?: boolean;
+    }): void;
+    /**
+     * Save the current recommend feed state before switching to playlist mode.
+     *
+     * @param activeIndex - Current scroll position (active item index)
+     */
+    saveRecommendSnapshot(activeIndex: number): void;
+    /**
+     * Restore the recommend feed state after exiting playlist mode.
+     * Delegates to hydrateFromSnapshot() internally to avoid duplicating hydration logic.
+     *
+     * @returns The saved activeIndex, or null if no snapshot was available
+     */
+    restoreRecommendSnapshot(): number | null;
+    /**
+     * Check if a recommend snapshot exists (for conditional logic in hooks)
+     */
+    hasRecommendSnapshot(): boolean;
     /**
      * Update prefetch cache with current feed tail
      * Called automatically after loadInitial() and loadMore()
      *
-     * Strategy: Cache the LAST N videos (tail of feed)
-     * These are videos user hasn't seen yet, perfect for instant display
+     * Strategy: Cache the LAST N items (tail of feed)
+     * These are items user hasn't seen yet, perfect for instant display
      */
     updatePrefetchCache(): void;
     /**
@@ -271,21 +687,37 @@ declare class FeedManager {
      * Marks data as stale to trigger background revalidation
      */
     hydrateFromPrefetchCache(cache: PrefetchCacheData): void;
+    /**
+     * Load prefetch cache synchronously (zero-flash optimization)
+     *
+     * Uses `storage.getSync()` for synchronous localStorage access.
+     * This allows hydrating the feed during React's synchronous render phase,
+     * preventing any flash of loading/empty state when cached data exists.
+     *
+     * Returns null if:
+     * - Prefetch cache is disabled
+     * - No storage adapter
+     * - Storage doesn't support sync reads (e.g., IndexedDB)
+     * - No cached data
+     *
+     * @returns Cached feed data or null
+     */
+    loadPrefetchCacheSync(): PrefetchCacheData | null;
     /**
      * Clear prefetch cache
      * Call when user logs out or data should be invalidated
      */
     clearPrefetchCache(): Promise<void>;
     /**
-     * Evict videos that user has scrolled past from prefetch cache
+     * Evict items that user has scrolled past from prefetch cache
      * Called when user's focusedIndex changes
      *
-     * Strategy: Remove all videos at or before current position
-     * This ensures user doesn't rewatch videos on reload
+     * Strategy: Remove all items at or before current position
+     * This ensures user doesn't rewatch items on reload
      *
-     * @param currentIndex - Current focused video index in feed
+     * @param currentIndex - Current focused item index in feed
      */
-    evictViewedVideosFromCache(currentIndex: number): Promise<void>;
+    evictViewedItemsFromCache(currentIndex: number): Promise<void>;
     /**
      * Get prefetch cache configuration (for external access)
      */
@@ -295,15 +727,15 @@ declare class FeedManager {
      */
     private fetchWithRetry;
     /**
-     * Add videos with deduplication
+     * Add items with deduplication
      * Triggers garbage collection if cache exceeds maxCacheSize
      */
-    private addVideos;
+    private addItems;
     /**
-     * Merge videos (for SWR revalidation)
-     * Updates existing videos, adds new ones at the beginning
+     * Merge items (for SWR revalidation)
+     * Updates existing items, adds new ones at the beginning
      */
-    private mergeVideos;
+    private mergeItems;
     /**
      * Handle and categorize errors
      */
@@ -320,9 +752,9 @@ declare class FeedManager {
      * 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)
+     * 1. Sort items by last access time (oldest first)
+     * 2. Evict oldest items until cache is within limit
+     * 3. Keep items that are currently in viewport (most recent in displayOrder)
      *
      * @returns Number of evicted items
      */
@@ -769,6 +1201,7 @@ declare class PlayerEngine {
     private emitEvent;
     /**
      * Start watch time tracking
+     * Increments watchTime every second and sends analytics heartbeat
      */
     private startWatchTimeTracking;
     /**
@@ -776,9 +1209,14 @@ declare class PlayerEngine {
      */
     private stopWatchTimeTracking;
     /**
-     * Track completion analytics
+     * Track completion analytics (when video loops/ends)
      */
     private trackCompletion;
+    /**
+     * Track when user leaves current video (scrolls to next video)
+     * Sends final analytics event before video change
+     */
+    private trackLeaveVideo;
     /**
      * Categorize media error
      */
@@ -838,543 +1276,244 @@ declare function isValidTransition(from: PlayerStatus, to: PlayerStatus): boolea
 /**
  * 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)
-     */
-    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>;
-    /**
-     * 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';
+declare function isActiveState(status: PlayerStatus): boolean;
 /**
- * Map contracts NetworkType to simplified NetworkType
+ * Check if player can start playback
  */
-declare function mapNetworkType(type: string): NetworkType;
+declare function canPlay(status: PlayerStatus): boolean;
 /**
- * Resource state for zustand store
+ * Check if player can pause
  */
-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 canPause(status: PlayerStatus): boolean;
 /**
- * Allocation result returned by requestAllocation
+ * Check if player can seek
  */
-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 canSeek(status: PlayerStatus): boolean;
+
 /**
- * Prefetch configuration by network type
+ * Lifecycle state for zustand store
  */
-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;
+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 {
-    /** 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>;
+ * ```
+ */
+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);
     /**
-     * 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: ContentItem[];
+        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
      */
@@ -1504,33 +1643,6 @@ 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 */
@@ -1539,7 +1651,7 @@ declare class OptimisticManager {
     private readonly config;
     /** Interaction adapter */
     private readonly interaction?;
-    /** Feed manager for updating video state */
+    /** Feed manager for updating item state */
     private readonly feedManager?;
     /** Logger adapter */
     private readonly logger?;
@@ -1547,137 +1659,65 @@ declare class OptimisticManager {
     private readonly eventListeners;
     /** Retry timer */
     private retryTimer;
-    /** Debounce timers for like/unlike per video */
+    /** Debounce timers for like/unlike per item */
     private readonly likeDebounceTimers;
+    /** Intended like state while debouncing (itemId -> isLiked) */
+    private readonly intendedLikeState;
     /** Debounce delay in ms */
     private readonly debounceDelay;
     constructor(config?: OptimisticConfig);
     /**
-     * Like a video with optimistic update
+     * Like an item with optimistic update
      */
-    like(videoId: string): Promise<boolean>;
+    like(itemId: string): Promise<boolean>;
     /**
-     * Unlike a video with optimistic update
+     * Unlike an item with optimistic update
      */
-    unlike(videoId: string): Promise<boolean>;
+    unlike(itemId: string): Promise<boolean>;
     /**
-     * Toggle like state with DEBOUNCE (like if not liked, unlike if liked)
-     *
-     * This method:
-     * 1. Updates UI immediately (optimistic)
-     * 2. Debounces API call - only sends after user stops clicking
-     * 3. Sends final state to API after debounce delay
-     *
-     * Perfect for rapid tapping like TikTok/Instagram behavior.
+     * Toggle like state with DEBOUNCE
      */
-    toggleLike(videoId: string): void;
+    toggleLike(itemId: string): void;
     /**
-     * Execute the actual API call after debounce
-     * Reads current state from FeedManager to get final intended state
+     * Execute API call after debounce delay
      */
     private executeDebouncedLikeApi;
     /**
-     * @deprecated Use toggleLike() instead - it now includes debounce
-     * Legacy toggle that waits for API response
+     * Handle errors from debounced API calls
      */
-    toggleLikeSync(videoId: string): Promise<boolean>;
+    private handleDebouncedApiError;
     /**
-     * Follow a video author with optimistic update
+     * Remove a pending action by ID
      */
-    follow(videoId: string): Promise<boolean>;
-    /**
-     * Unfollow a video author with optimistic update
-     */
-    unfollow(videoId: string): Promise<boolean>;
+    private removePendingAction;
     /**
      * Toggle follow state
      */
-    toggleFollow(videoId: string): Promise<boolean>;
+    toggleFollow(itemId: string): Promise<boolean>;
+    follow(itemId: string): Promise<boolean>;
+    unfollow(itemId: string): Promise<boolean>;
+    addEventListener(listener: OptimisticEventListener): () => void;
+    removeEventListener(listener: OptimisticEventListener): void;
     /**
-     * Get all pending actions
+     * Reset all optimistic state
      */
+    reset(): void;
     getPendingActions(): PendingAction[];
-    /**
-     * Check if there's a pending action for a video
-     * Only returns true for actions with status 'pending' (not 'failed')
-     */
-    hasPendingAction(videoId: string, type?: ActionType): boolean;
-    /**
-     * Get failed actions queue
-     */
+    hasPendingAction(itemId: string, type?: ActionType): boolean;
     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 emit;
     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;
 }
 
 /**
@@ -1914,4 +1954,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 };