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

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

@@ -2,34 +2,41 @@ import { computed } 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 { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from "./track-types.js";
-import { pickFirstTrackId, pickTextTrack } from "../../media/primitives/select-tracks.js";
+import { AUDIO_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from "../primitives/track-types.js";
+import { pickAudioTrack, pickFirstTrackId } from "../../media/primitives/select-tracks.js";
 //#region src/playback/behaviors/select-tracks.ts
 /**
-* **Default audio/text track selection on src load / unselect on src unload.**
-* When a presentation is resolved, sets `selectedAudioTrackId` /
-* `selectedTextTrackId` to a per-type-picker default 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.
+* **Default audio/video track selection on src load / unselect on src unload.**
+* When a presentation is resolved, sets `selectedVideoTrackId` /
+* `selectedAudioTrackId` to a per-type-picker default 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: each transition fires its work once. Does not police
-* the selection between transitions; external writes (user picks) are left
-* alone.
+* Lifecycle-driven: each transition fires its work once. Does not police the
+* selection between transitions; external writes (user picks, ABR, programmatic
+* filter-driven re-picks) are left alone.
 *
 * Picker is config-driven: each per-type export wires a sensible default
-* (`pickFirstTrackId` for audio, `pickTextTrack` for text) and the caller
-* can supply their own via `config.picker` for custom selection logic
-* (language preferences, default-track handling, etc.). The behavior's
-* `config` is forwarded to the picker as its second argument, so options
-* like `preferredAudioLanguage` / `preferredSubtitleLanguage` reach the
-* picker without an intermediate wrapping layer.
+* (`pickAudioTrack` for audio — three-tier language-aware; `pickFirstTrackId`
+* for video) and the caller can supply their own via `config.picker` for custom
+* selection logic. The behavior's `config` is forwarded to the picker as its
+* second argument, so options like `preferredAudioLanguage` reach the picker
+* without an intermediate wrapping layer.
 *
 * Compose `selectVideoTrack` for the simple "pick a default video track"
-* behavior, or `switchVideoQuality` (`./quality-switching.ts`) for the
-* ABR-driven variant — they're alternatives, not stackable (both write
-* `selectedVideoTrackId`). The simple variant tree-shakes out the
-* ABR machinery (bandwidth-estimator, quality-selection algorithms).
+* 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, picker, pickerConfig } }) {
 	const derivedStateSignal = computed(() => isResolvedPresentation(state.presentation.get()) ? "presentation-resolved" : "presentation-unresolved");
@@ -50,83 +57,45 @@ function setupTrackSelection({ state, config: { selectedKey, picker, pickerConfi
 }
 /** Default video picker: first track in the video selection set. */
 const defaultVideoPicker = (presentation) => pickFirstTrackId(presentation, "video");
-const VIDEO_TRACK_SELECTION_CONFIG = {
-	...VIDEO_TYPE_CONFIG,
-	picker: defaultVideoPicker
-};
-/** Default audio picker: first track in the audio selection set. */
-const defaultAudioPicker = (presentation) => pickFirstTrackId(presentation, "audio");
-const AUDIO_TRACK_SELECTION_CONFIG = {
-	...AUDIO_TYPE_CONFIG,
-	picker: defaultAudioPicker
-};
-const TEXT_TRACK_SELECTION_CONFIG = {
-	...TEXT_TYPE_CONFIG,
-	picker: pickTextTrack
-};
-defineBehavior({
-	stateKeys: ["presentation", "selectedVideoTrackId"],
-	contextKeys: [],
-	setup: ({ state, config }) => setupTrackSelection({
-		state,
-		config: {
-			...VIDEO_TRACK_SELECTION_CONFIG,
-			picker: config?.picker ?? VIDEO_TRACK_SELECTION_CONFIG.picker,
-			pickerConfig: config
-		}
-	})
-});
 /**
-* Select an audio track when a presentation loads. Clears the selection
-* on src unload.
+* Select a video track when a presentation loads. Clears the selection on
+* src unload.
 *
-* @example
-* const reactor = selectAudioTrack.setup({ state });
+* 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
-* // Custom picker with language preference
-* const reactor = selectAudioTrack.setup({
-*   state,
-*   config: { preferredAudioLanguage: 'en', picker: myLanguageAwarePicker },
-* });
+* const reactor = selectVideoTrack.setup({ state });
 */
-const selectAudioTrack = defineBehavior({
-	stateKeys: ["presentation", "selectedAudioTrackId"],
+const selectVideoTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedVideoTrackId"],
 	contextKeys: [],
 	setup: ({ state, config }) => setupTrackSelection({
 		state,
 		config: {
-			...AUDIO_TRACK_SELECTION_CONFIG,
-			picker: config?.picker ?? AUDIO_TRACK_SELECTION_CONFIG.picker,
+			selectedKey: VIDEO_TYPE_CONFIG.selectedKey,
+			picker: config?.picker ?? defaultVideoPicker,
 			pickerConfig: config
 		}
 	})
 });
-/**
-* Select a text track based on user preferences (preferred language,
-* default-track auto-select, forced-track filtering). Clears the selection
-* on src unload.
-*
-* Unlike audio selection, the default text picker returns `undefined` when
-* no preference matches, leaving the selection unset — text-track
-* selection is user opt-in.
-*
-* @example
-* const reactor = selectTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });
-*/
-const selectTextTrack = defineBehavior({
-	stateKeys: ["presentation", "selectedTextTrackId"],
+defineBehavior({
+	stateKeys: ["presentation", "selectedAudioTrackId"],
 	contextKeys: [],
 	setup: ({ state, config }) => setupTrackSelection({
 		state,
 		config: {
-			...TEXT_TRACK_SELECTION_CONFIG,
-			picker: config?.picker ?? TEXT_TRACK_SELECTION_CONFIG.picker,
+			selectedKey: AUDIO_TYPE_CONFIG.selectedKey,
+			picker: config?.picker ?? pickAudioTrack,
 			pickerConfig: config
 		}
 	})
 });
 //#endregion
-export { selectAudioTrack, selectTextTrack };
+export { selectVideoTrack };
 
 //# sourceMappingURL=select-tracks.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/playback/behaviors/select-tracks.ts"],"sourcesContent":["/**\n * **Default audio/text track selection on src load / unselect on src unload.**\n * When a presentation is resolved, sets `selectedAudioTrackId` /\n * `selectedTextTrackId` to a per-type-picker default if no selection already\n * exists. When the presentation is unset/reset (transitions back to\n * unresolved), clears the selection so a stale id from the previous source\n * doesn't persist.\n *\n * Lifecycle-driven: each transition fires its work once. Does not police\n * the selection between transitions; external writes (user picks) are left\n * alone.\n *\n * Picker is config-driven: each per-type export wires a sensible default\n * (`pickFirstTrackId` for audio, `pickTextTrack` for text) and the caller\n * can supply their own via `config.picker` for custom selection logic\n * (language preferences, default-track handling, etc.). The behavior's\n * `config` is forwarded to the picker as its second argument, so options\n * like `preferredAudioLanguage` / `preferredSubtitleLanguage` reach the\n * picker without an intermediate wrapping layer.\n *\n * Compose `selectVideoTrack` for the simple \"pick a default video track\"\n * behavior, or `switchVideoQuality` (`./quality-switching.ts`) for the\n * ABR-driven variant — they're alternatives, not stackable (both write\n * `selectedVideoTrackId`). The simple variant tree-shakes out the\n * ABR machinery (bandwidth-estimator, quality-selection algorithms).\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport {\n  type AudioSelectionConfig,\n  pickFirstTrackId,\n  pickTextTrack,\n  type TextSelectionConfig,\n  type TrackPicker,\n  type TrackSelectionState,\n  type VideoSelectionConfig,\n} from '../../media/primitives/select-tracks';\nimport { isResolvedPresentation } from '../../media/types';\nimport { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from './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`, default picker, and forwarded picker 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' | 'selectedTextTrackId';\n\ntype SelectStateMap<K extends SelectedTrackKey> = {\n  presentation: ReadonlySignal<TrackSelectionState['presentation']>;\n} & { [P in K]: Signal<TrackSelectionState[P]> };\n\ninterface TrackSelectionSetupConfig<K extends SelectedTrackKey, PickerConfig> {\n  selectedKey: K;\n  picker: TrackPicker<PickerConfig>;\n  pickerConfig?: PickerConfig;\n}\n\nfunction setupTrackSelection<K extends SelectedTrackKey, PickerConfig>({\n  state,\n  config: { selectedKey, picker, pickerConfig },\n}: {\n  state: SelectStateMap<K>;\n  config: TrackSelectionSetupConfig<K, PickerConfig>;\n}) {\n  const derivedStateSignal = computed(() =>\n    isResolvedPresentation(state.presentation.get())\n      ? ('presentation-resolved' as const)\n      : ('presentation-unresolved' as const)\n  );\n\n  return createMachineReactor({\n    initial: 'presentation-unresolved',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'presentation-unresolved': {},\n      'presentation-resolved': {\n        // 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            const id = picker(state.presentation.get()!, pickerConfig);\n            if (id) state[selectedKey].set(id);\n          }\n          return () => state[selectedKey].set(undefined);\n        },\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Per-helper-per-type configs — defaults that variants spread engine config over\n//\n// The engine-facing config carries `picker?` (optional override) plus\n// fields the default picker consults (preferred language, etc.). The\n// variant resolves the final picker (engine override or default) and\n// forwards the whole engine config as `pickerConfig` so rich pickers can\n// read their options.\n// ============================================================================\n\n/** Default video picker: first track in the video selection set. */\nconst defaultVideoPicker: TrackPicker = (presentation) => pickFirstTrackId(presentation, 'video');\n\nconst VIDEO_TRACK_SELECTION_CONFIG = {\n  ...VIDEO_TYPE_CONFIG,\n  picker: defaultVideoPicker,\n} as const;\n\n/** Default audio picker: first track in the audio selection set. */\nconst defaultAudioPicker: TrackPicker = (presentation) => pickFirstTrackId(presentation, 'audio');\n\nconst AUDIO_TRACK_SELECTION_CONFIG = {\n  ...AUDIO_TYPE_CONFIG,\n  picker: defaultAudioPicker,\n} as const;\n\nconst TEXT_TRACK_SELECTION_CONFIG = {\n  ...TEXT_TYPE_CONFIG,\n  picker: pickTextTrack,\n} as const;\n\n// ============================================================================\n// Specialized exports — one per track type\n// ============================================================================\n\n/**\n * Config for `selectVideoTrack`. Pass `picker` to fully override selection\n * logic; otherwise the default `pickFirstTrackId` is used.\n */\nexport interface SelectVideoTrackConfig extends Omit<VideoSelectionConfig, 'type'> {\n  picker?: TrackPicker<SelectVideoTrackConfig>;\n}\n\n/**\n * Select a video track when a presentation loads. Clears the selection on\n * src unload.\n *\n * This is the simple, non-ABR counterpart to `switchVideoQuality` — compose\n * one or the other, not both (both write `selectedVideoTrackId`). Composing\n * `selectVideoTrack` alone tree-shakes out the ABR code path\n * (bandwidth-estimator, quality-selection); use it for sources without\n * meaningful quality variants, test setups, or players that intentionally\n * 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        ...VIDEO_TRACK_SELECTION_CONFIG,\n        picker: config?.picker ?? VIDEO_TRACK_SELECTION_CONFIG.picker,\n        pickerConfig: config,\n      },\n    }),\n});\n\n/**\n * Config for `selectAudioTrack`. Pass `picker` to fully override selection\n * logic; otherwise the default `pickFirstTrackId` is used (which ignores\n * the other fields — they reach the picker as its second arg for callers\n * who supply a richer picker, like a language-aware one).\n */\nexport interface SelectAudioTrackConfig extends Omit<AudioSelectionConfig, 'type'> {\n  picker?: TrackPicker<SelectAudioTrackConfig>;\n}\n\n/**\n * Select an audio track when a presentation loads. Clears the selection\n * on src unload.\n *\n * @example\n * const reactor = selectAudioTrack.setup({ state });\n *\n * @example\n * // Custom picker with language preference\n * const reactor = selectAudioTrack.setup({\n *   state,\n *   config: { preferredAudioLanguage: 'en', picker: myLanguageAwarePicker },\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        ...AUDIO_TRACK_SELECTION_CONFIG,\n        picker: config?.picker ?? AUDIO_TRACK_SELECTION_CONFIG.picker,\n        pickerConfig: config,\n      },\n    }),\n});\n\n/**\n * Config for `selectTextTrack`. Pass `picker` to fully override selection\n * logic; otherwise the default `pickTextTrack` is used, which honors the\n * other fields.\n */\nexport interface SelectTextTrackConfig extends TextSelectionConfig {\n  picker?: TrackPicker<SelectTextTrackConfig>;\n}\n\n/**\n * Select a text track based on user preferences (preferred language,\n * default-track auto-select, forced-track filtering). Clears the selection\n * on src unload.\n *\n * Unlike audio selection, the default text picker returns `undefined` when\n * no preference matches, leaving the selection unset — text-track\n * selection is user opt-in.\n *\n * @example\n * const reactor = selectTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });\n */\nexport const selectTextTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedTextTrackId'],\n  contextKeys: [],\n  setup: ({ state, config }: { state: SelectStateMap<'selectedTextTrackId'>; config?: SelectTextTrackConfig }) =>\n    setupTrackSelection({\n      state,\n      config: {\n        ...TEXT_TRACK_SELECTION_CONFIG,\n        picker: config?.picker ?? TEXT_TRACK_SELECTION_CONFIG.picker,\n        pickerConfig: config,\n      },\n    }),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAS,oBAA8D,EACrE,OACA,QAAQ,EAAE,aAAa,QAAQ,kBAI9B;CACD,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,KAAK,CAAC,GAC3C,0BACA,0BACN;AAED,QAAO,qBAAqB;EAC1B,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,2BAA2B,EAAE;GAC7B,yBAAyB,EAYvB,aAAa;AACX,QAAI,CAAC,MAAM,aAAa,KAAK,EAAE;KAK7B,MAAM,KAAK,OAAO,MAAM,aAAa,KAAK,EAAG,aAAa;AAC1D,SAAI,GAAI,OAAM,aAAa,IAAI,GAAG;;AAEpC,iBAAa,MAAM,aAAa,IAAI,KAAA,EAAU;MAEjD;GACF;EACF,CAAC;;;AAcJ,MAAM,sBAAmC,iBAAiB,iBAAiB,cAAc,QAAQ;AAEjG,MAAM,+BAA+B;CACnC,GAAG;CACH,QAAQ;CACT;;AAGD,MAAM,sBAAmC,iBAAiB,iBAAiB,cAAc,QAAQ;AAEjG,MAAM,+BAA+B;CACnC,GAAG;CACH,QAAQ;CACT;AAED,MAAM,8BAA8B;CAClC,GAAG;CACH,QAAQ;CACT;AA4B+B,eAAe;CAC7C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,GAAG;GACH,QAAQ,QAAQ,UAAU,6BAA6B;GACvD,cAAc;GACf;EACF,CAAC;CACL,CAAC;;;;;;;;;;;;;;;AA0BF,MAAa,mBAAmB,eAAe;CAC7C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,GAAG;GACH,QAAQ,QAAQ,UAAU,6BAA6B;GACvD,cAAc;GACf;EACF,CAAC;CACL,CAAC;;;;;;;;;;;;;AAuBF,MAAa,kBAAkB,eAAe;CAC5C,WAAW,CAAC,gBAAgB,sBAAsB;CAClD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,GAAG;GACH,QAAQ,QAAQ,UAAU,4BAA4B;GACtD,cAAc;GACf;EACF,CAAC;CACL,CAAC"}
+{"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.**\n * When a presentation is resolved, sets `selectedVideoTrackId` /\n * `selectedAudioTrackId` to a per-type-picker default if no selection already\n * exists. When the presentation is unset/reset (transitions back to unresolved),\n * clears the selection so a stale id from the previous source doesn't persist.\n *\n * Lifecycle-driven: each transition fires its work once. Does not police the\n * selection between transitions; external writes (user picks, ABR, programmatic\n * filter-driven re-picks) are left alone.\n *\n * Picker is config-driven: each per-type export wires a sensible default\n * (`pickAudioTrack` for audio — three-tier language-aware; `pickFirstTrackId`\n * for video) and the caller can supply their own via `config.picker` for custom\n * selection logic. The behavior's `config` is forwarded to the picker as its\n * second argument, so options like `preferredAudioLanguage` reach the picker\n * without an intermediate wrapping layer.\n *\n * Compose `selectVideoTrack` for the simple \"pick a default video track\"\n * behavior, or `switchVideoTrack` (`./track-switching.ts`) for the\n * ABR-driven variant. Compose `selectAudioTrack` for the simple default\n * pick, or `switchAudioTrack` (`./track-switching.ts`) for the\n * filter-reactive + mid-stream-flush slot-owner variant — when audio-abr\n * lands, `switchAudioTrack` extends into `switchAudioQuality`. Compose\n * only one per type — they're alternatives, not stackable (each writes\n * the same `selected*TrackId` slot). The simple variants tree-shake out\n * the heavier machinery (bandwidth estimator, quality selection, flush\n * orchestration).\n *\n * Text selection has no simple variant here — it's owned by `switchTextTrack`\n * (`./track-switching.ts`), which resolves standing `userTextTrackSelection`\n * 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, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport {\n  type AudioSelectionConfig,\n  pickAudioTrack,\n  pickFirstTrackId,\n  type TrackPicker,\n  type TrackSelectionState,\n  type VideoSelectionConfig,\n} from '../../media/primitives/select-tracks';\nimport { isResolvedPresentation } from '../../media/types';\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`, default picker, and forwarded picker 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\ninterface TrackSelectionSetupConfig<K extends SelectedTrackKey, PickerConfig> {\n  selectedKey: K;\n  picker: TrackPicker<PickerConfig>;\n  pickerConfig?: PickerConfig;\n}\n\nfunction setupTrackSelection<K extends SelectedTrackKey, PickerConfig>({\n  state,\n  config: { selectedKey, picker, pickerConfig },\n}: {\n  state: SelectStateMap<K>;\n  config: TrackSelectionSetupConfig<K, PickerConfig>;\n}) {\n  const derivedStateSignal = computed(() =>\n    isResolvedPresentation(state.presentation.get())\n      ? ('presentation-resolved' as const)\n      : ('presentation-unresolved' as const)\n  );\n\n  return createMachineReactor({\n    initial: 'presentation-unresolved',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'presentation-unresolved': {},\n      'presentation-resolved': {\n        // 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            const id = picker(state.presentation.get()!, pickerConfig);\n            if (id) state[selectedKey].set(id);\n          }\n          return () => state[selectedKey].set(undefined);\n        },\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Default pickers\n//\n// Each variant resolves its picker as `config?.picker ?? <default>` and\n// forwards the whole engine config as `pickerConfig`, so a rich picker\n// (`pickAudioTrack`) reads its options directly. Audio uses its primitive\n// picker as-is; video adapts `pickFirstTrackId` (positional `type` arg) into\n// the `TrackPicker` shape.\n// ============================================================================\n\n/** Default video picker: first track in the video selection set. */\nconst defaultVideoPicker: TrackPicker = (presentation) => pickFirstTrackId(presentation, 'video');\n\n// ============================================================================\n// Specialized exports — one per track type\n// ============================================================================\n\n/**\n * Config for `selectVideoTrack`. Pass `picker` to fully override selection\n * logic; otherwise the default `pickFirstTrackId` is used.\n */\nexport interface SelectVideoTrackConfig extends VideoSelectionConfig {\n  picker?: TrackPicker<SelectVideoTrackConfig>;\n}\n\n/**\n * Select a video track when a presentation loads. Clears the selection on\n * src unload.\n *\n * This is the simple, non-ABR counterpart to `switchVideoTrack` — compose\n * one or the other, not both (both write `selectedVideoTrackId`). Composing\n * `selectVideoTrack` alone tree-shakes out the ABR code path\n * (bandwidth-estimator, quality-selection); use it for sources without\n * meaningful quality variants, test setups, or players that intentionally\n * 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        picker: config?.picker ?? defaultVideoPicker,\n        pickerConfig: config,\n      },\n    }),\n});\n\n/**\n * Config for `selectAudioTrack`. Pass `picker` to fully override selection\n * logic; otherwise the default `pickAudioTrack` is used (three-tier:\n * `preferredAudioLanguage` → `DEFAULT=YES` → first track).\n */\nexport interface SelectAudioTrackConfig extends AudioSelectionConfig {\n  picker?: TrackPicker<SelectAudioTrackConfig>;\n}\n\n/**\n * Select an audio track when a presentation loads. Clears the selection\n * on src unload.\n *\n * This is the simple, lifecycle-only counterpart to `switchAudioTrack`\n * (in `./track-switching.ts`) — compose one or the other, not both\n * (both write `selectedAudioTrackId`). `switchAudioTrack` adds\n * filter-reactivity (`userAudioTrackSelection`) and mid-stream-flush\n * orchestration; `selectAudioTrack` covers the default-on-load case\n * without those. Use this variant for test setups, audio-only flows\n * that don't expose language switching, or composition variants that\n * intentionally pin a track.\n *\n * @example\n * const reactor = selectAudioTrack.setup({ state });\n *\n * @example\n * // Custom picker with language preference\n * const reactor = selectAudioTrack.setup({\n *   state,\n *   config: { preferredAudioLanguage: 'en', picker: myLanguageAwarePicker },\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        picker: config?.picker ?? pickAudioTrack,\n        pickerConfig: config,\n      },\n    }),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,SAAS,oBAA8D,EACrE,OACA,QAAQ,EAAE,aAAa,QAAQ,kBAI9B;CACD,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,KAAK,CAAC,GAC3C,0BACA,0BACN;AAED,QAAO,qBAAqB;EAC1B,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,2BAA2B,EAAE;GAC7B,yBAAyB,EAYvB,aAAa;AACX,QAAI,CAAC,MAAM,aAAa,KAAK,EAAE;KAK7B,MAAM,KAAK,OAAO,MAAM,aAAa,KAAK,EAAG,aAAa;AAC1D,SAAI,GAAI,OAAM,aAAa,IAAI,GAAG;;AAEpC,iBAAa,MAAM,aAAa,IAAI,KAAA,EAAU;MAEjD;GACF;EACF,CAAC;;;AAcJ,MAAM,sBAAmC,iBAAiB,iBAAiB,cAAc,QAAQ;;;;;;;;;;;;;;;AA4BjG,MAAa,mBAAmB,eAAe;CAC7C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,aAAa,kBAAkB;GAC/B,QAAQ,QAAQ,UAAU;GAC1B,cAAc;GACf;EACF,CAAC;CACL,CAAC;AAkC8B,eAAe;CAC7C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,aACf,oBAAoB;EAClB;EACA,QAAQ;GACN,aAAa,kBAAkB;GAC/B,QAAQ,QAAQ,UAAU;GAC1B,cAAc;GACf;EACF,CAAC;CACL,CAAC"}

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

@@ -0,0 +1,12 @@
+//#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":";;;;;UA0BiB,qBAAA;;EAEf,UAAA;AAAA"}

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

@@ -0,0 +1,66 @@
+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 { 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\n * own the *trip*: on a failed fetch they add the failing CDN (origin) to the\n * `failedCdns` state signal directly. This behavior owns the *expiry*: while a\n * presentation is resolved, it watches `failedCdns` and, for each CDN that\n * appears, schedules a timer to remove it once its cooldown lapses.\n * `track-switching`'s `excludeFailedCdns` constraint prunes a failed CDN's\n * tracks and the active-CDN scope falls to the next one — and back, once the\n * cooldown removes it here.\n *\n * Lifecycle is per-source: timers + `failedCdns` are cleared on exit (a new\n * source starts with a clean slate). Policy (cooldown) is engine config. This is\n * 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\n * anything that reaches `failedCdns` is 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/**\n * Failover policy: how long a CDN stays excluded after a failed fetch trips it.\n * Supplied via engine config.\n */\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\n * 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              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                const timer = setTimeout(() => {\n                  timers.delete(cdn);\n                  update(state.failedCdns, (current) => current?.filter((c) => c !== cdn));\n                }, cooldownMs);\n                timers.set(cdn, timer);\n              });\n            },\n          ],\n        },\n      },\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,kCAAyD,EAKpE,YAAY,KACb;;;;;;;;AAmBD,MAAa,uBAAuB,eAAe;CACjD,WAAW,CAAC,gBAAgB,aAAa;CACzC,aAAa,EAAE;CACf,QAAQ,EACN,OACA,SAAS,EAAE,OAOP;EACJ,MAAM,aAAa,OAAO,UAAU,cAAc,gCAAgC;EAIlF,MAAM,yBAAS,IAAI,KAA4C;EAC/D,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,KAAK,CAAC,GAC3C,0BACA,0BACN;AAED,SAAO,qBAAqB;GAC1B,SAAS;GACT,eAAe,mBAAmB,KAAK;GACvC,QAAQ;IACN,2BAA2B,EAAE;IAC7B,yBAAyB;KAGvB,mBAAmB;AACjB,aAAO,SAAS,UAAU,aAAa,MAAM,CAAC;AAC9C,aAAO,OAAO;AACd,YAAM,WAAW,IAAI,KAAA,EAAU;;KAEjC,SAAS,OACD;AAEJ,OADe,MAAM,WAAW,KAAK,IAAI,EAAE,EACpC,SAAS,QAAQ;AAGtB,WAAI,OAAO,IAAI,IAAI,CAAE;OACrB,MAAM,QAAQ,iBAAiB;AAC7B,eAAO,OAAO,IAAI;AAClB,eAAO,MAAM,aAAa,YAAY,SAAS,QAAQ,MAAM,MAAM,IAAI,CAAC;UACvE,WAAW;AACd,cAAO,IAAI,KAAK,MAAM;QACtB;OAEL;KACF;IACF;GACF,CAAC;;CAEL,CAAC"}