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

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

@@ -0,0 +1,96 @@
+import { computed, peek } from "../../core/signals/primitives.js";
+import { defineBehavior } from "../../core/composition/create-composition.js";
+import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
+import { isResolvedPresentation } from "../../media/types/index.js";
+import { getTracksByType } from "../../media/utils/tracks.js";
+import { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from "../../network/bandwidth-estimator.js";
+import { DEFAULT_QUALITY_CONFIG, selectLowestQuality, selectQuality } from "../../media/abr/quality-selection.js";
+function setupQualitySwitching({ state, config }) {
+	const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;
+	const upgradeMargin = config.quality?.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;
+	const initialBandwidth = config.initialBandwidth ?? 5e6;
+	const bandwidthConfig = {
+		...DEFAULT_BANDWIDTH_CONFIG,
+		...config.bandwidth
+	};
+	const { selectionKey, userSelectionKey, getTracks, selectOptimal } = config;
+	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: () => () => state[selectionKey].set(void 0),
+				effects: [() => {
+					const presentation = peek(state.presentation);
+					if (!presentation) return;
+					const allTracks = getTracks(presentation);
+					const [firstAllTrack] = allTracks;
+					if (!firstAllTrack) return;
+					const userFilter = state[userSelectionKey].get();
+					const matching = userFilter ? allTracks.filter((track) => {
+						for (const key in userFilter) {
+							const filterValue = userFilter[key];
+							if (filterValue !== void 0 && track[key] !== filterValue) return false;
+						}
+						return true;
+					}) : allTracks;
+					const candidates = matching.length > 0 ? matching : allTracks;
+					if (!candidates.length) return;
+					const selectedId = state[selectionKey].get();
+					if (candidates.length === 1) {
+						if (candidates[0].id !== selectedId) state[selectionKey].set(candidates[0].id);
+						return;
+					}
+					const bandwidth = getBandwidthEstimate(state.bandwidthState.get(), initialBandwidth, bandwidthConfig);
+					if (!selectedId && config.picker) {
+						const id = config.picker(presentation, config);
+						if (id) {
+							state[selectionKey].set(id);
+							return;
+						}
+					}
+					const optimal = selectOptimal(candidates, bandwidth, {
+						safetyMargin,
+						upgradeMargin,
+						currentTrack: candidates.find((t) => t.id === selectedId)
+					}) ?? selectLowestQuality(candidates);
+					if (optimal.id !== selectedId) state[selectionKey].set(optimal.id);
+				}]
+			}
+		}
+	});
+}
+/**
+* Manage `selectedVideoTrackId`: pick a default on src load, dynamically
+* adjust based on bandwidth, clear on src unload. Honors
+* `userVideoTrackSelection` as a partial-track constraint on candidates;
+* short-circuits ABR when the constraint narrows to a single track.
+*
+* @example
+* const reactor = switchVideoQuality.setup({ state });
+*/
+const switchVideoQuality = defineBehavior({
+	stateKeys: [
+		"presentation",
+		"bandwidthState",
+		"selectedVideoTrackId",
+		"userVideoTrackSelection"
+	],
+	contextKeys: [],
+	setup: ({ state, config }) => setupQualitySwitching({
+		state,
+		config: {
+			...config,
+			selectionKey: "selectedVideoTrackId",
+			userSelectionKey: "userVideoTrackSelection",
+			getTracks: (presentation) => getTracksByType(presentation, "video"),
+			selectOptimal: selectQuality
+		}
+	})
+});
+//#endregion
+export { switchVideoQuality };
+
+//# sourceMappingURL=quality-switching.js.map

