@f8team/reel-core 1.0.3 → 1.0.4

package/dist/index.d.cts

@@ -58,7 +58,7 @@ interface CreateStoreOptions<_T> {
  * Golden cases: G13 (unauthorized HLS), every error path in G1..G16.
  */
 /** Stable error codes. The string literal IS the public contract. */
-type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "internal";
+type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "hls-fragment-loop" | "internal";
 /**
  * Structured player error. Adapters render the message; plugins can inspect
  * `code`, `status`, and `retryable` to decide on retry/UI strategy.
@@ -639,7 +639,7 @@ interface PlayerOptions {
 }
 
 /**
- * `createPlayer(options)` — wires every piece of `@f8team/reel-core` into a
+ * `createPlayer(options)` - wires every piece of `@f8team/reel-core` into a
  * single `Player`. The factory is the one and only public entry point.
  *
  * Responsibilities:
@@ -658,7 +658,7 @@ interface PlayerOptions {
  * unit tests.
  */
 
-/** @internal — extra knobs surfaced for tests and adapters. */
+/** @internal - extra knobs surfaced for tests and adapters. */
 interface CreatePlayerInternalOptions {
     /** Override the microtask scheduler for the store. Tests use this. */
     storeOptions?: CreateStoreOptions<PlayerState>;

package/dist/index.d.ts

@@ -58,7 +58,7 @@ interface CreateStoreOptions<_T> {
  * Golden cases: G13 (unauthorized HLS), every error path in G1..G16.
  */
 /** Stable error codes. The string literal IS the public contract. */
-type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "internal";
+type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "hls-fragment-loop" | "internal";
 /**
  * Structured player error. Adapters render the message; plugins can inspect
  * `code`, `status`, and `retryable` to decide on retry/UI strategy.
@@ -639,7 +639,7 @@ interface PlayerOptions {
 }
 
 /**
- * `createPlayer(options)` — wires every piece of `@f8team/reel-core` into a
+ * `createPlayer(options)` - wires every piece of `@f8team/reel-core` into a
  * single `Player`. The factory is the one and only public entry point.
  *
  * Responsibilities:
@@ -658,7 +658,7 @@ interface PlayerOptions {
  * unit tests.
  */
 
-/** @internal — extra knobs surfaced for tests and adapters. */
+/** @internal - extra knobs surfaced for tests and adapters. */
 interface CreatePlayerInternalOptions {
     /** Override the microtask scheduler for the store. Tests use this. */
     storeOptions?: CreateStoreOptions<PlayerState>;

package/dist/index.js

@@ -5,6 +5,7 @@ var RETRYABLE_BY_DEFAULT = {
   decode: false,
   unauthorized: false,
   unsupported: false,
+  "hls-fragment-loop": true,
   internal: false
 };
 function createPlayerError(input) {
@@ -264,6 +265,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);
 };
@@ -288,13 +337,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;
@@ -350,6 +403,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;
@@ -370,27 +424,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()))
       );
@@ -398,6 +469,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);
@@ -412,7 +484,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) {
@@ -438,10 +510,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();
@@ -449,6 +660,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());
@@ -484,6 +709,8 @@ var HlsLoader = class {
     this.aborted = false;
     this.lastChosenQualityWasAuto = false;
     this.manualLevelIndex = null;
+    this.mediaRecoveryCount = 0;
+    this.resetFragmentLoopGuard();
   }
   clearQualitySwitchTimerOnly() {
     if (this.qualitySwitchTimer !== null) {
@@ -605,7 +832,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 };
   }
@@ -1246,7 +1473,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 })
     })
   );