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

package/dist/default/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.**\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/default/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/default/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"}

package/dist/default/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 `mediaElement.preload` into
+*   `state.preload` if it's a W3C value and `state.preload` isn't holding
+*   an extended (non-W3C) value. When the DOM has no 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 target = mediaElement && isStandardPreload(mediaElement.preload) ? mediaElement.preload : 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/default/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 * - **Read (DOM → state)** — on `context.mediaElement` swap or\n *   `state.presentation.url` change, copies `mediaElement.preload` into\n *   `state.preload` if it's a W3C value and `state.preload` isn't holding\n *   an extended (non-W3C) value. When the DOM has no W3C opinion and\n *   `state.preload` is undefined, backfills from `config.defaultPreload`\n *   (default-default `'metadata'`) so `state.preload` is never undefined\n *   in steady state.\n * - **Write (state → DOM)** — on `state.preload` change or\n *   `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`\n * are sticky: read won't overwrite them, write won't push them to the DOM.\n * All writes are deduped to break echo loops and avoid spurious re-triggers\n * downstream (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\n   * external code has supplied a W3C value. 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    const target: StandardPreload | undefined =\n      mediaElement && isStandardPreload(mediaElement.preload)\n        ? mediaElement.preload\n        : current === undefined\n          ? defaultPreload\n          : undefined;\n    if (target === undefined || target === current) return;\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    if (!isStandardPreload(next)) return;\n    if (mediaElement.preload === next) return;\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":";;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAS,iBAAiB,EACxB,OACA,SACA,UAQa;CACb,MAAM,iBAAkC,QAAQ,kBAAA;CAChD,MAAM,kBAAkB,eAAe,MAAM,aAAa,KAAK,EAAE,IAAI;CAUrE,MAAM,cAAc,aAAa;AAC/B,kBAAgB,KAAK;EACrB,MAAM,eAAe,QAAQ,aAAa,KAAK;EAG/C,MAAM,UAAU,KAAK,MAAM,QAAQ;AAEnC,MAAI,YAAY,KAAA,KAAa,CAAC,kBAAkB,QAAQ,CAAE;EAE1D,MAAM,SACJ,gBAAgB,kBAAkB,aAAa,QAAQ,GACnD,aAAa,UACb,YAAY,KAAA,IACV,iBACA,KAAA;AACR,MAAI,WAAW,KAAA,KAAa,WAAW,QAAS;AAChD,QAAM,QAAQ,IAAI,OAAO;GACzB;CAEF,MAAM,eAAe,aAAa;EAChC,MAAM,OAAO,MAAM,QAAQ,KAAK;EAChC,MAAM,eAAe,QAAQ,aAAa,KAAK;AAC/C,MAAI,CAAC,aAAc;AACnB,MAAI,CAAC,kBAAkB,KAAK,CAAE;AAC9B,MAAI,aAAa,YAAY,KAAM;AACnC,eAAa,UAAU;GACvB;AAEF,cAAa;AACX,eAAa;AACb,gBAAc;;;AAIlB,MAAa,cAAc,eAAe;CACxC,WAAW,CAAC,WAAW,eAAe;CACtC,aAAa,CAAC,eAAe;CAC7B,OAAO;CACR,CAAC"}

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

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