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

package/dist/default/playback/primitives/selection-rules.js

@@ -30,9 +30,10 @@ function applyRules(rules, tracks, deps) {
 * `applyRules`, this never skips an empty result and never early-bails — every
 * constraint always applies, and an empty survivor set is a real outcome
 * ("nothing playable here"), not a fall-through. Because each constraint only
-* removes, the order they run in can't change the result.
+* removes, the order they run in can't change which tracks survive — though one
+* that also *reports* reads the list at its own position, so placement matters.
 *
-* @param constraints - Constraints to apply (pooled, order-independent)
+* @param constraints - Constraints to apply, in order
 * @param tracks - Candidate tracks
 * @param deps - The behavior's `{ state, context, config }`, passed to each constraint
 * @returns The playable survivors (possibly empty)
@@ -72,7 +73,7 @@ function sameCandidateSet(a, b) {
 * Passes everything through when there's no probe (a composition that didn't
 * wire one, or DOM-free tests). When it prunes *every* track, the empty result is
 * preserved (per `applyConstraints`) — "nothing playable" — which each consuming
-* behavior answers by clearing its selection and reporting the type's verdict.
+* behavior answers by clearing its selection; reporting the verdict is separate.
 */
 function excludeUnplayableTracks(tracks, { config }) {
 	const canPlay = config?.canPlayTrack;

package/dist/default/playback/primitives/selection-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"selection-rules.js","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"sourcesContent":["/**\n * The selection-rule substrate: the shape of a rule, and the two composers that\n * turn a list of them into a pick.\n *\n * Lives here rather than beside `switchVideoTrack` so both track-selection\n * behaviors can share rules. The simple `selectVideoTrack` variant exists\n * specifically to tree-shake the ABR path out, so importing a composer from\n * `behaviors/track-switching.ts` would drag the bandwidth estimator and quality\n * selection back in with it. These four have no dependencies at all — pure\n * generics over a candidate list — so either side can reach them freely.\n *\n * See `internal/design/spf/track-switching-model.md` for the model these\n * implement: a hard constraints pre-pass, then an ordered chain of soft\n * narrowing rules and rankers, with the pick as the first survivor.\n */\n\nimport type { CanPlayTrack } from '../../media/types';\n\n/**\n * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup\n * deps so a rule reads from the same surfaces a behavior does. `context` is\n * optional — it's threaded through but absent on direct setup calls (and\n * unread by today's rules), so the whole deps object can pass straight through.\n */\nexport interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown> {\n  state: State;\n  context?: Context;\n  config: Config;\n}\n\n/**\n * A selection rule narrows or reorders the candidate list. It reads the state,\n * context, and config it needs at apply time (tightly-coupled reads), so a\n * rule's `.get()`s subscribe the running effect to exactly what it consulted.\n * Returning an empty list means \"no match\" — the composer skips it, so a soft\n * filter never narrows the set to nothing. A ranker returns the list with its\n * pick at the head.\n */\nexport type SelectionRule<T, State = unknown, Context = unknown, Config = unknown> = (\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n) => readonly T[];\n\n/**\n * Apply rules to a candidate list in order; the pick is the first survivor.\n * Two responsibilities the rules don't carry: a rule that returns nothing is\n * skipped (fall-through — a preference never empties the set), and once one\n * survivor remains the chain stops (early-bail — later rules, including the\n * bandwidth ranker, never run, so the effect doesn't subscribe to their\n * signals while the choice is fixed).\n *\n * @param rules - Rules to apply, most authoritative first\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed through to each rule\n * @returns The surviving candidates, pick first\n */\nexport function applyRules<T, State, Context, Config>(\n  rules: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const rule of rules) {\n    const remaining = rule(current, deps);\n    if (remaining.length === 0) continue;\n    current = remaining;\n    if (current.length === 1) break;\n  }\n  return current;\n}\n\n/**\n * Apply hard constraints to a candidate list — the pre-pass that runs before the\n * rule chain. A constraint shares a rule's signature but its exclusion is\n * *hard*: it removes the unplayable (a codec the environment can't decode, a CDN\n * in failover cooldown) and a removed track is never attempted. Unlike\n * `applyRules`, this never skips an empty result and never early-bails — every\n * constraint always applies, and an empty survivor set is a real outcome\n * (\"nothing playable here\"), not a fall-through. Because each constraint only\n * removes, the order they run in can't change the result.\n *\n * @param constraints - Constraints to apply (pooled, order-independent)\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed to each constraint\n * @returns The playable survivors (possibly empty)\n */\nexport function applyConstraints<T, State, Context, Config>(\n  constraints: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const constraint of constraints) current = constraint(current, deps);\n  return current;\n}\n\n/**\n * Whether two candidate sets hold the same tracks, by id.\n *\n * The `equals` both selection behaviors give their candidate-set `computed`. A\n * live playlist refresh swaps in a new presentation object carrying the same\n * variants, and a constraint's own inputs can churn without changing which\n * tracks survive; in both cases the set is unchanged and the reaction must not\n * re-fire. Compares by id rather than array identity for exactly that.\n */\nexport function sameCandidateSet<T extends { id: string }>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((track) => b.some((other) => other.id === track.id));\n}\n\n/**\n * What {@link excludeUnplayableTracks} reads off the config it is handed.\n *\n * Read through a cast rather than constraining the rule's `Config` generic, the\n * same way `screenResolutionCap` reads `screenResolution` off its state: a rule\n * composes into chains whose config types have nothing else in common, and\n * constraining the generic would make every one of those a weak-type mismatch.\n * Each engine defaults `canPlayTrack` to the DOM-bound probe; unwired means \"no\n * capability filtering\" and the constraint passes everything through.\n */\nexport interface CapabilityConstraintConfig {\n  canPlayTrack?: CanPlayTrack;\n}\n\n/**\n * Capability constraint — a *hard* filter for the {@link applyConstraints}\n * pre-pass. Removes renditions this environment can't decode, probed via the\n * injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the\n * container and encryption assertions that probe can't make). Constraining here\n * — before selection — means an unplayable variant is pruned upstream and never\n * picked, instead of surviving into the pipeline to fail late at\n * `createSourceBuffer`. That late throw stays as a defensive structural\n * guarantee; with this constraint it should rarely fire.\n *\n * Lives here rather than beside `switchVideoTrack` for the reason this module\n * exists: both the re-evaluating variant and the pinned `selectVideoTrack` apply\n * it, and reaching it through `behaviors/track-switching.ts` would drag the ABR\n * path into a composition that deliberately omits it.\n *\n * Passes everything through when there's no probe (a composition that didn't\n * wire one, or DOM-free tests). When it prunes *every* track, the empty result is\n * preserved (per `applyConstraints`) — \"nothing playable\" — which each consuming\n * behavior answers by clearing its selection and reporting the type's verdict.\n */\nexport function excludeUnplayableTracks<T, State, Context, Config>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  const canPlay = (config as CapabilityConstraintConfig | undefined)?.canPlayTrack;\n  if (!canPlay) return tracks;\n  return tracks.filter((track) => canPlay(track as Parameters<CanPlayTrack>[0]));\n}\n"],"mappings":";;;;;;;;;;;;;;AAwDA,SAAgB,WACd,OACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,YAAY,KAAK,SAAS,IAAI;EACpC,IAAI,UAAU,WAAW,GAAG;EAC5B,UAAU;EACV,IAAI,QAAQ,WAAW,GAAG;CAC5B;CACA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBACd,aACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,cAAc,aAAa,UAAU,WAAW,SAAS,IAAI;CACxE,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,iBAA2C,GAAiB,GAA0B;CACpG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM,EAAE,CAAC;AAC7F;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,wBACd,QACA,EAAE,UACY;CACd,MAAM,UAAW,QAAmD;CACpE,IAAI,CAAC,SAAS,OAAO;CACrB,OAAO,OAAO,QAAQ,UAAU,QAAQ,KAAoC,CAAC;AAC/E"}
+{"version":3,"file":"selection-rules.js","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"sourcesContent":["/**\n * The selection-rule substrate: the shape of a rule, and the two composers that\n * turn a list of them into a pick.\n *\n * Lives here rather than beside `switchVideoTrack` so both track-selection\n * behaviors can share rules. The simple `selectVideoTrack` variant exists\n * specifically to tree-shake the ABR path out, so importing a composer from\n * `behaviors/track-switching.ts` would drag the bandwidth estimator and quality\n * selection back in with it. These four have no dependencies at all — pure\n * generics over a candidate list — so either side can reach them freely.\n *\n * See `internal/design/spf/track-switching-model.md` for the model these\n * implement: a hard constraints pre-pass, then an ordered chain of soft\n * narrowing rules and rankers, with the pick as the first survivor.\n */\n\nimport type { CanPlayTrack } from '../../media/types';\n\n/**\n * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup\n * deps so a rule reads from the same surfaces a behavior does. `context` is\n * optional — it's threaded through but absent on direct setup calls (and\n * unread by today's rules), so the whole deps object can pass straight through.\n */\nexport interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown> {\n  state: State;\n  context?: Context;\n  config: Config;\n}\n\n/**\n * A selection rule narrows or reorders the candidate list. It reads the state,\n * context, and config it needs at apply time (tightly-coupled reads), so a\n * rule's `.get()`s subscribe the running effect to exactly what it consulted.\n * Returning an empty list means \"no match\" — the composer skips it, so a soft\n * filter never narrows the set to nothing. A ranker returns the list with its\n * pick at the head.\n */\nexport type SelectionRule<T, State = unknown, Context = unknown, Config = unknown> = (\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n) => readonly T[];\n\n/**\n * Apply rules to a candidate list in order; the pick is the first survivor.\n * Two responsibilities the rules don't carry: a rule that returns nothing is\n * skipped (fall-through — a preference never empties the set), and once one\n * survivor remains the chain stops (early-bail — later rules, including the\n * bandwidth ranker, never run, so the effect doesn't subscribe to their\n * signals while the choice is fixed).\n *\n * @param rules - Rules to apply, most authoritative first\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed through to each rule\n * @returns The surviving candidates, pick first\n */\nexport function applyRules<T, State, Context, Config>(\n  rules: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const rule of rules) {\n    const remaining = rule(current, deps);\n    if (remaining.length === 0) continue;\n    current = remaining;\n    if (current.length === 1) break;\n  }\n  return current;\n}\n\n/**\n * Apply hard constraints to a candidate list — the pre-pass that runs before the\n * rule chain. A constraint shares a rule's signature but its exclusion is\n * *hard*: it removes the unplayable (a codec the environment can't decode, a CDN\n * in failover cooldown) and a removed track is never attempted. Unlike\n * `applyRules`, this never skips an empty result and never early-bails — every\n * constraint always applies, and an empty survivor set is a real outcome\n * (\"nothing playable here\"), not a fall-through. Because each constraint only\n * removes, the order they run in can't change which tracks survive — though one\n * that also *reports* reads the list at its own position, so placement matters.\n *\n * @param constraints - Constraints to apply, in order\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed to each constraint\n * @returns The playable survivors (possibly empty)\n */\nexport function applyConstraints<T, State, Context, Config>(\n  constraints: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const constraint of constraints) current = constraint(current, deps);\n  return current;\n}\n\n/**\n * Whether two candidate sets hold the same tracks, by id.\n *\n * The `equals` both selection behaviors give their candidate-set `computed`. A\n * live playlist refresh swaps in a new presentation object carrying the same\n * variants, and a constraint's own inputs can churn without changing which\n * tracks survive; in both cases the set is unchanged and the reaction must not\n * re-fire. Compares by id rather than array identity for exactly that.\n */\nexport function sameCandidateSet<T extends { id: string }>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((track) => b.some((other) => other.id === track.id));\n}\n\n/**\n * What {@link excludeUnplayableTracks} reads off the config it is handed.\n *\n * Read through a cast rather than constraining the rule's `Config` generic, the\n * same way `screenResolutionCap` reads `screenResolution` off its state: a rule\n * composes into chains whose config types have nothing else in common, and\n * constraining the generic would make every one of those a weak-type mismatch.\n * Each engine defaults `canPlayTrack` to the DOM-bound probe; unwired means \"no\n * capability filtering\" and the constraint passes everything through.\n */\nexport interface CapabilityConstraintConfig {\n  canPlayTrack?: CanPlayTrack;\n}\n\n/**\n * Capability constraint — a *hard* filter for the {@link applyConstraints}\n * pre-pass. Removes renditions this environment can't decode, probed via the\n * injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the\n * container and encryption assertions that probe can't make). Constraining here\n * — before selection — means an unplayable variant is pruned upstream and never\n * picked, instead of surviving into the pipeline to fail late at\n * `createSourceBuffer`. That late throw stays as a defensive structural\n * guarantee; with this constraint it should rarely fire.\n *\n * Lives here rather than beside `switchVideoTrack` for the reason this module\n * exists: both the re-evaluating variant and the pinned `selectVideoTrack` apply\n * it, and reaching it through `behaviors/track-switching.ts` would drag the ABR\n * path into a composition that deliberately omits it.\n *\n * Passes everything through when there's no probe (a composition that didn't\n * wire one, or DOM-free tests). When it prunes *every* track, the empty result is\n * preserved (per `applyConstraints`) — \"nothing playable\" — which each consuming\n * behavior answers by clearing its selection; reporting the verdict is separate.\n */\nexport function excludeUnplayableTracks<T, State, Context, Config>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  const canPlay = (config as CapabilityConstraintConfig | undefined)?.canPlayTrack;\n  if (!canPlay) return tracks;\n  return tracks.filter((track) => canPlay(track as Parameters<CanPlayTrack>[0]));\n}\n"],"mappings":";;;;;;;;;;;;;;AAwDA,SAAgB,WACd,OACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,YAAY,KAAK,SAAS,IAAI;EACpC,IAAI,UAAU,WAAW,GAAG;EAC5B,UAAU;EACV,IAAI,QAAQ,WAAW,GAAG;CAC5B;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;AAkBA,SAAgB,iBACd,aACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,cAAc,aAAa,UAAU,WAAW,SAAS,IAAI;CACxE,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,iBAA2C,GAAiB,GAA0B;CACpG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM,EAAE,CAAC;AAC7F;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,wBACd,QACA,EAAE,UACY;CACd,MAAM,UAAW,QAAmD;CACpE,IAAI,CAAC,SAAS,OAAO;CACrB,OAAO,OAAO,QAAQ,UAAU,QAAQ,KAAoC,CAAC;AAC/E"}

