@xhub-reels/sdk 0.2.11 → 0.2.13

package/dist/index.js

@@ -1,7 +1,8 @@
 import { createStore } from 'zustand/vanilla';
-import { createContext, useRef, useEffect, useCallback, useMemo, useContext, useSyncExternalStore, useState } from 'react';
+import { createContext, useRef, useEffect, useCallback, useMemo, useContext, useSyncExternalStore, useState, useLayoutEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import Hls from 'hls.js';
+import { createPortal } from 'react-dom';
 
 // src/types/content.ts
 function isVideoItem(item) {
@@ -100,6 +101,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;
@@ -309,8 +311,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();
   }
   // ═══════════════════════════════════════════
@@ -413,6 +420,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 };
@@ -438,6 +447,13 @@ var FeedManager = class {
   // ═══════════════════════════════════════════
   // PUBLIC API — Prefetch
   // ═══════════════════════════════════════════
+  setInitialItems(items) {
+    this.prefetchCache = {
+      items,
+      nextCursor: null,
+      timestamp: Date.now()
+    };
+  }
   async prefetch(ttlMs) {
     if (this.prefetchCache) {
       const ttl = ttlMs ?? this.config.staleTTL;
@@ -518,7 +534,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;
@@ -587,7 +606,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());
     }
@@ -595,14 +620,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);
@@ -644,6 +669,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 = createStore(createInitialState3);
@@ -734,6 +761,8 @@ var OptimisticManager = class {
   // PUBLIC API — Lifecycle
   // ═══════════════════════════════════════════
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
     for (const timer of this.likeDebounceTimers.values()) {
       clearTimeout(timer);
     }
@@ -755,6 +784,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;
@@ -785,11 +815,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();
   }
@@ -913,6 +951,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 = 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",
@@ -1102,7 +1287,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);
@@ -1130,31 +1317,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 = createContext(null);
-function ReelsProvider({ children, adapters, debug = false }) {
-  const logger = adapters.logger;
-  const sdkRef = useRef(null);
+function ReelsProvider({
+  children,
+  adapters,
+  initialItems,
+  debug = false,
+  navigationConfig
+}) {
+  const resolvedAdapters = 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 = useRef(null);
   const value = 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 = {
@@ -1162,15 +1418,27 @@ function ReelsProvider({ children, adapters, debug = false }) {
       playerEngine,
       resourceGovernor,
       optimisticManager,
-      adapters
+      navigationManager,
+      adapters: resolvedAdapters
     };
-    sdkRef.current = instance;
     return instance;
   }, [adapters.dataSource]);
   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]);
+  useEffect(() => {
+    const governor = value.resourceGovernor;
+    governor.activate();
     return () => {
-      value.resourceGovernor.deactivate();
+      governor.deactivate();
     };
   }, [value.resourceGovernor]);
   useEffect(() => {
@@ -1180,10 +1448,11 @@ function ReelsProvider({ children, adapters, debug = false }) {
   }, [debug, logger]);
   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__ */ jsx(SDKContext.Provider, { value, children });
@@ -1330,10 +1599,11 @@ var ACTIVE_HLS_DEFAULTS = {
   maxMaxBufferLength: 15,
   capLevelToPlayerSize: true,
   startLevel: 0,
-  abrEwmaDefaultEstimate: 5e5,
+  abrEwmaDefaultEstimate: 2e6,
   lowLatencyMode: false,
   backBufferLength: 5,
-  enableWorker: true
+  enableWorker: true,
+  startFragPrefetch: true
 };
 var HOT_HLS_DEFAULTS = {
   maxBufferLength: 2,
@@ -1686,25 +1956,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,
@@ -1827,6 +2106,56 @@ function VideoSlotInner({
     }
   }, [mp4Src, isActive, isPrefetch, isPreloaded, isHlsSource]);
   const isReady = isHlsSource ? hlsReady : mp4Ready;
+  const [capturedPoster, setCapturedPoster] = useState(null);
+  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]);
+  useEffect(() => {
+    setCapturedPoster(null);
+  }, [src]);
+  const [isVideoPlaying, setIsVideoPlaying] = useState(false);
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !isActive) {
+      setIsVideoPlaying(false);
+      return;
+    }
+    const onPlaying = () => setIsVideoPlaying(true);
+    video.addEventListener("playing", onPlaying);
+    return () => {
+      video.removeEventListener("playing", onPlaying);
+      setIsVideoPlaying(false);
+    };
+  }, [isActive]);
   const [hasPlayedAhead, setHasPlayedAhead] = useState(false);
   useEffect(() => {
     const video = videoRef.current;
@@ -1836,36 +2165,43 @@ 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]);
   useEffect(() => {
     setHasPlayedAhead(false);
+    setIsVideoPlaying(false);
   }, [src]);
   const wasActiveRef = useRef(false);
   const [isManuallyPaused, setIsManuallyPaused] = useState(false);
@@ -1942,7 +2278,7 @@ function VideoSlotInner({
     if (!video) return;
     video.muted = isActive ? isMuted : true;
   }, [isMuted, isActive]);
-  const showPosterOverlay = !isReady && !hasPlayedAhead;
+  const showPosterOverlay = isActive ? !isVideoPlaying : !isReady && !hasPlayedAhead;
   const isPreDecoded = hasPlayedAhead;
   const [showMuteIndicator, setShowMuteIndicator] = useState(false);
   const muteIndicatorTimer = useRef(null);
