@videojs/spf 10.0.0-beta.2 → 10.0.0-beta.21

package/dist/dev/core/create-transition-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-transition-actor.js","names":[],"sources":["../../../src/core/create-transition-actor.ts"],"sourcesContent":["import type { ActorSnapshot } from './actor';\nimport type { Machine } from './machine';\nimport { createMachineCore } from './machine';\nimport { untrack, update } from './signals/primitives';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reducer-shaped actor: `(context, message) => context`.\n *\n * No finite states — the snapshot carries `value: 'active' | 'destroyed'`\n * as a universal lifecycle marker rather than domain state. The interesting\n * state is entirely in the context, which is reactive via `snapshot`.\n *\n * Use this when the actor has context that needs to be reactive but no\n * meaningful state machine (e.g., a message-driven model with DOM side\n * effects). For actors that need per-state behavior, use `createMachineActor`.\n */\nexport interface TransitionActor<Context extends object, Message extends { type: string }>\n  extends Machine<ActorSnapshot<'active' | 'destroyed', Context>> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reducer-shaped actor from an initial context and a reducer function.\n *\n * The reducer receives the current context and a message and returns the next\n * context. Returning the same reference (by identity) skips the signal update —\n * so early-returning `context` unchanged is both the no-op and the optimization.\n *\n * Side effects (e.g. DOM mutations) may be performed inside the reducer.\n * They run synchronously before the signal is updated.\n *\n * @example\n * const actor = createTransitionActor(\n *   { count: 0 },\n *   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })\n * );\n */\nexport function createTransitionActor<Context extends object, Message extends { type: string }>(\n  initialContext: Context,\n  reducer: (context: Context, message: Message) => Context\n): TransitionActor<Context, Message> {\n  const { snapshotSignal, getState, transition } = createMachineCore<\n    'active' | 'destroyed',\n    ActorSnapshot<'active' | 'destroyed', Context>\n  >({ value: 'active', context: initialContext });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n  const setContext = (context: Context): void => update(snapshotSignal, { context });\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      if (getState() === 'destroyed') return;\n      const context = getContext();\n      const newContext = reducer(context, message);\n      if (newContext !== context) setContext(newContext);\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,sBACd,gBACA,SACmC;CACnC,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAG/C;EAAE,OAAO;EAAU,SAAS;EAAgB,CAAC;CAE/C,MAAM,mBAA4B,cAAc,eAAe,KAAK,CAAC,QAAQ;CAC7E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,SAAS,CAAC;AAElF,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,KAAK,SAAwB;AAC3B,OAAI,UAAU,KAAK,YAAa;GAChC,MAAM,UAAU,YAAY;GAC5B,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAC5C,OAAI,eAAe,QAAS,YAAW,WAAW;;EAGpD,UAAgB;AACd,OAAI,UAAU,KAAK,YAAa;AAChC,cAAW,YAAY;;EAE1B"}

package/dist/dev/core/features/calculate-presentation-duration.js

@@ -0,0 +1,53 @@
+import { effect } from "../signals/effect.js";
+import { isResolvedTrack } from "../types/index.js";
+import { getSelectedTrack } from "../utils/track-selection.js";
+//#region src/core/features/calculate-presentation-duration.ts
+/**
+* Check if we can calculate presentation duration (have required data).
+*/
+function canCalculateDuration(state) {
+	if (!state.presentation) return false;
+	return !!(state.selectedVideoTrackId || state.selectedAudioTrackId);
+}
+/**
+* Check if we should calculate presentation duration (conditions met).
+*/
+function shouldCalculateDuration(state) {
+	if (!canCalculateDuration(state)) return false;
+	const { presentation } = state;
+	if (presentation.duration !== void 0) return false;
+	const videoTrack = state.selectedVideoTrackId ? getSelectedTrack(state, "video") : void 0;
+	const audioTrack = state.selectedAudioTrackId ? getSelectedTrack(state, "audio") : void 0;
+	return !!(videoTrack && isResolvedTrack(videoTrack) || audioTrack && isResolvedTrack(audioTrack));
+}
+/**
+* Get duration from the first resolved track (prefer video, fallback to audio).
+*/
+function getDurationFromResolvedTracks(state) {
+	const videoTrack = state.selectedVideoTrackId ? getSelectedTrack(state, "video") : void 0;
+	if (videoTrack && isResolvedTrack(videoTrack)) return videoTrack.duration;
+	const audioTrack = state.selectedAudioTrackId ? getSelectedTrack(state, "audio") : void 0;
+	if (audioTrack && isResolvedTrack(audioTrack)) return audioTrack.duration;
+}
+/**
+* Calculate and set presentation duration from resolved tracks.
+*/
+function calculatePresentationDuration({ state }) {
+	return effect(() => {
+		const currentState = state.get();
+		if (!shouldCalculateDuration(currentState)) return;
+		const duration = getDurationFromResolvedTracks(currentState);
+		if (duration === void 0 || !Number.isFinite(duration)) return;
+		state.set({
+			...currentState,
+			presentation: {
+				...currentState.presentation,
+				duration
+			}
+		});
+	});
+}
+//#endregion
+export { calculatePresentationDuration };
+
+//# sourceMappingURL=calculate-presentation-duration.js.map

package/dist/dev/core/features/calculate-presentation-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate-presentation-duration.js","names":[],"sources":["../../../../src/core/features/calculate-presentation-duration.ts"],"sourcesContent":["import { effect } from '../signals/effect';\nimport type { Signal } from '../signals/primitives';\nimport type { AudioTrack, Presentation, VideoTrack } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack } from '../utils/track-selection';\n\nexport interface PresentationDurationState {\n  presentation?: Presentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n}\n\n/**\n * Check if we can calculate presentation duration (have required data).\n */\nexport function canCalculateDuration(state: PresentationDurationState): boolean {\n  if (!state.presentation) return false;\n  // Need at least one selected track\n  return !!(state.selectedVideoTrackId || state.selectedAudioTrackId);\n}\n\n/**\n * Check if we should calculate presentation duration (conditions met).\n */\nexport function shouldCalculateDuration(state: PresentationDurationState): boolean {\n  if (!canCalculateDuration(state)) return false;\n\n  const { presentation } = state;\n\n  // Don't recalculate if already set\n  if (presentation!.duration !== undefined) return false;\n\n  // Check if any selected track is resolved\n  const videoTrack = state.selectedVideoTrackId ? getSelectedTrack(state, 'video') : undefined;\n  const audioTrack = state.selectedAudioTrackId ? getSelectedTrack(state, 'audio') : undefined;\n\n  // At least one track must be resolved (has segments and duration)\n  return !!((videoTrack && isResolvedTrack(videoTrack)) || (audioTrack && isResolvedTrack(audioTrack)));\n}\n\n/**\n * Get duration from the first resolved track (prefer video, fallback to audio).\n */\nexport function getDurationFromResolvedTracks(state: PresentationDurationState): number | undefined {\n  // Try video track first\n  const videoTrack = state.selectedVideoTrackId\n    ? (getSelectedTrack(state, 'video') as VideoTrack | undefined)\n    : undefined;\n  if (videoTrack && isResolvedTrack(videoTrack)) {\n    return videoTrack.duration;\n  }\n\n  // Fallback to audio track\n  const audioTrack = state.selectedAudioTrackId\n    ? (getSelectedTrack(state, 'audio') as AudioTrack | undefined)\n    : undefined;\n  if (audioTrack && isResolvedTrack(audioTrack)) {\n    return audioTrack.duration;\n  }\n\n  return undefined;\n}\n\n/**\n * Calculate and set presentation duration from resolved tracks.\n */\nexport function calculatePresentationDuration<S extends PresentationDurationState>({\n  state,\n}: {\n  state: Signal<S>;\n}): () => void {\n  return effect(() => {\n    const currentState = state.get();\n    if (!shouldCalculateDuration(currentState)) return;\n\n    const duration = getDurationFromResolvedTracks(currentState);\n    if (duration === undefined || !Number.isFinite(duration)) return;\n\n    state.set({\n      ...currentState,\n      presentation: {\n        ...currentState.presentation!,\n        duration,\n      },\n    } as S);\n  });\n}\n"],"mappings":";;;;;;;AAeA,SAAgB,qBAAqB,OAA2C;AAC9E,KAAI,CAAC,MAAM,aAAc,QAAO;AAEhC,QAAO,CAAC,EAAE,MAAM,wBAAwB,MAAM;;;;;AAMhD,SAAgB,wBAAwB,OAA2C;AACjF,KAAI,CAAC,qBAAqB,MAAM,CAAE,QAAO;CAEzC,MAAM,EAAE,iBAAiB;AAGzB,KAAI,aAAc,aAAa,KAAA,EAAW,QAAO;CAGjD,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG,KAAA;CACnF,MAAM,aAAa,MAAM,uBAAuB,iBAAiB,OAAO,QAAQ,GAAG,KAAA;AAGnF,QAAO,CAAC,EAAG,cAAc,gBAAgB,WAAW,IAAM,cAAc,gBAAgB,WAAW;;;;;AAMrG,SAAgB,8BAA8B,OAAsD;CAElG,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC,KAAA;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;CAIpB,MAAM,aAAa,MAAM,uBACpB,iBAAiB,OAAO,QAAQ,GACjC,KAAA;AACJ,KAAI,cAAc,gBAAgB,WAAW,CAC3C,QAAO,WAAW;;;;;AAStB,SAAgB,8BAAmE,EACjF,SAGa;AACb,QAAO,aAAa;EAClB,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,wBAAwB,aAAa,CAAE;EAE5C,MAAM,WAAW,8BAA8B,aAAa;AAC5D,MAAI,aAAa,KAAA,KAAa,CAAC,OAAO,SAAS,SAAS,CAAE;AAE1D,QAAM,IAAI;GACR,GAAG;GACH,cAAc;IACZ,GAAG,aAAa;IAChB;IACD;GACF,CAAM;GACP"}

package/dist/dev/core/features/quality-switching.js

@@ -0,0 +1,69 @@
+import { getBandwidthEstimate } from "../abr/bandwidth-estimator.js";
+import { effect } from "../signals/effect.js";
+import { update } from "../signals/primitives.js";
+import { selectQuality } from "../abr/quality-selection.js";
+//#region src/core/features/quality-switching.ts
+/**
+* Default quality switching configuration.
+*/
+const DEFAULT_SWITCHING_CONFIG = {
+	safetyMargin: .85,
+	minUpgradeInterval: 8e3,
+	defaultBandwidth: 5e6
+};
+/**
+* Get all video tracks from a presentation's first switching set.
+* Returns [] when the presentation is still unresolved (no selectionSets yet).
+*/
+function getVideoTracks(presentation) {
+	return (presentation.selectionSets?.find((s) => s.type === "video"))?.switchingSets[0]?.tracks ?? [];
+}
+/**
+* Quality switching orchestration (F9).
+*
+* Reacts to bandwidth estimate changes and updates `selectedVideoTrackId`
+* when a different quality is optimal:
+*
+* - **Downgrades** happen immediately to avoid buffering stalls.
+* - **Upgrades** are gated by `minUpgradeInterval` to prevent oscillation.
+* - The first switch (from any track, or no track) is always immediate.
+*
+* Smooth switching is handled downstream: when `selectedVideoTrackId` changes,
+* `resolveTrack` fetches the new playlist and `loadSegments` reloads the init
+* segment, then appends media segments from the current position in the new
+* quality. The browser's SourceBuffer replaces the overlapping buffered range.
+*
+* @example
+* const cleanup = switchQuality({ state });
+* // Later, when done:
+* cleanup();
+*/
+function switchQuality({ state }, config = {}) {
+	const safetyMargin = config.safetyMargin ?? DEFAULT_SWITCHING_CONFIG.safetyMargin;
+	const minUpgradeInterval = config.minUpgradeInterval ?? DEFAULT_SWITCHING_CONFIG.minUpgradeInterval;
+	const defaultBandwidth = config.defaultBandwidth ?? DEFAULT_SWITCHING_CONFIG.defaultBandwidth;
+	let lastUpgradeTime = Date.now();
+	let firstMeaningfulFire = true;
+	return effect(() => {
+		const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = state.get();
+		if (abrDisabled === true) return;
+		if (!presentation || !bandwidthState) return;
+		const videoTracks = getVideoTracks(presentation);
+		if (videoTracks.length === 0) return;
+		const isFirst = firstMeaningfulFire;
+		firstMeaningfulFire = false;
+		const optimal = selectQuality(videoTracks, getBandwidthEstimate(bandwidthState, defaultBandwidth), { safetyMargin });
+		if (!optimal || optimal.id === selectedVideoTrackId) return;
+		const currentTrack = videoTracks.find((t) => t.id === selectedVideoTrackId);
+		if (!currentTrack || optimal.bandwidth > currentTrack.bandwidth) {
+			const now = Date.now();
+			if (!isFirst && now - lastUpgradeTime < minUpgradeInterval) return;
+			lastUpgradeTime = now;
+		}
+		update(state, { selectedVideoTrackId: optimal.id });
+	});
+}
+//#endregion
+export { switchQuality };
+
+//# sourceMappingURL=quality-switching.js.map

package/dist/dev/core/features/quality-switching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-switching.js","names":[],"sources":["../../../../src/core/features/quality-switching.ts"],"sourcesContent":["import type { BandwidthState } from '../abr/bandwidth-estimator';\nimport { getBandwidthEstimate } from '../abr/bandwidth-estimator';\nimport { selectQuality } from '../abr/quality-selection';\nimport { effect } from '../signals/effect';\nimport { type Signal, update } from '../signals/primitives';\nimport type { Presentation, VideoSelectionSet } from '../types';\n\n/**\n * State shape for quality switching.\n */\nexport interface QualitySwitchingState {\n  presentation?: Presentation;\n  bandwidthState?: BandwidthState;\n  selectedVideoTrackId?: string;\n  // TODO: abrDisabled is a blunt instrument — it requires callers to know they're\n  // competing with ABR and explicitly opt out. A better long-term design would\n  // separate ABR selection (abrVideoTrackId) from manual selection (manualVideoTrackId)\n  // and derive the effective selectedVideoTrackId as manualVideoTrackId ?? abrVideoTrackId.\n  // That way the two concerns never write to the same field and consumers are unchanged.\n  /** When true, ABR quality switching is suppressed. Use for manual quality selection. */\n  abrDisabled?: boolean;\n}\n\n/**\n * Configuration for quality switching behavior.\n */\nexport interface QualitySwitchingConfig {\n  /**\n   * Safety margin for quality selection (0–1).\n   * Track is selected only when bandwidth >= track.bandwidth / safetyMargin.\n   * Default: 0.85 (15% headroom).\n   */\n  safetyMargin?: number;\n\n  /**\n   * Minimum milliseconds between upgrades.\n   * Prevents oscillation when bandwidth fluctuates around a quality threshold.\n   * Downgrades are always immediate regardless of this setting.\n   * Default: 8000 (8 seconds).\n   */\n  minUpgradeInterval?: number;\n\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected.\n   * Default: 5_000_000 (5 Mbps).\n   */\n  defaultBandwidth?: number;\n}\n\n/**\n * Default quality switching configuration.\n */\nexport const DEFAULT_SWITCHING_CONFIG: Required<QualitySwitchingConfig> = {\n  safetyMargin: 0.85,\n  minUpgradeInterval: 8000,\n  defaultBandwidth: 5_000_000,\n};\n\n/**\n * Get all video tracks from a presentation's first switching set.\n * Returns [] when the presentation is still unresolved (no selectionSets yet).\n */\nfunction getVideoTracks(presentation: Presentation) {\n  const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n  return videoSet?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Quality switching orchestration (F9).\n *\n * Reacts to bandwidth estimate changes and updates `selectedVideoTrackId`\n * when a different quality is optimal:\n *\n * - **Downgrades** happen immediately to avoid buffering stalls.\n * - **Upgrades** are gated by `minUpgradeInterval` to prevent oscillation.\n * - The first switch (from any track, or no track) is always immediate.\n *\n * Smooth switching is handled downstream: when `selectedVideoTrackId` changes,\n * `resolveTrack` fetches the new playlist and `loadSegments` reloads the init\n * segment, then appends media segments from the current position in the new\n * quality. The browser's SourceBuffer replaces the overlapping buffered range.\n *\n * @example\n * const cleanup = switchQuality({ state });\n * // Later, when done:\n * cleanup();\n */\nexport function switchQuality<S extends QualitySwitchingState>(\n  { state }: { state: Signal<S> },\n  config: QualitySwitchingConfig = {}\n): () => void {\n  const safetyMargin = config.safetyMargin ?? DEFAULT_SWITCHING_CONFIG.safetyMargin;\n  const minUpgradeInterval = config.minUpgradeInterval ?? DEFAULT_SWITCHING_CONFIG.minUpgradeInterval;\n  const defaultBandwidth = config.defaultBandwidth ?? DEFAULT_SWITCHING_CONFIG.defaultBandwidth;\n\n  // Initialize to creation time so the interval starts counting immediately.\n  // The first time we have enough data to make a meaningful quality decision\n  // (presentation resolved + bandwidth available), the upgrade gate is skipped\n  // so the initial ABR correction does not wait for minUpgradeInterval.\n  let lastUpgradeTime = Date.now();\n  let firstMeaningfulFire = true;\n\n  return effect(() => {\n    const currentState = state.get();\n    const { presentation, bandwidthState, selectedVideoTrackId, abrDisabled } = currentState;\n\n    if (abrDisabled === true) return;\n    if (!presentation || !bandwidthState) return;\n\n    const videoTracks = getVideoTracks(presentation);\n    if (videoTracks.length === 0) return;\n\n    // Consume the first-meaningful-fire flag now that we have all required data.\n    const isFirst = firstMeaningfulFire;\n    firstMeaningfulFire = false;\n\n    const bandwidth = getBandwidthEstimate(bandwidthState, defaultBandwidth);\n    const optimal = selectQuality(videoTracks as any, bandwidth, { safetyMargin });\n    if (!optimal || optimal.id === selectedVideoTrackId) return;\n\n    // Determine whether this is an upgrade or downgrade.\n    const currentTrack = videoTracks.find((t) => t.id === selectedVideoTrackId);\n    const isUpgrade = !currentTrack || optimal.bandwidth > currentTrack.bandwidth;\n\n    if (isUpgrade) {\n      const now = Date.now();\n      // Gate upgrades with minUpgradeInterval to prevent oscillation.\n      // Downgrades are always immediate; the first meaningful evaluation is always allowed.\n      if (!isFirst && now - lastUpgradeTime < minUpgradeInterval) return;\n      lastUpgradeTime = now;\n    }\n\n    const patch: Partial<QualitySwitchingState> = { selectedVideoTrackId: optimal.id };\n    update(state, patch);\n  });\n}\n"],"mappings":";;;;;;;;AAoDA,MAAa,2BAA6D;CACxE,cAAc;CACd,oBAAoB;CACpB,kBAAkB;CACnB;;;;;AAMD,SAAS,eAAe,cAA4B;AAElD,SADiB,aAAa,eAAe,MAAM,MAAM,EAAE,SAAS,QAAQ,GAC3D,cAAc,IAAI,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;AAuBjD,SAAgB,cACd,EAAE,SACF,SAAiC,EAAE,EACvB;CACZ,MAAM,eAAe,OAAO,gBAAgB,yBAAyB;CACrE,MAAM,qBAAqB,OAAO,sBAAsB,yBAAyB;CACjF,MAAM,mBAAmB,OAAO,oBAAoB,yBAAyB;CAM7E,IAAI,kBAAkB,KAAK,KAAK;CAChC,IAAI,sBAAsB;AAE1B,QAAO,aAAa;EAElB,MAAM,EAAE,cAAc,gBAAgB,sBAAsB,gBADvC,MAAM,KAAK;AAGhC,MAAI,gBAAgB,KAAM;AAC1B,MAAI,CAAC,gBAAgB,CAAC,eAAgB;EAEtC,MAAM,cAAc,eAAe,aAAa;AAChD,MAAI,YAAY,WAAW,EAAG;EAG9B,MAAM,UAAU;AAChB,wBAAsB;EAGtB,MAAM,UAAU,cAAc,aADZ,qBAAqB,gBAAgB,iBAAiB,EACX,EAAE,cAAc,CAAC;AAC9E,MAAI,CAAC,WAAW,QAAQ,OAAO,qBAAsB;EAGrD,MAAM,eAAe,YAAY,MAAM,MAAM,EAAE,OAAO,qBAAqB;AAG3E,MAFkB,CAAC,gBAAgB,QAAQ,YAAY,aAAa,WAErD;GACb,MAAM,MAAM,KAAK,KAAK;AAGtB,OAAI,CAAC,WAAW,MAAM,kBAAkB,mBAAoB;AAC5D,qBAAkB;;AAIpB,SAAO,OADuC,EAAE,sBAAsB,QAAQ,IAAI,CAC9D;GACpB"}

package/dist/dev/core/features/resolve-presentation.js

@@ -0,0 +1,73 @@
+import { computed, update } from "../signals/primitives.js";
+import { fetchResolvable, getResponseText } from "../../dom/network/fetch.js";
+import { createMachineReactor } from "../create-machine-reactor.js";
+import { parseMultivariantPlaylist } from "../hls/parse-multivariant.js";
+//#region src/core/features/resolve-presentation.ts
+/**
+* Determines if resolution conditions are met based on preload policy and playback state.
+*
+* Resolution conditions:
+* - State-driven: preload is 'auto' or 'metadata'
+* - Playback-driven: playbackInitiated is true
+*
+* @param state - Current presentation state
+* @returns true if resolution conditions are met
+*/
+function shouldResolve(state) {
+	const { preload, playbackInitiated } = state;
+	return ["auto", "metadata"].includes(preload) || !!playbackInitiated;
+}
+/**
+* Derives the correct state from current state conditions.
+*
+* States are mutually exclusive and exhaustive:
+* - `'preconditions-unmet'`: no presentation, or presentation has no URL
+* - `'idle'`:     URL present, unresolved (no id), shouldResolve not met
+* - `'resolving'`: URL present, unresolved (no id), shouldResolve met
+* - `'resolved'`:  URL present, resolved (has id)
+*/
+function deriveState(state) {
+	const { presentation } = state;
+	if (!presentation || !("url" in presentation)) return "preconditions-unmet";
+	if ("id" in presentation) return "resolved";
+	return shouldResolve(state) ? "resolving" : "idle";
+}
+/**
+* Resolves unresolved presentations using reactive composition.
+*
+* FSM driven by `deriveState` — a single `always` monitor keeps the state in
+* sync with conditions at all times. `'resolving'` additionally runs the fetch
+* task and returns an AbortController so the framework aborts it on state exit.
+*
+* @example
+* const reactor = resolvePresentation({ state });
+* // later:
+* reactor.destroy();
+*/
+function resolvePresentation({ state }) {
+	const derivedStateSignal = computed(() => deriveState(state.get()));
+	return createMachineReactor({
+		initial: "preconditions-unmet",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"preconditions-unmet": {},
+			idle: {},
+			resolving: { entry: () => {
+				const presentation = state.get().presentation;
+				const ac = new AbortController();
+				fetchResolvable(presentation, { signal: ac.signal }).then((response) => getResponseText(response)).then((text) => {
+					update(state, { presentation: parseMultivariantPlaylist(text, presentation) });
+				}).catch((error) => {
+					if (error instanceof Error && error.name === "AbortError") return;
+					throw error;
+				});
+				return ac;
+			} },
+			resolved: {}
+		}
+	});
+}
+//#endregion
+export { resolvePresentation };
+
+//# sourceMappingURL=resolve-presentation.js.map

package/dist/dev/core/features/resolve-presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-presentation.js","names":[],"sources":["../../../../src/core/features/resolve-presentation.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport type { Reactor } from '../create-machine-reactor';\nimport { createMachineReactor } from '../create-machine-reactor';\nimport { parseMultivariantPlaylist } from '../hls/parse-multivariant';\nimport { computed, type Signal, update } from '../signals/primitives';\nimport type { AddressableObject, Presentation } from '../types';\n\n/**\n * Unresolved presentation - has a URL but no data yet.\n * Identical to AddressableObject per user requirement.\n */\nexport type UnresolvedPresentation = AddressableObject;\n\n/**\n * State shape for presentation resolution.\n */\nexport interface PresentationState {\n  presentation?: UnresolvedPresentation | Presentation | undefined;\n  preload?: 'auto' | 'metadata' | 'none' | undefined;\n  /** True once the user has initiated playback — enables resolution regardless of preload. */\n  playbackInitiated?: boolean;\n}\n\n/**\n * Type guard to check if presentation is unresolved.\n */\nexport function isUnresolved(\n  presentation: UnresolvedPresentation | Presentation | undefined\n): presentation is UnresolvedPresentation {\n  return presentation !== undefined && 'url' in presentation && !('id' in presentation);\n}\n\nexport function canResolve(\n  state: PresentationState\n): state is PresentationState & { presentation: UnresolvedPresentation } {\n  return isUnresolved(state.presentation);\n}\n\n/**\n * Determines if resolution conditions are met based on preload policy and playback state.\n *\n * Resolution conditions:\n * - State-driven: preload is 'auto' or 'metadata'\n * - Playback-driven: playbackInitiated is true\n *\n * @param state - Current presentation state\n * @returns true if resolution conditions are met\n */\nexport function shouldResolve(state: PresentationState): boolean {\n  const { preload, playbackInitiated } = state;\n  return (\n    // State-driven: preload allows (auto/metadata)\n    ['auto', 'metadata'].includes(preload as any) ||\n    // Playback-driven: user has initiated playback\n    !!playbackInitiated\n  );\n}\n\nexport type ResolvePresentationState = 'preconditions-unmet' | 'idle' | 'resolving' | 'resolved';\n\n/**\n * Derives the correct state from current state conditions.\n *\n * States are mutually exclusive and exhaustive:\n * - `'preconditions-unmet'`: no presentation, or presentation has no URL\n * - `'idle'`:     URL present, unresolved (no id), shouldResolve not met\n * - `'resolving'`: URL present, unresolved (no id), shouldResolve met\n * - `'resolved'`:  URL present, resolved (has id)\n */\nfunction deriveState(state: PresentationState): ResolvePresentationState {\n  const { presentation } = state;\n  if (!presentation || !('url' in presentation)) return 'preconditions-unmet';\n  if ('id' in presentation) return 'resolved';\n  return shouldResolve(state) ? 'resolving' : 'idle';\n}\n\n/**\n * Resolves unresolved presentations using reactive composition.\n *\n * FSM driven by `deriveState` — a single `always` monitor keeps the state in\n * sync with conditions at all times. `'resolving'` additionally runs the fetch\n * task and returns an AbortController so the framework aborts it on state exit.\n *\n * @example\n * const reactor = resolvePresentation({ state });\n * // later:\n * reactor.destroy();\n */\nexport function resolvePresentation<S extends PresentationState>({\n  state,\n}: {\n  state: Signal<S>;\n}): Reactor<ResolvePresentationState | 'destroying' | 'destroyed'> {\n  const derivedStateSignal = computed(() => deriveState(state.get()));\n\n  return createMachineReactor<ResolvePresentationState>({\n    initial: 'preconditions-unmet',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'preconditions-unmet': {},\n      idle: {},\n      resolving: {\n        // Entry: start fetch on state entry; return AbortController so the\n        // framework aborts the in-flight request on state exit.\n        entry: () => {\n          const presentation = state.get().presentation as UnresolvedPresentation;\n          const ac = new AbortController();\n\n          fetchResolvable(presentation, { signal: ac.signal })\n            .then((response) => getResponseText(response))\n            .then((text) => {\n              const parsed = parseMultivariantPlaylist(text, presentation);\n              update(state, { presentation: parsed } as Partial<S>);\n            })\n            .catch((error) => {\n              if (error instanceof Error && error.name === 'AbortError') return;\n              throw error;\n            });\n\n          return ac;\n        },\n      },\n      resolved: {},\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgDA,SAAgB,cAAc,OAAmC;CAC/D,MAAM,EAAE,SAAS,sBAAsB;AACvC,QAEE,CAAC,QAAQ,WAAW,CAAC,SAAS,QAAe,IAE7C,CAAC,CAAC;;;;;;;;;;;AAeN,SAAS,YAAY,OAAoD;CACvE,MAAM,EAAE,iBAAiB;AACzB,KAAI,CAAC,gBAAgB,EAAE,SAAS,cAAe,QAAO;AACtD,KAAI,QAAQ,aAAc,QAAO;AACjC,QAAO,cAAc,MAAM,GAAG,cAAc;;;;;;;;;;;;;;AAe9C,SAAgB,oBAAiD,EAC/D,SAGiE;CACjE,MAAM,qBAAqB,eAAe,YAAY,MAAM,KAAK,CAAC,CAAC;AAEnE,QAAO,qBAA+C;EACpD,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,uBAAuB,EAAE;GACzB,MAAM,EAAE;GACR,WAAW,EAGT,aAAa;IACX,MAAM,eAAe,MAAM,KAAK,CAAC;IACjC,MAAM,KAAK,IAAI,iBAAiB;AAEhC,oBAAgB,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAAC,CACjD,MAAM,aAAa,gBAAgB,SAAS,CAAC,CAC7C,MAAM,SAAS;AAEd,YAAO,OAAO,EAAE,cADD,0BAA0B,MAAM,aAAa,EACtB,CAAe;MACrD,CACD,OAAO,UAAU;AAChB,SAAI,iBAAiB,SAAS,MAAM,SAAS,aAAc;AAC3D,WAAM;MACN;AAEJ,WAAO;MAEV;GACD,UAAU,EAAE;GACb;EACF,CAAC"}

package/dist/dev/core/features/resolve-track.js

@@ -0,0 +1,66 @@
+import { effect } from "../signals/effect.js";
+import { isResolvedTrack } from "../types/index.js";
+import { getSelectedTrack } from "../utils/track-selection.js";
+import { fetchResolvable, getResponseText } from "../../dom/network/fetch.js";
+import { ConcurrentRunner, Task } from "../task.js";
+import { parseMediaPlaylist } from "../hls/parse-media-playlist.js";
+//#region src/core/features/resolve-track.ts
+function canResolve(state, config) {
+	const track = getSelectedTrack(state, config.type);
+	if (!track) return false;
+	return !isResolvedTrack(track);
+}
+/**
+* Updates a track within a presentation (immutably).
+* Generic - works for video, audio, or text tracks.
+*/
+function updateTrackInPresentation(presentation, resolvedTrack) {
+	const trackId = resolvedTrack.id;
+	return {
+		...presentation,
+		selectionSets: presentation.selectionSets.map((selectionSet) => ({
+			...selectionSet,
+			switchingSets: selectionSet.switchingSets.map((switchingSet) => ({
+				...switchingSet,
+				tracks: switchingSet.tracks.map((track) => track.id === trackId ? resolvedTrack : track)
+			}))
+		}))
+	};
+}
+/**
+* Resolves unresolved tracks using reactive composition.
+*
+* Reacts to state changes and schedules fetch tasks via ConcurrentRunner when
+* a selected track is unresolved. The ConcurrentRunner handles deduplication,
+* parallel execution, and cleanup.
+*
+* Generic version that works for video, audio, or text tracks based on config.
+* Type parameter T is inferred from config.type (use 'as const' for inference).
+*/
+function resolveTrack({ state }, config) {
+	const runner = new ConcurrentRunner();
+	const cleanup = effect(() => {
+		const currentState = state.get();
+		if (!canResolve(currentState, config)) return;
+		const track = getSelectedTrack(currentState, config.type);
+		if (!track) return;
+		const resolvedTrack = track;
+		runner.schedule(new Task(async (signal) => {
+			const mediaTrack = parseMediaPlaylist(await getResponseText(await fetchResolvable(resolvedTrack, { signal })), resolvedTrack);
+			const latest = state.get();
+			const updatedPresentation = updateTrackInPresentation(latest.presentation, mediaTrack);
+			state.set({
+				...latest,
+				presentation: updatedPresentation
+			});
+		}, { id: track.id }));
+	});
+	return () => {
+		runner.abortAll();
+		cleanup();
+	};
+}
+//#endregion
+export { resolveTrack };
+
+//# sourceMappingURL=resolve-track.js.map

package/dist/dev/core/features/resolve-track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-track.js","names":[],"sources":["../../../../src/core/features/resolve-track.ts"],"sourcesContent":["import { fetchResolvable, getResponseText } from '../../dom/network/fetch';\nimport { parseMediaPlaylist } from '../hls/parse-media-playlist';\nimport { effect } from '../signals/effect';\nimport type { Signal } from '../signals/primitives';\nimport { ConcurrentRunner, Task } from '../task';\nimport type { Presentation, ResolvedTrack, TrackType } from '../types';\nimport { isResolvedTrack } from '../types';\nimport { getSelectedTrack, type TrackSelectionState } from '../utils/track-selection';\n\n/**\n * State shape for track resolution.\n */\nexport interface TrackResolutionState extends TrackSelectionState {\n  presentation?: Presentation | undefined;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\nexport function canResolve<T extends TrackType>(\n  state: TrackResolutionState,\n  config: TrackResolutionConfig<T>\n): boolean {\n  const track = getSelectedTrack(state, config.type);\n  if (!track) return false;\n\n  return !isResolvedTrack(track);\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Updates a track within a presentation (immutably).\n * Generic - works for video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n\n/**\n * Configuration for track resolution.\n */\nexport interface TrackResolutionConfig<T extends TrackType = TrackType> {\n  type: T;\n}\n\n/**\n * Resolves unresolved tracks using reactive composition.\n *\n * Reacts to state changes and schedules fetch tasks via ConcurrentRunner when\n * a selected track is unresolved. The ConcurrentRunner handles deduplication,\n * parallel execution, and cleanup.\n *\n * Generic version that works for video, audio, or text tracks based on config.\n * Type parameter T is inferred from config.type (use 'as const' for inference).\n */\nexport function resolveTrack<S extends TrackResolutionState, T extends TrackType>(\n  { state }: { state: Signal<S> },\n  config: TrackResolutionConfig<T>\n): () => void {\n  // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createTaskRunner() with args TBD),\n  // likely eventually passed down via config or a new \"definitions\" argument. This will allow us to decide if we want our task runner/scheduler\n  // to e.g. run concurrently (like we currently are), serially with a queue, or abort the previous task and replace it with the newly scheduled one. (CJP).\n  const runner = new ConcurrentRunner();\n\n  const cleanup = effect(() => {\n    const currentState = state.get();\n    if (!canResolve(currentState, config)) return;\n\n    const track = getSelectedTrack(currentState, config.type);\n    if (!track) return;\n\n    const resolvedTrack = track;\n\n    runner.schedule(\n      // NOTE: This can/maybe will be pulled into a per-use case factory (e.g. something like createResolveTrackTask(track, context, config)),\n      // likely eventually passed down via config or a new \"definitions\" argument (CJP).\n      new Task(\n        async (signal) => {\n          const response = await fetchResolvable(resolvedTrack, { signal });\n          const text = await getResponseText(response);\n          const mediaTrack = parseMediaPlaylist(text, resolvedTrack);\n\n          // IMPORTANT: Read state.get().presentation at write time, not from the\n          // captured currentState snapshot. Multiple Tasks may be running concurrently\n          // (one per track being resolved), so the snapshot is likely already stale by\n          // the time a task completes — a sibling task may have already written the\n          // presentation with its own resolved track. Reading live state ensures each\n          // task builds on top of whatever has been committed so far.\n          const latest = state.get();\n          const updatedPresentation = updateTrackInPresentation(latest.presentation!, mediaTrack);\n          state.set({ ...latest, presentation: updatedPresentation } as S);\n        },\n        { id: track.id }\n      )\n    );\n  });\n\n  return () => {\n    runner.abortAll();\n    cleanup();\n  };\n}\n"],"mappings":";;;;;;;AAmBA,SAAgB,WACd,OACA,QACS;CACT,MAAM,QAAQ,iBAAiB,OAAO,OAAO,KAAK;AAClD,KAAI,CAAC,MAAO,QAAO;AAEnB,QAAO,CAAC,gBAAgB,MAAM;;;;;;AAWhC,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;AAC9B,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,MAAO;IAC3F,EAAE;GACJ,EAAE;EACJ;;;;;;;;;;;;AAoBH,SAAgB,aACd,EAAE,SACF,QACY;CAIZ,MAAM,SAAS,IAAI,kBAAkB;CAErC,MAAM,UAAU,aAAa;EAC3B,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,WAAW,cAAc,OAAO,CAAE;EAEvC,MAAM,QAAQ,iBAAiB,cAAc,OAAO,KAAK;AACzD,MAAI,CAAC,MAAO;EAEZ,MAAM,gBAAgB;AAEtB,SAAO,SAGL,IAAI,KACF,OAAO,WAAW;GAGhB,MAAM,aAAa,mBADN,MAAM,gBADF,MAAM,gBAAgB,eAAe,EAAE,QAAQ,CAAC,CACrB,EACA,cAAc;GAQ1D,MAAM,SAAS,MAAM,KAAK;GAC1B,MAAM,sBAAsB,0BAA0B,OAAO,cAAe,WAAW;AACvF,SAAM,IAAI;IAAE,GAAG;IAAQ,cAAc;IAAqB,CAAM;KAElE,EAAE,IAAI,MAAM,IAAI,CACjB,CACF;GACD;AAEF,cAAa;AACX,SAAO,UAAU;AACjB,WAAS"}

package/dist/dev/core/features/select-tracks.js

@@ -0,0 +1,130 @@
+import { effect } from "../signals/effect.js";
+import { update } from "../signals/primitives.js";
+import { SelectedTrackIdKeyByType } from "../utils/track-selection.js";
+//#region src/core/features/select-tracks.ts
+/**
+* Pick text track to activate.
+*
+* Selection priority (if enabled):
+* 1. User preference (preferredSubtitleLanguage)
+* 2. DEFAULT track (if enableDefaultTrack is true and track has DEFAULT=YES + AUTOSELECT=YES)
+* 3. No auto-selection (user opt-in)
+*
+* By default, FORCED tracks are excluded per Apple's HLS spec.
+*
+* @param presentation - Presentation with text tracks
+* @param config - Selection configuration
+* @returns Track ID or undefined (no auto-selection)
+*/
+function pickTextTrack(presentation, config) {
+	const textSet = presentation.selectionSets.find((set) => set.type === "text");
+	if (!textSet?.switchingSets?.[0]?.tracks.length) return void 0;
+	const tracks = textSet.switchingSets[0].tracks;
+	const availableTracks = config.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);
+	if (availableTracks.length === 0) return void 0;
+	const { preferredSubtitleLanguage, enableDefaultTrack = false } = config;
+	if (preferredSubtitleLanguage) {
+		const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);
+		if (languageMatch) return languageMatch.id;
+	}
+	if (enableDefaultTrack) {
+		const defaultTrack = availableTracks.find((track) => track.default === true);
+		if (defaultTrack) return defaultTrack.id;
+	}
+}
+/**
+* Check if we can select a track of the given type.
+*
+* Returns true when:
+* - Presentation exists
+* - Has tracks of the specified type
+*
+* Generic over track type - works for video, audio, or text.
+*/
+function canSelectTrack(state, config) {
+	return !!state?.presentation?.selectionSets?.find(({ type }) => type === config.type)?.switchingSets?.[0]?.tracks.length;
+}
+/**
+* Check if we should select a track of the given type.
+*
+* Returns true when:
+* - Track of this type is not already selected
+*
+* Generic over track type - works for video, audio, or text.
+*
+* @TODO figure out reactive model for ABR cases - right now we're only selecting
+* if we have nothing selected (CJP)
+*/
+function shouldSelectTrack(state, config) {
+	return !state[SelectedTrackIdKeyByType[config.type]];
+}
+/**
+* Select video track orchestration.
+*
+* Selects video track when:
+* - Presentation exists
+* - No video track is selected yet
+*
+* Uses bandwidth-based quality selection algorithm.
+*
+* @example
+* const cleanup = selectVideoTrack(
+*   { state, owners, events },
+*   { initialBandwidth: 2_000_000 }
+* );
+*/
+function selectVideoTrack({ state }, config = { type: "video" }) {
+	return effect(() => {
+		const currentState = state.get();
+		if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+		const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === config.type)?.switchingSets[0]?.tracks[0]?.id;
+		if (selectedTrackId) update(state, { [SelectedTrackIdKeyByType[config.type]]: selectedTrackId });
+	});
+}
+/**
+* Select audio track orchestration.
+*
+* Selects audio track when:
+* - Presentation exists
+* - No audio track is selected yet
+*
+* Uses language and preference-based selection.
+*
+* @example
+* const cleanup = selectAudioTrack(
+*   { state, owners, events },
+*   { preferredAudioLanguage: 'en' }
+* );
+*/
+function selectAudioTrack({ state }, config = { type: "audio" }) {
+	return effect(() => {
+		const currentState = state.get();
+		if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+		const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === "audio")?.switchingSets[0]?.tracks[0]?.id;
+		if (selectedTrackId) update(state, { selectedAudioTrackId: selectedTrackId });
+	});
+}
+/**
+* Select text track orchestration.
+*
+* Selects text track when:
+* - Presentation exists
+* - No text track is selected yet
+*
+* Note: Currently does not auto-select (user opt-in).
+*
+* @example
+* const cleanup = selectTextTrack({ state, owners, events }, {});
+*/
+function selectTextTrack({ state }, config = { type: "text" }) {
+	return effect(() => {
+		const currentState = state.get();
+		if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+		const selectedTextTrackId = pickTextTrack(currentState.presentation, config);
+		if (selectedTextTrackId) update(state, { selectedTextTrackId });
+	});
+}
+//#endregion
+export { selectAudioTrack, selectTextTrack, selectVideoTrack };
+
+//# sourceMappingURL=select-tracks.js.map

package/dist/dev/core/features/select-tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/core/features/select-tracks.ts"],"sourcesContent":["import { DEFAULT_QUALITY_CONFIG, selectQuality } from '../abr/quality-selection';\nimport { effect } from '../signals/effect';\nimport { type Signal, update } from '../signals/primitives';\nimport type { AudioSelectionSet, Presentation, TrackType, VideoSelectionSet } from '../types';\nimport { SelectedTrackIdKeyByType } from '../utils/track-selection';\n\n/**\n * Default initial bandwidth estimate for cold start (bits per second).\n * Conservative 1 Mbps to avoid over-selecting on slow connections.\n */\nexport const DEFAULT_INITIAL_BANDWIDTH = 1_000_000;\n\n/**\n * State shape for track selection.\n */\nexport interface TrackSelectionState {\n  presentation?: Presentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/**\n * Owners shape for track selection.\n * Currently empty - reserved for future use (e.g., bandwidth estimator).\n */\nexport type TrackSelectionOwners = Record<string, never>;\n\n/**\n * Action types for track selection.\n * Reserved for future event-driven selection triggers.\n */\nexport type TrackSelectionAction = { type: 'presentation-loaded' };\n\n/**\n * Base configuration for track selection.\n * Generic over track type with discriminant `type` field.\n */\nexport interface TrackSelectionConfig<T extends TrackType = TrackType> {\n  type: T;\n}\n\n/**\n * Configuration for video track selection.\n * Generic with default to 'video' for convenience.\n */\nexport interface VideoSelectionConfig<T extends TrackType = 'video'> extends TrackSelectionConfig<T> {\n  /**\n   * Initial bandwidth estimate for cold start (bits per second).\n   * Used to select video quality before we have real measurements.\n   * Default: 1 Mbps (conservative).\n   */\n  initialBandwidth?: number;\n\n  /**\n   * Safety margin for quality selection (0-1).\n   * Default: 0.85 (15% headroom).\n   */\n  safetyMargin?: number;\n}\n\n/**\n * Configuration for audio track selection.\n * Generic with default to 'audio' for convenience.\n */\nexport interface AudioSelectionConfig<T extends TrackType = 'audio'> extends TrackSelectionConfig<T> {\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n}\n\n/**\n * Configuration for text track selection.\n * Generic with default to 'text' for convenience.\n */\nexport interface TextSelectionConfig<T extends TrackType = 'text'> extends TrackSelectionConfig<T> {\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles\n   * in the same language, the regular track MUST contain both forced and\n   * regular content. Therefore, forced-only tracks are redundant and excluded\n   * by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES\n   * will be automatically selected if no user preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n// =============================================================================\n\n/**\n * Pick video track using quality selection algorithm.\n *\n * Uses bandwidth-based selection with safety margin to pick\n * the highest quality track that fits available bandwidth.\n *\n * @param presentation - Presentation with video tracks\n * @param config - Selection configuration (bandwidth, safety margin)\n * @returns Selected video track ID, or undefined if no video tracks\n */\nexport function pickVideoTrack(presentation: Presentation, config: VideoSelectionConfig): string | undefined {\n  const videoSet = presentation.selectionSets.find((set) => set.type === 'video') as VideoSelectionSet | undefined;\n\n  if (!videoSet || videoSet.switchingSets.length === 0) {\n    return undefined;\n  }\n\n  // Get first switching set's tracks (HLS typically has one switching set per type)\n  const switchingSet = videoSet.switchingSets[0];\n  if (!switchingSet || switchingSet.tracks.length === 0) {\n    return undefined;\n  }\n\n  const initialBandwidth = config.initialBandwidth ?? DEFAULT_INITIAL_BANDWIDTH;\n  const safetyMargin = config.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;\n\n  // selectQuality works with both partially resolved and resolved tracks\n  const selected = selectQuality(switchingSet.tracks as any, initialBandwidth, { safetyMargin });\n\n  return selected?.id;\n}\n\n/**\n * Pick audio track.\n *\n * Selection priority:\n * 1. First track matching preferred language (if specified)\n * 2. First default track\n * 3. First audio track\n *\n * @param presentation - Presentation with audio tracks\n * @param config - Selection configuration (preferred language)\n * @returns Selected audio track ID, or undefined if no audio tracks\n */\nexport function pickAudioTrack(presentation: Presentation, config: AudioSelectionConfig): string | undefined {\n  const audioSet = presentation.selectionSets.find((set) => set.type === 'audio') as AudioSelectionSet | undefined;\n\n  if (!audioSet || audioSet.switchingSets.length === 0) {\n    return undefined;\n  }\n\n  // Get first switching set's tracks\n  const switchingSet = audioSet.switchingSets[0];\n  if (!switchingSet || switchingSet.tracks.length === 0) {\n    return undefined;\n  }\n\n  const tracks = switchingSet.tracks;\n\n  // Try preferred language first\n  if (config.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) {\n      return languageMatch.id;\n    }\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) {\n    return defaultTrack.id;\n  }\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Pick text track to activate.\n *\n * Selection priority (if enabled):\n * 1. User preference (preferredSubtitleLanguage)\n * 2. DEFAULT track (if enableDefaultTrack is true and track has DEFAULT=YES + AUTOSELECT=YES)\n * 3. No auto-selection (user opt-in)\n *\n * By default, FORCED tracks are excluded per Apple's HLS spec.\n *\n * @param presentation - Presentation with text tracks\n * @param config - Selection configuration\n * @returns Track ID or undefined (no auto-selection)\n */\nexport function pickTextTrack(presentation: Presentation, config: TextSelectionConfig): string | undefined {\n  const textSet = presentation.selectionSets.find((set) => set.type === 'text');\n  if (!textSet?.switchingSets?.[0]?.tracks.length) return undefined;\n\n  const tracks = textSet.switchingSets[0].tracks;\n\n  // Filter out FORCED tracks by default (following hls.js/http-streaming pattern)\n  // Per Apple spec: regular tracks MUST contain forced content when both exist\n  const availableTracks = config.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config;\n\n  // 1. Preferred language match (if specified)\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  // 2. DEFAULT track (if enabled AND track has both DEFAULT=YES + AUTOSELECT=YES)\n  //    Note: Parser only sets default=true when BOTH attributes present\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  // 3. User opt-in (no auto-selection)\n  return undefined;\n}\n\n/**\n * Check if we can select a track of the given type.\n *\n * Returns true when:\n * - Presentation exists\n * - Has tracks of the specified type\n *\n * Generic over track type - works for video, audio, or text.\n */\nexport function canSelectTrack<T extends TrackType>(\n  state: TrackSelectionState,\n  config: TrackSelectionConfig<T>\n): boolean {\n  return !!state?.presentation?.selectionSets?.find(({ type }) => type === config.type)?.switchingSets?.[0]?.tracks\n    .length;\n}\n\n/**\n * Check if we should select a track of the given type.\n *\n * Returns true when:\n * - Track of this type is not already selected\n *\n * Generic over track type - works for video, audio, or text.\n *\n * @TODO figure out reactive model for ABR cases - right now we're only selecting\n * if we have nothing selected (CJP)\n */\nexport function shouldSelectTrack<T extends TrackType>(\n  state: TrackSelectionState,\n  config: TrackSelectionConfig<T>\n): boolean {\n  return !state[SelectedTrackIdKeyByType[config.type]];\n}\n\n// =============================================================================\n// Orchestrations\n// =============================================================================\n\n/**\n * Select video track orchestration.\n *\n * Selects video track when:\n * - Presentation exists\n * - No video track is selected yet\n *\n * Uses bandwidth-based quality selection algorithm.\n *\n * @example\n * const cleanup = selectVideoTrack(\n *   { state, owners, events },\n *   { initialBandwidth: 2_000_000 }\n * );\n */\nexport function selectVideoTrack<S extends TrackSelectionState>(\n  { state }: { state: Signal<S> },\n  config: VideoSelectionConfig = { type: 'video' }\n): () => void {\n  return effect(() => {\n    const currentState = state.get();\n    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;\n\n    // Just to have basic functionality/POC, simply selecting the first track\n    const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === config.type)\n      ?.switchingSets[0]?.tracks[0]?.id;\n\n    if (selectedTrackId) {\n      const selectedTrackKey = SelectedTrackIdKeyByType[config.type];\n      const patch: Partial<TrackSelectionState> = { [selectedTrackKey]: selectedTrackId };\n      update(state, patch);\n    }\n  });\n}\n\n/**\n * Select audio track orchestration.\n *\n * Selects audio track when:\n * - Presentation exists\n * - No audio track is selected yet\n *\n * Uses language and preference-based selection.\n *\n * @example\n * const cleanup = selectAudioTrack(\n *   { state, owners, events },\n *   { preferredAudioLanguage: 'en' }\n * );\n */\nexport function selectAudioTrack<S extends TrackSelectionState>(\n  { state }: { state: Signal<S> },\n  config: AudioSelectionConfig = { type: 'audio' }\n): () => void {\n  return effect(() => {\n    const currentState = state.get();\n    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;\n\n    // Just to have basic functionality/POC, simply selecting the first track\n    const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === 'audio')\n      ?.switchingSets[0]?.tracks[0]?.id;\n\n    if (selectedTrackId) {\n      const patch: Partial<TrackSelectionState> = { selectedAudioTrackId: selectedTrackId };\n      update(state, patch);\n    }\n  });\n}\n\n/**\n * Select text track orchestration.\n *\n * Selects text track when:\n * - Presentation exists\n * - No text track is selected yet\n *\n * Note: Currently does not auto-select (user opt-in).\n *\n * @example\n * const cleanup = selectTextTrack({ state, owners, events }, {});\n */\nexport function selectTextTrack<S extends TrackSelectionState>(\n  { state }: { state: Signal<S> },\n  config: TextSelectionConfig = { type: 'text' }\n): () => void {\n  return effect(() => {\n    const currentState = state.get();\n    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;\n\n    // Text tracks are user opt-in - don't auto-select\n    const selectedTextTrackId = pickTextTrack(currentState.presentation!, config);\n\n    if (selectedTextTrackId) {\n      const patch: Partial<TrackSelectionState> = { selectedTextTrackId };\n      update(state, patch);\n    }\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAwMA,SAAgB,cAAc,cAA4B,QAAiD;CACzG,MAAM,UAAU,aAAa,cAAc,MAAM,QAAQ,IAAI,SAAS,OAAO;AAC7E,KAAI,CAAC,SAAS,gBAAgB,IAAI,OAAO,OAAQ,QAAO,KAAA;CAExD,MAAM,SAAS,QAAQ,cAAc,GAAG;CAIxC,MAAM,kBAAkB,OAAO,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,OAAO;AAErG,KAAI,gBAAgB,WAAW,EAAG,QAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU;AAGlE,KAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,0BAA0B;AACnG,MAAI,cAAe,QAAO,cAAc;;AAK1C,KAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,KAAK;AAC5E,MAAI,aAAc,QAAO,aAAa;;;;;;;;;;;;AAgB1C,SAAgB,eACd,OACA,QACS;AACT,QAAO,CAAC,CAAC,OAAO,cAAc,eAAe,MAAM,EAAE,WAAW,SAAS,OAAO,KAAK,EAAE,gBAAgB,IAAI,OACxG;;;;;;;;;;;;;AAcL,SAAgB,kBACd,OACA,QACS;AACT,QAAO,CAAC,MAAM,yBAAyB,OAAO;;;;;;;;;;;;;;;;;AAsBhD,SAAgB,iBACd,EAAE,SACF,SAA+B,EAAE,MAAM,SAAS,EACpC;AACZ,QAAO,aAAa;EAClB,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,eAAe,cAAc,OAAO,IAAI,CAAC,kBAAkB,cAAc,OAAO,CAAE;EAGvF,MAAM,kBAAkB,aAAa,cAAc,cAAc,MAAM,EAAE,WAAW,SAAS,OAAO,KAAK,EACrG,cAAc,IAAI,OAAO,IAAI;AAEjC,MAAI,gBAGF,QAAO,OADqC,GADnB,yBAAyB,OAAO,QACS,iBAAiB,CAC/D;GAEtB;;;;;;;;;;;;;;;;;AAkBJ,SAAgB,iBACd,EAAE,SACF,SAA+B,EAAE,MAAM,SAAS,EACpC;AACZ,QAAO,aAAa;EAClB,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,eAAe,cAAc,OAAO,IAAI,CAAC,kBAAkB,cAAc,OAAO,CAAE;EAGvF,MAAM,kBAAkB,aAAa,cAAc,cAAc,MAAM,EAAE,WAAW,SAAS,QAAQ,EACjG,cAAc,IAAI,OAAO,IAAI;AAEjC,MAAI,gBAEF,QAAO,OADqC,EAAE,sBAAsB,iBAAiB,CACjE;GAEtB;;;;;;;;;;;;;;AAeJ,SAAgB,gBACd,EAAE,SACF,SAA8B,EAAE,MAAM,QAAQ,EAClC;AACZ,QAAO,aAAa;EAClB,MAAM,eAAe,MAAM,KAAK;AAChC,MAAI,CAAC,eAAe,cAAc,OAAO,IAAI,CAAC,kBAAkB,cAAc,OAAO,CAAE;EAGvF,MAAM,sBAAsB,cAAc,aAAa,cAAe,OAAO;AAE7E,MAAI,oBAEF,QAAO,OADqC,EAAE,qBAAqB,CAC/C;GAEtB"}

package/dist/dev/core/features/sync-preload-attribute.js

@@ -0,0 +1,26 @@
+import { effect } from "../signals/effect.js";
+import { computed, update } from "../signals/primitives.js";
+//#region src/core/features/sync-preload-attribute.ts
+/**
+* Syncs preload attribute from mediaElement to state.
+*
+* Watches the owners signal for mediaElement changes and copies the
+* preload attribute to state when no explicit value has been set.
+* An explicit value (set via SpfMedia.preload) always wins.
+*
+* @example
+* const cleanup = syncPreloadAttribute({ state, owners });
+*/
+function syncPreloadAttribute({ state, owners }) {
+	const mediaElement = computed(() => owners.get().mediaElement);
+	return effect(() => {
+		if (state.get().preload !== void 0) return;
+		const preload = mediaElement.get()?.preload || void 0;
+		if (preload === void 0) return;
+		update(state, { preload });
+	});
+}
+//#endregion
+export { syncPreloadAttribute };
+
+//# sourceMappingURL=sync-preload-attribute.js.map

package/dist/dev/core/features/sync-preload-attribute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-preload-attribute.js","names":[],"sources":["../../../../src/core/features/sync-preload-attribute.ts"],"sourcesContent":["import { effect } from '../signals/effect';\nimport { computed, type Signal, update } from '../signals/primitives';\nimport type { MediaElementLike } from '../types';\nimport type { PresentationState } from './resolve-presentation';\n\n/**\n * Owners shape for preload attribute sync.\n */\nexport interface PlatformOwners {\n  mediaElement?: MediaElementLike | undefined;\n}\n\n/**\n * Syncs preload attribute from mediaElement to state.\n *\n * Watches the owners signal for mediaElement changes and copies the\n * preload attribute to state when no explicit value has been set.\n * An explicit value (set via SpfMedia.preload) always wins.\n *\n * @example\n * const cleanup = syncPreloadAttribute({ state, owners });\n */\nexport function syncPreloadAttribute<S extends PresentationState, O extends PlatformOwners>({\n  state,\n  owners,\n}: {\n  state: Signal<S>;\n  owners: Signal<O>;\n}): () => void {\n  const mediaElement = computed(() => owners.get().mediaElement);\n  return effect(() => {\n    if (state.get().preload !== undefined) return;\n    const preload = mediaElement.get()?.preload || undefined;\n    if (preload === undefined) return;\n    const patch: Partial<PresentationState> = { preload: preload as 'auto' | 'metadata' | 'none' };\n    update(state, patch);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;AAsBA,SAAgB,qBAA4E,EAC1F,OACA,UAIa;CACb,MAAM,eAAe,eAAe,OAAO,KAAK,CAAC,aAAa;AAC9D,QAAO,aAAa;AAClB,MAAI,MAAM,KAAK,CAAC,YAAY,KAAA,EAAW;EACvC,MAAM,UAAU,aAAa,KAAK,EAAE,WAAW,KAAA;AAC/C,MAAI,YAAY,KAAA,EAAW;AAE3B,SAAO,OADmC,EAAW,SAAyC,CAC1E;GACpB"}