@videojs/spf 10.0.0-beta.9 → 10.0.0-rc.2

package/dist/dev/playback/behaviors/select-tracks.js

@@ -0,0 +1,189 @@
+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 { AUDIO_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from "../primitives/track-types.js";
+import { byDescendingResolution, pickAudioTrackFromTracks, tracksUnderPixelArea } from "../../media/primitives/select-tracks.js";
+import { applyConstraints, applyRules, excludeUnplayableTracks, sameCandidateSet } from "../primitives/selection-rules.js";
+//#region src/playback/behaviors/select-tracks.ts
+/**
+* **Default audio/video track selection on src load / unselect on src unload.** When a presentation is resolved, sets
+* `selectedVideoTrackId` / `selectedAudioTrackId` from a per-type default rule chain if no selection already exists.
+* When the presentation is unset/reset (transitions back to unresolved), clears the selection so a stale id from the
+* previous source doesn't persist.
+*
+* Lifecycle-driven: the pick fires once per transition, and nothing re-picks — that is what separates these from the
+* `switch*` variants. External writes (user picks, ABR, programmatic filter-driven re-picks) are left alone, including
+* a write naming a track the manifest never offered.
+*
+* The one thing policed between transitions is a pick the _constraints_ turn against: a rendition's container and
+* encryption are only known once its media playlist resolves, which is after the pick was made, so a selection that
+* becomes unplayable is dropped. Dropped, never moved — re-picking is exactly the behavior `switchVideoTrack` exists to
+* provide. Dropping reports nothing on its own, since whatever made the pick unplayable already reported its own, more
+* specific cause.
+*
+* Selection runs the same rule model `switchVideoTrack` does — a hard `constraints` pre-pass, then an ordered `rules`
+* chain, with the pick as the head (see `internal/design/spf/track-switching-model.md`). What differs is reactivity,
+* not the rules: this evaluates the chain once on resolve and pins the result, where `switchVideoTrack` re-evaluates
+* inside an effect so its rules subscribe to bandwidth and user selection. A rule written for one therefore composes
+* into the other unchanged.
+*
+* Both are config-driven, each per-type export wiring a sensible default: audio's three-tier language policy, and for
+* video the _empty_ chain — with nothing narrowing or reordering, the head is the first candidate. The behavior's
+* `config` is forwarded to the rules, so options like `preferredAudioLanguage` reach them without an intermediate
+* layer.
+*
+* Note a rule can only pick among real candidates, where the picker it replaced could return any id at all. An id
+* absent from the manifest was never selectable, so that narrowing is the point rather than a limitation.
+*
+* Compose `selectVideoTrack` for the simple "pick a default video track" behavior, or `switchVideoTrack`
+* (`./track-switching.ts`) for the ABR-driven variant. Compose `selectAudioTrack` for the simple default pick, or
+* `switchAudioTrack` (`./track-switching.ts`) for the filter-reactive + mid-stream-flush slot-owner variant — when
+* audio-abr lands, `switchAudioTrack` extends into `switchAudioQuality`. Compose only one per type — they're
+* alternatives, not stackable (each writes the same `selected*TrackId` slot). The simple variants tree-shake out the
+* heavier machinery (bandwidth estimator, quality selection, flush orchestration).
+*
+* Text selection has no simple variant here — it's owned by `switchTextTrack` (`./track-switching.ts`), which resolves
+* standing `userTextTrackSelection` intent against the constrained, CDN-scoped renditions.
+*/
+function setupTrackSelection({ state, config: { selectedKey, trackType, constraints, rules, ruleConfig } }) {
+	const derivedStateSignal = computed(() => isResolvedPresentation(state.presentation.get()) ? "presentation-resolved" : "presentation-unresolved");
+	const deps = {
+		state,
+		config: ruleConfig
+	};
+	const candidateSet = computed(() => {
+		const presentation = state.presentation.get();
+		if (!isResolvedPresentation(presentation)) return [];
+		return applyConstraints(constraints, getTracksByType(presentation, trackType), deps);
+	}, { equals: sameCandidateSet });
+	return createMachineReactor({
+		initial: "presentation-unresolved",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"presentation-unresolved": {},
+			"presentation-resolved": {
+				entry: () => {
+					if (!state[selectedKey].get()) {
+						const id = applyRules(rules, peek(candidateSet), deps)[0]?.id;
+						if (id) state[selectedKey].set(id);
+					}
+					return () => state[selectedKey].set(void 0);
+				},
+				effects: [() => {
+					const selectedId = peek(state[selectedKey]);
+					if (!selectedId) return;
+					if (candidateSet.get().some((track) => track.id === selectedId)) return;
+					const presentation = peek(state.presentation);
+					if (isResolvedPresentation(presentation) && getTracksByType(presentation, trackType).some((track) => track.id === selectedId)) state[selectedKey].set(void 0);
+				}]
+			}
+		}
+	});
+}
+/** Default video chain: none. The first candidate is the pick. */
+const DEFAULT_VIDEO_RULES = [];
+/**
+* Default audio chain: the three-tier policy (`preferredAudioLanguage` → `DEFAULT=YES` → first) as a single narrowing
+* rule. Returning `[]` when nothing is picked lets `applyRules` fall through to the unnarrowed candidates, so the head
+* stays the first track — the same last tier the policy itself ends on.
+*/
+const preferAudioPolicy = (tracks, { config }) => {
+	const id = pickAudioTrackFromTracks(tracks, config);
+	const pick = tracks.find((track) => track.id === id);
+	return pick ? [pick] : [];
+};
+const DEFAULT_AUDIO_RULES = [preferAudioPolicy];
+/**
+* Order the candidates by resolution, largest first, with bandwidth breaking ties between renditions of identical
+* dimensions. The background-video default — that variant pins one rendition for the session, and absent a cap the
+* largest is the head.
+*
+* A ranker, so it reorders rather than narrowing: the chain's pick is the head of what it returns, which means ranking
+* never has to collapse to one track. Belongs last in a chain — a sort only reorders what survived the filters ahead of
+* it, and leaving it last is what lets `applyRules` early-bail before it runs.
+*
+* Exported because it is a _rule_, not a variant's private policy: the same one composes into `switchVideoTrack`'s
+* chain when a ranker is wanted there.
+*/
+const preferHighestResolution = (tracks) => [...tracks].sort(byDescendingResolution);
+/**
+* Narrow to the renditions that fit the screen, by pixel area — the screen-size cap from
+* `internal/design/spf/features/rendition-selection-caps.md`, as a scope (soft filter) rather than a constraint: an
+* over-cap rendition is wasteful, not unplayable, so nothing here may make a source unplayable.
+*
+* Narrows only — it neither orders the survivors nor resolves the case where none survive, because `applyRules` owns
+* both. So it needs a ranker behind it to pick within the cap: `[screenResolutionCap, preferHighestResolution]` yields
+* the largest rendition that fits. Composed _last_, the pick would instead be whichever fitting rendition the manifest
+* happened to list first.
+*
+* Reading `state.screenResolution` through its signal is what subscribes a re-evaluating chain (`switchVideoTrack`) to
+* screen changes; `selectVideoTrack` pins the first answer instead, by design.
+*
+* Compares areas rather than matching a `"1080p"`-style tier because a tier only describes a rendition once you assume
+* its aspect ratio — the assumption that mis-measures an anamorphic ladder. See `media/dom/screen.ts`.
+*
+* Three ways the cap ends up not applying, all of them fall-through:
+*
+* - **No `screenResolution` signal at all**, because the composition omits `trackScreenResolution`. So composing the cap
+*   without its signal source is inert rather than broken.
+* - **A `screenResolution` of `undefined`**, meaning no screen to read. "Unknown" has to mean "don't cap": treating it as
+*   an area of zero would pin every source to its smallest rendition on exactly the environments we know least about.
+* - **No rendition fits**, on a screen smaller than the whole ladder. `applyRules` skips the empty result and the chain
+*   proceeds unnarrowed, so the ranker behind the cap decides — for `preferHighestResolution`, the largest rendition. A
+*   floor is the fix if that ever matters (`rendition-selection-caps.md` carries one), not a special case here.
+*/
+const screenResolutionCap = (tracks, { state }) => {
+	const screenResolution = state?.screenResolution?.get();
+	if (!screenResolution) return [];
+	return tracksUnderPixelArea(tracks, screenResolution.width * screenResolution.height);
+};
+/**
+* Default video constraints: the capability pre-pass alone. No `excludeFailedCdns` — this variant's compositions run no
+* failover monitor, so `failedCdns` has no writer and the constraint would always pass through.
+*/
+const DEFAULT_VIDEO_CONSTRAINTS = [excludeUnplayableTracks];
+/**
+* Select a video track when a presentation loads. Clears the selection on src unload.
+*
+* This is the simple, non-ABR counterpart to `switchVideoTrack` — compose one or the other, not both (both write
+* `selectedVideoTrackId`). Composing `selectVideoTrack` alone tree-shakes out the ABR code path (bandwidth-estimator,
+* quality-selection); use it for sources without meaningful quality variants, test setups, or players that
+* intentionally pin a quality.
+*
+* @example
+*   const reactor = selectVideoTrack.setup({ state });
+*/
+const selectVideoTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedVideoTrackId"],
+	contextKeys: [],
+	setup: ({ state, config }) => setupTrackSelection({
+		state,
+		config: {
+			selectedKey: VIDEO_TYPE_CONFIG.selectedKey,
+			trackType: "video",
+			constraints: config?.constraints ?? DEFAULT_VIDEO_CONSTRAINTS,
+			rules: config?.rules ?? DEFAULT_VIDEO_RULES,
+			ruleConfig: config
+		}
+	})
+});
+defineBehavior({
+	stateKeys: ["presentation", "selectedAudioTrackId"],
+	contextKeys: [],
+	setup: ({ state, config }) => setupTrackSelection({
+		state,
+		config: {
+			selectedKey: AUDIO_TYPE_CONFIG.selectedKey,
+			trackType: "audio",
+			constraints: config?.constraints ?? [],
+			rules: config?.rules ?? DEFAULT_AUDIO_RULES,
+			ruleConfig: config
+		}
+	})
+});
+//#endregion
+export { preferHighestResolution, screenResolutionCap, selectVideoTrack };
+
+//# sourceMappingURL=select-tracks.js.map

