@videojs/spf 10.0.0-beta.28 → 10.0.0-beta.29

package/dist/dev/playback/adapters/hls-background-video/adapter.js

@@ -1,17 +1,62 @@
-import { pickTrackUnderPixelArea } from "../../../media/primitives/select-tracks.js";
+import { effect } from "../../../core/signals/effect.js";
+import { SVTA_NO_SUPPORTED_VIDEO_TRACK, SVTA_UNSUPPORTED_DRM_SYSTEM, SVTA_UNSUPPORTED_PLAYBACK_FEATURE, SVTA_UNSUPPORTED_VIDEO_FORMAT } from "../../../media/errors.js";
 import { createBackgroundVideoEngine } from "../../engines/hls/engine-background-video.js";
+import { UNPLAYABLE_SOURCE_MESSAGE } from "../../primitives/error-messages.js";
+import { firstFatal, hasUnsupportedFeatureCause } from "../hls-video/error-surface.js";
 //#region src/playback/adapters/hls-background-video/adapter.ts
 const hlsBackgroundVideoMediaDefaultProps = { src: "" };
 /**
+* Which reported conditions this composition treats as **fatal** — the ones that
+* reach `error` and fire `'error'`. Severity isn't part of an SVTA code
+* (§Approach: "impact varies with player implementation"), so it's decided at
+* this boundary rather than by the reporter.
+*
+* **Causes are fatal here, unlike on the other two adapters.** There, a cause is
+* context — one unplayable rendition doesn't fail a source whose others still
+* play, and a verdict follows if the type empties. In the pinned variant a cause
+* *is* the verdict: only the pinned rendition's playlist is ever resolved, so a
+* cause can only be about the pick itself, and dropping that pick is final —
+* nothing here re-picks (that is what `switchVideoTrack` exists for, and this
+* engine doesn't compose it). Measured on Chromium: an MPEG-TS source reports
+* 1004 and an encrypted one 4008, each with no verdict behind it, and the element
+* then sits at `readyState 0` with `error` null forever.
+*
+* The verdict is still listed, for the one shape that reports nothing else: a
+* source offering no video renditions at all, which `reportAbsentTrackType`
+* reports from the head of the constraint chain.
+*
+* First-fatal-wins then surfaces the cause rather than the verdict when both are
+* present, which is the more specific of the two.
+*/
+const FATAL_SVTA_CODES = /* @__PURE__ */ new Set([
+	SVTA_NO_SUPPORTED_VIDEO_TRACK,
+	SVTA_UNSUPPORTED_VIDEO_FORMAT,
+	SVTA_UNSUPPORTED_DRM_SYSTEM
+]);
+/**
 * Mixin that adds the background-video SPF playback engine to any base class,
 * for an HLS URL.
 *
-* `src` is the whole surface, and the picker always pins the top rendition on
-* offer. There is no cap of its own because the manifest is the better place to
-* narrow one: a delivery param — `?max_resolution=720p` on a Mux stream URL, for
-* one — keeps the renditions it excludes out of the manifest entirely, rather
-* than fetched-then-unpicked. Deriving a cap from the screen instead is on the
-* roadmap, and lands here when it does.
+* `src` is the whole input surface, and `error` is the one output: nothing about
+* an unplayable source reaches the media element on its own here — an unsupported
+* container, encryption with no EME, and an undecodable codec all leave
+* `HTMLMediaElement.error` null with the element stalled at `readyState 0`
+* (measured on Chromium and WebKit) — so a consumer that watched only the
+* `<video>` would see a source that never appears and never says why. The engine
+* reports each condition onto `engine.state.errors` and logs it; this adapter
+* promotes the first fatal one, mapping it the same way the video and audio Medias
+* map theirs. See `internal/design/spf/features/errors.md`.
+*
+* Selection pins the largest rendition that *fits the screen*, and holds it for
+* the session. The manifest is still the better place to narrow further: a
+* delivery param — `?max_resolution=720p` on a Mux stream URL, for one — keeps
+* the renditions it excludes out of the manifest entirely, rather than
+* fetched-then-unpicked.
+*
+* The pin is given up, never moved, if the pick turns out to be unplayable: the
+* container is only known once a media playlist resolves, which is after the pick
+* is made, so the selection clears rather than quietly appending bytes nothing can
+* decode.
 *
 * `@videojs/spf/mux-background-video` is this same Media under a Mux-flavored
 * name — an alias, not a variant. Nothing about the surface changes with the
@@ -29,6 +74,8 @@ const hlsBackgroundVideoMediaDefaultProps = { src: "" };
 * engine instance and the attached media element are both kept, so neither has to
 * be rewired.
 *
+* @fires error - Fired when a fatal condition is reported. Read `error` for it.
+*
 * @example
 * class HlsBackgroundVideoMedia extends HlsBackgroundVideoMediaMixin(BackgroundVideoHost) {}
 *
@@ -42,6 +89,14 @@ function HlsBackgroundVideoMediaMixin(BaseClass) {
 		#engine;
 		#config;
 		#signals;
+		#error = null;
+		/**
+		* The *reported* condition currently surfaced, which is what the re-fire latch
+		* keys on. Not `#error.code`: that's the code this adapter chose to surface,
+		* and the substitution below can make the two differ.
+		*/
+		#reportedCode = null;
+		#stopErrorSync;
 		/** Pending loadstart listener from a deferred play() retry, if any. */
 		#loadstartListener = null;
 		constructor(...args) {
@@ -49,10 +104,46 @@ function HlsBackgroundVideoMediaMixin(BaseClass) {
 			const { config } = args?.[0] ?? {};
 			this.#config = config;
 			this.#engine = this.#createEngine();
+			this.#stopErrorSync = effect(() => {
+				const errors = this.#signals.state.errors.get();
+				this.#setError(firstFatal(errors, FATAL_SVTA_CODES), errors);
+			});
 		}
 		get engine() {
 			return this.#engine;
 		}
