@nomercy-entertainment/nomercy-video-player 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [2.2.3] — 2026-09-25
+
+### Added
+
+- `disableClickToPause` in `setup()` stops a click from pausing the video.
+
+### Fixed
+
+- Streams added with `registerStream()` are now used for playback.
+- Playlist thumbnails load from the configured image URL.
+- Changing auth at runtime now applies to media requests.
+- Georgia subtitles fall back to a serif font, and subtitle colors match the palette.
+- One press of `?` opens the shortcuts overlay.
+- Cast artwork shows the right image, and the media-key option works.
+- The help key on a TV remote works.
+
+## [2.2.2] — 2026-09-04
+
+### Fixed
+
+- A 404 got the full retry ladder: thirty seconds of spinner on an episode that was never encoded, ending in the generic network error. The file is not late, it is absent, and no amount of waiting changes the answer; 410 is the same answer said more firmly. Both now get no retries and their own code, `core:stream/media-absent`, so a consumer can offer the next item instead of the dead-end overlay it shows for a decode failure. The code matches `CoreErrorCodes.MEDIA_ABSENT` in the Kotlin trio.
+- Georgia's subtitle-font fallback was `sans-serif`. Georgia is a serif face, so a client without it installed — Android carries none — fell back to the one font every other choice already draws, collapsing distinct options into each other.
+
+
 ## [2.2.1] — 2026-09-04
 
 ### Changed

package/dist/adapters/video-backend/IVideoBackend.d.ts

