@f8team/reel-core 1.0.1 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @f8team/reel-core
 
+## 1.0.4
+
+### Patch Changes
+
+- b476560: Harden HLS playback against repeated fragment request storms by bounding HLS load retries, detecting looped fragment loads, aborting stuck loaders, and surfacing retryable player errors instead of leaving playback stuck in loading.
+
+## 1.0.3
+
+### Patch Changes
+
+- Stabilize YouTube playback state by preventing hidden native media timeupdate events from overriding the YouTube clock.
+
 ## 1.0.1
 
 ### Patch Changes
@@ -18,46 +30,46 @@
   publishable as OSS.
 
   ## Public API additions (minor)
-  - **`@f8team/reel-core`** — `Player.retry(): boolean` re-attempts the last
+  - **`@f8team/reel-core`** - `Player.retry(): boolean` re-attempts the last
     source. Returns `false` when there is nothing to retry. Useful for
     "Try again" buttons on error overlays.
-  - **`@f8team/reel-core`** — `SourceLoader.abort?()` (optional) lets the
+  - **`@f8team/reel-core`** - `SourceLoader.abort?()` (optional) lets the
     orchestrator cancel in-flight network work on rapid `setSource` swaps
     without tearing down the underlying media element. Both built-in HLS and
     YouTube loaders implement it.
-  - **`@f8team/reel-react`** — `<Player.Root labels>` prop + `defaultLabels` /
+  - **`@f8team/reel-react`** - `<Player.Root labels>` prop + `defaultLabels` /
     `vietnameseLabels` presets + `useLabels()` hook for ARIA / time-formatter
     i18n.
-  - **`@f8team/reel-plugin-resume-position`** — `keyFn(source) => string | null`
+  - **`@f8team/reel-plugin-resume-position`** - `keyFn(source) => string | null`
     (signed-URL-friendly), `saveIntervalMs` (default 10s, periodic save while
     playing).
-  - **`@f8team/reel-plugin-auth-aware`** — `allowlist` now accepts
+  - **`@f8team/reel-plugin-auth-aware`** - `allowlist` now accepts
     `string | RegExp | (url: string) => boolean` per entry; new
     `AuthAwareAllowlistEntry` exported type.
-  - **`@f8team/reel-themes`** — `f8-brand.css` opt-in layer for F8 orange
+  - **`@f8team/reel-themes`** - `f8-brand.css` opt-in layer for F8 orange
     branding on top of any base theme.
 
   ## Production robustness (patch + minor)
-  - **HLS** — listener-leak fix on per-segment XHRs; manifest-load timeout
+  - **HLS** - listener-leak fix on per-segment XHRs; manifest-load timeout
     (default 30s) so a stalled manifest doesn't pin the player in `loading`;
     non-fatal HTTP 4xx/5xx now surface as load errors; native fallback path
     cleans up listeners on early `detach()`.
-  - **YouTube** — bridges polled `getCurrentTime` / `getDuration` into the
+  - **YouTube** - bridges polled `getCurrentTime` / `getDuration` into the
     core store and event bus (seek bars and time-aware plugins now tick on
     YouTube sources); marks the underlying `<video>` via the
     `data-reel-yt-hidden` attribute instead of mutating inline styles
     (host CSS no longer fights the loader); warns once when the player's
     parent is `position: static`.
-  - **createPlayer** — autoplay / startTime no longer leak listeners across
+  - **createPlayer** - autoplay / startTime no longer leak listeners across
     re-attach cycles, and re-attach to an already-`ready` player now applies
     them synchronously instead of waiting for a transition that already fired.
-  - **plugin-keyboard** — fixes container-scope fallback; skips `contenteditable`
+  - **plugin-keyboard** - fixes container-scope fallback; skips `contenteditable`
     regions, `role="textbox"`, and IME composition (no more accidental Space
     toggles while typing in a rich-text editor).
-  - **plugin-resume-position** — SSR-safe (no-op when `window` is undefined);
+  - **plugin-resume-position** - SSR-safe (no-op when `window` is undefined);
     also saves on `pagehide` / `visibilitychange→hidden` for iOS Safari, plus
     periodic save while playing.
-  - **plugin-auth-aware** — emits a one-time console warning when a string
+  - **plugin-auth-aware** - emits a one-time console warning when a string
     allowlist entry ends with `.`, to surface a class of consumer mistakes
     (`"https://api-gateway."` literal vs `/^https:\/\/api-gateway\./` regex).
 

package/dist/index.cjs