package/dist/default/playback/behaviors/quality-switching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-switching.js","names":[],"sources":["../../../../src/playback/behaviors/quality-switching.ts"],"sourcesContent":["/**\n * **Manage the per-type ABR-eligible track selection slot.** While a\n * presentation is resolved, owns the slot's lifecycle: pick a default,\n * dynamically adjust based on media metrics (today: bandwidth via\n * `selectQuality`), and clear on src unload. User intent is expressed as a\n * partial-track description in a sibling slot (e.g.\n * `userVideoTrackSelection`) which constrains the candidate set for\n * selection — when the constraint narrows candidates to exactly one, the\n * choice is fully determined and ABR is short-circuited (no bandwidth read,\n * no effect re-fire on bandwidth changes).\n *\n * Lifecycle: `'presentation-unresolved'` ↔ `'presentation-resolved'`. The\n * `'presentation-resolved'` state owns the selection slot; its\n * entry-returned cleanup clears the slot on exit (canonical\n * cleanup-binds-to-setup per `reactors.md`).\n *\n * Hysteresis: downgrades apply immediately; upgrades require the optimal\n * track's bandwidth to exceed the current track's by `upgradeMargin`. No\n * temporal state — short-term smoothing is the bandwidth estimator's job.\n *\n * Initial pick is configurable via `config.picker` — pass any `TrackPicker`\n * to override the bandwidth-aware default for the empty-slot case. ABR\n * re-evaluation (downgrade/upgrade) is unaffected. Composing\n * `switchVideoQuality` with `picker: (p) => pickFirstTrackId(p, 'video')`\n * yields \"first track at load, ABR adjusts from there\" — a non-bandwidth\n * initial pick paired with bandwidth-driven re-evaluation.\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, peek, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport {\n  DEFAULT_QUALITY_CONFIG,\n  type QualityConfig,\n  selectLowestQuality,\n  selectQuality,\n} from '../../media/abr/quality-selection';\nimport type { TrackPicker } from '../../media/primitives/select-tracks';\nimport {\n  isResolvedPresentation,\n  type MaybeResolvedPresentation,\n  type PartiallyResolvedVideoTrack,\n  type VideoTrack,\n} from '../../media/types';\nimport { getTracksByType } from '../../media/utils/tracks';\nimport type { BandwidthConfig, BandwidthState } from '../../network/bandwidth-estimator';\nimport { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from '../../network/bandwidth-estimator';\n\nexport interface QualitySwitchingState {\n  presentation?: MaybeResolvedPresentation;\n  bandwidthState?: BandwidthState;\n  selectedVideoTrackId?: string;\n  /**\n   * Partial-track description expressing user intent. When set, narrows\n   * the ABR candidate set to tracks matching every present field. The\n   * common case is `{ id: 'specific-track-id' }` for a \"manual quality\"\n   * pick, but other partial shapes work — e.g., `{ height: 720 }` would\n   * constrain to 720p tracks; ABR continues to pick among them.\n   *\n   * When the narrowed candidates contain exactly one track, ABR is\n   * short-circuited entirely (no bandwidth read, no effect re-fire).\n   *\n   * When the filter matches no tracks in the current presentation (e.g.,\n   * user-picked id from a previous source doesn't exist here), falls back\n   * to the unfiltered set rather than stalling playback.\n   */\n  userVideoTrackSelection?: Partial<VideoTrack>;\n}\n\nexport interface QualitySwitchingConfig {\n  /**\n   * Quality-selection tuning. `safetyMargin` is the bandwidth-headroom\n   * multiplier; `upgradeMargin` is the hysteresis ratio gating upgrades.\n   * Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).\n   */\n  quality?: Partial<QualityConfig>;\n\n  /**\n   * Bandwidth-estimator tuning passed through to `getBandwidthEstimate`.\n   * Merged over `DEFAULT_BANDWIDTH_CONFIG`.\n   */\n  bandwidth?: Partial<BandwidthConfig>;\n\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected.\n   * Default: 5_000_000 (5 Mbps).\n   */\n  initialBandwidth?: number;\n\n  /**\n   * Override the initial-pick algorithm. When set, the picker is called the\n   * first time the slot is empty in the `'presentation-resolved'` state;\n   * its returned id is set verbatim (no bandwidth-aware logic). Subsequent\n   * ABR re-evaluation (downgrade/upgrade by bandwidth + hysteresis) is\n   * unaffected and runs as usual.\n   *\n   * Default (no picker): a bandwidth-aware initial pick driven by\n   * `initialBandwidth` and `quality.safetyMargin`, identical to ABR's\n   * downgrade branch.\n   *\n   * Honors of `userVideoTrackSelection` are the picker's responsibility\n   * when overridden. If the picker returns `undefined`, the bandwidth-aware\n   * default pick fires (graceful fallback).\n   */\n  picker?: TrackPicker<QualitySwitchingConfig>;\n}\n\n/** Default initial-bandwidth value used by quality-switching variants before measurements arrive. */\nexport const DEFAULT_INITIAL_BANDWIDTH = 5_000_000;\n\n// ============================================================================\n// Specialization helper\n//\n// `setupQualitySwitching` has the same shape as a Behavior `setup` function:\n// `({ state, config }) => Reactor`. Each `switchXQuality` export below calls\n// it from inside its own `defineBehavior` setup, passing the per-type slot\n// keys, track type, and selection algorithm explicitly via three generic\n// parameters — `S` (selection slot key), `U` (user-selection slot key), `T`\n// (ABR track type). The per-type export is the single point that ties them\n// together; the helper stays slot-agnostic.\n//\n// -- Design note: why narrow `SelectionKey` / `UserSelectionKey` unions ----\n// Goal we did not reach: have callers \"fully pass in\" the slot keys, with\n// the helper enforcing zero internal knowledge of which literals are valid.\n// What blocks it: indexing a mapped-type intersection by a generic key.\n// When `S extends keyof QualitySwitchingState` (or `string`), TS conservatively\n// treats `state[selectionKey]` as the union of every possible match across\n// the intersected mapped portions — including the fixed-key signals\n// (`presentation`, `bandwidthState`) — and widens to their value-type union.\n// The sibling pattern hits the same constraint and answers it the same way:\n// `SelectedTrackKey` in `select-tracks.ts:43` is a hardcoded narrow union\n// for the same reason.\n//\n// Routes considered for \"fully passed in\", with trade-offs (left here for\n// the larger-group conversation):\n//\n//   A. Derived constraint — `Exclude<keyof QualitySwitchingState, 'presentation'\n//      | 'bandwidthState'>`. Removes the literal enumeration; same narrowness,\n//      computed from the state shape. Still \"knows\" the fixed-key names.\n//   B. Broad constraint (`S extends keyof QualitySwitchingState`) + access-site\n//      casts (`state[selectionKey] as Signal<string | undefined>` at the top\n//      of the helper). Caller passes any keys; the type system stops checking\n//      S ≠ U or that the keys actually refer to selection slots. Once you\n//      cast at the top, the body is structurally the original remap pattern\n//      with extra ceremony.\n//   C. Remap pattern (pre-refactor) — caller passes signals under logical\n//      names (`selection`, `userSelection`); helper has no key generics.\n//      Cleanest types; inconsistent with the sibling helpers.\n//\n// Current pick is the narrow-union route because it matches siblings and\n// the unions read as documentation (\"these are the slots this helper\n// manages\") rather than restriction. Extending for audio is one literal\n// per union.\n// --------------------------------------------------------------------------\n// ============================================================================\n\ntype AbrTrack = { id: string; bandwidth: number };\n\ntype SelectionKey = 'selectedVideoTrackId';\ntype UserSelectionKey = 'userVideoTrackSelection';\n\n// Each mapped value references `P` so TS keeps the per-key dependency and\n// resolves `state[selectionKey]` / `state[userSelectionKey]` to the right\n// arm. `T` (track type) deliberately stays out of the state map — pulling\n// it in detaches the user-selection mapped value from `P` and TS collapses\n// the intersection. T flows through `QualitySwitchingSetupConfig` instead;\n// the user-filter access casts at the read site (see below).\ntype QualitySwitchingStateMap<S extends SelectionKey, U extends UserSelectionKey> = {\n  presentation: ReadonlySignal<QualitySwitchingState['presentation']>;\n  bandwidthState: ReadonlySignal<QualitySwitchingState['bandwidthState']>;\n} & { [P in S]: Signal<QualitySwitchingState[P]> } & { [P in U]: ReadonlySignal<QualitySwitchingState[P]> };\n\ninterface QualitySwitchingSetupConfig<S extends SelectionKey, U extends UserSelectionKey, T extends AbrTrack>\n  extends QualitySwitchingConfig {\n  selectionKey: S;\n  userSelectionKey: U;\n  getTracks: (presentation: MaybeResolvedPresentation) => readonly T[];\n  selectOptimal: (\n    tracks: readonly T[],\n    bandwidth: number,\n    opts: { safetyMargin: number; upgradeMargin: number; currentTrack?: T }\n  ) => T | undefined;\n}\n\nfunction setupQualitySwitching<S extends SelectionKey, U extends UserSelectionKey, T extends AbrTrack>({\n  state,\n  config,\n}: {\n  state: QualitySwitchingStateMap<S, U>;\n  config: QualitySwitchingSetupConfig<S, U, T>;\n}) {\n  const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;\n  const upgradeMargin = config.quality?.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;\n  const initialBandwidth = config.initialBandwidth ?? DEFAULT_INITIAL_BANDWIDTH;\n  const bandwidthConfig: BandwidthConfig = { ...DEFAULT_BANDWIDTH_CONFIG, ...config.bandwidth };\n  const { selectionKey, userSelectionKey, getTracks, selectOptimal } = config;\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        // Canonical cleanup-binds-to-setup: the selection slot's valid\n        // lifespan is exactly 'presentation-resolved'. Clear fires on\n        // 'presentation-resolved' exit, covering both src unload and\n        // behavior destroy.\n        entry: () => () => state[selectionKey].set(undefined),\n        effects: [\n          () => {\n            const presentation = peek(state.presentation);\n            if (!presentation) return;\n\n            const allTracks = getTracks(presentation);\n            const [firstAllTrack] = allTracks;\n            if (!firstAllTrack) return;\n\n            // State stores the filter as `Partial<VideoTrack>` (user-facing\n            // shape — includes V-only fields like `height`); the helper\n            // works against `Partial<T>` so filter and track access share\n            // one index type. Filter keys absent on a partially-resolved\n            // track read as `undefined` and just exclude that track.\n            const userFilter = state[userSelectionKey].get() as Partial<T> | undefined;\n            const matching = userFilter\n              ? allTracks.filter((track) => {\n                  for (const key in userFilter) {\n                    const filterValue = userFilter[key as keyof T];\n                    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n                  }\n                  return true;\n                })\n              : allTracks;\n            // Fall back to all tracks when the filter excludes everything\n            // (e.g., user-picked id doesn't exist in the current source).\n            const candidates = matching.length > 0 ? matching : allTracks;\n            if (!candidates.length) return;\n\n            const selectedId = state[selectionKey].get();\n\n            // Common case: user has fully constrained the choice (e.g.,\n            // `{ id: 'specific-720p' }` narrows to a single track). Skip\n            // the ABR path — and crucially, don't read `bandwidthState`\n            // so the effect doesn't re-fire on bandwidth changes while\n            // the user's selection holds.\n            if (candidates.length === 1) {\n              if (candidates[0]!.id !== selectedId) state[selectionKey].set(candidates[0]!.id);\n              return;\n            }\n\n            // Read bandwidth up front to establish the signal subscription —\n            // future bandwidth changes must re-fire this effect even when\n            // the picker branch below takes the early-return path. (If the\n            // picker bails out without ever touching `bandwidthState`, ABR\n            // would otherwise be deaf to subsequent bandwidth changes.)\n            //\n            // Single path for pre-trust and post-trust:\n            // `getBandwidthEstimate` returns `initialBandwidth` when state\n            // is undefined or bytes sampled hasn't crossed `minTotalBytes`,\n            // so the initial pick + early-ABR window run the same\n            // `selectOptimal` path as a fully-trusted measurement.\n            const bandwidth = getBandwidthEstimate(state.bandwidthState.get(), initialBandwidth, bandwidthConfig);\n\n            // Picker-driven initial pick: when the slot is empty and the\n            // caller supplied a `picker`, defer to it instead of the\n            // bandwidth-aware default. The picker sees the full\n            // presentation (not narrowed by `userVideoTrackSelection`) —\n            // honoring the filter is the picker's responsibility when\n            // overridden. Returning `undefined` falls through to the\n            // bandwidth-aware default (graceful fallback).\n            //\n            // ABR re-evaluation (downgrade/upgrade by bandwidth) runs as\n            // usual on subsequent effect re-runs once the slot is set.\n            if (!selectedId && config.picker) {\n              const id = config.picker(presentation, config);\n              if (id) {\n                state[selectionKey].set(id);\n                return;\n              }\n            }\n            // `selectOptimal` decides the track to apply now given current\n            // selection + bandwidth + tuning. It returns:\n            //   - the optimal when no current track or on a downgrade\n            //   - the optimal when an upgrade clears `upgradeMargin`\n            //   - the current track itself when an upgrade doesn't clear margin\n            //     (caller's id-compare below no-ops in that case)\n            // Outer `?? selectLowestQuality` is defensive — `selectQuality` falls\n            // back to lowest internally; this catches future impls that don't.\n            // `selectLowestQuality` returns `undefined` only on empty input,\n            // and `candidates.length >= 2` here.\n            const currentTrack = candidates.find((t) => t.id === selectedId);\n            const optimal =\n              selectOptimal(candidates, bandwidth, { safetyMargin, upgradeMargin, currentTrack }) ??\n              selectLowestQuality(candidates)!;\n            if (optimal.id !== selectedId) state[selectionKey].set(optimal.id);\n          },\n        ],\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Specialized exports — one per ABR-enabled track type\n// ============================================================================\n\n/**\n * Manage `selectedVideoTrackId`: pick a default on src load, dynamically\n * adjust based on bandwidth, clear on src unload. Honors\n * `userVideoTrackSelection` as a partial-track constraint on candidates;\n * short-circuits ABR when the constraint narrows to a single track.\n *\n * @example\n * const reactor = switchVideoQuality.setup({ state });\n */\nexport const switchVideoQuality = defineBehavior({\n  stateKeys: ['presentation', 'bandwidthState', 'selectedVideoTrackId', 'userVideoTrackSelection'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config,\n  }: {\n    state: QualitySwitchingStateMap<'selectedVideoTrackId', 'userVideoTrackSelection'>;\n    config?: QualitySwitchingConfig;\n  }) =>\n    setupQualitySwitching<'selectedVideoTrackId', 'userVideoTrackSelection', PartiallyResolvedVideoTrack | VideoTrack>({\n      state,\n      config: {\n        ...config,\n        selectionKey: 'selectedVideoTrackId',\n        userSelectionKey: 'userVideoTrackSelection',\n        getTracks: (presentation) =>\n          getTracksByType(presentation, 'video') as readonly (PartiallyResolvedVideoTrack | VideoTrack)[],\n        selectOptimal: selectQuality,\n      },\n    }),\n});\n"],"mappings":";;;;;;;AAwLA,SAAS,sBAA8F,EACrG,OACA,UAIC;CACD,MAAM,eAAe,OAAO,SAAS,gBAAgB,uBAAuB;CAC5E,MAAM,gBAAgB,OAAO,SAAS,iBAAiB,uBAAuB;CAC9E,MAAM,mBAAmB,OAAO,oBAAA;CAChC,MAAM,kBAAmC;EAAE,GAAG;EAA0B,GAAG,OAAO;EAAW;CAC7F,MAAM,EAAE,cAAc,kBAAkB,WAAW,kBAAkB;CAErE,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;IAKvB,mBAAmB,MAAM,cAAc,IAAI,KAAA,EAAU;IACrD,SAAS,OACD;KACJ,MAAM,eAAe,KAAK,MAAM,aAAa;AAC7C,SAAI,CAAC,aAAc;KAEnB,MAAM,YAAY,UAAU,aAAa;KACzC,MAAM,CAAC,iBAAiB;AACxB,SAAI,CAAC,cAAe;KAOpB,MAAM,aAAa,MAAM,kBAAkB,KAAK;KAChD,MAAM,WAAW,aACb,UAAU,QAAQ,UAAU;AAC1B,WAAK,MAAM,OAAO,YAAY;OAC5B,MAAM,cAAc,WAAW;AAC/B,WAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,YAAa,QAAO;;AAEjF,aAAO;OACP,GACF;KAGJ,MAAM,aAAa,SAAS,SAAS,IAAI,WAAW;AACpD,SAAI,CAAC,WAAW,OAAQ;KAExB,MAAM,aAAa,MAAM,cAAc,KAAK;AAO5C,SAAI,WAAW,WAAW,GAAG;AAC3B,UAAI,WAAW,GAAI,OAAO,WAAY,OAAM,cAAc,IAAI,WAAW,GAAI,GAAG;AAChF;;KAcF,MAAM,YAAY,qBAAqB,MAAM,eAAe,KAAK,EAAE,kBAAkB,gBAAgB;AAYrG,SAAI,CAAC,cAAc,OAAO,QAAQ;MAChC,MAAM,KAAK,OAAO,OAAO,cAAc,OAAO;AAC9C,UAAI,IAAI;AACN,aAAM,cAAc,IAAI,GAAG;AAC3B;;;KAcJ,MAAM,UACJ,cAAc,YAAY,WAAW;MAAE;MAAc;MAAe,cAFjD,WAAW,MAAM,MAAM,EAAE,OAAO,WAAW;MAEoB,CAAC,IACnF,oBAAoB,WAAW;AACjC,SAAI,QAAQ,OAAO,WAAY,OAAM,cAAc,IAAI,QAAQ,GAAG;MAErE;IACF;GACF;EACF,CAAC;;;;;;;;;;;AAgBJ,MAAa,qBAAqB,eAAe;CAC/C,WAAW;EAAC;EAAgB;EAAkB;EAAwB;EAA0B;CAChG,aAAa,EAAE;CACf,QAAQ,EACN,OACA,aAKA,sBAAmH;EACjH;EACA,QAAQ;GACN,GAAG;GACH,cAAc;GACd,kBAAkB;GAClB,YAAY,iBACV,gBAAgB,cAAc,QAAQ;GACxC,eAAe;GAChB;EACF,CAAC;CACL,CAAC"}

