@xhub-reels/sdk 0.1.17 → 0.1.19

package/dist/index.cjs

@@ -741,9 +741,12 @@ var OptimisticManager = class {
   }
 };
 var DEFAULT_RESOURCE_CONFIG = {
-  maxAllocations: 11,
-  bufferWindow: 3,
-  warmWindow: 4,
+  // bufferWindow=2 → ±2 hot slots + 1 active = 5 HLS instances max.
+  // Reduced from 3 to eliminate media pipeline thread contention on iOS/Android WebView
+  // that caused jank after scrolling 4-5 videos (7 concurrent HLS instances was too many).
+  maxAllocations: 8,
+  bufferWindow: 2,
+  warmWindow: 3,
   // 0ms debounce — setFocusedIndexImmediate is already used post-snap.
   focusDebounceMs: 0,
   preloadLookAhead: 3
@@ -1393,7 +1396,7 @@ function mapHlsError(data) {
   }
 }
 function useHls(options) {
-  const { src, videoRef, isActive, isPrefetch, bufferTier = "active", hlsConfig, onError } = options;
+  const { src, videoRef, isActive, isPrefetch, bufferTier = "active", hlsConfig, onError, isDragging = false } = options;
   const isHlsSupported = typeof window !== "undefined" && Hls__default.default.isSupported();
   const isNative = supportsNativeHls();
   const isHlsJs = isHlsSupported && !isNative;
@@ -1549,6 +1552,21 @@ function useHls(options) {
       }
     }
   }, [bufferTier]);
+  react.useEffect(() => {
+    const hls = hlsRef.current;
+    if (!hls || isActive) return;
+    if (isDragging) {
+      try {
+        hls.stopLoad();
+      } catch {
+      }
+    } else {
+      try {
+        hls.startLoad(-1);
+      } catch {
+      }
+    }
+  }, [isDragging, isActive]);
   return {
     isHlsJs,
     isReady,
@@ -1705,7 +1723,8 @@ function DefaultPauseAction() {
     }
   );
 }