package/dist/dev/media/dom/screen.d.ts

@@ -1,26 +1,7 @@
+import { Resolution } from "../primitives/resolution.js";
 //#region src/media/dom/screen.d.ts
-/**
- * Screen resolution, as the signal source for a screen-size rendition cap.
- *
- * Reported as a width and a height rather than a `"720p"`-style tier, because
- * the cap that consumes it compares against real track dimensions. A tier only
- * describes a track once you assume its aspect ratio, and that assumption
- * mis-measures an anamorphic or otherwise non-16:9 rendition.
- *
- * The signal source for the screen-size cap in
- * `internal/design/spf/features/rendition-selection-caps.md`.
- *
- * The screen underneath a window is not stable: rotating a device swaps the axes,
- * and unplugging a monitor or dragging the window to another display changes the
- * numbers *and* which physical screen they describe. So `getScreenResolution`
- * reads at call time and caches nothing, and `watchScreenResolution` layers the
- * reacting on top rather than the reader holding state of its own.
- */
 /** A screen's pixel dimensions. */
-interface ScreenResolution {
-  readonly width: number;
-  readonly height: number;
-}
+type ScreenResolution = Resolution;
 //#endregion
 export { ScreenResolution };
 //# sourceMappingURL=screen.d.ts.map

package/dist/dev/media/dom/screen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screen.d.ts","names":[],"sources":["../../../../src/media/dom/screen.ts"],"mappings":";;;;;;;;;;;;;;;;;;;UAuBiB;WACN;WACA"}
+{"version":3,"file":"screen.d.ts","names":[],"sources":["../../../../src/media/dom/screen.ts"],"mappings":";;;KAwBY,mBAAmB"}