@@ -7,6 +7,7 @@ var RETRYABLE_BY_DEFAULT = {
   decode: false,
   unauthorized: false,
   unsupported: false,
+  "hls-fragment-loop": true,
   internal: false
 };
 function createPlayerError(input) {
@@ -113,16 +114,16 @@ function createPluginBus({ player, host }) {
     if (findIndex(plugin.name) >= 0) {
       throw new Error(`[@f8team/reel-core] plugin "${plugin.name}" is already registered`);
     }
-    let teardown = null;
+    let setupResult;
     try {
-      const result = plugin.setup(player, host);
-      teardown = typeof result === "function" ? result : null;
+      setupResult = plugin.setup(player, host);
     } catch (err) {
       throw new Error(
         `[@f8team/reel-core] plugin "${plugin.name}" setup threw: ${err.message}`,
         { cause: err }
       );
     }
+    const teardown = typeof setupResult === "function" ? setupResult : null;
     entries.push({ plugin, teardown });
   }
   function unregister(name) {
@@ -266,6 +267,54 @@ function resolveWithCredentials(policy, url) {
 }
 
 // src/sources/hls.ts
+var REPEATED_FRAGMENT_LOAD_LIMIT = 4;
+var MEDIA_RECOVERY_LIMIT = 1;
+function makeLoadPolicy(options) {
+  return {
+    default: {
+      maxTimeToFirstByteMs: options.maxTimeToFirstByteMs,
+      maxLoadTimeMs: options.maxLoadTimeMs,
+      timeoutRetry: options.timeoutRetry,
+      errorRetry: options.errorRetry
+    }
+  };
+}
+function makeLinearRetry(maxNumRetry, retryDelayMs, maxRetryDelayMs) {
+  return {
+    maxNumRetry,
+    retryDelayMs,
+    maxRetryDelayMs,
+    backoff: "linear"
+  };
+}
+function makeHlsLoadPolicies() {
+  return {
+    manifestLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(1, 1e3, 8e3)
+    }),
+    playlistLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(2, 1e3, 8e3)
+    }),
+    keyLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 8e3,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 1e3, 8e3),
+      errorRetry: makeLinearRetry(2, 1e3, 8e3)
+    }),
+    fragLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 3e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(2, 1e3, 4e3)
+    })
+  };
+}
 var defaultLoad = () => {
   return import('hls.js').then((m) => m.default);
 };
