@xhub-reels/sdk 0.2.12 → 0.2.13

package/dist/index.cjs

@@ -4,6 +4,7 @@ var vanilla = require('zustand/vanilla');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 var Hls = require('hls.js');
+var reactDom = require('react-dom');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -106,6 +107,7 @@ var PlayerEngine = class {
     this.circuitResetTimer = null;
     this.watchTimeInterval = null;
     this.lastStatus = "idle" /* IDLE */;
+    this._destroyed = false;
     this.config = { ...DEFAULT_PLAYER_CONFIG, ...config };
     this.analytics = analytics;
     this.logger = logger;
@@ -315,8 +317,13 @@ var PlayerEngine = class {
     this.lastStatus = "idle" /* IDLE */;
   }
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
     this.stopWatchTime();
-    if (this.circuitResetTimer) clearTimeout(this.circuitResetTimer);
+    if (this.circuitResetTimer) {
+      clearTimeout(this.circuitResetTimer);
+      this.circuitResetTimer = null;
+    }
     this.listeners.clear();
   }
   // ═══════════════════════════════════════════
@@ -419,6 +426,8 @@ var FeedManager = class {
     this.inFlightRequests = /* @__PURE__ */ new Map();
     /** LRU tracking: itemId → lastAccessTime */
     this.accessOrder = /* @__PURE__ */ new Map();
+    /** Idempotency guard for destroy() */
+    this._destroyed = false;
     /** Prefetch cache — instance-scoped (not static) */
     this.prefetchCache = null;
     this.config = { ...DEFAULT_FEED_CONFIG, ...config };
@@ -531,7 +540,10 @@ var FeedManager = class {
   // PUBLIC API — Lifecycle
   // ═══════════════════════════════════════════
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
     this.abortController?.abort();
+    this.abortController = null;
     this.inFlightRequests.clear();
     this.accessOrder.clear();
     this.prefetchCache = null;
@@ -600,7 +612,13 @@ var FeedManager = class {
   applyItems(incoming, _nextCursor, append) {
     const { itemsById, displayOrder } = this.store.getState();
     const nextById = new Map(itemsById);
+    const seenInBatch = /* @__PURE__ */ new Set();
+    const deduped = [];
     for (const item of incoming) {
+      if (!seenInBatch.has(item.id)) {
+        seenInBatch.add(item.id);
+        deduped.push(item);
+      }
       nextById.set(item.id, item);
       this.accessOrder.set(item.id, Date.now());
     }
@@ -608,14 +626,14 @@ var FeedManager = class {
     if (append) {
       const existingIds = new Set(displayOrder);
       const newIds = [];
-      for (const item of incoming) {
+      for (const item of deduped) {
         if (!existingIds.has(item.id)) {
           newIds.push(item.id);
         }
       }
       nextOrder = [...displayOrder, ...newIds];
     } else {
-      nextOrder = incoming.map((item) => item.id);
+      nextOrder = deduped.map((item) => item.id);
     }
     if (nextById.size > this.config.maxCacheSize) {
       this.evictLRU(nextById, nextOrder);
@@ -657,6 +675,8 @@ var OptimisticManager = class {
     this.likeDebounceTimers = /* @__PURE__ */ new Map();
     /** Pending like direction: contentId → final intended state */
     this.pendingLikeState = /* @__PURE__ */ new Map();
+    /** Idempotency guard for destroy() */
+    this._destroyed = false;
     this.interaction = interaction;
     this.logger = logger;
     this.store = vanilla.createStore(createInitialState3);
@@ -747,6 +767,8 @@ var OptimisticManager = class {
   // PUBLIC API — Lifecycle
   // ═══════════════════════════════════════════
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
     for (const timer of this.likeDebounceTimers.values()) {
       clearTimeout(timer);
     }
@@ -768,6 +790,7 @@ var DEFAULT_RESOURCE_CONFIG = {
 var ResourceGovernor = class {
   constructor(config = {}, videoLoader, network, logger) {
     this.focusDebounceTimer = null;
+    this._destroyed = false;
     this.config = { ...DEFAULT_RESOURCE_CONFIG, ...config };
     this.videoLoader = videoLoader;
     this.network = network;
@@ -798,11 +821,19 @@ var ResourceGovernor = class {
     this.logger?.debug("[ResourceGovernor] Activated");
   }
   deactivate() {
+    if (this._destroyed) return;
+    if (!this.store.getState().isActive) return;
     this.networkUnsubscribe?.();
-    if (this.focusDebounceTimer) clearTimeout(this.focusDebounceTimer);
+    this.networkUnsubscribe = void 0;
+    if (this.focusDebounceTimer) {
+      clearTimeout(this.focusDebounceTimer);
+      this.focusDebounceTimer = null;
+    }
     this.store.setState({ isActive: false });
   }
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
     this.deactivate();
     this.videoLoader?.clearAll();
   }
@@ -926,6 +957,153 @@ var ResourceGovernor = class {
     );
   }
 };
+var DEFAULT_NAVIGATION_CONFIG = {
+  phaseTimeoutMs: 1200
+};
+var VALID_NAV_TRANSITIONS = {
+  closed: ["opening"],
+  // Allow opening → closing so a fast user can dismiss mid-open.
+  opening: ["open", "closing", "closed"],
+  open: ["closing"],
+  // Allow closing → opening so re-opening during the exit animation works.
+  closing: ["closed", "opening"]
+};
+function isValidNavTransition(from, to) {
+  if (from === to) return false;
+  return VALID_NAV_TRANSITIONS[from].includes(to);
+}
+var NavigationManager = class {
+  constructor(config = {}, logger) {
+    /** Fallback timer guarding against a missing animationend report. */
+    this.phaseTimer = null;
+    this._destroyed = false;
+    this.config = { ...DEFAULT_NAVIGATION_CONFIG, ...config };
+    this.logger = logger;
+    this.store = vanilla.createStore(() => ({
+      phase: "closed",
+      openIndex: null
+    }));
+  }
+  // ═══════════════════════════════════════════
+  // PUBLIC API — Intent
+  // ═══════════════════════════════════════════
+  /**
+   * Open the reels viewer at `index`. Safe to call from a thumbnail click
+   * handler — it transitions into `opening`, at which point ReelsModal mounts
+   * <ReelsFeed> hidden and begins prewarming.
+   *
+   * Calling open() while already open/opening just retargets the index
+   * (e.g. user taps a different thumbnail before the animation settles).
+   */
+  open(index) {
+    if (this._destroyed) return;
+    const { phase, openIndex } = this.store.getState();
+    if ((phase === "open" || phase === "opening") && index === openIndex) {
+      return;
+    }
+    if (phase === "open" || phase === "opening") {
+      this.store.setState({ openIndex: index });
+      this.logger?.debug(`[NavigationManager] retarget openIndex=${index}`);
+      return;
+    }
+    if (!this.transition("opening")) return;
+    this.store.setState({ openIndex: index });
+    this.logger?.debug(`[NavigationManager] open(${index}) \u2192 opening`);
+  }
+  /**
+   * Begin closing the viewer. ReelsModal animates out then calls
+   * `setPhase('closed')`. Idempotent if already closing/closed.
+   */
+  close() {
+    if (this._destroyed) return;
+    const { phase } = this.store.getState();
+    if (phase === "closed" || phase === "closing") return;
+    this.transition("closing");
+    this.logger?.debug("[NavigationManager] close() \u2192 closing");
+  }
+  // ═══════════════════════════════════════════
+  // PUBLIC API — Phase reporting (called by ReelsModal)
+  // ═══════════════════════════════════════════
+  /**
+   * Report an animation-driven phase change from the component layer.
+   * Invalid transitions are dropped. When reaching `closed`, openIndex is
+   * cleared so <ReelsFeed> unmounts.
+   */
+  setPhase(next) {
+    if (this._destroyed) return;
+    this.transition(next);
+  }
+  // ═══════════════════════════════════════════
+  // PUBLIC API — Queries
+  // ═══════════════════════════════════════════
+  getPhase() {
+    return this.store.getState().phase;
+  }
+  getOpenIndex() {
+    return this.store.getState().openIndex;
+  }
+  isOpen() {
+    const { phase } = this.store.getState();
+    return phase === "open" || phase === "opening";
+  }
+  /** Whether <ReelsFeed> should be mounted (any non-closed phase). */
+  shouldMount() {
+    return this.store.getState().phase !== "closed";
+  }
+  // ═══════════════════════════════════════════
+  // PUBLIC API — Lifecycle
+  // ═══════════════════════════════════════════
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    if (this.phaseTimer) {
+      clearTimeout(this.phaseTimer);
+      this.phaseTimer = null;
+    }
+  }
+  // ═══════════════════════════════════════════
+  // PRIVATE
+  // ═══════════════════════════════════════════
+  /**
+   * Apply a guarded phase transition. Returns true if it was applied.
+   * Manages the fallback timer for transient phases (opening/closing).
+   */
+  transition(next) {
+    const { phase } = this.store.getState();
+    if (!isValidNavTransition(phase, next)) {
+      this.logger?.debug(
+        `[NavigationManager] dropped invalid transition ${phase} \u2192 ${next}`
+      );
+      return false;
+    }
+    this.clearPhaseTimer();
+    if (next === "closed") {
+      this.store.setState({ phase: "closed", openIndex: null });
+      return true;
+    }
+    this.store.setState({ phase: next });
+    if (next === "opening" || next === "closing") {
+      const fallbackTarget = next === "opening" ? "open" : "closed";
+      this.phaseTimer = setTimeout(() => {
+        this.phaseTimer = null;
+        const current = this.store.getState().phase;
+        if (current === next) {
+          this.logger?.warn(
+            `[NavigationManager] phase fallback ${next} \u2192 ${fallbackTarget}`
+          );
+          this.transition(fallbackTarget);
+        }
+      }, this.config.phaseTimeoutMs);
+    }
+    return true;
+  }
+  clearPhaseTimer() {
+    if (this.phaseTimer) {
+      clearTimeout(this.phaseTimer);
+      this.phaseTimer = null;
+    }
+  }
+};
 function usePointerGesture(config = {}) {
   const {
     axis = "y",
@@ -1115,7 +1293,9 @@ function useSnapAnimation(config = {}) {
           }
         );
         anim.addEventListener("finish", () => {
-          element.style.transform = `translateY(${toY}px)`;
+          if (element.isConnected) {
+            element.style.transform = `translateY(${toY}px)`;
+          }
           anim.cancel();
         });
         animations.push(anim);
@@ -1143,39 +1323,100 @@ function useSnapAnimation(config = {}) {
   }, [cancelAnimation]);
   return { animateSnap, animateBounceBack, cancelAnimation };
 }
+var noop = () => {
+};
+var noopAsync = () => Promise.resolve();
+var DEFAULT_LOGGER = {
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop
+};
+var DEFAULT_ANALYTICS = {
+  trackView: noop,
+  trackLike: noop,
+  trackShare: noop,
+  trackComment: noop,
+  trackError: noop,
+  trackPlaybackEvent: noop
+};
+var DEFAULT_INTERACTION = {
+  like: noopAsync,
+  unlike: noopAsync,
+  follow: noopAsync,
+  unfollow: noopAsync,
+  bookmark: noopAsync,
+  unbookmark: noopAsync,
+  share: noopAsync
+};
+var DEFAULT_STORAGE = {
+  get: () => null,
+  set: noop,
+  remove: noop,
+  clear: noop
+};
+var DEFAULT_NETWORK = {
+  getNetworkType: () => "unknown",
+  isOnline: () => true,
+  onNetworkChange: () => noop
+};
+var DEFAULT_VIDEO_LOADER = {
+  preload: (videoId) => Promise.resolve({ videoId, status: "idle" }),
+  cancel: noop,
+  isPreloaded: () => false,
+  getPreloadStatus: () => "idle",
+  clearAll: noop
+};
+var DEFAULT_COMMENT = {
+  fetchComments: () => Promise.resolve({ items: [], nextCursor: null, hasMore: false, total: 0 }),
+  postComment: () => Promise.reject(new Error("Comment adapter not configured")),
+  deleteComment: noopAsync,
+  likeComment: noopAsync,
+  unlikeComment: noopAsync
+};
 var SDKContext = react.createContext(null);
 function ReelsProvider({
   children,
   adapters,
   initialItems,
-  debug = false
+  debug = false,
+  navigationConfig
 }) {
-  const logger = adapters.logger;
-  const sdkRef = react.useRef(null);
+  const resolvedAdapters = react.useMemo(() => ({
+    dataSource: adapters.dataSource,
+    interaction: adapters.interaction ?? DEFAULT_INTERACTION,
+    storage: adapters.storage ?? DEFAULT_STORAGE,
+    analytics: adapters.analytics ?? DEFAULT_ANALYTICS,
+    logger: adapters.logger ?? DEFAULT_LOGGER,
+    network: adapters.network ?? DEFAULT_NETWORK,
+    videoLoader: adapters.videoLoader ?? DEFAULT_VIDEO_LOADER,
+    comment: adapters.comment ?? DEFAULT_COMMENT
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), [adapters.dataSource]);
+  const logger = resolvedAdapters.logger;
+  const prevInstanceRef = react.useRef(null);
   const value = react.useMemo(() => {
-    if (sdkRef.current) {
-      sdkRef.current.feedManager.destroy();
-      sdkRef.current.playerEngine.destroy();
-      sdkRef.current.resourceGovernor.destroy();
-      sdkRef.current.optimisticManager.destroy();
-    }
     const feedManager = new FeedManager(adapters.dataSource, {}, logger);
     if (initialItems && initialItems.length > 0) {
       feedManager.setInitialItems(initialItems);
     }
     const playerEngine = new PlayerEngine(
       {},
-      adapters.analytics,
+      resolvedAdapters.analytics,
       logger
     );
     const resourceGovernor = new ResourceGovernor(
       {},
-      adapters.videoLoader,
-      adapters.network,
+      resolvedAdapters.videoLoader,
+      resolvedAdapters.network,
       logger
     );
     const optimisticManager = new OptimisticManager(
-      adapters.interaction ?? {},
+      resolvedAdapters.interaction,
+      logger
+    );
+    const navigationManager = new NavigationManager(
+      navigationConfig ?? {},
       logger
     );
     const instance = {
@@ -1183,15 +1424,27 @@ function ReelsProvider({
       playerEngine,
       resourceGovernor,
       optimisticManager,
-      adapters
+      navigationManager,
+      adapters: resolvedAdapters
     };
-    sdkRef.current = instance;
     return instance;
   }, [adapters.dataSource]);
   react.useEffect(() => {
-    value.resourceGovernor.activate();
+    const prev = prevInstanceRef.current;
+    if (prev && prev !== value) {
+      prev.feedManager.destroy();
+      prev.playerEngine.destroy();
+      prev.resourceGovernor.destroy();
+      prev.optimisticManager.destroy();
+      prev.navigationManager.destroy();
+    }
+    prevInstanceRef.current = value;
+  }, [value]);
+  react.useEffect(() => {
+    const governor = value.resourceGovernor;
+    governor.activate();
     return () => {
-      value.resourceGovernor.deactivate();
+      governor.deactivate();
     };
   }, [value.resourceGovernor]);
   react.useEffect(() => {
@@ -1201,10 +1454,11 @@ function ReelsProvider({
   }, [debug, logger]);
   react.useEffect(() => {
     return () => {
-      sdkRef.current?.feedManager.destroy();
-      sdkRef.current?.playerEngine.destroy();
-      sdkRef.current?.resourceGovernor.destroy();
-      sdkRef.current?.optimisticManager.destroy();
+      prevInstanceRef.current?.feedManager.destroy();
+      prevInstanceRef.current?.playerEngine.destroy();
+      prevInstanceRef.current?.resourceGovernor.destroy();
+      prevInstanceRef.current?.optimisticManager.destroy();
+      prevInstanceRef.current?.navigationManager.destroy();
     };
   }, []);
   return /* @__PURE__ */ jsxRuntime.jsx(SDKContext.Provider, { value, children });
@@ -1708,25 +1962,34 @@ var PLAY_AHEAD_MAX_CONCURRENT = 2;
 var PLAY_AHEAD_STAGGER_MS = 80;
 var _playAheadActive = 0;
 var _playAheadQueue = [];
+var _tokenCounter = 0;
+var _releasedTokens = /* @__PURE__ */ new Set();
 function acquirePlayAhead() {
+  const token = ++_tokenCounter;
+  const makeRelease = () => {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      _releasedTokens.add(token);
+      _playAheadActive = Math.max(0, _playAheadActive - 1);
+      const next = _playAheadQueue.shift();
+      if (next) {
+        next();
+      }
+    };
+  };
   if (_playAheadActive < PLAY_AHEAD_MAX_CONCURRENT) {
     _playAheadActive++;
-    return Promise.resolve();
+    return Promise.resolve(makeRelease());
   }
   return new Promise((resolve) => {
     _playAheadQueue.push(() => {
-      setTimeout(resolve, PLAY_AHEAD_STAGGER_MS);
+      _playAheadActive++;
+      setTimeout(() => resolve(makeRelease()), PLAY_AHEAD_STAGGER_MS);
     });
   });
 }
-function releasePlayAhead() {
-  _playAheadActive = Math.max(0, _playAheadActive - 1);
-  const next = _playAheadQueue.shift();
-  if (next) {
-    _playAheadActive++;
-    next();
-  }
-}
 function VideoSlot({
   item,
   index,
@@ -1849,6 +2112,42 @@ function VideoSlotInner({
     }
   }, [mp4Src, isActive, isPrefetch, isPreloaded, isHlsSource]);
   const isReady = isHlsSource ? hlsReady : mp4Ready;
+  const [capturedPoster, setCapturedPoster] = react.useState(null);
+  react.useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !shouldLoadSrc) return;
+    let cancelled = false;
+    const captureFrame = () => {
+      if (cancelled) return;
+      if (video.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) return;
+      if (video.videoWidth === 0 || video.videoHeight === 0) return;
+      try {
+        const canvas = document.createElement("canvas");
+        canvas.width = video.videoWidth;
+        canvas.height = video.videoHeight;
+        const ctx = canvas.getContext("2d");
+        if (!ctx) return;
+        ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
+        const dataUrl = canvas.toDataURL("image/webp", 0.85);
+        if (!cancelled) {
+          setCapturedPoster(dataUrl);
+        }
+      } catch {
+      }
+    };
+    if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && video.videoWidth > 0) {
+      captureFrame();
+    } else {
+      video.addEventListener("loadeddata", captureFrame, { once: true });
+    }
+    return () => {
+      cancelled = true;
+      video.removeEventListener("loadeddata", captureFrame);
+    };
+  }, [src, shouldLoadSrc]);
+  react.useEffect(() => {
+    setCapturedPoster(null);
+  }, [src]);
   const [isVideoPlaying, setIsVideoPlaying] = react.useState(false);
   react.useEffect(() => {
     const video = videoRef.current;
@@ -1872,32 +2171,38 @@ function VideoSlotInner({
     const prevMuted = video.muted;
     video.muted = true;
     let cancelled = false;
+    let release = null;
     const doPlayAhead = async () => {
-      await acquirePlayAhead();
+      release = await acquirePlayAhead();
+      if (cancelled) {
+        release();
+        return;
+      }
       try {
         await video.play();
         if (cancelled) {
           video.pause();
-          releasePlayAhead();
+          release();
           return;
         }
         const pauseAfterDecode = () => {
           video.pause();
           video.currentTime = 0;
           video.muted = prevMuted;
-          releasePlayAhead();
+          release?.();
           if (!cancelled) {
             setHasPlayedAhead(true);
           }
         };
         setTimeout(pauseAfterDecode, 50);
       } catch {
-        releasePlayAhead();
+        release?.();
       }
     };
     doPlayAhead();
     return () => {
       cancelled = true;
+      release?.();
     };
   }, [isActive, isReady, hasPlayedAhead]);
   react.useEffect(() => {
@@ -2103,13 +2408,13 @@ function VideoSlotInner({
             }
           }
         ),
-        item.poster && !isPreDecoded && /* @__PURE__ */ jsxRuntime.jsx(
+        (capturedPoster || item.poster) && !isPreDecoded && /* @__PURE__ */ jsxRuntime.jsx(
           "div",
           {
             style: {
               position: "absolute",
               inset: 0,
-              backgroundImage: `url(${item.poster})`,
+              backgroundImage: `url(${capturedPoster || item.poster})`,
               backgroundSize: "cover",
               backgroundPosition: "center",
               opacity: showPosterOverlay ? 1 : 0,
@@ -2321,7 +2626,7 @@ function ReelsFeed({
       }, 16);
     };
     const observer = new MutationObserver(debouncedRebuild);
-    observer.observe(container, { childList: true, subtree: true });
+    observer.observe(container, { childList: true, subtree: false });
     return () => {
       observer.disconnect();
       if (rebuildTimer !== null) clearTimeout(rebuildTimer);
@@ -2558,6 +2863,56 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+function useNavigationSelector(selector) {
+  const { navigationManager } = useSDK();
+  const selectorRef = react.useRef(selector);
+  selectorRef.current = selector;
+  const lastSnapshot = react.useRef(void 0);
+  const lastState = react.useRef(void 0);
+  const getSnapshot = react.useCallback(() => {
+    const state = navigationManager.store.getState();
+    if (state !== lastState.current) {
+      lastState.current = state;
+      lastSnapshot.current = selectorRef.current(state);
+    }
+    return lastSnapshot.current;
+  }, [navigationManager]);
+  return react.useSyncExternalStore(
+    navigationManager.store.subscribe,
+    getSnapshot,
+    getSnapshot
+  );
+}
+function useNavigation() {
+  const { navigationManager } = useSDK();
+  const selectPhase = react.useCallback((s) => s.phase, []);
+  const selectOpenIndex = react.useCallback((s) => s.openIndex, []);
+  const phase = useNavigationSelector(selectPhase);
+  const openIndex = useNavigationSelector(selectOpenIndex);
+  const isOpen = phase === "open" || phase === "opening";
+  const shouldMount = phase !== "closed";
+  const open = react.useCallback(
+    (index) => navigationManager.open(index),
+    [navigationManager]
+  );
+  const close = react.useCallback(
+    () => navigationManager.close(),
+    [navigationManager]
+  );
+  const setPhase = react.useCallback(
+    (next) => navigationManager.setPhase(next),
+    [navigationManager]
+  );
+  return {
+    phase,
+    openIndex,
+    isOpen,
+    shouldMount,
+    open,
+    close,
+    setPhase
+  };
+}
 function ReelsFeedThumbnail({
   renderThumbnail,
   onThumbnailClick,
@@ -2567,33 +2922,48 @@ function ReelsFeedThumbnail({
   className = "grid grid-cols-2 gap-3",
   wrap = true,
   setFocusOnClick = true,
+  openOnClick = false,
   prefetchOnHover = false,
+  prewarmOnClick = true,
   getKey
 }) {
   const { items, loading, error, refresh } = useFeed();
   const { setFocusedIndexImmediate } = useResource();
+  const { open } = useNavigation();
   const { adapters } = useSDK();
   const prefetchedRef = react.useRef(/* @__PURE__ */ new Set());
+  const prewarm = react.useCallback(
+    (item) => {
+      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);
+    },
+    [adapters.videoLoader]
+  );
   const handleClick = react.useCallback(
     (id, item, index) => {
+      if (prewarmOnClick) {
+        prewarm(item);
+      }
       if (setFocusOnClick) {
         setFocusedIndexImmediate(index);
       }
+      if (openOnClick) {
+        open(index);
+      }
       onThumbnailClick?.(id, item, index);
     },
-    [setFocusOnClick, setFocusedIndexImmediate, onThumbnailClick]
+    [prewarmOnClick, prewarm, setFocusOnClick, setFocusedIndexImmediate, openOnClick, open, 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);
+      prewarm(item);
     },
-    [prefetchOnHover, adapters.videoLoader]
+    [prefetchOnHover, prewarm]
   );
   if (loading && items.length === 0) {
     if (renderLoading) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderLoading() });
@@ -2633,6 +3003,309 @@ function ReelsFeedThumbnail({
   }
   return /* @__PURE__ */ jsxRuntime.jsx("div", { className, children: content });
 }
+var DEFAULT_DURATION = 300;
+var DEFAULT_EASING = "cubic-bezier(0.22, 1, 0.36, 1)";
+var DEFAULT_DIRECTION = "up";
+var DEFAULT_Z_INDEX = 1e3;
+var DEFAULT_PREWARM_FORWARD = 2;
+function offscreenTransform(direction) {
+  switch (direction) {
+    case "down":
+      return "translateY(-100%)";
+    case "fade":
+      return "translateY(0)";
+    case "up":
+    default:
+      return "translateY(100%)";
+  }
+}
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+var FOCUSABLE = 'a[href],button:not([disabled]),textarea,input,select,[tabindex]:not([tabindex="-1"])';
+function ReelsModal({
+  feedProps,
+  animationConfig,
+  renderBackdrop,
+  renderCloseButton,
+  onOpen,
+  onClose,
+  closeOnBackdropClick = true,
+  closeOnEscape = true,
+  lockBodyScroll = true,
+  prewarmForward = DEFAULT_PREWARM_FORWARD,
+  className,
+  zIndex = DEFAULT_Z_INDEX,
+  portalTarget
+}) {
+  const { phase, openIndex, shouldMount, close, setPhase } = useNavigation();
+  const { setFocusedIndexImmediate } = useResource();
+  const { items } = useFeed();
+  const { adapters } = useSDK();
+  const duration = animationConfig?.duration ?? DEFAULT_DURATION;
+  const easing = animationConfig?.easing ?? DEFAULT_EASING;
+  const direction = animationConfig?.direction ?? DEFAULT_DIRECTION;
+  const backdropRef = react.useRef(null);
+  const panelRef = react.useRef(null);
+  const animationsRef = react.useRef([]);
+  const previouslyFocusedRef = react.useRef(null);
+  const renderState = react.useMemo(
+    () => ({ phase, openIndex, close }),
+    [phase, openIndex, close]
+  );
+  const prewarmedRef = react.useRef(null);
+  react.useEffect(() => {
+    if (phase !== "opening") {
+      if (phase === "closed") prewarmedRef.current = null;
+      return;
+    }
+    if (openIndex == null) return;
+    if (prewarmedRef.current === openIndex) return;
+    prewarmedRef.current = openIndex;
+    setFocusedIndexImmediate(openIndex);
+    const preload = adapters.videoLoader?.preloadMetadata;
+    if (!preload) return;
+    const targets = /* @__PURE__ */ new Set();
+    targets.add(openIndex);
+    for (let d = 1; d <= prewarmForward; d++) targets.add(openIndex + d);
+    targets.add(openIndex - 1);
+    for (const idx of targets) {
+      if (idx < 0 || idx >= items.length) continue;
+      const item = items[idx];
+      if (item && isVideoItem(item) && item.source.type === "hls") {
+        preload(item.source.url);
+      }
+    }
+  }, [phase, openIndex, items, adapters.videoLoader, prewarmForward, setFocusedIndexImmediate]);
+  react.useEffect(() => {
+    if (!lockBodyScroll || !shouldMount) return;
+    if (typeof document === "undefined") return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [lockBodyScroll, shouldMount]);
+  const cancelAnimations = react.useCallback(() => {
+    for (const a of animationsRef.current) a.cancel();
+    animationsRef.current = [];
+  }, []);
+  react.useLayoutEffect(() => {
+    const panel = panelRef.current;
+    const backdrop = backdropRef.current;
+    if (!panel) return;
+    if (phase === "open" || phase === "closed") return;
+    const reduce = prefersReducedMotion();
+    const enter = phase === "opening";
+    const offscreen2 = offscreenTransform(direction);
+    const panelFrames = direction === "fade" ? enter ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 1 }, { opacity: 0 }] : enter ? [{ transform: offscreen2 }, { transform: "translateY(0)" }] : [{ transform: "translateY(0)" }, { transform: offscreen2 }];
+    const backdropFrames = enter ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 1 }, { opacity: 0 }];
+    const animDuration = reduce ? 0 : duration;
+    let cancelled = false;
+    cancelAnimations();
+    const anims = [];
+    const panelAnim = panel.animate(panelFrames, {
+      duration: animDuration,
+      easing,
+      fill: "forwards"
+    });
+    anims.push(panelAnim);
+    if (backdrop) {
+      anims.push(
+        backdrop.animate(backdropFrames, {
+          duration: animDuration,
+          easing,
+          fill: "forwards"
+        })
+      );
+    }
+    animationsRef.current = anims;
+    const finalize = () => {
+      if (cancelled) return;
+      if (enter) {
+        if (direction === "fade") panel.style.opacity = "1";
+        else panel.style.transform = "translateY(0)";
+        if (backdrop) backdrop.style.opacity = "1";
+      } else {
+        if (direction === "fade") panel.style.opacity = "0";
+        else panel.style.transform = offscreen2;
+        if (backdrop) backdrop.style.opacity = "0";
+      }
+      for (const a of anims) a.cancel();
+      animationsRef.current = [];
+      setPhase(enter ? "open" : "closed");
+    };
+    panelAnim.addEventListener("finish", finalize);
+    return () => {
+      cancelled = true;
+      panelAnim.removeEventListener("finish", finalize);
+      cancelAnimations();
+    };
+  }, [phase, direction, duration, easing, setPhase, cancelAnimations]);
+  const prevPhaseRef = react.useRef("closed");
+  react.useEffect(() => {
+    const prev = prevPhaseRef.current;
+    if (prev !== "open" && phase === "open") onOpen?.(openIndex);
+    if (prev !== "closed" && phase === "closed") onClose?.();
+    prevPhaseRef.current = phase;
+  }, [phase, openIndex, onOpen, onClose]);
+  react.useEffect(() => {
+    if (phase === "opening" && typeof document !== "undefined") {
+      previouslyFocusedRef.current = document.activeElement;
+      const id = requestAnimationFrame(() => {
+        const panel = panelRef.current;
+        if (!panel) return;
+        const first = panel.querySelector(FOCUSABLE);
+        (first ?? panel).focus();
+      });
+      return () => cancelAnimationFrame(id);
+    }
+    if (phase === "closed") {
+      previouslyFocusedRef.current?.focus?.();
+      previouslyFocusedRef.current = null;
+    }
+    return void 0;
+  }, [phase]);
+  const handleKeyDown = react.useCallback(
+    (e) => {
+      if (closeOnEscape && e.key === "Escape") {
+        e.stopPropagation();
+        close();
+        return;
+      }
+      if (e.key !== "Tab") return;
+      const panel = panelRef.current;
+      if (!panel) return;
+      const focusables = Array.from(
+        panel.querySelectorAll(FOCUSABLE)
+      ).filter((el) => el.offsetParent !== null);
+      if (focusables.length === 0) {
+        e.preventDefault();
+        panel.focus();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    },
+    [closeOnEscape, close]
+  );
+  const handleBackdropClick = react.useCallback(() => {
+    if (closeOnBackdropClick) close();
+  }, [closeOnBackdropClick, close]);
+  if (!shouldMount) return null;
+  if (typeof document === "undefined") return null;
+  const target = portalTarget ?? document.body;
+  if (!target) return null;
+  const enterStart = phase === "opening";
+  const offscreen = offscreenTransform(direction);
+  const panelInitialTransform = direction === "fade" ? "translateY(0)" : enterStart ? offscreen : "translateY(0)";
+  const panelInitialOpacity = direction === "fade" ? enterStart ? 0 : 1 : 1;
+  const backdropInitialOpacity = enterStart ? 0 : 1;
+  const rootStyle = {
+    position: "fixed",
+    inset: 0,
+    zIndex,
+    // While opening, the panel is parked off-screen but MUST stay painted so
+    // the <video> decodes its first frame. overflow:hidden keeps the
+    // off-screen panel from creating scrollbars / capturing stray taps.
+    overflow: "hidden"
+  };
+  const backdropStyle = {
+    position: "absolute",
+    inset: 0,
+    opacity: backdropInitialOpacity,
+    background: renderBackdrop ? "transparent" : "rgba(0,0,0,0.85)",
+    // willChange hints the compositor for the opacity fade.
+    willChange: "opacity"
+  };
+  const panelStyle = {
+    position: "absolute",
+    inset: 0,
+    transform: panelInitialTransform,
+    opacity: panelInitialOpacity,
+    willChange: direction === "fade" ? "opacity" : "transform",
+    outline: "none"
+  };
+  return reactDom.createPortal(
+    /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        style: rootStyle,
+        onKeyDown: handleKeyDown,
+        "data-reels-modal-phase": phase,
+        children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              ref: backdropRef,
+              style: backdropStyle,
+              onClick: handleBackdropClick,
+              "aria-hidden": "true",
+              "data-reels-modal-backdrop": true,
+              children: renderBackdrop ? renderBackdrop(renderState) : null
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsxs(
+            "div",
+            {
+              ref: panelRef,
+              role: "dialog",
+              "aria-modal": "true",
+              "aria-label": "Reels viewer",
+              tabIndex: -1,
+              className,
+              style: panelStyle,
+              "data-reels-modal-panel": true,
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(ReelsFeed, { ...feedProps }),
+                renderCloseButton ? renderCloseButton(renderState) : /* @__PURE__ */ jsxRuntime.jsx(DefaultCloseButton, { onClose: close })
+              ]
+            }
+          )
+        ]
+      }
+    ),
+    target
+  );
+}
+function DefaultCloseButton({ onClose }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      onClick: onClose,
+      "aria-label": "Close reels viewer",
+      style: {
+        position: "absolute",
+        top: "max(12px, env(safe-area-inset-top))",
+        right: 12,
+        width: 40,
+        height: 40,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        borderRadius: "50%",
+        border: "none",
+        background: "rgba(0,0,0,0.45)",
+        color: "#fff",
+        fontSize: 22,
+        lineHeight: 1,
+        cursor: "pointer",
+        zIndex: 2
+      },
+      children: "\u2715"
+    }
+  );
+}
 function usePlayerSelector(selector) {
   const { playerEngine } = useSDK();
   const selectorRef = react.useRef(selector);
@@ -3248,6 +3921,7 @@ var HttpError = class extends Error {
 };
 
 exports.DEFAULT_FEED_CONFIG = DEFAULT_FEED_CONFIG;
+exports.DEFAULT_NAVIGATION_CONFIG = DEFAULT_NAVIGATION_CONFIG;
 exports.DEFAULT_PLAYER_CONFIG = DEFAULT_PLAYER_CONFIG;
 exports.DEFAULT_RESOURCE_CONFIG = DEFAULT_RESOURCE_CONFIG;
 exports.DefaultActions = DefaultActions;
@@ -3265,11 +3939,13 @@ exports.MockLogger = MockLogger;
 exports.MockNetworkAdapter = MockNetworkAdapter;
 exports.MockSessionStorage = MockSessionStorage;
 exports.MockVideoLoader = MockVideoLoader;
+exports.NavigationManager = NavigationManager;
 exports.OptimisticManager = OptimisticManager;
 exports.PlayerEngine = PlayerEngine;
 exports.PlayerStatus = PlayerStatus;
 exports.ReelsFeed = ReelsFeed;
 exports.ReelsFeedThumbnail = ReelsFeedThumbnail;
+exports.ReelsModal = ReelsModal;
 exports.ReelsProvider = ReelsProvider;
 exports.ResourceGovernor = ResourceGovernor;
 exports.VALID_TRANSITIONS = VALID_TRANSITIONS;
@@ -3278,11 +3954,14 @@ exports.canPause = canPause;
 exports.canPlay = canPlay;
 exports.canSeek = canSeek;
 exports.isArticle = isArticle;
+exports.isValidNavTransition = isValidNavTransition;
 exports.isValidTransition = isValidTransition;
 exports.isVideoItem = isVideoItem;
 exports.useFeed = useFeed;
 exports.useFeedSelector = useFeedSelector;
 exports.useHls = useHls;
+exports.useNavigation = useNavigation;
+exports.useNavigationSelector = useNavigationSelector;
 exports.usePlayer = usePlayer;
 exports.usePlayerSelector = usePlayerSelector;
 exports.usePointerGesture = usePointerGesture;