package/dist/dev/media/dom/screen.js

@@ -1,4 +1,5 @@
-import { listen } from "@videojs/utils/dom";
+import { scaleResolution } from "../primitives/resolution.js";
+import { getDevicePixelRatio, listen, watchDevicePixelRatio } from "@videojs/utils/dom";
 import { isFunction } from "@videojs/utils/predicate";
 import { shallowEqual } from "@videojs/utils/object";
 //#region src/media/dom/screen.ts
@@ -36,13 +37,7 @@ import { shallowEqual } from "@videojs/utils/object";
 function getScreenResolution({ useDevicePixelRatio } = { useDevicePixelRatio: true }) {
 	const screen = globalThis.screen;
 	if (!screen) return void 0;
-	const ratio = useDevicePixelRatio ? globalThis.devicePixelRatio || 1 : 1;
-	const width = Math.round(screen.width * ratio);
-	const height = Math.round(screen.height * ratio);
-	return width > 0 && height > 0 ? {
-		width,
-		height
-	} : void 0;
+	return scaleResolution(screen, useDevicePixelRatio ? getDevicePixelRatio() : 1);
 }
 /**
 * Call `onChange` whenever {@link getScreenResolution} would start answering
@@ -72,10 +67,9 @@ function getScreenResolution({ useDevicePixelRatio } = { useDevicePixelRatio: tr
 *   when the display it was on goes away.
 * - **`screen.orientation` change** — rotation, which swaps the axes without
 *   necessarily resizing the window.
-* - **a `(resolution: <ratio>dppx)` media query** — the device pixel ratio
-*   changing under a window that kept its size, which is the cross-display drag
-*   between displays of different density. Each query only answers about the ratio
-*   it was built for, so it reports one change and its handler arms the next.
+* - **a `(resolution: <ratio>dppx)` media query** (`watchDevicePixelRatio`) — the
+*   device pixel ratio changing under a window that kept its size, which is the
+*   cross-display drag between displays of different density.
 *
 *   Worth keeping despite looking redundant, because it is the only coverage that
 *   case has in WebKit and Firefox: neither implements `screen`'s change event,
@@ -101,18 +95,7 @@ function watchScreenResolution(onChange, options = { useDevicePixelRatio: true }
 		onChange(next);
 	};
 	onChange(current);
-	const watchRatio = () => {
-		const query = globalThis.matchMedia?.(`(resolution: ${globalThis.devicePixelRatio}dppx)`);
-		if (!query) return;
-		listen(query, "change", () => {
-			watchRatio();
-			check();
-		}, {
-			once: true,
-			signal
-		});
-	};
-	watchRatio();
+	watchDevicePixelRatio(check, signal);
 	const screen = globalThis.screen;
 	const orientation = screen?.orientation;
 	if (globalThis.window) listen(globalThis.window, "resize", check, { signal });

package/dist/dev/media/dom/screen.js.map

@@ -1 +1 @@
-{"version":3,"file":"screen.js","names":[],"sources":["../../../../src/media/dom/screen.ts"],"sourcesContent":["/**\n * Screen resolution, as the signal source for a screen-size rendition cap.\n *\n * Reported as a width and a height rather than a `\"720p\"`-style tier, because\n * the cap that consumes it compares against real track dimensions. A tier only\n * describes a track once you assume its aspect ratio, and that assumption\n * mis-measures an anamorphic or otherwise non-16:9 rendition.\n *\n * The signal source for the screen-size cap in\n * `internal/design/spf/features/rendition-selection-caps.md`.\n *\n * The screen underneath a window is not stable: rotating a device swaps the axes,\n * and unplugging a monitor or dragging the window to another display changes the\n * numbers *and* which physical screen they describe. So `getScreenResolution`\n * reads at call time and caches nothing, and `watchScreenResolution` layers the\n * reacting on top rather than the reader holding state of its own.\n */\n\nimport { listen } from '@videojs/utils/dom';\nimport { shallowEqual } from '@videojs/utils/object';\nimport { isFunction } from '@videojs/utils/predicate';\n\n/** A screen's pixel dimensions. */\nexport interface ScreenResolution {\n  readonly width: number;\n  readonly height: number;\n}\n\nexport interface ScreenResolutionOptions {\n  /**\n   * Scale the reading from CSS pixels into device pixels. On by default, since\n   * device pixels are what the screen actually has, and a rendition's dimensions\n   * are in the same units.\n   *\n   * Opt out for CSS pixels. Note that derating — a 3x phone rarely wanting 3x the\n   * pixels of its layout — is a scale applied over this reading rather than a\n   * reason to turn it off.\n   *\n   * ⚠️ Chromium and Gecko fold page zoom into `devicePixelRatio`, so with this on,\n   * zooming moves the reading even though the screen didn't change. WebKit holds\n   * the ratio independent of zoom and is unaffected. Whether a cap should track\n   * zoom is the cap's call; this flag is only what puts zoom in scope.\n   */\n  useDevicePixelRatio: boolean;\n}\n\n/**\n * Read the screen's resolution, or `undefined` where there isn't one to read.\n *\n * `undefined` means \"unknown\", which is the answer a cap needs in order to not\n * cap. `screenResolutionCap` reads it that way and declines to narrow, so an\n * unknown screen is \"no cap\" rather than a cap of zero — the reading a naive\n * `?? 0` would produce, which would pin every source to its smallest rendition on\n * exactly the environments we know least about.\n *\n * Dimensions are reported as-is, including the axis swap a rotated device\n * applies to them. Normalizing orientation away is a policy question — whether a\n * cap should flap on rotation, or hold the larger budget across both — and\n * belongs to the cap rather than to the reading.\n */\nexport function getScreenResolution(\n  { useDevicePixelRatio }: ScreenResolutionOptions = { useDevicePixelRatio: true }\n): ScreenResolution | undefined {\n  const screen = globalThis.screen;\n  if (!screen) return undefined;\n\n  // `|| 1` covers a missing or nonsense ratio: a CSS-pixel reading is still true\n  // and still cappable, so it isn't worth failing the whole answer over.\n  const ratio = useDevicePixelRatio ? globalThis.devicePixelRatio || 1 : 1;\n\n  // Rounded because device pixels are whole and a fractional ratio doesn't divide\n  // a screen evenly. `NaN` from a nonsense dimension fails the check below, since\n  // no comparison against it holds.\n  const width = Math.round(screen.width * ratio);\n  const height = Math.round(screen.height * ratio);\n\n  return width > 0 && height > 0 ? { width, height } : undefined;\n}\n\n/**\n * Call `onChange` whenever {@link getScreenResolution} would start answering\n * differently. Returns a function that stops watching.\n *\n * There is no single event for \"the screen changed\", so this subscribes to every\n * signal that implies one and compares readings to decide whether anything\n * actually moved. Comparing is what makes that safe: the signals overlap and\n * `resize` in particular is noisy, so over-subscribing costs a discarded read\n * rather than a spurious call.\n *\n * `onChange` is called once on subscribe with the starting value — including\n * `undefined` where there is no screen — and after that only on a genuine change.\n * So a consumer gets its initial state from the watcher and never has to pair it\n * with a separate {@link getScreenResolution} call.\n *\n * The signals, and what each one is here for:\n *\n * - **`screen`'s own `change`** — the screen itself being reconfigured, or the\n *   window landing on a different one. The direct signal, and the only one that\n *   catches a window moving between two same-size, same-ratio displays. From the\n *   Window Management API, but on the base `Screen` rather than behind\n *   `getScreenDetails()`, so it needs no permission — only a secure context.\n *   Measured present in Chromium and absent in WebKit and Firefox, hence the\n *   three below rather than this alone.\n * - **`resize`** — the window changing size, which is also what the OS does to it\n *   when the display it was on goes away.\n * - **`screen.orientation` change** — rotation, which swaps the axes without\n *   necessarily resizing the window.\n * - **a `(resolution: <ratio>dppx)` media query** — the device pixel ratio\n *   changing under a window that kept its size, which is the cross-display drag\n *   between displays of different density. Each query only answers about the ratio\n *   it was built for, so it reports one change and its handler arms the next.\n *\n *   Worth keeping despite looking redundant, because it is the only coverage that\n *   case has in WebKit and Firefox: neither implements `screen`'s change event,\n *   and the drag doesn't resize the window. It is also a cleaner signal in Safari\n *   than elsewhere — WebKit holds `devicePixelRatio` independent of page zoom, so\n *   there it moves only on a real density change, where Chromium and Gecko fold\n *   zoom into it as well.\n *\n * ⚠️ Known gap, on engines without `screen`'s change event: dragging a window\n * between two different-size displays that share a ratio, without the window\n * resizing, changes the reading with nothing firing. Closing it there would mean\n * polling, whose interval and battery cost are a policy decision this function\n * shouldn't be making.\n */\nexport function watchScreenResolution(\n  onChange: (resolution: ScreenResolution | undefined) => void,\n  options: ScreenResolutionOptions = { useDevicePixelRatio: true }\n): () => void {\n  // One signal for every listener, so stopping is one call rather than a handle\n  // per subscription. Also makes a late `watchRatio` inert: `addEventListener`\n  // drops a listener whose signal has already aborted.\n  const disconnect = new AbortController();\n  const { signal } = disconnect;\n  let current = getScreenResolution(options);\n\n  const check = () => {\n    const next = getScreenResolution(options);\n    if (shallowEqual(current, next)) return;\n\n    current = next;\n    onChange(next);\n  };\n\n  // Deliver the starting value up front, so a consumer gets its initial state from\n  // the watcher rather than having to pair it with a separate read. Unconditional,\n  // rather than falling out of comparing against an empty `current`: an unknown\n  // reading is a value too, and a consumer that only ever heard from us about a\n  // *known* screen couldn't tell \"there is no screen\" from \"not called yet\".\n  //\n  // Before the listeners rather than after, so a callback that throws takes\n  // nothing with it — there is no subscription yet to strand.\n  onChange(current);\n\n  // A `dppx` query only answers about the ratio it was built for, so each one\n  // reports a single change and the handler builds the next. `once: true` is what\n  // keeps that from accumulating listeners: the fired one is gone before the\n  // replacement is armed, with no handle to track. Same shape as MDN's snippet\n  // for this, whose earlier non-re-arming version fired exactly once and stopped.\n  const watchRatio = () => {\n    const query = globalThis.matchMedia?.(`(resolution: ${globalThis.devicePixelRatio}dppx)`);\n    if (!query) return;\n\n    listen(\n      query,\n      'change',\n      () => {\n        watchRatio();\n        check();\n      },\n      { once: true, signal }\n    );\n  };\n\n  watchRatio();\n\n  // Each signal is optional for the same reason the reading is: an environment\n  // missing one has nothing to report from it, which is not a reason to fail.\n  // `screen`'s own change event is subscribed without feature-detecting — where\n  // it isn't implemented it simply never fires, and a signal that never fires\n  // costs nothing under comparison.\n  const screen = globalThis.screen;\n  const orientation = screen?.orientation;\n\n  if (globalThis.window) listen(globalThis.window, 'resize', check, { signal });\n  // NOTE: Chromium browsers support screen change event.\n  // See: https://developer.mozilla.org/en-US/docs/Web/API/Screen/change_event\n  if (isEventTarget(screen)) listen(screen, 'change', check, { signal });\n  if (orientation) listen(orientation, 'change', check, { signal });\n\n  return () => disconnect.abort();\n}\n\nfunction isEventTarget(value: any): value is EventTarget {\n  return isFunction(value?.addEventListener);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,oBACd,EAAE,wBAAiD,EAAE,qBAAqB,KAAK,GACjD;CAC9B,MAAM,SAAS,WAAW;CAC1B,IAAI,CAAC,QAAQ,OAAO,KAAA;CAIpB,MAAM,QAAQ,sBAAsB,WAAW,oBAAoB,IAAI;CAKvE,MAAM,QAAQ,KAAK,MAAM,OAAO,QAAQ,KAAK;CAC7C,MAAM,SAAS,KAAK,MAAM,OAAO,SAAS,KAAK;CAE/C,OAAO,QAAQ,KAAK,SAAS,IAAI;EAAE;EAAO;CAAO,IAAI,KAAA;AACvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,sBACd,UACA,UAAmC,EAAE,qBAAqB,KAAK,GACnD;CAIZ,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,EAAE,WAAW;CACnB,IAAI,UAAU,oBAAoB,OAAO;CAEzC,MAAM,cAAc;EAClB,MAAM,OAAO,oBAAoB,OAAO;EACxC,IAAI,aAAa,SAAS,IAAI,GAAG;EAEjC,UAAU;EACV,SAAS,IAAI;CACf;CAUA,SAAS,OAAO;CAOhB,MAAM,mBAAmB;EACvB,MAAM,QAAQ,WAAW,aAAa,gBAAgB,WAAW,iBAAiB,MAAM;EACxF,IAAI,CAAC,OAAO;EAEZ,OACE,OACA,gBACM;GACJ,WAAW;GACX,MAAM;EACR,GACA;GAAE,MAAM;GAAM;EAAO,CACvB;CACF;CAEA,WAAW;CAOX,MAAM,SAAS,WAAW;CAC1B,MAAM,cAAc,QAAQ;CAE5B,IAAI,WAAW,QAAQ,OAAO,WAAW,QAAQ,UAAU,OAAO,EAAE,OAAO,CAAC;CAG5E,IAAI,cAAc,MAAM,GAAG,OAAO,QAAQ,UAAU,OAAO,EAAE,OAAO,CAAC;CACrE,IAAI,aAAa,OAAO,aAAa,UAAU,OAAO,EAAE,OAAO,CAAC;CAEhE,aAAa,WAAW,MAAM;AAChC;AAEA,SAAS,cAAc,OAAkC;CACvD,OAAO,WAAW,OAAO,gBAAgB;AAC3C"}
+{"version":3,"file":"screen.js","names":[],"sources":["../../../../src/media/dom/screen.ts"],"sourcesContent":["/**\n * Screen resolution, as the signal source for a screen-size rendition cap.\n *\n * Reported as a width and a height rather than a `\"720p\"`-style tier, because\n * the cap that consumes it compares against real track dimensions. A tier only\n * describes a track once you assume its aspect ratio, and that assumption\n * mis-measures an anamorphic or otherwise non-16:9 rendition.\n *\n * The signal source for the screen-size cap in\n * `internal/design/spf/features/rendition-selection-caps.md`.\n *\n * The screen underneath a window is not stable: rotating a device swaps the axes,\n * and unplugging a monitor or dragging the window to another display changes the\n * numbers *and* which physical screen they describe. So `getScreenResolution`\n * reads at call time and caches nothing, and `watchScreenResolution` layers the\n * reacting on top rather than the reader holding state of its own.\n */\n\nimport { getDevicePixelRatio, listen, watchDevicePixelRatio } from '@videojs/utils/dom';\nimport { shallowEqual } from '@videojs/utils/object';\nimport { isFunction } from '@videojs/utils/predicate';\nimport { type Resolution, scaleResolution } from '../primitives/resolution';\n\n/** A screen's pixel dimensions. */\nexport type ScreenResolution = Resolution;\n\nexport interface ScreenResolutionOptions {\n  /**\n   * Scale the reading from CSS pixels into device pixels. On by default, since\n   * device pixels are what the screen actually has, and a rendition's dimensions\n   * are in the same units.\n   *\n   * Opt out for CSS pixels. Note that derating — a 3x phone rarely wanting 3x the\n   * pixels of its layout — is a scale applied over this reading rather than a\n   * reason to turn it off.\n   *\n   * ⚠️ Chromium and Gecko fold page zoom into `devicePixelRatio`, so with this on,\n   * zooming moves the reading even though the screen didn't change. WebKit holds\n   * the ratio independent of zoom and is unaffected. Whether a cap should track\n   * zoom is the cap's call; this flag is only what puts zoom in scope.\n   */\n  useDevicePixelRatio: boolean;\n}\n\n/**\n * Read the screen's resolution, or `undefined` where there isn't one to read.\n *\n * `undefined` means \"unknown\", which is the answer a cap needs in order to not\n * cap. `screenResolutionCap` reads it that way and declines to narrow, so an\n * unknown screen is \"no cap\" rather than a cap of zero — the reading a naive\n * `?? 0` would produce, which would pin every source to its smallest rendition on\n * exactly the environments we know least about.\n *\n * Dimensions are reported as-is, including the axis swap a rotated device\n * applies to them. Normalizing orientation away is a policy question — whether a\n * cap should flap on rotation, or hold the larger budget across both — and\n * belongs to the cap rather than to the reading.\n */\nexport function getScreenResolution(\n  { useDevicePixelRatio }: ScreenResolutionOptions = { useDevicePixelRatio: true }\n): ScreenResolution | undefined {\n  const screen = globalThis.screen;\n  if (!screen) return undefined;\n\n  // A missing or nonsense ratio falls back to 1 (see `getDevicePixelRatio`): a\n  // CSS-pixel reading is still true and still cappable, so it isn't worth failing\n  // the whole answer over. Rounding, and the nothing-to-report case a `NaN` or\n  // zero dimension lands in, belong to `scaleResolution`.\n  return scaleResolution(screen, useDevicePixelRatio ? getDevicePixelRatio() : 1);\n}\n\n/**\n * Call `onChange` whenever {@link getScreenResolution} would start answering\n * differently. Returns a function that stops watching.\n *\n * There is no single event for \"the screen changed\", so this subscribes to every\n * signal that implies one and compares readings to decide whether anything\n * actually moved. Comparing is what makes that safe: the signals overlap and\n * `resize` in particular is noisy, so over-subscribing costs a discarded read\n * rather than a spurious call.\n *\n * `onChange` is called once on subscribe with the starting value — including\n * `undefined` where there is no screen — and after that only on a genuine change.\n * So a consumer gets its initial state from the watcher and never has to pair it\n * with a separate {@link getScreenResolution} call.\n *\n * The signals, and what each one is here for:\n *\n * - **`screen`'s own `change`** — the screen itself being reconfigured, or the\n *   window landing on a different one. The direct signal, and the only one that\n *   catches a window moving between two same-size, same-ratio displays. From the\n *   Window Management API, but on the base `Screen` rather than behind\n *   `getScreenDetails()`, so it needs no permission — only a secure context.\n *   Measured present in Chromium and absent in WebKit and Firefox, hence the\n *   three below rather than this alone.\n * - **`resize`** — the window changing size, which is also what the OS does to it\n *   when the display it was on goes away.\n * - **`screen.orientation` change** — rotation, which swaps the axes without\n *   necessarily resizing the window.\n * - **a `(resolution: <ratio>dppx)` media query** (`watchDevicePixelRatio`) — the\n *   device pixel ratio changing under a window that kept its size, which is the\n *   cross-display drag between displays of different density.\n *\n *   Worth keeping despite looking redundant, because it is the only coverage that\n *   case has in WebKit and Firefox: neither implements `screen`'s change event,\n *   and the drag doesn't resize the window. It is also a cleaner signal in Safari\n *   than elsewhere — WebKit holds `devicePixelRatio` independent of page zoom, so\n *   there it moves only on a real density change, where Chromium and Gecko fold\n *   zoom into it as well.\n *\n * ⚠️ Known gap, on engines without `screen`'s change event: dragging a window\n * between two different-size displays that share a ratio, without the window\n * resizing, changes the reading with nothing firing. Closing it there would mean\n * polling, whose interval and battery cost are a policy decision this function\n * shouldn't be making.\n */\nexport function watchScreenResolution(\n  onChange: (resolution: ScreenResolution | undefined) => void,\n  options: ScreenResolutionOptions = { useDevicePixelRatio: true }\n): () => void {\n  // One signal for every listener, so stopping is one call rather than a handle\n  // per subscription. Also makes a late ratio re-arm inert: `addEventListener`\n  // drops a listener whose signal has already aborted.\n  const disconnect = new AbortController();\n  const { signal } = disconnect;\n  let current = getScreenResolution(options);\n\n  const check = () => {\n    const next = getScreenResolution(options);\n    if (shallowEqual(current, next)) return;\n\n    current = next;\n    onChange(next);\n  };\n\n  // Deliver the starting value up front, so a consumer gets its initial state from\n  // the watcher rather than having to pair it with a separate read. Unconditional,\n  // rather than falling out of comparing against an empty `current`: an unknown\n  // reading is a value too, and a consumer that only ever heard from us about a\n  // *known* screen couldn't tell \"there is no screen\" from \"not called yet\".\n  //\n  // Before the listeners rather than after, so a callback that throws takes\n  // nothing with it — there is no subscription yet to strand.\n  onChange(current);\n\n  watchDevicePixelRatio(check, signal);\n\n  // Each signal is optional for the same reason the reading is: an environment\n  // missing one has nothing to report from it, which is not a reason to fail.\n  // `screen`'s own change event is subscribed without feature-detecting — where\n  // it isn't implemented it simply never fires, and a signal that never fires\n  // costs nothing under comparison.\n  const screen = globalThis.screen;\n  const orientation = screen?.orientation;\n\n  if (globalThis.window) listen(globalThis.window, 'resize', check, { signal });\n  // NOTE: Chromium browsers support screen change event.\n  // See: https://developer.mozilla.org/en-US/docs/Web/API/Screen/change_event\n  if (isEventTarget(screen)) listen(screen, 'change', check, { signal });\n  if (orientation) listen(orientation, 'change', check, { signal });\n\n  return () => disconnect.abort();\n}\n\nfunction isEventTarget(value: any): value is EventTarget {\n  return isFunction(value?.addEventListener);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,oBACd,EAAE,wBAAiD,EAAE,qBAAqB,KAAK,GACjD;CAC9B,MAAM,SAAS,WAAW;CAC1B,IAAI,CAAC,QAAQ,OAAO,KAAA;CAMpB,OAAO,gBAAgB,QAAQ,sBAAsB,oBAAoB,IAAI,CAAC;AAChF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,sBACd,UACA,UAAmC,EAAE,qBAAqB,KAAK,GACnD;CAIZ,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,EAAE,WAAW;CACnB,IAAI,UAAU,oBAAoB,OAAO;CAEzC,MAAM,cAAc;EAClB,MAAM,OAAO,oBAAoB,OAAO;EACxC,IAAI,aAAa,SAAS,IAAI,GAAG;EAEjC,UAAU;EACV,SAAS,IAAI;CACf;CAUA,SAAS,OAAO;CAEhB,sBAAsB,OAAO,MAAM;CAOnC,MAAM,SAAS,WAAW;CAC1B,MAAM,cAAc,QAAQ;CAE5B,IAAI,WAAW,QAAQ,OAAO,WAAW,QAAQ,UAAU,OAAO,EAAE,OAAO,CAAC;CAG5E,IAAI,cAAc,MAAM,GAAG,OAAO,QAAQ,UAAU,OAAO,EAAE,OAAO,CAAC;CACrE,IAAI,aAAa,OAAO,aAAa,UAAU,OAAO,EAAE,OAAO,CAAC;CAEhE,aAAa,WAAW,MAAM;AAChC;AAEA,SAAS,cAAc,OAAkC;CACvD,OAAO,WAAW,OAAO,gBAAgB;AAC3C"}

package/dist/dev/media/primitives/resolution.d.ts

@@ -0,0 +1,24 @@
+//#region src/media/primitives/resolution.d.ts
+/**
+ * Pixel dimensions, and the one projection every reader of them needs.
+ *
+ * Shared by the surfaces a rendition cap measures — a screen (`media/dom/screen`),
+ * a player element (`behaviors/dom/track-player-resolution`) — and by the caps
+ * that compare renditions against them. Lives outside the DOM layer because
+ * scaling and rounding two numbers needs no DOM, which is also what lets the
+ * DOM-free selection rules name the type they read instead of restating its shape.
+ */
+/**
+ * A surface's pixel dimensions.
+ *
+ * A width and a height rather than a `"720p"`-style tier, because a tier only
+ * describes a surface once you assume its aspect ratio — the assumption that
+ * mis-measures an anamorphic or otherwise non-16:9 rendition.
+ */
+interface Resolution {
+  readonly width: number;
+  readonly height: number;
+}
+//#endregion
+export { Resolution };
+//# sourceMappingURL=resolution.d.ts.map

package/dist/dev/media/primitives/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","names":[],"sources":["../../../../src/media/primitives/resolution.ts"],"mappings":";;;;;;;;;;;;;;;;;UAiBiB;WACN;WACA"}

package/dist/dev/media/primitives/resolution.js

@@ -0,0 +1,29 @@
+//#region src/media/primitives/resolution.ts
+/**
+* Apply `scale` to a size and normalize it to whole pixels, or `undefined` where
+* that leaves nothing to describe.
+*
+* Rounded because pixels are whole and a fractional scale doesn't divide a
+* surface evenly. A non-positive or non-finite axis yields `undefined` rather
+* than a zero-area reading: an element that isn't being rendered reports `0 × 0`
+* and a nonsense dimension reports `NaN`, and the caps consuming this read
+* absence as "unknown, don't cap" while an area of zero would read as a cap of
+* zero — pinning every source to its smallest rendition.
+*
+* @param size - Dimensions to project, in the units `scale` converts from
+* @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1
+* @returns The scaled, whole-pixel resolution, or `undefined` when either axis
+* doesn't survive it
+*/
+function scaleResolution(size, scale = 1) {
+	const width = Math.round(size.width * scale);
+	const height = Math.round(size.height * scale);
+	return width > 0 && height > 0 ? {
+		width,
+		height
+	} : void 0;
+}
+//#endregion
+export { scaleResolution };
+
+//# sourceMappingURL=resolution.js.map

package/dist/dev/media/primitives/resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.js","names":[],"sources":["../../../../src/media/primitives/resolution.ts"],"sourcesContent":["/**\n * Pixel dimensions, and the one projection every reader of them needs.\n *\n * Shared by the surfaces a rendition cap measures — a screen (`media/dom/screen`),\n * a player element (`behaviors/dom/track-player-resolution`) — and by the caps\n * that compare renditions against them. Lives outside the DOM layer because\n * scaling and rounding two numbers needs no DOM, which is also what lets the\n * DOM-free selection rules name the type they read instead of restating its shape.\n */\n\n/**\n * A surface's pixel dimensions.\n *\n * A width and a height rather than a `\"720p\"`-style tier, because a tier only\n * describes a surface once you assume its aspect ratio — the assumption that\n * mis-measures an anamorphic or otherwise non-16:9 rendition.\n */\nexport interface Resolution {\n  readonly width: number;\n  readonly height: number;\n}\n\n/**\n * Apply `scale` to a size and normalize it to whole pixels, or `undefined` where\n * that leaves nothing to describe.\n *\n * Rounded because pixels are whole and a fractional scale doesn't divide a\n * surface evenly. A non-positive or non-finite axis yields `undefined` rather\n * than a zero-area reading: an element that isn't being rendered reports `0 × 0`\n * and a nonsense dimension reports `NaN`, and the caps consuming this read\n * absence as \"unknown, don't cap\" while an area of zero would read as a cap of\n * zero — pinning every source to its smallest rendition.\n *\n * @param size - Dimensions to project, in the units `scale` converts from\n * @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1\n * @returns The scaled, whole-pixel resolution, or `undefined` when either axis\n * doesn't survive it\n */\nexport function scaleResolution(size: Resolution, scale = 1): Resolution | undefined {\n  const width = Math.round(size.width * scale);\n  const height = Math.round(size.height * scale);\n\n  return width > 0 && height > 0 ? { width, height } : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAsCA,SAAgB,gBAAgB,MAAkB,QAAQ,GAA2B;CACnF,MAAM,QAAQ,KAAK,MAAM,KAAK,QAAQ,KAAK;CAC3C,MAAM,SAAS,KAAK,MAAM,KAAK,SAAS,KAAK;CAE7C,OAAO,QAAQ,KAAK,SAAS,IAAI;EAAE;EAAO;CAAO,IAAI,KAAA;AACvD"}

package/dist/dev/media/primitives/select-tracks.js

@@ -36,6 +36,22 @@ function tracksUnderPixelArea(tracks, maxPixelArea = Number.POSITIVE_INFINITY) {
 	return tracks.filter((track) => pixelArea(track) <= maxPixelArea);
 }
 /**
+* The smallest track area that still covers `minPixelArea`, or `undefined` when
+* no track reaches it.
+*
+* The cap a surface-size rule wants when it should round *up* to the ladder: a
+* surface between two tiers is covered by the upper one, and capping at the
+* surface's own area instead would serve a picture smaller than the surface and
+* upscale it.
+*
+* Tracks declaring no dimensions compare as area `0` and so never cover anything,
+* which keeps them out of the cap rather than pinning it to zero.
+*/
+function smallestCoveringPixelArea(tracks, minPixelArea) {
+	const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);
+	return covering.length ? Math.min(...covering) : void 0;
+}
+/**
 * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak
 * for renditions of identical dimensions. Missing dimensions are treated as area
 * `0`, so a track without them sorts last.
@@ -86,6 +102,6 @@ function pickTextTrackFromTracks(tracks, config) {
 	}
 }
 //#endregion
-export { byDescendingResolution, matchesPartialTrack, pickAudioTrackFromTracks, pickTextTrackFromTracks, tracksUnderPixelArea };
+export { byDescendingResolution, matchesPartialTrack, pickAudioTrackFromTracks, pickTextTrackFromTracks, smallestCoveringPixelArea, tracksUnderPixelArea };
 
 //# sourceMappingURL=select-tracks.js.map

package/dist/dev/media/primitives/select-tracks.js.map

@@ -1 +1 @@
-{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/media/primitives/select-tracks.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../types';\n\n/**\n * State shape for track selection.\n */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/**\n * Configuration for audio track selection.\n */\nexport interface AudioSelectionConfig {\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n}\n\n/**\n * Configuration for text track selection.\n */\nexport interface TextSelectionConfig {\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles\n   * in the same language, the regular track MUST contain both forced and\n   * regular content. Therefore, forced-only tracks are redundant and excluded\n   * by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES\n   * will be automatically selected if no user preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n//\n// Candidate-list policies and track geometry, for the selection rules in\n// `playback/behaviors/select-tracks.ts` and `playback/behaviors/track-switching.ts`\n// to compose. Nothing here consults a whole presentation or returns a single id:\n// narrowing a list and ordering a list are the two shapes a rule can take, and the\n// rule chain takes the head of what they leave.\n// =============================================================================\n\n/**\n * Test whether a track matches a partial-track description: every present,\n * defined field of `filter` equals the track's. Absent or `undefined` filter\n * fields don't constrain. Used to narrow candidates by a user selection\n * (`{ id }`, `{ language }`, `{ height }`, …).\n *\n * @param track - The track to test\n * @param filter - Partial-track description; only present, defined fields constrain\n * @returns `true` when the track matches every constraining field\n */\nexport function matchesPartialTrack<T>(track: T, filter: Partial<T>): boolean {\n  for (const key in filter) {\n    const filterValue = filter[key as keyof T];\n    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n  }\n  return true;\n}\n\ntype RankableTrack = { id: string; width?: number; height?: number; bandwidth?: number };\n\n/** Missing dimensions are treated as area `0`, so a track without them ranks last. */\nfunction pixelArea(track: RankableTrack): number {\n  return (track.width ?? 0) * (track.height ?? 0);\n}\n\n/**\n * Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering,\n * no fallback. Survivors keep their incoming order, and an empty result is a real\n * answer — \"none of these fit\".\n *\n * Deliberately only the filter, because as a selection rule this composes under\n * `applyRules`, which already owns both halves a caller might expect here: an empty\n * result is skipped, so a preference can never narrow the candidate set to nothing;\n * and ordering the survivors is a separate rule's job\n * ({@link byDescendingResolution}, bandwidth ABR). Doing either here would duplicate\n * the composer and give one rule two responsibilities.\n */\nexport function tracksUnderPixelArea<T extends RankableTrack>(\n  tracks: readonly T[],\n  maxPixelArea: number = Number.POSITIVE_INFINITY\n): readonly T[] {\n  return tracks.filter((track) => pixelArea(track) <= maxPixelArea);\n}\n\n/**\n * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak\n * for renditions of identical dimensions. Missing dimensions are treated as area\n * `0`, so a track without them sorts last.\n *\n * A comparator rather than a \"highest track\" function: the selection-rule chain\n * takes the head of the list it produces, so ranking never has to collapse to a\n * single track. `preferHighestResolution` is `sort` over this and nothing more.\n */\nexport function byDescendingResolution(a: RankableTrack, b: RankableTrack): number {\n  return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);\n}\n\n/**\n * Default audio policy over a candidate list: the three-tier pick a selection-rule\n * chain applies once it has narrowed the candidates.\n *\n * Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.\n */\nexport function pickAudioTrackFromTracks(\n  tracks: readonly { id: string; language?: string | undefined; default?: boolean | undefined }[],\n  config?: AudioSelectionConfig\n): string | undefined {\n  // Try preferred language first\n  if (config?.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) {\n      return languageMatch.id;\n    }\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) {\n    return defaultTrack.id;\n  }\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Default text-track policy over a candidate list: the opt-in three-tier pick\n * `switchTextTrack`'s terminal applies once it has narrowed the renditions to the\n * constrained, CDN-scoped set.\n *\n * Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES`\n * (only when `enableDefaultTrack`) → `undefined` (opt-in). FORCED tracks are\n * excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry\n * forced content when both exist, so a forced-only track is redundant).\n */\nexport function pickTextTrackFromTracks(\n  tracks: readonly (PartiallyResolvedTextTrack | TextTrack)[],\n  config?: TextSelectionConfig\n): string | undefined {\n  const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};\n\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;AA0EA,SAAgB,oBAAuB,OAAU,QAA6B;CAC5E,KAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,IAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,aAAa,OAAO;CACjF;CACA,OAAO;AACT;;AAKA,SAAS,UAAU,OAA8B;CAC/C,QAAQ,MAAM,SAAS,MAAM,MAAM,UAAU;AAC/C;;;;;;;;;;;;;AAcA,SAAgB,qBACd,QACA,eAAuB,OAAO,mBAChB;CACd,OAAO,OAAO,QAAQ,UAAU,UAAU,KAAK,KAAK,YAAY;AAClE;;;;;;;;;;AAWA,SAAgB,uBAAuB,GAAkB,GAA0B;CACjF,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa;AAC7E;;;;;;;AAQA,SAAgB,yBACd,QACA,QACoB;CAEpB,IAAI,QAAQ,wBAAwB;EAClC,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,aAAa,OAAO,sBAAsB;EAC7F,IAAI,eACF,OAAO,cAAc;CAEzB;CAGA,MAAM,eAAe,OAAO,MAAM,UAAU,MAAM,YAAY,IAAI;CAClE,IAAI,cACF,OAAO,aAAa;CAItB,OAAO,OAAO,EAAE,EAAE;AACpB;;;;;;;;;;;AAYA,SAAgB,wBACd,QACA,QACoB;CACpB,MAAM,kBAAkB,QAAQ,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,MAAM;CACrG,IAAI,gBAAgB,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU,UAAU,CAAC;CAE7E,IAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,yBAAyB;EAClG,IAAI,eAAe,OAAO,cAAc;CAC1C;CAEA,IAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,IAAI;EAC3E,IAAI,cAAc,OAAO,aAAa;CACxC;AAGF"}
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/media/primitives/select-tracks.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../types';\n\n/**\n * State shape for track selection.\n */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/**\n * Configuration for audio track selection.\n */\nexport interface AudioSelectionConfig {\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n}\n\n/**\n * Configuration for text track selection.\n */\nexport interface TextSelectionConfig {\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles\n   * in the same language, the regular track MUST contain both forced and\n   * regular content. Therefore, forced-only tracks are redundant and excluded\n   * by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES\n   * will be automatically selected if no user preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n//\n// Candidate-list policies and track geometry, for the selection rules in\n// `playback/behaviors/select-tracks.ts` and `playback/behaviors/track-switching.ts`\n// to compose. Nothing here consults a whole presentation or returns a single id:\n// narrowing a list and ordering a list are the two shapes a rule can take, and the\n// rule chain takes the head of what they leave.\n// =============================================================================\n\n/**\n * Test whether a track matches a partial-track description: every present,\n * defined field of `filter` equals the track's. Absent or `undefined` filter\n * fields don't constrain. Used to narrow candidates by a user selection\n * (`{ id }`, `{ language }`, `{ height }`, …).\n *\n * @param track - The track to test\n * @param filter - Partial-track description; only present, defined fields constrain\n * @returns `true` when the track matches every constraining field\n */\nexport function matchesPartialTrack<T>(track: T, filter: Partial<T>): boolean {\n  for (const key in filter) {\n    const filterValue = filter[key as keyof T];\n    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n  }\n  return true;\n}\n\ntype RankableTrack = { id: string; width?: number; height?: number; bandwidth?: number };\n\n/** Missing dimensions are treated as area `0`, so a track without them ranks last. */\nfunction pixelArea(track: RankableTrack): number {\n  return (track.width ?? 0) * (track.height ?? 0);\n}\n\n/**\n * Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering,\n * no fallback. Survivors keep their incoming order, and an empty result is a real\n * answer — \"none of these fit\".\n *\n * Deliberately only the filter, because as a selection rule this composes under\n * `applyRules`, which already owns both halves a caller might expect here: an empty\n * result is skipped, so a preference can never narrow the candidate set to nothing;\n * and ordering the survivors is a separate rule's job\n * ({@link byDescendingResolution}, bandwidth ABR). Doing either here would duplicate\n * the composer and give one rule two responsibilities.\n */\nexport function tracksUnderPixelArea<T extends RankableTrack>(\n  tracks: readonly T[],\n  maxPixelArea: number = Number.POSITIVE_INFINITY\n): readonly T[] {\n  return tracks.filter((track) => pixelArea(track) <= maxPixelArea);\n}\n\n/**\n * The smallest track area that still covers `minPixelArea`, or `undefined` when\n * no track reaches it.\n *\n * The cap a surface-size rule wants when it should round *up* to the ladder: a\n * surface between two tiers is covered by the upper one, and capping at the\n * surface's own area instead would serve a picture smaller than the surface and\n * upscale it.\n *\n * Tracks declaring no dimensions compare as area `0` and so never cover anything,\n * which keeps them out of the cap rather than pinning it to zero.\n */\nexport function smallestCoveringPixelArea(tracks: readonly RankableTrack[], minPixelArea: number): number | undefined {\n  const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);\n\n  return covering.length ? Math.min(...covering) : undefined;\n}\n\n/**\n * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak\n * for renditions of identical dimensions. Missing dimensions are treated as area\n * `0`, so a track without them sorts last.\n *\n * A comparator rather than a \"highest track\" function: the selection-rule chain\n * takes the head of the list it produces, so ranking never has to collapse to a\n * single track. `preferHighestResolution` is `sort` over this and nothing more.\n */\nexport function byDescendingResolution(a: RankableTrack, b: RankableTrack): number {\n  return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);\n}\n\n/**\n * Default audio policy over a candidate list: the three-tier pick a selection-rule\n * chain applies once it has narrowed the candidates.\n *\n * Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.\n */\nexport function pickAudioTrackFromTracks(\n  tracks: readonly { id: string; language?: string | undefined; default?: boolean | undefined }[],\n  config?: AudioSelectionConfig\n): string | undefined {\n  // Try preferred language first\n  if (config?.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) {\n      return languageMatch.id;\n    }\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) {\n    return defaultTrack.id;\n  }\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Default text-track policy over a candidate list: the opt-in three-tier pick\n * `switchTextTrack`'s terminal applies once it has narrowed the renditions to the\n * constrained, CDN-scoped set.\n *\n * Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES`\n * (only when `enableDefaultTrack`) → `undefined` (opt-in). FORCED tracks are\n * excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry\n * forced content when both exist, so a forced-only track is redundant).\n */\nexport function pickTextTrackFromTracks(\n  tracks: readonly (PartiallyResolvedTextTrack | TextTrack)[],\n  config?: TextSelectionConfig\n): string | undefined {\n  const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};\n\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;AA0EA,SAAgB,oBAAuB,OAAU,QAA6B;CAC5E,KAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,IAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,aAAa,OAAO;CACjF;CACA,OAAO;AACT;;AAKA,SAAS,UAAU,OAA8B;CAC/C,QAAQ,MAAM,SAAS,MAAM,MAAM,UAAU;AAC/C;;;;;;;;;;;;;AAcA,SAAgB,qBACd,QACA,eAAuB,OAAO,mBAChB;CACd,OAAO,OAAO,QAAQ,UAAU,UAAU,KAAK,KAAK,YAAY;AAClE;;;;;;;;;;;;;AAcA,SAAgB,0BAA0B,QAAkC,cAA0C;CACpH,MAAM,WAAW,OAAO,IAAI,SAAS,CAAC,CAAC,QAAQ,SAAS,QAAQ,YAAY;CAE5E,OAAO,SAAS,SAAS,KAAK,IAAI,GAAG,QAAQ,IAAI,KAAA;AACnD;;;;;;;;;;AAWA,SAAgB,uBAAuB,GAAkB,GAA0B;CACjF,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa;AAC7E;;;;;;;AAQA,SAAgB,yBACd,QACA,QACoB;CAEpB,IAAI,QAAQ,wBAAwB;EAClC,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,aAAa,OAAO,sBAAsB;EAC7F,IAAI,eACF,OAAO,cAAc;CAEzB;CAGA,MAAM,eAAe,OAAO,MAAM,UAAU,MAAM,YAAY,IAAI;CAClE,IAAI,cACF,OAAO,aAAa;CAItB,OAAO,OAAO,EAAE,EAAE;AACpB;;;;;;;;;;;AAYA,SAAgB,wBACd,QACA,QACoB;CACpB,MAAM,kBAAkB,QAAQ,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,MAAM;CACrG,IAAI,gBAAgB,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU,UAAU,CAAC;CAE7E,IAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,yBAAyB;EAClG,IAAI,eAAe,OAAO,cAAc;CAC1C;CAEA,IAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,IAAI;EAC3E,IAAI,cAAc,OAAO,aAAa;CACxC;AAGF"}

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

@@ -21,9 +21,9 @@ const hlsBackgroundVideoMediaDefaultProps = { src: "" };
 * 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.
+* The verdict is still listed, for the shapes that report nothing else: no video
+* renditions at all, or a ladder pruned before anything resolves — both of which
+* `reportAbsentTrackType` covers from the tail 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.

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

@@ -1 +1 @@
-{"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"}
+{"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 shapes that report nothing else: no video\n * renditions at all, or a ladder pruned before anything resolves — both of which\n * `reportAbsentTrackType` covers from the tail 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/behaviors/collect-errors.js

@@ -59,14 +59,14 @@ function emitError(state, error) {
 * 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."
+* **Belongs last in the chain.** A constraint sees the list as it stands at its
+* own position, so only at the tail does an empty input mean "nothing playable
+* here" — none of this type offered, or the constraints ahead 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.
+* These are the failures no per-rendition cause can report: causes come from
+* `reportUnsupportedTrackConditions` as each media playlist resolves, and a
+* rendition pruned before selection never resolves. Container and encryption
+* aren't knowable until one does; CODECS is, so an undecodable ladder isn't.
 *
 * Idempotent because the constraint chain runs inside a `computed` that re-derives
 * on every `presentation` write — segment appends and live reloads included — and
@@ -75,7 +75,7 @@ function emitError(state, error) {
 *
 * @example
 * // engine-background-video.ts — video-only, so a source with none can't play
-* constraints: [reportAbsentTrackType(SVTA_NO_SUPPORTED_VIDEO_TRACK), excludeUnplayableTracks]
+* constraints: [excludeUnplayableTracks, reportAbsentTrackType(SVTA_NO_SUPPORTED_VIDEO_TRACK)]
 */
 function reportAbsentTrackType(code) {
 	return (tracks, { state }) => {

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, 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"}
+{"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 last in the chain.** A constraint sees the list as it stands at its\n * own position, so only at the tail does an empty input mean \"nothing playable\n * here\" — none of this type offered, or the constraints ahead pruned them all.\n *\n * These are the failures no per-rendition cause can report: causes come from\n * `reportUnsupportedTrackConditions` as each media playlist resolves, and a\n * rendition pruned before selection never resolves. Container and encryption\n * aren't knowable until one does; CODECS is, so an undecodable ladder isn't.\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: [excludeUnplayableTracks, reportAbsentTrackType(SVTA_NO_SUPPORTED_VIDEO_TRACK)]\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-player-resolution.d.ts

@@ -0,0 +1,8 @@
+import "../../../core/signals/primitives.js";
+import { Resolution } from "../../../media/primitives/resolution.js";
+//#region src/playback/behaviors/dom/track-player-resolution.d.ts
+/** A player element's rendered pixel dimensions. */
+type PlayerResolution = Resolution;
+//#endregion
+export { PlayerResolution };
+//# sourceMappingURL=track-player-resolution.d.ts.map

package/dist/dev/playback/behaviors/dom/track-player-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-player-resolution.d.ts","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-player-resolution.ts"],"mappings":";;;;KA6BY,mBAAmB"}

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

@@ -0,0 +1,57 @@
+import { defineBehavior } from "../../../core/composition/create-composition.js";
+import { effect } from "../../../core/signals/effect.js";
+import { scaleResolution } from "../../../media/primitives/resolution.js";
+import { observeElementSize, observeRenderedSize } from "@videojs/utils/dom";
+import { shallowEqual } from "@videojs/utils/object";
+//#region src/playback/behaviors/dom/track-player-resolution.ts
+/**
+* Mirror the player element's rendered pixel dimensions into reactive state, so
+* a rendition cap can narrow candidates to what the element can actually show
+* without reading the DOM at pick time — which would make the picker impure, and
+* would never re-pick when the element resized.
+*
+* The player-element half of the caps in
+* `internal/design/spf/features/rendition-selection-caps.md`, and the tighter
+* half: a small embed on a large display is capped by its own box rather than by
+* the screen behind it (`trackScreenResolution`).
+*
+* Reported as a width and a height in device pixels — the same units, and for the
+* same reason, as `media/dom/screen`'s reading: the cap compares against real
+* track dimensions, and a `"720p"`-style tier only describes a track once you
+* assume its aspect ratio.
+*
+* `undefined` where there is nothing to measure — no element attached, or one
+* that isn't being rendered (detached, `display: none`, not yet laid out) — which
+* is the value the cap reads as "don't cap".
+*/
+function trackPlayerResolutionSetup({ state, context, config = {} }) {
+	const { capRenditionToPlayerSize = true, useDevicePixelRatio = true } = config;
+	return effect(() => {
+		const mediaElement = context.mediaElement.get();
+		let current;
+		state.playerResolution.set(current);
+		if (!capRenditionToPlayerSize || !mediaElement) return;
+		const write = (size) => {
+			const next = scaleResolution(size, size.scale);
+			if (shallowEqual(current, next)) return;
+			current = next;
+			state.playerResolution.set(next);
+		};
+		return useDevicePixelRatio ? observeRenderedSize(mediaElement, write) : observeElementSize(mediaElement, write);
+	});
+}
+/**
+* Track the player element's rendered resolution in `state.playerResolution`.
+*
+* @example
+* const cleanup = trackPlayerResolution.setup({ state, context });
+*/
+const trackPlayerResolution = defineBehavior({
+	stateKeys: ["playerResolution"],
+	contextKeys: ["mediaElement"],
+	setup: trackPlayerResolutionSetup
+});
+//#endregion
+export { trackPlayerResolution };
+
+//# sourceMappingURL=track-player-resolution.js.map