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

package/dist/dev/playback/behaviors/resolve-presentation.js

@@ -0,0 +1,85 @@
+import { computed } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
+import { isResolvedPresentation } from "../../media/types/index.js";
+import { fetchResolvable, getResponseText } from "../../network/fetch.js";
+import { isBlockingPreload } from "../../media/utils/preload.js";
+//#region src/playback/behaviors/resolve-presentation.ts
+/**
+* **Resolve an unresolved presentation by fetching and parsing its manifest.**
+*
+* Reads `state.presentation`; when it holds `{ url }` (unresolved) and the
+* preload / load-activation gate is met, fetches the manifest, parses it via
+* the **required** `config.parsePresentation`, and writes the resolved
+* `Presentation` back to the same slot. The behavior is format-neutral: the
+* composing engine wires in its parser (e.g. the HLS engine supplies the
+* multivariant-playlist parser).
+*
+* Source-identity-driven, expressed as a 4-state machine:
+*
+* ```
+* 'preconditions-unmet' → 'idle' → 'resolving' → 'resolved'
+* ```
+*
+* - `'preconditions-unmet'`: no presentation, or presentation has no URL.
+* - `'idle'`: URL present, unresolved, gate unmet (blocking preload + no
+*   load-activation). Waits for the gate to open.
+* - `'resolving'`: URL present, unresolved, gate met. Entry starts the fetch
+*   and returns the AbortController — the reactor calls `.abort()` on state
+*   exit, so source change / gate-close / destroy all cancel cleanly.
+* - `'resolved'`: `state.presentation` holds a resolved `Presentation`.
+*
+* Gate semantics: `state.preload` (or `config.defaultPreload`, default
+* `'metadata'`, when state.preload is unset) blocks resolution when its
+* value is `'none'` (see `isBlockingPreload` in `media/utils/preload`).
+* `state.loadActivated` is an override — true bypasses the preload gate
+* entirely.
+*
+* Multi-writer with the engine adapter, which writes the initial unresolved
+* `{ url }` to `state.presentation` from src input. Different domains
+* (config-input vs. derived state via fetch) — legitimate multi-writer.
+*/
+function deriveState(presentation, preload, loadActivated, defaultPreload) {
+	if (!presentation?.url) return "preconditions-unmet";
+	if (isResolvedPresentation(presentation)) return "resolved";
+	return !!loadActivated || !isBlockingPreload(preload, defaultPreload) ? "resolving" : "idle";
+}
+function resolvePresentationSetup({ state, config }) {
+	const { parsePresentation } = config;
+	const defaultPreload = config.defaultPreload ?? "metadata";
+	const derivedStateSignal = computed(() => deriveState(state.presentation.get(), state.preload.get(), state.loadActivated.get(), defaultPreload));
+	return createMachineReactor({
+		initial: "preconditions-unmet",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"preconditions-unmet": {},
+			idle: {},
+			resolving: { entry: () => {
+				const presentation = state.presentation.get();
+				const ac = new AbortController();
+				fetchResolvable(presentation, { signal: ac.signal }).then((response) => getResponseText(response)).then((text) => {
+					const parsed = parsePresentation(text, presentation);
+					state.presentation.set(parsed);
+				}).catch((error) => {
+					if (error instanceof Error && error.name === "AbortError") return;
+					console.error("[resolvePresentation] manifest fetch/parse failed:", error);
+				});
+				return ac;
+			} },
+			resolved: {}
+		}
+	});
+}
+const resolvePresentation = defineBehavior({
+	stateKeys: [
+		"presentation",
+		"preload",
+		"loadActivated"
+	],
+	contextKeys: [],
+	setup: resolvePresentationSetup
+});
+//#endregion
+export { resolvePresentation };
+
+//# sourceMappingURL=resolve-presentation.js.map

