@xhub-short/core 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { VideoItem, IDataSource, IAnalytics, ILogger, ISessionStorage, SessionSnapshot, INetworkAdapter, IVideoLoader, IPosterLoader, VideoSource, IInteraction } from '@xhub-short/contracts';
+import { VideoItem, IDataSource, IStorage, PrefetchCacheData, IAnalytics, ILogger, ISessionStorage, SessionSnapshot, INetworkAdapter, IVideoLoader, IPosterLoader, VideoSource, IInteraction, CommentItem, ReplyItem, ICommentAdapter, InternalLogger, CommentAuthor } from '@xhub-short/contracts';
 export { SessionSnapshot } from '@xhub-short/contracts';
 import { StoreApi } from 'zustand/vanilla';
 
@@ -68,6 +68,58 @@ interface FeedConfig {
  * Default feed configuration
  */
 declare const DEFAULT_FEED_CONFIG: Required<FeedConfig>;
+/**
+ * Configuration for prefetch cache feature
+ *
+ * Enables instant feed loading on fresh app open by caching
+ * the last N videos and showing them immediately while
+ * fresh data is fetched in the background.
+ *
+ * @example
+ * ```typescript
+ * const prefetchConfig: PrefetchCacheConfig = {
+ *   enabled: true,
+ *   maxVideos: 15,
+ *   enableDynamicEviction: true,
+ *   evictionThrottleMs: 2000,
+ * };
+ * ```
+ */
+interface PrefetchCacheConfig {
+    /**
+     * Enable prefetch cache for instant loading
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Maximum number of videos to cache
+     * Higher = more instant content, but more storage
+     * @default 10
+     */
+    maxVideos: number;
+    /**
+     * Storage key for prefetch cache
+     * @default 'sv-prefetch-cache'
+     */
+    storageKey: string;
+    /**
+     * Enable dynamic cache eviction
+     * When user scrolls past cached videos, remove them from cache
+     * Prevents user from rewatching same videos on reload
+     * @default true
+     */
+    enableDynamicEviction: boolean;
+    /**
+     * Throttle duration (ms) for dynamic eviction
+     * Reduces storage writes when user scrolls quickly
+     * @default 2000
+     */
+    evictionThrottleMs: number;
+}
+/**
+ * Default prefetch cache configuration
+ */
+declare const DEFAULT_PREFETCH_CACHE_CONFIG: PrefetchCacheConfig;
 
 /**
  * FeedManager - Manages video feed data with zustand/vanilla store
@@ -101,6 +153,10 @@ declare class FeedManager {
     readonly store: StoreApi<FeedState>;
     /** Resolved configuration */
     private readonly config;
+    /** Prefetch cache configuration */
+    private readonly prefetchConfig;
+    /** Storage adapter for prefetch cache (optional) */
+    private readonly storage;
     /** Abort controller for cancelling in-flight requests */
     private abortController;
     /**
@@ -113,7 +169,26 @@ declare class FeedManager {
      * Used for garbage collection
      */
     private accessOrder;
-    constructor(dataSource: IDataSource, config?: FeedConfig);
+    constructor(dataSource: IDataSource, config?: FeedConfig, storage?: IStorage, prefetchConfig?: Partial<PrefetchCacheConfig>);
+    /** 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;
     /**
      * Load initial feed data
      *
@@ -179,6 +254,61 @@ declare class FeedManager {
      * Destroy the manager and cleanup
      */
     destroy(): void;
+    /**
+     * Hydrate feed from a session snapshot
+     *
+     * Used by LifecycleManager to restore state without API call.
+     * This bypasses normal data flow for state restoration.
+     *
+     * @param items - Video 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;
+    /**
+     * 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
+     */
+    updatePrefetchCache(): void;
+    /**
+     * Save prefetch cache to storage (async, non-blocking)
+     */
+    private savePrefetchCacheAsync;
+    /**
+     * Load prefetch cache from storage
+     * Returns null if no cache, disabled, or storage error
+     */
+    loadPrefetchCache(): Promise<PrefetchCacheData | null>;
+    /**
+     * Hydrate feed from prefetch cache for instant display
+     * Marks data as stale to trigger background revalidation
+     */
+    hydrateFromPrefetchCache(cache: PrefetchCacheData): void;
+    /**
+     * 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
+     * Called when user's focusedIndex changes
+     *
+     * Strategy: Remove all videos at or before current position
+     * This ensures user doesn't rewatch videos on reload
+     *
+     * @param currentIndex - Current focused video index in feed
+     */
+    evictViewedVideosFromCache(currentIndex: number): Promise<void>;
+    /**
+     * Get prefetch cache configuration (for external access)
+     */
+    getPrefetchConfig(): PrefetchCacheConfig;
     /**
      * Fetch with exponential backoff retry
      */
@@ -274,6 +404,8 @@ interface PlayerState {
     status: PlayerStatus;
     /** Currently loaded video */
     currentVideo: VideoItem | null;
+    /** Current video ID (convenience getter for currentVideo?.id) */
+    currentVideoId: string | null;
     /** Current playback time in seconds */
     currentTime: number;
     /** Video duration in seconds */
@@ -294,6 +426,29 @@ interface PlayerState {
     error: PlayerError | null;
     /** Whether video has ended */
     ended: boolean;
+    /**
+     * Pending restore position for session restore.
+     *
+     * When set, the next video with matching `pendingRestoreVideoId`
+     * should start at this position (using #t= or hls.startPosition).
+     *
+     * Cleared after being consumed by VideoPlayer.
+     */
+    pendingRestoreTime: number | null;
+    /**
+     * Video ID for pending restore position.
+     *
+     * Used to match the correct video when restoring session.
+     * Only the video with this ID should use `pendingRestoreTime`.
+     */
+    pendingRestoreVideoId: string | null;
+    /**
+     * Captured video frame at restore position (base64 JPEG).
+     *
+     * Displayed as instant preview while video loads.
+     * Cleared after being consumed by VideoPlayer/VideoSlot.
+     */
+    pendingRestoreFrame: string | null;
 }
 /**
  * PlayerEngine configuration
@@ -537,6 +692,60 @@ declare class PlayerEngine {
      * Handle video error
      */
     onError(error: Error, mediaError?: MediaError): void;
+    /**
+     * Set restore position for session restore.
+     *
+     * When the video with matching ID loads, VideoPlayer should
+     * use this position as startTime (via #t= or hls.startPosition).
+     *
+     * @param videoId - Video ID that should use this restore position
+     * @param time - Playback position in seconds
+     *
+     * @example
+     * ```typescript
+     * // During session restore
+     * if (result.playbackTime && result.currentVideoId) {
+     *   playerEngine.setRestorePosition(result.currentVideoId, result.playbackTime, result.restoreFrame);
+     * }
+     * ```
+     */
+    setRestorePosition(videoId: string, time: number, frame?: string): void;
+    /**
+     * Get and clear restore position for a video.
+     *
+     * VideoPlayer calls this when rendering to get startTime.
+     * Position is cleared after being read to prevent reuse.
+     * Note: restoreFrame is NOT cleared here - use consumeRestoreFrame() separately.
+     *
+     * @param videoId - Video ID to check
+     * @returns Restore time in seconds, or null if no pending restore
+     */
+    consumeRestorePosition(videoId: string): number | null;
+    /**
+     * Get and clear restore frame for a video.
+     *
+     * VideoSlot calls this to display instant preview while video loads.
+     * Frame is cleared after being read to free memory.
+     *
+     * @param videoId - Video ID to check
+     * @returns Base64 JPEG data URL, or null if no pending frame
+     */
+    consumeRestoreFrame(videoId: string): string | null;
+    /**
+     * Get restore frame without consuming (peek).
+     * Used to display preview while keeping it available.
+     *
+     * @param videoId - Video ID to check
+     * @returns Base64 JPEG data URL, or null if no pending frame
+     */
+    peekRestoreFrame(videoId: string): string | null;
+    /**
+     * Check if there's a pending restore position for a video.
+     *
+     * @param videoId - Video ID to check
+     * @returns True if there's a pending restore position
+     */
+    hasPendingRestorePosition(videoId: string): boolean;
     /**
      * Reset player to initial state
      */
@@ -579,6 +788,7 @@ declare class PlayerEngine {
     private emitEvent;
     /**
      * Start watch time tracking
+     * Increments watchTime every second and sends analytics heartbeat
      */
     private startWatchTimeTracking;
     /**
@@ -586,9 +796,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
      */
@@ -697,6 +912,8 @@ interface RestoreResult {
     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
@@ -819,6 +1036,7 @@ declare class LifecycleManager {
      * @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[];
@@ -829,6 +1047,8 @@ declare class LifecycleManager {
         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
@@ -1352,6 +1572,10 @@ declare class OptimisticManager {
     private readonly eventListeners;
     /** Retry timer */
     private retryTimer;
+    /** Debounce timers for like/unlike per video */
+    private readonly likeDebounceTimers;
+    /** Debounce delay in ms */
+    private readonly debounceDelay;
     constructor(config?: OptimisticConfig);
     /**
      * Like a video with optimistic update
@@ -1362,9 +1586,26 @@ declare class OptimisticManager {
      */
     unlike(videoId: string): Promise<boolean>;
     /**
-     * Toggle like state (like if not liked, unlike if liked)
+     * 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.
      */
-    toggleLike(videoId: string): Promise<boolean>;
+    toggleLike(videoId: string): void;
+    /**
+     * Execute the actual API call after debounce
+     * Reads current state from FeedManager to get final intended state
+     */
+    private executeDebouncedLikeApi;
+    /**
+     * @deprecated Use toggleLike() instead - it now includes debounce
+     * Legacy toggle that waits for API response
+     */
+    toggleLikeSync(videoId: string): Promise<boolean>;
     /**
      * Follow a video author with optimistic update
      */
@@ -1383,6 +1624,7 @@ declare class OptimisticManager {
     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;
     /**
@@ -1463,4 +1705,238 @@ declare class OptimisticManager {
     private emitEvent;
 }
 
-export { type ActionType, type AllocationResult, DEFAULT_FEED_CONFIG, DEFAULT_LIFECYCLE_CONFIG, DEFAULT_OPTIMISTIC_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_PREFETCH_CONFIG, DEFAULT_RESOURCE_CONFIG, type FeedConfig, type FeedError, FeedManager, type FeedState, type LifecycleConfig, type LifecycleEvent, type LifecycleEventListener, LifecycleManager, type LifecycleState, type NetworkType, type OptimisticConfig, type OptimisticEvent, type OptimisticEventListener, OptimisticManager, type OptimisticState, type PendingAction, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PrefetchConfig, type ResourceConfig, type ResourceEvent, type ResourceEventListener, ResourceGovernor, type ResourceState, type RestoreResult, calculatePrefetchIndices, calculateWindowIndices, canPause, canPlay, canSeek, computeAllocationChanges, isActiveState, isValidTransition, mapNetworkType };
+/**
+ * Comment state for a single video in zustand store
+ */
+interface VideoCommentState {
+    /** Normalized comments - Map for O(1) lookup */
+    commentsById: Map<string, CommentItem>;
+    /** Ordered list of comment IDs for rendering */
+    displayOrder: string[];
+    /** Total comment count from API */
+    totalCount: number;
+    /** Cursor for pagination */
+    cursor: string | null;
+    /** Whether more comments can be loaded */
+    hasMore: boolean;
+    /** Initial loading state */
+    loading: boolean;
+    /** Loading more (pagination) state */
+    loadingMore: boolean;
+    /** Error state */
+    error: CommentError | null;
+    /** Cache timestamp for TTL */
+    cachedAt: number;
+    /** Whether data is stale */
+    isStale: boolean;
+}
+/**
+ * Global comment manager state
+ */
+interface CommentManagerState {
+    /** Comments by video ID */
+    byVideoId: Map<string, VideoCommentState>;
+    /** Currently active video ID (for comment sheet) */
+    activeVideoId: string | null;
+    /** Posting state */
+    isPosting: boolean;
+    /** Posting error */
+    postError: CommentError | null;
+    /** Deleting comment ID (for optimistic UI) */
+    deletingId: string | null;
+}
+/**
+ * Comment error with additional context
+ */
+interface CommentError {
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVER_ERROR' | 'NOT_FOUND' | 'FORBIDDEN' | 'RATE_LIMITED' | 'UNKNOWN';
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Whether error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * CommentManager configuration
+ */
+interface CommentManagerConfig {
+    /** Comments per page (default: 20) */
+    pageSize?: number;
+    /** Replies per load (default: 10) */
+    repliesPageSize?: number;
+    /** Cache TTL in ms (default: 5 minutes) */
+    cacheTTL?: number;
+    /** Maximum retry attempts (default: 2) */
+    maxRetries?: number;
+    /** Auto-expand threshold for replies (default: 1) */
+    repliesAutoExpandThreshold?: number;
+    /** Replies collapse limit (default: 3) */
+    repliesCollapseLimit?: number;
+    /** Comment text max lines before collapse (default: 3) */
+    textMaxLines?: number;
+    /** Enable optimistic UI (default: true) */
+    enableOptimistic?: boolean;
+}
+/**
+ * Default comment manager configuration
+ */
+declare const DEFAULT_COMMENT_MANAGER_CONFIG: Required<CommentManagerConfig>;
+/**
+ * Create initial state for a video's comments
+ */
+declare const createInitialVideoCommentState: () => VideoCommentState;
+/**
+ * Create initial global comment state
+ */
+declare const createInitialCommentState: () => CommentManagerState;
+/**
+ * Optimistic comment for immediate UI feedback
+ */
+interface OptimisticComment extends Omit<CommentItem, 'id'> {
+    /** Temporary optimistic ID (prefixed with 'optimistic_') */
+    id: string;
+    /** Flag to identify optimistic items */
+    isPending: true;
+}
+/**
+ * Optimistic reply for immediate UI feedback
+ */
+interface OptimisticReply extends Omit<ReplyItem, 'id'> {
+    /** Temporary optimistic ID */
+    id: string;
+    /** Flag to identify optimistic items */
+    isPending: true;
+}
+
+/**
+ * CommentManager - Manages comment data with zustand/vanilla store
+ *
+ * Features:
+ * - Multi-video comment caching (by videoId)
+ * - Pagination with cursor
+ * - Nested replies support (1 level)
+ * - Optimistic UI for post/delete
+ * - Cache TTL for stale data detection
+ * - Request deduplication
+ *
+ * Architecture: Hexagonal (Port = ICommentAdapter)
+ *
+ * @example
+ * ```typescript
+ * const commentManager = new CommentManager(commentAdapter);
+ *
+ * // Subscribe to state changes
+ * commentManager.store.subscribe((state) => console.log(state));
+ *
+ * // Load comments for a video
+ * await commentManager.loadComments('video-123');
+ *
+ * // Post a comment
+ * await commentManager.postComment('video-123', 'Great video!');
+ * ```
+ */
+declare class CommentManager {
+    private readonly adapter;
+    /** Zustand vanilla store - Single Source of Truth */
+    readonly store: StoreApi<CommentManagerState>;
+    /** Resolved configuration */
+    private readonly config;
+    /** Logger (optional) */
+    private readonly logger?;
+    /** Request deduplication: Map of key → in-flight Promise */
+    private inFlightRequests;
+    /** Optimistic ID counter */
+    private optimisticIdCounter;
+    constructor(adapter: ICommentAdapter, config?: CommentManagerConfig, logger?: InternalLogger);
+    /**
+     * Load comments for a video
+     *
+     * Features:
+     * - Cache check with TTL
+     * - Request deduplication
+     * - Stale data detection
+     */
+    loadComments(videoId: string, forceRefresh?: boolean): Promise<void>;
+    /**
+     * Load more comments (pagination)
+     */
+    loadMore(videoId: string): Promise<void>;
+    /**
+     * Load replies for a comment
+     */
+    loadReplies(commentId: string): Promise<void>;
+    /**
+     * Post a new comment with optimistic UI
+     */
+    postComment(videoId: string, content: string, currentUser: CommentAuthor): Promise<CommentItem | null>;
+    /**
+     * Post a reply with optimistic UI
+     */
+    postReply(videoId: string, parentId: string, content: string, currentUser: CommentAuthor, replyTo?: CommentAuthor): Promise<ReplyItem | null>;
+    /**
+     * Delete a comment with optimistic UI
+     */
+    deleteComment(videoId: string, commentId: string, isReply?: boolean, parentId?: string): Promise<boolean>;
+    /**
+     * Like a comment/reply with optimistic UI
+     */
+    likeComment(videoId: string, commentId: string, isReply?: boolean, parentId?: string): Promise<void>;
+    /**
+     * Unlike a comment/reply with optimistic UI
+     */
+    unlikeComment(videoId: string, commentId: string, isReply?: boolean, parentId?: string): Promise<void>;
+    /**
+     * Get comments for a video
+     */
+    getComments(videoId: string): CommentItem[];
+    /**
+     * Get a single comment
+     */
+    getComment(videoId: string, commentId: string): CommentItem | undefined;
+    /**
+     * Get a single reply
+     */
+    getReply(videoId: string, parentId: string, replyId: string): ReplyItem | undefined;
+    /**
+     * Get video comment state
+     */
+    getVideoState(videoId: string): VideoCommentState | undefined;
+    /**
+     * Set active video ID (for comment sheet)
+     */
+    setActiveVideo(videoId: string | null): void;
+    /**
+     * Get config
+     */
+    getConfig(): Required<CommentManagerConfig>;
+    /**
+     * Clear comments for a video
+     */
+    clearVideoComments(videoId: string): void;
+    /**
+     * Clear all comments
+     */
+    clearAll(): void;
+    private executeLoadComments;
+    private executeLoadMore;
+    private executeLoadReplies;
+    private addOptimisticComment;
+    private removeOptimisticComment;
+    private replaceOptimisticComment;
+    private addOptimisticReply;
+    private removeOptimisticReply;
+    private replaceOptimisticReply;
+    private removeCommentFromStore;
+    private removeReplyFromStore;
+    private restoreComment;
+    private restoreReply;
+    private updateLikeState;
+    private updateVideoState;
+    private isCacheStale;
+    private generateOptimisticId;
+    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 };