package/dist/dev/playback/behaviors/select-tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/playback/behaviors/select-tracks.ts"],"sourcesContent":["/**\n * **Default audio/video track selection on src load / unselect on src unload.** When a presentation is resolved, sets\n * `selectedVideoTrackId` / `selectedAudioTrackId` from a per-type default rule chain if no selection already exists.\n * When the presentation is unset/reset (transitions back to unresolved), clears the selection so a stale id from the\n * previous source doesn't persist.\n *\n * Lifecycle-driven: the pick fires once per transition, and nothing re-picks — that is what separates these from the\n * `switch*` variants. External writes (user picks, ABR, programmatic filter-driven re-picks) are left alone, including\n * a write naming a track the manifest never offered.\n *\n * The one thing policed between transitions is a pick the _constraints_ turn against: a rendition's container and\n * encryption are only known once its media playlist resolves, which is after the pick was made, so a selection that\n * becomes unplayable is dropped. Dropped, never moved — re-picking is exactly the behavior `switchVideoTrack` exists to\n * provide. Dropping reports nothing on its own, since whatever made the pick unplayable already reported its own, more\n * specific cause.\n *\n * Selection runs the same rule model `switchVideoTrack` does — a hard `constraints` pre-pass, then an ordered `rules`\n * chain, with the pick as the head (see `internal/design/spf/track-switching-model.md`). What differs is reactivity,\n * not the rules: this evaluates the chain once on resolve and pins the result, where `switchVideoTrack` re-evaluates\n * inside an effect so its rules subscribe to bandwidth and user selection. A rule written for one therefore composes\n * into the other unchanged.\n *\n * Both are config-driven, each per-type export wiring a sensible default: audio's three-tier language policy, and for\n * video the _empty_ chain — with nothing narrowing or reordering, the head is the first candidate. The behavior's\n * `config` is forwarded to the rules, so options like `preferredAudioLanguage` reach them without an intermediate\n * layer.\n *\n * Note a rule can only pick among real candidates, where the picker it replaced could return any id at all. An id\n * absent from the manifest was never selectable, so that narrowing is the point rather than a limitation.\n *\n * Compose `selectVideoTrack` for the simple \"pick a default video track\" behavior, or `switchVideoTrack`\n * (`./track-switching.ts`) for the ABR-driven variant. Compose `selectAudioTrack` for the simple default pick, or\n * `switchAudioTrack` (`./track-switching.ts`) for the filter-reactive + mid-stream-flush slot-owner variant — when\n * audio-abr lands, `switchAudioTrack` extends into `switchAudioQuality`. Compose only one per type — they're\n * alternatives, not stackable (each writes the same `selected*TrackId` slot). The simple variants tree-shake out the\n * heavier machinery (bandwidth estimator, quality selection, flush orchestration).\n *\n * Text selection has no simple variant here — it's owned by `switchTextTrack` (`./track-switching.ts`), which resolves\n * standing `userTextTrackSelection` intent against the constrained, CDN-scoped renditions.\n */\n\nimport { 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 type { Resolution } from '../../media/primitives/resolution';\nimport {\n  type AudioSelectionConfig,\n  byDescendingResolution,\n  pickAudioTrackFromTracks,\n  type TrackSelectionState,\n  tracksUnderPixelArea,\n} from '../../media/primitives/select-tracks';\nimport { isResolvedPresentation, type TrackType } from '../../media/types';\nimport { getTracksByType } from '../../media/utils/tracks';\nimport {\n  applyConstraints,\n  applyRules,\n  type CapabilityConstraintConfig,\n  excludeUnplayableTracks,\n  type SelectionRule,\n  sameCandidateSet,\n} from '../primitives/selection-rules';\nimport { AUDIO_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from '../primitives/track-types';\n\n// ============================================================================\n// Specialization helper\n//\n// `setupTrackSelection` has the same shape as a Behavior `setup` function:\n// `({ state, config }) => Reactor`. Each `selectXTrack` export below calls\n// it from inside its own `defineBehavior` setup, supplying its per-type\n// `selectedKey`, track type, default rule chain, and forwarded config. The lifecycle\n// — pick on entering 'presentation-resolved' if not already selected; clear\n// on entering 'presentation-unresolved' — is shared.\n// ============================================================================\n\ntype SelectedTrackKey = 'selectedVideoTrackId' | 'selectedAudioTrackId';\n\ntype SelectStateMap<K extends SelectedTrackKey> = {\n  presentation: ReadonlySignal<TrackSelectionState['presentation']>;\n} & { [P in K]: Signal<TrackSelectionState[P]> };\n\n/** A selection rule over this behavior's candidate tracks. */\nexport type SelectTrackRule<Config> = SelectionRule<SelectableTrack, unknown, unknown, Config | undefined>;\n\n/** What a rule here needs off a candidate: the id it may become the pick by. */\ntype SelectableTrack = { id: string };\n\ninterface TrackSelectionSetupConfig<K extends SelectedTrackKey, RuleConfig> {\n  selectedKey: K;\n  trackType: TrackType;\n  constraints: readonly SelectTrackRule<RuleConfig>[];\n  rules: readonly SelectTrackRule<RuleConfig>[];\n  ruleConfig?: RuleConfig;\n}\n\nfunction setupTrackSelection<K extends SelectedTrackKey, RuleConfig>({\n  state,\n  config: { selectedKey, trackType, constraints, rules, ruleConfig },\n}: {\n  state: SelectStateMap<K>;\n  config: TrackSelectionSetupConfig<K, RuleConfig>;\n}) {\n  const derivedStateSignal = computed(() =>\n    isResolvedPresentation(state.presentation.get())\n      ? ('presentation-resolved' as const)\n      : ('presentation-unresolved' as const)\n  );\n\n  const deps = { state, config: ruleConfig };\n\n  // The playable candidate set — the type's tracks after the hard-constraints\n  // pre-pass. A `computed` so it re-evaluates when its inputs change, which is what\n  // lets a *pinned* selection still notice it has gone unplayable: `resolve-track`\n  // relabels the whole type's container from the first resolved media playlist,\n  // long after `entry` made its pick under the fMP4 default.\n  //\n  // The `equals` gates notification on the set of track ids rather than array\n  // identity, matching `setupTrackSwitching`'s. Segment appends and live reloads\n  // both swap in a new presentation object carrying the same variants; without\n  // this the effect below would re-run on every one of them.\n  const candidateSet = computed(\n    () => {\n      const presentation = state.presentation.get();\n      if (!isResolvedPresentation(presentation)) return [];\n\n      return applyConstraints(constraints, getTracksByType(presentation, trackType), deps);\n    },\n    { equals: sameCandidateSet }\n  );\n\n  return createMachineReactor({\n    initial: 'presentation-unresolved',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'presentation-unresolved': {},\n      'presentation-resolved': {\n        // Entry: pick a default on entering presentation-resolved if none\n        // is set. External writes (user picks, ABR) that already populated\n        // the slot are left alone.\n        //\n        // The returned cleanup runs on state exit — which fires on src\n        // unload (presentation-resolved → presentation-unresolved) AND on\n        // behavior destroy (presentation-resolved → destroying →\n        // destroyed). Putting the clear here rather than as\n        // presentation-unresolved.entry is more cohesive (operation +\n        // cleanup co-located) and correctly covers destroy (destroy\n        // doesn't pass through presentation-unresolved).\n        entry: () => {\n          if (!state[selectedKey].get()) {\n            // `state.presentation.get()` is non-null inside this entry —\n            // the reactor's `'presentation-resolved'` gate is exactly\n            // `isResolvedPresentation(state.presentation.get())`, which\n            // requires a truthy Presentation.\n            //\n            // Constraints prune the unplayable, then the chain narrows and ranks;\n            // the pick is the head. An empty `rules` chain therefore selects the\n            // first candidate, which falls out of the model rather than needing a\n            // first-track code path of its own.\n            const survivors = applyRules(rules, peek(candidateSet), deps);\n            const id = survivors[0]?.id;\n\n            if (id) state[selectedKey].set(id);\n          }\n\n          return () => state[selectedKey].set(undefined);\n        },\n        effects: [\n          // Selection is `entry`'s alone — this only ever *de*selects. Keeping the\n          // pick out of a reaction is what makes this the pinned variant rather\n          // than a worse-spelled `switchVideoTrack`: nothing here re-ranks or moves\n          // the pin. It has to be a reaction all the same, because what it watches\n          // for is learned late — container and encryption come from a rendition's\n          // media playlist, which resolves after the pick was made.\n          //\n          // Deliberately does *not* report why. Whatever made the pick unplayable\n          // reported its own cause as the playlist resolved (1004 container, 4008\n          // encryption, via `reportUnsupportedTrackConditions`), which is both more\n          // specific than a verdict and already logged. The one condition no cause\n          // covers is nothing being playable at all — no rendition resolved, so\n          // none reported — which is why that alone emits here. See\n          // `internal/design/spf/features/errors.md`.\n          () => {\n            // Untracked: writing the slot below must not re-enter this reaction.\n            const selectedId = peek(state[selectedKey]);\n            if (!selectedId) return;\n\n            if (candidateSet.get().some((track) => track.id === selectedId)) return;\n\n            // Only a pick the source actually offers is this behavior's to drop. An\n            // id absent from the manifest was never selectable, and external writes\n            // are left alone — see this module's header.\n            const presentation = peek(state.presentation);\n\n            if (\n              isResolvedPresentation(presentation) &&\n              getTracksByType(presentation, trackType).some((track) => track.id === selectedId)\n            ) {\n              state[selectedKey].set(undefined);\n            }\n          },\n        ],\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Default rules\n//\n// Each variant resolves its chain as `config?.rules ?? <default>`. The whole\n// behavior config is forwarded as the rules' `config`, so a policy rule reads\n// its own options (`preferredAudioLanguage`) directly off it.\n//\n// Video's default is the *empty* chain: with no rule narrowing or reordering the\n// candidates, the head is the first track — a consequence of the model rather than\n// a first-track code path of its own.\n// ============================================================================\n\n/** Default video chain: none. The first candidate is the pick. */\nconst DEFAULT_VIDEO_RULES: readonly SelectTrackRule<SelectVideoTrackConfig>[] = [];\n\n/**\n * Default audio chain: the three-tier policy (`preferredAudioLanguage` → `DEFAULT=YES` → first) as a single narrowing\n * rule. Returning `[]` when nothing is picked lets `applyRules` fall through to the unnarrowed candidates, so the head\n * stays the first track — the same last tier the policy itself ends on.\n */\nconst preferAudioPolicy: SelectTrackRule<SelectAudioTrackConfig> = (tracks, { config }) => {\n  const id = pickAudioTrackFromTracks(tracks as readonly { id: string }[], config);\n  const pick = tracks.find((track) => track.id === id);\n\n  return pick ? [pick] : [];\n};\n\nconst DEFAULT_AUDIO_RULES: readonly SelectTrackRule<SelectAudioTrackConfig>[] = [preferAudioPolicy];\n\n/**\n * Order the candidates by resolution, largest first, with bandwidth breaking ties between renditions of identical\n * dimensions. The background-video default — that variant pins one rendition for the session, and absent a cap the\n * largest is the head.\n *\n * A ranker, so it reorders rather than narrowing: the chain's pick is the head of what it returns, which means ranking\n * never has to collapse to one track. Belongs last in a chain — a sort only reorders what survived the filters ahead of\n * it, and leaving it last is what lets `applyRules` early-bail before it runs.\n *\n * Exported because it is a _rule_, not a variant's private policy: the same one composes into `switchVideoTrack`'s\n * chain when a ranker is wanted there.\n */\nexport const preferHighestResolution: SelectTrackRule<unknown> = (tracks) => [...tracks].sort(byDescendingResolution);\n\n/** What {@link screenResolutionCap} reads off the composition state. */\ntype ScreenResolutionRuleState = {\n  screenResolution?: ReadonlySignal<Resolution | undefined>;\n};\n\n/**\n * Narrow to the renditions that fit the screen, by pixel area — the screen-size cap from\n * `internal/design/spf/features/rendition-selection-caps.md`, as a scope (soft filter) rather than a constraint: an\n * over-cap rendition is wasteful, not unplayable, so nothing here may make a source unplayable.\n *\n * Narrows only — it neither orders the survivors nor resolves the case where none survive, because `applyRules` owns\n * both. So it needs a ranker behind it to pick within the cap: `[screenResolutionCap, preferHighestResolution]` yields\n * the largest rendition that fits. Composed _last_, the pick would instead be whichever fitting rendition the manifest\n * happened to list first.\n *\n * Reading `state.screenResolution` through its signal is what subscribes a re-evaluating chain (`switchVideoTrack`) to\n * screen changes; `selectVideoTrack` pins the first answer instead, by design.\n *\n * Compares areas rather than matching a `\"1080p\"`-style tier because a tier only describes a rendition once you assume\n * its aspect ratio — the assumption that mis-measures an anamorphic ladder. See `media/dom/screen.ts`.\n *\n * Three ways the cap ends up not applying, all of them fall-through:\n *\n * - **No `screenResolution` signal at all**, because the composition omits `trackScreenResolution`. So composing the cap\n *   without its signal source is inert rather than broken.\n * - **A `screenResolution` of `undefined`**, meaning no screen to read. \"Unknown\" has to mean \"don't cap\": treating it as\n *   an area of zero would pin every source to its smallest rendition on exactly the environments we know least about.\n * - **No rendition fits**, on a screen smaller than the whole ladder. `applyRules` skips the empty result and the chain\n *   proceeds unnarrowed, so the ranker behind the cap decides — for `preferHighestResolution`, the largest rendition. A\n *   floor is the fix if that ever matters (`rendition-selection-caps.md` carries one), not a special case here.\n */\nexport const screenResolutionCap: SelectTrackRule<unknown> = (tracks, { state }) => {\n  const screenResolution = (state as ScreenResolutionRuleState | undefined)?.screenResolution?.get();\n  if (!screenResolution) return [];\n\n  return tracksUnderPixelArea(tracks, screenResolution.width * screenResolution.height);\n};\n\n// ============================================================================\n// Specialized exports — one per track type\n// ============================================================================\n\n/**\n * Config for `selectVideoTrack`. Pass `rules` to replace the selection chain, or `constraints` to replace the\n * capability pre-pass; otherwise the chain is empty and the first playable candidate is the pick.\n */\nexport interface SelectVideoTrackConfig extends CapabilityConstraintConfig {\n  constraints?: readonly SelectTrackRule<SelectVideoTrackConfig>[];\n  rules?: readonly SelectTrackRule<SelectVideoTrackConfig>[];\n}\n\n/**\n * Default video constraints: the capability pre-pass alone. No `excludeFailedCdns` — this variant's compositions run no\n * failover monitor, so `failedCdns` has no writer and the constraint would always pass through.\n */\nconst DEFAULT_VIDEO_CONSTRAINTS: readonly SelectTrackRule<SelectVideoTrackConfig>[] = [excludeUnplayableTracks];\n\n/**\n * Select a video track when a presentation loads. Clears the selection on src unload.\n *\n * This is the simple, non-ABR counterpart to `switchVideoTrack` — compose one or the other, not both (both write\n * `selectedVideoTrackId`). Composing `selectVideoTrack` alone tree-shakes out the ABR code path (bandwidth-estimator,\n * quality-selection); use it for sources without meaningful quality variants, test setups, or players that\n * intentionally pin a quality.\n *\n * @example\n *   const reactor = selectVideoTrack.setup({ state });\n */\nexport const selectVideoTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedVideoTrackId'],\n  contextKeys: [],\n  setup: ({ state, config }: { state: SelectStateMap<'selectedVideoTrackId'>; config?: SelectVideoTrackConfig }) =>\n    setupTrackSelection({\n      state,\n      config: {\n        selectedKey: VIDEO_TYPE_CONFIG.selectedKey,\n        trackType: 'video',\n        constraints: config?.constraints ?? DEFAULT_VIDEO_CONSTRAINTS,\n        rules: config?.rules ?? DEFAULT_VIDEO_RULES,\n        ruleConfig: config,\n      },\n    }),\n});\n\n/**\n * Config for `selectAudioTrack`. Pass `rules` to replace the selection chain, or `constraints` to prune candidates\n * before it runs; otherwise the default three-tier policy applies (`preferredAudioLanguage` → `DEFAULT=YES` → first).\n */\nexport interface SelectAudioTrackConfig extends AudioSelectionConfig {\n  constraints?: readonly SelectTrackRule<SelectAudioTrackConfig>[];\n  rules?: readonly SelectTrackRule<SelectAudioTrackConfig>[];\n}\n\n/**\n * Select an audio track when a presentation loads. Clears the selection on src unload.\n *\n * This is the simple, lifecycle-only counterpart to `switchAudioTrack` (in `./track-switching.ts`) — compose one or the\n * other, not both (both write `selectedAudioTrackId`). `switchAudioTrack` adds filter-reactivity\n * (`userAudioTrackSelection`) and mid-stream-flush orchestration; `selectAudioTrack` covers the default-on-load case\n * without those. Use this variant for test setups, audio-only flows that don't expose language switching, or\n * composition variants that intentionally pin a track.\n *\n * @example\n *   const reactor = selectAudioTrack.setup({ state });\n *\n * @example\n *   // Language preference, honored by the default audio policy rule\n *   const reactor = selectAudioTrack.setup({\n *     state,\n *     config: { preferredAudioLanguage: 'en' },\n *   });\n */\nexport const selectAudioTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedAudioTrackId'],\n  contextKeys: [],\n  setup: ({ state, config }: { state: SelectStateMap<'selectedAudioTrackId'>; config?: SelectAudioTrackConfig }) =>\n    setupTrackSelection({\n      state,\n      config: {\n        selectedKey: AUDIO_TYPE_CONFIG.selectedKey,\n        trackType: 'audio',\n        constraints: config?.constraints ?? [],\n        rules: config?.rules ?? DEFAULT_AUDIO_RULES,\n        ruleConfig: config,\n      },\n    }),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+FA,SAAS,oBAA4D,EACnE,OACA,QAAQ,EAAE,aAAa,WAAW,aAAa,OAAO,gBAIrD;CACD,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,IAAI,CAAC,IAC1C,0BACA,yBACP;CAEA,MAAM,OAAO;EAAE;EAAO,QAAQ;CAAW;CAYzC,MAAM,eAAe,eACb;EACJ,MAAM,eAAe,MAAM,aAAa,IAAI;EAC5C,IAAI,CAAC,uBAAuB,YAAY,GAAG,OAAO,CAAC;EAEnD,OAAO,iBAAiB,aAAa,gBAAgB,cAAc,SAAS,GAAG,IAAI;CACrF,GACA,EAAE,QAAQ,iBAAiB,CAC7B;CAEA,OAAO,qBAAqB;EAC1B,SAAS;EACT,eAAe,mBAAmB,IAAI;EACtC,QAAQ;GACN,2BAA2B,CAAC;GAC5B,yBAAyB;IAYvB,aAAa;KACX,IAAI,CAAC,MAAM,YAAY,CAAC,IAAI,GAAG;MAW7B,MAAM,KADY,WAAW,OAAO,KAAK,YAAY,GAAG,IACrC,CAAC,CAAC,EAAE,EAAE;MAEzB,IAAI,IAAI,MAAM,YAAY,CAAC,IAAI,EAAE;KACnC;KAEA,aAAa,MAAM,YAAY,CAAC,IAAI,KAAA,CAAS;IAC/C;IACA,SAAS,OAeD;KAEJ,MAAM,aAAa,KAAK,MAAM,YAAY;KAC1C,IAAI,CAAC,YAAY;KAEjB,IAAI,aAAa,IAAI,CAAC,CAAC,MAAM,UAAU,MAAM,OAAO,UAAU,GAAG;KAKjE,MAAM,eAAe,KAAK,MAAM,YAAY;KAE5C,IACE,uBAAuB,YAAY,KACnC,gBAAgB,cAAc,SAAS,CAAC,CAAC,MAAM,UAAU,MAAM,OAAO,UAAU,GAEhF,MAAM,YAAY,CAAC,IAAI,KAAA,CAAS;IAEpC,CACF;GACF;EACF;CACF,CAAC;AACH;;AAeA,MAAM,sBAA0E,CAAC;;;;;;AAOjF,MAAM,qBAA8D,QAAQ,EAAE,aAAa;CACzF,MAAM,KAAK,yBAAyB,QAAqC,MAAM;CAC/E,MAAM,OAAO,OAAO,MAAM,UAAU,MAAM,OAAO,EAAE;CAEnD,OAAO,OAAO,CAAC,IAAI,IAAI,CAAC;AAC1B;AAEA,MAAM,sBAA0E,CAAC,iBAAiB;;;;;;;;;;;;;AAclG,MAAa,2BAAqD,WAAW,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCpH,MAAa,uBAAiD,QAAQ,EAAE,YAAY;CAClF,MAAM,mBAAoB,OAAiD,kBAAkB,IAAI;CACjG,IAAI,CAAC,kBAAkB,OAAO,CAAC;CAE/B,OAAO,qBAAqB,QAAQ,iBAAiB,QAAQ,iBAAiB,MAAM;AACtF;;;;;AAmBA,MAAM,4BAAgF,CAAC,uBAAuB;;;;;;;;;;;;AAa9G,MAAa,mBAAmB,eAAe;CAC7C,WAAW,CAAC,gBAAgB,sBAAsB;CAClD,aAAa,CAAC;CACd,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,aAAa,kBAAkB;GAC/B,WAAW;GACX,aAAa,QAAQ,eAAe;GACpC,OAAO,QAAQ,SAAS;GACxB,YAAY;EACd;CACF,CAAC;AACL,CAAC;AA8B+B,eAAe;CAC7C,WAAW,CAAC,gBAAgB,sBAAsB;CAClD,aAAa,CAAC;CACd,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,aAAa,kBAAkB;GAC/B,WAAW;GACX,aAAa,QAAQ,eAAe,CAAC;GACrC,OAAO,QAAQ,SAAS;GACxB,YAAY;EACd;CACF,CAAC;AACL,CAAC"}

package/dist/dev/playback/behaviors/setup-failover-monitor.d.ts

@@ -0,0 +1,11 @@
+import "../../core/signals/primitives.js";
+import "../../index.js";
+//#region src/playback/behaviors/setup-failover-monitor.d.ts
+/** Failover policy: how long a CDN stays excluded after a failed fetch trips it. Supplied via engine config. */
+interface FailoverMonitorConfig {
+  /** How long a tripped CDN stays excluded, in milliseconds. */
+  cooldownMs: number;
+}
+//#endregion
+export { FailoverMonitorConfig };
+//# sourceMappingURL=setup-failover-monitor.d.ts.map

package/dist/dev/playback/behaviors/setup-failover-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-failover-monitor.d.ts","names":[],"sources":["../../../../src/playback/behaviors/setup-failover-monitor.ts"],"mappings":";;;;UAmBiB;;EAEf"}

package/dist/dev/playback/behaviors/setup-failover-monitor.js

@@ -0,0 +1,61 @@
+import { computed, update } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
+import { isResolvedPresentation } from "../../media/types/index.js";
+//#region src/playback/behaviors/setup-failover-monitor.ts
+/**
+* **CDN failover cooldown.** The expiry half of multi-CDN failover. Fetch sites own the _trip_: on a failed fetch they
+* add the failing CDN (origin) to the `failedCdns` state signal directly. This behavior owns the _expiry_: while a
+* presentation is resolved, it watches `failedCdns` and, for each CDN that appears, schedules a timer to remove it once
+* its cooldown lapses. `track-switching`'s `excludeFailedCdns` constraint prunes a failed CDN's tracks and the
+* active-CDN scope falls to the next one — and back, once the cooldown removes it here.
+*
+* Lifecycle is per-source: timers + `failedCdns` are cleared on exit (a new source starts with a clean slate). Policy
+* (cooldown) is engine config. This is the minimal `network-resilience` slice — a single failure trips a CDN, since
+* transient blips are the retry layer's job (it sits below the fetch sites, so anything that reaches `failedCdns` is
+* already terminal).
+*/
+const DEFAULT_FAILOVER_MONITOR_CONFIG = { cooldownMs: 3e5 };
+/**
+* Expire failed CDNs from `failedCdns` once their cooldown lapses, for the resolved source.
+*
+* @example
+*   const reactor = setupFailoverMonitor.setup({ state });
+*/
+const setupFailoverMonitor = defineBehavior({
+	stateKeys: ["presentation", "failedCdns"],
+	contextKeys: [],
+	setup: ({ state, config = {} }) => {
+		const cooldownMs = config.failover?.cooldownMs ?? DEFAULT_FAILOVER_MONITOR_CONFIG.cooldownMs;
+		const timers = /* @__PURE__ */ new Map();
+		const derivedStateSignal = computed(() => isResolvedPresentation(state.presentation.get()) ? "presentation-resolved" : "presentation-unresolved");
+		return createMachineReactor({
+			initial: "presentation-unresolved",
+			monitor: () => derivedStateSignal.get(),
+			states: {
+				"presentation-unresolved": {},
+				"presentation-resolved": {
+					entry: () => () => {
+						timers.forEach((timer) => clearTimeout(timer));
+						timers.clear();
+						state.failedCdns.set(void 0);
+					},
+					effects: [() => {
+						(state.failedCdns.get() ?? []).forEach((cdn) => {
+							if (timers.has(cdn)) return;
+							const timer = setTimeout(() => {
+								timers.delete(cdn);
+								update(state.failedCdns, (current) => current?.filter((c) => c !== cdn));
+							}, cooldownMs);
+							timers.set(cdn, timer);
+						});
+					}]
+				}
+			}
+		});
+	}
+});
+//#endregion
+export { DEFAULT_FAILOVER_MONITOR_CONFIG, setupFailoverMonitor };
+
+//# sourceMappingURL=setup-failover-monitor.js.map

package/dist/dev/playback/behaviors/setup-failover-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-failover-monitor.js","names":[],"sources":["../../../../src/playback/behaviors/setup-failover-monitor.ts"],"sourcesContent":["/**\n * **CDN failover cooldown.** The expiry half of multi-CDN failover. Fetch sites own the _trip_: on a failed fetch they\n * add the failing CDN (origin) to the `failedCdns` state signal directly. This behavior owns the _expiry_: while a\n * presentation is resolved, it watches `failedCdns` and, for each CDN that appears, schedules a timer to remove it once\n * its cooldown lapses. `track-switching`'s `excludeFailedCdns` constraint prunes a failed CDN's tracks and the\n * active-CDN scope falls to the next one — and back, once the cooldown removes it here.\n *\n * Lifecycle is per-source: timers + `failedCdns` are cleared on exit (a new source starts with a clean slate). Policy\n * (cooldown) is engine config. This is the minimal `network-resilience` slice — a single failure trips a CDN, since\n * transient blips are the retry layer's job (it sits below the fetch sites, so anything that reaches `failedCdns` is\n * already terminal).\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, type ReadonlySignal, type Signal, update } from '../../core/signals/primitives';\nimport { isResolvedPresentation, type MaybeResolvedPresentation } from '../../media/types';\n\n/** Failover policy: how long a CDN stays excluded after a failed fetch trips it. Supplied via engine config. */\nexport interface FailoverMonitorConfig {\n  /** How long a tripped CDN stays excluded, in milliseconds. */\n  cooldownMs: number;\n}\n\nexport const DEFAULT_FAILOVER_MONITOR_CONFIG: FailoverMonitorConfig = {\n  // 5 minutes — a CDN outage is an infrastructure problem that outlasts a\n  // transient blip, so re-probing it sooner mostly re-trips. Matches the\n  // prevailing prior-art default (ExoPlayer's location exclusion, hls.js's\n  // content-steering penalty box).\n  cooldownMs: 300_000,\n};\n\nexport interface SetupFailoverMonitorState {\n  presentation?: MaybeResolvedPresentation;\n  failedCdns?: string[];\n}\n\nexport interface SetupFailoverMonitorConfig {\n  /** Failover policy (cooldown); defaults to `DEFAULT_FAILOVER_MONITOR_CONFIG`. */\n  failover?: Partial<FailoverMonitorConfig>;\n}\n\n/**\n * Expire failed CDNs from `failedCdns` once their cooldown lapses, for the resolved source.\n *\n * @example\n *   const reactor = setupFailoverMonitor.setup({ state });\n */\nexport const setupFailoverMonitor = defineBehavior({\n  stateKeys: ['presentation', 'failedCdns'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config = {},\n  }: {\n    state: {\n      presentation: ReadonlySignal<SetupFailoverMonitorState['presentation']>;\n      failedCdns: Signal<SetupFailoverMonitorState['failedCdns']>;\n    };\n    config?: SetupFailoverMonitorConfig;\n  }) => {\n    const cooldownMs = config.failover?.cooldownMs ?? DEFAULT_FAILOVER_MONITOR_CONFIG.cooldownMs;\n    // CDN id → its pending cooldown-removal timer. Shared by the `effects`\n    // scheduler (adds a timer per newly-failed CDN) and the exit cleanup\n    // (clears them). Per-source: emptied on exit, so it re-enters clean.\n    const timers = new Map<string, ReturnType<typeof setTimeout>>();\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: on exit (src unload + destroy) clear the\n          // pending timers and reset `failedCdns` for the next source.\n          entry: () => () => {\n            timers.forEach((timer) => clearTimeout(timer));\n            timers.clear();\n            state.failedCdns.set(undefined);\n          },\n          effects: [\n            () => {\n              const failed = state.failedCdns.get() ?? [];\n\n              failed.forEach((cdn) => {\n                // Idempotent: a CDN already counting down keeps its original\n                // deadline (re-failing it mid-cooldown doesn't extend it).\n                if (timers.has(cdn)) return;\n\n                const timer = setTimeout(() => {\n                  timers.delete(cdn);\n                  update(state.failedCdns, (current) => current?.filter((c) => c !== cdn));\n                }, cooldownMs);\n\n                timers.set(cdn, timer);\n              });\n            },\n          ],\n        },\n      },\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;AAwBA,MAAa,kCAAyD,EAKpE,YAAY,IACd;;;;;;;AAkBA,MAAa,uBAAuB,eAAe;CACjD,WAAW,CAAC,gBAAgB,YAAY;CACxC,aAAa,CAAC;CACd,QAAQ,EACN,OACA,SAAS,CAAC,QAON;EACJ,MAAM,aAAa,OAAO,UAAU,cAAc,gCAAgC;EAIlF,MAAM,yBAAS,IAAI,IAA2C;EAC9D,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;KAGvB,mBAAmB;MACjB,OAAO,SAAS,UAAU,aAAa,KAAK,CAAC;MAC7C,OAAO,MAAM;MACb,MAAM,WAAW,IAAI,KAAA,CAAS;KAChC;KACA,SAAS,OACD;MAGJ,CAFe,MAAM,WAAW,IAAI,KAAK,CAAC,EAAA,CAEnC,SAAS,QAAQ;OAGtB,IAAI,OAAO,IAAI,GAAG,GAAG;OAErB,MAAM,QAAQ,iBAAiB;QAC7B,OAAO,OAAO,GAAG;QACjB,OAAO,MAAM,aAAa,YAAY,SAAS,QAAQ,MAAM,MAAM,GAAG,CAAC;OACzE,GAAG,UAAU;OAEb,OAAO,IAAI,KAAK,KAAK;MACvB,CAAC;KACH,CACF;IACF;GACF;EACF,CAAC;CACH;AACF,CAAC"}

package/dist/dev/playback/behaviors/sync-preload.js

@@ -0,0 +1,59 @@
+import { computed, peek } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { effect } from "../../core/signals/effect.js";
+import { isStandardPreload } from "../../media/utils/preload.js";
+//#region src/playback/behaviors/sync-preload.ts
+/**
+* **Bidirectional sync between `state.preload` and `mediaElement.preload`.**
+*
+* Two effects:
+*
+* - **Read (DOM → state)** — on `context.mediaElement` swap or `state.presentation.url` change, copies the media
+*   element's _authored_ preload into `state.preload` if it's a W3C value and `state.preload` isn't holding an extended
+*   (non-W3C) value. Author intent only: on a DOM element the `preload` IDL property reports a browser-dependent UA
+*   default even when no attribute was set (`'metadata'` Chromium, `'auto'` WebKit), so the property is consulted only
+*   when the element carries a `preload` content attribute — a UA default is never a source. When the element has no
+*   authored W3C opinion and `state.preload` is undefined, backfills from `config.defaultPreload` (default-default
+*   `'metadata'`) so `state.preload` is never undefined in steady state.
+* - **Write (state → DOM)** — on `state.preload` change or `context.mediaElement` swap, writes `state.preload` back to
+*   `mediaElement.preload` if the value is W3C.
+*
+* Extended values (e.g. `'canplay'`) written externally to `state.preload` are sticky: read won't overwrite them, write
+* won't push them to the DOM. All writes are deduped to break echo loops and avoid spurious re-triggers downstream
+* (notably `resolvePresentation`, which reads `state.preload`).
+*/
+function syncPreloadSetup({ state, context, config }) {
+	const defaultPreload = config?.defaultPreload ?? "metadata";
+	const presentationUrl = computed(() => state.presentation.get()?.url);
+	const cleanupRead = effect(() => {
+		presentationUrl.get();
+		const mediaElement = context.mediaElement.get();
+		const current = peek(state.preload);
+		if (current !== void 0 && !isStandardPreload(current)) return;
+		const authoredPreload = mediaElement && (!mediaElement.hasAttribute || mediaElement.hasAttribute("preload")) ? mediaElement.preload : void 0;
+		const target = isStandardPreload(authoredPreload) ? authoredPreload : current === void 0 ? defaultPreload : void 0;
+		if (target === void 0 || target === current) return;
+		state.preload.set(target);
+	});
+	const cleanupWrite = effect(() => {
+		const next = state.preload.get();
+		const mediaElement = context.mediaElement.get();
+		if (!mediaElement) return;
+		if (!isStandardPreload(next)) return;
+		if (mediaElement.preload === next) return;
+		mediaElement.preload = next;
+	});
+	return () => {
+		cleanupRead();
+		cleanupWrite();
+	};
+}
+const syncPreload = defineBehavior({
+	stateKeys: ["preload", "presentation"],
+	contextKeys: ["mediaElement"],
+	setup: syncPreloadSetup
+});
+//#endregion
+export { syncPreload };
+
+//# sourceMappingURL=sync-preload.js.map

package/dist/dev/playback/behaviors/sync-preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-preload.js","names":[],"sources":["../../../../src/playback/behaviors/sync-preload.ts"],"sourcesContent":["/**\n * **Bidirectional sync between `state.preload` and `mediaElement.preload`.**\n *\n * Two effects:\n *\n * - **Read (DOM → state)** — on `context.mediaElement` swap or `state.presentation.url` change, copies the media\n *   element's _authored_ preload into `state.preload` if it's a W3C value and `state.preload` isn't holding an extended\n *   (non-W3C) value. Author intent only: on a DOM element the `preload` IDL property reports a browser-dependent UA\n *   default even when no attribute was set (`'metadata'` Chromium, `'auto'` WebKit), so the property is consulted only\n *   when the element carries a `preload` content attribute — a UA default is never a source. When the element has no\n *   authored W3C opinion and `state.preload` is undefined, backfills from `config.defaultPreload` (default-default\n *   `'metadata'`) so `state.preload` is never undefined in steady state.\n * - **Write (state → DOM)** — on `state.preload` change or `context.mediaElement` swap, writes `state.preload` back to\n *   `mediaElement.preload` if the value is W3C.\n *\n * Extended values (e.g. `'canplay'`) written externally to `state.preload` are sticky: read won't overwrite them, write\n * won't push them to the DOM. All writes are deduped to break echo loops and avoid spurious re-triggers downstream\n * (notably `resolvePresentation`, which reads `state.preload`).\n */\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport { computed, peek, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport type { MediaElementLike } from '../../media/types';\nimport { DEFAULT_PRELOAD, isStandardPreload, type StandardPreload } from '../../media/utils/preload';\nimport type { PresentationState } from './resolve-presentation';\n\nexport interface SyncPreloadConfig {\n  /**\n   * Backfill applied to `state.preload` when neither the host element nor external code has supplied a W3C value.\n   * Defaults to `'metadata'`.\n   */\n  defaultPreload?: StandardPreload;\n}\n\ntype State = Pick<PresentationState, 'preload' | 'presentation'>;\n\nfunction syncPreloadSetup({\n  state,\n  context,\n  config,\n}: {\n  state: {\n    preload: Signal<State['preload']>;\n    presentation: ReadonlySignal<State['presentation']>;\n  };\n  context: { mediaElement: ReadonlySignal<MediaElementLike | undefined> };\n  config?: SyncPreloadConfig;\n}): () => void {\n  const defaultPreload: StandardPreload = config?.defaultPreload ?? DEFAULT_PRELOAD;\n  const presentationUrl = computed(() => state.presentation.get()?.url);\n\n  // Read must be registered before write: effects re-run in registration\n  // order (see core/signals/effect.ts → runPending). On a shared-signal\n  // change (e.g. `context.mediaElement` swap), read fires first and gets to\n  // claim `state.preload`, giving \"most-recent-wins on attach\" — a freshly\n  // mounted <video> with a W3C `preload` attribute overrides whatever\n  // `state.preload` previously held. Swap the order or split these into\n  // separate behaviors and the \"most-recent-wins on attach\" test pins the\n  // regression.\n  const cleanupRead = effect(() => {\n    presentationUrl.get();\n    const mediaElement = context.mediaElement.get();\n    // peek (not get): external writes to state.preload shouldn't re-trigger\n    // this effect, only mediaElement / presentation-url changes should.\n    const current = peek(state.preload);\n    // Extended sticky: leave non-W3C values (e.g. 'canplay') alone.\n    if (current !== undefined && !isStandardPreload(current)) return;\n\n    // Author intent only: a DOM element's `preload` property reports a UA\n    // default when no attribute was authored (the shadow <video> under an SPF\n    // Media never carries one), so gate the property read on attribute\n    // presence. An element without attribute reflection has no UA defaults —\n    // its property is authored by construction.\n    const authoredPreload =\n      mediaElement && (!mediaElement.hasAttribute || mediaElement.hasAttribute('preload'))\n        ? mediaElement.preload\n        : undefined;\n\n    const target: StandardPreload | undefined = isStandardPreload(authoredPreload)\n      ? authoredPreload\n      : current === undefined\n        ? defaultPreload\n        : undefined;\n    if (target === undefined || target === current) return;\n\n    state.preload.set(target);\n  });\n\n  const cleanupWrite = effect(() => {\n    const next = state.preload.get();\n    const mediaElement = context.mediaElement.get();\n    if (!mediaElement) return;\n\n    if (!isStandardPreload(next)) return;\n\n    if (mediaElement.preload === next) return;\n\n    mediaElement.preload = next;\n  });\n\n  return () => {\n    cleanupRead();\n    cleanupWrite();\n  };\n}\n\nexport const syncPreload = defineBehavior({\n  stateKeys: ['preload', 'presentation'],\n  contextKeys: ['mediaElement'],\n  setup: syncPreloadSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAS,iBAAiB,EACxB,OACA,SACA,UAQa;CACb,MAAM,iBAAkC,QAAQ,kBAAA;CAChD,MAAM,kBAAkB,eAAe,MAAM,aAAa,IAAI,CAAC,EAAE,GAAG;CAUpE,MAAM,cAAc,aAAa;EAC/B,gBAAgB,IAAI;EACpB,MAAM,eAAe,QAAQ,aAAa,IAAI;EAG9C,MAAM,UAAU,KAAK,MAAM,OAAO;EAElC,IAAI,YAAY,KAAA,KAAa,CAAC,kBAAkB,OAAO,GAAG;EAO1D,MAAM,kBACJ,iBAAiB,CAAC,aAAa,gBAAgB,aAAa,aAAa,SAAS,KAC9E,aAAa,UACb,KAAA;EAEN,MAAM,SAAsC,kBAAkB,eAAe,IACzE,kBACA,YAAY,KAAA,IACV,iBACA,KAAA;EACN,IAAI,WAAW,KAAA,KAAa,WAAW,SAAS;EAEhD,MAAM,QAAQ,IAAI,MAAM;CAC1B,CAAC;CAED,MAAM,eAAe,aAAa;EAChC,MAAM,OAAO,MAAM,QAAQ,IAAI;EAC/B,MAAM,eAAe,QAAQ,aAAa,IAAI;EAC9C,IAAI,CAAC,cAAc;EAEnB,IAAI,CAAC,kBAAkB,IAAI,GAAG;EAE9B,IAAI,aAAa,YAAY,MAAM;EAEnC,aAAa,UAAU;CACzB,CAAC;CAED,aAAa;EACX,YAAY;EACZ,aAAa;CACf;AACF;AAEA,MAAa,cAAc,eAAe;CACxC,WAAW,CAAC,WAAW,cAAc;CACrC,aAAa,CAAC,cAAc;CAC5B,OAAO;AACT,CAAC"}

package/dist/dev/playback/behaviors/track-switching.d.ts

@@ -0,0 +1,110 @@
+import { MaybeResolvedPresentation } from "../../media/types/index.js";
+import { ReadonlySignal, Signal } from "../../core/signals/primitives.js";
+import { AnySlotMap } from "../../core/composition/create-composition.js";
+import "../../index.js";
+import { CodecPreferenceConfig, DEFAULT_PREFERRED_CODECS, SelectionRule, SelectionRuleDeps, preferCodecFamilies } from "../primitives/selection-rules.js";
+import "./collect-errors.js";
+//#region src/playback/behaviors/track-switching.d.ts
+/**
+ * The slots `setupTrackSwitching` itself owns: the `presentation` gate it reads and the per-type `selected*TrackId` it
+ * writes. Rule-only inputs are deliberately absent — `user*TrackSelection` and `bandwidthState` belong to whoever
+ * materializes them (the embedder via `shareSignals`, the buffer-actor sampler), and each rule declares the signal it
+ * consults as an optional slot on its own deps map, so the behavior never assumes a rule's signal exists.
+ */
+interface TrackSwitchingState {
+  presentation?: MaybeResolvedPresentation;
+  selectedVideoTrackId?: string;
+  selectedAudioTrackId?: string;
+  selectedTextTrackId?: string;
+}
+/**
+ * Minimum candidate-track shape consumed by the helper and its rules: an `id` (the pick), a `url` (the active-CDN scope
+ * derives the CDN from it), an optional `bandwidth` (the ranker's throughput sort), and optional `width`/`height` (the
+ * ranker's equal-bitrate tie-break — absent on audio, so audio candidates area-compare equal). Every
+ * resolved/partially-resolved video track carries them all; audio tracks omit the dimensions.
+ */
+type SwitchableTrack = {
+  id: string;
+  url: string;
+  bandwidth?: number;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  codecs?: string[];
+};
+/**
+ * Map the rule chain's surviving candidates to the final selection id, or `undefined` for a deliberate no-selection.
+ * Defaults to the chain head (`selectChainHead`) — the always-pick contract video and audio rely on (`applyRules`
+ * guarantees a non-empty result, so the head is always there). A variant whose selection is legitimately optional
+ * (text: opt-in captions, explicit off) supplies its own picker that may return `undefined`; the helper writes that
+ * straight through to the slot, clearing it.
+ */
+type ResolveSelection<T extends SwitchableTrack, State = unknown, Context = unknown, Config = unknown> = (candidates: readonly T[], deps: SelectionRuleDeps<State, Context, Config>) => string | undefined;
+type SelectionKey = 'selectedVideoTrackId' | 'selectedAudioTrackId' | 'selectedTextTrackId';
+type TrackSwitchingStateMap<S extends SelectionKey> = {
+  presentation: ReadonlySignal<TrackSwitchingState['presentation']>;
+} & { [P in S]: Signal<TrackSwitchingState[P]>; };
+/**
+ * Config `setupTrackSwitching` itself reads — its own wiring: which selection slot to write and clear (`selectionKey`),
+ * how to enumerate candidate tracks (`getTracks`), the optional **hard-constraints pre-pass** (`constraints`, applied
+ * before the chain to prune the unplayable), and the **rule chain** to run (`rules`), and how to map the chain's
+ * survivors to the final pick (`resolveSelection`, defaulting to the chain head). Rule-/constraint-specific config is
+ * deliberately absent — each declares the fields it reads as _optional_ on its own config view (`UserSelectionConfig`,
+ * `BandwidthRankerConfig`), so the behavior never enumerates them. The variant builds the concrete config as this base
+ * plus whatever its chain consults; it flows through untouched as the `C` type param on `setupTrackSwitching`.
+ */
+interface TrackSwitchingConfig<S extends SelectionKey, T extends SwitchableTrack> {
+  selectionKey: S;
+  getTracks: (presentation: MaybeResolvedPresentation) => readonly T[];
+  constraints?: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];
+  rules: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];
+  /**
+   * Map the chain's surviving candidates to the final selection id. Optional — absent means the chain head
+   * (`selectChainHead`), the always-pick path video and audio use. A variant with optional selection (text) supplies
+   * one that may return `undefined`.
+   */
+  resolveSelection?: ResolveSelection<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>;
+  /**
+   * SVTA code to report when this type _has_ tracks but the constraints pruned every one. Per-variant because the
+   * condition isn't universally an error: video and audio supply {@link SVTA_NO_SUPPORTED_VIDEO_TRACK} /
+   * {@link SVTA_NO_SUPPORTED_AUDIO_TRACK}, while text supplies none — an unavailable subtitle track is a legitimate
+   * outcome, not a playback failure. Absent → the selection still clears, nothing is reported.
+   */
+  noSupportedTrackCode?: number;
+}
+/**
+ * Codec-family sticky constraint — a _hard_ filter for the constraints pre-pass, shared by video and audio, and the
+ * reason the re-evaluating variants can run ABR over a mixed-codec source at all: SPF implements no
+ * `SourceBuffer.changeType()`, so once segments of the selected track's codec families are what a buffer was created
+ * for, a pick outside them could never play — constraint semantics ("can't play here"), not preference. Removes the
+ * candidates whose codec-family set doesn't _equal_ the selected track's (set-equality so a muxed `hvc1,mp4a` rendition
+ * can't pass as a match for `avc1,mp4a` on its audio half). Purely relational: the lock _is_ the current selection's
+ * families, no state of its own. Pruned pre-pass, a cross-family user selection mid-stream never reaches the user
+ * filter, which falls through unhonored instead of killing playback. Before any selection exists (the initial pick) it
+ * removes nothing, which is what leaves the initial family choice to the rule chain (user intent, then
+ * `preferCodecFamilies`).
+ *
+ * The selected track's families come from the _presentation's_ track list, not the already-pruned candidates: a CDN
+ * entering cooldown may prune the current track itself while same-family renditions survive on another host, and the
+ * lock must carry over to them. Removes nothing when: no selection yet, a selection the presentation no longer carries,
+ * or a selected track without codecs (then no candidate's compatibility is decidable — same inertness as
+ * `preferCodecFamilies` on a codec-less ladder).
+ *
+ * When the selected family genuinely vanishes from the playable set, the pre-pass empties: the behavior reports the
+ * type's no-supported-track code and clears the selection — an explicable stop instead of a cross-family append
+ * surfacing as an opaque decode error. Clearing also releases the lock (it keys on the live selection), so a following
+ * pick may land in the surviving family on freshly-created buffer actors; whether the append layer survives that
+ * rebuild is the changeType gap, out of this constraint's hands. If `changeType` support ever lands, this constraint is
+ * what relaxes.
+ *
+ * Reading the selection here — a slot the picking effect itself writes, from inside the candidate-set computed — is
+ * safe only because the effect scheduler revalidates an effect's sources after each run; see `core/signals/effect.ts`
+ * (`revalidateSources`) for the lost-wakeup it prevents.
+ *
+ * Composed only into the re-evaluating `switch*` variants: the pinned `selectVideoTrack` (background compositions)
+ * evaluates once and never re-picks, so it's immune by construction.
+ */
+declare function stickToSelectedCodecs<S extends SelectionKey, T extends SwitchableTrack>(tracks: readonly T[], { state, config }: SelectionRuleDeps<TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>): readonly T[];
+//#endregion
+export { ResolveSelection, TrackSwitchingState, TrackSwitchingStateMap, stickToSelectedCodecs };
+//# sourceMappingURL=track-switching.d.ts.map

package/dist/dev/playback/behaviors/track-switching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-switching.d.ts","names":[],"sources":["../../../../src/playback/behaviors/track-switching.ts"],"mappings":";;;;;;;;;;;;;UAyGiB;EACf,eAAe;EACf;EACA;EACA;;;;;;;;KAyFG;EACH;EACA;EACA;EACA;EACA;EAIA;EACA;;;;;;;;;KAUU,iBAAiB,UAAU,iBAAiB,iBAAiB,mBAAmB,qBAC1F,qBAAqB,KACrB,MAAM,kBAAkB,OAAO,SAAS;KAGrC;KAeO,uBAAuB,UAAU;EAC3C,cAAc,eAAe;OACxB,KAAK,IAAI,OAAO,oBAAoB;;;;;;;;;;UAkBjC,qBAAqB,UAAU,cAAc,UAAU;EAC/D,cAAc;EACd,YAAY,cAAc,uCAAuC;EACjE,uBAAuB,cAAc,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;EACvG,gBAAgB,cAAc,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;;;;;;EAMhG,mBAAmB,iBAAiB,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;;;;;;;EAOtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwOc,sBAAsB,UAAU,cAAc,UAAU,iBACtE,iBAAiB,OACf,OAAO,UAAU,kBAAkB,uBAAuB,IAAI,YAAY,qBAAqB,GAAG,eAC1F"}