package/dist/dev/playback/behaviors/resolve-presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-presentation.js","names":[],"sources":["../../../../src/playback/behaviors/resolve-presentation.ts"],"sourcesContent":["/**\n * **Resolve an unresolved presentation by fetching and parsing its manifest.**\n *\n * Reads `state.presentation`; when it holds `{ url }` (unresolved) and the\n * preload / load-activation gate is met, fetches the manifest, parses it via\n * the **required** `config.parsePresentation`, and writes the resolved\n * `Presentation` back to the same slot. The behavior is format-neutral: the\n * composing engine wires in its parser (e.g. the HLS engine supplies the\n * multivariant-playlist parser).\n *\n * Source-identity-driven, expressed as a 4-state machine:\n *\n * ```\n * 'preconditions-unmet' → 'idle' → 'resolving' → 'resolved'\n * ```\n *\n * - `'preconditions-unmet'`: no presentation, or presentation has no URL.\n * - `'idle'`: URL present, unresolved, gate unmet (blocking preload + no\n *   load-activation). Waits for the gate to open.\n * - `'resolving'`: URL present, unresolved, gate met. Entry starts the fetch\n *   and returns the AbortController — the reactor calls `.abort()` on state\n *   exit, so source change / gate-close / destroy all cancel cleanly.\n * - `'resolved'`: `state.presentation` holds a resolved `Presentation`.\n *\n * Gate semantics: `state.preload` (or `config.defaultPreload`, default\n * `'metadata'`, when state.preload is unset) blocks resolution when its\n * value is `'none'` (see `isBlockingPreload` in `media/utils/preload`).\n * `state.loadActivated` is an override — true bypasses the preload gate\n * entirely.\n *\n * Multi-writer with the engine adapter, which writes the initial unresolved\n * `{ url }` to `state.presentation` from src input. Different domains\n * (config-input vs. derived state via fetch) — legitimate multi-writer.\n */\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport type { Reactor } from '../../core/reactors/create-machine-reactor';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport { isResolvedPresentation, type MaybeResolvedPresentation, type Presentation } from '../../media/types';\nimport { DEFAULT_PRELOAD, isBlockingPreload, type StandardPreload } from '../../media/utils/preload';\nimport { fetchResolvable, getResponseText } from '../../network/fetch';\n\nexport interface PresentationState {\n  presentation?: MaybeResolvedPresentation;\n  preload?: 'auto' | 'metadata' | 'none' | undefined;\n  /** True once a preload-overriding event has fired for the current source — enables resolution regardless of preload. */\n  loadActivated?: boolean;\n}\n\nexport type ParsePresentation = (text: string, presentation: MaybeResolvedPresentation) => Presentation;\n\nexport interface ResolvePresentationConfig {\n  /**\n   * Parses a manifest body into a resolved `Presentation`. **Required** —\n   * the behavior is format-neutral and the composing engine supplies its\n   * own parser (HLS, DASH, etc.).\n   */\n  parsePresentation: ParsePresentation;\n  /**\n   * Fallback used when `state.preload` is unset (undefined / empty) for the\n   * resolution-gate decision. Defaults to `'metadata'`, matching\n   * `syncPreload`'s own `defaultPreload`.\n   */\n  defaultPreload?: StandardPreload;\n}\n\nexport type ResolvePresentationState = 'preconditions-unmet' | 'idle' | 'resolving' | 'resolved';\n\nfunction deriveState(\n  presentation: MaybeResolvedPresentation | undefined,\n  preload: PresentationState['preload'],\n  loadActivated: boolean | undefined,\n  defaultPreload: StandardPreload\n): ResolvePresentationState {\n  if (!presentation?.url) return 'preconditions-unmet';\n  if (isResolvedPresentation(presentation)) return 'resolved';\n  const gateOpen = !!loadActivated || !isBlockingPreload(preload, defaultPreload);\n  return gateOpen ? 'resolving' : 'idle';\n}\n\nfunction resolvePresentationSetup({\n  state,\n  config,\n}: {\n  state: {\n    presentation: Signal<PresentationState['presentation']>;\n    preload: ReadonlySignal<PresentationState['preload']>;\n    loadActivated: ReadonlySignal<PresentationState['loadActivated']>;\n  };\n  config: ResolvePresentationConfig;\n}): Reactor<ResolvePresentationState | 'destroying' | 'destroyed'> {\n  const { parsePresentation } = config;\n  const defaultPreload: StandardPreload = config.defaultPreload ?? DEFAULT_PRELOAD;\n\n  const derivedStateSignal = computed(() =>\n    deriveState(state.presentation.get(), state.preload.get(), state.loadActivated.get(), defaultPreload)\n  );\n\n  return createMachineReactor<ResolvePresentationState>({\n    initial: 'preconditions-unmet',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'preconditions-unmet': {},\n      idle: {},\n      resolving: {\n        entry: () => {\n          const presentation = state.presentation.get()!;\n          const ac = new AbortController();\n\n          fetchResolvable(presentation, { signal: ac.signal })\n            .then((response) => getResponseText(response))\n            .then((text) => {\n              const parsed = parsePresentation(text, presentation);\n              state.presentation.set(parsed);\n            })\n            .catch((error) => {\n              if (error instanceof Error && error.name === 'AbortError') return;\n              // TODO(error-management): route to a state-error slot once one exists.\n              console.error('[resolvePresentation] manifest fetch/parse failed:', error);\n            });\n\n          return ac;\n        },\n      },\n      resolved: {},\n    },\n  });\n}\n\nexport const resolvePresentation = defineBehavior({\n  stateKeys: ['presentation', 'preload', 'loadActivated'],\n  contextKeys: [],\n  setup: resolvePresentationSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,SAAS,YACP,cACA,SACA,eACA,gBAC0B;AAC1B,KAAI,CAAC,cAAc,IAAK,QAAO;AAC/B,KAAI,uBAAuB,aAAa,CAAE,QAAO;AAEjD,QADiB,CAAC,CAAC,iBAAiB,CAAC,kBAAkB,SAAS,eAAe,GAC7D,cAAc;;AAGlC,SAAS,yBAAyB,EAChC,OACA,UAQiE;CACjE,MAAM,EAAE,sBAAsB;CAC9B,MAAM,iBAAkC,OAAO,kBAAA;CAE/C,MAAM,qBAAqB,eACzB,YAAY,MAAM,aAAa,KAAK,EAAE,MAAM,QAAQ,KAAK,EAAE,MAAM,cAAc,KAAK,EAAE,eAAe,CACtG;AAED,QAAO,qBAA+C;EACpD,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,uBAAuB,EAAE;GACzB,MAAM,EAAE;GACR,WAAW,EACT,aAAa;IACX,MAAM,eAAe,MAAM,aAAa,KAAK;IAC7C,MAAM,KAAK,IAAI,iBAAiB;AAEhC,oBAAgB,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAAC,CACjD,MAAM,aAAa,gBAAgB,SAAS,CAAC,CAC7C,MAAM,SAAS;KACd,MAAM,SAAS,kBAAkB,MAAM,aAAa;AACpD,WAAM,aAAa,IAAI,OAAO;MAC9B,CACD,OAAO,UAAU;AAChB,SAAI,iBAAiB,SAAS,MAAM,SAAS,aAAc;AAE3D,aAAQ,MAAM,sDAAsD,MAAM;MAC1E;AAEJ,WAAO;MAEV;GACD,UAAU,EAAE;GACb;EACF,CAAC;;AAGJ,MAAa,sBAAsB,eAAe;CAChD,WAAW;EAAC;EAAgB;EAAW;EAAgB;CACvD,aAAa,EAAE;CACf,OAAO;CACR,CAAC"}

package/dist/dev/playback/behaviors/resolve-track.js

@@ -0,0 +1,97 @@
+import { computed, peek, update } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { ConcurrentRunner, Task } from "../../core/tasks/task.js";
+import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
+import { isResolvedPresentation, isResolvedTrack } from "../../media/types/index.js";
+import { findTrack, updateTrackInPresentation } from "../../media/utils/tracks.js";
+import { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from "./track-types.js";
+import { fetchResolvable, getResponseText } from "../../network/fetch.js";
+import { parseMediaPlaylist } from "../../media/hls/parse-media-playlist.js";
+//#region src/playback/behaviors/resolve-track.ts
+function setupTrackResolution({ state, config: { selectedKey, findTrackToResolve } }) {
+	const runner = new ConcurrentRunner();
+	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: () => () => runner.abortAll(),
+				effects: [() => {
+					const presentation = peek(state.presentation);
+					const trackId = state[selectedKey].get();
+					if (!presentation || !trackId) return;
+					const track = findTrackToResolve(presentation, trackId);
+					if (!track || isResolvedTrack(track)) return;
+					runner.schedule(new Task(async (signal) => {
+						const mediaTrack = parseMediaPlaylist(await getResponseText(await fetchResolvable(track, { signal })), track);
+						update(state.presentation, (current) => isResolvedPresentation(current) ? updateTrackInPresentation(current, mediaTrack) : current);
+					}, { id: track.id }));
+				}]
+			}
+		}
+	});
+}
+const VIDEO_TRACK_RESOLUTION_CONFIG = {
+	...VIDEO_TYPE_CONFIG,
+	findTrackToResolve: (presentation, trackId) => findTrack(presentation, "video", trackId)
+};
+const AUDIO_TRACK_RESOLUTION_CONFIG = {
+	...AUDIO_TYPE_CONFIG,
+	findTrackToResolve: (presentation, trackId) => findTrack(presentation, "audio", trackId)
+};
+const TEXT_TRACK_RESOLUTION_CONFIG = {
+	...TEXT_TYPE_CONFIG,
+	findTrackToResolve: (presentation, trackId) => findTrack(presentation, "text", trackId)
+};
+/**
+* Resolve unresolved video tracks. Schedules a fetch task whenever the
+* selected video track is partially resolved, parses the manifest, and
+* writes the resolved track back into `state.presentation`.
+*/
+const resolveVideoTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedVideoTrackId"],
+	contextKeys: [],
+	setup: ({ state, config = {} }) => setupTrackResolution({
+		state,
+		config: {
+			...VIDEO_TRACK_RESOLUTION_CONFIG,
+			...config
+		}
+	})
+});
+/**
+* Resolve unresolved audio tracks. Same shape as `resolveVideoTrack`,
+* narrowed to audio.
+*/
+const resolveAudioTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedAudioTrackId"],
+	contextKeys: [],
+	setup: ({ state, config = {} }) => setupTrackResolution({
+		state,
+		config: {
+			...AUDIO_TRACK_RESOLUTION_CONFIG,
+			...config
+		}
+	})
+});
+/**
+* Resolve unresolved text tracks. Same shape as `resolveVideoTrack`,
+* narrowed to text.
+*/
+const resolveTextTrack = defineBehavior({
+	stateKeys: ["presentation", "selectedTextTrackId"],
+	contextKeys: [],
+	setup: ({ state, config = {} }) => setupTrackResolution({
+		state,
+		config: {
+			...TEXT_TRACK_RESOLUTION_CONFIG,
+			...config
+		}
+	})
+});
+//#endregion
+export { resolveAudioTrack, resolveTextTrack, resolveVideoTrack };
+
+//# sourceMappingURL=resolve-track.js.map

package/dist/dev/playback/behaviors/resolve-track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-track.js","names":[],"sources":["../../../../src/playback/behaviors/resolve-track.ts"],"sourcesContent":["import { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, peek, type ReadonlySignal, type Signal, update } from '../../core/signals/primitives';\nimport { ConcurrentRunner, Task } from '../../core/tasks/task';\nimport { parseMediaPlaylist } from '../../media/hls/parse-media-playlist';\nimport type { MaybeResolvedPresentation, PartiallyResolvedTrack, ResolvedTrack } from '../../media/types';\nimport { isResolvedPresentation, isResolvedTrack } from '../../media/types';\nimport { findTrack, updateTrackInPresentation } from '../../media/utils/tracks';\nimport { fetchResolvable, getResponseText } from '../../network/fetch';\nimport { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG } from './track-types';\n\n// ============================================================================\n// Specialization helper\n//\n// `setupTrackResolution` has the same shape as a Behavior `setup` function:\n// `({ state, config }) => cleanup`. Each `resolveXTrack` export below calls it\n// from inside its own `defineBehavior` setup, supplying its per-type config\n// inline. The orchestration — gate on a selection, short-circuit when the\n// track is already resolved or missing, schedule the fetch+parse, and patch\n// the resolved track back into `state.presentation` — is shared.\n// ============================================================================\n\n/**\n * State shape for track resolution. Uses `MaybeResolvedPresentation` so it\n * matches the engine's slot type; resolution narrows internally.\n */\nexport interface ResolveTrackState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\ntype SelectedTrackKey = 'selectedVideoTrackId' | 'selectedAudioTrackId' | 'selectedTextTrackId';\n\ntype ResolveTrackStateMap<K extends SelectedTrackKey> = {\n  presentation: Signal<ResolveTrackState['presentation']>;\n} & { [P in K]: ReadonlySignal<ResolveTrackState[P]> };\n\ninterface TrackResolutionConfig<K extends SelectedTrackKey> {\n  selectedKey: K;\n  findTrackToResolve: (\n    presentation: MaybeResolvedPresentation,\n    trackId: string\n  ) => PartiallyResolvedTrack | ResolvedTrack | undefined;\n}\n\nfunction setupTrackResolution<K extends SelectedTrackKey>({\n  state,\n  config: { selectedKey, findTrackToResolve },\n}: {\n  state: ResolveTrackStateMap<K>;\n  config: TrackResolutionConfig<K>;\n}) {\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  // Reactor states model the FSM the previous effect-based body was\n  // hand-rolling. 'presentation-resolved' is entered when the\n  // presentation is fully parsed (has a Ham id + selectionSets); leaving\n  // it (presentation cleared or reset to an unresolved value) aborts all\n  // in-flight tasks via the entry-cleanup. Most URL changes go through\n  // 'presentation-unresolved' naturally (set undefined → set new partial\n  // → re-parse), so the common case is covered by state-exit alone; the\n  // task body's commit-time id check covers the pathological\n  // resolved→resolved-without-unresolved transition.\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` runs on state entry; the function it returns is the\n        // state-exit cleanup. Returning `() => runner.abortAll()` binds\n        // abort-of-in-flight-resolutions to leaving 'presentation-resolved'\n        // (presentation cleared/reset, or behavior destroyed) —\n        // source-change cancellation expressed structurally through the\n        // state machine.\n        entry: () => () => runner.abortAll(),\n        effects: [\n          () => {\n            // The reactor's state transitions handle relevant presentation\n            // changes (presentation-resolved ↔ presentation-unresolved);\n            // within 'presentation-resolved' we peek (untracked read) so\n            // internal updates (segments added by sibling tasks) don't\n            // re-fire the effect.\n            const presentation = peek(state.presentation);\n            const trackId = state[selectedKey].get();\n            if (!presentation || !trackId) return;\n\n            const track = findTrackToResolve(presentation, trackId);\n            if (!track || isResolvedTrack(track)) return;\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(track, { signal });\n                  const text = await getResponseText(response);\n                  const mediaTrack = parseMediaPlaylist(text, track);\n\n                  // Updater handles undefined inputs by returning current\n                  // unchanged; isResolvedPresentation narrows for the patch.\n                  // State-exit on resolving→unresolved fires runner.abortAll\n                  // before any URL change settles, and per the Fetch spec the\n                  // signal abort cancels in-flight body reads — so by the\n                  // time we reach this point the presentation we resolved\n                  // against is the live one.\n                  update(state.presentation, (current) =>\n                    isResolvedPresentation(current) ? updateTrackInPresentation(current, mediaTrack) : current\n                  );\n                },\n                { id: track.id }\n              )\n            );\n          },\n        ],\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Per-helper-per-type configs — defaults that variants spread engine config over\n// ============================================================================\n\nconst VIDEO_TRACK_RESOLUTION_CONFIG = {\n  ...VIDEO_TYPE_CONFIG,\n  findTrackToResolve: (presentation: MaybeResolvedPresentation, trackId: string) =>\n    findTrack(presentation, 'video', trackId),\n} as const;\n\nconst AUDIO_TRACK_RESOLUTION_CONFIG = {\n  ...AUDIO_TYPE_CONFIG,\n  findTrackToResolve: (presentation: MaybeResolvedPresentation, trackId: string) =>\n    findTrack(presentation, 'audio', trackId),\n} as const;\n\nconst TEXT_TRACK_RESOLUTION_CONFIG = {\n  ...TEXT_TYPE_CONFIG,\n  findTrackToResolve: (presentation: MaybeResolvedPresentation, trackId: string) =>\n    findTrack(presentation, 'text', trackId),\n} as const;\n\n// ============================================================================\n// Specialized exports — one per track type\n// ============================================================================\n\n/**\n * Resolve unresolved video tracks. Schedules a fetch task whenever the\n * selected video track is partially resolved, parses the manifest, and\n * writes the resolved track back into `state.presentation`.\n */\nexport const resolveVideoTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedVideoTrackId'],\n  contextKeys: [],\n  setup: ({ state, config = {} }: { state: ResolveTrackStateMap<'selectedVideoTrackId'>; config?: object }) =>\n    setupTrackResolution({\n      state,\n      config: { ...VIDEO_TRACK_RESOLUTION_CONFIG, ...config },\n    }),\n});\n\n/**\n * Resolve unresolved audio tracks. Same shape as `resolveVideoTrack`,\n * narrowed to audio.\n */\nexport const resolveAudioTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedAudioTrackId'],\n  contextKeys: [],\n  setup: ({ state, config = {} }: { state: ResolveTrackStateMap<'selectedAudioTrackId'>; config?: object }) =>\n    setupTrackResolution({\n      state,\n      config: { ...AUDIO_TRACK_RESOLUTION_CONFIG, ...config },\n    }),\n});\n\n/**\n * Resolve unresolved text tracks. Same shape as `resolveVideoTrack`,\n * narrowed to text.\n */\nexport const resolveTextTrack = defineBehavior({\n  stateKeys: ['presentation', 'selectedTextTrackId'],\n  contextKeys: [],\n  setup: ({ state, config = {} }: { state: ResolveTrackStateMap<'selectedTextTrackId'>; config?: object }) =>\n    setupTrackResolution({\n      state,\n      config: { ...TEXT_TRACK_RESOLUTION_CONFIG, ...config },\n    }),\n});\n"],"mappings":";;;;;;;;;;AA+CA,SAAS,qBAAiD,EACxD,OACA,QAAQ,EAAE,aAAa,wBAItB;CAID,MAAM,SAAS,IAAI,kBAAkB;CAWrC,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;IAOvB,mBAAmB,OAAO,UAAU;IACpC,SAAS,OACD;KAMJ,MAAM,eAAe,KAAK,MAAM,aAAa;KAC7C,MAAM,UAAU,MAAM,aAAa,KAAK;AACxC,SAAI,CAAC,gBAAgB,CAAC,QAAS;KAE/B,MAAM,QAAQ,mBAAmB,cAAc,QAAQ;AACvD,SAAI,CAAC,SAAS,gBAAgB,MAAM,CAAE;AAEtC,YAAO,SAGL,IAAI,KACF,OAAO,WAAW;MAGhB,MAAM,aAAa,mBADN,MAAM,gBADF,MAAM,gBAAgB,OAAO,EAAE,QAAQ,CAAC,CACb,EACA,MAAM;AASlD,aAAO,MAAM,eAAe,YAC1B,uBAAuB,QAAQ,GAAG,0BAA0B,SAAS,WAAW,GAAG,QACpF;QAEH,EAAE,IAAI,MAAM,IAAI,CACjB,CACF;MAEJ;IACF;GACF;EACF,CAAC;;AAOJ,MAAM,gCAAgC;CACpC,GAAG;CACH,qBAAqB,cAAyC,YAC5D,UAAU,cAAc,SAAS,QAAQ;CAC5C;AAED,MAAM,gCAAgC;CACpC,GAAG;CACH,qBAAqB,cAAyC,YAC5D,UAAU,cAAc,SAAS,QAAQ;CAC5C;AAED,MAAM,+BAA+B;CACnC,GAAG;CACH,qBAAqB,cAAyC,YAC5D,UAAU,cAAc,QAAQ,QAAQ;CAC3C;;;;;;AAWD,MAAa,oBAAoB,eAAe;CAC9C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,SAAS,EAAE,OAC1B,qBAAqB;EACnB;EACA,QAAQ;GAAE,GAAG;GAA+B,GAAG;GAAQ;EACxD,CAAC;CACL,CAAC;;;;;AAMF,MAAa,oBAAoB,eAAe;CAC9C,WAAW,CAAC,gBAAgB,uBAAuB;CACnD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,SAAS,EAAE,OAC1B,qBAAqB;EACnB;EACA,QAAQ;GAAE,GAAG;GAA+B,GAAG;GAAQ;EACxD,CAAC;CACL,CAAC;;;;;AAMF,MAAa,mBAAmB,eAAe;CAC7C,WAAW,CAAC,gBAAgB,sBAAsB;CAClD,aAAa,EAAE;CACf,QAAQ,EAAE,OAAO,SAAS,EAAE,OAC1B,qBAAqB;EACnB;EACA,QAAQ;GAAE,GAAG;GAA8B,GAAG;GAAQ;EACvD,CAAC;CACL,CAAC"}

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

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

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

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

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