@@ -2060,23 +2396,23 @@ function VideoSlotInner({
               height: "100%",
               objectFit: "cover",
               // Hide video until ready to avoid black frame flash.
-              // When pre-decoded, skip transition — first frame is already on canvas.
+              // When pre-decoded or active, skip transition — first frame is already on canvas or playing.
               opacity: showPosterOverlay ? 0 : 1,
-              transition: isPreDecoded ? "none" : "opacity 0.15s ease"
+              transition: isActive ? "none" : isPreDecoded ? "none" : "opacity 0.15s ease"
             }
           }
         ),
-        item.poster && !isPreDecoded && /* @__PURE__ */ jsx(
+        (capturedPoster || item.poster) && !isPreDecoded && /* @__PURE__ */ jsx(
           "div",
           {
             style: {
               position: "absolute",
               inset: 0,
-              backgroundImage: `url(${item.poster})`,
+              backgroundImage: `url(${capturedPoster || item.poster})`,
               backgroundSize: "cover",
               backgroundPosition: "center",
               opacity: showPosterOverlay ? 1 : 0,
-              transition: "opacity 0.15s ease",
+              transition: isActive ? "none" : "opacity 0.15s ease",
               pointerEvents: "none"
             }
           }
@@ -2284,7 +2620,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);
@@ -2521,6 +2857,56 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+function useNavigationSelector(selector) {
+  const { navigationManager } = useSDK();
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+  const lastSnapshot = useRef(void 0);
+  const lastState = useRef(void 0);
+  const getSnapshot = useCallback(() => {
+    const state = navigationManager.store.getState();
+    if (state !== lastState.current) {
+      lastState.current = state;
+      lastSnapshot.current = selectorRef.current(state);
+    }
+    return lastSnapshot.current;
+  }, [navigationManager]);
+  return useSyncExternalStore(
+    navigationManager.store.subscribe,
+    getSnapshot,
+    getSnapshot
+  );
+}
+function useNavigation() {
+  const { navigationManager } = useSDK();
+  const selectPhase = useCallback((s) => s.phase, []);
+  const selectOpenIndex = useCallback((s) => s.openIndex, []);
+  const phase = useNavigationSelector(selectPhase);
+  const openIndex = useNavigationSelector(selectOpenIndex);
+  const isOpen = phase === "open" || phase === "opening";
+  const shouldMount = phase !== "closed";
+  const open = useCallback(
+    (index) => navigationManager.open(index),
+    [navigationManager]
+  );
+  const close = useCallback(
+    () => navigationManager.close(),
+    [navigationManager]
+  );
+  const setPhase = useCallback(
+    (next) => navigationManager.setPhase(next),
+    [navigationManager]
+  );
+  return {
+    phase,
+    openIndex,
+    isOpen,
+    shouldMount,
+    open,
+    close,
+    setPhase
+  };
+}
 function ReelsFeedThumbnail({
   renderThumbnail,
   onThumbnailClick,
@@ -2530,33 +2916,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 = useRef(/* @__PURE__ */ new Set());
+  const prewarm = 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 = 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 = 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__ */ jsx(Fragment, { children: renderLoading() });
@@ -2596,6 +2997,309 @@ function ReelsFeedThumbnail({
   }
   return /* @__PURE__ */ 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 = useRef(null);
+  const panelRef = useRef(null);
+  const animationsRef = useRef([]);
+  const previouslyFocusedRef = useRef(null);
+  const renderState = useMemo(
+    () => ({ phase, openIndex, close }),
+    [phase, openIndex, close]
+  );
+  const prewarmedRef = useRef(null);
+  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]);
+  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 = useCallback(() => {
+    for (const a of animationsRef.current) a.cancel();
+    animationsRef.current = [];
+  }, []);
+  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 = useRef("closed");
+  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]);
+  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 = 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 = 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 createPortal(
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        style: rootStyle,
+        onKeyDown: handleKeyDown,
+        "data-reels-modal-phase": phase,
+        children: [
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              ref: backdropRef,
+              style: backdropStyle,
+              onClick: handleBackdropClick,
+              "aria-hidden": "true",
+              "data-reels-modal-backdrop": true,
+              children: renderBackdrop ? renderBackdrop(renderState) : null
+            }
+          ),
+          /* @__PURE__ */ 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__ */ jsx(ReelsFeed, { ...feedProps }),
+                renderCloseButton ? renderCloseButton(renderState) : /* @__PURE__ */ jsx(DefaultCloseButton, { onClose: close })
+              ]
+            }
+          )
+        ]
+      }
+    ),
+    target
+  );
+}
+function DefaultCloseButton({ onClose }) {
+  return /* @__PURE__ */ 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 = useRef(selector);
@@ -3210,4 +3914,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, ReelsFeedThumbnail, 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_NAVIGATION_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, FeedManager, HttpDataSource, HttpError, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, NavigationManager, OptimisticManager, PlayerEngine, PlayerStatus, ReelsFeed, ReelsFeedThumbnail, ReelsModal, ReelsProvider, ResourceGovernor, VALID_TRANSITIONS, VideoSlot, canPause, canPlay, canSeek, isArticle, isValidNavTransition, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, useNavigation, useNavigationSelector, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };