@xhub-short/core 0.1.0-beta.14 → 0.1.0-beta.17

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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';
+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';
 
@@ -313,9 +313,9 @@ declare class ResourceGovernor {
  * 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;
@@ -360,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;
@@ -399,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'
@@ -411,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;
@@ -429,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)
@@ -478,10 +481,16 @@ declare class FeedManager {
      */
     private accessOrder;
     /**
-     * Track videos that have already triggered predictive preload
+     * Track items that have already triggered predictive preload
      * to avoid duplicate requests.
      */
-    private preloadedVideoIds;
+    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;
@@ -558,29 +567,37 @@ declare class FeedManager {
     /**
      * Handle playback progress and trigger predictive preloading
      *
-     * @param videoId - ID of the currently playing video
+     * @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(videoId: string, progress: number, governor: ResourceGovernor, threshold?: number): void;
+    handlePlaybackProgress(itemId: string, progress: number, governor: ResourceGovernor, threshold?: number): void;
+    getItem(id: string): ContentItem | undefined;
+    /**
+     * Get ordered list of items
+     */
+    getItems(): ContentItem[];
     /**
-     * Get a video by ID
-     * Also updates LRU access time for garbage collection
+     * 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;
-    /**
-     * Replace all items in the feed (e.g. for Playlist synchronization)
-     */
-    replaceItems(items: VideoItem[]): void;
     /**
      * Remove an item from the feed
      *
@@ -593,10 +610,10 @@ declare class FeedManager {
      *
      * @example
      * ```typescript
-     * // User reports a video
-     * const wasRemoved = feedManager.removeItem(videoId);
+     * // User reports a content item
+     * const wasRemoved = feedManager.removeItem(itemId);
      * if (wasRemoved) {
-     *   // Navigate to next video
+     *   // Navigate to next item
      * }
      * ```
      */
@@ -623,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?: {
+    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;
     /**
@@ -653,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)
      */
@@ -677,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
      */
@@ -702,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
      */
@@ -1402,7 +1452,7 @@ declare class LifecycleManager {
      * @param data.restoreFrame - Captured video frame at playback position (only saved if restorePlaybackPosition is enabled)
      */
     saveSnapshot(data: {
-        items: VideoItem[];
+        items: ContentItem[];
         cursor: string | null;
         focusedIndex: number;
         scrollPosition?: number;
@@ -1601,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?;
@@ -1609,25 +1659,25 @@ 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 (videoId -> isLiked) */
+    /** 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
      */
-    toggleLike(videoId: string): void;
+    toggleLike(itemId: string): void;
     /**
      * Execute API call after debounce delay
      */
@@ -1643,9 +1693,9 @@ declare class OptimisticManager {
     /**
      * Toggle follow state
      */
-    toggleFollow(videoId: string): Promise<boolean>;
-    follow(videoId: string): Promise<boolean>;
-    unfollow(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;
     /**
@@ -1653,7 +1703,7 @@ declare class OptimisticManager {
      */
     reset(): void;
     getPendingActions(): PendingAction[];
-    hasPendingAction(videoId: string, type?: ActionType): boolean;
+    hasPendingAction(itemId: string, type?: ActionType): boolean;
     getFailedQueue(): PendingAction[];
     retryFailed(): Promise<void>;
     clearFailed(): void;

package/dist/index.js

@@ -1,4 +1,4 @@
-// ../../node_modules/.pnpm/zustand@5.0.9_@types+react@19.2.7_react@19.2.3/node_modules/zustand/esm/vanilla.mjs
+// ../../node_modules/.pnpm/zustand@5.0.11_@types+react@19.2.14_react@19.2.4/node_modules/zustand/esm/vanilla.mjs
 var createStoreImpl = (createState) => {
   let state;
   const listeners = /* @__PURE__ */ new Set();
@@ -35,6 +35,7 @@ var DEFAULT_FEED_CONFIG = {
 };
 var DEFAULT_PREFETCH_CACHE_CONFIG = {
   enabled: true,
+  maxItems: 10,
   maxVideos: 10,
   storageKey: "sv-prefetch-cache",
   enableDynamicEviction: true,
@@ -70,10 +71,16 @@ var _FeedManager = class _FeedManager {
      */
     this.accessOrder = /* @__PURE__ */ new Map();
     /**
-     * Track videos that have already triggered predictive preload
+     * Track items that have already triggered predictive preload
      * to avoid duplicate requests.
      */
-    this.preloadedVideoIds = /* @__PURE__ */ new Set();
+    this.preloadedItemIds = /* @__PURE__ */ new Set();
+    /**
+     * 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.
+     */
+    this.recommendSnapshot = null;
     this.config = { ...DEFAULT_FEED_CONFIG, ...config };
     this.prefetchConfig = { ...DEFAULT_PREFETCH_CACHE_CONFIG, ...prefetchConfig };
     this.storage = storage ?? null;
@@ -240,7 +247,7 @@ var _FeedManager = class _FeedManager {
     }
     try {
       const response = await this.dataSource.fetchFeed();
-      this.mergeVideos(response.items, true);
+      this.mergeItems(response.items, true);
       this.store.setState({
         cursor: response.nextCursor,
         hasMore: response.hasMore,
@@ -253,17 +260,17 @@ var _FeedManager = class _FeedManager {
   /**
    * Handle playback progress and trigger predictive preloading
    *
-   * @param videoId - ID of the currently playing video
+   * @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(videoId, progress, governor, threshold = 0.2) {
-    if (this.preloadedVideoIds.has(videoId)) return;
+  handlePlaybackProgress(itemId, progress, governor, threshold = 0.2) {
+    if (this.preloadedItemIds.has(itemId)) return;
     if (progress >= threshold) {
-      this.preloadedVideoIds.add(videoId);
+      this.preloadedItemIds.add(itemId);
       const state = this.store.getState();
-      const currentIndex = state.displayOrder.indexOf(videoId);
+      const currentIndex = state.displayOrder.indexOf(itemId);
       if (currentIndex !== -1) {
         const nextIndices = [currentIndex + 1, currentIndex + 2].filter(
           (idx) => idx < state.displayOrder.length
@@ -277,28 +284,24 @@ var _FeedManager = class _FeedManager {
       }
     }
   }
-  /**
-   * Get a video by ID
-   * Also updates LRU access time for garbage collection
-   */
-  getVideo(id) {
-    const video = this.store.getState().itemsById.get(id);
-    if (video) {
+  getItem(id) {
+    const item = this.store.getState().itemsById.get(id);
+    if (item) {
       this.accessOrder.set(id, Date.now());
     }
-    return video;
+    return item;
   }
   /**
-   * Get ordered list of videos
+   * Get ordered list of items
    */
-  getVideos() {
+  getItems() {
     const state = this.store.getState();
     return state.displayOrder.map((id) => state.itemsById.get(id)).filter((v) => v !== void 0);
   }
   /**
-   * Update a video in the feed (for optimistic updates)
+   * Update an item in the feed (for optimistic updates)
    */
-  updateVideo(id, updates) {
+  updateItem(id, updates) {
     const state = this.store.getState();
     const existing = state.itemsById.get(id);
     if (existing) {
@@ -326,6 +329,24 @@ var _FeedManager = class _FeedManager {
       hasMore: false
     });
   }
+  /**
+   * @deprecated Use getItem instead
+   */
+  getVideo(id) {
+    return this.getItem(id);
+  }
+  /**
+   * @deprecated Use getItems instead
+   */
+  getVideos() {
+    return this.getItems();
+  }
+  /**
+   * @deprecated Use updateItem instead
+   */
+  updateVideo(id, updates) {
+    this.updateItem(id, updates);
+  }
   /**
    * Remove an item from the feed
    *
@@ -338,10 +359,10 @@ var _FeedManager = class _FeedManager {
    *
    * @example
    * ```typescript
-   * // User reports a video
-   * const wasRemoved = feedManager.removeItem(videoId);
+   * // User reports a content item
+   * const wasRemoved = feedManager.removeItem(itemId);
    * if (wasRemoved) {
-   *   // Navigate to next video
+   *   // Navigate to next item
    * }
    * ```
    */
@@ -375,7 +396,7 @@ var _FeedManager = class _FeedManager {
     this.cancelPendingRequests();
     this.inFlightRequests.clear();
     this.accessOrder.clear();
-    this.preloadedVideoIds.clear();
+    this.preloadedItemIds.clear();
     this.store.setState(createInitialState());
   }
   /**
@@ -402,7 +423,7 @@ var _FeedManager = 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
    */
@@ -413,10 +434,10 @@ var _FeedManager = class _FeedManager {
     const now = Date.now();
     const newItemsById = /* @__PURE__ */ new Map();
     const newDisplayOrder = [];
-    for (const video of items) {
-      newItemsById.set(video.id, video);
-      newDisplayOrder.push(video.id);
-      this.accessOrder.set(video.id, now);
+    for (const item of items) {
+      newItemsById.set(item.id, item);
+      newDisplayOrder.push(item.id);
+      this.accessOrder.set(item.id, now);
     }
     this.store.setState({
       itemsById: newItemsById,
@@ -431,26 +452,67 @@ var _FeedManager = class _FeedManager {
     });
   }
   // ═══════════════════════════════════════════════════════════════
+  // RECOMMEND SNAPSHOT (for playlist ↔ recommend switching)
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * Save the current recommend feed state before switching to playlist mode.
+   *
+   * @param activeIndex - Current scroll position (active item index)
+   */
+  saveRecommendSnapshot(activeIndex) {
+    this.recommendSnapshot = {
+      items: this.getItems(),
+      cursor: this.store.getState().cursor,
+      hasMore: this.store.getState().hasMore,
+      activeIndex
+    };
+  }
+  /**
+   * 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() {
+    const snapshot = this.recommendSnapshot;
+    if (!snapshot || snapshot.items.length === 0) {
+      this.recommendSnapshot = null;
+      return null;
+    }
+    this.hydrateFromSnapshot(snapshot.items, snapshot.cursor, {
+      markAsStale: false
+    });
+    const savedIndex = snapshot.activeIndex;
+    this.recommendSnapshot = null;
+    return savedIndex;
+  }
+  /**
+   * Check if a recommend snapshot exists (for conditional logic in hooks)
+   */
+  hasRecommendSnapshot() {
+    return this.recommendSnapshot !== null && this.recommendSnapshot.items.length > 0;
+  }
+  // ═══════════════════════════════════════════════════════════════
   // PREFETCH CACHE METHODS
   // ═══════════════════════════════════════════════════════════════
   /**
    * 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() {
     if (!this.prefetchConfig.enabled) return;
     if (!this.storage) return;
     const state = this.store.getState();
-    const allVideos = this.getVideos();
-    if (allVideos.length < this.prefetchConfig.maxVideos) {
+    const allItems = this.getItems();
+    if (allItems.length < this.prefetchConfig.maxItems) {
       return;
     }
-    const tailVideos = allVideos.slice(-this.prefetchConfig.maxVideos);
+    const tailItems = allItems.slice(-this.prefetchConfig.maxItems);
     const cacheData = {
-      items: tailVideos,
+      items: tailItems,
       savedAt: Date.now(),
       cursor: state.cursor
     };
@@ -493,6 +555,35 @@ var _FeedManager = class _FeedManager {
       // Trigger revalidation
     });
   }
+  /**
+   * 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() {
+    if (!this.prefetchConfig.enabled) return null;
+    if (!this.storage) return null;
+    if (!this.storage.getSync) return null;
+    try {
+      const data = this.storage.getSync(this.prefetchConfig.storageKey);
+      if (!data || !data.items || data.items.length === 0) {
+        return null;
+      }
+      return data;
+    } catch {
+      return null;
+    }
+  }
   /**
    * Clear prefetch cache
    * Call when user logs out or data should be invalidated
@@ -505,26 +596,26 @@ var _FeedManager = class _FeedManager {
     }
   }
   /**
-   * 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
    */
-  async evictViewedVideosFromCache(currentIndex) {
+  async evictViewedItemsFromCache(currentIndex) {
     if (!this.prefetchConfig.enabled) return;
     if (!this.prefetchConfig.enableDynamicEviction) return;
     if (!this.storage) return;
     try {
       const cache = await this.loadPrefetchCache();
       if (!cache || cache.items.length === 0) return;
-      const allVideos = this.getVideos();
-      const currentVideo = allVideos[currentIndex];
-      if (!currentVideo) return;
-      const viewedVideoIds = new Set(allVideos.slice(0, currentIndex + 1).map((v) => v.id));
-      const updatedItems = cache.items.filter((item) => !viewedVideoIds.has(item.id));
+      const allItems = this.getItems();
+      const currentItem = allItems[currentIndex];
+      if (!currentItem) return;
+      const viewedItemIds = new Set(allItems.slice(0, currentIndex + 1).map((v) => v.id));
+      const updatedItems = cache.items.filter((item) => !viewedItemIds.has(item.id));
       if (updatedItems.length === cache.items.length) return;
       if (updatedItems.length === 0) {
         await this.storage.remove(this.prefetchConfig.storageKey);
@@ -560,7 +651,7 @@ var _FeedManager = class _FeedManager {
         if (replace) {
           this.replaceItems(response.items);
         } else {
-          this.addVideos(response.items);
+          this.addItems(response.items);
         }
         this.store.setState({
           cursor: response.nextCursor,
@@ -584,23 +675,23 @@ var _FeedManager = class _FeedManager {
     throw lastError;
   }
   /**
-   * Add videos with deduplication
+   * Add items with deduplication
    * Triggers garbage collection if cache exceeds maxCacheSize
    */
-  addVideos(videos) {
+  addItems(items) {
     const state = this.store.getState();
     const newItemsById = new Map(state.itemsById);
     const newDisplayOrder = [...state.displayOrder];
     const now = Date.now();
-    for (const video of videos) {
-      const existing = newItemsById.get(video.id);
+    for (const item of items) {
+      const existing = newItemsById.get(item.id);
       if (existing) {
-        newItemsById.set(video.id, { ...existing, ...video });
+        newItemsById.set(item.id, { ...existing, ...item });
       } else {
-        newItemsById.set(video.id, video);
-        newDisplayOrder.push(video.id);
+        newItemsById.set(item.id, item);
+        newDisplayOrder.push(item.id);
       }
-      this.accessOrder.set(video.id, now);
+      this.accessOrder.set(item.id, now);
     }
     this.store.setState({
       itemsById: newItemsById,
@@ -611,19 +702,19 @@ var _FeedManager = class _FeedManager {
     }
   }
   /**
-   * 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
    */
-  mergeVideos(videos, prepend) {
+  mergeItems(items, prepend) {
     const state = this.store.getState();
     const newItemsById = new Map(state.itemsById);
     const newIds = [];
-    for (const video of videos) {
-      if (newItemsById.has(video.id)) {
-        newItemsById.set(video.id, video);
+    for (const item of items) {
+      if (newItemsById.has(item.id)) {
+        newItemsById.set(item.id, item);
       } else {
-        newItemsById.set(video.id, video);
-        newIds.push(video.id);
+        newItemsById.set(item.id, item);
+        newIds.push(item.id);
       }
     }
     const newDisplayOrder = prepend ? [...newIds, ...state.displayOrder] : [...state.displayOrder, ...newIds];
@@ -696,9 +787,9 @@ var _FeedManager = 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
    */
@@ -2577,9 +2668,9 @@ var OptimisticManager = class {
     this.eventListeners = /* @__PURE__ */ new Set();
     /** Retry timer */
     this.retryTimer = null;
-    /** Debounce timers for like/unlike per video */
+    /** Debounce timers for like/unlike per item */
     this.likeDebounceTimers = /* @__PURE__ */ new Map();
-    /** Intended like state while debouncing (videoId -> isLiked) */
+    /** Intended like state while debouncing (itemId -> isLiked) */
     this.intendedLikeState = /* @__PURE__ */ new Map();
     /** Debounce delay in ms */
     this.debounceDelay = 300;
@@ -2594,73 +2685,75 @@ var OptimisticManager = class {
   // PUBLIC API - ACTIONS
   // ═══════════════════════════════════════════════════════════════
   /**
-   * Like a video with optimistic update
+   * Like an item with optimistic update
    */
-  async like(videoId) {
-    return this.performAction("like", videoId, async () => {
+  async like(itemId) {
+    return this.performAction("like", itemId, async () => {
       if (!this.interaction) throw new Error("No interaction adapter");
-      await this.interaction.like(videoId);
+      await this.interaction.like(itemId);
     });
   }
   /**
-   * Unlike a video with optimistic update
+   * Unlike an item with optimistic update
    */
-  async unlike(videoId) {
-    return this.performAction("unlike", videoId, async () => {
+  async unlike(itemId) {
+    return this.performAction("unlike", itemId, async () => {
       if (!this.interaction) throw new Error("No interaction adapter");
-      await this.interaction.unlike(videoId);
+      await this.interaction.unlike(itemId);
     });
   }
   /**
    * Toggle like state with DEBOUNCE
    */
-  toggleLike(videoId) {
-    const video = this.feedManager?.getVideo(videoId);
-    if (!video) {
-      this.logger?.warn(`[OptimisticManager] Video not found for toggleLike: ${videoId}`);
+  toggleLike(itemId) {
+    const item = this.feedManager?.getItem(itemId);
+    if (!item) {
+      this.logger?.warn(`[OptimisticManager] Item not found for toggleLike: ${itemId}`);
       return;
     }
-    const currentIntended = this.intendedLikeState.get(videoId) ?? video.isLiked;
+    const currentIntended = this.intendedLikeState.get(itemId) ?? item.isLiked;
     const newIsLiked = !currentIntended;
-    this.intendedLikeState.set(videoId, newIsLiked);
+    this.intendedLikeState.set(itemId, newIsLiked);
     const likeDelta = newIsLiked ? 1 : -1;
-    const currentLikesFromStore = video.stats.likes;
-    this.feedManager?.updateVideo(videoId, {
+    const currentLikesFromStore = item.stats.likes;
+    this.feedManager?.updateItem(itemId, {
       isLiked: newIsLiked,
-      stats: { ...video.stats, likes: Math.max(0, currentLikesFromStore + likeDelta) }
+      stats: { ...item.stats, likes: Math.max(0, currentLikesFromStore + likeDelta) }
     });
-    const actionId = `like-debounce-${videoId}`;
+    const actionId = `like-debounce-${itemId}`;
     this.store.setState((state) => {
       const pendingActions = new Map(state.pendingActions);
       pendingActions.set(actionId, {
         id: actionId,
-        videoId,
+        videoId: itemId,
+        // Keep property name 'videoId' in PendingAction for compatibility if needed, but using itemId value
         type: newIsLiked ? "like" : "unlike",
         status: "pending",
         timestamp: Date.now(),
         retryCount: 0,
         rollbackData: {
           isLiked: currentIntended,
-          stats: { ...video.stats }
+          stats: { ...item.stats }
         }
+        // Cast back to VideoItem if needed for contract
       });
       return { pendingActions, hasPending: true };
     });
-    const existingTimer = this.likeDebounceTimers.get(videoId);
+    const existingTimer = this.likeDebounceTimers.get(itemId);
     if (existingTimer) {
       clearTimeout(existingTimer);
     }
     const timer = setTimeout(() => {
-      this.likeDebounceTimers.delete(videoId);
-      this.executeDebouncedLikeApi(videoId, actionId);
+      this.likeDebounceTimers.delete(itemId);
+      this.executeDebouncedLikeApi(itemId, actionId);
     }, this.debounceDelay);
-    this.likeDebounceTimers.set(videoId, timer);
+    this.likeDebounceTimers.set(itemId, timer);
   }
   /**
    * Execute API call after debounce delay
    */
-  async executeDebouncedLikeApi(videoId, actionId) {
-    const finalIntended = this.intendedLikeState.get(videoId);
+  async executeDebouncedLikeApi(itemId, actionId) {
+    const finalIntended = this.intendedLikeState.get(itemId);
     if (finalIntended === void 0) {
       this.removePendingAction(actionId);
       return;
@@ -2668,15 +2761,15 @@ var OptimisticManager = class {
     try {
       if (!this.interaction) throw new Error("No interaction adapter");
       if (finalIntended) {
-        await this.interaction.like(videoId);
+        await this.interaction.like(itemId);
       } else {
-        await this.interaction.unlike(videoId);
+        await this.interaction.unlike(itemId);
       }
-      if (this.intendedLikeState.get(videoId) === finalIntended) {
-        this.intendedLikeState.delete(videoId);
+      if (this.intendedLikeState.get(itemId) === finalIntended) {
+        this.intendedLikeState.delete(itemId);
       }
     } catch (error) {
-      this.handleDebouncedApiError(videoId, finalIntended, error);
+      this.handleDebouncedApiError(itemId, finalIntended, error);
     } finally {
       this.removePendingAction(actionId);
     }
@@ -2684,19 +2777,19 @@ var OptimisticManager = class {
   /**
    * Handle errors from debounced API calls
    */
-  handleDebouncedApiError(videoId, finalIntended, error) {
+  handleDebouncedApiError(itemId, finalIntended, error) {
     const err = error instanceof Error ? error : new Error(String(error));
-    this.logger?.error(`[OptimisticManager] API failed for ${videoId}`, err);
-    if (!this.intendedLikeState.has(videoId)) {
-      const currentVideo = this.feedManager?.getVideo(videoId);
-      if (currentVideo) {
+    this.logger?.error(`[OptimisticManager] API failed for ${itemId}`, err);
+    if (!this.intendedLikeState.has(itemId)) {
+      const currentItem = this.feedManager?.getItem(itemId);
+      if (currentItem) {
         const rollbackIsLiked = !finalIntended;
         const rollbackDelta = rollbackIsLiked ? 1 : -1;
-        this.feedManager?.updateVideo(videoId, {
+        this.feedManager?.updateItem(itemId, {
           isLiked: rollbackIsLiked,
           stats: {
-            ...currentVideo.stats,
-            likes: Math.max(0, currentVideo.stats.likes + rollbackDelta)
+            ...currentItem.stats,
+            likes: Math.max(0, currentItem.stats.likes + rollbackDelta)
           }
         });
       }
@@ -2718,21 +2811,21 @@ var OptimisticManager = class {
   /**
    * Toggle follow state
    */
-  async toggleFollow(videoId) {
-    const video = this.feedManager?.getVideo(videoId);
-    if (!video) return false;
-    return video.isFollowing ? this.unfollow(videoId) : this.follow(videoId);
+  async toggleFollow(itemId) {
+    const item = this.feedManager?.getItem(itemId);
+    if (!item) return false;
+    return item.isFollowing ? this.unfollow(itemId) : this.follow(itemId);
   }
-  async follow(videoId) {
-    return this.performAction("follow", videoId, async () => {
+  async follow(itemId) {
+    return this.performAction("follow", itemId, async () => {
       if (!this.interaction) throw new Error("No interaction adapter");
-      await this.interaction.follow(videoId);
+      await this.interaction.follow(itemId);
     });
   }
-  async unfollow(videoId) {
-    return this.performAction("unfollow", videoId, async () => {
+  async unfollow(itemId) {
+    return this.performAction("unfollow", itemId, async () => {
       if (!this.interaction) throw new Error("No interaction adapter");
-      await this.interaction.unfollow(videoId);
+      await this.interaction.unfollow(itemId);
     });
   }
   addEventListener(listener) {
@@ -2754,10 +2847,10 @@ var OptimisticManager = class {
   getPendingActions() {
     return [...this.store.getState().pendingActions.values()];
   }
-  hasPendingAction(videoId, type) {
+  hasPendingAction(itemId, type) {
     const actions = this.store.getState().pendingActions;
     for (const action of actions.values()) {
-      if (action.videoId === videoId && action.status === "pending" && (!type || action.type === type)) {
+      if (action.videoId === itemId && action.status === "pending" && (!type || action.type === type)) {
         return true;
       }
     }
@@ -2816,23 +2909,23 @@ var OptimisticManager = class {
       }
     }
   }
-  async performAction(type, videoId, apiCall) {
-    const video = this.feedManager?.getVideo(videoId);
-    if (!video) return false;
-    if (this.hasPendingAction(videoId, type)) {
+  async performAction(type, itemId, apiCall) {
+    const item = this.feedManager?.getItem(itemId);
+    if (!item) return false;
+    if (this.hasPendingAction(itemId, type)) {
       return false;
     }
     const action = {
       id: generateActionId(),
       type,
-      videoId,
-      rollbackData: this.createRollbackData(type, video),
+      videoId: itemId,
+      rollbackData: this.createRollbackData(type, item),
       timestamp: Date.now(),
       status: "pending",
       retryCount: 0
     };
     this.addPendingAction(action);
-    this.applyOptimisticUpdate(type, video);
+    this.applyOptimisticUpdate(type, item);
     this.emit({ type: "actionStart", action });
     try {
       await apiCall();
@@ -2846,32 +2939,32 @@ var OptimisticManager = class {
       return false;
     }
   }
-  createRollbackData(type, video) {
+  createRollbackData(type, item) {
     if (type === "like" || type === "unlike") {
-      return { isLiked: video.isLiked, stats: { ...video.stats } };
+      return { isLiked: item.isLiked, stats: { ...item.stats } };
     }
-    return { isFollowing: video.isFollowing };
+    return { isFollowing: item.isFollowing };
   }
-  applyOptimisticUpdate(type, video) {
+  applyOptimisticUpdate(type, item) {
     if (!this.feedManager) return;
     if (type === "like") {
-      this.feedManager.updateVideo(video.id, {
+      this.feedManager.updateItem(item.id, {
         isLiked: true,
-        stats: { ...video.stats, likes: video.stats.likes + 1 }
+        stats: { ...item.stats, likes: item.stats.likes + 1 }
       });
     } else if (type === "unlike") {
-      this.feedManager.updateVideo(video.id, {
+      this.feedManager.updateItem(item.id, {
         isLiked: false,
-        stats: { ...video.stats, likes: Math.max(0, video.stats.likes - 1) }
+        stats: { ...item.stats, likes: Math.max(0, item.stats.likes - 1) }
       });
     } else if (type === "follow") {
-      this.feedManager.updateVideo(video.id, { isFollowing: true });
+      this.feedManager.updateItem(item.id, { isFollowing: true });
     } else if (type === "unfollow") {
-      this.feedManager.updateVideo(video.id, { isFollowing: false });
+      this.feedManager.updateItem(item.id, { isFollowing: false });
     }
   }
   applyRollback(action) {
-    this.feedManager?.updateVideo(action.videoId, action.rollbackData);
+    this.feedManager?.updateItem(action.videoId, action.rollbackData);
     this.emit({ type: "actionRollback", action });
   }
   addPendingAction(action) {
@@ -2929,9 +3022,9 @@ var OptimisticManager = class {
         await this.interaction?.follow(updatedAction.videoId);
       else if (updatedAction.type === "unfollow")
         await this.interaction?.unfollow(updatedAction.videoId);
-      const currentVideo = this.feedManager?.getVideo(updatedAction.videoId);
-      if (currentVideo) {
-        this.applyOptimisticUpdate(updatedAction.type, currentVideo);
+      const currentItem = this.feedManager?.getItem(updatedAction.videoId);
+      if (currentItem) {
+        this.applyOptimisticUpdate(updatedAction.type, currentItem);
       }
       this.markActionSuccess(updatedAction.id);
     } catch (e) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xhub-short/core",
   "sideEffects": false,
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.17",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -21,7 +21,7 @@
   ],
   "dependencies": {
     "zustand": "^5.0.0",
-    "@xhub-short/contracts": "0.1.0-beta.14"
+    "@xhub-short/contracts": "0.1.0-beta.17"
   },
   "devDependencies": {
     "tsup": "^8.3.0",