+		/**
+		* The current fatal condition, or `null`. Only *fatal* ones appear here — the
+		* engine reports non-fatal ones too (they stay in `engine.state.errors`), and
+		* promoting them would say playback had failed when it hadn't. Which ones are
+		* fatal is wider here than on the video and audio Medias; see
+		* {@link FATAL_SVTA_CODES}. Resets per source. Fires `'error'` when set.
+		*
+		* Mapped the same way theirs are: a sequence holding an
+		* unimplemented-capability cause surfaces as
+		* {@link SVTA_UNSUPPORTED_PLAYBACK_FEATURE} (99001) with the specifics logged,
+		* because "this player can't play this source" is what a consumer can act on,
+		* where a raw container or DRM code only says what to go and look up.
+		*/
+		get error() {
+			return this.#error;
+		}
+		#setError(reported, errors) {
+			if (!reported) {
+				this.#error = null;
+				this.#reportedCode = null;
+				return;
+			}
+			if (this.#reportedCode === reported.code) return;
+			this.#reportedCode = reported.code;
+			console.error(UNPLAYABLE_SOURCE_MESSAGE, { conditions: errors });
+			this.#error = {
+				code: hasUnsupportedFeatureCause(errors) ? SVTA_UNSUPPORTED_PLAYBACK_FEATURE : reported.code,
+				message: reported.message ?? "",
+				...reported.data === void 0 ? {} : { data: reported.data }
+			};
+			this.dispatchEvent?.(new Event("error"));
+		}
 		attach(mediaElement) {
 			super.attach?.(mediaElement);
 			mediaElement.loop = true;
@@ -68,6 +159,7 @@ function HlsBackgroundVideoMediaMixin(BaseClass) {
 		}
 		destroy() {
 			this.#cancelPendingPlay();
+			this.#stopErrorSync();
 			this.#engine.destroy();
 		}
 		get src() {
@@ -96,11 +188,7 @@ function HlsBackgroundVideoMediaMixin(BaseClass) {
 			}
 		}
 		#createEngine() {
-			const adapterPicker = (presentation) => {
-				return pickTrackUnderPixelArea((presentation.selectionSets?.find((s) => s.type === "video"))?.switchingSets[0]?.tracks ?? [])?.id;
-			};
 			return createBackgroundVideoEngine({
-				picker: adapterPicker,
 				...this.#config,
 				onSignalsReady: (signals) => {
 					this.#signals = signals;

package/dist/dev/playback/adapters/hls-background-video/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":["#config","#engine","#createEngine","#signals","#cancelPendingPlay","#loadstartListener"],"sources":["../../../../../src/playback/adapters/hls-background-video/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport { pickTrackUnderPixelArea, type TrackPicker } from '../../../media/primitives/select-tracks';\nimport type { VideoSelectionSet } from '../../../media/types';\nimport {\n  type BackgroundVideoEngineConfig,\n  type BackgroundVideoEngineContext,\n  type BackgroundVideoEngineSignals,\n  type BackgroundVideoEngineState,\n  createBackgroundVideoEngine,\n} from '../../engines/hls/engine-background-video';\n\nexport interface HlsBackgroundVideoMediaProps {\n  src: string;\n}\n\nexport const hlsBackgroundVideoMediaDefaultProps: HlsBackgroundVideoMediaProps = {\n  src: '',\n};\n\nexport interface HlsBackgroundVideoMediaAPI extends HlsBackgroundVideoMediaProps {\n  readonly engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds the background-video SPF playback engine to any base class,\n * for an HLS URL.\n *\n * `src` is the whole surface, and the picker always pins the top rendition on\n * offer. There is no cap of its own because the manifest is the better place to\n * narrow one: a delivery param — `?max_resolution=720p` on a Mux stream URL, for\n * one — keeps the renditions it excludes out of the manifest entirely, rather\n * than fetched-then-unpicked. Deriving a cap from the screen instead is on the\n * roadmap, and lands here when it does.\n *\n * `@videojs/spf/mux-background-video` is this same Media under a Mux-flavored\n * name — an alias, not a variant. Nothing about the surface changes with the\n * import path.\n *\n * Everything else the use case fixes rather than exposes: video-only, looping,\n * muted, autoplaying, loading as soon as there is a source. `attach` writes that\n * onto the element and nothing here declares `loop` / `muted` / `autoplay` /\n * `preload` of its own — a host-bound Media inherits all four from the host\n * already, and shadowing them with fixed values would only make reads describe\n * an intention rather than what the element is doing.\n *\n * A new src re-resolves the presentation, tearing down the state, SourceBuffers,\n * and in-flight requests the previous one built before the next begins. The\n * engine instance and the attached media element are both kept, so neither has to\n * be rewired.\n *\n * @example\n * class HlsBackgroundVideoMedia extends HlsBackgroundVideoMediaMixin(BackgroundVideoHost) {}\n *\n * const media = new HlsBackgroundVideoMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p';\n * media.play();\n */\nexport function HlsBackgroundVideoMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class HlsBackgroundVideoMediaImpl extends BaseClass {\n    #engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n    #config: BackgroundVideoEngineConfig;\n    #signals!: BackgroundVideoEngineSignals;\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n      this.#engine = this.#createEngine();\n    }\n\n    get engine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      // The one place the fixed behavior is stated. Muted and autoplay are what\n      // let it start without a gesture, loop is the defining behavior, and\n      // `preload` says out loud what the engine does regardless — it subtracts\n      // preload monitoring and loads from the moment it has a source.\n      mediaElement.loop = true;\n      mediaElement.muted = true;\n      mediaElement.autoplay = true;\n      mediaElement.preload = 'auto';\n\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      // Same line the HLS Medias draw: the presentation is set from a fresh\n      // object every time, so re-resolving a URL already playing would restart\n      // it for no reason.\n      if (value === this.src) return;\n\n      this.#cancelPendingPlay();\n      this.#signals.state.presentation.set(value ? { url: value } : undefined);\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    async play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('HlsBackgroundVideoMediaElement: no media element attached'));\n      }\n\n      try {\n        return await mediaElement.play();\n      } catch (err) {\n        // If we have a pending HLS source, the rejection may be because MSE\n        // hasn't attached a blob URL yet. Wait for loadstart (src assigned by\n        // MSE setup) and retry once.\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #createEngine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      // No cap to apply, so the pick is whichever rendition is largest. Passing\n      // no maximum is what makes that the answer, rather than a rule of its own.\n      const adapterPicker: TrackPicker = (presentation) => {\n        const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n        const tracks = videoSet?.switchingSets[0]?.tracks ?? [];\n        return pickTrackUnderPixelArea(tracks)?.id;\n      };\n\n      return createBackgroundVideoEngine({\n        picker: adapterPicker,\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return HlsBackgroundVideoMediaImpl as unknown as MixinReturn<Base, HlsBackgroundVideoMediaAPI>;\n}\n\n/** Standalone SPF background-video adapter with no base class. */\nexport class HlsBackgroundVideoMediaElement extends HlsBackgroundVideoMediaMixin(class {}) {}\n"],"mappings":";;;AAgBA,MAAa,sCAAoE,EAC/E,KAAK,GACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,6BAA4D,WAAiB;CAC3F,MAAM,oCAAoC,UAAU;EAClD;EACA;EACA;;EAGA,qBAA0C;EAE1C,YAAY,GAAG,MAAa;GAC1B,MAAM,GAAG,IAAI;GAEb,MAAM,EAAE,WAAW,OAAO,MAAM,CAAC;GACjC,KAAKA,UAAU;GACf,KAAKC,UAAU,KAAKC,cAAc;EACpC;EAEA,IAAI,SAAgF;GAClF,OAAO,KAAKD;EACd;EAMA,OAAO,cAAsC;GAC3C,MAAM,SAAS,YAAY;GAK3B,aAAa,OAAO;GACpB,aAAa,QAAQ;GACrB,aAAa,WAAW;GACxB,aAAa,UAAU;GAEvB,KAAKE,SAAS,QAAQ,aAAa,IAAI,YAAY;EACrD;EAEA,SAAe;GACb,KAAKC,mBAAmB;GACxB,KAAKD,SAAS,QAAQ,aAAa,IAAI,KAAA,CAAS;GAChD,MAAM,SAAS;EACjB;EAEA,UAAgB;GACd,KAAKC,mBAAmB;GACxB,KAAKH,QAAQ,QAAQ;EACvB;EAMA,IAAI,MAAc;GAChB,OAAO,KAAKE,SAAS,MAAM,aAAa,IAAI,CAAC,EAAE,OAAO;EACxD;EAEA,IAAI,IAAI,OAAe;GAIrB,IAAI,UAAU,KAAK,KAAK;GAExB,KAAKC,mBAAmB;GACxB,KAAKD,SAAS,MAAM,aAAa,IAAI,QAAQ,EAAE,KAAK,MAAM,IAAI,KAAA,CAAS;EACzE;EAOA,MAAM,OAAsB;GAC1B,MAAM,eAAe,KAAKA,SAAS,QAAQ,aAAa,IAAI;GAC5D,IAAI,CAAC,cACH,OAAO,QAAQ,uBAAO,IAAI,MAAM,2DAA2D,CAAC;GAG9F,IAAI;IACF,OAAO,MAAM,aAAa,KAAK;GACjC,SAAS,KAAK;IAIZ,IAAI,KAAK,KACP,OAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;MACrB,KAAKE,qBAAqB;MAC1B,aAAa,KAAK,CAAC,CAAC,KAAK,SAAS,MAAM;KAC1C;KACA,KAAKA,qBAAqB;KAC1B,aAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,KAAK,CAAC;IACrE,CAAC;IAEH,MAAM;GACR;EACF;EAMA,gBAAuF;GAGrF,MAAM,iBAA8B,iBAAiB;IAGnD,OAAO,yBAFU,aAAa,eAAe,MAAM,MAAM,EAAE,SAAS,OAAO,EAAA,EAClD,cAAc,EAAE,EAAE,UAAU,CAAC,CACjB,CAAC,EAAE;GAC1C;GAEA,OAAO,4BAA4B;IACjC,QAAQ;IACR,GAAG,KAAKL;IACR,iBAAiB,YAAY;KAC3B,KAAKG,WAAW;IAClB;GACF,CAAC;EACH;EAEA,qBAA2B;GACzB,IAAI,CAAC,KAAKE,oBAAoB;GAE9B,KAD0BF,SAAS,QAAQ,aAAa,IAC7C,CAAC,EAAE,oBAAoB,aAAa,KAAKE,kBAAkB;GACtE,KAAKA,qBAAqB;EAC5B;CACF;CAEA,OAAO;AACT;;AAGA,IAAa,iCAAb,cAAoD,6BAA6B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"adapter.js","names":["#config","#engine","#createEngine","#stopErrorSync","#signals","#setError","#error","#reportedCode","#cancelPendingPlay","#loadstartListener"],"sources":["../../../../../src/playback/adapters/hls-background-video/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport { effect } from '../../../core/signals/effect';\nimport {\n  SVTA_NO_SUPPORTED_VIDEO_TRACK,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n  SVTA_UNSUPPORTED_PLAYBACK_FEATURE,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  type SvtaError,\n} from '../../../media/errors';\nimport {\n  type BackgroundVideoEngineConfig,\n  type BackgroundVideoEngineContext,\n  type BackgroundVideoEngineSignals,\n  type BackgroundVideoEngineState,\n  createBackgroundVideoEngine,\n} from '../../engines/hls/engine-background-video';\nimport { UNPLAYABLE_SOURCE_MESSAGE } from '../../primitives/error-messages';\nimport { firstFatal, type HlsVideoMediaError, hasUnsupportedFeatureCause } from '../hls-video/error-surface';\n\n// The same error shape the video and audio Medias expose, under the name they\n// publish it as — one type for all three surfaces rather than a background-flavored\n// copy of it.\nexport type { HlsVideoMediaError } from '../hls-video/error-surface';\n\nexport interface HlsBackgroundVideoMediaProps {\n  src: string;\n}\n\nexport const hlsBackgroundVideoMediaDefaultProps: HlsBackgroundVideoMediaProps = {\n  src: '',\n};\n\nexport interface HlsBackgroundVideoMediaAPI extends HlsBackgroundVideoMediaProps {\n  readonly engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n  readonly error: HlsVideoMediaError | null;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Which reported conditions this composition treats as **fatal** — the ones that\n * reach `error` and fire `'error'`. Severity isn't part of an SVTA code\n * (§Approach: \"impact varies with player implementation\"), so it's decided at\n * this boundary rather than by the reporter.\n *\n * **Causes are fatal here, unlike on the other two adapters.** There, a cause is\n * context — one unplayable rendition doesn't fail a source whose others still\n * play, and a verdict follows if the type empties. In the pinned variant a cause\n * *is* the verdict: only the pinned rendition's playlist is ever resolved, so a\n * cause can only be about the pick itself, and dropping that pick is final —\n * nothing here re-picks (that is what `switchVideoTrack` exists for, and this\n * engine doesn't compose it). Measured on Chromium: an MPEG-TS source reports\n * 1004 and an encrypted one 4008, each with no verdict behind it, and the element\n * then sits at `readyState 0` with `error` null forever.\n *\n * The verdict is still listed, for the one shape that reports nothing else: a\n * source offering no video renditions at all, which `reportAbsentTrackType`\n * reports from the head of the constraint chain.\n *\n * First-fatal-wins then surfaces the cause rather than the verdict when both are\n * present, which is the more specific of the two.\n */\nconst FATAL_SVTA_CODES: ReadonlySet<number> = new Set<number>([\n  SVTA_NO_SUPPORTED_VIDEO_TRACK,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n]);\n\n/**\n * Mixin that adds the background-video SPF playback engine to any base class,\n * for an HLS URL.\n *\n * `src` is the whole input surface, and `error` is the one output: nothing about\n * an unplayable source reaches the media element on its own here — an unsupported\n * container, encryption with no EME, and an undecodable codec all leave\n * `HTMLMediaElement.error` null with the element stalled at `readyState 0`\n * (measured on Chromium and WebKit) — so a consumer that watched only the\n * `<video>` would see a source that never appears and never says why. The engine\n * reports each condition onto `engine.state.errors` and logs it; this adapter\n * promotes the first fatal one, mapping it the same way the video and audio Medias\n * map theirs. See `internal/design/spf/features/errors.md`.\n *\n * Selection pins the largest rendition that *fits the screen*, and holds it for\n * the session. The manifest is still the better place to narrow further: a\n * delivery param — `?max_resolution=720p` on a Mux stream URL, for one — keeps\n * the renditions it excludes out of the manifest entirely, rather than\n * fetched-then-unpicked.\n *\n * The pin is given up, never moved, if the pick turns out to be unplayable: the\n * container is only known once a media playlist resolves, which is after the pick\n * is made, so the selection clears rather than quietly appending bytes nothing can\n * decode.\n *\n * `@videojs/spf/mux-background-video` is this same Media under a Mux-flavored\n * name — an alias, not a variant. Nothing about the surface changes with the\n * import path.\n *\n * Everything else the use case fixes rather than exposes: video-only, looping,\n * muted, autoplaying, loading as soon as there is a source. `attach` writes that\n * onto the element and nothing here declares `loop` / `muted` / `autoplay` /\n * `preload` of its own — a host-bound Media inherits all four from the host\n * already, and shadowing them with fixed values would only make reads describe\n * an intention rather than what the element is doing.\n *\n * A new src re-resolves the presentation, tearing down the state, SourceBuffers,\n * and in-flight requests the previous one built before the next begins. The\n * engine instance and the attached media element are both kept, so neither has to\n * be rewired.\n *\n * @fires error - Fired when a fatal condition is reported. Read `error` for it.\n *\n * @example\n * class HlsBackgroundVideoMedia extends HlsBackgroundVideoMediaMixin(BackgroundVideoHost) {}\n *\n * const media = new HlsBackgroundVideoMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p';\n * media.play();\n */\nexport function HlsBackgroundVideoMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class HlsBackgroundVideoMediaImpl extends BaseClass {\n    #engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n    #config: BackgroundVideoEngineConfig;\n    #signals!: BackgroundVideoEngineSignals;\n    #error: HlsVideoMediaError | null = null;\n    /**\n     * The *reported* condition currently surfaced, which is what the re-fire latch\n     * keys on. Not `#error.code`: that's the code this adapter chose to surface,\n     * and the substitution below can make the two differ.\n     */\n    #reportedCode: number | null = null;\n    #stopErrorSync: () => void;\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n      this.#engine = this.#createEngine();\n\n      // Promote the first fatal condition out of the engine's reported sequence\n      // onto this surface. Clearing rides the same signal: `collectErrors` resets\n      // the slot per source, so a new source starts with no error without this\n      // needing its own source-change hook.\n      this.#stopErrorSync = effect(() => {\n        const errors = this.#signals.state.errors.get();\n        this.#setError(firstFatal(errors, FATAL_SVTA_CODES), errors);\n      });\n    }\n\n    get engine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      return this.#engine;\n    }\n\n    /**\n     * The current fatal condition, or `null`. Only *fatal* ones appear here — the\n     * engine reports non-fatal ones too (they stay in `engine.state.errors`), and\n     * promoting them would say playback had failed when it hadn't. Which ones are\n     * fatal is wider here than on the video and audio Medias; see\n     * {@link FATAL_SVTA_CODES}. Resets per source. Fires `'error'` when set.\n     *\n     * Mapped the same way theirs are: a sequence holding an\n     * unimplemented-capability cause surfaces as\n     * {@link SVTA_UNSUPPORTED_PLAYBACK_FEATURE} (99001) with the specifics logged,\n     * because \"this player can't play this source\" is what a consumer can act on,\n     * where a raw container or DRM code only says what to go and look up.\n     */\n    get error(): HlsVideoMediaError | null {\n      return this.#error;\n    }\n\n    #setError(reported: SvtaError | undefined, errors: readonly SvtaError[] | undefined): void {\n      if (!reported) {\n        // Cleared (new source). No event: `'error'` announces a failure, and\n        // consumers reset their own copy on source change.\n        this.#error = null;\n        this.#reportedCode = null;\n        return;\n      }\n      // Keyed on the code, not the object: a later append re-runs this effect\n      // with an equal-but-new array, and re-firing `'error'` for a condition\n      // already surfaced would look like a second failure.\n      if (this.#reportedCode === reported.code) return;\n      this.#reportedCode = reported.code;\n\n      // Logged for every fatal condition, not just the substituted ones: a source\n      // with no video renditions is as dead as an unplayable container, and it\n      // would otherwise reach a developer as a bare code. One generic sentence\n      // rather than one per case — the conditions beside it carry the specifics.\n      //\n      // Prose stays here rather than on `error.message`, matching the other two:\n      // viewer-facing copy is the consumer's to localize, and a background video\n      // has no chrome to put it in anyway.\n      console.error(UNPLAYABLE_SOURCE_MESSAGE, { conditions: errors });\n\n      this.#error = {\n        code: hasUnsupportedFeatureCause(errors) ? SVTA_UNSUPPORTED_PLAYBACK_FEATURE : reported.code,\n        message: reported.message ?? '',\n        ...(reported.data === undefined ? {} : { data: reported.data }),\n      };\n      // Optional-chained: with an EventTarget-less base (`HlsBackgroundVideoMediaElement`\n      // standalone) there's nowhere to dispatch.\n      this.dispatchEvent?.(new Event('error'));\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      // The one place the fixed behavior is stated. Muted and autoplay are what\n      // let it start without a gesture, loop is the defining behavior, and\n      // `preload` says out loud what the engine does regardless — it subtracts\n      // preload monitoring and loads from the moment it has a source.\n      mediaElement.loop = true;\n      mediaElement.muted = true;\n      mediaElement.autoplay = true;\n      mediaElement.preload = 'auto';\n\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#stopErrorSync();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      // Same line the HLS Medias draw: the presentation is set from a fresh\n      // object every time, so re-resolving a URL already playing would restart\n      // it for no reason.\n      if (value === this.src) return;\n\n      this.#cancelPendingPlay();\n      this.#signals.state.presentation.set(value ? { url: value } : undefined);\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    async play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('HlsBackgroundVideoMediaElement: no media element attached'));\n      }\n\n      try {\n        return await mediaElement.play();\n      } catch (err) {\n        // If we have a pending HLS source, the rejection may be because MSE\n        // hasn't attached a blob URL yet. Wait for loadstart (src assigned by\n        // MSE setup) and retry once.\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #createEngine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      // No selection config of its own: the engine's default rule chain already\n      // narrows to the largest rendition that fits the screen, which is exactly\n      // what this adapter used to hand over as a bespoke picker.\n      return createBackgroundVideoEngine({\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return HlsBackgroundVideoMediaImpl as unknown as MixinReturn<Base, HlsBackgroundVideoMediaAPI>;\n}\n\n/** Standalone SPF background-video adapter with no base class. */\nexport class HlsBackgroundVideoMediaElement extends HlsBackgroundVideoMediaMixin(class {}) {}\n"],"mappings":";;;;;;AA6BA,MAAa,sCAAoE,EAC/E,KAAK,GACP;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAM,mCAAwC,IAAI,IAAY;CAC5D;CACA;CACA;AACF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDD,SAAgB,6BAA4D,WAAiB;CAC3F,MAAM,oCAAoC,UAAU;EAClD;EACA;EACA;EACA,SAAoC;;;;;;EAMpC,gBAA+B;EAC/B;;EAGA,qBAA0C;EAE1C,YAAY,GAAG,MAAa;GAC1B,MAAM,GAAG,IAAI;GAEb,MAAM,EAAE,WAAW,OAAO,MAAM,CAAC;GACjC,KAAKA,UAAU;GACf,KAAKC,UAAU,KAAKC,cAAc;GAMlC,KAAKC,iBAAiB,aAAa;IACjC,MAAM,SAAS,KAAKC,SAAS,MAAM,OAAO,IAAI;IAC9C,KAAKC,UAAU,WAAW,QAAQ,gBAAgB,GAAG,MAAM;GAC7D,CAAC;EACH;EAEA,IAAI,SAAgF;GAClF,OAAO,KAAKJ;EACd;;;;;;;;;;;;;;EAeA,IAAI,QAAmC;GACrC,OAAO,KAAKK;EACd;EAEA,UAAU,UAAiC,QAAgD;GACzF,IAAI,CAAC,UAAU;IAGb,KAAKA,SAAS;IACd,KAAKC,gBAAgB;IACrB;GACF;GAIA,IAAI,KAAKA,kBAAkB,SAAS,MAAM;GAC1C,KAAKA,gBAAgB,SAAS;GAU9B,QAAQ,MAAM,2BAA2B,EAAE,YAAY,OAAO,CAAC;GAE/D,KAAKD,SAAS;IACZ,MAAM,2BAA2B,MAAM,IAAI,oCAAoC,SAAS;IACxF,SAAS,SAAS,WAAW;IAC7B,GAAI,SAAS,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM,SAAS,KAAK;GAC/D;GAGA,KAAK,gBAAgB,IAAI,MAAM,OAAO,CAAC;EACzC;EAMA,OAAO,cAAsC;GAC3C,MAAM,SAAS,YAAY;GAK3B,aAAa,OAAO;GACpB,aAAa,QAAQ;GACrB,aAAa,WAAW;GACxB,aAAa,UAAU;GAEvB,KAAKF,SAAS,QAAQ,aAAa,IAAI,YAAY;EACrD;EAEA,SAAe;GACb,KAAKI,mBAAmB;GACxB,KAAKJ,SAAS,QAAQ,aAAa,IAAI,KAAA,CAAS;GAChD,MAAM,SAAS;EACjB;EAEA,UAAgB;GACd,KAAKI,mBAAmB;GACxB,KAAKL,eAAe;GACpB,KAAKF,QAAQ,QAAQ;EACvB;EAMA,IAAI,MAAc;GAChB,OAAO,KAAKG,SAAS,MAAM,aAAa,IAAI,CAAC,EAAE,OAAO;EACxD;EAEA,IAAI,IAAI,OAAe;GAIrB,IAAI,UAAU,KAAK,KAAK;GAExB,KAAKI,mBAAmB;GACxB,KAAKJ,SAAS,MAAM,aAAa,IAAI,QAAQ,EAAE,KAAK,MAAM,IAAI,KAAA,CAAS;EACzE;EAOA,MAAM,OAAsB;GAC1B,MAAM,eAAe,KAAKA,SAAS,QAAQ,aAAa,IAAI;GAC5D,IAAI,CAAC,cACH,OAAO,QAAQ,uBAAO,IAAI,MAAM,2DAA2D,CAAC;GAG9F,IAAI;IACF,OAAO,MAAM,aAAa,KAAK;GACjC,SAAS,KAAK;IAIZ,IAAI,KAAK,KACP,OAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;MACrB,KAAKK,qBAAqB;MAC1B,aAAa,KAAK,CAAC,CAAC,KAAK,SAAS,MAAM;KAC1C;KACA,KAAKA,qBAAqB;KAC1B,aAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,KAAK,CAAC;IACrE,CAAC;IAEH,MAAM;GACR;EACF;EAMA,gBAAuF;GAIrF,OAAO,4BAA4B;IACjC,GAAG,KAAKT;IACR,iBAAiB,YAAY;KAC3B,KAAKI,WAAW;IAClB;GACF,CAAC;EACH;EAEA,qBAA2B;GACzB,IAAI,CAAC,KAAKK,oBAAoB;GAE9B,KAD0BL,SAAS,QAAQ,aAAa,IAC7C,CAAC,EAAE,oBAAoB,aAAa,KAAKK,kBAAkB;GACtE,KAAKA,qBAAqB;EAC5B;CACF;CAEA,OAAO;AACT;;AAGA,IAAa,iCAAb,cAAoD,6BAA6B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/dev/playback/adapters/hls-video/error-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-surface.d.ts","names":[],"sources":["../../../../../src/playback/adapters/hls-video/error-surface.ts"],"mappings":";;;;;;;;;;;UA6BiB,2BAA2B;;WAEjC"}
+{"version":3,"file":"error-surface.d.ts","names":[],"sources":["../../../../../src/playback/adapters/hls-video/error-surface.ts"],"mappings":";;;;;;;;;;;UAkCiB,2BAA2B;;WAEjC"}

package/dist/dev/playback/adapters/hls-video/error-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-surface.js","names":[],"sources":["../../../../../src/playback/adapters/hls-video/error-surface.ts"],"sourcesContent":["/**\n * The shared half of promoting reported conditions onto a media surface.\n *\n * Both HLS adapters do the same things: pick the first condition they treat as\n * fatal, latch it so a later append doesn't re-fire, and name a better-equipped\n * Media when their own class points at one. Only the *policy* differs — which\n * codes are fatal, which the video adapter and the audio-only adapter answer\n * differently — so that stays with each adapter and everything else lives here.\n *\n * See `internal/design/spf/features/errors.md` for the causes-vs-verdicts split\n * this rests on.\n */\nimport type { ErrorLike } from '@videojs/media';\nimport {\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  type SvtaError,\n} from '../../../media/errors';\n\n/**\n * The error shape a media surface exposes: `@videojs/media`'s {@link ErrorLike}\n * plus the reporter context the engine carries alongside a condition.\n *\n * `code` is the **SVTA code**, not a `MediaError.MEDIA_ERR_*` value. Consumers\n * that map codes to copy currently only know 1–5, so an SVTA code falls through\n * to showing `message`; an extensible code lookup above the engine is the\n * follow-up that fixes it.\n */\nexport interface HlsVideoMediaError extends ErrorLike {\n  /** Reporter context (which selection emptied, which track, …). */\n  readonly data?: unknown;\n}\n\n/**\n * `message`, plus the alternative-Media sentence when `media`'s class names one.\n *\n * Read off the class rather than passed in so a subclass can point at a\n * better-equipped sibling — the SPF Mux Medias name the hls.js-backed one, which\n * plays the MPEG-TS and DRM sources SPF doesn't — without either adapter knowing\n * that sibling exists.\n */\nexport function withAlternativeMediaSuggestion(message: string, media: object): string {\n  const { alternativeMediaSuggestion } = media.constructor as { alternativeMediaSuggestion?: string };\n  const suggestion = alternativeMediaSuggestion?.trim();\n\n  return suggestion ? `${message} ${suggestion}` : message;\n}\n\n/** The first condition `fatalCodes` covers — the root cause, not its consequences. */\nexport function firstFatal(\n  errors: readonly SvtaError[] | undefined,\n  fatalCodes: ReadonlySet<number>\n): SvtaError | undefined {\n  return errors?.find((error) => fatalCodes.has(error.code));\n}\n\n/**\n * The causes that mean the engine has no pipeline for what the source delivers —\n * a container it can't append, or encryption it can't decrypt.\n *\n * What these have in common is that no retry, no other CDN, and no other\n * rendition of the same source fixes them: the source needs a capability this\n * engine doesn't have. That's the distinction the surfaced code exists to draw,\n * and it's why the set is these three rather than \"every cause\".\n */\nconst UNSUPPORTED_FEATURE_CAUSES: ReadonlySet<number> = new Set<number>([\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n]);\n\n/**\n * Whether anything in the sequence is a cause of the \"we don't implement this\"\n * kind.\n *\n * Deliberately `some` over the whole sequence rather than a per-type match\n * against the verdict. A verdict means one type's candidates emptied, but the\n * *reason* the source is unplayable can sit on another type — an audio-only\n * source whose sole rendition is encrypted empties the audio candidates, and a\n * video source with encrypted video empties the video ones. Both are the same\n * answer to the viewer, so both get the same code.\n */\nexport function hasUnsupportedFeatureCause(errors: readonly SvtaError[] | undefined): boolean {\n  return errors?.some((error) => UNSUPPORTED_FEATURE_CAUSES.has(error.code)) ?? false;\n}\n"],"mappings":";;;;;;;;;;AA0CA,SAAgB,+BAA+B,SAAiB,OAAuB;CACrF,MAAM,EAAE,+BAA+B,MAAM;CAC7C,MAAM,aAAa,4BAA4B,KAAK;CAEpD,OAAO,aAAa,GAAG,QAAQ,GAAG,eAAe;AACnD;;AAGA,SAAgB,WACd,QACA,YACuB;CACvB,OAAO,QAAQ,MAAM,UAAU,WAAW,IAAI,MAAM,IAAI,CAAC;AAC3D;;;;;;;;;;AAWA,MAAM,6CAAkD,IAAI,IAAY;CACtE;CACA;CACA;AACF,CAAC;;;;;;;;;;;;AAaD,SAAgB,2BAA2B,QAAmD;CAC5F,OAAO,QAAQ,MAAM,UAAU,2BAA2B,IAAI,MAAM,IAAI,CAAC,KAAK;AAChF"}
+{"version":3,"file":"error-surface.js","names":[],"sources":["../../../../../src/playback/adapters/hls-video/error-surface.ts"],"sourcesContent":["/**\n * The shared half of promoting reported conditions onto a media surface.\n *\n * Every adapter that has one does the same things: pick the first condition it\n * treats as fatal, latch it so a later append doesn't re-fire, and name a\n * better-equipped Media when its own class points at one. Only the *policy*\n * differs — which codes are fatal, which the video, audio-only, and background\n * adapters each answer differently — so that stays with each adapter and\n * everything else lives here.\n *\n * `firstFatal` is the part all three share. The `ErrorLike` mapping below it is\n * for the two that feed a store and a dialog; the background adapter surfaces the\n * reported condition unmapped, so it takes the picker and nothing else.\n *\n * See `internal/design/spf/features/errors.md` for the causes-vs-verdicts split\n * this rests on.\n */\nimport type { ErrorLike } from '@videojs/media';\nimport {\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  type SvtaError,\n} from '../../../media/errors';\n\n/**\n * The error shape a media surface exposes: `@videojs/media`'s {@link ErrorLike}\n * plus the reporter context the engine carries alongside a condition.\n *\n * `code` is the **SVTA code**, not a `MediaError.MEDIA_ERR_*` value. Consumers\n * that map codes to copy currently only know 1–5, so an SVTA code falls through\n * to showing `message`; an extensible code lookup above the engine is the\n * follow-up that fixes it.\n */\nexport interface HlsVideoMediaError extends ErrorLike {\n  /** Reporter context (which selection emptied, which track, …). */\n  readonly data?: unknown;\n}\n\n/**\n * `message`, plus the alternative-Media sentence when `media`'s class names one.\n *\n * Read off the class rather than passed in so a subclass can point at a\n * better-equipped sibling — the SPF Mux Medias name the hls.js-backed one, which\n * plays the MPEG-TS and DRM sources SPF doesn't — without either adapter knowing\n * that sibling exists.\n */\nexport function withAlternativeMediaSuggestion(message: string, media: object): string {\n  const { alternativeMediaSuggestion } = media.constructor as { alternativeMediaSuggestion?: string };\n  const suggestion = alternativeMediaSuggestion?.trim();\n\n  return suggestion ? `${message} ${suggestion}` : message;\n}\n\n/** The first condition `fatalCodes` covers — the root cause, not its consequences. */\nexport function firstFatal(\n  errors: readonly SvtaError[] | undefined,\n  fatalCodes: ReadonlySet<number>\n): SvtaError | undefined {\n  return errors?.find((error) => fatalCodes.has(error.code));\n}\n\n/**\n * The causes that mean the engine has no pipeline for what the source delivers —\n * a container it can't append, or encryption it can't decrypt.\n *\n * What these have in common is that no retry, no other CDN, and no other\n * rendition of the same source fixes them: the source needs a capability this\n * engine doesn't have. That's the distinction the surfaced code exists to draw,\n * and it's why the set is these three rather than \"every cause\".\n */\nconst UNSUPPORTED_FEATURE_CAUSES: ReadonlySet<number> = new Set<number>([\n  SVTA_UNSUPPORTED_VIDEO_FORMAT,\n  SVTA_UNSUPPORTED_AUDIO_FORMAT,\n  SVTA_UNSUPPORTED_DRM_SYSTEM,\n]);\n\n/**\n * Whether anything in the sequence is a cause of the \"we don't implement this\"\n * kind.\n *\n * Deliberately `some` over the whole sequence rather than a per-type match\n * against the verdict. A verdict means one type's candidates emptied, but the\n * *reason* the source is unplayable can sit on another type — an audio-only\n * source whose sole rendition is encrypted empties the audio candidates, and a\n * video source with encrypted video empties the video ones. Both are the same\n * answer to the viewer, so both get the same code.\n */\nexport function hasUnsupportedFeatureCause(errors: readonly SvtaError[] | undefined): boolean {\n  return errors?.some((error) => UNSUPPORTED_FEATURE_CAUSES.has(error.code)) ?? false;\n}\n"],"mappings":";;;;;;;;;;AA+CA,SAAgB,+BAA+B,SAAiB,OAAuB;CACrF,MAAM,EAAE,+BAA+B,MAAM;CAC7C,MAAM,aAAa,4BAA4B,KAAK;CAEpD,OAAO,aAAa,GAAG,QAAQ,GAAG,eAAe;AACnD;;AAGA,SAAgB,WACd,QACA,YACuB;CACvB,OAAO,QAAQ,MAAM,UAAU,WAAW,IAAI,MAAM,IAAI,CAAC;AAC3D;;;;;;;;;;AAWA,MAAM,6CAAkD,IAAI,IAAY;CACtE;CACA;CACA;AACF,CAAC;;;;;;;;;;;;AAaD,SAAgB,2BAA2B,QAAmD;CAC5F,OAAO,QAAQ,MAAM,UAAU,2BAA2B,IAAI,MAAM,IAAI,CAAC,KAAK;AAChF"}

package/dist/dev/playback/adapters/mux-video/adapter.d.ts

@@ -24,6 +24,7 @@ interface MuxMediaAPI extends MuxMediaProps {
  * source and dispatches `sourcechange` itself.
  *
  * @fires sourcechange - Fired when `source` changes, either directly or by parsing a new `src`. Read `source` for the new value.
+ * @fires contentdatachange - Fired when the derived `contentData` changes. Read `contentData` for the new value.
  */
 declare function MuxMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, MuxMediaAPI> & {
   readonly alternativeMediaSuggestion: string | undefined;

package/dist/dev/playback/adapters/mux-video/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../../../../src/playback/adapters/mux-video/adapter.ts"],"mappings":";;;UAUiB;EACf;EACA,QAAQ;;cAGG,sBAAsB;UAKlB,oBAAoB;WAC1B,aAAa;;;;;;;;;;;;;;;;;;iBAmBR,cAAc,aAAa,kBAAkB,WAAW,OAkFpC,YAAY,MAAM;WACzC"}
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../../../../src/playback/adapters/mux-video/adapter.ts"],"mappings":";;;UAWiB;EACf;EACA,QAAQ;;cAGG,sBAAsB;UAKlB,oBAAoB;WAC1B,aAAa;;;;;;;;;;;;;;;;;;;iBAoBR,cAAc,aAAa,kBAAkB,WAAW,OAsGpC,YAAY,MAAM;WACzC"}

package/dist/dev/playback/adapters/mux-video/adapter.js

@@ -1,3 +1,4 @@
+import { shallowEqual } from "@videojs/utils/object";
 import { createMuxPosterURL, createMuxStoryboardURL, createMuxVideoURL, parseMuxVideoURL } from "@videojs/media/dom/mux/source";
 //#region src/playback/adapters/mux-video/adapter.ts
 const muxMediaDefaultProps = {
@@ -19,6 +20,7 @@ const muxMediaDefaultProps = {
 * source and dispatches `sourcechange` itself.
 *
 * @fires sourcechange - Fired when `source` changes, either directly or by parsing a new `src`. Read `source` for the new value.
+* @fires contentdatachange - Fired when the derived `contentData` changes. Read `contentData` for the new value.
 */
 function MuxMediaMixin(BaseClass) {
 	class MuxMediaImpl extends BaseClass {
@@ -36,6 +38,7 @@ function MuxMediaMixin(BaseClass) {
 			return "Try the hls.js-backed Mux media instead: import the `hls-js` flavor in place of the `spf` one.";
 		}
 		#source = muxMediaDefaultProps.source;
+		#contentData = {};
 		/**
 		* Media source URL. Setting a Mux stream URL
 		* (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID
@@ -65,23 +68,33 @@ function MuxMediaMixin(BaseClass) {
 			const source = value ?? null;
 			if (source === this.#source) return;
 			this.#source = source;
+			const contentDataChanged = this.#refreshContentData();
 			super.src = source && (createMuxVideoURL(source) ?? source.src) || "";
 			this.dispatchEvent?.(new Event("sourcechange"));
+			if (contentDataChanged) this.dispatchEvent?.(new Event("contentdatachange"));
 		}
 		/**
 		* Image URLs `source` describes rather than plays: `poster` from its `poster`
 		* params, `storyboard` from its `storyboard` params.
 		*
-		* Read-only and re-derived on read, so read it again after `sourcechange`.
-		* Nothing here is applied for you.
+		* Derived from `source` and nothing else. The same object is handed back
+		* until one of those URLs changes, and `contentdatachange` announces it when
+		* it does. Nothing here is applied for you.
 		*/
 		get contentData() {
+			return this.#contentData;
+		}
+		/** Rebuild the derived bag, reporting whether anything about it changed. */
+		#refreshContentData() {
 			const poster = createMuxPosterURL(this.#source);
 			const storyboard = createMuxStoryboardURL(this.#source);
-			return {
+			const next = {
 				...poster && { poster },
 				...storyboard && { storyboard }
 			};
+			if (shallowEqual(this.#contentData, next)) return false;
+			this.#contentData = next;
+			return true;
 		}
 	}
 	return MuxMediaImpl;

package/dist/dev/playback/adapters/mux-video/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":["#source"],"sources":["../../../../../src/playback/adapters/mux-video/adapter.ts"],"sourcesContent":["import {\n  createMuxPosterURL,\n  createMuxStoryboardURL,\n  createMuxVideoURL,\n  type MuxContentData,\n  type MuxSourceBase,\n  parseMuxVideoURL,\n} from '@videojs/media/dom/mux/source';\nimport type { Constructor, MixinReturn } from '@videojs/utils/types';\n\nexport interface MuxMediaProps {\n  src: string;\n  source: MuxSourceBase | null;\n}\n\nexport const muxMediaDefaultProps: MuxMediaProps = {\n  src: '',\n  source: null,\n};\n\nexport interface MuxMediaAPI extends MuxMediaProps {\n  readonly contentData: MuxContentData;\n}\n\n/**\n * Mux identity over any SPF Media: the structured `source`, the `src` derived\n * from it, and the image URLs it describes.\n *\n * Everything here is Mux identity, so it carries no engine and both flavors get\n * it unchanged — the video Media over the full HLS engine, the audio-only Media\n * over the subtractive one. A mixin rather than a shared base class because each\n * flavor extends a different SPF Media, so there is no common class to put this\n * on, only a common `src` accessor to write through.\n *\n * Unlike the hls.js-backed `MuxMedia`, there is no inherited `source` to\n * delegate to — the SPF Medias know only `src` — so this owns the structured\n * source and dispatches `sourcechange` itself.\n *\n * @fires sourcechange - Fired when `source` changes, either directly or by parsing a new `src`. Read `source` for the new value.\n */\nexport function MuxMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class MuxMediaImpl extends BaseClass {\n    /**\n     * Named on the error copy when this engine can't play a source: the\n     * hls.js-backed Mux Media plays the MPEG-TS and DRM-protected sources that\n     * SPF does not, and it backs both `<mux-video>` and `<mux-audio>`.\n     *\n     * Names the flavor rather than an import path, because one Media is reached\n     * through three of them — `@videojs/html`, `@videojs/react`, and this package\n     * — and each has a different counterpart. The flavor suffix is the one thing\n     * common to the layers a consumer imports elements and components from.\n     */\n    static get alternativeMediaSuggestion(): string | undefined {\n      return 'Try the hls.js-backed Mux media instead: import the `hls-js` flavor in place of the `spf` one.';\n    }\n\n    #source: MuxSourceBase | null = muxMediaDefaultProps.source;\n\n    /**\n     * Media source URL. Setting a Mux stream URL\n     * (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID\n     * and query params into `source`; other URLs are kept as a plain `source.src`.\n     *\n     * Only playback options carry over. Mux identity comes from the URL, and the\n     * signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID,\n     * so carrying them onto a different source would build rejected URLs.\n     */\n    get src(): string {\n      return super.src;\n    }\n\n    set src(value: string) {\n      // A URL already describing the current source leaves it alone. The elements\n      // reflect the derived `src` back to the host, and re-deriving would drop the\n      // params a Mux URL does not carry, such as `poster`.\n      if (super.src === value) return;\n\n      this.source = parseMuxVideoURL(value) ?? (value ? { src: value } : null);\n    }\n\n    /**\n     * Structured Mux source. Setting it derives `src` from the playback ID, custom\n     * domain, and `playback` params (appended as `snake_case` query params). A\n     * `playback.token` replaces all other params — signed URLs bake them into the\n     * token.\n     */\n    get source(): MuxSourceBase | null {\n      return this.#source;\n    }\n\n    set source(value: MuxSourceBase | null) {\n      const source = value ?? null;\n      // Changing anything takes a new object, so handing the same one back costs\n      // nothing.\n      if (source === this.#source) return;\n\n      this.#source = source;\n      super.src = (source && (createMuxVideoURL(source) ?? source.src)) || '';\n\n      this.dispatchEvent?.(new Event('sourcechange'));\n    }\n\n    /**\n     * Image URLs `source` describes rather than plays: `poster` from its `poster`\n     * params, `storyboard` from its `storyboard` params.\n     *\n     * Read-only and re-derived on read, so read it again after `sourcechange`.\n     * Nothing here is applied for you.\n     */\n    get contentData(): MuxContentData {\n      const poster = createMuxPosterURL(this.#source);\n      const storyboard = createMuxStoryboardURL(this.#source);\n\n      return {\n        ...(poster && { poster }),\n        ...(storyboard && { storyboard }),\n      };\n    }\n  }\n\n  // `MixinReturn` sources statics from `Base`, so this mixin's own needs adding\n  // back to the type or callers can't read it.\n  return MuxMediaImpl as unknown as MixinReturn<Base, MuxMediaAPI> & {\n    readonly alternativeMediaSuggestion: string | undefined;\n  };\n}\n"],"mappings":";;AAeA,MAAa,uBAAsC;CACjD,KAAK;CACL,QAAQ;AACV;;;;;;;;;;;;;;;;;AAsBA,SAAgB,cAA6C,WAAiB;CAC5E,MAAM,qBAAqB,UAAU;;;;;;;;;;;EAWnC,WAAW,6BAAiD;GAC1D,OAAO;EACT;EAEA,UAAgC,qBAAqB;;;;;;;;;;EAWrD,IAAI,MAAc;GAChB,OAAO,MAAM;EACf;EAEA,IAAI,IAAI,OAAe;GAIrB,IAAI,MAAM,QAAQ,OAAO;GAEzB,KAAK,SAAS,iBAAiB,KAAK,MAAM,QAAQ,EAAE,KAAK,MAAM,IAAI;EACrE;;;;;;;EAQA,IAAI,SAA+B;GACjC,OAAO,KAAKA;EACd;EAEA,IAAI,OAAO,OAA6B;GACtC,MAAM,SAAS,SAAS;GAGxB,IAAI,WAAW,KAAKA,SAAS;GAE7B,KAAKA,UAAU;GACf,MAAM,MAAO,WAAW,kBAAkB,MAAM,KAAK,OAAO,QAAS;GAErE,KAAK,gBAAgB,IAAI,MAAM,cAAc,CAAC;EAChD;;;;;;;;EASA,IAAI,cAA8B;GAChC,MAAM,SAAS,mBAAmB,KAAKA,OAAO;GAC9C,MAAM,aAAa,uBAAuB,KAAKA,OAAO;GAEtD,OAAO;IACL,GAAI,UAAU,EAAE,OAAO;IACvB,GAAI,cAAc,EAAE,WAAW;GACjC;EACF;CACF;CAIA,OAAO;AAGT"}
+{"version":3,"file":"adapter.js","names":["#source","#refreshContentData","#contentData"],"sources":["../../../../../src/playback/adapters/mux-video/adapter.ts"],"sourcesContent":["import {\n  createMuxPosterURL,\n  createMuxStoryboardURL,\n  createMuxVideoURL,\n  type MuxContentData,\n  type MuxSourceBase,\n  parseMuxVideoURL,\n} from '@videojs/media/dom/mux/source';\nimport { shallowEqual } from '@videojs/utils/object';\nimport type { Constructor, MixinReturn } from '@videojs/utils/types';\n\nexport interface MuxMediaProps {\n  src: string;\n  source: MuxSourceBase | null;\n}\n\nexport const muxMediaDefaultProps: MuxMediaProps = {\n  src: '',\n  source: null,\n};\n\nexport interface MuxMediaAPI extends MuxMediaProps {\n  readonly contentData: MuxContentData;\n}\n\n/**\n * Mux identity over any SPF Media: the structured `source`, the `src` derived\n * from it, and the image URLs it describes.\n *\n * Everything here is Mux identity, so it carries no engine and both flavors get\n * it unchanged — the video Media over the full HLS engine, the audio-only Media\n * over the subtractive one. A mixin rather than a shared base class because each\n * flavor extends a different SPF Media, so there is no common class to put this\n * on, only a common `src` accessor to write through.\n *\n * Unlike the hls.js-backed `MuxMedia`, there is no inherited `source` to\n * delegate to — the SPF Medias know only `src` — so this owns the structured\n * source and dispatches `sourcechange` itself.\n *\n * @fires sourcechange - Fired when `source` changes, either directly or by parsing a new `src`. Read `source` for the new value.\n * @fires contentdatachange - Fired when the derived `contentData` changes. Read `contentData` for the new value.\n */\nexport function MuxMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class MuxMediaImpl extends BaseClass {\n    /**\n     * Named on the error copy when this engine can't play a source: the\n     * hls.js-backed Mux Media plays the MPEG-TS and DRM-protected sources that\n     * SPF does not, and it backs both `<mux-video>` and `<mux-audio>`.\n     *\n     * Names the flavor rather than an import path, because one Media is reached\n     * through three of them — `@videojs/html`, `@videojs/react`, and this package\n     * — and each has a different counterpart. The flavor suffix is the one thing\n     * common to the layers a consumer imports elements and components from.\n     */\n    static get alternativeMediaSuggestion(): string | undefined {\n      return 'Try the hls.js-backed Mux media instead: import the `hls-js` flavor in place of the `spf` one.';\n    }\n\n    #source: MuxSourceBase | null = muxMediaDefaultProps.source;\n    #contentData: MuxContentData = {};\n\n    /**\n     * Media source URL. Setting a Mux stream URL\n     * (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID\n     * and query params into `source`; other URLs are kept as a plain `source.src`.\n     *\n     * Only playback options carry over. Mux identity comes from the URL, and the\n     * signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID,\n     * so carrying them onto a different source would build rejected URLs.\n     */\n    get src(): string {\n      return super.src;\n    }\n\n    set src(value: string) {\n      // A URL already describing the current source leaves it alone. The elements\n      // reflect the derived `src` back to the host, and re-deriving would drop the\n      // params a Mux URL does not carry, such as `poster`.\n      if (super.src === value) return;\n\n      this.source = parseMuxVideoURL(value) ?? (value ? { src: value } : null);\n    }\n\n    /**\n     * Structured Mux source. Setting it derives `src` from the playback ID, custom\n     * domain, and `playback` params (appended as `snake_case` query params). A\n     * `playback.token` replaces all other params — signed URLs bake them into the\n     * token.\n     */\n    get source(): MuxSourceBase | null {\n      return this.#source;\n    }\n\n    set source(value: MuxSourceBase | null) {\n      const source = value ?? null;\n      // Changing anything takes a new object, so handing the same one back costs\n      // nothing.\n      if (source === this.#source) return;\n\n      this.#source = source;\n\n      // Refresh the bag before announcing `sourcechange`, because listeners read\n      // `contentData` from that event. Announcing its own change waits until\n      // after, so `src` is in step by the time either event fires.\n      const contentDataChanged = this.#refreshContentData();\n\n      super.src = (source && (createMuxVideoURL(source) ?? source.src)) || '';\n\n      this.dispatchEvent?.(new Event('sourcechange'));\n\n      if (contentDataChanged) this.dispatchEvent?.(new Event('contentdatachange'));\n    }\n\n    /**\n     * Image URLs `source` describes rather than plays: `poster` from its `poster`\n     * params, `storyboard` from its `storyboard` params.\n     *\n     * Derived from `source` and nothing else. The same object is handed back\n     * until one of those URLs changes, and `contentdatachange` announces it when\n     * it does. Nothing here is applied for you.\n     */\n    get contentData(): MuxContentData {\n      return this.#contentData;\n    }\n\n    /** Rebuild the derived bag, reporting whether anything about it changed. */\n    #refreshContentData(): boolean {\n      const poster = createMuxPosterURL(this.#source);\n      const storyboard = createMuxStoryboardURL(this.#source);\n\n      const next: MuxContentData = {\n        ...(poster && { poster }),\n        ...(storyboard && { storyboard }),\n      };\n\n      if (shallowEqual(this.#contentData, next)) return false;\n\n      this.#contentData = next;\n      return true;\n    }\n  }\n\n  // `MixinReturn` sources statics from `Base`, so this mixin's own needs adding\n  // back to the type or callers can't read it.\n  return MuxMediaImpl as unknown as MixinReturn<Base, MuxMediaAPI> & {\n    readonly alternativeMediaSuggestion: string | undefined;\n  };\n}\n"],"mappings":";;;AAgBA,MAAa,uBAAsC;CACjD,KAAK;CACL,QAAQ;AACV;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,cAA6C,WAAiB;CAC5E,MAAM,qBAAqB,UAAU;;;;;;;;;;;EAWnC,WAAW,6BAAiD;GAC1D,OAAO;EACT;EAEA,UAAgC,qBAAqB;EACrD,eAA+B,CAAC;;;;;;;;;;EAWhC,IAAI,MAAc;GAChB,OAAO,MAAM;EACf;EAEA,IAAI,IAAI,OAAe;GAIrB,IAAI,MAAM,QAAQ,OAAO;GAEzB,KAAK,SAAS,iBAAiB,KAAK,MAAM,QAAQ,EAAE,KAAK,MAAM,IAAI;EACrE;;;;;;;EAQA,IAAI,SAA+B;GACjC,OAAO,KAAKA;EACd;EAEA,IAAI,OAAO,OAA6B;GACtC,MAAM,SAAS,SAAS;GAGxB,IAAI,WAAW,KAAKA,SAAS;GAE7B,KAAKA,UAAU;GAKf,MAAM,qBAAqB,KAAKC,oBAAoB;GAEpD,MAAM,MAAO,WAAW,kBAAkB,MAAM,KAAK,OAAO,QAAS;GAErE,KAAK,gBAAgB,IAAI,MAAM,cAAc,CAAC;GAE9C,IAAI,oBAAoB,KAAK,gBAAgB,IAAI,MAAM,mBAAmB,CAAC;EAC7E;;;;;;;;;EAUA,IAAI,cAA8B;GAChC,OAAO,KAAKC;EACd;;EAGA,sBAA+B;GAC7B,MAAM,SAAS,mBAAmB,KAAKF,OAAO;GAC9C,MAAM,aAAa,uBAAuB,KAAKA,OAAO;GAEtD,MAAM,OAAuB;IAC3B,GAAI,UAAU,EAAE,OAAO;IACvB,GAAI,cAAc,EAAE,WAAW;GACjC;GAEA,IAAI,aAAa,KAAKE,cAAc,IAAI,GAAG,OAAO;GAElD,KAAKA,eAAe;GACpB,OAAO;EACT;CACF;CAIA,OAAO;AAGT"}

package/dist/dev/playback/behaviors/collect-errors.js

@@ -1,4 +1,4 @@
-import { computed, update } from "../../core/signals/primitives.js";
+import { computed, peek, update } from "../../core/signals/primitives.js";
 import { defineBehavior } from "../../core/composition/create-composition.js";
 import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
 import { isResolvedPresentation } from "../../media/types/index.js";
@@ -51,6 +51,40 @@ function emitError(state, error) {
 	update(state.errors, (errors) => [...errors ?? [], error]);
 }
 /**
+* A "constraint" that reports a type the source carries **no** renditions of, for
+* a composition that can't play without it.
+*
+* Strange on purpose, and the strangeness is the point: it never constrains
+* anything, always returning its input untouched. It is shaped as a rule so a
+* composition opts in by adding it to `constraints` — nothing to thread through
+* config, and no cost at all to a composition that leaves it out.
+*
+* **Belongs first in the chain.** A constraint sees the list as it stands at its
+* own position, so only at the head does an empty input mean "the source offers
+* none of this type" rather than "the constraints ahead of me pruned them all."
+*
+* This is the one failure no per-rendition cause can report: causes come from
+* `reportUnsupportedTrackConditions` as each media playlist resolves, and here
+* nothing resolves, because there is nothing to resolve. Everything else already
+* reports something more specific than a verdict.
+*
+* Idempotent because the constraint chain runs inside a `computed` that re-derives
+* on every `presentation` write — segment appends and live reloads included — and
+* the sequence deliberately keeps duplicates. `peek` is what keeps that computed
+* from subscribing to the slot this writes.
+*
+* @example
+* // engine-background-video.ts — video-only, so a source with none can't play
+* constraints: [reportAbsentTrackType(SVTA_NO_SUPPORTED_VIDEO_TRACK), excludeUnplayableTracks]
+*/
+function reportAbsentTrackType(code) {
+	return (tracks, { state }) => {
+		const reported = state.errors && peek(state.errors);
+		if (!tracks.length && !reported?.some((error) => error.code === code)) emitError(state, { code });
+		return tracks;
+	};
+}
+/**
 * Own `errors` for the resolved source's lifetime.
 *
 * @example
@@ -72,6 +106,6 @@ const collectErrors = defineBehavior({
 	}
 });
 //#endregion
-export { collectErrors, emitError };
+export { collectErrors, emitError, reportAbsentTrackType };
 
 //# sourceMappingURL=collect-errors.js.map

package/dist/dev/playback/behaviors/collect-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"collect-errors.js","names":[],"sources":["../../../../src/playback/behaviors/collect-errors.ts"],"sourcesContent":["/**\n * **Owns the engine's error sequence.** Reporters append through\n * {@link emitError}; this behavior owns the slot and its per-source lifecycle,\n * clearing it on exit so a new source starts clean and the sequence can't grow\n * unbounded across a session.\n *\n * Same split as `setupFailoverMonitor` and `failedCdns`: writes come from\n * wherever the condition is detected, one behavior owns the slot. Deliberately\n * has no `effects` — it holds no policy and derives nothing. Severity is decided\n * at the adapter, not here (see `internal/design/spf/features/errors.md`), which\n * is why this is a lifecycle owner rather than an error *handler*.\n *\n * Clearing binds to *exit* of `presentation-resolved`, mirroring the sibling\n * mixins' clear-on-teardown (`emptied` / `MEDIA_DETACHED`). A live reload swaps\n * the presentation object without leaving the resolved state, so it doesn't\n * clear — only an actual source change or destroy does. Known gap: a\n * resolved→resolved source swap that never passes through unresolved carries the\n * prior source's errors forward; `resolve-track` guards the same transition with\n * a commit-time id check, and doing likewise here is a follow-up.\n *\n * The vocabulary itself ({@link SvtaError} and the codes) is DOM- and\n * signal-free in `media/errors`; only the write seam lives here, with the slot\n * it writes.\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, type ReadonlySignal, type Signal, update } from '../../core/signals/primitives';\nimport type { SvtaError } from '../../media/errors';\nimport { isResolvedPresentation, type MaybeResolvedPresentation } from '../../media/types';\n\nexport interface CollectErrorsState {\n  presentation?: MaybeResolvedPresentation;\n  errors?: SvtaError[];\n}\n\n/**\n * State an error reporter writes into. The slot is *optional*: a behavior reports\n * through this seam without declaring ownership in its own typed slice, and\n * emission no-ops when `collectErrors` isn't composed. Same contract as\n * `failedCdns` / `failoverFetch`.\n */\nexport interface ErrorEmitterState {\n  errors?: Signal<SvtaError[] | undefined>;\n}\n\n/**\n * Append `error` to the engine's error sequence. No-op when no owner is\n * composed. Replaces the array rather than mutating it, so signal consumers\n * notify; duplicates are kept, since a repeated condition is a real observation.\n * Writes go through `update` so concurrent reporters can't lose each other's\n * appends.\n *\n * Every emission is logged, deliberately *before* the owner check. A condition\n * emitted with no `collectErrors` composed is dropped on the floor — that's the\n * case where a log is the only evidence it happened at all, so gating the log on\n * the same check would hide exactly what's worth seeing. Emissions that *are*\n * collected still get logged, because reaching `state.errors` is no guarantee of\n * reaching a person: only *verdicts* are promoted to the media surface, so every\n * cause (and any non-fatal notice) is otherwise invisible outside a debugger.\n *\n * Ungated rather than `__DEV__`-only, matching the other reporting paths in this\n * package (`resolve-presentation`, `track-switching`, the segment actors).\n */\nexport function emitError(state: ErrorEmitterState, error: SvtaError): void {\n  console.error('[spf] reported condition', error);\n  if (!state.errors) return;\n  update(state.errors, (errors) => [...(errors ?? []), error]);\n}\n\n/**\n * Own `errors` for the resolved source's lifetime.\n *\n * @example\n * const reactor = collectErrors.setup({ state });\n */\nexport const collectErrors = defineBehavior({\n  stateKeys: ['presentation', 'errors'],\n  contextKeys: [],\n  setup: ({\n    state,\n  }: {\n    state: {\n      presentation: ReadonlySignal<CollectErrorsState['presentation']>;\n      errors: Signal<CollectErrorsState['errors']>;\n    };\n  }) => {\n    const derivedStateSignal = computed(() =>\n      isResolvedPresentation(state.presentation.get())\n        ? ('presentation-resolved' as const)\n        : ('presentation-unresolved' as const)\n    );\n\n    return createMachineReactor({\n      initial: 'presentation-unresolved',\n      monitor: () => derivedStateSignal.get(),\n      states: {\n        'presentation-unresolved': {},\n        'presentation-resolved': {\n          // Cleanup-binds-to-setup: reset for the next source on exit (src\n          // unload + destroy).\n          entry: () => () => state.errors.set(undefined),\n        },\n      },\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,UAAU,OAA0B,OAAwB;CAC1E,QAAQ,MAAM,4BAA4B,KAAK;CAC/C,IAAI,CAAC,MAAM,QAAQ;CACnB,OAAO,MAAM,SAAS,WAAW,CAAC,GAAI,UAAU,CAAC,GAAI,KAAK,CAAC;AAC7D;;;;;;;AAQA,MAAa,gBAAgB,eAAe;CAC1C,WAAW,CAAC,gBAAgB,QAAQ;CACpC,aAAa,CAAC;CACd,QAAQ,EACN,YAMI;EACJ,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,IAAI,CAAC,IAC1C,0BACA,yBACP;EAEA,OAAO,qBAAqB;GAC1B,SAAS;GACT,eAAe,mBAAmB,IAAI;GACtC,QAAQ;IACN,2BAA2B,CAAC;IAC5B,yBAAyB,EAGvB,mBAAmB,MAAM,OAAO,IAAI,KAAA,CAAS,EAC/C;GACF;EACF,CAAC;CACH;AACF,CAAC"}
+{"version":3,"file":"collect-errors.js","names":[],"sources":["../../../../src/playback/behaviors/collect-errors.ts"],"sourcesContent":["/**\n * **Owns the engine's error sequence.** Reporters append through\n * {@link emitError}; this behavior owns the slot and its per-source lifecycle,\n * clearing it on exit so a new source starts clean and the sequence can't grow\n * unbounded across a session.\n *\n * Same split as `setupFailoverMonitor` and `failedCdns`: writes come from\n * wherever the condition is detected, one behavior owns the slot. Deliberately\n * has no `effects` — it holds no policy and derives nothing. Severity is decided\n * at the adapter, not here (see `internal/design/spf/features/errors.md`), which\n * is why this is a lifecycle owner rather than an error *handler*.\n *\n * Clearing binds to *exit* of `presentation-resolved`, mirroring the sibling\n * mixins' clear-on-teardown (`emptied` / `MEDIA_DETACHED`). A live reload swaps\n * the presentation object without leaving the resolved state, so it doesn't\n * clear — only an actual source change or destroy does. Known gap: a\n * resolved→resolved source swap that never passes through unresolved carries the\n * prior source's errors forward; `resolve-track` guards the same transition with\n * a commit-time id check, and doing likewise here is a follow-up.\n *\n * The vocabulary itself ({@link SvtaError} and the codes) is DOM- and\n * signal-free in `media/errors`; only the write seam lives here, with the slot\n * it writes.\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, peek, type ReadonlySignal, type Signal, update } from '../../core/signals/primitives';\nimport type { SvtaError } from '../../media/errors';\nimport { isResolvedPresentation, type MaybeResolvedPresentation } from '../../media/types';\nimport type { SelectionRule } from '../primitives/selection-rules';\n\nexport interface CollectErrorsState {\n  presentation?: MaybeResolvedPresentation;\n  errors?: SvtaError[];\n}\n\n/**\n * State an error reporter writes into. The slot is *optional*: a behavior reports\n * through this seam without declaring ownership in its own typed slice, and\n * emission no-ops when `collectErrors` isn't composed. Same contract as\n * `failedCdns` / `failoverFetch`.\n */\nexport interface ErrorEmitterState {\n  errors?: Signal<SvtaError[] | undefined>;\n}\n\n/**\n * Append `error` to the engine's error sequence. No-op when no owner is\n * composed. Replaces the array rather than mutating it, so signal consumers\n * notify; duplicates are kept, since a repeated condition is a real observation.\n * Writes go through `update` so concurrent reporters can't lose each other's\n * appends.\n *\n * Every emission is logged, deliberately *before* the owner check. A condition\n * emitted with no `collectErrors` composed is dropped on the floor — that's the\n * case where a log is the only evidence it happened at all, so gating the log on\n * the same check would hide exactly what's worth seeing. Emissions that *are*\n * collected still get logged, because reaching `state.errors` is no guarantee of\n * reaching a person: only *verdicts* are promoted to the media surface, so every\n * cause (and any non-fatal notice) is otherwise invisible outside a debugger.\n *\n * Ungated rather than `__DEV__`-only, matching the other reporting paths in this\n * package (`resolve-presentation`, `track-switching`, the segment actors).\n */\nexport function emitError(state: ErrorEmitterState, error: SvtaError): void {\n  console.error('[spf] reported condition', error);\n  if (!state.errors) return;\n  update(state.errors, (errors) => [...(errors ?? []), error]);\n}\n\n/**\n * A \"constraint\" that reports a type the source carries **no** renditions of, for\n * a composition that can't play without it.\n *\n * Strange on purpose, and the strangeness is the point: it never constrains\n * anything, always returning its input untouched. It is shaped as a rule so a\n * composition opts in by adding it to `constraints` — nothing to thread through\n * config, and no cost at all to a composition that leaves it out.\n *\n * **Belongs first in the chain.** A constraint sees the list as it stands at its\n * own position, so only at the head does an empty input mean \"the source offers\n * none of this type\" rather than \"the constraints ahead of me pruned them all.\"\n *\n * This is the one failure no per-rendition cause can report: causes come from\n * `reportUnsupportedTrackConditions` as each media playlist resolves, and here\n * nothing resolves, because there is nothing to resolve. Everything else already\n * reports something more specific than a verdict.\n *\n * Idempotent because the constraint chain runs inside a `computed` that re-derives\n * on every `presentation` write — segment appends and live reloads included — and\n * the sequence deliberately keeps duplicates. `peek` is what keeps that computed\n * from subscribing to the slot this writes.\n *\n * @example\n * // engine-background-video.ts — video-only, so a source with none can't play\n * constraints: [reportAbsentTrackType(SVTA_NO_SUPPORTED_VIDEO_TRACK), excludeUnplayableTracks]\n */\nexport function reportAbsentTrackType<T>(code: number): SelectionRule<T, ErrorEmitterState> {\n  return (tracks, { state }) => {\n    const reported = state.errors && peek(state.errors);\n    if (!tracks.length && !reported?.some((error) => error.code === code)) {\n      emitError(state, { code });\n    }\n    return tracks;\n  };\n}\n\n/**\n * Own `errors` for the resolved source's lifetime.\n *\n * @example\n * const reactor = collectErrors.setup({ state });\n */\nexport const collectErrors = defineBehavior({\n  stateKeys: ['presentation', 'errors'],\n  contextKeys: [],\n  setup: ({\n    state,\n  }: {\n    state: {\n      presentation: ReadonlySignal<CollectErrorsState['presentation']>;\n      errors: Signal<CollectErrorsState['errors']>;\n    };\n  }) => {\n    const derivedStateSignal = computed(() =>\n      isResolvedPresentation(state.presentation.get())\n        ? ('presentation-resolved' as const)\n        : ('presentation-unresolved' as const)\n    );\n\n    return createMachineReactor({\n      initial: 'presentation-unresolved',\n      monitor: () => derivedStateSignal.get(),\n      states: {\n        'presentation-unresolved': {},\n        'presentation-resolved': {\n          // Cleanup-binds-to-setup: reset for the next source on exit (src\n          // unload + destroy).\n          entry: () => () => state.errors.set(undefined),\n        },\n      },\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,UAAU,OAA0B,OAAwB;CAC1E,QAAQ,MAAM,4BAA4B,KAAK;CAC/C,IAAI,CAAC,MAAM,QAAQ;CACnB,OAAO,MAAM,SAAS,WAAW,CAAC,GAAI,UAAU,CAAC,GAAI,KAAK,CAAC;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,sBAAyB,MAAmD;CAC1F,QAAQ,QAAQ,EAAE,YAAY;EAC5B,MAAM,WAAW,MAAM,UAAU,KAAK,MAAM,MAAM;EAClD,IAAI,CAAC,OAAO,UAAU,CAAC,UAAU,MAAM,UAAU,MAAM,SAAS,IAAI,GAClE,UAAU,OAAO,EAAE,KAAK,CAAC;EAE3B,OAAO;CACT;AACF;;;;;;;AAQA,MAAa,gBAAgB,eAAe;CAC1C,WAAW,CAAC,gBAAgB,QAAQ;CACpC,aAAa,CAAC;CACd,QAAQ,EACN,YAMI;EACJ,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,IAAI,CAAC,IAC1C,0BACA,yBACP;EAEA,OAAO,qBAAqB;GAC1B,SAAS;GACT,eAAe,mBAAmB,IAAI;GACtC,QAAQ;IACN,2BAA2B,CAAC;IAC5B,yBAAyB,EAGvB,mBAAmB,MAAM,OAAO,IAAI,KAAA,CAAS,EAC/C;GACF;EACF,CAAC;CACH;AACF,CAAC"}

package/dist/dev/playback/behaviors/dom/track-screen-resolution.js

@@ -0,0 +1,29 @@
+import { defineBehavior } from "../../../core/composition/create-composition.js";
+import { watchScreenResolution } from "../../../media/dom/screen.js";
+//#region src/playback/behaviors/dom/track-screen-resolution.ts
+/**
+* Mirror the screen's pixel dimensions into reactive state, so a rendition cap
+* can narrow candidates to what the screen can actually show without reading the
+* environment at pick time — which would make the picker impure, and would never
+* re-pick when the screen changed.
+*
+* Populated at setup rather than on the first change: `watchScreenResolution`
+* reports its starting value, so nothing downstream waits on a screen that may
+* never move. `undefined` where there is no screen to read, which is the value a
+* cap reads as "no cap" — see `getScreenResolution` on why that beats a zero.
+*
+* Reads no other slot, and has no source-identity reset: the screen is
+* independent of the presentation, so a new `src` doesn't invalidate the reading.
+*/
+function trackScreenResolutionSetup({ state, config }) {
+	return watchScreenResolution((resolution) => state.screenResolution.set(resolution), { useDevicePixelRatio: config?.useDevicePixelRatio ?? true });
+}
+const trackScreenResolution = defineBehavior({
+	stateKeys: ["screenResolution"],
+	contextKeys: [],
+	setup: trackScreenResolutionSetup
+});
+//#endregion
+export { trackScreenResolution };
+
+//# sourceMappingURL=track-screen-resolution.js.map

package/dist/dev/playback/behaviors/dom/track-screen-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-screen-resolution.js","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-screen-resolution.ts"],"sourcesContent":["/**\n * Mirror the screen's pixel dimensions into reactive state, so a rendition cap\n * can narrow candidates to what the screen can actually show without reading the\n * environment at pick time — which would make the picker impure, and would never\n * re-pick when the screen changed.\n *\n * Populated at setup rather than on the first change: `watchScreenResolution`\n * reports its starting value, so nothing downstream waits on a screen that may\n * never move. `undefined` where there is no screen to read, which is the value a\n * cap reads as \"no cap\" — see `getScreenResolution` on why that beats a zero.\n *\n * Reads no other slot, and has no source-identity reset: the screen is\n * independent of the presentation, so a new `src` doesn't invalidate the reading.\n */\nimport { defineBehavior } from '../../../core/composition/create-composition';\nimport type { Signal } from '../../../core/signals/primitives';\nimport { type ScreenResolution, watchScreenResolution } from '../../../media/dom/screen';\n\nexport interface ScreenResolutionState {\n  screenResolution?: ScreenResolution;\n}\n\nexport interface TrackScreenResolutionConfig {\n  /**\n   * Whether the reading is scaled into device pixels. Defaults to `true` — see\n   * `ScreenResolutionOptions.useDevicePixelRatio`, including its note on page\n   * zoom being folded into the ratio outside WebKit.\n   */\n  useDevicePixelRatio?: boolean;\n}\n\nfunction trackScreenResolutionSetup({\n  state,\n  config,\n}: {\n  state: { screenResolution: Signal<ScreenResolutionState['screenResolution']> };\n  config?: TrackScreenResolutionConfig;\n}): () => void {\n  const useDevicePixelRatio = config?.useDevicePixelRatio ?? true;\n\n  // No `effect` wrapper, unlike its `track*` siblings: they re-subscribe when\n  // `context.mediaElement` changes, and this behavior has no reactive dependency\n  // to re-run on. The watcher's own teardown is the whole cleanup.\n  return watchScreenResolution((resolution) => state.screenResolution.set(resolution), { useDevicePixelRatio });\n}\n\nexport const trackScreenResolution = defineBehavior({\n  stateKeys: ['screenResolution'],\n  contextKeys: [],\n  setup: trackScreenResolutionSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;AA+BA,SAAS,2BAA2B,EAClC,OACA,UAIa;CAMb,OAAO,uBAAuB,eAAe,MAAM,iBAAiB,IAAI,UAAU,GAAG,EAAE,qBAL3D,QAAQ,uBAAuB,KAKgD,CAAC;AAC9G;AAEA,MAAa,wBAAwB,eAAe;CAClD,WAAW,CAAC,kBAAkB;CAC9B,aAAa,CAAC;CACd,OAAO;AACT,CAAC"}

package/dist/dev/playback/behaviors/select-tracks.d.ts

@@ -1,14 +1,72 @@
 import "../../core/signals/primitives.js";
 import "../../index.js";
-import { TrackPicker, VideoSelectionConfig } from "../../media/primitives/select-tracks.js";
+import { CapabilityConstraintConfig, SelectionRule } from "../primitives/selection-rules.js";
 //#region src/playback/behaviors/select-tracks.d.ts
+/** A selection rule over this behavior's candidate tracks. */
+type SelectTrackRule<Config> = SelectionRule<SelectableTrack, unknown, unknown, Config | undefined>;
+/** What a rule here needs off a candidate: the id it may become the pick by. */
+type SelectableTrack = {
+  id: string;
+};
 /**
- * Config for `selectVideoTrack`. Pass `picker` to fully override selection
- * logic; otherwise the default `pickFirstTrackId` is used.
+ * Order the candidates by resolution, largest first, with bandwidth breaking ties
+ * between renditions of identical dimensions. The background-video default — that
+ * variant pins one rendition for the session, and absent a cap the largest is the
+ * head.
+ *
+ * A ranker, so it reorders rather than narrowing: the chain's pick is the head of
+ * what it returns, which means ranking never has to collapse to one track. Belongs
+ * last in a chain — a sort only reorders what survived the filters ahead of it, and
+ * leaving it last is what lets `applyRules` early-bail before it runs.
+ *
+ * Exported because it is a *rule*, not a variant's private policy: the same one
+ * composes into `switchVideoTrack`'s chain when a ranker is wanted there.
  */
-interface SelectVideoTrackConfig extends VideoSelectionConfig {
-  picker?: TrackPicker<SelectVideoTrackConfig>;
+declare const preferHighestResolution: SelectTrackRule<unknown>;
+/**
+ * Narrow to the renditions that fit the screen, by pixel area — the screen-size
+ * cap from `internal/design/spf/features/rendition-selection-caps.md`, as a scope
+ * (soft filter) rather than a constraint: an over-cap rendition is wasteful, not
+ * unplayable, so nothing here may make a source unplayable.
+ *
+ * Narrows only — it neither orders the survivors nor resolves the case where none
+ * survive, because `applyRules` owns both. So it needs a ranker behind it to pick
+ * within the cap: `[screenResolutionCap, preferHighestResolution]` yields the
+ * largest rendition that fits. Composed *last*, the pick would instead be whichever
+ * fitting rendition the manifest happened to list first.
+ *
+ * Reading `state.screenResolution` through its signal is what subscribes a
+ * re-evaluating chain (`switchVideoTrack`) to screen changes; `selectVideoTrack`
+ * pins the first answer instead, by design.
+ *
+ * Compares areas rather than matching a `"1080p"`-style tier because a tier only
+ * describes a rendition once you assume its aspect ratio — the assumption that
+ * mis-measures an anamorphic ladder. See `media/dom/screen.ts`.
+ *
+ * Three ways the cap ends up not applying, all of them fall-through:
+ *
+ * - **No `screenResolution` signal at all**, because the composition omits
+ *   `trackScreenResolution`. So composing the cap without its signal source is
+ *   inert rather than broken.
+ * - **A `screenResolution` of `undefined`**, meaning no screen to read. "Unknown"
+ *   has to mean "don't cap": treating it as an area of zero would pin every source
+ *   to its smallest rendition on exactly the environments we know least about.
+ * - **No rendition fits**, on a screen smaller than the whole ladder. `applyRules`
+ *   skips the empty result and the chain proceeds unnarrowed, so the ranker behind
+ *   the cap decides — for `preferHighestResolution`, the largest rendition. A floor
+ *   is the fix if that ever matters (`rendition-selection-caps.md` carries one), not
+ *   a special case here.
+ */
+declare const screenResolutionCap: SelectTrackRule<unknown>;
+/**
+ * Config for `selectVideoTrack`. Pass `rules` to replace the selection chain, or
+ * `constraints` to replace the capability pre-pass; otherwise the chain is empty
+ * and the first playable candidate is the pick.
+ */
+interface SelectVideoTrackConfig extends CapabilityConstraintConfig {
+  constraints?: readonly SelectTrackRule<SelectVideoTrackConfig>[];
+  rules?: readonly SelectTrackRule<SelectVideoTrackConfig>[];
 }
 //#endregion
-export { SelectVideoTrackConfig };
+export { SelectTrackRule, SelectVideoTrackConfig, preferHighestResolution, screenResolutionCap };
 //# sourceMappingURL=select-tracks.d.ts.map

package/dist/dev/playback/behaviors/select-tracks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-tracks.d.ts","names":[],"sources":["../../../../src/playback/behaviors/select-tracks.ts"],"mappings":";;;;;;;;UA0IiB,+BAA+B;EAC9C,SAAS,YAAY"}
+{"version":3,"file":"select-tracks.d.ts","names":[],"sources":["../../../../src/playback/behaviors/select-tracks.ts"],"mappings":";;;;;KA6FY,gBAAgB,UAAU,cAAc,mCAAmC;;KAGlF;EAAoB;;;;;;;;;;;;;;;;cA+JZ,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+CzB,qBAAqB;;;;;;UAgBjB,+BAA+B;EAC9C,uBAAuB,gBAAgB;EACvC,iBAAiB,gBAAgB"}