@codenkay/video-nsgplayer-core 3.0.2 → 4.0.0

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.2";
+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>;
@@ -449,17 +452,6 @@ type HlsEngineOptions = {
     logger: Logger;
     callbacks: HlsEngineCallbacks;
 };
-/**
- * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
- *
- * Signed CDN playback requires auth query params on every HLS request
- * (playlists, segments, and AES `enc.key` on CDN hosts).
- *
- * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
- * `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 {
     private readonly options;
     private hls;
@@ -474,10 +466,17 @@ declare class HlsEngine {
     private audioTracks;
     private audioTrackSelection;
     private nativeTextTrackCleanup;
+    private startPositionApplied;
+    private autoplayApplied;
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
     private handleHlsError;
+    /** Pin the next load to the lowest ladder rung after MSE append failures. */
+    private lockPlaybackToSafeLevel;
+    private clampStartPosition;
+    private applyStartPositionOnly;
+    private applyAutoplayOnly;
     private applyStartPositionAndAutoplay;
     private bindMediaEvents;
     updateAuthParams(): void;
@@ -654,6 +653,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;
@@ -663,6 +710,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 = {
@@ -678,7 +727,7 @@ declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolea
  * 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.
  */
@@ -686,7 +735,7 @@ declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, op
 /**
  * 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;
 /**
@@ -695,4 +744,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.2";
+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>;
@@ -449,17 +452,6 @@ type HlsEngineOptions = {
     logger: Logger;
     callbacks: HlsEngineCallbacks;
 };
-/**
- * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
- *
- * Signed CDN playback requires auth query params on every HLS request
- * (playlists, segments, and AES `enc.key` on CDN hosts).
- *
- * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
- * `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 {
     private readonly options;
     private hls;
@@ -474,10 +466,17 @@ declare class HlsEngine {
     private audioTracks;
     private audioTrackSelection;
     private nativeTextTrackCleanup;
+    private startPositionApplied;
+    private autoplayApplied;
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
     private handleHlsError;
+    /** Pin the next load to the lowest ladder rung after MSE append failures. */
+    private lockPlaybackToSafeLevel;
+    private clampStartPosition;
+    private applyStartPositionOnly;
+    private applyAutoplayOnly;
     private applyStartPositionAndAutoplay;
     private bindMediaEvents;
     updateAuthParams(): void;
@@ -654,6 +653,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;
@@ -663,6 +710,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 = {
@@ -678,7 +727,7 @@ declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolea
  * 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.
  */
@@ -686,7 +735,7 @@ declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, op
 /**
  * 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;
 /**
@@ -695,4 +744,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 };