@codenkay/video-nsgplayer-core 3.0.1 → 3.0.4

package/dist/index.d.cts

@@ -1,5 +1,3 @@
-import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
-
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
@@ -89,6 +87,11 @@ type ControlsConfig = {
     showLive?: boolean;
     seekCueDurationMs?: number;
     keyboardShortcuts?: boolean;
+    /**
+     * When true, UI chrome persists the last quality choice (by height) in
+     * localStorage and restores it for later sessions.
+     */
+    persistQualityPreference?: boolean;
 };
 type ThemeConfig = {
     playIconPreset?: PlayIconPreset;
@@ -286,7 +289,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "3.0.1";
+declare const PACKAGE_VERSION = "3.0.3";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -456,7 +459,8 @@ type HlsEngineOptions = {
  * (playlists, segments, and AES `enc.key` on CDN hosts).
  *
  * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
- * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * `streaming.getKeyAccessToken` (Bearer only after signed-query 401/403).
+ * CDN keys prefer signed query without Authorization (no CORS preflight).
  * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
@@ -653,6 +657,54 @@ declare class RefreshManager {
     private renew;
 }
 
+/**
+ * Local loader types (structurally compatible with hls.js) so the public
+ * `.d.ts` does not require a value import of optional peer `hls.js`.
+ */
+type HlsLoaderTiming = {
+    start: number;
+    first: number;
+    end: number;
+};
+type LoaderStats = {
+    aborted: boolean;
+    loaded: number;
+    retry: number;
+    total: number;
+    chunkCount: number;
+    bwEstimate: number;
+    loading: HlsLoaderTiming;
+    parsing: {
+        start: number;
+        end: number;
+    };
+    buffering: HlsLoaderTiming;
+};
+type LoaderContext = {
+    url: string;
+    responseType?: string;
+    rangeStart?: number;
+    rangeEnd?: number;
+    progressData?: boolean;
+    [key: string]: unknown;
+};
+type LoaderConfiguration = {
+    timeout?: number;
+};
+type LoaderCallbacks<TContext> = {
+    onSuccess: (response: {
+        url: string;
+        data: ArrayBuffer | string;
+        code?: number;
+    }, stats: LoaderStats, context: TContext, networkDetails: unknown) => void;
+    onError: (error: {
+        code: number;
+        text: string;
+    }, context: TContext, networkDetails: unknown, stats: LoaderStats) => void;
+    onTimeout?: (...args: unknown[]) => void;
+    onAbort?: (...args: unknown[]) => void;
+    onProgress?: (...args: unknown[]) => void;
+};
 type HlsLoaderInstance = {
     stats: LoaderStats;
     context: LoaderContext | null;
@@ -662,6 +714,8 @@ type HlsLoaderInstance = {
 };
 /** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
 type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Public alias — pass `hls.js` default export (typed as object at the boundary). */
+type HlsModuleLike = object;
 /** Max same-origin BFF key attempts before the session circuit opens. */
 declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
@@ -673,30 +727,19 @@ type AuthParamsLoaderOptions = {
 };
 declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
 /**
- * Always resolve a builtin hls.js loader (XhrLoader).
- *
- * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
- * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
- * stack (`InternalError: too much recursion`).
+ * Resolve the builtin loader from the **same** `hls.js` module instance the
+ * engine loaded. Never statically import `XhrLoader` — that can pull a second
+ * hls.js copy into the app bundle after npm pack/publish and break key loads.
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
+declare function resolveBuiltinHlsLoader(HlsModule: HlsModuleLike): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- *
- * AES `enc.key` handling (enterprise priority order):
- * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
- * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
- * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that:
- * - Re-applies signed auth query params on every media request
- * - Loads AES `enc.key` via controlled BFF (≤2) → Bearer → query XHR
- *   with a **session circuit breaker** so a dead Cloudflare BFF is not
- *   hammered by hls.js retries (which previously caused 9–10× 502s).
+ * hls.js loader: auth query rewrite + enterprise AES key loading.
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
+declare function createAuthParamsLoader(HlsModule: HlsModuleLike, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -705,4 +748,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsLoaderConstructor, type HlsModuleLike, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
-
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
@@ -89,6 +87,11 @@ type ControlsConfig = {
     showLive?: boolean;
     seekCueDurationMs?: number;
     keyboardShortcuts?: boolean;
+    /**
+     * When true, UI chrome persists the last quality choice (by height) in
+     * localStorage and restores it for later sessions.
+     */
+    persistQualityPreference?: boolean;
 };
 type ThemeConfig = {
     playIconPreset?: PlayIconPreset;
@@ -286,7 +289,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "3.0.1";
+declare const PACKAGE_VERSION = "3.0.3";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -456,7 +459,8 @@ type HlsEngineOptions = {
  * (playlists, segments, and AES `enc.key` on CDN hosts).
  *
  * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
- * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * `streaming.getKeyAccessToken` (Bearer only after signed-query 401/403).
+ * CDN keys prefer signed query without Authorization (no CORS preflight).
  * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
@@ -653,6 +657,54 @@ declare class RefreshManager {
     private renew;
 }
 
+/**
+ * Local loader types (structurally compatible with hls.js) so the public
+ * `.d.ts` does not require a value import of optional peer `hls.js`.
+ */
+type HlsLoaderTiming = {
+    start: number;
+    first: number;
+    end: number;
+};
+type LoaderStats = {
+    aborted: boolean;
+    loaded: number;
+    retry: number;
+    total: number;
+    chunkCount: number;
+    bwEstimate: number;
+    loading: HlsLoaderTiming;
+    parsing: {
+        start: number;
+        end: number;
+    };
+    buffering: HlsLoaderTiming;
+};
+type LoaderContext = {
+    url: string;
+    responseType?: string;
+    rangeStart?: number;
+    rangeEnd?: number;
+    progressData?: boolean;
+    [key: string]: unknown;
+};
+type LoaderConfiguration = {
+    timeout?: number;
+};
+type LoaderCallbacks<TContext> = {
+    onSuccess: (response: {
+        url: string;
+        data: ArrayBuffer | string;
+        code?: number;
+    }, stats: LoaderStats, context: TContext, networkDetails: unknown) => void;
+    onError: (error: {
+        code: number;
+        text: string;
+    }, context: TContext, networkDetails: unknown, stats: LoaderStats) => void;
+    onTimeout?: (...args: unknown[]) => void;
+    onAbort?: (...args: unknown[]) => void;
+    onProgress?: (...args: unknown[]) => void;
+};
 type HlsLoaderInstance = {
     stats: LoaderStats;
     context: LoaderContext | null;
@@ -662,6 +714,8 @@ type HlsLoaderInstance = {
 };
 /** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
 type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Public alias — pass `hls.js` default export (typed as object at the boundary). */
+type HlsModuleLike = object;
 /** Max same-origin BFF key attempts before the session circuit opens. */
 declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
@@ -673,30 +727,19 @@ type AuthParamsLoaderOptions = {
 };
 declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
 /**
- * Always resolve a builtin hls.js loader (XhrLoader).
- *
- * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
- * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
- * stack (`InternalError: too much recursion`).
+ * Resolve the builtin loader from the **same** `hls.js` module instance the
+ * engine loaded. Never statically import `XhrLoader` — that can pull a second
+ * hls.js copy into the app bundle after npm pack/publish and break key loads.
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
+declare function resolveBuiltinHlsLoader(HlsModule: HlsModuleLike): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- *
- * AES `enc.key` handling (enterprise priority order):
- * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
- * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
- * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that:
- * - Re-applies signed auth query params on every media request
- * - Loads AES `enc.key` via controlled BFF (≤2) → Bearer → query XHR
- *   with a **session circuit breaker** so a dead Cloudflare BFF is not
- *   hammered by hls.js retries (which previously caused 9–10× 502s).
+ * hls.js loader: auth query rewrite + enterprise AES key loading.
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
+declare function createAuthParamsLoader(HlsModule: HlsModuleLike, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -705,4 +748,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsLoaderConstructor, type HlsModuleLike, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.js

@@ -146,7 +146,7 @@ var AuthManager = class {
 
 // src/config/defaults.ts
 var PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2];
-var PACKAGE_VERSION = "3.0.1";
+var PACKAGE_VERSION = "3.0.3";
 var DEFAULT_PLAYER_BEHAVIOR = {
   autoplay: true,
   startMuted: true,
@@ -170,7 +170,8 @@ var DEFAULT_CONTROLS = {
   showSkip: true,
   showLive: true,
   seekCueDurationMs: 720,
-  keyboardShortcuts: true
+  keyboardShortcuts: true,
+  persistQualityPreference: false
 };
 var DEFAULT_THEME = {
   playIconPreset: "triangle",
@@ -766,9 +767,12 @@ function seekToLiveEdge(media, options) {
 }
 
 // src/streaming/authParamsLoader.ts
-import { XhrLoader as BuiltinXhrLoader } from "hls.js";
 var ENC_KEY_PATH_RE = /enc\.key$/i;
 var BUILTIN_LOADER_NAMES = /* @__PURE__ */ new Set(["XhrLoader", "FetchLoader"]);
+var BUILTIN_LOADER_REF = /* @__PURE__ */ Symbol.for(
+  "@codenkay/video-nsgplayer-core/builtin-hls-loader"
+);
+var builtinLoaderByHls = /* @__PURE__ */ new WeakMap();
 var KEY_PROXY_MAX_FAILURES = 2;
 function isEncryptionKeyUrl(rawUrl, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
   try {
@@ -777,18 +781,35 @@ function isEncryptionKeyUrl(rawUrl, baseOrigin = typeof location !== "undefined"
     return /enc\.key/i.test(rawUrl);
   }
 }
-function resolveBuiltinHlsLoader(HlsClass) {
-  if (typeof BuiltinXhrLoader === "function") {
-    return BuiltinXhrLoader;
+function isBuiltinLoaderName(name) {
+  return BUILTIN_LOADER_NAMES.has(name);
+}
+function rememberBuiltin(HlsClass, loader) {
+  if (isBuiltinLoaderName(typeof loader.name === "string" ? loader.name : "")) {
+    builtinLoaderByHls.set(HlsClass, loader);
   }
+  return loader;
+}
+function getStashedBuiltinLoader(loader) {
+  return loader[BUILTIN_LOADER_REF];
+}
+function resolveBuiltinHlsLoader(HlsModule) {
+  const HlsClass = HlsModule;
+  const cached = builtinLoaderByHls.get(HlsClass);
+  if (cached) return cached;
   const start = HlsClass.DefaultConfig.loader;
   let current = start;
   const seen = /* @__PURE__ */ new Set();
   while (current && !seen.has(current)) {
     seen.add(current);
     const name = typeof current.name === "string" ? current.name : "";
-    if (BUILTIN_LOADER_NAMES.has(name)) {
-      return current;
+    if (isBuiltinLoaderName(name)) {
+      return rememberBuiltin(HlsClass, current);
+    }
+    const stashed = getStashedBuiltinLoader(current);
+    if (stashed) {
+      current = stashed;
+      continue;
     }
     const parentCtor = Object.getPrototypeOf(current.prototype)?.constructor;
     if (!parentCtor || parentCtor === Object || parentCtor === Function) {
@@ -796,7 +817,8 @@ function resolveBuiltinHlsLoader(HlsClass) {
     }
     current = parentCtor;
   }
-  return start;
+  const fallback = builtinLoaderByHls.get(HlsClass);
+  return fallback ?? start;
 }
 function rewriteHlsRequestUrl(rawUrl, store, options = {}, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
   if (!rawUrl) return rawUrl;
@@ -844,67 +866,82 @@ function isProxyUpstreamBlocked(status, contentType, bodyHead, errorText) {
   }
   return false;
 }
-async function loadEncryptionKeyWithFetch(context, callbacks, accessToken, signal) {
-  const stats = createLoaderStats();
-  stats.loading.first = performance.now();
-  const headers = {
-    Accept: "*/*",
-    ...context.headers
-  };
-  if (accessToken) {
-    headers.Authorization = `Bearer ${accessToken}`;
-  }
-  const response = await fetch(context.url, {
-    method: "GET",
-    headers,
-    credentials: "omit",
-    cache: "no-store",
-    signal
-  });
-  if (!response.ok) {
-    callbacks.onError(
-      {
-        code: response.status,
-        text: response.statusText || `enc.key HTTP ${response.status}`
-      },
-      context,
+async function fetchEncryptionKeyBytes(url, accessToken, signal) {
+  const headers = accessToken ? { Authorization: `Bearer ${accessToken}`, Accept: "*/*" } : void 0;
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      ...headers ? { headers } : {},
+      credentials: "omit",
+      cache: "no-store",
+      signal
+    });
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: response.status,
+        text: response.statusText || `enc.key HTTP ${response.status}`,
+        cors: false,
+        response
+      };
+    }
+    const data = await response.arrayBuffer();
+    const head = new TextDecoder().decode(data.slice(0, 32));
+    if (/<!DOCTYPE|<html/i.test(head)) {
+      return {
+        ok: false,
+        status: 403,
+        text: "enc.key returned HTML (CDN challenge/block), not an AES key",
+        cors: false,
+        response
+      };
+    }
+    return {
+      ok: true,
+      data,
       response,
-      stats
-    );
-    return;
+      url: response.url || url
+    };
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      return {
+        ok: false,
+        status: 0,
+        text: "enc.key fetch aborted/timeout",
+        cors: false,
+        response: null
+      };
+    }
+    const cors = error instanceof TypeError || error instanceof Error && /Failed to fetch|NetworkError|CORS/i.test(error.message);
+    return {
+      ok: false,
+      status: 0,
+      text: error instanceof Error ? error.message : "enc.key fetch failed",
+      cors,
+      response: null
+    };
   }
-  const data = await response.arrayBuffer();
+}
+function reportKeySuccess(context, callbacks, result) {
+  const stats = createLoaderStats();
   const end = performance.now();
+  stats.loading.first = stats.loading.start;
   stats.loading.end = end;
-  stats.loaded = data.byteLength;
-  stats.total = data.byteLength;
-  const head = new TextDecoder().decode(data.slice(0, 32));
-  if (/<!DOCTYPE|<html/i.test(head)) {
-    callbacks.onError(
-      {
-        code: 403,
-        text: "enc.key returned HTML (CDN challenge/block), not an AES key"
-      },
-      context,
-      response,
-      stats
-    );
-    return;
-  }
+  stats.loaded = result.data.byteLength;
+  stats.total = result.data.byteLength;
   callbacks.onSuccess(
     {
-      url: response.url || context.url,
-      data,
-      code: response.status
+      url: result.url,
+      data: result.data,
+      code: result.response.status
     },
     stats,
     context,
-    response
+    result.response
   );
 }
 async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, state) {
   const stats = createLoaderStats();
-  stats.loading.first = performance.now();
   const canTryProxy = Boolean(plan.proxyUrl) && !state.circuitOpen && state.proxyFailures < plan.maxProxyFailures;
   if (canTryProxy && plan.proxyUrl) {
     while (!state.circuitOpen && state.proxyFailures < plan.maxProxyFailures && !signal.aborted) {
@@ -975,47 +1012,71 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
     }
     state.circuitOpen = true;
   }
-  if (plan.accessToken) {
-    try {
-      await loadEncryptionKeyWithFetch(
+  const queryResult = await fetchEncryptionKeyBytes(
+    plan.signedKeyUrl,
+    null,
+    signal
+  );
+  if (queryResult.ok) {
+    reportKeySuccess(
+      { ...context, url: plan.signedKeyUrl },
+      callbacks,
+      queryResult
+    );
+    return "ok";
+  }
+  const needsBearer = Boolean(plan.accessToken) && (queryResult.status === 401 || queryResult.status === 403 || // Browser-direct: opaque CORS/network on unsigned GET — try Bearer once
+  // Appextech allows ACAO + Authorization (AUTH_MODE=browser, no BFF).
+  queryResult.cors || queryResult.status === 0);
+  if (needsBearer && plan.accessToken) {
+    const bearerResult = await fetchEncryptionKeyBytes(
+      plan.signedKeyUrl,
+      plan.accessToken,
+      signal
+    );
+    if (bearerResult.ok) {
+      reportKeySuccess(
         { ...context, url: plan.signedKeyUrl },
         callbacks,
-        plan.accessToken,
-        signal
-      );
-      return "ok";
-    } catch (error) {
-      if (error instanceof DOMException && error.name === "AbortError") {
-        callbacks.onError(
-          { code: 0, text: "enc.key fetch aborted/timeout" },
-          { ...context, url: plan.signedKeyUrl },
-          null,
-          stats
-        );
-        return "ok";
-      }
-      if (error instanceof TypeError || error instanceof Error && /Failed to fetch|NetworkError|CORS/i.test(error.message)) {
-        return "try_xhr";
-      }
-      callbacks.onError(
-        {
-          code: 0,
-          text: error instanceof Error ? error.message : "enc.key Bearer fetch failed"
-        },
-        { ...context, url: plan.signedKeyUrl },
-        null,
-        stats
+        bearerResult
       );
       return "ok";
     }
+    if (bearerResult.cors || bearerResult.status === 0) {
+      return "try_xhr";
+    }
+    callbacks.onError(
+      {
+        code: bearerResult.status,
+        text: bearerResult.text
+      },
+      { ...context, url: plan.signedKeyUrl },
+      bearerResult.response,
+      stats
+    );
+    return "ok";
+  }
+  if (queryResult.cors || queryResult.status === 0) {
+    return "try_xhr";
   }
-  return "try_xhr";
+  callbacks.onError(
+    {
+      code: queryResult.status,
+      text: queryResult.text
+    },
+    { ...context, url: plan.signedKeyUrl },
+    queryResult.response,
+    stats
+  );
+  return "ok";
 }
-function createAuthParamsLoader(HlsClass, store, options = {}) {
+function createAuthParamsLoader(HlsModule, store, options = {}) {
+  const HlsClass = HlsModule;
   const BaseLoader = resolveBuiltinHlsLoader(HlsClass);
+  rememberBuiltin(HlsClass, BaseLoader);
   const maxProxyFailures = typeof options.keyProxyMaxFailures === "number" && options.keyProxyMaxFailures >= 0 ? options.keyProxyMaxFailures : KEY_PROXY_MAX_FAILURES;
   const keyProxyState = { proxyFailures: 0, circuitOpen: false };
-  return class AuthParamsLoader {
+  class AuthParamsLoader {
     constructor(config) {
       this.context = null;
       this.keyAbort = null;
@@ -1099,7 +1160,13 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
       }
       this.inner.load(context, config, callbacks);
     }
-  };
+  }
+  Object.defineProperty(AuthParamsLoader, BUILTIN_LOADER_REF, {
+    value: BaseLoader,
+    enumerable: false,
+    configurable: false
+  });
+  return AuthParamsLoader;
 }
 
 // src/streaming/HlsEngine.ts
@@ -1214,7 +1281,7 @@ var HlsEngine = class {
         if (!data.fatal) return;
       } else if (!data.fatal) {
         callbacks.onFatalError?.(
-          status ? `Encryption key load failed (HTTP ${status}).` : "Encryption key load failed (network/CORS). Ensure signed query params are applied, or use keyProxyUrlBuilder / getKeyAccessToken when the key host requires API Bearer."
+          status ? `Encryption key load failed (HTTP ${status}).` : "Encryption key load failed (network/CORS). For browser-direct mode the key host must allow CORS (and Authorization if Bearer is required). Otherwise use keyProxyUrlBuilder (same-origin BFF) when the server IP can reach Appextech."
         );
         return;
       }
@@ -1589,10 +1656,11 @@ function createVideoPlayer(options) {
         volume: config.player.volume,
         videoId: options.videoId,
         keyProxyUrlBuilder: config.streaming.keyProxyUrlBuilder,
-        // Enterprise AES key auth:
-        // 1) keyProxyUrlBuilder (same-origin BFF) when configured — max 2 failures
-        // 2) else getKeyAccessToken / AuthManager Bearer via browser fetch
-        // 3) else signed query + XHR (CDN hosts)
+        // Enterprise AES key auth (see authParamsLoader):
+        // 1) keyProxyUrlBuilder BFF — max 2 failures then circuit
+        // 2) signed-query fetch (no Bearer / no CORS preflight)
+        // 3) Bearer only on HTTP 401/403 when getKeyAccessToken is set
+        // 4) signed-query XHR fallback if fetch is CORS-blocked
         getKeyAccessToken: config.streaming.getKeyAccessToken ?? (() => authManager.getAccessToken()),
         keyProxyMaxFailures: config.streaming.keyProxyMaxFailures,
         hlsConfig: config.streaming.hls,