@scarlett-player/hls 1.6.0 → 1.8.0

package/README.md

@@ -11,16 +11,14 @@ npm install @scarlett-player/core @scarlett-player/hls
 ## Usage
 
 ```typescript
-import { ScarlettPlayer } from '@scarlett-player/core';
+import { createPlayer } from '@scarlett-player/core';
 import { createHLSPlugin } from '@scarlett-player/hls';
 
-const player = new ScarlettPlayer({
+const player = await createPlayer({
   container: document.getElementById('player'),
+  src: 'https://example.com/video.m3u8',
   plugins: [createHLSPlugin()],
 });
-
-await player.init();
-await player.load('https://example.com/video.m3u8');
 ```
 
 ## Features

package/dist/{chunk-IFUZZQQE.js → chunk-FN6QUW42.js}

@@ -4,6 +4,17 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/sanitize-url.ts
+function sanitizeUrl(url) {
+  if (!url) return void 0;
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/create-hls-plugin.ts
 import { ErrorCode } from "@scarlett-player/core";
 
@@ -211,8 +222,14 @@ function setupVideoEventHandlers(video, api) {
     video.addEventListener(event, handler);
     handlers.push({ event, handler });
   };
+  const syncEndedFromElement = () => {
+    if (video.ended || !api.getState("ended")) return;
+    api.setState("ended", false);
+    api.setState("playbackState", video.paused ? "paused" : "playing");
+  };
   addHandler("play", () => {
     api.setState("paused", false);
+    syncEndedFromElement();
   });
   addHandler("playing", () => {
     api.setState("playing", true);
@@ -220,6 +237,7 @@ function setupVideoEventHandlers(video, api) {
     api.setState("waiting", false);
     api.setState("buffering", false);
     api.setState("playbackState", "playing");
+    syncEndedFromElement();
   });
   addHandler("pause", () => {
     api.setState("playing", false);
@@ -274,6 +292,7 @@ function setupVideoEventHandlers(video, api) {
   });
   addHandler("seeking", () => {
     api.setState("seeking", true);
+    syncEndedFromElement();
   });
   addHandler("seeked", () => {
     api.setState("seeking", false);
@@ -381,6 +400,9 @@ function createValidatingPlaylistLoader(Hls) {
   };
 }
 
+// src/version.ts
+var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+
 // src/create-hls-plugin.ts
 var DEFAULT_CONFIG = {
   debug: false,
@@ -437,6 +459,12 @@ function createHLSPluginWith(loader, variant, config) {
   let reconnectWindowStart = 0;
   let reconnectResumePosition = 0;
   let onlineListener = null;
+  let reconnectTriggerError = null;
+  let reconnectExhausted = false;
+  const applyPoster = () => {
+    if (!video) return;
+    video.poster = api?.getState("poster") || "";
+  };
   const getOrCreateVideo = () => {
     if (video) return video;
     const existing = api?.container.querySelector("video");
@@ -449,10 +477,7 @@ function createHLSPluginWith(loader, variant, config) {
     video.preload = "metadata";
     video.controls = false;
     video.playsInline = true;
-    const poster = api?.getState("poster");
-    if (poster) {
-      video.poster = poster;
-    }
+    applyPoster();
     api?.container.appendChild(video);
     return video;
   };
@@ -545,6 +570,22 @@ function createHLSPluginWith(loader, variant, config) {
         return ErrorCode.PLAYBACK_FAILED;
     }
   };
+  const buildErrorDetail = (error, retriesExhausted) => {
+    const attempts = error.type === "network" ? networkRetryCount : error.type === "media" ? mediaRetryCount : 0;
+    const detail = {
+      type: error.type,
+      retriesExhausted,
+      attempts
+    };
+    if (typeof error.response?.code === "number" && error.response.code > 0) {
+      detail.httpStatus = error.response.code;
+    }
+    const url = sanitizeUrl(error.url);
+    if (url) {
+      detail.url = url;
+    }
+    return detail;
+  };
   const emitFatalError = (error, retriesExhausted) => {
     const message = retriesExhausted ? `HLS error: ${error.details} (max retries exceeded)` : `HLS error: ${error.details}`;
     api?.logger.error(message, { type: error.type, details: error.details });
@@ -554,7 +595,8 @@ function createHLSPluginWith(loader, variant, config) {
       code: mapFatalErrorCode(error),
       message,
       fatal: true,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      detail: buildErrorDetail(error, retriesExhausted)
     });
     maybeScheduleReconnect(error);
   };
@@ -631,6 +673,62 @@ function createHLSPluginWith(loader, variant, config) {
     }
     return false;
   };
+  const handleNativeFatalError = (error, resumePosition) => {
+    const is_network = error.type === "network";
+    const max_retries = is_network ? mergedConfig.maxNetworkRetries ?? 3 : mergedConfig.maxMediaRetries ?? 2;
+    const used = is_network ? networkRetryCount : mediaRetryCount;
+    if (!currentSrc || used >= max_retries) {
+      emitFatalError(error, used >= max_retries);
+      return;
+    }
+    const resume_position = resumePosition ?? video?.currentTime ?? 0;
+    if (is_network) {
+      networkRetryCount++;
+    } else {
+      mediaRetryCount++;
+    }
+    const attempt = used + 1;
+    const delay = getRetryDelay(attempt - 1);
+    api?.logger.info(
+      `Attempting native ${error.type} error recovery (attempt ${attempt}/${max_retries}) in ${delay}ms`
+    );
+    api?.emit(is_network ? "error:network" : "error:media", {
+      error: new Error(error.details)
+    });
+    if (retryTimeout) {
+      clearTimeout(retryTimeout);
+    }
+    const retry_session = loadSession;
+    retryTimeout = setTimeout(() => {
+      if (retry_session !== loadSession) return;
+      void recoverNative(error, resume_position);
+    }, delay);
+  };
+  const recoverNative = async (error, resumePosition) => {
+    if (!currentSrc) return;
+    const session = ++loadSession;
+    const saved_src = currentSrc;
+    const was_live = api?.getState("live") ?? false;
+    try {
+      teardownPipeline(new Error("HLS load cancelled: native error recovery"));
+      api?.setState("playbackState", "loading");
+      await loadNative(saved_src);
+      if (session !== loadSession) return;
+      if (!was_live && video && resumePosition > 0) {
+        video.currentTime = resumePosition;
+      }
+      api?.setState("playbackState", "ready");
+      api?.setState("buffering", false);
+      try {
+        await video?.play();
+      } catch {
+      }
+    } catch {
+      if (session !== loadSession) return;
+      api?.logger.warn("Native error recovery attempt failed");
+      handleNativeFatalError(error, resumePosition);
+    }
+  };
   const loadNative = async (src) => {
     const session = loadSession;
     const videoEl = getOrCreateVideo();
@@ -675,10 +773,21 @@ function createHLSPluginWith(loader, variant, config) {
             details: media_error?.message || "Native HLS playback error",
             fatal: true
           };
-          emitFatalError(hls_error, false);
+          handleNativeFatalError(hls_error);
         };
         videoEl.addEventListener("error", onFatalVideoError);
-        const removeFatalListener = () => videoEl.removeEventListener("error", onFatalVideoError);
+        const onPlayingResetBudget = () => {
+          if (networkRetryCount > 0 || mediaRetryCount > 0) {
+            api?.logger.debug("Native playback recovered, resetting retry budgets");
+            networkRetryCount = 0;
+            mediaRetryCount = 0;
+          }
+        };
+        videoEl.addEventListener("playing", onPlayingResetBudget);
+        const removeFatalListener = () => {
+          videoEl.removeEventListener("error", onFatalVideoError);
+          videoEl.removeEventListener("playing", onPlayingResetBudget);
+        };
         const previous_cleanup = cleanupVideoEvents;
         cleanupVideoEvents = () => {
           removeFatalListener();
@@ -803,12 +912,38 @@ function createHLSPluginWith(loader, variant, config) {
     reconnectAttempts = 0;
     reconnectWindowStart = 0;
     reconnectResumePosition = 0;
+    reconnectTriggerError = null;
+    reconnectExhausted = false;
+  };
+  const emitReconnectExhausted = (elapsedMs, windowMs) => {
+    if (reconnectExhausted) return;
+    reconnectExhausted = true;
+    const attempts = reconnectAttempts;
+    const trigger = reconnectTriggerError;
+    api?.emit("error:reconnect-exhausted", { attempts, elapsedMs, windowMs });
+    api?.setState("playbackState", "error");
+    api?.setState("buffering", false);
+    api?.emit("error", {
+      code: trigger ? mapFatalErrorCode(trigger) : ErrorCode.PLAYBACK_FAILED,
+      message: `HLS auto-reconnect gave up after ${attempts} attempts over ${Math.round(elapsedMs / 1e3)}s`,
+      fatal: true,
+      timestamp: Date.now(),
+      detail: {
+        type: trigger?.type ?? "other",
+        retriesExhausted: true,
+        attempts,
+        reconnectExhausted: true
+      }
+    });
   };
   const scheduleReconnectAttempt = () => {
+    if (reconnectExhausted) return;
     if (reconnectTimer) return;
     const window_ms = mergedConfig.reconnectWindowMs ?? 3e5;
-    if (Date.now() - reconnectWindowStart > window_ms) {
+    const elapsed_ms = Date.now() - reconnectWindowStart;
+    if (elapsed_ms > window_ms) {
       api?.logger.warn(`Auto-reconnect window exhausted after ${reconnectAttempts} attempts`);
+      emitReconnectExhausted(elapsed_ms, window_ms);
       return;
     }
     const base_delay = mergedConfig.reconnectBaseDelayMs ?? 2e3;
@@ -816,7 +951,12 @@ function createHLSPluginWith(loader, variant, config) {
     const backoff = Math.min(base_delay * Math.pow(2, reconnectAttempts), max_delay);
     const delay = Math.round(backoff * (0.7 + Math.random() * 0.3));
     api?.logger.info(`Scheduling auto-reconnect attempt ${reconnectAttempts + 1} in ${delay}ms`);
-    api?.emit("error:reconnecting", { attempt: reconnectAttempts + 1, delayMs: delay });
+    api?.emit("error:reconnecting", {
+      attempt: reconnectAttempts + 1,
+      delayMs: delay,
+      elapsedMs: elapsed_ms,
+      windowMs: window_ms
+    });
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       void attemptReconnect();
@@ -829,6 +969,7 @@ function createHLSPluginWith(loader, variant, config) {
     if (reconnectWindowStart === 0) {
       reconnectWindowStart = Date.now();
       reconnectResumePosition = video?.currentTime ?? 0;
+      reconnectTriggerError = error;
     }
     scheduleReconnectAttempt();
   };
@@ -860,7 +1001,10 @@ function createHLSPluginWith(loader, variant, config) {
       }
       api.setState("playbackState", "ready");
       api.setState("buffering", false);
-      api.emit("error:recovered", void 0);
+      api.emit("error:recovered", {
+        attempt: reconnectAttempts,
+        elapsedMs: Date.now() - reconnectWindowStart
+      });
       api.logger.info("Auto-reconnect succeeded");
       cancelReconnect();
       try {
@@ -876,7 +1020,7 @@ function createHLSPluginWith(loader, variant, config) {
   const plugin = {
     id: "hls-provider",
     name: variant.name,
-    version: "1.0.0",
+    version: PKG_VERSION,
     type: "provider",
     description: variant.description,
     canPlay(src) {
@@ -967,6 +1111,9 @@ function createHLSPluginWith(loader, variant, config) {
         };
         window.addEventListener("online", onlineListener);
       }
+      const unsubPoster = api.subscribeToState((event) => {
+        if (event.key === "poster") applyPoster();
+      });
       api.onDestroy(() => {
         unsubPlay();
         unsubPause();
@@ -975,6 +1122,7 @@ function createHLSPluginWith(loader, variant, config) {
         unsubMute();
         unsubRate();
         unsubQuality();
+        unsubPoster();
       });
     },
     async destroy() {
@@ -1000,6 +1148,7 @@ function createHLSPluginWith(loader, variant, config) {
       hasPlayedContent = false;
       cleanup(new Error("HLS load cancelled: superseded by a new load"));
       currentSrc = src;
+      applyPoster();
       api.setState("playbackState", "loading");
       api.setState("buffering", true);
       if (api.getState("airplayActive") && loader.supportsNativeHLS()) {
@@ -1137,5 +1286,6 @@ function createHLSPluginWith(loader, variant, config) {
 
 export {
   __export,
+  sanitizeUrl,
   createHLSPluginWith
 };

package/dist/index.cjs

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createHLSPlugin: () => createHLSPlugin,
-  default: () => index_default
+  default: () => index_default,
+  sanitizeUrl: () => sanitizeUrl
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -316,8 +317,14 @@ function setupVideoEventHandlers(video, api) {
     video.addEventListener(event, handler);
     handlers.push({ event, handler });
   };
+  const syncEndedFromElement = () => {
+    if (video.ended || !api.getState("ended")) return;
+    api.setState("ended", false);
+    api.setState("playbackState", video.paused ? "paused" : "playing");
+  };
   addHandler("play", () => {
     api.setState("paused", false);
+    syncEndedFromElement();
   });
   addHandler("playing", () => {
     api.setState("playing", true);
@@ -325,6 +332,7 @@ function setupVideoEventHandlers(video, api) {
     api.setState("waiting", false);
     api.setState("buffering", false);
     api.setState("playbackState", "playing");
+    syncEndedFromElement();
   });
   addHandler("pause", () => {
     api.setState("playing", false);
@@ -379,6 +387,7 @@ function setupVideoEventHandlers(video, api) {
   });
   addHandler("seeking", () => {
     api.setState("seeking", true);
+    syncEndedFromElement();
   });
   addHandler("seeked", () => {
     api.setState("seeking", false);
@@ -486,6 +495,20 @@ function createValidatingPlaylistLoader(Hls) {
   };
 }
 
+// src/sanitize-url.ts
+function sanitizeUrl(url) {
+  if (!url) return void 0;
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/version.ts
+var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+
 // src/create-hls-plugin.ts
 var DEFAULT_CONFIG = {
   debug: false,
@@ -542,6 +565,12 @@ function createHLSPluginWith(loader, variant, config) {
   let reconnectWindowStart = 0;
   let reconnectResumePosition = 0;
   let onlineListener = null;
+  let reconnectTriggerError = null;
+  let reconnectExhausted = false;
+  const applyPoster = () => {
+    if (!video) return;
+    video.poster = api?.getState("poster") || "";
+  };
   const getOrCreateVideo = () => {
     if (video) return video;
     const existing = api?.container.querySelector("video");
@@ -554,10 +583,7 @@ function createHLSPluginWith(loader, variant, config) {
     video.preload = "metadata";
     video.controls = false;
     video.playsInline = true;
-    const poster = api?.getState("poster");
-    if (poster) {
-      video.poster = poster;
-    }
+    applyPoster();
     api?.container.appendChild(video);
     return video;
   };
@@ -650,6 +676,22 @@ function createHLSPluginWith(loader, variant, config) {
         return import_core.ErrorCode.PLAYBACK_FAILED;
     }
   };
+  const buildErrorDetail = (error, retriesExhausted) => {
+    const attempts = error.type === "network" ? networkRetryCount : error.type === "media" ? mediaRetryCount : 0;
+    const detail = {
+      type: error.type,
+      retriesExhausted,
+      attempts
+    };
+    if (typeof error.response?.code === "number" && error.response.code > 0) {
+      detail.httpStatus = error.response.code;
+    }
+    const url = sanitizeUrl(error.url);
+    if (url) {
+      detail.url = url;
+    }
+    return detail;
+  };
   const emitFatalError = (error, retriesExhausted) => {
     const message = retriesExhausted ? `HLS error: ${error.details} (max retries exceeded)` : `HLS error: ${error.details}`;
     api?.logger.error(message, { type: error.type, details: error.details });
@@ -659,7 +701,8 @@ function createHLSPluginWith(loader, variant, config) {
       code: mapFatalErrorCode(error),
       message,
       fatal: true,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      detail: buildErrorDetail(error, retriesExhausted)
     });
     maybeScheduleReconnect(error);
   };
@@ -736,6 +779,62 @@ function createHLSPluginWith(loader, variant, config) {
     }
     return false;
   };
+  const handleNativeFatalError = (error, resumePosition) => {
+    const is_network = error.type === "network";
+    const max_retries = is_network ? mergedConfig.maxNetworkRetries ?? 3 : mergedConfig.maxMediaRetries ?? 2;
+    const used = is_network ? networkRetryCount : mediaRetryCount;
+    if (!currentSrc || used >= max_retries) {
+      emitFatalError(error, used >= max_retries);
+      return;
+    }
+    const resume_position = resumePosition ?? video?.currentTime ?? 0;
+    if (is_network) {
+      networkRetryCount++;
+    } else {
+      mediaRetryCount++;
+    }
+    const attempt = used + 1;
+    const delay = getRetryDelay(attempt - 1);
+    api?.logger.info(
+      `Attempting native ${error.type} error recovery (attempt ${attempt}/${max_retries}) in ${delay}ms`
+    );
+    api?.emit(is_network ? "error:network" : "error:media", {
+      error: new Error(error.details)
+    });
+    if (retryTimeout) {
+      clearTimeout(retryTimeout);
+    }
+    const retry_session = loadSession;
+    retryTimeout = setTimeout(() => {
+      if (retry_session !== loadSession) return;
+      void recoverNative(error, resume_position);
+    }, delay);
+  };
+  const recoverNative = async (error, resumePosition) => {
+    if (!currentSrc) return;
+    const session = ++loadSession;
+    const saved_src = currentSrc;
+    const was_live = api?.getState("live") ?? false;
+    try {
+      teardownPipeline(new Error("HLS load cancelled: native error recovery"));
+      api?.setState("playbackState", "loading");
+      await loadNative(saved_src);
+      if (session !== loadSession) return;
+      if (!was_live && video && resumePosition > 0) {
+        video.currentTime = resumePosition;
+      }
+      api?.setState("playbackState", "ready");
+      api?.setState("buffering", false);
+      try {
+        await video?.play();
+      } catch {
+      }
+    } catch {
+      if (session !== loadSession) return;
+      api?.logger.warn("Native error recovery attempt failed");
+      handleNativeFatalError(error, resumePosition);
+    }
+  };
   const loadNative = async (src) => {
     const session = loadSession;
     const videoEl = getOrCreateVideo();
@@ -780,10 +879,21 @@ function createHLSPluginWith(loader, variant, config) {
             details: media_error?.message || "Native HLS playback error",
             fatal: true
           };
-          emitFatalError(hls_error, false);
+          handleNativeFatalError(hls_error);
         };
         videoEl.addEventListener("error", onFatalVideoError);
-        const removeFatalListener = () => videoEl.removeEventListener("error", onFatalVideoError);
+        const onPlayingResetBudget = () => {
+          if (networkRetryCount > 0 || mediaRetryCount > 0) {
+            api?.logger.debug("Native playback recovered, resetting retry budgets");
+            networkRetryCount = 0;
+            mediaRetryCount = 0;
+          }
+        };
+        videoEl.addEventListener("playing", onPlayingResetBudget);
+        const removeFatalListener = () => {
+          videoEl.removeEventListener("error", onFatalVideoError);
+          videoEl.removeEventListener("playing", onPlayingResetBudget);
+        };
         const previous_cleanup = cleanupVideoEvents;
         cleanupVideoEvents = () => {
           removeFatalListener();
@@ -908,12 +1018,38 @@ function createHLSPluginWith(loader, variant, config) {
     reconnectAttempts = 0;
     reconnectWindowStart = 0;
     reconnectResumePosition = 0;
+    reconnectTriggerError = null;
+    reconnectExhausted = false;
+  };
+  const emitReconnectExhausted = (elapsedMs, windowMs) => {
+    if (reconnectExhausted) return;
+    reconnectExhausted = true;
+    const attempts = reconnectAttempts;
+    const trigger = reconnectTriggerError;
+    api?.emit("error:reconnect-exhausted", { attempts, elapsedMs, windowMs });
+    api?.setState("playbackState", "error");
+    api?.setState("buffering", false);
+    api?.emit("error", {
+      code: trigger ? mapFatalErrorCode(trigger) : import_core.ErrorCode.PLAYBACK_FAILED,
+      message: `HLS auto-reconnect gave up after ${attempts} attempts over ${Math.round(elapsedMs / 1e3)}s`,
+      fatal: true,
+      timestamp: Date.now(),
+      detail: {
+        type: trigger?.type ?? "other",
+        retriesExhausted: true,
+        attempts,
+        reconnectExhausted: true
+      }
+    });
   };
   const scheduleReconnectAttempt = () => {
+    if (reconnectExhausted) return;
     if (reconnectTimer) return;
     const window_ms = mergedConfig.reconnectWindowMs ?? 3e5;
-    if (Date.now() - reconnectWindowStart > window_ms) {
+    const elapsed_ms = Date.now() - reconnectWindowStart;
+    if (elapsed_ms > window_ms) {
       api?.logger.warn(`Auto-reconnect window exhausted after ${reconnectAttempts} attempts`);
+      emitReconnectExhausted(elapsed_ms, window_ms);
       return;
     }
     const base_delay = mergedConfig.reconnectBaseDelayMs ?? 2e3;
@@ -921,7 +1057,12 @@ function createHLSPluginWith(loader, variant, config) {
     const backoff = Math.min(base_delay * Math.pow(2, reconnectAttempts), max_delay);
     const delay = Math.round(backoff * (0.7 + Math.random() * 0.3));
     api?.logger.info(`Scheduling auto-reconnect attempt ${reconnectAttempts + 1} in ${delay}ms`);
-    api?.emit("error:reconnecting", { attempt: reconnectAttempts + 1, delayMs: delay });
+    api?.emit("error:reconnecting", {
+      attempt: reconnectAttempts + 1,
+      delayMs: delay,
+      elapsedMs: elapsed_ms,
+      windowMs: window_ms
+    });
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       void attemptReconnect();
@@ -934,6 +1075,7 @@ function createHLSPluginWith(loader, variant, config) {
     if (reconnectWindowStart === 0) {
       reconnectWindowStart = Date.now();
       reconnectResumePosition = video?.currentTime ?? 0;
+      reconnectTriggerError = error;
     }
     scheduleReconnectAttempt();
   };
@@ -965,7 +1107,10 @@ function createHLSPluginWith(loader, variant, config) {
       }
       api.setState("playbackState", "ready");
       api.setState("buffering", false);
-      api.emit("error:recovered", void 0);
+      api.emit("error:recovered", {
+        attempt: reconnectAttempts,
+        elapsedMs: Date.now() - reconnectWindowStart
+      });
       api.logger.info("Auto-reconnect succeeded");
       cancelReconnect();
       try {
@@ -981,7 +1126,7 @@ function createHLSPluginWith(loader, variant, config) {
   const plugin = {
     id: "hls-provider",
     name: variant.name,
-    version: "1.0.0",
+    version: PKG_VERSION,
     type: "provider",
     description: variant.description,
     canPlay(src) {
@@ -1072,6 +1217,9 @@ function createHLSPluginWith(loader, variant, config) {
         };
         window.addEventListener("online", onlineListener);
       }
+      const unsubPoster = api.subscribeToState((event) => {
+        if (event.key === "poster") applyPoster();
+      });
       api.onDestroy(() => {
         unsubPlay();
         unsubPause();
@@ -1080,6 +1228,7 @@ function createHLSPluginWith(loader, variant, config) {
         unsubMute();
         unsubRate();
         unsubQuality();
+        unsubPoster();
       });
     },
     async destroy() {
@@ -1105,6 +1254,7 @@ function createHLSPluginWith(loader, variant, config) {
       hasPlayedContent = false;
       cleanup(new Error("HLS load cancelled: superseded by a new load"));
       currentSrc = src;
+      applyPoster();
       api.setState("playbackState", "loading");
       api.setState("buffering", true);
       if (api.getState("airplayActive") && loader.supportsNativeHLS()) {
@@ -1256,5 +1406,6 @@ function createHLSPlugin(config) {
 var index_default = createHLSPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createHLSPlugin
+  createHLSPlugin,
+  sanitizeUrl
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-D-HW4lmM.cjs';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-D-HW4lmM.cjs';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './sanitize-url-DcZXD_K-.cjs';
+export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, s as sanitizeUrl } from './sanitize-url-DcZXD_K-.cjs';
 import '@scarlett-player/core';
 
 /**
@@ -20,9 +20,10 @@ import '@scarlett-player/core';
  *
  * @example
  * ```ts
+ * import { createPlayer } from '@scarlett-player/core';
  * import { createHLSPlugin } from '@scarlett-player/hls';
  *
- * const player = new ScarlettPlayer({
+ * const player = await createPlayer({
  *   container: document.getElementById('player'),
  *   plugins: [createHLSPlugin()],
  * });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-D-HW4lmM.js';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-D-HW4lmM.js';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './sanitize-url-DcZXD_K-.js';
+export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, s as sanitizeUrl } from './sanitize-url-DcZXD_K-.js';
 import '@scarlett-player/core';
 
 /**
@@ -20,9 +20,10 @@ import '@scarlett-player/core';
  *
  * @example
  * ```ts
+ * import { createPlayer } from '@scarlett-player/core';
  * import { createHLSPlugin } from '@scarlett-player/hls';
  *
- * const player = new ScarlettPlayer({
+ * const player = await createPlayer({
  *   container: document.getElementById('player'),
  *   plugins: [createHLSPlugin()],
  * });

package/dist/index.js

@@ -1,7 +1,8 @@
 import {
   __export,
-  createHLSPluginWith
-} from "./chunk-IFUZZQQE.js";
+  createHLSPluginWith,
+  sanitizeUrl
+} from "./chunk-FN6QUW42.js";
 
 // src/hls-loader.ts
 var hls_loader_exports = {};
@@ -93,5 +94,6 @@ function createHLSPlugin(config) {
 var index_default = createHLSPlugin;
 export {
   createHLSPlugin,
-  index_default as default
+  index_default as default,
+  sanitizeUrl
 };

package/dist/light.cjs

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var light_exports = {};
 __export(light_exports, {
   createHLSPlugin: () => createHLSPlugin,
-  default: () => light_default
+  default: () => light_default,
+  sanitizeUrl: () => sanitizeUrl
 });
 module.exports = __toCommonJS(light_exports);
 
@@ -316,8 +317,14 @@ function setupVideoEventHandlers(video, api) {
     video.addEventListener(event, handler);
     handlers.push({ event, handler });
   };
+  const syncEndedFromElement = () => {
+    if (video.ended || !api.getState("ended")) return;
+    api.setState("ended", false);
+    api.setState("playbackState", video.paused ? "paused" : "playing");
+  };
   addHandler("play", () => {
     api.setState("paused", false);
+    syncEndedFromElement();
   });
   addHandler("playing", () => {
     api.setState("playing", true);
@@ -325,6 +332,7 @@ function setupVideoEventHandlers(video, api) {
     api.setState("waiting", false);
     api.setState("buffering", false);
     api.setState("playbackState", "playing");
+    syncEndedFromElement();
   });
   addHandler("pause", () => {
     api.setState("playing", false);
@@ -379,6 +387,7 @@ function setupVideoEventHandlers(video, api) {
   });
   addHandler("seeking", () => {
     api.setState("seeking", true);
+    syncEndedFromElement();
   });
   addHandler("seeked", () => {
     api.setState("seeking", false);
@@ -486,6 +495,20 @@ function createValidatingPlaylistLoader(Hls) {
   };
 }
 
+// src/sanitize-url.ts
+function sanitizeUrl(url) {
+  if (!url) return void 0;
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/version.ts
+var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+
 // src/create-hls-plugin.ts
 var DEFAULT_CONFIG = {
   debug: false,
@@ -542,6 +565,12 @@ function createHLSPluginWith(loader, variant, config) {
   let reconnectWindowStart = 0;
   let reconnectResumePosition = 0;
   let onlineListener = null;
+  let reconnectTriggerError = null;
+  let reconnectExhausted = false;
+  const applyPoster = () => {
+    if (!video) return;
+    video.poster = api?.getState("poster") || "";
+  };
   const getOrCreateVideo = () => {
     if (video) return video;
     const existing = api?.container.querySelector("video");
@@ -554,10 +583,7 @@ function createHLSPluginWith(loader, variant, config) {
     video.preload = "metadata";
     video.controls = false;
     video.playsInline = true;
-    const poster = api?.getState("poster");
-    if (poster) {
-      video.poster = poster;
-    }
+    applyPoster();
     api?.container.appendChild(video);
     return video;
   };
@@ -650,6 +676,22 @@ function createHLSPluginWith(loader, variant, config) {
         return import_core.ErrorCode.PLAYBACK_FAILED;
     }
   };
+  const buildErrorDetail = (error, retriesExhausted) => {
+    const attempts = error.type === "network" ? networkRetryCount : error.type === "media" ? mediaRetryCount : 0;
+    const detail = {
+      type: error.type,
+      retriesExhausted,
+      attempts
+    };
+    if (typeof error.response?.code === "number" && error.response.code > 0) {
+      detail.httpStatus = error.response.code;
+    }
+    const url = sanitizeUrl(error.url);
+    if (url) {
+      detail.url = url;
+    }
+    return detail;
+  };
   const emitFatalError = (error, retriesExhausted) => {
     const message = retriesExhausted ? `HLS error: ${error.details} (max retries exceeded)` : `HLS error: ${error.details}`;
     api?.logger.error(message, { type: error.type, details: error.details });
@@ -659,7 +701,8 @@ function createHLSPluginWith(loader, variant, config) {
       code: mapFatalErrorCode(error),
       message,
       fatal: true,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      detail: buildErrorDetail(error, retriesExhausted)
     });
     maybeScheduleReconnect(error);
   };
@@ -736,6 +779,62 @@ function createHLSPluginWith(loader, variant, config) {
     }
     return false;
   };
+  const handleNativeFatalError = (error, resumePosition) => {
+    const is_network = error.type === "network";
+    const max_retries = is_network ? mergedConfig.maxNetworkRetries ?? 3 : mergedConfig.maxMediaRetries ?? 2;
+    const used = is_network ? networkRetryCount : mediaRetryCount;
+    if (!currentSrc || used >= max_retries) {
+      emitFatalError(error, used >= max_retries);
+      return;
+    }
+    const resume_position = resumePosition ?? video?.currentTime ?? 0;
+    if (is_network) {
+      networkRetryCount++;
+    } else {
+      mediaRetryCount++;
+    }
+    const attempt = used + 1;
+    const delay = getRetryDelay(attempt - 1);
+    api?.logger.info(
+      `Attempting native ${error.type} error recovery (attempt ${attempt}/${max_retries}) in ${delay}ms`
+    );
+    api?.emit(is_network ? "error:network" : "error:media", {
+      error: new Error(error.details)
+    });
+    if (retryTimeout) {
+      clearTimeout(retryTimeout);
+    }
+    const retry_session = loadSession;
+    retryTimeout = setTimeout(() => {
+      if (retry_session !== loadSession) return;
+      void recoverNative(error, resume_position);
+    }, delay);
+  };
+  const recoverNative = async (error, resumePosition) => {
+    if (!currentSrc) return;
+    const session = ++loadSession;
+    const saved_src = currentSrc;
+    const was_live = api?.getState("live") ?? false;
+    try {
+      teardownPipeline(new Error("HLS load cancelled: native error recovery"));
+      api?.setState("playbackState", "loading");
+      await loadNative(saved_src);
+      if (session !== loadSession) return;
+      if (!was_live && video && resumePosition > 0) {
+        video.currentTime = resumePosition;
+      }
+      api?.setState("playbackState", "ready");
+      api?.setState("buffering", false);
+      try {
+        await video?.play();
+      } catch {
+      }
+    } catch {
+      if (session !== loadSession) return;
+      api?.logger.warn("Native error recovery attempt failed");
+      handleNativeFatalError(error, resumePosition);
+    }
+  };
   const loadNative = async (src) => {
     const session = loadSession;
     const videoEl = getOrCreateVideo();
@@ -780,10 +879,21 @@ function createHLSPluginWith(loader, variant, config) {
             details: media_error?.message || "Native HLS playback error",
             fatal: true
           };
-          emitFatalError(hls_error, false);
+          handleNativeFatalError(hls_error);
         };
         videoEl.addEventListener("error", onFatalVideoError);
-        const removeFatalListener = () => videoEl.removeEventListener("error", onFatalVideoError);
+        const onPlayingResetBudget = () => {
+          if (networkRetryCount > 0 || mediaRetryCount > 0) {
+            api?.logger.debug("Native playback recovered, resetting retry budgets");
+            networkRetryCount = 0;
+            mediaRetryCount = 0;
+          }
+        };
+        videoEl.addEventListener("playing", onPlayingResetBudget);
+        const removeFatalListener = () => {
+          videoEl.removeEventListener("error", onFatalVideoError);
+          videoEl.removeEventListener("playing", onPlayingResetBudget);
+        };
         const previous_cleanup = cleanupVideoEvents;
         cleanupVideoEvents = () => {
           removeFatalListener();
@@ -908,12 +1018,38 @@ function createHLSPluginWith(loader, variant, config) {
     reconnectAttempts = 0;
     reconnectWindowStart = 0;
     reconnectResumePosition = 0;
+    reconnectTriggerError = null;
+    reconnectExhausted = false;
+  };
+  const emitReconnectExhausted = (elapsedMs, windowMs) => {
+    if (reconnectExhausted) return;
+    reconnectExhausted = true;
+    const attempts = reconnectAttempts;
+    const trigger = reconnectTriggerError;
+    api?.emit("error:reconnect-exhausted", { attempts, elapsedMs, windowMs });
+    api?.setState("playbackState", "error");
+    api?.setState("buffering", false);
+    api?.emit("error", {
+      code: trigger ? mapFatalErrorCode(trigger) : import_core.ErrorCode.PLAYBACK_FAILED,
+      message: `HLS auto-reconnect gave up after ${attempts} attempts over ${Math.round(elapsedMs / 1e3)}s`,
+      fatal: true,
+      timestamp: Date.now(),
+      detail: {
+        type: trigger?.type ?? "other",
+        retriesExhausted: true,
+        attempts,
+        reconnectExhausted: true
+      }
+    });
   };
   const scheduleReconnectAttempt = () => {
+    if (reconnectExhausted) return;
     if (reconnectTimer) return;
     const window_ms = mergedConfig.reconnectWindowMs ?? 3e5;
-    if (Date.now() - reconnectWindowStart > window_ms) {
+    const elapsed_ms = Date.now() - reconnectWindowStart;
+    if (elapsed_ms > window_ms) {
       api?.logger.warn(`Auto-reconnect window exhausted after ${reconnectAttempts} attempts`);
+      emitReconnectExhausted(elapsed_ms, window_ms);
       return;
     }
     const base_delay = mergedConfig.reconnectBaseDelayMs ?? 2e3;
@@ -921,7 +1057,12 @@ function createHLSPluginWith(loader, variant, config) {
     const backoff = Math.min(base_delay * Math.pow(2, reconnectAttempts), max_delay);
     const delay = Math.round(backoff * (0.7 + Math.random() * 0.3));
     api?.logger.info(`Scheduling auto-reconnect attempt ${reconnectAttempts + 1} in ${delay}ms`);
-    api?.emit("error:reconnecting", { attempt: reconnectAttempts + 1, delayMs: delay });
+    api?.emit("error:reconnecting", {
+      attempt: reconnectAttempts + 1,
+      delayMs: delay,
+      elapsedMs: elapsed_ms,
+      windowMs: window_ms
+    });
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       void attemptReconnect();
@@ -934,6 +1075,7 @@ function createHLSPluginWith(loader, variant, config) {
     if (reconnectWindowStart === 0) {
       reconnectWindowStart = Date.now();
       reconnectResumePosition = video?.currentTime ?? 0;
+      reconnectTriggerError = error;
     }
     scheduleReconnectAttempt();
   };
@@ -965,7 +1107,10 @@ function createHLSPluginWith(loader, variant, config) {
       }
       api.setState("playbackState", "ready");
       api.setState("buffering", false);
-      api.emit("error:recovered", void 0);
+      api.emit("error:recovered", {
+        attempt: reconnectAttempts,
+        elapsedMs: Date.now() - reconnectWindowStart
+      });
       api.logger.info("Auto-reconnect succeeded");
       cancelReconnect();
       try {
@@ -981,7 +1126,7 @@ function createHLSPluginWith(loader, variant, config) {
   const plugin = {
     id: "hls-provider",
     name: variant.name,
-    version: "1.0.0",
+    version: PKG_VERSION,
     type: "provider",
     description: variant.description,
     canPlay(src) {
@@ -1072,6 +1217,9 @@ function createHLSPluginWith(loader, variant, config) {
         };
         window.addEventListener("online", onlineListener);
       }
+      const unsubPoster = api.subscribeToState((event) => {
+        if (event.key === "poster") applyPoster();
+      });
       api.onDestroy(() => {
         unsubPlay();
         unsubPause();
@@ -1080,6 +1228,7 @@ function createHLSPluginWith(loader, variant, config) {
         unsubMute();
         unsubRate();
         unsubQuality();
+        unsubPoster();
       });
     },
     async destroy() {
@@ -1105,6 +1254,7 @@ function createHLSPluginWith(loader, variant, config) {
       hasPlayedContent = false;
       cleanup(new Error("HLS load cancelled: superseded by a new load"));
       currentSrc = src;
+      applyPoster();
       api.setState("playbackState", "loading");
       api.setState("buffering", true);
       if (api.getState("airplayActive") && loader.supportsNativeHLS()) {
@@ -1256,5 +1406,6 @@ function createHLSPlugin(config) {
 var light_default = createHLSPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createHLSPlugin
+  createHLSPlugin,
+  sanitizeUrl
 });

package/dist/light.d.cts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-D-HW4lmM.cjs';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-D-HW4lmM.cjs';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './sanitize-url-DcZXD_K-.cjs';
+export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, s as sanitizeUrl } from './sanitize-url-DcZXD_K-.cjs';
 import '@scarlett-player/core';
 
 /**

package/dist/light.d.ts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-D-HW4lmM.js';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-D-HW4lmM.js';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './sanitize-url-DcZXD_K-.js';
+export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, s as sanitizeUrl } from './sanitize-url-DcZXD_K-.js';
 import '@scarlett-player/core';
 
 /**

package/dist/light.js

@@ -1,7 +1,8 @@
 import {
   __export,
-  createHLSPluginWith
-} from "./chunk-IFUZZQQE.js";
+  createHLSPluginWith,
+  sanitizeUrl
+} from "./chunk-FN6QUW42.js";
 
 // src/hls-loader-light.ts
 var hls_loader_light_exports = {};
@@ -93,5 +94,6 @@ function createHLSPlugin(config) {
 var light_default = createHLSPlugin;
 export {
   createHLSPlugin,
-  light_default as default
+  light_default as default,
+  sanitizeUrl
 };

package/dist/{types-D-HW4lmM.d.cts → sanitize-url-DcZXD_K-.d.cts}

@@ -22,9 +22,19 @@ interface HLSPluginConfig {
     backBufferLength?: number;
     /** Enable worker for hls.js (better performance) */
     enableWorker?: boolean;
-    /** Max network error retries before giving up (default: 3) */
+    /**
+     * Max network error retries before giving up (default: 3).
+     *
+     * Governs both playback branches: hls.js retries the load, and the native
+     * (Safari/iOS) path reloads the source and restores position.
+     */
     maxNetworkRetries?: number;
-    /** Max media error retries before giving up (default: 2) */
+    /**
+     * Max media error retries before giving up (default: 2).
+     *
+     * Governs both playback branches: hls.js calls recoverMediaError(), and the
+     * native (Safari/iOS) path reloads the source and restores position.
+     */
     maxMediaRetries?: number;
     /** Cap quality to player element dimensions (default: true) */
     capLevelToPlayerSize?: boolean;
@@ -128,4 +138,29 @@ interface IHLSPlugin extends Plugin<HLSPluginConfig> {
     switchToHlsJs(): Promise<void>;
 }
 
-export type { HLSPluginConfig as H, IHLSPlugin as I, HLSQualityLevel as a, HLSError as b, HLSLiveInfo as c };
+/**
+ * URL sanitizer for error telemetry.
+ *
+ * Segment and playlist URLs are the single most useful field when
+ * diagnosing a dead stream, and the single most dangerous one to hand to a
+ * consumer's telemetry: signed-URL tokens, HMAC signatures, and session ids
+ * all live in the query string. Stripping the whole query (and fragment) is
+ * the privacy-safe default for EVERY consumer; anyone who genuinely needs
+ * the parameters can subscribe to hls.js directly.
+ */
+/**
+ * Reduce a URL to origin + pathname, dropping the query string and fragment.
+ *
+ * @param url - Raw URL from a provider error, if any
+ * @returns Sanitized `origin + pathname`, or undefined when there is
+ *          nothing usable to report (absent or unparseable URL)
+ *
+ * @example
+ * ```ts
+ * sanitizeUrl('https://cdn.example.com/live/x.m3u8?token=secret#frag');
+ * // 'https://cdn.example.com/live/x.m3u8'
+ * ```
+ */
+declare function sanitizeUrl(url: string | undefined | null): string | undefined;
+
+export { type HLSPluginConfig as H, type IHLSPlugin as I, type HLSQualityLevel as a, type HLSError as b, type HLSLiveInfo as c, sanitizeUrl as s };

package/dist/{types-D-HW4lmM.d.ts → sanitize-url-DcZXD_K-.d.ts}

@@ -22,9 +22,19 @@ interface HLSPluginConfig {
     backBufferLength?: number;
     /** Enable worker for hls.js (better performance) */
     enableWorker?: boolean;
-    /** Max network error retries before giving up (default: 3) */
+    /**
+     * Max network error retries before giving up (default: 3).
+     *
+     * Governs both playback branches: hls.js retries the load, and the native
+     * (Safari/iOS) path reloads the source and restores position.
+     */
     maxNetworkRetries?: number;
-    /** Max media error retries before giving up (default: 2) */
+    /**
+     * Max media error retries before giving up (default: 2).
+     *
+     * Governs both playback branches: hls.js calls recoverMediaError(), and the
+     * native (Safari/iOS) path reloads the source and restores position.
+     */
     maxMediaRetries?: number;
     /** Cap quality to player element dimensions (default: true) */
     capLevelToPlayerSize?: boolean;
@@ -128,4 +138,29 @@ interface IHLSPlugin extends Plugin<HLSPluginConfig> {
     switchToHlsJs(): Promise<void>;
 }
 
-export type { HLSPluginConfig as H, IHLSPlugin as I, HLSQualityLevel as a, HLSError as b, HLSLiveInfo as c };
+/**
+ * URL sanitizer for error telemetry.
+ *
+ * Segment and playlist URLs are the single most useful field when
+ * diagnosing a dead stream, and the single most dangerous one to hand to a
+ * consumer's telemetry: signed-URL tokens, HMAC signatures, and session ids
+ * all live in the query string. Stripping the whole query (and fragment) is
+ * the privacy-safe default for EVERY consumer; anyone who genuinely needs
+ * the parameters can subscribe to hls.js directly.
+ */
+/**
+ * Reduce a URL to origin + pathname, dropping the query string and fragment.
+ *
+ * @param url - Raw URL from a provider error, if any
+ * @returns Sanitized `origin + pathname`, or undefined when there is
+ *          nothing usable to report (absent or unparseable URL)
+ *
+ * @example
+ * ```ts
+ * sanitizeUrl('https://cdn.example.com/live/x.m3u8?token=secret#frag');
+ * // 'https://cdn.example.com/live/x.m3u8'
+ * ```
+ */
+declare function sanitizeUrl(url: string | undefined | null): string | undefined;
+
+export { type HLSPluginConfig as H, type IHLSPlugin as I, type HLSQualityLevel as a, type HLSError as b, type HLSLiveInfo as c, sanitizeUrl as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/hls",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "HLS Provider Plugin for Scarlett Player",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,8 +22,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "@scarlett-player/core": "^1.0.3",
-    "hls.js": "^1.5.0"
+    "@scarlett-player/core": "^1.7.0",
+    "hls.js": "^1.6.0"
   },
   "peerDependenciesMeta": {
     "hls.js": {
@@ -37,7 +37,7 @@
     "vitest": "^1.6.0",
     "@vitest/coverage-v8": "^1.6.0",
     "jsdom": "^24.0.0",
-    "@scarlett-player/core": "1.6.0"
+    "@scarlett-player/core": "1.8.0"
   },
   "keywords": [
     "video",
@@ -58,10 +58,11 @@
   },
   "homepage": "https://scarlettplayer.com",
   "scripts": {
-    "build": "tsup src/index.ts src/light.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts src/light.ts --format esm,cjs --dts --watch",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "test": "vitest --run",
     "test:watch": "vitest",
-    "test:coverage": "vitest --coverage"
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
   }
 }