@nomercy-entertainment/nomercy-video-player 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [2.1.0] — 2026-08-20
+
+### Added
+
+- Re-exports `volumeMemoryPlugin` / `VolumeMemoryPlugin` from `@nomercy-entertainment/nomercy-player-core@2.1.0`, alongside the rest of the kit's audio-graph plugins.
+- New `./adapters` subpath export.
+
+### Fixed
+
+- A server that went away is now ridden out as an outage rather than treated as a dead file.
+
+### Changed
+
+- Built against `@nomercy-entertainment/nomercy-player-core@2.1.0`.
+
 ## [2.0.3] — 2026-07-31
 
 ### Fixed

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

@@ -1,4 +1,4 @@
-import type { AudioTrack, BackendLoaderState, BackendState, HdrOnSdrFallback, MinimalBackendEventPayload, QualityLevel, SubtitleCueChange, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core';
+import type { AudioTrack, AuthHeaderProvider, BackendLoaderState, BackendState, HdrOnSdrFallback, MinimalBackendEventPayload, QualityLevel, SubtitleCueChange, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core';
 import type { HtmlPreloadMode } from '../../types.js';
 /**
  * Per-event payload map. Each backend event has a fixed payload shape so
@@ -135,7 +135,7 @@ export interface IVideoBackend {
      * manifests/segments). Optional — backends without their own network
      * stack omit it.
      */
-    setAuthHeaderProvider?(provider: () => string | undefined | Promise<string | undefined>): void;
+    setAuthHeaderProvider?(provider: AuthHeaderProvider): 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

@@ -40,6 +40,23 @@ export declare class Html5VideoBackend extends MediaElementBackend<HTMLVideoElem
     private _mediaRecoveryStartMs;
     /** Timer handle for exponential back-off retries. Cleared on unload/dispose. */
     private _retryTimer;
+    /**
+     * Whether this outage already failed below the HTTP layer, which is what
+     * tells a restarting server's 404 apart from a video that is genuinely gone.
+     */
+    private _sawConnectionFailure;
+    /**
+     * True while the ladder is riding out a source the server stopped serving.
+     *
+     * The backend is the first thing a consumer has that learns the origin is
+     * gone: it asks for bytes constantly, while a realtime socket through the
+     * same tunnel can stay up long after the server behind it died. An app
+     * watches this to raise its own server-offline screen on the player's
+     * evidence rather than waiting for a socket that may never drop.
+     */
+    private _recoveringFromOutage;
+    /** Retries the moment the device has a route again, rather than waiting out a rung. */
+    private _onlineHandler;
     private _sourceNode?;
     private _sourceCtx?;
     private _analyserNode?;
@@ -213,6 +230,30 @@ export declare class Html5VideoBackend extends MediaElementBackend<HTMLVideoElem
     private wireElementEvents;
     /** Reset all recovery counters. Call on successful playback resume or unload. */
     private _resetRecoveryState;
+    /**
+     * True while the ladder is riding out a source the server stopped serving —
+     * see `_recoveringFromOutage`. A consumer probes server reachability on this
+     * so its own offline screen rises from the evidence that arrives first.
+     */
+    get isRecoveringFromOutage(): boolean;
+    /**
+     * A server that went away is an outage to ride out, not a dead file.
+     *
+     * Escalating after three tries over seven seconds is what made a host
+     * restart read to a viewer as a broken film: the ladder was spent before
+     * the server had finished booting. The budget now matches how long a real
+     * restart takes, and how many rungs a failure earns depends on what it was
+     * — an origin-down status or a refused connection gets all of them, a cold
+     * 4xx gets five, because a URL that is genuinely gone answers the same way
+     * every time and a viewer should be told so rather than shown a spinner.
+     */
+    private _rideOutNetworkError;
+    /**
+     * Retries the moment the device has a route again, so an outage longer than
+     * the ladder still ends in playback. Without it a Wi-Fi drop that outlasts
+     * the budget leaves the session unrecoverable until the viewer reloads.
+     */
+    private _watchForConnectivityReturn;
     /**
      * Escalate a fatal HLS error to a player-level error event.
      *
@@ -227,8 +268,8 @@ export declare class Html5VideoBackend extends MediaElementBackend<HTMLVideoElem
      *
      * Decision tree per hls.js error semantics:
      * - Non-fatal → emit `stream:error` with `fatal: false`, no escalation.
-     * - Fatal NETWORK → retry `hls.startLoad()` up to 3× with exponential
-     *   back-off (1 s, 2 s, 4 s). If exhausted, escalate.
+     * - Fatal NETWORK → ride the outage out on `SOURCE_OUTAGE_BACKOFF_MS`,
+     *   for as many rungs as the failure earns. If exhausted, escalate.
      * - Fatal MEDIA → call `hls.recoverMediaError()`. If a second media
      *   error fires within 5 s, escalate.
      * - Fatal MUX / other → destroy + reload via `load()`. If that fails, escalate.

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

@@ -6,6 +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';
 const CODEC_LABELS = [
     [/avc1|h264/i, 'H.264'],
     [/hvc1|hev1|h265/i, 'H.265 (HEVC)'],
@@ -69,6 +70,23 @@ export class Html5VideoBackend extends MediaElementBackend {
     _mediaRecoveryStartMs = 0;
     /** Timer handle for exponential back-off retries. Cleared on unload/dispose. */
     _retryTimer;
+    /**
+     * Whether this outage already failed below the HTTP layer, which is what
+     * tells a restarting server's 404 apart from a video that is genuinely gone.
+     */
+    _sawConnectionFailure = false;
+    /**
+     * True while the ladder is riding out a source the server stopped serving.
+     *
+     * The backend is the first thing a consumer has that learns the origin is
+     * gone: it asks for bytes constantly, while a realtime socket through the
+     * same tunnel can stay up long after the server behind it died. An app
+     * watches this to raise its own server-offline screen on the player's
+     * evidence rather than waiting for a socket that may never drop.
+     */
+    _recoveringFromOutage = false;
+    /** Retries the moment the device has a route again, rather than waiting out a rung. */
+    _onlineHandler;
     // ── Web Audio graph ──────────────────────────────────────────────────────
     _sourceNode;
     _sourceCtx;
@@ -219,7 +237,7 @@ export class Html5VideoBackend extends MediaElementBackend {
         // what produces the ~8 s stall on auto-advance.
         resetMediaElement(this.element);
         performance.mark('nm:backend:load:start');
-        const headerValue = await this._authHeaderProvider?.();
+        const headerValue = this._authHeaderProvider?.(url);
         if (hlsUrl && !nativeHls) {
             const { default: Hls } = await import('hls.js');
             if (!Hls?.isSupported?.()) {
@@ -239,7 +257,7 @@ export class Html5VideoBackend extends MediaElementBackend {
                 enableCEA708Captions: true,
                 startPosition: typeof opts?.startTime === 'number' && opts.startTime > 0 ? opts.startTime : -1,
                 startFragPrefetch: true,
-                xhrSetup: createAuthorizationXhrSetup(headerValue),
+                xhrSetup: createAuthorizationXhrSetup(this._authHeaderProvider),
             });
             this.hls = hlsInstance;
             this.hlsInstance = hlsInstance;
@@ -811,6 +829,92 @@ export class Html5VideoBackend extends MediaElementBackend {
         }
         this._netRetryCount = 0;
         this._mediaRecoveryStartMs = 0;
+        this._sawConnectionFailure = false;
+        this._recoveringFromOutage = false;
+        if (this._onlineHandler !== undefined) {
+            globalThis.removeEventListener?.('online', this._onlineHandler);
+            this._onlineHandler = undefined;
+        }
+    }
+    /**
+     * True while the ladder is riding out a source the server stopped serving —
+     * see `_recoveringFromOutage`. A consumer probes server reachability on this
+     * so its own offline screen rises from the evidence that arrives first.
+     */
+    get isRecoveringFromOutage() {
+        return this._recoveringFromOutage;
+    }
+    /**
+     * A server that went away is an outage to ride out, not a dead file.
+     *
+     * Escalating after three tries over seven seconds is what made a host
+     * restart read to a viewer as a broken film: the ladder was spent before
+     * the server had finished booting. The budget now matches how long a real
+     * restart takes, and how many rungs a failure earns depends on what it was
+     * — an origin-down status or a refused connection gets all of them, a cold
+     * 4xx gets five, because a URL that is genuinely gone answers the same way
+     * every time and a viewer should be told so rather than shown a spinner.
+     */
+    _rideOutNetworkError(data) {
+        const httpStatus = data.response?.code ?? 0;
+        if (httpStatus === 0)
+            this._sawConnectionFailure = true;
+        const limit = sourceOutageRetryLimit(httpStatus, this._sawConnectionFailure);
+        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.
+            this._watchForConnectivityReturn();
+            this._recoveringFromOutage = false;
+            this._escalateHlsError(data.details, `HLS network error after ${limit} retries: ${data.details}`);
+            return;
+        }
+        // An outage on THIS device's side is not evidence that the server is
+        // gone, so it must not spend the budget — a two-minute Wi-Fi drop would
+        // burn the whole ladder without a single attempt ever having a route to
+        // try. Hold at the current rung and let the `online` event take over.
+        const deviceOffline = globalThis.navigator?.onLine === false;
+        const attempt = this._netRetryCount;
+        if (!deviceOffline)
+            this._netRetryCount = attempt + 1;
+        this._watchForConnectivityReturn();
+        this._recoveringFromOutage = true;
+        this.emit('stream:recovering', { details: data.details, attempt: attempt + 1, maxAttempts: limit });
+        this._retryTimer = setTimeout(() => {
+            this._retryTimer = undefined;
+            if (!this.hls)
+                return;
+            try {
+                this.hls.startLoad();
+            }
+            catch {
+                this._escalateHlsError(data.details, `HLS startLoad failed: ${data.details}`);
+            }
+        }, SOURCE_OUTAGE_BACKOFF_MS[attempt]);
+    }
+    /**
+     * Retries the moment the device has a route again, so an outage longer than
+     * the ladder still ends in playback. Without it a Wi-Fi drop that outlasts
+     * the budget leaves the session unrecoverable until the viewer reloads.
+     */
+    _watchForConnectivityReturn() {
+        if (this._onlineHandler !== undefined)
+            return;
+        this._onlineHandler = () => {
+            // A fresh outage deserves the whole ladder: the attempts spent
+            // waiting for the network to come back say nothing about whether
+            // the server answers now.
+            this._netRetryCount = 0;
+            this._sawConnectionFailure = false;
+            if (this._retryTimer !== undefined) {
+                clearTimeout(this._retryTimer);
+                this._retryTimer = undefined;
+            }
+            try {
+                this.hls?.startLoad();
+            }
+            catch { /* the ladder's next failure reports it; a throw here is not the viewer's problem */ }
+        };
+        globalThis.addEventListener?.('online', this._onlineHandler);
     }
     /**
      * Escalate a fatal HLS error to a player-level error event.
@@ -836,8 +940,8 @@ export class Html5VideoBackend extends MediaElementBackend {
      *
      * Decision tree per hls.js error semantics:
      * - Non-fatal → emit `stream:error` with `fatal: false`, no escalation.
-     * - Fatal NETWORK → retry `hls.startLoad()` up to 3× with exponential
-     *   back-off (1 s, 2 s, 4 s). If exhausted, escalate.
+     * - Fatal NETWORK → ride the outage out on `SOURCE_OUTAGE_BACKOFF_MS`,
+     *   for as many rungs as the failure earns. If exhausted, escalate.
      * - Fatal MEDIA → call `hls.recoverMediaError()`. If a second media
      *   error fires within 5 s, escalate.
      * - Fatal MUX / other → destroy + reload via `load()`. If that fails, escalate.
@@ -848,7 +952,6 @@ export class Html5VideoBackend extends MediaElementBackend {
     _attachHlsErrorHandler(Hls, url) {
         if (!this.hls)
             return;
-        const MAX_NET_RETRIES = 3;
         this.hls.on(Hls.Events.ERROR, (_e, data) => {
             if (!data.fatal) {
                 if (data.details === 'bufferIncompatibleCodecsError') {
@@ -868,24 +971,7 @@ export class Html5VideoBackend extends MediaElementBackend {
                 return;
             }
             if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
-                if (this._netRetryCount >= MAX_NET_RETRIES) {
-                    this._escalateHlsError(data.details, `HLS network error after ${MAX_NET_RETRIES} retries: ${data.details}`);
-                    return;
-                }
-                this._netRetryCount++;
-                const delayMs = 1_000 * (2 ** (this._netRetryCount - 1)); // 1s, 2s, 4s
-                this.emit('stream:recovering', { details: data.details, attempt: this._netRetryCount, maxAttempts: MAX_NET_RETRIES });
-                this._retryTimer = setTimeout(() => {
-                    this._retryTimer = undefined;
-                    if (!this.hls)
-                        return;
-                    try {
-                        this.hls.startLoad();
-                    }
-                    catch {
-                        this._escalateHlsError(data.details, `HLS startLoad failed: ${data.details}`);
-                    }
-                }, delayMs);
+                this._rideOutNetworkError(data);
             }
             else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
                 const now = Date.now();

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

@@ -0,0 +1,58 @@
+/**
+ * Telling "the bytes are not there right now" apart from "this media is broken".
+ *
+ * A media-server restart produces two failure shapes in one outage:
+ * connection-refused while the host is down, then a bad HTTP status the moment
+ * it is listening again but has not finished mapping its routes. Treating only
+ * the first as recoverable ends the restart on a 404 no retry ladder ever sees,
+ * and the session dies under an error overlay while the server is two seconds
+ * from answering again.
+ *
+ * The previous ladder here was three tries over seven seconds, which is shorter
+ * than a .NET host takes to warm EF Core and reload its plugins — so the common
+ * case, a server the viewer themselves just restarted, always lost.
+ *
+ * Kept separate from the backend so the decision can be checked without a
+ * browser: every answer below is a number-to-verdict lookup, and a lookup that
+ * has drifted is invisible in a screenshot. Playback still fails, it just fails
+ * for a reason nobody chose.
+ */
+/**
+ * Backoff for re-loading after the server drops out mid-playback. Starts tight
+ * so a momentary blip is invisible, then settles to a steady 15 s poll — long
+ * enough to sit out a host restart without hammering a server that is still
+ * booting. The ladder's length IS the give-up budget (~105 s); past that the
+ * failure is real and the error surfaces.
+ */
+export declare const SOURCE_OUTAGE_BACKOFF_MS: readonly number[];
+/**
+ * Rungs an HTTP-status failure gets when nothing connection-level preceded it
+ * (~30 s). A video whose URL is genuinely gone answers 404 identically every
+ * time, and making the viewer watch a spinner for the full budget before being
+ * told so is its own bug.
+ */
+export declare const HTTP_STATUS_RETRY_LIMIT = 5;
+/** Total wall-clock the ladder covers before a failure is treated as real. */
+export declare function sourceOutageBudgetMs(): number;
+/**
+ * True for a status that means "the server is not there", as opposed to "the
+ * server is there and this file is not".
+ *
+ * Measured on a real outage: a NoMercy server behind cloudflared never refuses
+ * a connection while it restarts — the edge answers 530, and 52x for its other
+ * failure modes. So the shape a restart actually takes is a bad HTTP status
+ * with no connection error anywhere in front of it, which is exactly the case a
+ * connection-failure-gated budget would cut short.
+ */
+export declare function isOriginDownStatus(httpStatus: number): boolean;
+/**
+ * How many rungs this failure is allowed.
+ *
+ * @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.
+ * @param sawConnectionFailure - Whether anything in this outage already failed
+ *   below the HTTP layer. That is what tells a restarting server's 404 apart
+ *   from a video that is genuinely gone.
+ */
+export declare function sourceOutageRetryLimit(httpStatus: number, sawConnectionFailure: boolean): number;

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

@@ -0,0 +1,84 @@
+/**
+ * Telling "the bytes are not there right now" apart from "this media is broken".
+ *
+ * A media-server restart produces two failure shapes in one outage:
+ * connection-refused while the host is down, then a bad HTTP status the moment
+ * it is listening again but has not finished mapping its routes. Treating only
+ * the first as recoverable ends the restart on a 404 no retry ladder ever sees,
+ * and the session dies under an error overlay while the server is two seconds
+ * from answering again.
+ *
+ * The previous ladder here was three tries over seven seconds, which is shorter
+ * than a .NET host takes to warm EF Core and reload its plugins — so the common
+ * case, a server the viewer themselves just restarted, always lost.
+ *
+ * Kept separate from the backend so the decision can be checked without a
+ * browser: every answer below is a number-to-verdict lookup, and a lookup that
+ * has drifted is invisible in a screenshot. Playback still fails, it just fails
+ * for a reason nobody chose.
+ */
+/**
+ * Backoff for re-loading after the server drops out mid-playback. Starts tight
+ * so a momentary blip is invisible, then settles to a steady 15 s poll — long
+ * enough to sit out a host restart without hammering a server that is still
+ * booting. The ladder's length IS the give-up budget (~105 s); past that the
+ * failure is real and the error surfaces.
+ */
+export const SOURCE_OUTAGE_BACKOFF_MS = [
+    1_000,
+    2_000,
+    4_000,
+    8_000,
+    15_000,
+    15_000,
+    15_000,
+    15_000,
+    15_000,
+    15_000,
+];
+/**
+ * Rungs an HTTP-status failure gets when nothing connection-level preceded it
+ * (~30 s). A video whose URL is genuinely gone answers 404 identically every
+ * time, and making the viewer watch a spinner for the full budget before being
+ * told so is its own bug.
+ */
+export const HTTP_STATUS_RETRY_LIMIT = 5;
+/** Total wall-clock the ladder covers before a failure is treated as real. */
+export function sourceOutageBudgetMs() {
+    return SOURCE_OUTAGE_BACKOFF_MS.reduce((total, rung) => total + rung, 0);
+}
+/**
+ * True for a status that means "the server is not there", as opposed to "the
+ * server is there and this file is not".
+ *
+ * Measured on a real outage: a NoMercy server behind cloudflared never refuses
+ * a connection while it restarts — the edge answers 530, and 52x for its other
+ * failure modes. So the shape a restart actually takes is a bad HTTP status
+ * with no connection error anywhere in front of it, which is exactly the case a
+ * connection-failure-gated budget would cut short.
+ */
+export function isOriginDownStatus(httpStatus) {
+    return (httpStatus >= 520 && httpStatus <= 530)
+        || httpStatus === 502
+        || httpStatus === 503
+        || httpStatus === 504;
+}
+/**
+ * How many rungs this failure is allowed.
+ *
+ * @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.
+ * @param sawConnectionFailure - Whether anything in this outage already failed
+ *   below the HTTP layer. That is what tells a restarting server's 404 apart
+ *   from a video that is genuinely gone.
+ */
+export function sourceOutageRetryLimit(httpStatus, sawConnectionFailure) {
+    if (sawConnectionFailure)
+        return SOURCE_OUTAGE_BACKOFF_MS.length;
+    if (isOriginDownStatus(httpStatus))
+        return SOURCE_OUTAGE_BACKOFF_MS.length;
+    if (httpStatus > 0)
+        return HTTP_STATUS_RETRY_LIMIT;
+    return SOURCE_OUTAGE_BACKOFF_MS.length;
+}

package/dist/index.d.ts

@@ -103,10 +103,6 @@ export declare class NMVideoPlayer<T extends VideoPlaylistItem = VideoPlaylistIt
     timeData: () => KitTimeState;
     /** Seek to a position expressed as a percentage (0–100) of total duration. */
     seekByPercentage: (pct: number, opts?: ActionOptions) => void;
-    /** @internal */
-    private _checkItemEndingSoon;
-    /** @internal */
-    private _timeStateAt;
     playbackRate: {
         (): number;
         (rate: number): Promise<void>;
@@ -256,7 +252,6 @@ export declare class NMVideoPlayer<T extends VideoPlaylistItem = VideoPlaylistIt
     togglePip(): void;
     toggleTheater(): void;
     cycleSubtitles(): void;
-    cycleAudioTracks(): void;
     private _aspectRatio;
     private static readonly _OBJECT_FIT_MAP;
     aspectRatio(): Stretching;
@@ -333,6 +328,8 @@ export declare class NMVideoPlayer<T extends VideoPlaylistItem = VideoPlaylistIt
         (): CurrentAudioTrackSelection | null;
         (idx: number): Promise<void>;
     };
+    /** Composed in via `mediaTracksMethods` — see that mixin for the full contract. */
+    cycleAudioTracks: () => void;
     qualityLevels: {
         (): QualityLevel[];
         (opts: {

package/dist/index.js

@@ -63,7 +63,7 @@ function _matchLanguage(candidates, target) {
  */
 export class NMVideoPlayer extends EventEmitter {
     playerId = '';
-    container = {};
+    container;
     videoElement;
     get id() {
         return this.playerId;
@@ -260,13 +260,9 @@ export class NMVideoPlayer extends EventEmitter {
         // Authenticated media servers need the Authorization header on every
         // hls.js manifest/segment request. The provider reads the auth config
         // lazily so getter-style tokens (Vue refs, stores) stay live.
-        instance.setAuthHeaderProvider?.(async () => {
-            const bearer = this.options?.auth?.bearerToken;
-            if (!bearer)
-                return undefined;
-            const token = typeof bearer === 'function' ? await bearer() : bearer;
-            return token ? `Bearer ${token}` : undefined;
-        });
+        // 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));
         // 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.
@@ -360,6 +356,15 @@ export class NMVideoPlayer extends EventEmitter {
             this.emit('subtitleCue', data);
         });
         instance.on('timeupdate', () => {
+            // Between a `next()` and the incoming item's mount, this element is
+            // still the OUTGOING item's — the cursor already moved. Publishing
+            // its position here hands every listener the previous item's
+            // position stamped with the new item's identity. Optional call:
+            // the dependency range admits a core that predates the reader, and
+            // an older core must degrade to the old behaviour, not throw on
+            // every tick.
+            if (this._mediaIsStale?.())
+                return;
             const currentTime = instance.currentTime();
             const duration = instance.duration();
             // The payload is core's full TimeState snapshot, built from the
@@ -523,24 +528,7 @@ export class NMVideoPlayer extends EventEmitter {
         const next = current >= list.length - 1 ? -1 : current + 1;
         this.subtitle(next === -1 ? null : next);
     }
-    cycleAudioTracks() {
-        let list = [];
-        try {
-            list = this.audioTracks();
-        }
-        catch { /* tracks API not implemented yet — treat as empty */ }
-        if (!list || list.length === 0)
-            return;
-        let current = -1;
-        try {
-            const sel = this.audioTrack();
-            if (sel != null && typeof sel.index === 'number' && sel.index >= 0)
-                current = sel.index;
-        }
-        catch { /* state unavailable — start from 0 */ }
-        const next = current >= list.length - 1 ? 0 : current + 1;
-        this.audioTrack(next);
-    }
+    // cycleAudioTracks — composed in via `mediaTracksMethods` mixin (core, shared with music).
     _aspectRatio = 'uniform';
     static _OBJECT_FIT_MAP = {
         uniform: 'contain',
@@ -702,9 +690,23 @@ composeMixins(NMVideoPlayer.prototype, ...playerCoreMethods);
 {
     const composedDispose = NMVideoPlayer.prototype.dispose;
     NMVideoPlayer.prototype.dispose = async function () {
+        // The container id is released before the first await, not after the
+        // teardown resolves. Consumers re-create on the same container in the
+        // same tick — a responsive view handing `#player1` from its desktop
+        // variant to its mobile one does exactly that — and the registry still
+        // held this player, so they were given back the very instance they had
+        // just asked to dispose. `setup()` then threw `already-setup`, and the
+        // throw left that player attached and playing with nobody holding a
+        // reference to stop it.
+        const claimedId = this.playerId;
+        _instances.delete(claimedId);
         await composedDispose.call(this);
-        if (this.phase() !== 'disposed')
-            return; // beforeDispose was prevented — backend + registry stay intact
+        if (this.phase() !== 'disposed') {
+            // beforeDispose was prevented — the player is still alive, so it
+            // takes its id back and the backend stays intact.
+            _instances.set(claimedId, this);
+            return;
+        }
         this._disposeBackend();
     };
 }