@xhub-reels/sdk 0.2.5 → 0.2.6

package/README.md

@@ -86,6 +86,72 @@ function MyFeed() {
 }
 ```
 
+## Thumbnail grid
+
+`<ReelsFeedThumbnail>` is a headless grid component for the pre-drawer browsing UX
+(e.g. a community feed that opens the player drawer on tap). It must be mounted
+inside `<ReelsProvider>` and reads items from the same shared feed. The host
+provides card visuals via `renderThumbnail`.
+
+```tsx
+import { ReelsProvider, ReelsFeedThumbnail } from 'xhub-reels-sdk';
+
+function CommunityPage() {
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  return (
+    <ReelsProvider adapters={{ dataSource, interaction }}>
+      <ReelsFeedThumbnail
+        renderThumbnail={(item) => (
+          <article className="aspect-[3/2] rounded-lg overflow-hidden">
+            <img src={item.poster} alt="" />
+            <p>@{item.author.name}</p>
+          </article>
+        )}
+        onThumbnailClick={(id) => {
+          setDrawerOpen(true);
+          window.history.replaceState(null, '', `#reel_uuid=${id}`);
+        }}
+      />
+      {drawerOpen && <ReelsDrawer onClose={() => setDrawerOpen(false)} />}
+    </ReelsProvider>
+  );
+}
+```
+
+By default, clicking a card calls `setFocusedIndexImmediate(index)` on the
+`ResourceGovernor` so the player opens instantly without a scroll-to-index. To
+disable this glue (e.g. if the host manages focus separately), pass
+`setFocusOnClick={false}`.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `renderThumbnail` | `(item, index) => ReactNode` | required | Card visual for a single item |
+| `onThumbnailClick` | `(id, item, index) => void` | — | Click handler |
+| `renderLoading` | `() => ReactNode` | — | Shown while loading with no items |
+| `renderEmpty` | `() => ReactNode` | — | Shown when feed is empty |
+| `renderError` | `({ message, retry }) => ReactNode` | — | Shown on error with no items |
+| `className` | `string` | `'grid grid-cols-2 gap-3'` | Outer wrapper className |
+| `wrap` | `boolean` | `true` | Set `false` to render without an outer `<div>` |
+| `setFocusOnClick` | `boolean` | `true` | Pre-focus the slot before `onThumbnailClick` fires |
+| `prefetchOnHover` | `boolean` | `false` | Opt-in HLS metadata prefetch on `pointerenter` |
+| `getKey` | `(item, index) => string` | `item.id` | Key override for duplicate lists |
+
+### Hover prefetch
+
+For hover-capable devices, opt into manifest prefetch so opening the player
+feels instant:
+
+```tsx
+<ReelsFeedThumbnail prefetchOnHover renderThumbnail={...} />
+```
+
+The SDK uses `adapters.videoLoader?.preloadMetadata?.(url)` and dedupes per item
+so a card only triggers one prefetch regardless of how many times it's hovered.
+Off by default to avoid surprising bandwidth on touch devices.
+
 ## Gesture Engine
 
 ```tsx

package/dist/index.cjs

