@videojs/spf 10.0.0-beta.24 → 10.0.0-beta.25

package/dist/default/playback/behaviors/track-switching.js

@@ -0,0 +1,341 @@
+import { computed, peek } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
+import { isResolvedPresentation } from "../../media/types/index.js";
+import { getTracksByType } from "../../media/utils/tracks.js";
+import { getCdnId } from "../../media/utils/cdn.js";
+import { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from "../../network/bandwidth-estimator.js";
+import { DEFAULT_QUALITY_CONFIG, resolutionArea } from "../../media/abr/quality-selection.js";
+import { matchesPartialTrack, pickTextTrackFromTracks } from "../../media/primitives/select-tracks.js";
+/**
+* Apply rules to a candidate list in order; the pick is the first survivor.
+* Two responsibilities the rules don't carry: a rule that returns nothing is
+* skipped (fall-through — a preference never empties the set), and once one
+* survivor remains the chain stops (early-bail — later rules, including the
+* bandwidth ranker, never run, so the effect doesn't subscribe to their
+* signals while the choice is fixed).
+*
+* @param rules - Rules to apply, most authoritative first
+* @param tracks - Candidate tracks
+* @param deps - The behavior's `{ state, context, config }`, passed through to each rule
+* @returns The surviving candidates, pick first
+*/
+function applyRules(rules, tracks, deps) {
+	let current = tracks;
+	for (const rule of rules) {
+		const remaining = rule(current, deps);
+		if (remaining.length === 0) continue;
+		current = remaining;
+		if (current.length === 1) break;
+	}
+	return current;
+}
+/**
+* Apply hard constraints to a candidate list — the pre-pass that runs before the
+* rule chain. A constraint shares a rule's signature but its exclusion is
+* *hard*: it removes the unplayable (a codec the environment can't decode, a CDN
+* in failover cooldown) and a removed track is never attempted. Unlike
+* `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.
+*
+* @param constraints - Constraints to apply (pooled, order-independent)
+* @param tracks - Candidate tracks
+* @param deps - The behavior's `{ state, context, config }`, passed to each constraint
+* @returns The playable survivors (possibly empty)
+*/
+function applyConstraints(constraints, tracks, deps) {
+	let current = tracks;
+	for (const constraint of constraints) current = constraint(current, deps);
+	return current;
+}
+/**
+* User intent — a soft filter. Narrows to tracks matching the partial-track
+* selection in `user*TrackSelection`; an empty match falls through (the
+* composer skips it) to the unfiltered set — e.g. a stale id from a previous
+* source.
+*/
+function filterByUserSelection(tracks, { state, config }) {
+	const key = config.userSelectionKey;
+	if (!key) return tracks;
+	const filter = state[key]?.get();
+	return filter ? tracks.filter((track) => matchesPartialTrack(track, filter)) : tracks;
+}
+/**
+* Failed-CDN constraint — a *hard* filter (constraints pre-pass), shared by
+* video and audio. Removes tracks served from a CDN currently in failover
+* cooldown (`failedCdns`, written by the failover monitor). Removed tracks are never
+* attempted; the scope then narrows to the next surviving CDN in `cdnPriority`,
+* and snaps back to the primary once it leaves cooldown.
+*
+* Passes everything through when there's no `failedCdns` signal/value. When it
+* prunes *every* track (all CDNs cooled down), the empty result is preserved
+* (per `applyConstraints`) — "nothing playable," which clears the selection (no
+* pick); a later CDN recovery refills the candidate set and re-picks.
+*/
+function excludeFailedCdns(tracks, { state, config }) {
+	const failed = state.failedCdns?.get();
+	if (!failed?.length) return tracks;
+	const getCdnId$1 = config.getCdnId ?? getCdnId;
+	const failedSet = new Set(failed);
+	return tracks.filter((track) => !failedSet.has(getCdnId$1(track.url)));
+}
+/**
+* Capability constraint — a *hard* filter (constraints pre-pass), shared by
+* video and audio. Removes renditions this environment can't decode, probed via
+* the injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`). Moving
+* the check here — before selection — means an unplayable variant (e.g. HEVC on
+* a browser without HEVC) is pruned upstream and never picked, instead of
+* surviving into the pipeline to fail late at `createSourceBuffer`. That late
+* throw stays as a defensive structural guarantee; with this constraint it
+* should rarely fire.
+*
+* Passes everything through when there's no `canPlayTrack` probe (a composition
+* that didn't wire it, or DOM-free tests). When it prunes *every* track (no
+* decodable rendition), the empty result is preserved (per `applyConstraints`)
+* — "nothing playable," so the behavior clears the selection (no pick) and the
+* late `createSourceBuffer` check stays as the backstop.
+*/
+function excludeUnplayableTracks(tracks, { config }) {
+	const canPlay = config.canPlayTrack;
+	if (!canPlay) return tracks;
+	return tracks.filter((track) => canPlay(track));
+}
+/**
+* Active-CDN scope — a soft filter, shared by video and audio. Narrows to the
+* highest-priority CDN in `cdnPriority` (owned by `deriveCdnPriority`) that
+* still has tracks, so every track type stays on one CDN. A redundant-streams
+* source lists the same renditions on multiple hosts; this keeps the pick on one
+* host rather than letting the ranker drift across them.
+*
+* "Active" is derived, not stored: constraints run before the rule chain, so a
+* failed CDN's tracks are already pruned by the time this runs — "first CDN with
+* survivors" *is* the active CDN, and it falls through to the next on failover
+* (and snaps back to the primary when it recovers). Content steering reorders
+* `cdnPriority`; this rule just honors the order.
+*
+* Soft-filter semantics: passes through when there's no `cdnPriority` signal/value
+* (no preference) or when nothing matches (`applyRules` skips an empty result).
+* Non-redundant sources have one CDN, so the narrow is a no-op.
+*
+* The CDN-id derivation defaults to origin-based `getCdnId`, overridable via the
+* `getCdnId` config — it must match the one `deriveCdnPriority` used to build
+* `cdnPriority`, or no track's CDN would ever equal an entry.
+*/
+function preferActiveCdn(tracks, { state, config }) {
+	const cdnPriority = state.cdnPriority?.get();
+	if (!cdnPriority?.length) return tracks;
+	const getCdnId$2 = config.getCdnId ?? getCdnId;
+	for (const cdn of cdnPriority) {
+		const tracksUsingCdn = tracks.filter((track) => getCdnId$2(track.url) === cdn);
+		if (tracksUsingCdn.length) return tracksUsingCdn;
+	}
+	return tracks;
+}
+/**
+* Bandwidth ranking — the terminal sort, shared by video and audio. Orders by
+* the throughput estimate: tracks within the bandwidth threshold first
+* (fitting), highest bitrate first; then over-threshold tracks, least-over
+* first. The head is the best-quality track that fits, falling back to the
+* smallest over-throughput track when nothing fits.
+*
+* Hysteresis without temporal state: the current track's effective bitrate is
+* boosted by `upgradeMargin` in the fitting sort, so a higher track only
+* outranks it once it clears `current.bitrate * upgradeMargin` (no flapping on
+* marginal bandwidth gains). Downgrades fall out for free — a current track
+* over the threshold isn't in the fitting set to be boosted, so the best fit (a
+* downgrade) wins immediately. Equal-bitrate tracks break by resolution (higher
+* `width × height` first), so an equal-bitrate ladder never picks a lower-
+* quality rendition by manifest order; audio tracks carry no dimensions, so
+* they area-compare equal and a stable sort keeps their candidate order (e.g.
+* same-bitrate language variants). Early-bail skips this rule when a prior one
+* narrowed to a single track, so the estimate is neither read nor subscribed
+* while that holds.
+*/
+function rankByBandwidth(tracks, { state, config }) {
+	const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;
+	const upgradeMargin = config.quality?.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;
+	const initialBandwidth = config.initialBandwidth ?? 5e6;
+	const bandwidthConfig = {
+		...DEFAULT_BANDWIDTH_CONFIG,
+		...config.bandwidth
+	};
+	if (!state.bandwidthState) console.debug("[track-switching] rankByBandwidth: no bandwidthState signal in composition; ranking on initialBandwidth");
+	const threshold = getBandwidthEstimate(state.bandwidthState?.get(), initialBandwidth, bandwidthConfig) * safetyMargin;
+	const currentId = state[config.selectionKey].get();
+	const bitrate = (track) => track.bandwidth ?? 0;
+	const rank = (track) => track.id === currentId ? bitrate(track) * upgradeMargin : bitrate(track);
+	const fitting = tracks.filter((track) => bitrate(track) <= threshold).sort((a, b) => rank(b) - rank(a) || resolutionArea(b) - resolutionArea(a));
+	const over = tracks.filter((track) => bitrate(track) > threshold).sort((a, b) => bitrate(a) - bitrate(b) || resolutionArea(b) - resolutionArea(a));
+	return [...fitting, ...over];
+}
+/**
+* Default final pick: the chain head. `applyRules` never narrows to nothing and
+* early-bails to a single survivor, so video and audio always converge to a
+* track and the head is the pick.
+*/
+function selectChainHead(candidates) {
+	return candidates[0].id;
+}
+/**
+* Terminal pick for text — the `resolveSelection` the text variant supplies.
+* Resolves the standing `userTextTrackSelection` intent against the chain's
+* survivors (already CDN-failover-pruned and active-CDN-scoped):
+*
+*   - `'off'` → no selection (clear the slot). Sticky through re-evaluation, so a
+*     live refresh or failover re-run can't re-assert a default.
+*   - explicit `Partial<TextTrack>` → narrow to the match (language-based). A
+*     stale pick whose match is gone (e.g. the language dropped on a source
+*     change) falls through to the default policy.
+*   - auto (`undefined`) → the opt-in default policy (`preferredSubtitleLanguage`
+*     → `DEFAULT=YES + AUTOSELECT=YES` → none), shared with `pickTextTrack`.
+*
+* Returning `undefined` is a real outcome (captions are opt-in), which is why the
+* text variant relies on `setupTrackSwitching`'s no-selection seam.
+*/
+function pickResolvedTextTrack(candidates, { state, config }) {
+	const intent = state.userTextTrackSelection?.get();
+	if (intent === "off") return void 0;
+	if (intent) {
+		const matched = candidates.filter((track) => matchesPartialTrack(track, intent));
+		if (matched.length) return matched[0].id;
+	}
+	return pickTextTrackFromTracks(candidates, config);
+}
+function setupTrackSwitching(deps) {
+	const { state, config } = deps;
+	const { selectionKey, getTracks, rules, resolveSelection = selectChainHead } = config;
+	const derivedStateSignal = computed(() => isResolvedPresentation(state.presentation.get()) ? "presentation-resolved" : "presentation-unresolved");
+	const candidateSet = computed(() => {
+		const presentation = state.presentation.get();
+		if (!isResolvedPresentation(presentation)) return [];
+		return applyConstraints(config.constraints ?? [], getTracks(presentation), deps);
+	}, { equals: (a, b) => a.length === b.length && a.every((track) => b.some((other) => other.id === track.id)) });
+	return createMachineReactor({
+		initial: "presentation-unresolved",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"presentation-unresolved": {},
+			"presentation-resolved": {
+				entry: () => () => state[selectionKey].set(void 0),
+				effects: [() => {
+					const tracks = candidateSet.get();
+					if (!tracks.length) {
+						const presentation = peek(state.presentation);
+						if (isResolvedPresentation(presentation) && getTracks(presentation).length > 0) {
+							console.error(`[track-switching] every ${selectionKey} candidate was filtered out by constraints; clearing selection`);
+							state[selectionKey].set(void 0);
+						}
+						return;
+					}
+					const candidates = applyRules(rules, tracks, deps);
+					if (!candidates.length) {
+						console.error("[track-switching] applyRules returned no candidates");
+						return;
+					}
+					state[selectionKey].set(resolveSelection(candidates, deps));
+				}]
+			}
+		}
+	});
+}
+/**
+* Manage `selectedVideoTrackId`: pick a default on src load, dynamically
+* adjust based on bandwidth, clear on src unload. Honors
+* `userVideoTrackSelection` as a partial-track constraint on candidates;
+* short-circuits ABR when the constraint narrows to a single track.
+*
+* @example
+* const reactor = switchVideoTrack.setup({ state });
+*/
+const switchVideoTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedVideoTrackId"],
+	contextKeys: [],
+	setup: ({ state, config, ...otherProps }) => setupTrackSwitching({
+		...otherProps,
+		state,
+		config: {
+			...config,
+			selectionKey: "selectedVideoTrackId",
+			userSelectionKey: "userVideoTrackSelection",
+			getTracks: (presentation) => getTracksByType(presentation, "video"),
+			constraints: [excludeFailedCdns, excludeUnplayableTracks],
+			rules: [
+				filterByUserSelection,
+				preferActiveCdn,
+				rankByBandwidth
+			]
+		}
+	})
+});
+/**
+* Manage `selectedAudioTrackId`: pick a default on src load, narrow by
+* `userAudioTrackSelection` filter, re-pick on filter change, clear on
+* src unload.
+*
+* Mid-stream flush on language switch is handled by the segment-loader's
+* `planTasks` (see `playback/actors/dom/segment-loader.ts`) — not this
+* behavior. Same split as the video pipeline: slot owner writes; loader
+* orchestrates segment + flush plans.
+*
+* @example
+* const reactor = switchAudioTrack.setup({ state });
+*/
+const switchAudioTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedAudioTrackId"],
+	contextKeys: [],
+	setup: ({ state, config, ...otherProps }) => setupTrackSwitching({
+		...otherProps,
+		state,
+		config: {
+			...config,
+			selectionKey: "selectedAudioTrackId",
+			userSelectionKey: "userAudioTrackSelection",
+			getTracks: (presentation) => getTracksByType(presentation, "audio"),
+			constraints: [excludeFailedCdns, excludeUnplayableTracks],
+			rules: [
+				filterByUserSelection,
+				preferActiveCdn,
+				rankByBandwidth
+			]
+		}
+	})
+});
+/**
+* Manage `selectedTextTrackId` as the single-writer **output** of standing user
+* intent (`userTextTrackSelection`) resolved against the playable, CDN-scoped
+* text renditions: clear on src unload; re-resolve when a CDN fails or recovers.
+*
+* Unlike video/audio, the selection is *optional* — captions are opt-in and the
+* user can turn them off — so the chain skips the bandwidth ranker and the shared
+* user-selection filter, and supplies a text-specific terminal
+* (`pickResolvedTextTrack`) that may resolve to no-selection via
+* `setupTrackSwitching`'s `resolveSelection` seam. Constraints are failed-CDN only
+* (`excludeUnplayableTracks`/`canPlayTrack` is MSE-based — the wrong probe for
+* text, whose playability is SPF-parser support); the active-CDN scope co-locates
+* captions with the surviving CDN on failover.
+*
+* @example
+* const reactor = switchTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });
+*/
+const switchTextTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedTextTrackId"],
+	contextKeys: [],
+	setup: ({ state, config, ...otherProps }) => setupTrackSwitching({
+		...otherProps,
+		state,
+		config: {
+			...config,
+			selectionKey: "selectedTextTrackId",
+			getTracks: (presentation) => getTracksByType(presentation, "text"),
+			constraints: [excludeFailedCdns],
+			rules: [preferActiveCdn],
+			resolveSelection: pickResolvedTextTrack
+		}
+	})
+});
+//#endregion
+export { switchAudioTrack, switchTextTrack, switchVideoTrack };
+
+//# sourceMappingURL=track-switching.js.map