@@ -0,0 +1,59 @@
+import { computed, peek } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { effect } from "../../core/signals/effect.js";
+import { isStandardPreload } from "../../media/utils/preload.js";
+//#region src/playback/behaviors/sync-preload.ts
+/**
+* **Bidirectional sync between `state.preload` and `mediaElement.preload`.**
+*
+* Two effects:
+* - **Read (DOM → state)** — on `context.mediaElement` swap or
+*   `state.presentation.url` change, copies `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/dev/playback/behaviors/sync-preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-preload.js","names":[],"sources":["../../../../src/playback/behaviors/sync-preload.ts"],"sourcesContent":["/**\n * **Bidirectional sync between `state.preload` and `mediaElement.preload`.**\n *\n * Two effects:\n * - **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/dev/playback/behaviors/track-types.js

@@ -0,0 +1,61 @@
+//#region src/playback/behaviors/track-types.ts
+/**
+* **Per-type config bundles for per-type behavior variants.**
+*
+* Each `*_TYPE_CONFIG` constant names the per-type slot keys that
+* per-type-variant setup-shape helpers consume. Variants reference the
+* shared constant at their `defineBehavior` setup body rather than
+* constructing the config inline, so the per-type identity (which state
+* slot, which context slot, which discriminant) lives in one place per
+* type.
+*
+* Variants spread their composition-time `config` over the defaults so
+* engines can layer composition-supplied additions on top (e.g. a
+* custom fetch closure, a non-default segment resolver). Defaults
+* first, engine config second.
+*
+* Helpers continue to consume their slice via the existing typed-key
+* generics (`<K extends SelectedTrackKey>` etc.); the extra fields on
+* the config object (carrying facets other helpers care about) are fine
+* under structural typing.
+*/
+/**
+* Type-identity bundle for video-track-typed behaviors.
+*
+* @see setupVideoBufferActors, loadVideoSegments
+*/
+const VIDEO_TYPE_CONFIG = {
+	type: "video",
+	selectedKey: "selectedVideoTrackId",
+	actorKey: "videoBufferActor",
+	loaderKey: "videoSegmentLoaderActor"
+};
+/**
+* Type-identity bundle for audio-track-typed behaviors.
+*
+* @see setupAudioBufferActors, loadAudioSegments
+*/
+const AUDIO_TYPE_CONFIG = {
+	type: "audio",
+	selectedKey: "selectedAudioTrackId",
+	actorKey: "audioBufferActor",
+	loaderKey: "audioSegmentLoaderActor"
+};
+/**
+* Type-identity bundle for text-track-typed behaviors. Text tracks have
+* no `SourceBufferActor` (MSE doesn't apply), so this bundle omits
+* `actorKey`. The `loaderKey` points at the text-track-segment-loader
+* actor (a `MessageActor` with continue-vs-preempt semantics, parallel
+* to v/a's `SegmentLoaderActor`).
+*
+* @see loadTextTrackSegments, setupTextTrackActors
+*/
+const TEXT_TYPE_CONFIG = {
+	type: "text",
+	selectedKey: "selectedTextTrackId",
+	loaderKey: "textTrackSegmentLoaderActor"
+};
+//#endregion
+export { AUDIO_TYPE_CONFIG, TEXT_TYPE_CONFIG, VIDEO_TYPE_CONFIG };
+
+//# sourceMappingURL=track-types.js.map