-var PLAY_AHEAD_MAX_CONCURRENT = 2;
+var PLAY_AHEAD_MAX_CONCURRENT = 3;
+var PLAY_AHEAD_STAGGER_MS = 50;
 var _playAheadActive = 0;
 var _playAheadQueue = [];
 function acquirePlayAhead() {
@@ -1713,7 +1732,12 @@ function acquirePlayAhead() {
     _playAheadActive++;
     return Promise.resolve();
   }
-  return new Promise((resolve) => _playAheadQueue.push(resolve));
+  return new Promise((resolve) => {
+    const queuePosition = _playAheadQueue.length;
+    _playAheadQueue.push(() => {
+      setTimeout(resolve, PLAY_AHEAD_STAGGER_MS * queuePosition);
+    });
+  });
 }
 function releasePlayAhead() {
   _playAheadActive = Math.max(0, _playAheadActive - 1);
@@ -1734,6 +1758,7 @@ function VideoSlot({
   onToggleMute,
   onAutoplayBlocked,
   showFps = false,
+  isDragging = false,
   renderOverlay,
   renderActions,
   renderPauseAction
@@ -1771,6 +1796,7 @@ function VideoSlot({
       onToggleMute,
       onAutoplayBlocked,
       showFps,
+      isDragging,
       renderOverlay,
       renderActions,
       renderPauseAction,
@@ -1790,6 +1816,7 @@ function VideoSlotInner({
   onToggleMute,
   onAutoplayBlocked,
   showFps,
+  isDragging,
   renderOverlay,
   renderActions,
   renderPauseAction,
@@ -1811,6 +1838,7 @@ function VideoSlotInner({
     // so useHls creates the HLS instance and starts buffering
     isPrefetch: isPrefetch || isPreloaded,
     bufferTier,
+    isDragging,
     onError: (code, message) => {
       console.error(`[VideoSlot] HLS error: ${code} \u2014 ${message}`);
     }
@@ -1947,6 +1975,7 @@ function VideoSlotInner({
     video.muted = isActive ? isMuted : true;
   }, [isMuted, isActive]);
   const showPosterOverlay = !isReady && !hasPlayedAhead;
+  const isPreDecoded = hasPlayedAhead;
   const [showMuteIndicator, setShowMuteIndicator] = react.useState(false);
   const muteIndicatorTimer = react.useRef(null);
   const handleToggleMute = react.useCallback(() => {
@@ -2062,13 +2091,14 @@ function VideoSlotInner({
               width: "100%",
               height: "100%",
               objectFit: "cover",
-              // Hide video until ready to avoid black frame flash
+              // Hide video until ready to avoid black frame flash.
+              // When pre-decoded, skip transition — first frame is already on canvas.
               opacity: showPosterOverlay ? 0 : 1,
-              transition: "opacity 0.15s ease"
+              transition: isPreDecoded ? "none" : "opacity 0.15s ease"
             }
           }
         ),
-        item.poster && /* @__PURE__ */ jsxRuntime.jsx(
+        item.poster && !isPreDecoded && /* @__PURE__ */ jsxRuntime.jsx(
           "div",
           {
             style: {
@@ -2198,6 +2228,7 @@ function FpsCounter() {
   );
 }
 var RENDER_WINDOW_RADIUS = 3;
+var PLACEHOLDER_EXTRA = 2;
 var centerStyle = {
   height: "100dvh",
   display: "flex",
@@ -2275,9 +2306,20 @@ function ReelsFeed({
       }
     };
     rebuild();
-    const observer = new MutationObserver(rebuild);
+    let rebuildTimer = null;
+    const debouncedRebuild = () => {
+      if (rebuildTimer !== null) return;
+      rebuildTimer = setTimeout(() => {
+        rebuildTimer = null;
+        rebuild();
+      }, 16);
+    };
+    const observer = new MutationObserver(debouncedRebuild);
     observer.observe(container, { childList: true, subtree: true });
-    return () => observer.disconnect();
+    return () => {
+      observer.disconnect();
+      if (rebuildTimer !== null) clearTimeout(rebuildTimer);
+    };
   }, [items.length, focusedIndex]);
   const containerHeight = react.useRef(
     typeof window !== "undefined" ? window.innerHeight : 800
@@ -2403,6 +2445,15 @@ function ReelsFeed({
   const handleToggleMute = react.useCallback(() => {
     setIsMuted((prev) => !prev);
   }, []);
+  const windowedItems = react.useMemo(() => {
+    const start = Math.max(0, focusedIndex - RENDER_WINDOW_RADIUS - PLACEHOLDER_EXTRA);
+    const end = Math.min(items.length - 1, focusedIndex + RENDER_WINDOW_RADIUS + PLACEHOLDER_EXTRA);
+    const result = [];
+    for (let i = start; i <= end; i++) {
+      result.push({ item: items[i], index: i });
+    }
+    return result;
+  }, [items, focusedIndex]);
   if (loading && items.length === 0) {
     return /* @__PURE__ */ jsxRuntime.jsx("div", { style: { ...centerStyle, flexDirection: "column", gap: 0 }, children: renderLoading ? renderLoading() : /* @__PURE__ */ jsxRuntime.jsx(DefaultSkeleton, {}) });
   }
@@ -2439,7 +2490,7 @@ function ReelsFeed({
                     to { transform: rotate(360deg); }
                 }
             ` }),
-        items.map((item, index) => {
+        windowedItems.map(({ item, index }) => {
           const distFromFocus = Math.abs(index - focusedIndex);
           const wrapperStyle = {
             position: "absolute",
@@ -2474,6 +2525,7 @@ function ReelsFeed({
                   onToggleMute: handleToggleMute,
                   onAutoplayBlocked,
                   showFps: showFps && isActive,
+                  isDragging: isDragMuted,
                   renderOverlay,
                   renderActions,
                   renderPauseAction

package/dist/index.d.cts

@@ -577,7 +577,10 @@ declare class OptimisticManager {
  * Tier 4 (Cold):    preloadLookAhead beyond warm — metadata/manifest prefetch only (no DOM)
  *
  * Total DOM nodes = 1 + 2×bufferWindow + warmWindow (forward) + 1 (backward)
- * Default: 1 + 6 + 4 = 11 DOM nodes, ~112 MB memory (fits comfortably in 1 GB budget)
+ * Default: 1 + 4 + 3 = 8 DOM nodes, ~80 MB memory (fits comfortably in 1 GB budget)
+ *
+ * bufferWindow reduced from 3→2 to cut concurrent HLS instances from 7→5,
+ * eliminating media pipeline thread contention on iOS/Android WebView.
  */
 
 interface ResourceState {
@@ -831,6 +834,13 @@ interface UseHlsOptions {
     hlsConfig?: Partial<HlsConfig>;
     /** Called when hls.js encounters a fatal error. Maps to PlayerEngine error codes. */
     onError?: (code: 'NETWORK_ERROR' | 'MEDIA_ERROR' | 'DECODE_ERROR' | 'UNKNOWN', message: string) => void;
+    /**
+     * Whether the user is currently dragging/swiping.
+     * When true, non-active slots pause HLS network fetching (hls.stopLoad) to
+     * free bandwidth for the active slot and reduce main-thread contention.
+     * Active slot is never paused regardless of this flag.
+     */
+    isDragging?: boolean;
 }
 interface UseHlsReturn {
     /** Whether hls.js is being used (false = native HLS on Safari) */
@@ -854,11 +864,16 @@ interface VideoSlotProps {
     /** Called when unmuted autoplay fails and SDK falls back to muted playback */
     onAutoplayBlocked?: () => void;
     showFps?: boolean;
+    /**
+     * Whether the user is currently dragging. Passed to useHls to pause
+     * non-active HLS fetching during gesture, freeing bandwidth + main thread.
+     */
+    isDragging?: boolean;
     renderOverlay?: (item: ContentItem, actions: SlotActions) => react.ReactNode;
     renderActions?: (item: ContentItem, actions: SlotActions) => react.ReactNode;
     renderPauseAction?: (item: ContentItem, actions: PauseSlotActions) => react.ReactNode;
 }
-declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
+declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, isDragging, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
 
 declare function DefaultOverlay({ item }: {
     item: ContentItem;

package/dist/index.d.ts

@@ -577,7 +577,10 @@ declare class OptimisticManager {
  * Tier 4 (Cold):    preloadLookAhead beyond warm — metadata/manifest prefetch only (no DOM)
  *
  * Total DOM nodes = 1 + 2×bufferWindow + warmWindow (forward) + 1 (backward)
- * Default: 1 + 6 + 4 = 11 DOM nodes, ~112 MB memory (fits comfortably in 1 GB budget)
+ * Default: 1 + 4 + 3 = 8 DOM nodes, ~80 MB memory (fits comfortably in 1 GB budget)
+ *
+ * bufferWindow reduced from 3→2 to cut concurrent HLS instances from 7→5,
+ * eliminating media pipeline thread contention on iOS/Android WebView.
  */
 
 interface ResourceState {
@@ -831,6 +834,13 @@ interface UseHlsOptions {
     hlsConfig?: Partial<HlsConfig>;
     /** Called when hls.js encounters a fatal error. Maps to PlayerEngine error codes. */
     onError?: (code: 'NETWORK_ERROR' | 'MEDIA_ERROR' | 'DECODE_ERROR' | 'UNKNOWN', message: string) => void;
+    /**
+     * Whether the user is currently dragging/swiping.
+     * When true, non-active slots pause HLS network fetching (hls.stopLoad) to
+     * free bandwidth for the active slot and reduce main-thread contention.
+     * Active slot is never paused regardless of this flag.
+     */
+    isDragging?: boolean;
 }
 interface UseHlsReturn {
     /** Whether hls.js is being used (false = native HLS on Safari) */
@@ -854,11 +864,16 @@ interface VideoSlotProps {
     /** Called when unmuted autoplay fails and SDK falls back to muted playback */
     onAutoplayBlocked?: () => void;
     showFps?: boolean;
+    /**
+     * Whether the user is currently dragging. Passed to useHls to pause
+     * non-active HLS fetching during gesture, freeing bandwidth + main thread.
+     */
+    isDragging?: boolean;
     renderOverlay?: (item: ContentItem, actions: SlotActions) => react.ReactNode;
     renderActions?: (item: ContentItem, actions: SlotActions) => react.ReactNode;
     renderPauseAction?: (item: ContentItem, actions: PauseSlotActions) => react.ReactNode;
 }
-declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
+declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, isDragging, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
 
 declare function DefaultOverlay({ item }: {
     item: ContentItem;

package/dist/index.js

@@ -735,9 +735,12 @@ var OptimisticManager = class {
   }
 };
 var DEFAULT_RESOURCE_CONFIG = {
-  maxAllocations: 11,
-  bufferWindow: 3,
-  warmWindow: 4,
+  // bufferWindow=2 → ±2 hot slots + 1 active = 5 HLS instances max.
+  // Reduced from 3 to eliminate media pipeline thread contention on iOS/Android WebView
+  // that caused jank after scrolling 4-5 videos (7 concurrent HLS instances was too many).
+  maxAllocations: 8,
+  bufferWindow: 2,
+  warmWindow: 3,
   // 0ms debounce — setFocusedIndexImmediate is already used post-snap.
   focusDebounceMs: 0,
   preloadLookAhead: 3
@@ -1387,7 +1390,7 @@ function mapHlsError(data) {
   }
 }
 function useHls(options) {
-  const { src, videoRef, isActive, isPrefetch, bufferTier = "active", hlsConfig, onError } = options;
+  const { src, videoRef, isActive, isPrefetch, bufferTier = "active", hlsConfig, onError, isDragging = false } = options;
   const isHlsSupported = typeof window !== "undefined" && Hls.isSupported();
   const isNative = supportsNativeHls();
   const isHlsJs = isHlsSupported && !isNative;
@@ -1543,6 +1546,21 @@ function useHls(options) {
       }
     }
   }, [bufferTier]);
+  useEffect(() => {
+    const hls = hlsRef.current;
+    if (!hls || isActive) return;
+    if (isDragging) {
+      try {
+        hls.stopLoad();
+      } catch {
+      }
+    } else {
+      try {
+        hls.startLoad(-1);
+      } catch {
+      }
+    }
+  }, [isDragging, isActive]);
   return {
     isHlsJs,
     isReady,
@@ -1699,7 +1717,8 @@ function DefaultPauseAction() {
     }
   );
 }
-var PLAY_AHEAD_MAX_CONCURRENT = 2;
+var PLAY_AHEAD_MAX_CONCURRENT = 3;
+var PLAY_AHEAD_STAGGER_MS = 50;
 var _playAheadActive = 0;
 var _playAheadQueue = [];
 function acquirePlayAhead() {
@@ -1707,7 +1726,12 @@ function acquirePlayAhead() {
     _playAheadActive++;
     return Promise.resolve();
   }
-  return new Promise((resolve) => _playAheadQueue.push(resolve));
+  return new Promise((resolve) => {
+    const queuePosition = _playAheadQueue.length;
+    _playAheadQueue.push(() => {
+      setTimeout(resolve, PLAY_AHEAD_STAGGER_MS * queuePosition);
+    });
+  });
 }
 function releasePlayAhead() {
   _playAheadActive = Math.max(0, _playAheadActive - 1);
@@ -1728,6 +1752,7 @@ function VideoSlot({
   onToggleMute,
   onAutoplayBlocked,
   showFps = false,
+  isDragging = false,
   renderOverlay,
   renderActions,
   renderPauseAction
@@ -1765,6 +1790,7 @@ function VideoSlot({
       onToggleMute,
       onAutoplayBlocked,
       showFps,
+      isDragging,
       renderOverlay,
       renderActions,
       renderPauseAction,
@@ -1784,6 +1810,7 @@ function VideoSlotInner({
   onToggleMute,
   onAutoplayBlocked,
   showFps,
+  isDragging,
   renderOverlay,
   renderActions,
   renderPauseAction,
@@ -1805,6 +1832,7 @@ function VideoSlotInner({
     // so useHls creates the HLS instance and starts buffering
     isPrefetch: isPrefetch || isPreloaded,
     bufferTier,
+    isDragging,
     onError: (code, message) => {
       console.error(`[VideoSlot] HLS error: ${code} \u2014 ${message}`);
     }
@@ -1941,6 +1969,7 @@ function VideoSlotInner({
     video.muted = isActive ? isMuted : true;
   }, [isMuted, isActive]);
   const showPosterOverlay = !isReady && !hasPlayedAhead;
+  const isPreDecoded = hasPlayedAhead;
   const [showMuteIndicator, setShowMuteIndicator] = useState(false);
   const muteIndicatorTimer = useRef(null);
   const handleToggleMute = useCallback(() => {
@@ -2056,13 +2085,14 @@ function VideoSlotInner({
               width: "100%",
               height: "100%",
               objectFit: "cover",
-              // Hide video until ready to avoid black frame flash
+              // Hide video until ready to avoid black frame flash.
+              // When pre-decoded, skip transition — first frame is already on canvas.
               opacity: showPosterOverlay ? 0 : 1,
-              transition: "opacity 0.15s ease"
+              transition: isPreDecoded ? "none" : "opacity 0.15s ease"
             }
           }
         ),
-        item.poster && /* @__PURE__ */ jsx(
+        item.poster && !isPreDecoded && /* @__PURE__ */ jsx(
           "div",
           {
             style: {
@@ -2192,6 +2222,7 @@ function FpsCounter() {
   );
 }
 var RENDER_WINDOW_RADIUS = 3;
+var PLACEHOLDER_EXTRA = 2;
 var centerStyle = {
   height: "100dvh",
   display: "flex",
@@ -2269,9 +2300,20 @@ function ReelsFeed({
       }
     };
     rebuild();
-    const observer = new MutationObserver(rebuild);
+    let rebuildTimer = null;
+    const debouncedRebuild = () => {
+      if (rebuildTimer !== null) return;
+      rebuildTimer = setTimeout(() => {
+        rebuildTimer = null;
+        rebuild();
+      }, 16);
+    };
+    const observer = new MutationObserver(debouncedRebuild);
     observer.observe(container, { childList: true, subtree: true });
-    return () => observer.disconnect();
+    return () => {
+      observer.disconnect();
+      if (rebuildTimer !== null) clearTimeout(rebuildTimer);
+    };
   }, [items.length, focusedIndex]);
   const containerHeight = useRef(
     typeof window !== "undefined" ? window.innerHeight : 800
@@ -2397,6 +2439,15 @@ function ReelsFeed({
   const handleToggleMute = useCallback(() => {
     setIsMuted((prev) => !prev);
   }, []);
+  const windowedItems = useMemo(() => {
+    const start = Math.max(0, focusedIndex - RENDER_WINDOW_RADIUS - PLACEHOLDER_EXTRA);
+    const end = Math.min(items.length - 1, focusedIndex + RENDER_WINDOW_RADIUS + PLACEHOLDER_EXTRA);
+    const result = [];
+    for (let i = start; i <= end; i++) {
+      result.push({ item: items[i], index: i });
+    }
+    return result;
+  }, [items, focusedIndex]);
   if (loading && items.length === 0) {
     return /* @__PURE__ */ jsx("div", { style: { ...centerStyle, flexDirection: "column", gap: 0 }, children: renderLoading ? renderLoading() : /* @__PURE__ */ jsx(DefaultSkeleton, {}) });
   }
@@ -2433,7 +2484,7 @@ function ReelsFeed({
                     to { transform: rotate(360deg); }
                 }
             ` }),
-        items.map((item, index) => {
+        windowedItems.map(({ item, index }) => {
           const distFromFocus = Math.abs(index - focusedIndex);
           const wrapperStyle = {
             position: "absolute",
@@ -2468,6 +2519,7 @@ function ReelsFeed({
                   onToggleMute: handleToggleMute,
                   onAutoplayBlocked,
                   showFps: showFps && isActive,
+                  isDragging: isDragMuted,
                   renderOverlay,
                   renderActions,
                   renderPauseAction

package/package.json

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