package/dist/default/playback/behaviors/track-switching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-switching.js","names":["getCdnId","defaultGetCdnId"],"sources":["../../../../src/playback/behaviors/track-switching.ts"],"sourcesContent":["/**\n * **Per-type track selection as a rule chain.** While a presentation is\n * resolved, owns that type's `selected{Video,Audio,Text}TrackId` signal: pick a\n * default, react to user intent and algorithmic ranking, and clear it on src\n * unload.\n *\n * Selection runs in two stages. First a **hard-constraints pre-pass**\n * (`applyConstraints`) prunes the unplayable from the candidate set — the\n * failed-CDN constraint (`excludeFailedCdns`, failover cooldown) and the\n * capability constraint (`excludeUnplayableTracks`, codec support). Then a small\n * ordered chain of rules (`applyRules`) picks among the survivors. Each constraint/rule reads the signals it needs at apply\n * time, so the effect subscribes to exactly what was consulted. The chain is\n * three rules, most authoritative first:\n *\n *   1. **user intent** — a soft filter on `user*TrackSelection`: narrow to the\n *      partial-track match; an empty match falls through to the full set.\n *   2. **active CDN** — a soft filter on `cdnPriority` (`preferActiveCdn`):\n *      narrow to the highest-priority CDN that still has tracks; an empty match\n *      falls through. Shared by video and audio, so every type stays on one CDN\n *      (`deriveCdnPriority` owns the list). No-op for non-redundant sources.\n *   3. **ranking** — the terminal sort: `rankByBandwidth`, shared by video and\n *      audio. Fitting tracks (within the throughput threshold) first, highest\n *      bitrate first; over-throughput tracks after, least-over first. Hysteresis\n *      via boosting the current track's sort weight by `upgradeMargin`.\n *\n * The composer's early-bail (one survivor → stop) is load-bearing: a user\n * selection that narrows to a single track is the pick without the ranker\n * running, so the bandwidth estimate is never read and the effect doesn't\n * re-fire on bandwidth while that choice holds.\n *\n * Lifecycle: `'presentation-unresolved'` ↔ `'presentation-resolved'`. The\n * resolved state owns the signal; its entry-returned cleanup clears it on exit\n * (canonical cleanup-binds-to-setup per `reactors.md`).\n *\n * The pick is the chain's result mapped to a slot value by `resolveSelection`\n * (default: the head, `applyRules(...)[0]`). Each variant supplies its\n * **constraints + rule chain (+ optional resolveSelection)** via config;\n * `setupTrackSwitching` owns only the lifecycle and runs what it's given. Video\n * and audio run constraints `[excludeFailedCdns, excludeUnplayableTracks]` then\n * rules `[filterByUserSelection, preferActiveCdn, rankByBandwidth]` and take the\n * head; `switchVideoTrack` also accepts ABR tuning config, `switchAudioTrack`\n * takes none. `switchTextTrack` differs — selection is *optional* (captions are\n * opt-in / off-able), so it runs `[excludeFailedCdns]` + `[preferActiveCdn]` and\n * supplies a text terminal (`pickResolvedTextTrack`) that resolves standing user\n * intent (`userTextTrackSelection`, incl. `'off'`) and may yield no selection.\n * (The active-CDN *scope* is the sticky-pick half of multi-CDN; the failed-CDN\n * *constraint* is the failover half — prune the cooled-down CDN, the scope falls\n * to the next.)\n *\n * When the pre-pass prunes a type's candidates to empty, the behavior leaves any\n * prior pick in place and makes no new pick; the late `createSourceBuffer` check\n * stays as the structural backstop for an unplayable rendition reaching the\n * pipeline. Surfacing \"nothing playable\" as observable state is deferred until a\n * consumer (error mapping) needs it.\n *\n * Deferred: audio's preferred-language / default-track selection as standing\n * soft-filter rules (previously the empty-slot picker, dropped in the move to\n * the rule chain).\n */\n\nimport { type AnySlotMap, defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, peek, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport { DEFAULT_QUALITY_CONFIG, type QualityConfig, resolutionArea } from '../../media/abr/quality-selection';\nimport {\n  matchesPartialTrack,\n  pickTextTrackFromTracks,\n  type TextSelectionConfig,\n} from '../../media/primitives/select-tracks';\nimport {\n  type AudioTrack,\n  type CanPlayTrack,\n  isResolvedPresentation,\n  type MaybeResolvedPresentation,\n  type PartiallyResolvedAudioTrack,\n  type PartiallyResolvedTextTrack,\n  type PartiallyResolvedVideoTrack,\n  type TextTrack,\n  type VideoTrack,\n} from '../../media/types';\nimport { getCdnId as defaultGetCdnId, type GetCdnId } from '../../media/utils/cdn';\nimport { getTracksByType } from '../../media/utils/tracks';\nimport type { BandwidthConfig, BandwidthState } from '../../network/bandwidth-estimator';\nimport { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from '../../network/bandwidth-estimator';\n\n// ============================================================================\n// State + Config\n// ============================================================================\n\n/**\n * The slots `setupTrackSwitching` itself owns: the `presentation` gate it reads\n * and the per-type `selected*TrackId` it writes. Rule-only inputs are\n * deliberately absent — `user*TrackSelection` and `bandwidthState` belong to\n * whoever materializes them (the embedder via `shareSignals`, the buffer-actor\n * sampler), and each rule declares the signal it consults as an optional slot\n * on its own deps map, so the behavior never assumes a rule's signal exists.\n */\nexport interface TrackSwitchingState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/**\n * Config for `switchVideoTrack` — the ABR tuning read by its ranker rule\n * (`rankByBandwidth`). `quality.safetyMargin` is the bandwidth-headroom\n * multiplier; `quality.upgradeMargin` the hysteresis ratio gating upgrades;\n * `bandwidth` tunes the estimator; `initialBandwidth` is the pre-sample\n * fallback. Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15),\n * `DEFAULT_BANDWIDTH_CONFIG`, `DEFAULT_INITIAL_BANDWIDTH` (5 Mbps).\n */\nexport interface SwitchVideoTrackConfig {\n  quality?: Partial<QualityConfig>;\n  bandwidth?: Partial<BandwidthConfig>;\n  initialBandwidth?: number;\n  /** Override CDN-id derivation (shared by the CDN scope + failover constraint). */\n  getCdnId?: GetCdnId;\n  /**\n   * Codec capability probe read by the `excludeUnplayableTracks` hard\n   * constraint — drops renditions this environment can't decode before\n   * selection runs. Injected (rather than imported) so the DOM-free behavior\n   * never reaches a DOM API directly; the engine defaults it to the\n   * `MediaSource.isTypeSupported`-backed `canPlayTrack`. Absent → no codec\n   * filtering (the constraint passes everything through).\n   */\n  canPlayTrack?: CanPlayTrack;\n}\n\n/** Default initial-bandwidth value before bandwidth measurements arrive. */\nexport const DEFAULT_INITIAL_BANDWIDTH = 5_000_000;\n\n// ============================================================================\n// Rule chain\n// ============================================================================\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// Specialization helper\n//\n// `setupTrackSwitching` has the same shape as a Behavior `setup` function:\n// `({ state, config }) => Reactor`. Each `switchXTrack` export below calls\n// it from inside its own `defineBehavior` setup. Its generics — `S` (selection\n// slot key), `T` (candidate track type), `C` (the concrete config the variant\n// builds) — all infer from the passed `state` + `config`, so the variants need\n// no explicit type arguments. `C extends TrackSwitchingConfig<S, T>` lets the\n// variant's richer config (rule-specific fields included) flow through the\n// helper untouched; the rules read those fields off their own config views.\n//\n// -- Design note: why narrow `SelectionKey` / `UserSelectionKey` unions ----\n// Goal we did not reach: have callers \"fully pass in\" the slot keys, with\n// the helper enforcing zero internal knowledge of which literals are valid.\n// What blocks it: indexing a mapped-type intersection by a generic key.\n// When `S extends keyof TrackSwitchingState` (or `string`), TS conservatively\n// treats `state[selectionKey]` as the union of every possible match across\n// the intersected mapped portions — including the fixed-key signal\n// (`presentation`) — and widens to their value-type union.\n// The sibling pattern hits the same constraint and answers it the same way:\n// `SelectedTrackKey` in `select-tracks.ts` is a hardcoded narrow union for\n// the same reason.\n//\n// Current pick is the narrow-union route because it matches siblings and\n// the unions read as documentation (\"these are the slots this helper\n// manages\") rather than restriction. Extending to a new track-switching\n// axis is one literal per union.\n// --------------------------------------------------------------------------\n// ============================================================================\n\n/**\n * Minimum candidate-track shape consumed by the helper and its rules: an `id`\n * (the pick), a `url` (the active-CDN scope derives the CDN from it), an\n * optional `bandwidth` (the ranker's throughput sort), and optional\n * `width`/`height` (the ranker's equal-bitrate tie-break — absent on audio, so\n * audio candidates area-compare equal). Every resolved/partially-resolved video\n * track carries them all; audio tracks omit the dimensions.\n */\ntype SwitchableTrack = {\n  id: string;\n  url: string;\n  bandwidth?: number;\n  width?: number;\n  height?: number;\n  // Read by the capability constraint to probe codec support. Optional on the\n  // minimal shape; every resolved/partially-resolved video & audio candidate\n  // carries them, and an absent `mimeType` makes a track unprobeable (kept).\n  mimeType?: string;\n  codecs?: string[];\n};\n\n/**\n * Map the rule chain's surviving candidates to the final selection id, or\n * `undefined` for a deliberate no-selection. Defaults to the chain head\n * (`selectChainHead`) — the always-pick contract video and audio rely on\n * (`applyRules` guarantees a non-empty result, so the head is always there). A\n * variant whose selection is legitimately optional (text: opt-in captions,\n * explicit off) supplies its own picker that may return `undefined`; the helper\n * writes that straight through to the slot, clearing it.\n */\nexport type ResolveSelection<T extends SwitchableTrack, State = unknown, Context = unknown, Config = unknown> = (\n  candidates: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n) => string | undefined;\n\ntype SelectionKey = 'selectedVideoTrackId' | 'selectedAudioTrackId' | 'selectedTextTrackId';\ntype UserSelectionKey = 'userVideoTrackSelection' | 'userAudioTrackSelection';\n\n// Each mapped value references `P` so TS keeps the per-key dependency and\n// resolves `state[selectionKey]` to the right arm. `T` (track type) stays out\n// of the state map (it flows through `TrackSwitchingConfig` instead).\n//\n// Only the behavior's own lifecycle signals are required here: the presentation\n// gate and the selection slot it writes. Signals a *rule* reads but the\n// behavior doesn't — `user*TrackSelection` (the user-selection filter) and\n// `bandwidthState` (the bandwidth ranker) — are NOT here; each rule declares\n// the signal it needs as *optional* on its own deps and reads it defensively,\n// so the behavior never assumes a rule-only signal exists. Those slots are\n// materialized by whoever owns them: `shareSignals` for the consumer-input\n// `user*TrackSelection`, the buffer-actor sampler for `bandwidthState`.\nexport type TrackSwitchingStateMap<S extends SelectionKey> = {\n  presentation: ReadonlySignal<TrackSwitchingState['presentation']>;\n} & { [P in S]: Signal<TrackSwitchingState[P]> };\n\n/**\n * Config `setupTrackSwitching` itself reads — its own wiring: which selection\n * slot to write and clear (`selectionKey`), how to enumerate candidate tracks\n * (`getTracks`), the optional **hard-constraints pre-pass** (`constraints`,\n * applied before the chain to prune the unplayable), and the **rule chain** to\n * run (`rules`), and how to map the chain's survivors to the final pick\n * (`resolveSelection`, defaulting to the chain head). Rule-/constraint-specific\n * config is deliberately absent — each declares the fields it reads as *optional*\n * on its own config view (`UserSelectionConfig`, `BandwidthRankerConfig`), so the\n * behavior never enumerates them. The variant builds the concrete config as this\n * base plus whatever its chain consults; it flows through untouched as the `C`\n * type param on `setupTrackSwitching`.\n */\ninterface TrackSwitchingConfig<S extends SelectionKey, T extends SwitchableTrack> {\n  selectionKey: S;\n  getTracks: (presentation: MaybeResolvedPresentation) => readonly T[];\n  constraints?: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];\n  rules: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];\n  /**\n   * Map the chain's surviving candidates to the final selection id. Optional —\n   * absent means the chain head (`selectChainHead`), the always-pick path video\n   * and audio use. A variant with optional selection (text) supplies one that\n   * may return `undefined`.\n   */\n  resolveSelection?: ResolveSelection<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>;\n}\n\n/**\n * State the user-selection filter reads: the lifecycle map plus an *optional*\n * user-selection slot (keyed by `U`), holding a partial-track description to\n * match against the candidates (`Partial<T>` — `{ id }`, `{ language }`,\n * `{ height }`, …). The slot exists only when the composition provides it\n * (materialized by `shareSignals`); the filter reads it defensively and no-ops\n * when it's absent (no user override).\n */\ntype UserSelectionStateMap<\n  S extends SelectionKey,\n  U extends UserSelectionKey,\n  T extends SwitchableTrack,\n> = TrackSwitchingStateMap<S> & {\n  [P in U]?: ReadonlySignal<Partial<T> | undefined>;\n};\n\n/**\n * Config the user-selection filter reads: `userSelectionKey` names the state\n * slot holding the user's selection. *Optional* on the rule's view — the base\n * config doesn't carry it, so an unwired key means \"no user selection\" and the\n * filter passes through. The variants always supply it.\n */\ntype UserSelectionConfig<\n  S extends SelectionKey,\n  U extends UserSelectionKey,\n  T extends SwitchableTrack,\n> = TrackSwitchingConfig<S, T> & { userSelectionKey?: U };\n\n/**\n * State the bandwidth ranker reads: the lifecycle map plus an *optional*\n * `bandwidthState`. The signal exists only when the composition includes a\n * bandwidth sampler; the ranker reads it defensively and falls back to\n * `initialBandwidth` (with a debug note) when it's absent.\n */\ntype BandwidthRankerStateMap<S extends SelectionKey> = TrackSwitchingStateMap<S> & {\n  bandwidthState?: ReadonlySignal<BandwidthState | undefined>;\n};\n\n/**\n * Config the bandwidth ranker reads: the ABR tuning in `SwitchVideoTrackConfig`\n * (`quality` / `bandwidth` / `initialBandwidth`), all optional with defaults.\n */\ntype BandwidthRankerConfig<S extends SelectionKey, T extends SwitchableTrack> = TrackSwitchingConfig<S, T> &\n  SwitchVideoTrackConfig;\n\n/**\n * State the active-CDN scope reads: the lifecycle map plus an *optional*\n * `cdnPriority` — the manifest-ordered CDN list (most-preferred first). The\n * signal exists only when the composition includes `deriveCdnPriority` (which\n * materializes + owns it); the scope reads it defensively and passes through\n * when it's absent (no CDN preference).\n */\ntype CdnScopeStateMap<S extends SelectionKey> = TrackSwitchingStateMap<S> & {\n  cdnPriority?: ReadonlySignal<string[] | undefined>;\n};\n\n/**\n * State the failed-CDN constraint reads: the lifecycle map plus an *optional*\n * `failedCdns` — the CDN ids currently in failover cooldown. The signal exists\n * only when the composition includes a failover monitor (or an external driver); the\n * constraint reads it defensively and excludes nothing when it's absent.\n */\ntype CdnConstraintStateMap<S extends SelectionKey> = TrackSwitchingStateMap<S> & {\n  failedCdns?: ReadonlySignal<string[] | undefined>;\n};\n\n/**\n * Config the CDN rules read: the base config plus an *optional* `getCdnId`\n * override. Both `excludeFailedCdns` and `preferActiveCdn` derive a track's CDN\n * from its URL; the override must be the *same* one `deriveCdnPriority` and the\n * failover trip use, or the keys stop matching. Optional → defaults to the\n * origin-based `getCdnId`, so the base config (without it) stays assignable.\n */\ntype CdnRuleConfig<S extends SelectionKey, T extends SwitchableTrack> = TrackSwitchingConfig<S, T> & {\n  getCdnId?: GetCdnId;\n};\n\n/**\n * Config the capability constraint reads: the base config plus an *optional*\n * `canPlayTrack` codec probe. Optional → an unwired probe means \"no codec\n * filtering\" and the constraint passes everything through, so the base config\n * (without it) stays assignable. The engine defaults it to the DOM-bound\n * `canPlayTrack`.\n */\ntype CapabilityConstraintConfig<S extends SelectionKey, T extends SwitchableTrack> = TrackSwitchingConfig<S, T> & {\n  canPlayTrack?: CanPlayTrack;\n};\n\ntype VideoTrackCandidate = PartiallyResolvedVideoTrack | VideoTrack;\ntype AudioTrackCandidate = PartiallyResolvedAudioTrack | AudioTrack;\ntype TextTrackCandidate = PartiallyResolvedTextTrack | TextTrack;\n\n// ----------------------------------------------------------------------------\n// Rules — defined outside the behavior closure, parameterized only by their\n// deps. Each is generic over the slot keys + track type; the variant's\n// concrete keys instantiate it where the chain is assembled.\n// ----------------------------------------------------------------------------\n\n/**\n * User intent — a soft filter. Narrows to tracks matching the partial-track\n * selection in `user*TrackSelection`; an empty match falls through (the\n * composer skips it) to the unfiltered set — e.g. a stale id from a previous\n * source.\n */\nfunction filterByUserSelection<S extends SelectionKey, U extends UserSelectionKey, T extends SwitchableTrack>(\n  tracks: readonly T[],\n  { state, config }: SelectionRuleDeps<UserSelectionStateMap<S, U, T>, AnySlotMap, UserSelectionConfig<S, U, T>>\n): readonly T[] {\n  const key = config.userSelectionKey;\n  if (!key) return tracks;\n  const filter = state[key]?.get();\n  return filter ? tracks.filter((track) => matchesPartialTrack(track, filter)) : tracks;\n}\n\n/**\n * Failed-CDN constraint — a *hard* filter (constraints pre-pass), shared by\n * video and audio. Removes tracks served from a CDN currently in failover\n * cooldown (`failedCdns`, written by the failover monitor). Removed tracks are never\n * attempted; the scope then narrows to the next surviving CDN in `cdnPriority`,\n * and snaps back to the primary once it leaves cooldown.\n *\n * Passes everything through when there's no `failedCdns` signal/value. When it\n * prunes *every* track (all CDNs cooled down), the empty result is preserved\n * (per `applyConstraints`) — \"nothing playable,\" which clears the selection (no\n * pick); a later CDN recovery refills the candidate set and re-picks.\n */\nfunction excludeFailedCdns<S extends SelectionKey, T extends SwitchableTrack>(\n  tracks: readonly T[],\n  { state, config }: SelectionRuleDeps<CdnConstraintStateMap<S>, AnySlotMap, CdnRuleConfig<S, T>>\n): readonly T[] {\n  const failed = state.failedCdns?.get();\n  if (!failed?.length) return tracks;\n  const getCdnId = config.getCdnId ?? defaultGetCdnId;\n  const failedSet = new Set(failed);\n  return tracks.filter((track) => !failedSet.has(getCdnId(track.url)));\n}\n\n/**\n * Capability constraint — a *hard* filter (constraints pre-pass), shared by\n * video and audio. Removes renditions this environment can't decode, probed via\n * the injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`). Moving\n * the check here — before selection — means an unplayable variant (e.g. HEVC on\n * a browser without HEVC) is pruned upstream and never picked, instead of\n * surviving into the pipeline to fail late at `createSourceBuffer`. That late\n * throw stays as a defensive structural guarantee; with this constraint it\n * should rarely fire.\n *\n * Passes everything through when there's no `canPlayTrack` probe (a composition\n * that didn't wire it, or DOM-free tests). When it prunes *every* track (no\n * decodable rendition), the empty result is preserved (per `applyConstraints`)\n * — \"nothing playable,\" so the behavior clears the selection (no pick) and the\n * late `createSourceBuffer` check stays as the backstop.\n */\nfunction excludeUnplayableTracks<S extends SelectionKey, T extends SwitchableTrack>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<TrackSwitchingStateMap<S>, AnySlotMap, CapabilityConstraintConfig<S, T>>\n): readonly T[] {\n  const canPlay = config.canPlayTrack;\n  if (!canPlay) return tracks;\n  return tracks.filter((track) => canPlay(track));\n}\n\n/**\n * Active-CDN scope — a soft filter, shared by video and audio. Narrows to the\n * highest-priority CDN in `cdnPriority` (owned by `deriveCdnPriority`) that\n * still has tracks, so every track type stays on one CDN. A redundant-streams\n * source lists the same renditions on multiple hosts; this keeps the pick on one\n * host rather than letting the ranker drift across them.\n *\n * \"Active\" is derived, not stored: constraints run before the rule chain, so a\n * failed CDN's tracks are already pruned by the time this runs — \"first CDN with\n * survivors\" *is* the active CDN, and it falls through to the next on failover\n * (and snaps back to the primary when it recovers). Content steering reorders\n * `cdnPriority`; this rule just honors the order.\n *\n * Soft-filter semantics: passes through when there's no `cdnPriority` signal/value\n * (no preference) or when nothing matches (`applyRules` skips an empty result).\n * Non-redundant sources have one CDN, so the narrow is a no-op.\n *\n * The CDN-id derivation defaults to origin-based `getCdnId`, overridable via the\n * `getCdnId` config — it must match the one `deriveCdnPriority` used to build\n * `cdnPriority`, or no track's CDN would ever equal an entry.\n */\nfunction preferActiveCdn<S extends SelectionKey, T extends SwitchableTrack>(\n  tracks: readonly T[],\n  { state, config }: SelectionRuleDeps<CdnScopeStateMap<S>, AnySlotMap, CdnRuleConfig<S, T>>\n): readonly T[] {\n  const cdnPriority = state.cdnPriority?.get();\n  if (!cdnPriority?.length) return tracks;\n  const getCdnId = config.getCdnId ?? defaultGetCdnId;\n  for (const cdn of cdnPriority) {\n    const tracksUsingCdn = tracks.filter((track) => getCdnId(track.url) === cdn);\n    if (tracksUsingCdn.length) return tracksUsingCdn;\n  }\n  return tracks;\n}\n\n/**\n * Bandwidth ranking — the terminal sort, shared by video and audio. Orders by\n * the throughput estimate: tracks within the bandwidth threshold first\n * (fitting), highest bitrate first; then over-threshold tracks, least-over\n * first. The head is the best-quality track that fits, falling back to the\n * smallest over-throughput track when nothing fits.\n *\n * Hysteresis without temporal state: the current track's effective bitrate is\n * boosted by `upgradeMargin` in the fitting sort, so a higher track only\n * outranks it once it clears `current.bitrate * upgradeMargin` (no flapping on\n * marginal bandwidth gains). Downgrades fall out for free — a current track\n * over the threshold isn't in the fitting set to be boosted, so the best fit (a\n * downgrade) wins immediately. Equal-bitrate tracks break by resolution (higher\n * `width × height` first), so an equal-bitrate ladder never picks a lower-\n * quality rendition by manifest order; audio tracks carry no dimensions, so\n * they area-compare equal and a stable sort keeps their candidate order (e.g.\n * same-bitrate language variants). Early-bail skips this rule when a prior one\n * narrowed to a single track, so the estimate is neither read nor subscribed\n * while that holds.\n */\nfunction rankByBandwidth<S extends SelectionKey, T extends SwitchableTrack>(\n  tracks: readonly T[],\n  { state, config }: SelectionRuleDeps<BandwidthRankerStateMap<S>, AnySlotMap, BandwidthRankerConfig<S, T>>\n): readonly T[] {\n  const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;\n  const upgradeMargin = config.quality?.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;\n  const initialBandwidth = config.initialBandwidth ?? DEFAULT_INITIAL_BANDWIDTH;\n  const bandwidthConfig: BandwidthConfig = { ...DEFAULT_BANDWIDTH_CONFIG, ...config.bandwidth };\n  if (!state.bandwidthState) {\n    console.debug(\n      '[track-switching] rankByBandwidth: no bandwidthState signal in composition; ranking on initialBandwidth'\n    );\n  }\n  const threshold = getBandwidthEstimate(state.bandwidthState?.get(), initialBandwidth, bandwidthConfig) * safetyMargin;\n  const currentId = state[config.selectionKey].get();\n  const bitrate = (track: T) => track.bandwidth ?? 0;\n  // Boost the current track's sort weight by upgradeMargin (fitting set only) so\n  // an upgrade must clear current.bitrate * upgradeMargin to outrank it.\n  const rank = (track: T) => (track.id === currentId ? bitrate(track) * upgradeMargin : bitrate(track));\n  // Equal bitrate → prefer higher resolution (width × height), so an\n  // equal-bitrate ladder doesn't pick a lower-quality rendition by manifest\n  // order. Audio tracks carry no dimensions, so they area-compare equal and\n  // keep candidate order (stable sort).\n  const fitting = tracks\n    .filter((track) => bitrate(track) <= threshold)\n    .sort((a, b) => rank(b) - rank(a) || resolutionArea(b) - resolutionArea(a));\n  const over = tracks\n    .filter((track) => bitrate(track) > threshold)\n    .sort((a, b) => bitrate(a) - bitrate(b) || resolutionArea(b) - resolutionArea(a));\n  return [...fitting, ...over];\n}\n\n/**\n * Default final pick: the chain head. `applyRules` never narrows to nothing and\n * early-bails to a single survivor, so video and audio always converge to a\n * track and the head is the pick.\n */\nfunction selectChainHead<T extends SwitchableTrack>(candidates: readonly T[]): string {\n  return candidates[0]!.id;\n}\n\n/**\n * State the text terminal reads: the lifecycle map plus an *optional*\n * `userTextTrackSelection` — the standing user intent. `Partial<TextTrack>` is an\n * explicit pick (language-based), `'off'` is explicit no-captions, `undefined` is\n * auto (no preference). The slot exists only when the composition materializes it\n * (`shareSignals`); the terminal reads it defensively and treats absence as auto.\n *\n * Unlike `user*TrackSelection` for video/audio, this carries the `'off'` sentinel\n * and feeds the terminal pick (not the shared `filterByUserSelection`) — text is\n * the only type whose selection is legitimately optional, so the off/auto logic\n * lives in one text-specific place rather than widening the shared filter.\n */\ntype TextSelectionStateMap = TrackSwitchingStateMap<'selectedTextTrackId'> & {\n  userTextTrackSelection?: ReadonlySignal<Partial<TextTrack> | 'off' | undefined>;\n};\n\n/** Config the text terminal reads: the base config plus the opt-in default policy. */\ntype TextTerminalConfig = TrackSwitchingConfig<'selectedTextTrackId', TextTrackCandidate> & TextSelectionConfig;\n\n/**\n * Terminal pick for text — the `resolveSelection` the text variant supplies.\n * Resolves the standing `userTextTrackSelection` intent against the chain's\n * survivors (already CDN-failover-pruned and active-CDN-scoped):\n *\n *   - `'off'` → no selection (clear the slot). Sticky through re-evaluation, so a\n *     live refresh or failover re-run can't re-assert a default.\n *   - explicit `Partial<TextTrack>` → narrow to the match (language-based). A\n *     stale pick whose match is gone (e.g. the language dropped on a source\n *     change) falls through to the default policy.\n *   - auto (`undefined`) → the opt-in default policy (`preferredSubtitleLanguage`\n *     → `DEFAULT=YES + AUTOSELECT=YES` → none), shared with `pickTextTrack`.\n *\n * Returning `undefined` is a real outcome (captions are opt-in), which is why the\n * text variant relies on `setupTrackSwitching`'s no-selection seam.\n */\nfunction pickResolvedTextTrack<T extends TextTrackCandidate>(\n  candidates: readonly T[],\n  { state, config }: SelectionRuleDeps<TextSelectionStateMap, AnySlotMap, TextTerminalConfig>\n): string | undefined {\n  const intent = state.userTextTrackSelection?.get();\n  if (intent === 'off') return undefined;\n  if (intent) {\n    // The stored intent is a `Partial<TextTrack>`; cast to the candidate's own\n    // partial shape so the generic `matchesPartialTrack` accepts it (every field\n    // it carries — language, forced — exists on the candidate too).\n    const matched = candidates.filter((track) => matchesPartialTrack(track, intent as Partial<T>));\n    if (matched.length) return matched[0]!.id;\n  }\n  return pickTextTrackFromTracks(candidates, config);\n}\n\n// `context` is the composition's context map, threaded in by each variant's\n// rest-spread and typed as the generic slot-map shape (`AnySlotMap`). It can't\n// be a typed param on the `defineBehavior` setup without widening `ContextMap`\n// to its constraint and forcing the slot required, so the variants forward it\n// untyped via the rest and it lands here — absent on direct setup calls, and\n// passed straight through to the rules (which don't read it yet).\nexport function setupTrackSwitching<\n  S extends SelectionKey,\n  T extends SwitchableTrack,\n  C extends TrackSwitchingConfig<S, T>,\n>(deps: { state: TrackSwitchingStateMap<S>; context?: AnySlotMap; config: C }) {\n  const { state, config } = deps;\n  const { selectionKey, getTracks, rules, resolveSelection = selectChainHead } = config;\n\n  const derivedStateSignal = computed(() =>\n    isResolvedPresentation(state.presentation.get())\n      ? ('presentation-resolved' as const)\n      : ('presentation-unresolved' as const)\n  );\n\n  // The playable candidate set — the tracks the rule chain gets to pick from,\n  // derived *outside* the reaction. The hard-constraints pre-pass (capability\n  // probing, CDN-failover cooldown) narrows the type's tracks before the chain\n  // runs. Because this is a `computed`, a constraint's own signal reads (e.g.\n  // `cdnHealth`) are tracked here, so when the playable set changes — a new\n  // source, or a *dynamic* constraint like a CDN entering cooldown — the effect\n  // re-picks. With no constraints configured this is just the type's tracks\n  // while a presentation is resolved.\n  //\n  // The `equals` gates notification on the *set of track ids*, not array\n  // identity: a live playlist refresh swaps in a new presentation object with\n  // the same variant tracks, and a constraint's inputs can churn without\n  // changing which tracks survive. In both cases the playable set is unchanged,\n  // so the reaction must not re-fire (the rule chain still re-runs on its own\n  // inputs — bandwidth, user selection). Same intent as `equalsById`, for the\n  // track list.\n  const candidateSet = computed<readonly T[]>(\n    () => {\n      const presentation = state.presentation.get();\n      if (!isResolvedPresentation(presentation)) return [];\n      return applyConstraints(config.constraints ?? [], getTracks(presentation), deps);\n    },\n    { equals: (a, b) => a.length === b.length && a.every((track) => b.some((other) => other.id === track.id)) }\n  );\n\n  return createMachineReactor({\n    initial: 'presentation-unresolved',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'presentation-unresolved': {},\n      'presentation-resolved': {\n        // Canonical cleanup-binds-to-setup: the selection signal's valid\n        // lifespan is exactly 'presentation-resolved'. Clear fires on exit,\n        // covering both src unload and behavior destroy.\n        entry: () => () => state[selectionKey].set(undefined),\n        effects: [\n          () => {\n            // Reactive read: subscribes the reaction to the candidate set, so a\n            // new presentation — or a constraint pruning it — re-fires this and\n            // re-picks.\n            const tracks = candidateSet.get();\n\n            // Empty candidate set — two shapes, told apart by whether the type\n            // has any tracks at all:\n            //   - The type has no tracks (e.g. a video-only source's absent\n            //     audio): legitimate, nothing to pick or clear.\n            //   - The type HAS tracks but the hard-constraints pre-pass pruned\n            //     every one (every rendition undecodable, or every CDN in\n            //     failover cooldown): no playable rendition. Clear the selection\n            //     so a pick made earlier — e.g. under the initial mp4 label,\n            //     before resolve-track relabeled the type to a non-fMP4\n            //     container — can't linger as a now-unplayable selection and\n            //     silently stall the pipeline.\n            // The `console.error` is a placeholder until the planned error\n            // behaviors surface \"nothing playable\" as observable state.\n            if (!tracks.length) {\n              const presentation = peek(state.presentation);\n              const hasTracksOfType = isResolvedPresentation(presentation) && getTracks(presentation).length > 0;\n              if (hasTracksOfType) {\n                console.error(\n                  `[track-switching] every ${selectionKey} candidate was filtered out by constraints; clearing selection`\n                );\n                state[selectionKey].set(undefined);\n              }\n              return;\n            }\n\n            // The whole deps object passes straight through to every rule in the\n            // variant-supplied chain (state + config from the behavior; context\n            // threaded in by the variant's rest-spread). Typed against the base\n            // config — each rule re-declares the extra fields it reads as\n            // optional, and the concrete `C` is assignable to the base.\n            const candidates = applyRules<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>(\n              rules,\n              tracks,\n              deps\n            );\n\n            // applyRules early-bails to a single survivor and never narrows to\n            // nothing (a soft filter that would empty the set falls through), so\n            // the pick is just the head. An empty result means a rule misbehaved\n            // — applyRules is supposed to account for those cases, so surface it.\n            if (!candidates.length) {\n              console.error('[track-switching] applyRules returned no candidates');\n              return;\n            }\n            // Map survivors to the final id. Defaults to the chain head; a\n            // variant with optional selection (text) may resolve to `undefined`,\n            // which clears the slot (e.g. explicit off, opt-in decline).\n            // No change-guard needed: the slot uses default (Object.is) equality,\n            // so re-setting the same value is a no-op (no notify, no re-fire).\n            state[selectionKey].set(resolveSelection(candidates, deps));\n          },\n        ],\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Variant: switchVideoTrack — bandwidth-driven ABR\n// ============================================================================\n\n/**\n * Manage `selectedVideoTrackId`: pick a default on src load, dynamically\n * adjust based on bandwidth, clear on src unload. Honors\n * `userVideoTrackSelection` as a partial-track constraint on candidates;\n * short-circuits ABR when the constraint narrows to a single track.\n *\n * @example\n * const reactor = switchVideoTrack.setup({ state });\n */\nexport const switchVideoTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedVideoTrackId'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config,\n    ...otherProps\n  }: {\n    state: TrackSwitchingStateMap<'selectedVideoTrackId'>;\n    config?: SwitchVideoTrackConfig;\n  }) =>\n    setupTrackSwitching({\n      ...otherProps,\n      state,\n      config: {\n        ...config,\n        selectionKey: 'selectedVideoTrackId',\n        userSelectionKey: 'userVideoTrackSelection',\n        getTracks: (presentation) => getTracksByType(presentation, 'video') as readonly VideoTrackCandidate[],\n        constraints: [excludeFailedCdns, excludeUnplayableTracks],\n        rules: [filterByUserSelection, preferActiveCdn, rankByBandwidth],\n      },\n    }),\n});\n\n// ============================================================================\n// Variant: switchAudioTrack — bandwidth-ranked (shared ranker)\n// ============================================================================\n\n/**\n * Manage `selectedAudioTrackId`: pick a default on src load, narrow by\n * `userAudioTrackSelection` filter, re-pick on filter change, clear on\n * src unload.\n *\n * Mid-stream flush on language switch is handled by the segment-loader's\n * `planTasks` (see `playback/actors/dom/segment-loader.ts`) — not this\n * behavior. Same split as the video pipeline: slot owner writes; loader\n * orchestrates segment + flush plans.\n *\n * @example\n * const reactor = switchAudioTrack.setup({ state });\n */\nexport const switchAudioTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedAudioTrackId'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config,\n    ...otherProps\n  }: {\n    state: TrackSwitchingStateMap<'selectedAudioTrackId'>;\n    // Shares the video config shape so the engine config spreads through (CDN\n    // derivation + any future cross-cutting fields).\n    config?: SwitchVideoTrackConfig;\n  }) =>\n    setupTrackSwitching({\n      ...otherProps,\n      state,\n      config: {\n        // Spread engine config so cross-cutting fields (`getCdnId`, future shared\n        // tuning) flow through like they do for video, then override the per-type\n        // wiring. Video-only ABR tuning (`quality`/`bandwidth`/`initialBandwidth`)\n        // rides along into the shared `rankByBandwidth` too; harmless since audio\n        // has no `bandwidthState` to act on it and the ranker always yields a pick.\n        // FOLLOW-UP: a shared config type for the genuinely cross-cutting fields\n        // would keep video-only tuning out of audio entirely (CJP).\n        ...config,\n        selectionKey: 'selectedAudioTrackId',\n        userSelectionKey: 'userAudioTrackSelection',\n        getTracks: (presentation) => getTracksByType(presentation, 'audio') as readonly AudioTrackCandidate[],\n        constraints: [excludeFailedCdns, excludeUnplayableTracks],\n        rules: [filterByUserSelection, preferActiveCdn, rankByBandwidth],\n      },\n    }),\n});\n\n// ============================================================================\n// Variant: switchTextTrack — intent-resolved, optional selection\n// ============================================================================\n\n/**\n * Config for `switchTextTrack` — the opt-in default policy\n * (`preferredSubtitleLanguage` / `includeForcedTracks` / `enableDefaultTrack`,\n * via `TextSelectionConfig`) read by the terminal when the user has no standing\n * intent, plus the `getCdnId` override shared with the CDN constraint + scope.\n */\nexport interface SwitchTextTrackConfig extends TextSelectionConfig {\n  /** Override CDN-id derivation (shared by the failed-CDN constraint + active-CDN scope). */\n  getCdnId?: GetCdnId;\n}\n\n/**\n * Manage `selectedTextTrackId` as the single-writer **output** of standing user\n * intent (`userTextTrackSelection`) resolved against the playable, CDN-scoped\n * text renditions: clear on src unload; re-resolve when a CDN fails or recovers.\n *\n * Unlike video/audio, the selection is *optional* — captions are opt-in and the\n * user can turn them off — so the chain skips the bandwidth ranker and the shared\n * user-selection filter, and supplies a text-specific terminal\n * (`pickResolvedTextTrack`) that may resolve to no-selection via\n * `setupTrackSwitching`'s `resolveSelection` seam. Constraints are failed-CDN only\n * (`excludeUnplayableTracks`/`canPlayTrack` is MSE-based — the wrong probe for\n * text, whose playability is SPF-parser support); the active-CDN scope co-locates\n * captions with the surviving CDN on failover.\n *\n * @example\n * const reactor = switchTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });\n */\nexport const switchTextTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedTextTrackId'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config,\n    ...otherProps\n  }: {\n    state: TrackSwitchingStateMap<'selectedTextTrackId'>;\n    config?: SwitchTextTrackConfig;\n  }) =>\n    // Explicit type args pin the candidate type to `TextTrackCandidate`. Video and\n    // audio let it infer to the `SwitchableTrack` constraint (harmless — every\n    // rule is assignable up to it), but the text terminal needs the narrower type\n    // (it reads text-only fields), so it's named here rather than inferred.\n    setupTrackSwitching<'selectedTextTrackId', TextTrackCandidate, TextTerminalConfig & SwitchTextTrackConfig>({\n      ...otherProps,\n      state,\n      config: {\n        ...config,\n        selectionKey: 'selectedTextTrackId',\n        getTracks: (presentation) => getTracksByType(presentation, 'text') as readonly TextTrackCandidate[],\n        constraints: [excludeFailedCdns],\n        rules: [preferActiveCdn],\n        resolveSelection: pickResolvedTextTrack,\n      },\n    }),\n});\n"],"mappings":"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"}

package/dist/default/playback/engines/background-video/adapter.js

@@ -0,0 +1,158 @@
+import { maxResolutionToPixelArea, pickTrackUnderPixelArea } from "../../../media/primitives/select-tracks.js";
+import { createBackgroundVideoEngine } from "./engine.js";
+//#region src/playback/engines/background-video/adapter.ts
+const backgroundVideoMediaDefaultProps = {
+	src: "",
+	preload: "auto",
+	loop: true,
+	muted: true,
+	autoplay: true,
+	maxResolution: void 0
+};
+/**
+* Mixin that adds the background-video SPF playback engine to any
+* base class.
+*
+* Implements the WHATWG HTML media element contract (`src`, `preload`,
+* `loop`, `muted`, `autoplay`, `play()`) so it can be dropped in anywhere a
+* media element API is expected. Compared to `SimpleHlsMediaMixin`, this
+* variant:
+*
+* - exposes `loop`, `muted`, and `autoplay` as adapter-owned native
+*   passthroughs, all defaulting to `true` — the use case is silent
+*   autoplay-looping video, so muted + autoplay satisfy browser autoplay
+*   policies and loop is the defining behavior;
+* - drives the underlying engine with the background-video
+*   composition (single-rendition, video-only, autoplay-from-construction).
+*
+* A new engine is created on every src assignment — this fully tears down
+* all state, SourceBuffers, and in-flight requests from the previous
+* source before the next one begins. The media element reference is
+* preserved across src changes and re-applied to the new engine
+* automatically.
+*
+* @example
+* class BackgroundVideoMedia extends BackgroundVideoMediaMixin(HTMLVideoElementHost) {}
+*
+* const media = new BackgroundVideoMedia();
+* media.attach(document.querySelector('video'));
+* media.src = 'https://stream.mux.com/abc123.m3u8';
+* media.play();
+*/
+function BackgroundVideoMediaMixin(BaseClass) {
+	class BackgroundVideoMediaImpl extends BaseClass {
+		#engine;
+		#config;
+		#signals;
+		#preload = backgroundVideoMediaDefaultProps.preload;
+		#loop = backgroundVideoMediaDefaultProps.loop;
+		#muted = backgroundVideoMediaDefaultProps.muted;
+		#autoplay = backgroundVideoMediaDefaultProps.autoplay;
+		#maxResolution;
+		/** Pending loadstart listener from a deferred play() retry, if any. */
+		#loadstartListener = null;
+		constructor(...args) {
+			super(...args);
+			const { config } = args?.[0] ?? {};
+			this.#config = config;
+			this.#maxResolution = config?.maxResolution;
+			this.#engine = this.#createEngine();
+		}
+		get engine() {
+			return this.#engine;
+		}
+		attach(mediaElement) {
+			super.attach?.(mediaElement);
+			mediaElement.loop = this.#loop;
+			mediaElement.muted = this.#muted;
+			mediaElement.autoplay = this.#autoplay;
+			this.#signals.context.mediaElement.set(mediaElement);
+		}
+		detach() {
+			this.#cancelPendingPlay();
+			this.#signals.context.mediaElement.set(void 0);
+			super.detach?.();
+		}
+		destroy() {
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+		}
+		get preload() {
+			return this.#preload;
+		}
+		set preload(_value) {}
+		get loop() {
+			return this.#loop;
+		}
+		set loop(_value) {}
+		get muted() {
+			return this.#muted;
+		}
+		set muted(_value) {}
+		get autoplay() {
+			return this.#autoplay;
+		}
+		set autoplay(_value) {}
+		get maxResolution() {
+			return this.#maxResolution;
+		}
+		/**
+		* Set the cap. Accepts `"720p"` / `"1080p"` etc., a bare number
+		* (interpreted as pixel area), or `undefined` to clear. Unrecognized
+		* values are treated as no cap.
+		*/
+		set maxResolution(value) {
+			if (value === this.#maxResolution) return;
+			this.#maxResolution = value;
+		}
+		get src() {
+			return this.#signals.state.presentation.get()?.url ?? "";
+		}
+		set src(value) {
+			this.#cancelPendingPlay();
+			if (value) this.#signals.state.presentation.set({ url: value });
+			else this.#signals.state.presentation.set(void 0);
+		}
+		async play() {
+			const mediaElement = this.#signals.context.mediaElement.get();
+			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("BackgroundVideoMediaElement: no media element attached"));
+			try {
+				return await mediaElement.play();
+			} catch (err) {
+				if (this.src) return new Promise((resolve, reject) => {
+					const listener = () => {
+						this.#loadstartListener = null;
+						mediaElement.play().then(resolve, reject);
+					};
+					this.#loadstartListener = listener;
+					mediaElement.addEventListener("loadstart", listener, { once: true });
+				});
+				throw err;
+			}
+		}
+		#createEngine() {
+			const adapterPicker = (presentation) => {
+				return pickTrackUnderPixelArea((presentation.selectionSets?.find((s) => s.type === "video"))?.switchingSets[0]?.tracks ?? [], maxResolutionToPixelArea(this.#maxResolution))?.id;
+			};
+			return createBackgroundVideoEngine({
+				picker: adapterPicker,
+				...this.#config,
+				onSignalsReady: (signals) => {
+					this.#signals = signals;
+				}
+			});
+		}
+		#cancelPendingPlay() {
+			if (!this.#loadstartListener) return;
+			this.#signals.context.mediaElement.get()?.removeEventListener("loadstart", this.#loadstartListener);
+			this.#loadstartListener = null;
+		}
+	}
+	return BackgroundVideoMediaImpl;
+}
+/** Standalone SPF background-video adapter with no base class. */
+var BackgroundVideoMediaElement = class extends BackgroundVideoMediaMixin(class {}) {};
+//#endregion
+export { BackgroundVideoMediaElement, BackgroundVideoMediaMixin, backgroundVideoMediaDefaultProps };
+
+//# sourceMappingURL=adapter.js.map

package/dist/default/playback/engines/background-video/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["#config","#maxResolution","#engine","#createEngine","#loop","#muted","#autoplay","#signals","#cancelPendingPlay","#preload","#loadstartListener"],"sources":["../../../../../src/playback/engines/background-video/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  maxResolutionToPixelArea,\n  pickTrackUnderPixelArea,\n  type TrackPicker,\n} from '../../../media/primitives/select-tracks';\nimport type { VideoSelectionSet } from '../../../media/types';\nimport {\n  type BackgroundVideoEngineConfig,\n  type BackgroundVideoEngineContext,\n  type BackgroundVideoEngineSignals,\n  type BackgroundVideoEngineState,\n  createBackgroundVideoEngine,\n} from './engine';\n\nexport interface BackgroundVideoMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n  loop: boolean;\n  muted: boolean;\n  autoplay: boolean;\n  maxResolution: string | number | undefined;\n}\n\nexport const backgroundVideoMediaDefaultProps: BackgroundVideoMediaProps = {\n  src: '',\n  preload: 'auto',\n  loop: true,\n  muted: true,\n  autoplay: true,\n  maxResolution: undefined,\n};\n\nexport interface BackgroundVideoMediaAPI extends BackgroundVideoMediaProps {\n  readonly engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds the background-video SPF playback engine to any\n * base class.\n *\n * Implements the WHATWG HTML media element contract (`src`, `preload`,\n * `loop`, `muted`, `autoplay`, `play()`) so it can be dropped in anywhere a\n * media element API is expected. Compared to `SimpleHlsMediaMixin`, this\n * variant:\n *\n * - exposes `loop`, `muted`, and `autoplay` as adapter-owned native\n *   passthroughs, all defaulting to `true` — the use case is silent\n *   autoplay-looping video, so muted + autoplay satisfy browser autoplay\n *   policies and loop is the defining behavior;\n * - drives the underlying engine with the background-video\n *   composition (single-rendition, video-only, autoplay-from-construction).\n *\n * A new engine is created on every src assignment — this fully tears down\n * all state, SourceBuffers, and in-flight requests from the previous\n * source before the next one begins. The media element reference is\n * preserved across src changes and re-applied to the new engine\n * automatically.\n *\n * @example\n * class BackgroundVideoMedia extends BackgroundVideoMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new BackgroundVideoMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n * media.play();\n */\nexport function BackgroundVideoMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class BackgroundVideoMediaImpl extends BaseClass {\n    #engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n    #config: BackgroundVideoEngineConfig;\n    #signals!: BackgroundVideoEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = backgroundVideoMediaDefaultProps.preload;\n    #loop: boolean = backgroundVideoMediaDefaultProps.loop;\n    #muted: boolean = backgroundVideoMediaDefaultProps.muted;\n    #autoplay: boolean = backgroundVideoMediaDefaultProps.autoplay;\n    #maxResolution: string | number | undefined;\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\n      this.#maxResolution = config?.maxResolution;\n      this.#engine = this.#createEngine();\n    }\n\n    get engine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      // Apply adapter-owned native props before the engine takes over —\n      // the underlying element needs `loop` / `muted` / `autoplay` set for\n      // the use case's autoplay-looping semantics.\n      mediaElement.loop = this.#loop;\n      mediaElement.muted = this.#muted;\n      mediaElement.autoplay = this.#autoplay;\n\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // preload — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get preload(): '' | 'none' | 'metadata' | 'auto' {\n      return this.#preload;\n    }\n\n    set preload(_value: '' | 'none' | 'metadata' | 'auto') {\n      // Noop for this phase\n    }\n\n    // -------------------------------------------------------------------------\n    // loop / muted / autoplay — adapter-owned IDL attributes mirrored onto\n    // the attached media element. The engine itself has no opinion on any\n    // of them.\n    // -------------------------------------------------------------------------\n\n    get loop(): boolean {\n      return this.#loop;\n    }\n\n    set loop(_value: boolean) {\n      // Noop for this phase\n    }\n\n    get muted(): boolean {\n      return this.#muted;\n    }\n\n    set muted(_value: boolean) {\n      // Noop for this phase\n    }\n\n    get autoplay(): boolean {\n      return this.#autoplay;\n    }\n\n    set autoplay(_value: boolean) {\n      // Noop for this phase\n    }\n\n    // -------------------------------------------------------------------------\n    // maxResolution — adapter-owned cap on the picked rendition. The engine's\n    // closure picker (see `#createEngine`) reads this field at pick time, so\n    // setter writes take effect on the next `presentation-resolved` transition\n    // without an engine rebuild.\n    // -------------------------------------------------------------------------\n\n    get maxResolution(): string | number | undefined {\n      return this.#maxResolution;\n    }\n\n    /**\n     * Set the cap. Accepts `\"720p\"` / `\"1080p\"` etc., a bare number\n     * (interpreted as pixel area), or `undefined` to clear. Unrecognized\n     * values are treated as no cap.\n     */\n    set maxResolution(value: string | number | undefined) {\n      if (value === this.#maxResolution) return;\n      this.#maxResolution = value;\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // Each assignment destroys the current engine and starts a fresh one,\n    // matching the browser's load algorithm reset on src change.\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      this.#cancelPendingPlay();\n\n      if (value) {\n        this.#signals.state.presentation.set({ url: value });\n      } else {\n        this.#signals.state.presentation.set(undefined);\n      }\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('BackgroundVideoMediaElement: 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\n        // by 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      const adapterPicker: TrackPicker = (presentation) => {\n        const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n        const tracks = videoSet?.switchingSets[0]?.tracks ?? [];\n        return pickTrackUnderPixelArea(tracks, maxResolutionToPixelArea(this.#maxResolution))?.id;\n      };\n\n      return createBackgroundVideoEngine({\n        picker: adapterPicker,\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return BackgroundVideoMediaImpl as unknown as MixinReturn<Base, BackgroundVideoMediaAPI>;\n}\n\n/** Standalone SPF background-video adapter with no base class. */\nexport class BackgroundVideoMediaElement extends BackgroundVideoMediaMixin(class {}) {}\n"],"mappings":"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"}