@@ -2520,6 +2520,81 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+function ReelsFeedThumbnail({
+  renderThumbnail,
+  onThumbnailClick,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  className = "grid grid-cols-2 gap-3",
+  wrap = true,
+  setFocusOnClick = true,
+  prefetchOnHover = false,
+  getKey
+}) {
+  const { items, loading, error, refresh } = useFeed();
+  const { setFocusedIndexImmediate } = useResource();
+  const { adapters } = useSDK();
+  const prefetchedRef = react.useRef(/* @__PURE__ */ new Set());
+  const handleClick = react.useCallback(
+    (id, item, index) => {
+      if (setFocusOnClick) {
+        setFocusedIndexImmediate(index);
+      }
+      onThumbnailClick?.(id, item, index);
+    },
+    [setFocusOnClick, setFocusedIndexImmediate, onThumbnailClick]
+  );
+  const handlePointerEnter = react.useCallback(
+    (item) => {
+      if (!prefetchOnHover) return;
+      if (!isVideoItem(item)) return;
+      if (item.source.type !== "hls") return;
+      const url = item.source.url;
+      if (prefetchedRef.current.has(url)) return;
+      prefetchedRef.current.add(url);
+      adapters.videoLoader?.preloadMetadata?.(url);
+    },
+    [prefetchOnHover, adapters.videoLoader]
+  );
+  if (loading && items.length === 0) {
+    if (renderLoading) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderLoading() });
+    return null;
+  }
+  if (error && items.length === 0) {
+    if (renderError) {
+      return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderError({ message: error.message, retry: refresh }) });
+    }
+    return null;
+  }
+  if (!loading && items.length === 0) {
+    if (renderEmpty) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderEmpty() });
+    return null;
+  }
+  const content = items.map((item, index) => {
+    const key = getKey ? getKey(item, index) : item.id;
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        onClick: () => handleClick(item.id, item, index),
+        onPointerEnter: () => handlePointerEnter(item),
+        style: {
+          all: "unset",
+          cursor: "pointer",
+          display: "block",
+          width: "100%"
+        },
+        children: renderThumbnail(item, index)
+      },
+      key
+    );
+  });
+  if (!wrap) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: content });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className, children: content });
+}
 function usePlayerSelector(selector) {
   const { playerEngine } = useSDK();
   const selectorRef = react.useRef(selector);
@@ -3156,6 +3231,7 @@ exports.OptimisticManager = OptimisticManager;
 exports.PlayerEngine = PlayerEngine;
 exports.PlayerStatus = PlayerStatus;
 exports.ReelsFeed = ReelsFeed;
+exports.ReelsFeedThumbnail = ReelsFeedThumbnail;
 exports.ReelsProvider = ReelsProvider;
 exports.ResourceGovernor = ResourceGovernor;
 exports.VALID_TRANSITIONS = VALID_TRANSITIONS;

package/dist/index.d.cts

@@ -789,6 +789,33 @@ declare function useSDK(): SDKContextValue;
 
 declare function ReelsFeed({ renderOverlay, renderActions, renderPauseAction, renderLoading, renderEmpty, renderError: _renderError, showFps, loadMoreThreshold, onSlotChange, gestureConfig, snapConfig, initialMuted, onAutoplayBlocked, }: ReelsFeedProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
 
+interface ReelsFeedThumbnailProps {
+    /** Render function for a single item's visual card. */
+    renderThumbnail: (videoData: ContentItem, index: number) => ReactNode;
+    /** Click handler — receives the item id, full data, and index in the feed. */
+    onThumbnailClick?: (id: string, videoData: ContentItem, index: number) => void;
+    /** Rendered when the feed is loading and has zero items yet. */
+    renderLoading?: () => ReactNode;
+    /** Rendered when the feed has loaded but is empty. */
+    renderEmpty?: () => ReactNode;
+    /** Rendered when the feed fails with no items — receives a retry callback. */
+    renderError?: (error: {
+        message: string;
+        retry: () => void;
+    }) => ReactNode;
+    /** Outer wrapper className. Defaults to `grid grid-cols-2 gap-3`. */
+    className?: string;
+    /** If the host wants to render its own wrapper, pass `false`. Default: true. */
+    wrap?: boolean;
+    /** Enable click → update focused index on ReelsProvider before host reacts. Default: true. */
+    setFocusOnClick?: boolean;
+    /** Prefetch metadata for this slot on pointer enter. Off by default. */
+    prefetchOnHover?: boolean;
+    /** Key override — useful when host renders multiple lists from the same feed. */
+    getKey?: (item: ContentItem, index: number) => string;
+}
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * useHls — React hook for hls.js lifecycle management (3-Tier buffer support)
  *
@@ -1174,4 +1201,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/dist/index.d.ts

@@ -789,6 +789,33 @@ declare function useSDK(): SDKContextValue;
 
 declare function ReelsFeed({ renderOverlay, renderActions, renderPauseAction, renderLoading, renderEmpty, renderError: _renderError, showFps, loadMoreThreshold, onSlotChange, gestureConfig, snapConfig, initialMuted, onAutoplayBlocked, }: ReelsFeedProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
 
+interface ReelsFeedThumbnailProps {
+    /** Render function for a single item's visual card. */
+    renderThumbnail: (videoData: ContentItem, index: number) => ReactNode;
+    /** Click handler — receives the item id, full data, and index in the feed. */
+    onThumbnailClick?: (id: string, videoData: ContentItem, index: number) => void;
+    /** Rendered when the feed is loading and has zero items yet. */
+    renderLoading?: () => ReactNode;
+    /** Rendered when the feed has loaded but is empty. */
+    renderEmpty?: () => ReactNode;
+    /** Rendered when the feed fails with no items — receives a retry callback. */
+    renderError?: (error: {
+        message: string;
+        retry: () => void;
+    }) => ReactNode;
+    /** Outer wrapper className. Defaults to `grid grid-cols-2 gap-3`. */
+    className?: string;
+    /** If the host wants to render its own wrapper, pass `false`. Default: true. */
+    wrap?: boolean;
+    /** Enable click → update focused index on ReelsProvider before host reacts. Default: true. */
+    setFocusOnClick?: boolean;
+    /** Prefetch metadata for this slot on pointer enter. Off by default. */
+    prefetchOnHover?: boolean;
+    /** Key override — useful when host renders multiple lists from the same feed. */
+    getKey?: (item: ContentItem, index: number) => string;
+}
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * useHls — React hook for hls.js lifecycle management (3-Tier buffer support)
  *
@@ -1174,4 +1201,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/dist/index.js

@@ -2514,6 +2514,81 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+function ReelsFeedThumbnail({
+  renderThumbnail,
+  onThumbnailClick,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  className = "grid grid-cols-2 gap-3",
+  wrap = true,
+  setFocusOnClick = true,
+  prefetchOnHover = false,
+  getKey
+}) {
+  const { items, loading, error, refresh } = useFeed();
+  const { setFocusedIndexImmediate } = useResource();
+  const { adapters } = useSDK();
+  const prefetchedRef = useRef(/* @__PURE__ */ new Set());
+  const handleClick = useCallback(
+    (id, item, index) => {
+      if (setFocusOnClick) {
+        setFocusedIndexImmediate(index);
+      }
+      onThumbnailClick?.(id, item, index);
+    },
+    [setFocusOnClick, setFocusedIndexImmediate, onThumbnailClick]
+  );
+  const handlePointerEnter = useCallback(
+    (item) => {
+      if (!prefetchOnHover) return;
+      if (!isVideoItem(item)) return;
+      if (item.source.type !== "hls") return;
+      const url = item.source.url;
+      if (prefetchedRef.current.has(url)) return;
+      prefetchedRef.current.add(url);
+      adapters.videoLoader?.preloadMetadata?.(url);
+    },
+    [prefetchOnHover, adapters.videoLoader]
+  );
+  if (loading && items.length === 0) {
+    if (renderLoading) return /* @__PURE__ */ jsx(Fragment, { children: renderLoading() });
+    return null;
+  }
+  if (error && items.length === 0) {
+    if (renderError) {
+      return /* @__PURE__ */ jsx(Fragment, { children: renderError({ message: error.message, retry: refresh }) });
+    }
+    return null;
+  }
+  if (!loading && items.length === 0) {
+    if (renderEmpty) return /* @__PURE__ */ jsx(Fragment, { children: renderEmpty() });
+    return null;
+  }
+  const content = items.map((item, index) => {
+    const key = getKey ? getKey(item, index) : item.id;
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        onClick: () => handleClick(item.id, item, index),
+        onPointerEnter: () => handlePointerEnter(item),
+        style: {
+          all: "unset",
+          cursor: "pointer",
+          display: "block",
+          width: "100%"
+        },
+        children: renderThumbnail(item, index)
+      },
+      key
+    );
+  });
+  if (!wrap) {
+    return /* @__PURE__ */ jsx(Fragment, { children: content });
+  }
+  return /* @__PURE__ */ jsx("div", { className, children: content });
+}
 function usePlayerSelector(selector) {
   const { playerEngine } = useSDK();
   const selectorRef = useRef(selector);
@@ -3128,4 +3203,4 @@ var HttpError = class extends Error {
   }
 };
 
-export { DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, FeedManager, HttpDataSource, HttpError, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, OptimisticManager, PlayerEngine, PlayerStatus, ReelsFeed, ReelsProvider, ResourceGovernor, VALID_TRANSITIONS, VideoSlot, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, FeedManager, HttpDataSource, HttpError, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, OptimisticManager, PlayerEngine, PlayerStatus, ReelsFeed, ReelsFeedThumbnail, ReelsProvider, ResourceGovernor, VALID_TRANSITIONS, VideoSlot, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xhub-reels/sdk",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "High-performance Short Video / Reels SDK for React — optimized for Flutter WebView",
   "license": "MIT",
   "type": "module",