@scarlett-player/hls 1.0.2 → 1.2.0

package/dist/light.cjs

@@ -36,6 +36,17 @@ __export(light_exports, {
 module.exports = __toCommonJS(light_exports);
 
 // src/hls-loader-light.ts
+var hls_loader_light_exports = {};
+__export(hls_loader_light_exports, {
+  createHlsInstance: () => createHlsInstance,
+  getHlsConstructor: () => getHlsConstructor,
+  isHLSSupported: () => isHLSSupported,
+  isHlsJsSupported: () => isHlsJsSupported,
+  loadHlsJs: () => loadHlsJs,
+  resetLoader: () => resetLoader,
+  shouldPreferNativeHLS: () => shouldPreferNativeHLS,
+  supportsNativeHLS: () => supportsNativeHLS
+});
 var hlsConstructor = null;
 var loadingPromise = null;
 function supportsNativeHLS() {
@@ -43,6 +54,13 @@ function supportsNativeHLS() {
   const video = document.createElement("video");
   return video.canPlayType("application/vnd.apple.mpegurl") !== "";
 }
+function shouldPreferNativeHLS() {
+  if (!supportsNativeHLS()) return false;
+  if (typeof navigator === "undefined") return false;
+  const ua = navigator.userAgent;
+  const isSafari = /Safari/.test(ua) && !/Chrome/.test(ua) && !/CriOS/.test(ua);
+  return isSafari;
+}
 function isHlsJsSupported() {
   if (hlsConstructor) {
     return hlsConstructor.isSupported();
@@ -86,6 +104,13 @@ function createHlsInstance(config) {
 function getHlsConstructor() {
   return hlsConstructor;
 }
+function resetLoader() {
+  hlsConstructor = null;
+  loadingPromise = null;
+}
+
+// src/create-hls-plugin.ts
+var import_core = require("@scarlett-player/core");
 
 // src/quality.ts
 function formatLevel(level) {
@@ -133,6 +158,18 @@ function mapLevels(levels, _currentLevel) {
     codec: level.codecSet
   }));
 }
+function getInitialBandwidthEstimate(overrideBps) {
+  const HLS_DEFAULT_ESTIMATE = 5e5;
+  if (overrideBps !== void 0 && overrideBps > 0) {
+    return overrideBps;
+  }
+  const connection = navigator.connection;
+  if (connection?.downlink && connection.downlink > 0) {
+    const bps = connection.downlink * 1e6;
+    return Math.round(bps * 0.85);
+  }
+  return HLS_DEFAULT_ESTIMATE;
+}
 
 // src/event-map.ts
 var HLS_ERROR_TYPES = {
@@ -214,6 +251,7 @@ function setupHlsEventHandlers(hls, api, callbacks) {
       lastBandwidthUpdate = now;
       api.setState("bandwidth", Math.round(hls.bandwidthEstimate));
     }
+    callbacks.onFragLoaded?.();
   });
   addHandler("hlsFragBuffered", () => {
     api.setState("buffering", false);
@@ -404,7 +442,51 @@ function setupVideoEventHandlers(video, api) {
   };
 }
 
-// src/light.ts
+// src/playlist-validation.ts
+var PLAYLIST_INVALID_TEXT = "Invalid playlist document";
+var MEDIA_PLAYLIST_CONTEXTS = ["level", "audioTrack", "subtitleTrack"];
+function isValidPlaylistDocument(data, contextType) {
+  if (typeof data !== "string" || data.length === 0) return false;
+  const text = data.trimStart();
+  if (!text.startsWith("#EXTM3U")) return false;
+  if (contextType && MEDIA_PLAYLIST_CONTEXTS.includes(contextType)) {
+    return /^#EXT(?:INF|-X-TARGETDURATION):/m.test(text);
+  }
+  return true;
+}
+function createValidatingPlaylistLoader(Hls) {
+  const BaseLoader = Hls.DefaultConfig.loader;
+  return class ValidatingPlaylistLoader extends BaseLoader {
+    /**
+     * Load a playlist, validating the response document before it reaches
+     * the M3U8 parser.
+     *
+     * @param context - hls.js loader context
+     * @param config - hls.js loader config
+     * @param callbacks - hls.js loader callbacks
+     */
+    load(context, config, callbacks) {
+      const wrapped = {
+        ...callbacks,
+        onSuccess: (response, stats, ctx, networkDetails) => {
+          if (!isValidPlaylistDocument(response?.data, ctx?.type)) {
+            callbacks.onError(
+              { code: 0, text: PLAYLIST_INVALID_TEXT },
+              ctx,
+              networkDetails,
+              stats
+            );
+            return;
+          }
+          callbacks.onSuccess(response, stats, ctx, networkDetails);
+        }
+      };
+      super.load(context, config, wrapped);
+    }
+  };
+}
+
+// src/create-hls-plugin.ts
 var DEFAULT_CONFIG = {
   debug: false,
   autoStartLoad: true,
@@ -414,12 +496,28 @@ var DEFAULT_CONFIG = {
   maxMaxBufferLength: 600,
   backBufferLength: 30,
   enableWorker: true,
+  capLevelToPlayerSize: true,
+  // Error recovery settings
   maxNetworkRetries: 3,
   maxMediaRetries: 2,
   retryDelayMs: 1e3,
-  retryBackoffFactor: 2
+  retryBackoffFactor: 2,
+  // Load watchdog: never leave the viewer on an endless spinner
+  loadTimeoutMs: 3e4,
+  // Self-healing: reconnect automatically after fatal errors mid-playback
+  autoReconnect: true,
+  reconnectBaseDelayMs: 2e3,
+  reconnectMaxDelayMs: 3e4,
+  reconnectWindowMs: 3e5,
+  // Never index a malformed live playlist refresh blindly
+  validatePlaylists: true
 };
-function createHLSPlugin(config) {
+var MANIFEST_PHASE_ERRORS = [
+  "manifestLoadError",
+  "manifestLoadTimeOut",
+  "manifestParsingError"
+];
+function createHLSPluginWith(loader, variant, config) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   let api = null;
   let hls = null;
@@ -429,6 +527,8 @@ function createHLSPlugin(config) {
   let cleanupHlsEvents = null;
   let cleanupVideoEvents = null;
   let isAutoQuality = true;
+  let loadSession = 0;
+  let abortPendingLoad = null;
   let networkRetryCount = 0;
   let mediaRetryCount = 0;
   let retryTimeout = null;
@@ -436,6 +536,12 @@ function createHLSPlugin(config) {
   let errorWindowStart = 0;
   const MAX_ERRORS_IN_WINDOW = 10;
   const ERROR_WINDOW_MS = 5e3;
+  let hasPlayedContent = false;
+  let reconnectTimer = null;
+  let reconnectAttempts = 0;
+  let reconnectWindowStart = 0;
+  let reconnectResumePosition = 0;
+  let onlineListener = null;
   const getOrCreateVideo = () => {
     if (video) return video;
     const existing = api?.container.querySelector("video");
@@ -448,10 +554,16 @@ function createHLSPlugin(config) {
     video.preload = "metadata";
     video.controls = false;
     video.playsInline = true;
+    const poster = api?.getState("poster");
+    if (poster) {
+      video.poster = poster;
+    }
     api?.container.appendChild(video);
     return video;
   };
-  const cleanup = () => {
+  const teardownPipeline = (reason) => {
+    abortPendingLoad?.(reason ?? new Error("HLS load cancelled"));
+    abortPendingLoad = null;
     cleanupHlsEvents?.();
     cleanupHlsEvents = null;
     cleanupVideoEvents?.();
@@ -464,6 +576,9 @@ function createHLSPlugin(config) {
       hls.destroy();
       hls = null;
     }
+  };
+  const cleanup = (reason) => {
+    teardownPipeline(reason);
     currentSrc = null;
     isNative = false;
     isAutoQuality = true;
@@ -472,16 +587,30 @@ function createHLSPlugin(config) {
     errorCount = 0;
     errorWindowStart = 0;
   };
-  const buildHlsConfig = () => ({
+  const buildHlsConfig = () => {
+    const config2 = buildBaseHlsConfig();
+    if (mergedConfig.validatePlaylists !== false) {
+      const Hls = loader.getHlsConstructor();
+      if (Hls && Hls.DefaultConfig?.loader) {
+        config2.pLoader = createValidatingPlaylistLoader(Hls);
+      }
+    }
+    return config2;
+  };
+  const buildBaseHlsConfig = () => ({
     debug: mergedConfig.debug,
     autoStartLoad: mergedConfig.autoStartLoad,
     startPosition: mergedConfig.startPosition,
     startLevel: -1,
+    // Auto quality selection (ABR)
+    abrEwmaDefaultEstimate: getInitialBandwidthEstimate(mergedConfig.initialBandwidthEstimate),
     lowLatencyMode: mergedConfig.lowLatencyMode,
     maxBufferLength: mergedConfig.maxBufferLength,
     maxMaxBufferLength: mergedConfig.maxMaxBufferLength,
     backBufferLength: mergedConfig.backBufferLength,
     enableWorker: mergedConfig.enableWorker,
+    capLevelToPlayerSize: mergedConfig.capLevelToPlayerSize,
+    // Minimize hls.js internal retries - we handle retries ourselves
     fragLoadingMaxRetry: 1,
     manifestLoadingMaxRetry: 1,
     levelLoadingMaxRetry: 1,
@@ -492,7 +621,34 @@ function createHLSPlugin(config) {
   const getRetryDelay = (retryCount) => {
     const baseDelay = mergedConfig.retryDelayMs ?? 1e3;
     const backoffFactor = mergedConfig.retryBackoffFactor ?? 2;
-    return baseDelay * Math.pow(backoffFactor, retryCount);
+    const delay = baseDelay * Math.pow(backoffFactor, retryCount);
+    const jitter = delay * (0.7 + Math.random() * 0.3);
+    return jitter;
+  };
+  const APPEND_ERROR_DETAILS = [
+    "bufferAppendError",
+    "bufferAppendingError",
+    "bufferAddCodecError"
+  ];
+  const mapFatalErrorCode = (error) => {
+    if (error.response?.text === PLAYLIST_INVALID_TEXT) {
+      return import_core.ErrorCode.PLAYLIST_INVALID;
+    }
+    if (error.details === "bufferFullError") {
+      return import_core.ErrorCode.MEDIA_BUFFER_FULL;
+    }
+    if (APPEND_ERROR_DETAILS.includes(error.details)) {
+      return import_core.ErrorCode.MEDIA_APPEND_ERROR;
+    }
+    switch (error.type) {
+      case "network":
+        return import_core.ErrorCode.MEDIA_NETWORK_ERROR;
+      case "media":
+      case "mux":
+        return import_core.ErrorCode.MEDIA_DECODE_ERROR;
+      default:
+        return import_core.ErrorCode.PLAYBACK_FAILED;
+    }
   };
   const emitFatalError = (error, retriesExhausted) => {
     const message = retriesExhausted ? `HLS error: ${error.details} (max retries exceeded)` : `HLS error: ${error.details}`;
@@ -500,15 +656,16 @@ function createHLSPlugin(config) {
     api?.setState("playbackState", "error");
     api?.setState("buffering", false);
     api?.emit("error", {
-      code: "MEDIA_ERROR",
+      code: mapFatalErrorCode(error),
       message,
       fatal: true,
       timestamp: Date.now()
     });
+    maybeScheduleReconnect(error);
   };
   const handleHlsError = (error) => {
-    const Hls = getHlsConstructor();
-    if (!Hls || !hls) return;
+    const Hls = loader.getHlsConstructor();
+    if (!Hls || !hls) return false;
     const now = Date.now();
     if (now - errorWindowStart > ERROR_WINDOW_MS) {
       errorCount = 1;
@@ -519,11 +676,8 @@ function createHLSPlugin(config) {
     if (errorCount >= MAX_ERRORS_IN_WINDOW) {
       api?.logger.error(`Too many errors (${errorCount} in ${ERROR_WINDOW_MS}ms), giving up`);
       emitFatalError(error, true);
-      cleanupHlsEvents?.();
-      cleanupHlsEvents = null;
-      hls.destroy();
-      hls = null;
-      return;
+      teardownPipeline(new Error(error.details));
+      return true;
     }
     if (error.fatal) {
       api?.logger.error("Fatal HLS error", { type: error.type, details: error.details });
@@ -533,7 +687,7 @@ function createHLSPlugin(config) {
           if (networkRetryCount >= maxRetries) {
             api?.logger.error(`Network error recovery failed after ${networkRetryCount} attempts`);
             emitFatalError(error, true);
-            return;
+            return true;
           }
           networkRetryCount++;
           const delay = getRetryDelay(networkRetryCount - 1);
@@ -542,8 +696,13 @@ function createHLSPlugin(config) {
           if (retryTimeout) {
             clearTimeout(retryTimeout);
           }
+          const isManifestPhase = MANIFEST_PHASE_ERRORS.includes(error.details);
+          const retry_session = loadSession;
           retryTimeout = setTimeout(() => {
-            if (hls) {
+            if (retry_session !== loadSession || !hls) return;
+            if (isManifestPhase && currentSrc) {
+              hls.loadSource(currentSrc);
+            } else {
               hls.startLoad();
             }
           }, delay);
@@ -554,7 +713,7 @@ function createHLSPlugin(config) {
           if (mediaRetryCount >= maxRetries) {
             api?.logger.error(`Media error recovery failed after ${mediaRetryCount} attempts`);
             emitFatalError(error, true);
-            return;
+            return true;
           }
           mediaRetryCount++;
           const delay = getRetryDelay(mediaRetryCount - 1);
@@ -563,39 +722,91 @@ function createHLSPlugin(config) {
           if (retryTimeout) {
             clearTimeout(retryTimeout);
           }
+          const retry_session = loadSession;
           retryTimeout = setTimeout(() => {
-            if (hls) {
-              hls.recoverMediaError();
-            }
+            if (retry_session !== loadSession || !hls) return;
+            hls.recoverMediaError();
           }, delay);
           break;
         }
         default:
           emitFatalError(error, false);
-          break;
+          return true;
       }
     }
+    return false;
   };
   const loadNative = async (src) => {
+    const session = loadSession;
     const videoEl = getOrCreateVideo();
     isNative = true;
     if (api) {
       cleanupVideoEvents = setupVideoEventHandlers(videoEl, api);
     }
     return new Promise((resolve, reject) => {
-      const onLoaded = () => {
+      let watchdog = null;
+      let settled = false;
+      const settle = () => {
+        settled = true;
+        if (abortPendingLoad === abort) {
+          abortPendingLoad = null;
+        }
         videoEl.removeEventListener("loadedmetadata", onLoaded);
         videoEl.removeEventListener("error", onError);
+        if (watchdog !== null) {
+          clearTimeout(watchdog);
+          watchdog = null;
+        }
+      };
+      const abort = (reason) => {
+        if (settled) return;
+        settle();
+        reject(reason);
+      };
+      abortPendingLoad = abort;
+      const onLoaded = () => {
+        if (settled) return;
+        if (session !== loadSession) {
+          settle();
+          reject(new Error("HLS load cancelled"));
+          return;
+        }
+        settle();
+        hasPlayedContent = true;
+        const onFatalVideoError = () => {
+          const media_error = videoEl.error;
+          const hls_error = {
+            type: media_error?.code === MediaError.MEDIA_ERR_NETWORK ? "network" : "media",
+            details: media_error?.message || "Native HLS playback error",
+            fatal: true
+          };
+          emitFatalError(hls_error, false);
+        };
+        videoEl.addEventListener("error", onFatalVideoError);
+        const removeFatalListener = () => videoEl.removeEventListener("error", onFatalVideoError);
+        const previous_cleanup = cleanupVideoEvents;
+        cleanupVideoEvents = () => {
+          removeFatalListener();
+          previous_cleanup?.();
+        };
         api?.setState("source", { src, type: "application/x-mpegURL" });
         api?.emit("media:loaded", { src, type: "application/x-mpegURL" });
         resolve();
       };
       const onError = () => {
-        videoEl.removeEventListener("loadedmetadata", onLoaded);
-        videoEl.removeEventListener("error", onError);
+        if (settled) return;
+        settle();
         const error = videoEl.error;
         reject(new Error(error?.message || "Failed to load HLS source"));
       };
+      const timeout_ms = mergedConfig.loadTimeoutMs ?? 3e4;
+      if (timeout_ms > 0) {
+        watchdog = setTimeout(() => {
+          if (settled || session !== loadSession) return;
+          settle();
+          reject(new Error("Video took too long to load (network timeout)"));
+        }, timeout_ms);
+      }
       videoEl.addEventListener("loadedmetadata", onLoaded);
       videoEl.addEventListener("error", onError);
       videoEl.src = src;
@@ -603,10 +814,14 @@ function createHLSPlugin(config) {
     });
   };
   const loadWithHlsJs = async (src) => {
-    await loadHlsJs();
+    const session = loadSession;
+    await loader.loadHlsJs();
+    if (session !== loadSession) {
+      throw new Error("HLS load cancelled");
+    }
     const videoEl = getOrCreateVideo();
     isNative = false;
-    hls = createHlsInstance(buildHlsConfig());
+    hls = loader.createHlsInstance(buildHlsConfig());
     if (api) {
       cleanupVideoEvents = setupVideoEventHandlers(videoEl, api);
     }
@@ -616,10 +831,33 @@ function createHLSPlugin(config) {
         return;
       }
       let resolved = false;
+      let watchdog = null;
+      const clearWatchdog = () => {
+        if (watchdog !== null) {
+          clearTimeout(watchdog);
+          watchdog = null;
+        }
+      };
+      const abort = (reason) => {
+        if (resolved) return;
+        resolved = true;
+        clearWatchdog();
+        reject(reason);
+      };
+      abortPendingLoad = abort;
+      const releaseAbort = () => {
+        if (abortPendingLoad === abort) {
+          abortPendingLoad = null;
+        }
+      };
       cleanupHlsEvents = setupHlsEventHandlers(hls, api, {
         onManifestParsed: () => {
+          if (session !== loadSession) return;
           if (!resolved) {
             resolved = true;
+            releaseAbort();
+            clearWatchdog();
+            hasPlayedContent = true;
             api?.setState("source", { src, type: "application/x-mpegURL" });
             api?.emit("media:loaded", { src, type: "application/x-mpegURL" });
             resolve();
@@ -628,26 +866,126 @@ function createHLSPlugin(config) {
         onLevelSwitched: () => {
         },
         onError: (error) => {
-          handleHlsError(error);
-          if (error.fatal && !resolved && error.type !== "network" && error.type !== "media") {
+          if (session !== loadSession) return;
+          const terminal = handleHlsError(error);
+          if (terminal && !resolved) {
             resolved = true;
+            releaseAbort();
+            clearWatchdog();
             reject(new Error(error.details));
           }
         },
+        onFragLoaded: () => {
+          if (session !== loadSession) return;
+          if (networkRetryCount > 0 || mediaRetryCount > 0) {
+            api?.logger.debug("Playback recovered, resetting retry budgets");
+            networkRetryCount = 0;
+            mediaRetryCount = 0;
+          }
+        },
         getIsAutoQuality: () => isAutoQuality
       });
+      const timeout_ms = mergedConfig.loadTimeoutMs ?? 3e4;
+      if (timeout_ms > 0) {
+        watchdog = setTimeout(() => {
+          if (resolved || session !== loadSession) return;
+          resolved = true;
+          releaseAbort();
+          api?.logger.error(`HLS load timed out after ${timeout_ms}ms`, { src });
+          teardownPipeline();
+          reject(new Error("Video took too long to load (network timeout)"));
+        }, timeout_ms);
+      }
       hls.attachMedia(videoEl);
       hls.loadSource(src);
     });
   };
+  const cancelReconnect = () => {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    reconnectAttempts = 0;
+    reconnectWindowStart = 0;
+    reconnectResumePosition = 0;
+  };
+  const scheduleReconnectAttempt = () => {
+    if (reconnectTimer) return;
+    const window_ms = mergedConfig.reconnectWindowMs ?? 3e5;
+    if (Date.now() - reconnectWindowStart > window_ms) {
+      api?.logger.warn(`Auto-reconnect window exhausted after ${reconnectAttempts} attempts`);
+      return;
+    }
+    const base_delay = mergedConfig.reconnectBaseDelayMs ?? 2e3;
+    const max_delay = mergedConfig.reconnectMaxDelayMs ?? 3e4;
+    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 });
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      void attemptReconnect();
+    }, delay);
+  };
+  const maybeScheduleReconnect = (error) => {
+    if (mergedConfig.autoReconnect === false) return;
+    if (!hasPlayedContent || !currentSrc) return;
+    if (error.type !== "network" && error.type !== "media") return;
+    if (reconnectWindowStart === 0) {
+      reconnectWindowStart = Date.now();
+      reconnectResumePosition = video?.currentTime ?? 0;
+    }
+    scheduleReconnectAttempt();
+  };
+  const attemptReconnect = async () => {
+    if (!api || !currentSrc) return;
+    const session = ++loadSession;
+    reconnectAttempts++;
+    const saved_src = currentSrc;
+    const was_live = api.getState("live");
+    const was_native = isNative;
+    const resume_position = reconnectResumePosition;
+    api.logger.info(`Auto-reconnect attempt ${reconnectAttempts}`, { src: saved_src });
+    try {
+      teardownPipeline(new Error("HLS load cancelled: reconnecting"));
+      networkRetryCount = 0;
+      mediaRetryCount = 0;
+      errorCount = 0;
+      errorWindowStart = 0;
+      currentSrc = saved_src;
+      api.setState("playbackState", "loading");
+      if (was_native && loader.supportsNativeHLS()) {
+        await loadNative(saved_src);
+      } else {
+        await loadWithHlsJs(saved_src);
+      }
+      if (session !== loadSession) return;
+      if (!was_live && video && resume_position > 0) {
+        video.currentTime = resume_position;
+      }
+      api.setState("playbackState", "ready");
+      api.setState("buffering", false);
+      api.emit("error:recovered", void 0);
+      api.logger.info("Auto-reconnect succeeded");
+      cancelReconnect();
+      try {
+        await video?.play();
+      } catch {
+      }
+    } catch {
+      if (session !== loadSession) return;
+      api?.logger.warn(`Auto-reconnect attempt ${reconnectAttempts} failed`);
+      scheduleReconnectAttempt();
+    }
+  };
   const plugin = {
     id: "hls-provider",
-    name: "HLS Provider (Light)",
+    name: variant.name,
     version: "1.0.0",
     type: "provider",
-    description: "HLS playback provider using hls.js/light (smaller bundle)",
+    description: variant.description,
     canPlay(src) {
-      if (!isHLSSupported()) return false;
+      if (!loader.isHLSSupported()) return false;
       const url = src.toLowerCase();
       const urlWithoutQuery = url.split("?")[0].split("#")[0];
       if (urlWithoutQuery.endsWith(".m3u8")) return true;
@@ -657,7 +995,7 @@ function createHLSPlugin(config) {
     },
     async init(pluginApi) {
       api = pluginApi;
-      api.logger.info("HLS plugin (light) initialized");
+      api.logger.info(`HLS plugin${variant.logSuffix} initialized`);
       const unsubPlay = api.on("playback:play", async () => {
         if (!video) return;
         try {
@@ -723,6 +1061,17 @@ function createHLSPlugin(config) {
           }
         }
       });
+      if (typeof window !== "undefined") {
+        onlineListener = () => {
+          if (reconnectTimer) {
+            api?.logger.info("Browser back online, reconnecting immediately");
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+            void attemptReconnect();
+          }
+        };
+        window.addEventListener("online", onlineListener);
+      }
       api.onDestroy(() => {
         unsubPlay();
         unsubPause();
@@ -734,8 +1083,14 @@ function createHLSPlugin(config) {
       });
     },
     async destroy() {
-      api?.logger.info("HLS plugin (light) destroying");
-      cleanup();
+      api?.logger.info(`HLS plugin${variant.logSuffix} destroying`);
+      loadSession++;
+      cancelReconnect();
+      if (onlineListener && typeof window !== "undefined") {
+        window.removeEventListener("online", onlineListener);
+        onlineListener = null;
+      }
+      cleanup(new Error("HLS load cancelled: player destroyed"));
       if (video?.parentNode) {
         video.parentNode.removeChild(video);
       }
@@ -744,20 +1099,27 @@ function createHLSPlugin(config) {
     },
     async loadSource(src) {
       if (!api) throw new Error("Plugin not initialized");
-      api.logger.info("Loading HLS source (light)", { src });
-      cleanup();
+      api.logger.info(`Loading HLS source${variant.logSuffix}`, { src });
+      const session = ++loadSession;
+      cancelReconnect();
+      hasPlayedContent = false;
+      cleanup(new Error("HLS load cancelled: superseded by a new load"));
       currentSrc = src;
       api.setState("playbackState", "loading");
       api.setState("buffering", true);
-      if (isHlsJsSupported()) {
-        api.logger.info("Using hls.js/light for HLS playback");
+      if (api.getState("airplayActive") && loader.supportsNativeHLS()) {
+        api.logger.info("Using native HLS (AirPlay active)");
+        await loadNative(src);
+      } else if (loader.isHlsJsSupported()) {
+        api.logger.info(`Using ${variant.engineLabel} for HLS playback`);
         await loadWithHlsJs(src);
-      } else if (supportsNativeHLS()) {
+      } else if (loader.supportsNativeHLS()) {
         api.logger.info("Using native HLS playback (hls.js not supported)");
         await loadNative(src);
       } else {
         throw new Error("HLS playback not supported in this browser");
       }
+      if (session !== loadSession) return;
       if (video) {
         const muted = api.getState("muted");
         const volume = api.getState("volume");
@@ -799,12 +1161,17 @@ function createHLSPlugin(config) {
         drift: hls.drift || 0
       };
     },
+    /**
+     * Switch from hls.js to native HLS playback.
+     * Used for AirPlay compatibility in Safari.
+     * Preserves current playback position.
+     */
     async switchToNative() {
       if (isNative) {
         api?.logger.debug("Already using native HLS");
         return;
       }
-      if (!supportsNativeHLS()) {
+      if (!loader.supportsNativeHLS()) {
         api?.logger.warn("Native HLS not supported in this browser");
         return;
       }
@@ -816,8 +1183,10 @@ function createHLSPlugin(config) {
       const wasPlaying = api?.getState("playing") || false;
       const currentTime = video?.currentTime || 0;
       const savedSrc = currentSrc;
-      cleanup();
+      const session = ++loadSession;
+      cleanup(new Error("HLS load cancelled: switching to native HLS"));
       await loadNative(savedSrc);
+      if (session !== loadSession) return;
       if (video && currentTime > 0) {
         video.currentTime = currentTime;
       }
@@ -830,12 +1199,16 @@ function createHLSPlugin(config) {
       }
       api?.logger.info("Switched to native HLS");
     },
+    /**
+     * Switch from native HLS back to hls.js.
+     * Restores quality control after AirPlay session ends.
+     */
     async switchToHlsJs() {
       if (!isNative) {
         api?.logger.debug("Already using hls.js");
         return;
       }
-      if (!isHlsJsSupported()) {
+      if (!loader.isHlsJsSupported()) {
         api?.logger.warn("hls.js not supported in this browser");
         return;
       }
@@ -847,8 +1220,10 @@ function createHLSPlugin(config) {
       const wasPlaying = api?.getState("playing") || false;
       const currentTime = video?.currentTime || 0;
       const savedSrc = currentSrc;
-      cleanup();
+      const session = ++loadSession;
+      cleanup(new Error("HLS load cancelled: switching to hls.js"));
       await loadWithHlsJs(savedSrc);
+      if (session !== loadSession) return;
       if (video && currentTime > 0) {
         video.currentTime = currentTime;
       }
@@ -864,6 +1239,20 @@ function createHLSPlugin(config) {
   };
   return plugin;
 }
+
+// src/light.ts
+function createHLSPlugin(config) {
+  return createHLSPluginWith(
+    hls_loader_light_exports,
+    {
+      name: "HLS Provider (Light)",
+      description: "HLS playback provider using hls.js/light (smaller bundle)",
+      logSuffix: " (light)",
+      engineLabel: "hls.js/light"
+    },
+    config
+  );
+}
 var light_default = createHLSPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {