@xhub-reels/sdk 0.1.18 → 0.1.20

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,
@@ -1706,6 +1724,7 @@ function DefaultPauseAction() {
   );
 }
 var PLAY_AHEAD_MAX_CONCURRENT = 2;
+var PLAY_AHEAD_STAGGER_MS = 80;
 var _playAheadActive = 0;
 var _playAheadQueue = [];
 function acquirePlayAhead() {
@@ -1713,7 +1732,11 @@ function acquirePlayAhead() {
     _playAheadActive++;
     return Promise.resolve();
   }
-  return new Promise((resolve) => _playAheadQueue.push(resolve));
+  return new Promise((resolve) => {
+    _playAheadQueue.push(() => {
+      setTimeout(resolve, PLAY_AHEAD_STAGGER_MS);
+    });
+  });
 }
 function releasePlayAhead() {
   _playAheadActive = Math.max(0, _playAheadActive - 1);
@@ -1734,6 +1757,7 @@ function VideoSlot({
   onToggleMute,
   onAutoplayBlocked,
   showFps = false,
+  isDragging = false,
   renderOverlay,
   renderActions,
   renderPauseAction
@@ -1771,6 +1795,7 @@ function VideoSlot({
       onToggleMute,
       onAutoplayBlocked,
       showFps,
+      isDragging,
       renderOverlay,
       renderActions,
       renderPauseAction,
@@ -1790,6 +1815,7 @@ function VideoSlotInner({
   onToggleMute,
   onAutoplayBlocked,
   showFps,
+  isDragging,
   renderOverlay,
   renderActions,
   renderPauseAction,
@@ -1811,6 +1837,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}`);
     }
@@ -2200,6 +2227,7 @@ function FpsCounter() {
   );
 }
 var RENDER_WINDOW_RADIUS = 3;
+var PLACEHOLDER_EXTRA = 2;
 var centerStyle = {
   height: "100dvh",
   display: "flex",
@@ -2241,7 +2269,6 @@ function ReelsFeed({
   const slotCacheRef = react.useRef(/* @__PURE__ */ new Map());
   const activeIndexRef = react.useRef(0);
   activeIndexRef.current = focusedIndex;
-  const [isSnapping, setIsSnapping] = react.useState(false);
   const { animateSnap, animateBounceBack, cancelAnimation } = useSnapAnimation({
     duration: snapConfig?.duration ?? 260,
     easing: snapConfig?.easing ?? "cubic-bezier(0.25, 0.46, 0.45, 0.94)"
@@ -2277,9 +2304,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
@@ -2336,13 +2374,7 @@ function ReelsFeed({
         return;
       }
       cancelAnimation();
-      setIsSnapping(true);
       setPrefetchIndex(null);
-      setFocusedIndexImmediate(next);
-      const nextItem = items[next];
-      if (nextItem) {
-        onSlotChange?.(next, nextItem, current);
-      }
       const h = containerHeight.current;
       const targets = [];
       for (const [idx, el] of slotCacheRef.current) {
@@ -2353,7 +2385,13 @@ function ReelsFeed({
         });
       }
       animateSnap(targets);
-      setTimeout(() => setIsSnapping(false), 300);
+      requestAnimationFrame(() => {
+        setFocusedIndexImmediate(next);
+        const nextItem = items[next];
+        if (nextItem) {
+          onSlotChange?.(next, nextItem, current);
+        }
+      });
     },
     [items, animateSnap, animateBounceBack, cancelAnimation, setFocusedIndexImmediate, setPrefetchIndex, onSlotChange]
   );
@@ -2375,13 +2413,13 @@ function ReelsFeed({
     setIsDragMuted(true);
   }, []);
   const handleDragEnd = react.useCallback(() => {
-    setTimeout(() => setIsDragMuted(false), 50);
+    setTimeout(() => setIsDragMuted(false), 300);
   }, []);
   const { bind } = usePointerGesture({
     axis: "y",
     velocityThreshold: gestureConfig?.velocityThreshold ?? 0.3,
     distanceThreshold: gestureConfig?.distanceThreshold ?? 80,
-    disabled: isSnapping,
+    disabled: false,
     containerSize: containerHeight.current,
     dragThresholdRatio: gestureConfig?.dragThresholdRatio ?? 0.5,
     onDragOffset: (offset) => {
@@ -2405,6 +2443,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, {}) });
   }
@@ -2441,12 +2488,18 @@ function ReelsFeed({
                     to { transform: rotate(360deg); }
                 }
             ` }),
-        items.map((item, index) => {
+        windowedItems.map(({ item, index }) => {
           const distFromFocus = Math.abs(index - focusedIndex);
           const wrapperStyle = {
             position: "absolute",
             inset: 0,
-            contain: "layout style paint",
+            // Fix 4: 'strict' = layout + style + paint + size containment.
+            // Tells browser this slot is fully self-contained — no layout
+            // escapes to parent. Eliminates layout thrash during animation.
+            contain: "strict",
+            // Fix 4: willChange only on active ±1 (3 slots max).
+            // Previously ±1 already, keep it. Avoids unnecessary GPU layers
+            // on warm/cold slots that are never animated directly.
             willChange: distFromFocus <= 1 ? "transform" : "auto",
             transform: getInitialTransformPx(index)
           };
@@ -2476,6 +2529,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,
@@ -1700,6 +1718,7 @@ function DefaultPauseAction() {
   );
 }
 var PLAY_AHEAD_MAX_CONCURRENT = 2;
+var PLAY_AHEAD_STAGGER_MS = 80;
 var _playAheadActive = 0;
 var _playAheadQueue = [];
 function acquirePlayAhead() {
@@ -1707,7 +1726,11 @@ function acquirePlayAhead() {
     _playAheadActive++;
     return Promise.resolve();
   }
-  return new Promise((resolve) => _playAheadQueue.push(resolve));
+  return new Promise((resolve) => {
+    _playAheadQueue.push(() => {
+      setTimeout(resolve, PLAY_AHEAD_STAGGER_MS);
+    });
+  });
 }
 function releasePlayAhead() {
   _playAheadActive = Math.max(0, _playAheadActive - 1);
@@ -1728,6 +1751,7 @@ function VideoSlot({
   onToggleMute,
   onAutoplayBlocked,
   showFps = false,
+  isDragging = false,
   renderOverlay,
   renderActions,
   renderPauseAction
@@ -1765,6 +1789,7 @@ function VideoSlot({
       onToggleMute,
       onAutoplayBlocked,
       showFps,
+      isDragging,
       renderOverlay,
       renderActions,
       renderPauseAction,
@@ -1784,6 +1809,7 @@ function VideoSlotInner({
   onToggleMute,
   onAutoplayBlocked,
   showFps,
+  isDragging,
   renderOverlay,
   renderActions,
   renderPauseAction,
@@ -1805,6 +1831,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}`);
     }
@@ -2194,6 +2221,7 @@ function FpsCounter() {
   );
 }
 var RENDER_WINDOW_RADIUS = 3;
+var PLACEHOLDER_EXTRA = 2;
 var centerStyle = {
   height: "100dvh",
   display: "flex",
@@ -2235,7 +2263,6 @@ function ReelsFeed({
   const slotCacheRef = useRef(/* @__PURE__ */ new Map());
   const activeIndexRef = useRef(0);
   activeIndexRef.current = focusedIndex;
-  const [isSnapping, setIsSnapping] = useState(false);
   const { animateSnap, animateBounceBack, cancelAnimation } = useSnapAnimation({
     duration: snapConfig?.duration ?? 260,
     easing: snapConfig?.easing ?? "cubic-bezier(0.25, 0.46, 0.45, 0.94)"
@@ -2271,9 +2298,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
@@ -2330,13 +2368,7 @@ function ReelsFeed({
         return;
       }
       cancelAnimation();
-      setIsSnapping(true);
       setPrefetchIndex(null);
-      setFocusedIndexImmediate(next);
-      const nextItem = items[next];
-      if (nextItem) {
-        onSlotChange?.(next, nextItem, current);
-      }
       const h = containerHeight.current;
       const targets = [];
       for (const [idx, el] of slotCacheRef.current) {
@@ -2347,7 +2379,13 @@ function ReelsFeed({
         });
       }
       animateSnap(targets);
-      setTimeout(() => setIsSnapping(false), 300);
+      requestAnimationFrame(() => {
+        setFocusedIndexImmediate(next);
+        const nextItem = items[next];
+        if (nextItem) {
+          onSlotChange?.(next, nextItem, current);
+        }
+      });
     },
     [items, animateSnap, animateBounceBack, cancelAnimation, setFocusedIndexImmediate, setPrefetchIndex, onSlotChange]
   );
@@ -2369,13 +2407,13 @@ function ReelsFeed({
     setIsDragMuted(true);
   }, []);
   const handleDragEnd = useCallback(() => {
-    setTimeout(() => setIsDragMuted(false), 50);
+    setTimeout(() => setIsDragMuted(false), 300);
   }, []);
   const { bind } = usePointerGesture({
     axis: "y",
     velocityThreshold: gestureConfig?.velocityThreshold ?? 0.3,
     distanceThreshold: gestureConfig?.distanceThreshold ?? 80,
-    disabled: isSnapping,
+    disabled: false,
     containerSize: containerHeight.current,
     dragThresholdRatio: gestureConfig?.dragThresholdRatio ?? 0.5,
     onDragOffset: (offset) => {
@@ -2399,6 +2437,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, {}) });
   }
@@ -2435,12 +2482,18 @@ function ReelsFeed({
                     to { transform: rotate(360deg); }
                 }
             ` }),
-        items.map((item, index) => {
+        windowedItems.map(({ item, index }) => {
           const distFromFocus = Math.abs(index - focusedIndex);
           const wrapperStyle = {
             position: "absolute",
             inset: 0,
-            contain: "layout style paint",
+            // Fix 4: 'strict' = layout + style + paint + size containment.
+            // Tells browser this slot is fully self-contained — no layout
+            // escapes to parent. Eliminates layout thrash during animation.
+            contain: "strict",
+            // Fix 4: willChange only on active ±1 (3 slots max).
+            // Previously ±1 already, keep it. Avoids unnecessary GPU layers
+            // on warm/cold slots that are never animated directly.
             willChange: distFromFocus <= 1 ? "transform" : "auto",
             transform: getInitialTransformPx(index)
           };
@@ -2470,6 +2523,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.18",
+  "version": "0.1.20",
   "description": "High-performance Short Video / Reels SDK for React — optimized for Flutter WebView",
   "license": "MIT",
   "type": "module",