@@ -290,13 +339,17 @@ var HlsLoader = class {
     this.rejectAttach = null;
     this.manifestTimeout = null;
     this.aborted = false;
+    this.lastLoadingFragmentKey = null;
+    this.repeatedFragmentLoadCount = 0;
+    this.repeatedFragmentErrorFired = false;
+    this.mediaRecoveryCount = 0;
     /** `false` idle; `'auto'` → first `LEVEL_SWITCHED` clears; otherwise await this level index. */
     this.qualityAwait = false;
     this.qualitySwitchTimer = null;
     /** Tracks consecutive menu selections so redundant "Auto → Auto" skips the spinner. */
     this.lastChosenQualityWasAuto = false;
     /**
-     * `null` — user chose ABR auto (menu shows "Auto"). Real hls.js still exposes
+     * `null` - user chose ABR auto (menu shows "Auto"). Real hls.js still exposes
      * `currentLevel >= 0` for the playing rendition; we must not mirror that into UI state.
      */
     this.manualLevelIndex = null;
@@ -352,6 +405,7 @@ var HlsLoader = class {
   attachWithHlsJs(Hls, video, source) {
     const hls = new Hls({
       enableWorker: true,
+      ...makeHlsLoadPolicies(),
       xhrSetup: (xhr, url) => this.installXhrWatcher(xhr, url, source)
     });
     this.hls = hls;
@@ -372,27 +426,44 @@ var HlsLoader = class {
         this.onLevelEventuallyStabilized(...args);
         this.refreshActiveQuality();
       };
+      const onFragmentLoading = (...args) => {
+        this.onFragmentLoading(...args);
+      };
+      const onFragmentBuffered = (...args) => {
+        this.resetFragmentLoopGuardFromEvent(...args);
+      };
       const onError = (..._args) => {
-        const data = _args[1] ?? {};
+        const data = this.getHlsEventData(_args);
         const status = data.response?.code;
+        if (this.tryRecoverMediaError(Hls, data)) {
+          return;
+        }
         const isHttpError = typeof status === "number" && status >= 400;
-        if (data.fatal || isHttpError) {
-          const message = data.fatal ? `HLS fatal error: ${data.type ?? "unknown"}` : `HLS load error: HTTP ${status}`;
+        const isTerminalHlsError = this.isTerminalHlsError(data);
+        if (data.fatal || isHttpError || isTerminalHlsError) {
+          const message = this.formatHlsErrorMessage(data, status);
+          this.stopHlsLoading();
           this.options.onError?.({
+            code: this.getHlsErrorCode(data, status),
             message,
             cause: data,
             status,
-            url: data.response?.url ?? data.url
+            url: this.getErrorUrl(data),
+            retryable: this.isRetryableHlsError(data, status)
           });
           settle(() => reject(new Error(message)));
         }
       };
       hls.on(Hls.Events.MANIFEST_PARSED, onParsed);
       hls.on(Hls.Events.LEVEL_SWITCHED, onSwitched);
+      hls.on(Hls.Events.FRAG_LOADING, onFragmentLoading);
+      hls.on(Hls.Events.FRAG_BUFFERED, onFragmentBuffered);
       hls.on(Hls.Events.ERROR, onError);
       this.detachListeners.push(
         () => hls.off(Hls.Events.MANIFEST_PARSED, onParsed),
         () => hls.off(Hls.Events.LEVEL_SWITCHED, onSwitched),
+        () => hls.off(Hls.Events.FRAG_LOADING, onFragmentLoading),
+        () => hls.off(Hls.Events.FRAG_BUFFERED, onFragmentBuffered),
         () => hls.off(Hls.Events.ERROR, onError),
         () => settle(() => reject(makeAbortError()))
       );
@@ -400,6 +471,7 @@ var HlsLoader = class {
       if (timeoutMs > 0) {
         this.manifestTimeout = setTimeout(() => {
           const message = `HLS manifest timeout after ${timeoutMs}ms`;
+          this.stopHlsLoading();
           this.options.onError?.({ message, cause: { type: "timeout" }, url: source.src });
           settle(() => reject(new Error(message)));
         }, timeoutMs);
@@ -414,7 +486,7 @@ var HlsLoader = class {
   }
   /**
    * Wire the readystatechange watcher and remove it as soon as the XHR
-   * completes — without this cleanup hls.js (which spawns one XHR per segment)
+   * completes - without this cleanup hls.js (which spawns one XHR per segment)
    * leaks a closure per request (A1).
    */
   installXhrWatcher(xhr, url, source) {
@@ -440,10 +512,149 @@ var HlsLoader = class {
     };
     xhr.addEventListener("readystatechange", watcher);
   }
-  abort() {
-    if (this.aborted) return;
-    this.aborted = true;
-    this.clearManifestTimeout();
+  getHlsEventData(args) {
+    const data = args[1] ?? args[0];
+    return data !== null && typeof data === "object" ? data : {};
+  }
+  getFragmentUrl(data) {
+    return data.frag?.url ?? data.frag?.relurl ?? data.response?.url ?? data.url;
+  }
+  getErrorUrl(data) {
+    return this.getFragmentUrl(data) ?? this.currentSource?.src;
+  }
+  getFragmentKey(data) {
+    const url = this.getFragmentUrl(data);
+    const frag = data.frag;
+    if (!frag) return url ?? null;
+    const type = frag.type ?? "main";
+    const level = frag.level ?? "unknown-level";
+    const sn = frag.sn ?? "unknown-sn";
+    const cc = frag.cc ?? "unknown-cc";
+    const start = frag.start ?? frag.startPTS ?? "unknown-start";
+    return `${url ?? "unknown-url"}:${type}:${level}:${sn}:${cc}:${start}`;
+  }
+  isTerminalHlsError(data) {
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelEmptyError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+      case "keyLoadError":
+      case "keyLoadTimeOut":
+      case "bufferFullError":
+        return true;
+      default:
+        return false;
+    }
+  }
+  formatHlsErrorMessage(data, status) {
+    if (data.fatal) {
+      const type2 = data.type ?? "unknown";
+      const details2 = data.details ? ` (${data.details})` : "";
+      return `HLS fatal error: ${type2}${details2}`;
+    }
+    if (typeof status === "number" && status >= 400) {
+      return `HLS load error: HTTP ${status}${data.details ? ` (${data.details})` : ""}`;
+    }
+    const type = data.type ?? "unknown";
+    const details = data.details ? ` (${data.details})` : "";
+    return `HLS error: ${type}${details}`;
+  }
+  getHlsErrorCode(data, status) {
+    if (status === 401 || status === 403) return "unauthorized";
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+        return "decode";
+      default:
+        return "network";
+    }
+  }
+  isRetryableHlsError(data, status) {
+    if (status === 401 || status === 403) return false;
+    if (typeof status === "number" && status >= 400 && status < 500) return false;
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+        return false;
+      default:
+        return true;
+    }
+  }
+  isRecoverableMediaError(Hls, data) {
+    if (data.type !== Hls.ErrorTypes.MEDIA_ERROR && data.type !== "mediaError") {
+      return false;
+    }
+    if (!data.fatal) return false;
+    if (this.mediaRecoveryCount >= MEDIA_RECOVERY_LIMIT) return false;
+    if (typeof this.hls?.recoverMediaError !== "function") return false;
+    switch (data.details) {
+      case void 0:
+      case "bufferAppendError":
+      case "bufferAppendingError":
+      case "bufferStalledError":
+      case "bufferSeekOverHole":
+      case "bufferNudgeOnStall":
+      case "bufferFullError":
+        return true;
+      default:
+        return false;
+    }
+  }
+  tryRecoverMediaError(Hls, data) {
+    if (!this.isRecoverableMediaError(Hls, data)) return false;
+    this.mediaRecoveryCount += 1;
+    this.resetFragmentLoopGuard();
+    this.completeQualityAwaitIfBusy();
+    try {
+      this.hls?.recoverMediaError?.();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  onFragmentLoading(...args) {
+    if (this.repeatedFragmentErrorFired) return;
+    const data = this.getHlsEventData(args);
+    const key = this.getFragmentKey(data);
+    if (!key) return;
+    if (key === this.lastLoadingFragmentKey) {
+      this.repeatedFragmentLoadCount += 1;
+    } else {
+      this.lastLoadingFragmentKey = key;
+      this.repeatedFragmentLoadCount = 1;
+    }
+    if (this.repeatedFragmentLoadCount < REPEATED_FRAGMENT_LOAD_LIMIT) return;
+    this.repeatedFragmentErrorFired = true;
+    this.stopHlsLoading();
+    const url = this.getFragmentUrl(data);
+    this.options.onError?.({
+      code: "hls-fragment-loop",
+      message: `HLS fragment repeatedly loading: ${url ?? key}`,
+      cause: data,
+      url
+    });
+  }
+  resetFragmentLoopGuardFromEvent(...args) {
+    const data = this.getHlsEventData(args);
+    if (this.getFragmentKey(data)) {
+      this.resetFragmentLoopGuard();
+    }
+  }
+  resetFragmentLoopGuard() {
+    this.lastLoadingFragmentKey = null;
+    this.repeatedFragmentLoadCount = 0;
+    this.repeatedFragmentErrorFired = false;
+  }
+  abortLiveXhrs() {
     for (const xhr of [...this.liveXhrs]) {
       try {
         xhr.abort();
@@ -451,6 +662,20 @@ var HlsLoader = class {
       }
     }
     this.liveXhrs.clear();
+  }
+  stopHlsLoading() {
+    this.completeQualityAwaitIfBusy();
+    try {
+      this.hls?.stopLoad?.();
+    } catch {
+    }
+    this.abortLiveXhrs();
+  }
+  abort() {
+    if (this.aborted) return;
+    this.aborted = true;
+    this.clearManifestTimeout();
+    this.abortLiveXhrs();
     const reject = this.rejectAttach;
     this.rejectAttach = null;
     reject?.(makeAbortError());
@@ -486,6 +711,8 @@ var HlsLoader = class {
     this.aborted = false;
     this.lastChosenQualityWasAuto = false;
     this.manualLevelIndex = null;
+    this.mediaRecoveryCount = 0;
+    this.resetFragmentLoopGuard();
   }
   clearQualitySwitchTimerOnly() {
     if (this.qualitySwitchTimer !== null) {
@@ -607,7 +834,7 @@ var HlsLoader = class {
     const locked = this.qualities[this.manualLevelIndex] ?? null;
     this.options.onActiveQuality?.(locked, false);
   }
-  /** @internal — for tests. */
+  /** @internal - for tests. */
   _getInternalState() {
     return { source: this.currentSource, qualities: this.qualities };
   }
@@ -1210,6 +1437,10 @@ function createPlayer(options = {}, internal = {}) {
   let disposed = false;
   let initialOptionsApplied = false;
   let pendingPlay = false;
+  const YT_PLAYER_STATE_PLAYING = 1;
+  function getYouTubePlayer() {
+    return activeLoader?._instance?.() ?? null;
+  }
   const registry = createSourceRegistry();
   function emitUnauthorized(payload) {
     bus.emit("unauthorized", payload);
@@ -1244,7 +1475,14 @@ function createPlayer(options = {}, internal = {}) {
       onUnauthorized: (e) => emitUnauthorized(e),
       onQualities: (q) => setQualities(q),
       onActiveQuality: (q, auto) => setActiveQuality(q, auto),
-      onError: (err) => applyError(createPlayerError({ ...err, code: "network" })),
+      onError: (err) => {
+        const playerError = createPlayerError({ ...err, code: err.code ?? "network" });
+        if (status === "loading") {
+          dispatch({ type: "loadFailed", error: playerError });
+          return;
+        }
+        dispatch({ type: "runtimeError", error: playerError });
+      },
       onQualitySwitch: (active) => bus.emit("qualityswitch", { active })
     })
   );
@@ -1263,6 +1501,20 @@ function createPlayer(options = {}, internal = {}) {
       onDuration: (duration) => {
         store.setState({ duration });
         bus.emit("durationchange", { duration });
+      },
+      onStateChange: (ytState) => {
+        if (ytState === "playing") {
+          bus.emit("play");
+          if (status !== "playing" && status !== "loading") dispatch({ type: "play" });
+        } else if (ytState === "paused") {
+          bus.emit("pause");
+          if (status === "playing") dispatch({ type: "pause" });
+        } else if (ytState === "ended") {
+          bus.emit("ended");
+          if (status !== "ended") dispatch({ type: "ended" });
+        } else if (ytState === "buffering") {
+          bus.emit("buffering", { isBuffering: true });
+        }
       }
     })
   );
@@ -1388,6 +1640,14 @@ function createPlayer(options = {}, internal = {}) {
   }
   function runMediaPlay() {
     if (!video) return;
+    const yt = getYouTubePlayer();
+    if (yt) {
+      try {
+        yt.playVideo();
+      } catch {
+      }
+      return;
+    }
     const result = video.play();
     if (result && typeof result.then === "function") {
       result.catch((err) => {
@@ -1400,6 +1660,14 @@ function createPlayer(options = {}, internal = {}) {
   }
   function runMediaPause() {
     if (!video) return;
+    const yt = getYouTubePlayer();
+    if (yt) {
+      try {
+        yt.pauseVideo();
+      } catch {
+      }
+      return;
+    }
     try {
       video.pause();
     } catch {
@@ -1407,6 +1675,20 @@ function createPlayer(options = {}, internal = {}) {
   }
   function runMediaSeek(seconds) {
     if (!video) return;
+    const yt = getYouTubePlayer();
+    if (yt) {
+      try {
+        yt.seekTo(seconds, true);
+        store.setState({ currentTime: seconds });
+        bus.emit("timeupdate", {
+          currentTime: seconds,
+          playedSeconds: seconds,
+          duration: store.getState().duration
+        });
+      } catch {
+      }
+      return;
+    }
     try {
       video.currentTime = seconds;
     } catch {
@@ -1436,6 +1718,7 @@ function createPlayer(options = {}, internal = {}) {
       bus.emit("durationchange", { duration });
     });
     on2("timeupdate", () => {
+      if (getYouTubePlayer()) return;
       const currentTime = target.currentTime;
       store.setState({ currentTime, buffered: bufferedToRanges(target.buffered) });
       bus.emit("timeupdate", {
@@ -1652,6 +1935,14 @@ function createPlayer(options = {}, internal = {}) {
   }
   function paused() {
     if (!video) return true;
+    const yt = getYouTubePlayer();
+    if (yt) {
+      try {
+        return yt.getPlayerState() !== YT_PLAYER_STATE_PLAYING;
+      } catch {
+        return true;
+      }
+    }
     return video.paused;
   }
   function seekTo(seconds) {
@@ -1659,6 +1950,20 @@ function createPlayer(options = {}, internal = {}) {
     if (!video) return;
     const duration = Number.isFinite(video.duration) ? video.duration : Number.POSITIVE_INFINITY;
     const clamped = Math.max(0, Math.min(seconds, duration));
+    const yt = getYouTubePlayer();
+    if (yt) {
+      try {
+        yt.seekTo(clamped, true);
+        store.setState({ currentTime: clamped });
+        bus.emit("timeupdate", {
+          currentTime: clamped,
+          playedSeconds: clamped,
+          duration: store.getState().duration
+        });
+      } catch {
+      }
+      return;
+    }
     video.currentTime = clamped;
   }
   function syncVolumeMutedStoreFromVideo() {