@@ -1,5 +1,11 @@
-import type { AudioTrack, AuthHeaderProvider, BackendLoaderState, BackendState, HdrOnSdrFallback, MinimalBackendEventPayload, QualityLevel, SubtitleCueChange, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core';
+import type { AudioTrack, AuthHeaderProvider, BackendLoaderState, BackendState, HdrOnSdrFallback, IStreamSource, MinimalBackendEventPayload, QualityLevel, SubtitleCueChange, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core';
 import type { HtmlPreloadMode } from '../../types.js';
+/**
+ * Asks the player's stream registry whether a consumer registered a factory for
+ * this URL. Returns a source to play it with, or `undefined` to let the backend
+ * handle the URL the way it always has.
+ */
+export type StreamResolver = (url: string, contentType?: string) => IStreamSource | undefined;
 /**
  * Per-event payload map. Each backend event has a fixed payload shape so
  * `IVideoBackend.on(event, fn)` narrows the listener's parameter type
@@ -136,6 +142,14 @@ export interface IVideoBackend {
      * stack omit it.
      */
     setAuthHeaderProvider?(provider: AuthHeaderProvider): void;
+    /**
+     * Wire the lookup that asks the player's stream registry whether a consumer
+     * has registered a factory for a URL. The backend calls it before its own
+     * HLS and progressive handling, and falls through to that handling when the
+     * lookup returns nothing, so a player with no registered factory behaves
+     * exactly as it did before. Optional — backends with no registry omit it.
+     */
+    setStreamResolver?(resolver: StreamResolver): void;
     /**
      * Consumer policy for an all-HDR item on a display that can't show HDR and
      * a backend that can't tone-map it. Optional — backends that never face the

package/dist/adapters/video-backend/html5.d.ts

@@ -1,15 +1,16 @@
 import type { AudioTrack, HdrOnSdrFallback, QualityLevel, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core';
 import type { HtmlPreloadMode } from '../../types.js';
-import type { BackendEventPayload, BackendState, IVideoBackend } from './IVideoBackend.js';
+import type { BackendEventPayload, BackendState, IVideoBackend, StreamResolver } from './IVideoBackend.js';
 import { MediaElementBackend } from '@nomercy-entertainment/nomercy-player-core';
 /**
  * Default video backend. Wraps an `<HTMLVideoElement>` for transport.
  *
- * HLS support: native pass-through when `canPlayType` reports support
- * (Safari / iOS), otherwise dynamically imports `hls.js` (peer dep — not
- * bundled; IIFE build externalises it as `window.Hls`, ESM build resolves
- * it from the consumer's node_modules) and attaches it. MSE / WebCodecs
- * backends ship later.
+ * HLS support: native pass-through when `canPlayType` reports support,
+ * otherwise dynamically imports `hls.js` and attaches it. `hls.js` is a
+ * runtime dependency of nomercy-player-core, not a peer dependency, so an
+ * npm consumer installs it without asking. The IIFE build externalizes it
+ * as `window.Hls`; the ESM build resolves it from node_modules. MSE /
+ * WebCodecs backends ship later.
  */
 export declare class Html5VideoBackend extends MediaElementBackend<HTMLVideoElement, BackendEventPayload> implements IVideoBackend {
     readonly kind: "html5";
@@ -137,6 +138,14 @@ export declare class Html5VideoBackend extends MediaElementBackend<HTMLVideoElem
     unload(): void;
     dispose(): void;
     private _teardownAudioGraph;
+    private _streamResolver?;
+    private _customSource?;
+    /**
+     * Wire the lookup that asks the player's stream registry for a consumer's
+     * factory. Without it the backend keeps its own HLS and progressive handling
+     * and a registered factory is never consulted.
+     */
+    setStreamResolver(resolver: StreamResolver): void;
     buffered(): number;
     videoWidth(): number;
     videoHeight(): number;

package/dist/adapters/video-backend/html5.js

@@ -6,7 +6,7 @@
 //  SPDX-License-Identifier: Apache-2.0
 // -----------------------------------------------------------------------------
 import { abrCeiling, appendAuthTokenParam, createAuthorizationXhrSetup, destroyHlsInstance, detectDisplayHdr, hdrDecision, isHls, MediaElementBackend, MediaFormatError, mediaFormatError, panePixels, resetMediaElement, sizeAbrCeiling, supportsNativeHls, } from '@nomercy-entertainment/nomercy-player-core';
-import { SOURCE_OUTAGE_BACKOFF_MS, sourceOutageRetryLimit } from './source-outage.js';
+import { isMediaAbsentStatus, MEDIA_ABSENT, SOURCE_OUTAGE_BACKOFF_MS, sourceOutageRetryLimit } from './source-outage.js';
 const CODEC_LABELS = [
     [/avc1|h264/i, 'H.264'],
     [/hvc1|hev1|h265/i, 'H.265 (HEVC)'],
@@ -34,11 +34,12 @@ function humanCodec(raw) {
 /**
  * Default video backend. Wraps an `<HTMLVideoElement>` for transport.
  *
- * HLS support: native pass-through when `canPlayType` reports support
- * (Safari / iOS), otherwise dynamically imports `hls.js` (peer dep — not
- * bundled; IIFE build externalises it as `window.Hls`, ESM build resolves
- * it from the consumer's node_modules) and attaches it. MSE / WebCodecs
- * backends ship later.
+ * HLS support: native pass-through when `canPlayType` reports support,
+ * otherwise dynamically imports `hls.js` and attaches it. `hls.js` is a
+ * runtime dependency of nomercy-player-core, not a peer dependency, so an
+ * npm consumer installs it without asking. The IIFE build externalizes it
+ * as `window.Hls`; the ESM build resolves it from node_modules. MSE /
+ * WebCodecs backends ship later.
  */
 export class Html5VideoBackend extends MediaElementBackend {
     kind = 'html5';
@@ -238,6 +239,21 @@ export class Html5VideoBackend extends MediaElementBackend {
         resetMediaElement(this.element);
         performance.mark('nm:backend:load:start');
         const headerValue = this._authHeaderProvider?.(url);
+        // A consumer's factory is asked first, because the branches below cover
+        // only HLS and whatever the element itself decodes. Nothing registered
+        // means nothing returned, and the built-in path runs untouched.
+        if (this._customSource) {
+            this._customSource.destroy();
+            this._customSource = undefined;
+        }
+        const customSource = this._streamResolver?.(url);
+        if (customSource) {
+            this._customSource = customSource;
+            await customSource.attach(this.element);
+            this._state = 'ready';
+            performance.mark('nm:backend:load:end');
+            return;
+        }
         if (hlsUrl && !nativeHls) {
             const { default: Hls } = await import('hls.js');
             if (!Hls?.isSupported?.()) {
@@ -349,6 +365,16 @@ export class Html5VideoBackend extends MediaElementBackend {
     // playbackRate / volume / mute / unmute / captureStream / setSinkId /
     // getSinkId / mediaKeys / setMediaKeys / mediaElement / pauseLoader /
     // resumeLoader / loaderState / setAuthHeaderProvider
+    _streamResolver;
+    _customSource;
+    /**
+     * Wire the lookup that asks the player's stream registry for a consumer's
+     * factory. Without it the backend keeps its own HLS and progressive handling
+     * and a registered factory is never consulted.
+     */
+    setStreamResolver(resolver) {
+        this._streamResolver = resolver;
+    }
     // ── Time / position (video-specific: buffered uses currentTime walk) ──
     buffered() {
         const ranges = this.element.buffered;
@@ -381,7 +407,9 @@ export class Html5VideoBackend extends MediaElementBackend {
                 default: hlsAudioTrack.default === true,
             }));
         }
-        // Native: HTMLMediaElement.audioTracks (Safari/Chrome with multi-audio).
+        // Native: HTMLMediaElement.audioTracks. Measured absent in Chrome 152,
+        // Edge 152 and bundled Chromium, so this branch is Safari in practice
+        // and yields [] elsewhere; the HLS path above is what fills the list.
         const nativeTracks = this.element.audioTracks;
         if (nativeTracks && nativeTracks.length > 0) {
             const out = [];
@@ -860,6 +888,15 @@ export class Html5VideoBackend extends MediaElementBackend {
         if (httpStatus === 0)
             this._sawConnectionFailure = true;
         const limit = sourceOutageRetryLimit(httpStatus, this._sawConnectionFailure);
+        // The server answered that this item has no media. Waiting cannot change
+        // that, and a consumer can act on it — offer the next item — but only if
+        // it is told which failure this was, so it gets its own code rather than
+        // the generic network one every outage ends with.
+        if (isMediaAbsentStatus(httpStatus) && !this._sawConnectionFailure) {
+            this._recoveringFromOutage = false;
+            this._escalateHlsError(MEDIA_ABSENT, `media absent (HTTP ${httpStatus}): ${data.details}`);
+            return;
+        }
         if (this._netRetryCount >= limit) {
             // The ladder is spent, but a device that gets a route back later
             // still deserves its session rather than a dead error overlay.

package/dist/adapters/video-backend/source-outage.d.ts

@@ -45,9 +45,26 @@ export declare function sourceOutageBudgetMs(): number;
  * connection-failure-gated budget would cut short.
  */
 export declare function isOriginDownStatus(httpStatus: number): boolean;
+/** No rung at all: the answer will not change by asking again. */
+export declare const NO_RETRIES = 0;
+/**
+ * True for a status that means the server answered, and answered that this
+ * media does not exist.
+ *
+ * An episode that has not been encoded yet answers 404, and it will answer 404
+ * to every retry: the file is not late, it is absent. Waiting is not a strategy
+ * for it, and the viewer is the only one who can decide what to do instead.
+ * 410 is the same answer said more firmly.
+ */
+export declare function isMediaAbsentStatus(httpStatus: number): boolean;
 /**
  * How many rungs this failure is allowed.
  *
+ * A 404 gets NONE. It used to get five, which is thirty seconds of spinner on
+ * an episode that was never encoded, and at the end of it the viewer was told
+ * nothing they could act on. A definite answer is worth surfacing the moment it
+ * arrives, so the consumer can offer to move to the next item.
+ *
  * @param httpStatus - The status the load gave up on, or 0 when the failure
  *   carried no response at all, which is what a refused connection looks like
  *   from a browser.
@@ -56,3 +73,10 @@ export declare function isOriginDownStatus(httpStatus: number): boolean;
  *   from a video that is genuinely gone.
  */
 export declare function sourceOutageRetryLimit(httpStatus: number, sawConnectionFailure: boolean): number;
+/**
+ * The code a consumer reads to offer "skip to the next item" rather than a dead
+ * end. Its Kotlin peer is `CoreErrorCodes.MEDIA_ABSENT`; the two trios must
+ * name this the same failure or a client written against one is wrong on the
+ * other.
+ */
+export declare const MEDIA_ABSENT = "core:stream/media-absent";

package/dist/adapters/video-backend/source-outage.js

@@ -63,9 +63,28 @@ export function isOriginDownStatus(httpStatus) {
         || httpStatus === 503
         || httpStatus === 504;
 }
+/** No rung at all: the answer will not change by asking again. */
+export const NO_RETRIES = 0;
+/**
+ * True for a status that means the server answered, and answered that this
+ * media does not exist.
+ *
+ * An episode that has not been encoded yet answers 404, and it will answer 404
+ * to every retry: the file is not late, it is absent. Waiting is not a strategy
+ * for it, and the viewer is the only one who can decide what to do instead.
+ * 410 is the same answer said more firmly.
+ */
+export function isMediaAbsentStatus(httpStatus) {
+    return httpStatus === 404 || httpStatus === 410;
+}
 /**
  * How many rungs this failure is allowed.
  *
+ * A 404 gets NONE. It used to get five, which is thirty seconds of spinner on
+ * an episode that was never encoded, and at the end of it the viewer was told
+ * nothing they could act on. A definite answer is worth surfacing the moment it
+ * arrives, so the consumer can offer to move to the next item.
+ *
  * @param httpStatus - The status the load gave up on, or 0 when the failure
  *   carried no response at all, which is what a refused connection looks like
  *   from a browser.
@@ -74,11 +93,22 @@ export function isOriginDownStatus(httpStatus) {
  *   from a video that is genuinely gone.
  */
 export function sourceOutageRetryLimit(httpStatus, sawConnectionFailure) {
+    // A connection failure first means the host went away; the 404 that follows
+    // is a route table still warming up, not a missing file.
     if (sawConnectionFailure)
         return SOURCE_OUTAGE_BACKOFF_MS.length;
     if (isOriginDownStatus(httpStatus))
         return SOURCE_OUTAGE_BACKOFF_MS.length;
+    if (isMediaAbsentStatus(httpStatus))
+        return NO_RETRIES;
     if (httpStatus > 0)
         return HTTP_STATUS_RETRY_LIMIT;
     return SOURCE_OUTAGE_BACKOFF_MS.length;
 }
+/**
+ * The code a consumer reads to offer "skip to the next item" rather than a dead
+ * end. Its Kotlin peer is `CoreErrorCodes.MEDIA_ABSENT`; the two trios must
+ * name this the same failure or a client written against one is wrong on the
+ * other.
+ */
+export const MEDIA_ABSENT = 'core:stream/media-absent';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { ActionOptions, AriaLiveLevel, AudioTrack, AuthConfig, BasePlaylistItem, BufferState, CanPlayResult, CastState, CastTarget, Chapter, CurrentAudioTrackSelection, CurrentQualitySelection, CurrentSubtitleSelection, DeviceCapabilities, ICueParser, IPlatform, IPlayer, IPreloadStrategy, IStreamFactory, ITransitionStrategy, IUrlResolver, TimeState as KitTimeState, LoadOptions, NetworkState, PlaybackMetrics, PlayerExperimental, PlayerPhase, Plugin, PluginCtorWithId, QualityLevel, ResolvedUrl, SetupState, SidecarSubtitleInput, SubtitleStyle, SubtitleTrack, Translations, UrlCategory, VisibilityState } from '@nomercy-entertainment/nomercy-player-core';
+import type { ActionOptions, AriaLiveLevel, AudioTrack, AuthConfig, BasePlaylistItem, BufferState, CanPlayResult, CastState, CastTarget, Chapter, CurrentAudioTrackSelection, CurrentQualitySelection, CurrentSubtitleSelection, DeviceCapabilities, ICueParser, IPlatform, IPlayer, IPreloadStrategy, IStreamFactory, IStreamSource, ITransitionStrategy, IUrlResolver, TimeState as KitTimeState, LoadOptions, NetworkState, PlaybackMetrics, PlayerExperimental, PlayerPhase, Plugin, PluginCtorWithId, QualityLevel, ResolvedUrl, SetupState, SidecarSubtitleInput, SubtitleStyle, SubtitleTrack, Translations, UrlCategory, VisibilityState } from '@nomercy-entertainment/nomercy-player-core';
 import type { IVideoBackend, VideoBackendKind } from './adapters/video-backend/IVideoBackend.js';
 import type { AudioTrackState, IVideoPlayer, PlayState, QualityState, RepeatState, SegmentOptions, ShuffleState, Stretching, VideoEventMap, VideoPlayerConfig, VideoPlaylistItem, VideoRect, VolumeState } from './types.js';
 import { EventEmitter } from '@nomercy-entertainment/nomercy-player-core';
@@ -200,12 +200,15 @@ export declare class NMVideoPlayer<T extends VideoPlaylistItem = VideoPlaylistIt
      * `mediaReady` fires so the backend's track lists are populated.
      *
      * Language matching: exact tag first, then prefix (e.g. `'en'` matches
-     * `'en-US'`). No match → leave selection at off; no warning emitted.
+     * `'en-US'`). No match leaves an UNSELECTED slot alone, but where a track is
+     * already selected the slot is handed to the stream's own default rendition
+     * instead. No warning either way.
      */
     private _applyDefaultTracks;
     /** Test-only: clear the registry. Not part of the public API. */
     static _resetRegistry(): void;
     registerStream: (factory: IStreamFactory, prepend?: boolean) => this;
+    resolveCustomStream: (url: string, contentType?: string) => IStreamSource | undefined;
     unregisterStream: (id: string) => this;
     streams: () => ReadonlyArray<string>;
     getStreamFactory: (id: string) => IStreamFactory | undefined;

package/dist/index.js

@@ -212,7 +212,9 @@ export class NMVideoPlayer extends EventEmitter {
      * `mediaReady` fires so the backend's track lists are populated.
      *
      * Language matching: exact tag first, then prefix (e.g. `'en'` matches
-     * `'en-US'`). No match → leave selection at off; no warning emitted.
+     * `'en-US'`). No match leaves an UNSELECTED slot alone, but where a track is
+     * already selected the slot is handed to the stream's own default rendition
+     * instead. No warning either way.
      */
     _applyDefaultTracks() {
         const remembered = this.languageMemory.subtitleChoice();
@@ -308,7 +310,14 @@ export class NMVideoPlayer extends EventEmitter {
         // lazily so getter-style tokens (Vue refs, stores) stay live.
         // Read per request rather than captured, so a consumer whose token or
         // rule changes mid-session is not answered from a stale closure.
-        instance.setAuthHeaderProvider?.((url) => this.options?.auth?.mediaAuthorization?.(url));
+        // Live config, not `options.auth`: setup seeds it and `player.auth()`
+        // updates it, so a rule set after setup reaches media requests too.
+        instance.setAuthHeaderProvider?.((url) => this.auth()?.mediaAuthorization?.(url));
+        // Without this the stream registry is seeded and never asked, so
+        // `registerStream` records a factory that no load path consults. Only
+        // consumer-registered factories are offered: HLS and progressive files
+        // stay on the backend's own path exactly as before.
+        instance.setStreamResolver?.((url, contentType) => this.resolveCustomStream?.(url, contentType));
         // Consumer's HDR-on-SDR policy, read once here rather than normalized
         // into `options` — `hdrDecision`'s own default ('play') applies at the
         // point of use when this was never pushed at all.