package/dist/default/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/default/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/default/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/default/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/default/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/default/playback/behaviors/select-tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/playback/behaviors/select-tracks.ts"],"sourcesContent":["/**\n * **Default audio/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/default/playback/behaviors/sync-preload.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync-preload.js","names":[],"sources":["../../../../src/playback/behaviors/sync-preload.ts"],"sourcesContent":["/**\n * **Bidirectional sync between `state.preload` and `mediaElement.preload`.**\n *\n * Two effects:\n * - **Read (DOM → state)** — on `context.mediaElement` swap or\n *   `state.presentation.url` change, copies `mediaElement.preload` into\n *   `state.preload` if it's a W3C value and `state.preload` isn't holding\n *   an extended (non-W3C) value. When the DOM has no W3C opinion and\n *   `state.preload` is undefined, backfills from `config.defaultPreload`\n *   (default-default `'metadata'`) so `state.preload` is never undefined\n *   in steady state.\n * - **Write (state → DOM)** — on `state.preload` change or\n *   `context.mediaElement` swap, writes `state.preload` back to\n *   `mediaElement.preload` if the value is W3C.\n *\n * Extended values (e.g. `'canplay'`) written externally to `state.preload`\n * are sticky: read won't overwrite them, write won't push them to the DOM.\n * All writes are deduped to break echo loops and avoid spurious re-triggers\n * downstream (notably `resolvePresentation`, which reads `state.preload`).\n */\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { effect } from '../../core/signals/effect';\nimport { computed, peek, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport type { MediaElementLike } from '../../media/types';\nimport { DEFAULT_PRELOAD, isStandardPreload, type StandardPreload } from '../../media/utils/preload';\nimport type { PresentationState } from './resolve-presentation';\n\nexport interface SyncPreloadConfig {\n  /**\n   * Backfill applied to `state.preload` when neither the host element nor\n   * external code has supplied a W3C value. Defaults to `'metadata'`.\n   */\n  defaultPreload?: StandardPreload;\n}\n\ntype State = Pick<PresentationState, 'preload' | 'presentation'>;\n\nfunction syncPreloadSetup({\n  state,\n  context,\n  config,\n}: {\n  state: {\n    preload: Signal<State['preload']>;\n    presentation: ReadonlySignal<State['presentation']>;\n  };\n  context: { mediaElement: ReadonlySignal<MediaElementLike | undefined> };\n  config?: SyncPreloadConfig;\n}): () => void {\n  const defaultPreload: StandardPreload = config?.defaultPreload ?? DEFAULT_PRELOAD;\n  const presentationUrl = computed(() => state.presentation.get()?.url);\n\n  // Read must be registered before write: effects re-run in registration\n  // order (see core/signals/effect.ts → runPending). On a shared-signal\n  // change (e.g. `context.mediaElement` swap), read fires first and gets to\n  // claim `state.preload`, giving \"most-recent-wins on attach\" — a freshly\n  // mounted <video> with a W3C `preload` attribute overrides whatever\n  // `state.preload` previously held. Swap the order or split these into\n  // separate behaviors and the \"most-recent-wins on attach\" test pins the\n  // regression.\n  const cleanupRead = effect(() => {\n    presentationUrl.get();\n    const mediaElement = context.mediaElement.get();\n    // peek (not get): external writes to state.preload shouldn't re-trigger\n    // this effect, only mediaElement / presentation-url changes should.\n    const current = peek(state.preload);\n    // Extended sticky: leave non-W3C values (e.g. 'canplay') alone.\n    if (current !== undefined && !isStandardPreload(current)) return;\n\n    const target: StandardPreload | undefined =\n      mediaElement && isStandardPreload(mediaElement.preload)\n        ? mediaElement.preload\n        : current === undefined\n          ? defaultPreload\n          : undefined;\n    if (target === undefined || target === current) return;\n    state.preload.set(target);\n  });\n\n  const cleanupWrite = effect(() => {\n    const next = state.preload.get();\n    const mediaElement = context.mediaElement.get();\n    if (!mediaElement) return;\n    if (!isStandardPreload(next)) return;\n    if (mediaElement.preload === next) return;\n    mediaElement.preload = next;\n  });\n\n  return () => {\n    cleanupRead();\n    cleanupWrite();\n  };\n}\n\nexport const syncPreload = defineBehavior({\n  stateKeys: ['preload', 'presentation'],\n  contextKeys: ['mediaElement'],\n  setup: syncPreloadSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAS,iBAAiB,EACxB,OACA,SACA,UAQa;CACb,MAAM,iBAAkC,QAAQ,kBAAA;CAChD,MAAM,kBAAkB,eAAe,MAAM,aAAa,KAAK,EAAE,IAAI;CAUrE,MAAM,cAAc,aAAa;AAC/B,kBAAgB,KAAK;EACrB,MAAM,eAAe,QAAQ,aAAa,KAAK;EAG/C,MAAM,UAAU,KAAK,MAAM,QAAQ;AAEnC,MAAI,YAAY,KAAA,KAAa,CAAC,kBAAkB,QAAQ,CAAE;EAE1D,MAAM,SACJ,gBAAgB,kBAAkB,aAAa,QAAQ,GACnD,aAAa,UACb,YAAY,KAAA,IACV,iBACA,KAAA;AACR,MAAI,WAAW,KAAA,KAAa,WAAW,QAAS;AAChD,QAAM,QAAQ,IAAI,OAAO;GACzB;CAEF,MAAM,eAAe,aAAa;EAChC,MAAM,OAAO,MAAM,QAAQ,KAAK;EAChC,MAAM,eAAe,QAAQ,aAAa,KAAK;AAC/C,MAAI,CAAC,aAAc;AACnB,MAAI,CAAC,kBAAkB,KAAK,CAAE;AAC9B,MAAI,aAAa,YAAY,KAAM;AACnC,eAAa,UAAU;GACvB;AAEF,cAAa;AACX,eAAa;AACb,gBAAc;;;AAIlB,MAAa,cAAc,eAAe;CACxC,WAAW,CAAC,WAAW,eAAe;CACtC,aAAa,CAAC,eAAe;CAC7B,OAAO;CACR,CAAC"}