package/dist/dev/playback/behaviors/track-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/behaviors/track-types.ts"],"sourcesContent":["/**\n * **Per-type config bundles for per-type behavior variants.**\n *\n * Each `*_TYPE_CONFIG` constant names the per-type slot keys that\n * per-type-variant setup-shape helpers consume. Variants reference the\n * shared constant at their `defineBehavior` setup body rather than\n * constructing the config inline, so the per-type identity (which state\n * slot, which context slot, which discriminant) lives in one place per\n * type.\n *\n * Variants spread their composition-time `config` over the defaults so\n * engines can layer composition-supplied additions on top (e.g. a\n * custom fetch closure, a non-default segment resolver). Defaults\n * first, engine config second.\n *\n * Helpers continue to consume their slice via the existing typed-key\n * generics (`<K extends SelectedTrackKey>` etc.); the extra fields on\n * the config object (carrying facets other helpers care about) are fine\n * under structural typing.\n */\n\n/**\n * Type-identity bundle for video-track-typed behaviors.\n *\n * @see setupVideoBufferActors, loadVideoSegments\n */\nexport const VIDEO_TYPE_CONFIG = {\n  type: 'video',\n  selectedKey: 'selectedVideoTrackId',\n  actorKey: 'videoBufferActor',\n  loaderKey: 'videoSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for audio-track-typed behaviors.\n *\n * @see setupAudioBufferActors, loadAudioSegments\n */\nexport const AUDIO_TYPE_CONFIG = {\n  type: 'audio',\n  selectedKey: 'selectedAudioTrackId',\n  actorKey: 'audioBufferActor',\n  loaderKey: 'audioSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for text-track-typed behaviors. Text tracks have\n * no `SourceBufferActor` (MSE doesn't apply), so this bundle omits\n * `actorKey`. The `loaderKey` points at the text-track-segment-loader\n * actor (a `MessageActor` with continue-vs-preempt semantics, parallel\n * to v/a's `SegmentLoaderActor`).\n *\n * @see loadTextTrackSegments, setupTextTrackActors\n */\nexport const TEXT_TYPE_CONFIG = {\n  type: 'text',\n  selectedKey: 'selectedTextTrackId',\n  loaderKey: 'textTrackSegmentLoaderActor',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;AAOD,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;;;;;AAWD,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;CACZ"}

package/dist/dev/{dom/playback-engine → playback/engines/hls}/adapter.d.ts

@@ -1,11 +1,15 @@
-import { PlaybackEngine } from "./engine.js";
+import { Composition } from "../../../core/composition/create-composition.js";
+import { SimpleHlsEngineContext, SimpleHlsEngineState } from "./engine.js";
 import { Constructor, MixinReturn } from "@videojs/utils/types";
 
-//#region src/dom/playback-engine/adapter.d.ts
-interface SpfMediaAPI {
-  readonly engine: PlaybackEngine;
+//#region src/playback/engines/hls/adapter.d.ts
+interface SimpleHlsMediaProps {
   src: string;
   preload: '' | 'none' | 'metadata' | 'auto';
+}
+declare const simpleHlsMediaDefaultProps: SimpleHlsMediaProps;
+interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {
+  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;
   attach(mediaElement: HTMLMediaElement): void;
   detach(): void;
   destroy(): void;
@@ -23,18 +27,18 @@ interface SpfMediaAPI {
  * changes and re-applied to the new engine automatically.
  *
  * @example
- * class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+ * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}
  *
  * const media = new SimpleHlsMedia();
  * media.attach(document.querySelector('video'));
  * media.src = 'https://stream.mux.com/abc123.m3u8';
  */
-declare function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, SpfMediaAPI>;
-declare const SpfMedia_base: MixinReturn<{
+declare function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, SimpleHlsMediaAPI>;
+declare const SimpleHlsMediaElement_base: MixinReturn<{
   new (): {};
-}, SpfMediaAPI>;
+}, SimpleHlsMediaAPI>;
 /** Standalone SPF media adapter with no base class. */
-declare class SpfMedia extends SpfMedia_base {}
+declare class SimpleHlsMediaElement extends SimpleHlsMediaElement_base {}
 //#endregion
-export { SpfMedia, SpfMediaAPI, SpfMediaMixin };
+export { SimpleHlsMediaAPI, SimpleHlsMediaElement, SimpleHlsMediaMixin, SimpleHlsMediaProps, simpleHlsMediaDefaultProps };
 //# sourceMappingURL=adapter.d.ts.map

package/dist/dev/playback/engines/hls/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"mappings":";;;;;UAUiB,mBAAA;EACf,GAAA;EACA,OAAA;AAAA;AAAA,cAGW,0BAAA,EAA4B,mBAAA;AAAA,UAKxB,iBAAA,SAA0B,mBAAA;EAAA,SAChC,MAAA,EAAQ,WAAA,CAAY,oBAAA,EAAsB,sBAAA;EACnD,MAAA,CAAO,YAAA,EAAc,gBAAA;EACrB,MAAA;EACA,OAAA;EACA,IAAA,IAAQ,OAAA;AAAA;AALV;;;;;;;;;;;;;;;;;;AAAA,iBA0BgB,mBAAA,cAAiC,WAAA,MAAA,CAAkB,SAAA,EAAW,IAAA,GAmJpC,WAAA,CAAY,IAAA,EAAM,iBAAA;AAAA,cAC3D,0BAAA;;;;cAGY,qBAAA,SAA8B,0BAAA"}