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

package/dist/dev/playback/behaviors/dom/track-current-time.js

@@ -0,0 +1,46 @@
+import { defineBehavior } from "../../../core/composition/create-composition.js";
+import { effect } from "../../../core/signals/effect.js";
+import { listen } from "@videojs/utils/dom";
+//#region src/playback/behaviors/dom/track-current-time.ts
+/**
+* Mirror `mediaElement.currentTime` into reactive state. Listens for:
+* - `timeupdate` — fires during playback (~4 Hz)
+* - `seeking` — fires when a seek begins; per spec, `currentTime` is already
+*   at the new position when this event dispatches, so buffer management can
+*   react immediately rather than waiting for `timeupdate`, which does not
+*   fire while paused.
+*
+* Also syncs immediately when a media element becomes available.
+*
+* When no media element is attached, writes `config.defaultCurrentTime`
+* (default-default `0`, matching the HTMLMediaElement spec) so consumers
+* always see a defined position. Read-only mirror; does not push
+* `state.currentTime` back to the element.
+*/
+function trackCurrentTimeSetup({ state, context, config }) {
+	const defaultCurrentTime = config?.defaultCurrentTime ?? 0;
+	return effect(() => {
+		const mediaElement = context.mediaElement.get();
+		if (!mediaElement) {
+			state.currentTime.set(defaultCurrentTime);
+			return;
+		}
+		const sync = () => state.currentTime.set(mediaElement.currentTime);
+		sync();
+		const removeTimeupdate = listen(mediaElement, "timeupdate", sync);
+		const removeSeeking = listen(mediaElement, "seeking", sync);
+		return () => {
+			removeTimeupdate();
+			removeSeeking();
+		};
+	});
+}
+const trackCurrentTime = defineBehavior({
+	stateKeys: ["currentTime"],
+	contextKeys: ["mediaElement"],
+	setup: trackCurrentTimeSetup
+});
+//#endregion
+export { trackCurrentTime };
+
+//# sourceMappingURL=track-current-time.js.map

package/dist/dev/playback/behaviors/dom/track-current-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-current-time.js","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-current-time.ts"],"sourcesContent":["/**\n * Mirror `mediaElement.currentTime` into reactive state. Listens for:\n * - `timeupdate` — fires during playback (~4 Hz)\n * - `seeking` — fires when a seek begins; per spec, `currentTime` is already\n *   at the new position when this event dispatches, so buffer management can\n *   react immediately rather than waiting for `timeupdate`, which does not\n *   fire while paused.\n *\n * Also syncs immediately when a media element becomes available.\n *\n * When no media element is attached, writes `config.defaultCurrentTime`\n * (default-default `0`, matching the HTMLMediaElement spec) so consumers\n * always see a defined position. Read-only mirror; does not push\n * `state.currentTime` back to the element.\n */\nimport { listen } from '@videojs/utils/dom';\nimport { defineBehavior } from '../../../core/composition/create-composition';\nimport { effect } from '../../../core/signals/effect';\nimport type { ReadonlySignal, Signal } from '../../../core/signals/primitives';\n\nexport interface CurrentTimeState {\n  currentTime?: number;\n}\n\nexport interface CurrentTimeContext {\n  mediaElement?: HTMLMediaElement | undefined;\n}\n\nexport interface TrackCurrentTimeConfig {\n  /**\n   * Value written to `state.currentTime` when no media element is attached.\n   * Defaults to `0` — the HTMLMediaElement spec default.\n   */\n  defaultCurrentTime?: number;\n}\n\nfunction trackCurrentTimeSetup({\n  state,\n  context,\n  config,\n}: {\n  state: { currentTime: Signal<CurrentTimeState['currentTime']> };\n  context: { mediaElement: ReadonlySignal<CurrentTimeContext['mediaElement']> };\n  config?: TrackCurrentTimeConfig;\n}): () => void {\n  const defaultCurrentTime = config?.defaultCurrentTime ?? 0;\n\n  return effect(() => {\n    const mediaElement = context.mediaElement.get();\n    if (!mediaElement) {\n      state.currentTime.set(defaultCurrentTime);\n      return;\n    }\n\n    const sync = () => state.currentTime.set(mediaElement.currentTime);\n    sync();\n    const removeTimeupdate = listen(mediaElement, 'timeupdate', sync);\n    const removeSeeking = listen(mediaElement, 'seeking', sync);\n    return () => {\n      removeTimeupdate();\n      removeSeeking();\n    };\n  });\n}\n\nexport const trackCurrentTime = defineBehavior({\n  stateKeys: ['currentTime'],\n  contextKeys: ['mediaElement'],\n  setup: trackCurrentTimeSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoCA,SAAS,sBAAsB,EAC7B,OACA,SACA,UAKa;CACb,MAAM,qBAAqB,QAAQ,sBAAsB;AAEzD,QAAO,aAAa;EAClB,MAAM,eAAe,QAAQ,aAAa,KAAK;AAC/C,MAAI,CAAC,cAAc;AACjB,SAAM,YAAY,IAAI,mBAAmB;AACzC;;EAGF,MAAM,aAAa,MAAM,YAAY,IAAI,aAAa,YAAY;AAClE,QAAM;EACN,MAAM,mBAAmB,OAAO,cAAc,cAAc,KAAK;EACjE,MAAM,gBAAgB,OAAO,cAAc,WAAW,KAAK;AAC3D,eAAa;AACX,qBAAkB;AAClB,kBAAe;;GAEjB;;AAGJ,MAAa,mBAAmB,eAAe;CAC7C,WAAW,CAAC,cAAc;CAC1B,aAAa,CAAC,eAAe;CAC7B,OAAO;CACR,CAAC"}

package/dist/dev/playback/behaviors/dom/track-load-triggers.d.ts

@@ -0,0 +1,48 @@
+import { ReadonlySignal, Signal } from "../../../core/signals/primitives.js";
+import { Reactor } from "../../../core/reactors/create-machine-reactor.js";
+import { MaybeResolvedPresentation } from "../../../media/types/index.js";
+
+//#region src/playback/behaviors/dom/track-load-triggers.d.ts
+/**
+ * State shape for load-trigger tracking.
+ */
+interface LoadTriggersState {
+  /**
+   * Sticky-true per source. Flips to `true` the first time an event occurs
+   * that should switch loading behavior from preload-based to standard load
+   * (currently DOM `play` / `seeking`). Reset to `false` on source change.
+   *
+   * Read by `resolvePresentation` and `loadVideoSegments` / `loadAudioSegments`
+   * to mirror native `HTMLMediaElement` preload semantics — only meaningful
+   * when `preload !== 'auto'`, which already loads fully regardless.
+   */
+  loadActivated?: boolean;
+  /** Current presentation — URL is used to detect source changes. */
+  presentation?: MaybeResolvedPresentation;
+}
+/**
+ * Context shape for load-trigger tracking.
+ */
+interface LoadTriggersContext {
+  mediaElement?: HTMLMediaElement | undefined;
+}
+type LoadTriggersFsmState = 'preconditions-unmet' | 'monitoring' | 'load-active';
+declare const trackLoadTriggers: {
+  stateKeys: readonly ["loadActivated", "presentation"];
+  contextKeys: readonly ["mediaElement"];
+  setup: (deps: {
+    state: {
+      loadActivated: Signal<LoadTriggersState['loadActivated']>;
+      presentation: ReadonlySignal<LoadTriggersState['presentation']>;
+    };
+  } & {
+    context: {
+      mediaElement: ReadonlySignal<LoadTriggersContext['mediaElement']>;
+    };
+  } & {
+    config?: {};
+  }) => Reactor<"destroyed" | "destroying" | LoadTriggersFsmState>;
+};
+//#endregion
+export { LoadTriggersContext, LoadTriggersState, trackLoadTriggers };
+//# sourceMappingURL=track-load-triggers.d.ts.map

package/dist/dev/playback/behaviors/dom/track-load-triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-load-triggers.d.ts","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-load-triggers.ts"],"mappings":";;;;;;;AAUA;UAAiB,iBAAA;;;;;;;;AAkBjB;;EARE,aAAA;EASA;EAPA,YAAA,GAAe,yBAAA;AAAA;;;;UAMA,mBAAA;EACf,YAAA,GAAe,gBAAA;AAAA;AAAA,KAGZ,oBAAA;AAAA,cA6HQ,iBAAA;;;;;qBA/DM,MAAA,CAAO,iBAAA;oBACR,cAAA,CAAe,iBAAA;IAAA;EAAA;;oBAEN,cAAA,CAAe,mBAAA;IAAA;EAAA"}

package/dist/dev/playback/behaviors/dom/track-load-triggers.js

@@ -0,0 +1,94 @@
+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 { listen } from "@videojs/utils/dom";
+//#region src/playback/behaviors/dom/track-load-triggers.ts
+/**
+* Slot-driven FSM. The slot `loadActivated` is the canonical externally-
+* observable state; `deriveState` reads it (and the preconditions) to
+* derive the local FSM state. The slot is *both* the state and the data —
+* no separate internal bookkeeping.
+*
+* ```
+* 'preconditions-unmet' ⟷ 'monitoring' ⟷ 'load-active'
+*
+* preconditions-unmet → monitoring        element + URL appear
+* monitoring          → load-active       slot flips true (listener fires
+*                                         or external write)
+* load-active         → monitoring        within-state cleanup resets slot
+*                                         (URL or element identity change)
+* any                 → preconditions-unmet  element or URL → undefined
+*
+* any state → destroying → destroyed       on destroy()
+* ```
+*/
+function deriveState(presentation, mediaElement, loadActivated) {
+	if (!mediaElement || !presentation?.url) return "preconditions-unmet";
+	if (loadActivated) return "load-active";
+	return "monitoring";
+}
+/**
+* Track preload-overriding events per source.
+*
+* Writes `state.loadActivated = true` the first time a `play` or `seeking`
+* event fires on the attached media element for the current source — or
+* immediately on entry if the element is already in such a state
+* (`!el.paused` or `el.seeking`), mirroring autoplay / native-controls /
+* direct-DOM-`play()` scenarios.
+*
+* Sticky-true *within a source identity*: subsequent play/pause/seek
+* cycles don't flip back. Source identity = (mediaElement, presentation
+* URL). Either changing — including direct in-place swap with no
+* `undefined` intermediate — resets the slot to `false`.
+*
+* Multi-writer with `hls/adapter.ts:play()` (which writes `true` directly
+* on programmatic play) is intentional — different domains. The adapter
+* records programmatic intent; this behavior is the DOM-side observer.
+* Pre-existing `true` writes are honored because `deriveState` reads the
+* slot — a `true` value routes directly to `'load-active'` without
+* entering `'monitoring'`.
+*
+* @example
+* const reactor = trackLoadTriggers.setup({ state, context });
+* // later:
+* reactor.destroy();
+*/
+function trackLoadTriggersSetup({ state, context }) {
+	const derivedStateSignal = computed(() => deriveState(state.presentation.get(), context.mediaElement.get(), state.loadActivated.get()));
+	const urlSignal = computed(() => state.presentation.get()?.url);
+	return createMachineReactor({
+		initial: "preconditions-unmet",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"preconditions-unmet": {},
+			monitoring: { effects: () => {
+				const el = context.mediaElement.get();
+				const setLoadActivated = () => state.loadActivated.set(true);
+				if (!el.paused || el.seeking) {
+					setLoadActivated();
+					return;
+				}
+				const cleanupPlay = listen(el, "play", setLoadActivated);
+				const cleanupSeeking = listen(el, "seeking", setLoadActivated);
+				return () => {
+					cleanupPlay();
+					cleanupSeeking();
+				};
+			} },
+			"load-active": { effects: () => {
+				context.mediaElement.get();
+				urlSignal.get();
+				return () => state.loadActivated.set(false);
+			} }
+		}
+	});
+}
+const trackLoadTriggers = defineBehavior({
+	stateKeys: ["loadActivated", "presentation"],
+	contextKeys: ["mediaElement"],
+	setup: trackLoadTriggersSetup
+});
+//#endregion
+export { trackLoadTriggers };
+
+//# sourceMappingURL=track-load-triggers.js.map

package/dist/dev/playback/behaviors/dom/track-load-triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-load-triggers.js","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-load-triggers.ts"],"sourcesContent":["import { listen } from '@videojs/utils/dom';\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 type { MaybeResolvedPresentation } from '../../../media/types';\n\n/**\n * State shape for load-trigger tracking.\n */\nexport interface LoadTriggersState {\n  /**\n   * Sticky-true per source. Flips to `true` the first time an event occurs\n   * that should switch loading behavior from preload-based to standard load\n   * (currently DOM `play` / `seeking`). Reset to `false` on source change.\n   *\n   * Read by `resolvePresentation` and `loadVideoSegments` / `loadAudioSegments`\n   * to mirror native `HTMLMediaElement` preload semantics — only meaningful\n   * when `preload !== 'auto'`, which already loads fully regardless.\n   */\n  loadActivated?: boolean;\n  /** Current presentation — URL is used to detect source changes. */\n  presentation?: MaybeResolvedPresentation;\n}\n\n/**\n * Context shape for load-trigger tracking.\n */\nexport interface LoadTriggersContext {\n  mediaElement?: HTMLMediaElement | undefined;\n}\n\ntype LoadTriggersFsmState = 'preconditions-unmet' | 'monitoring' | 'load-active';\n\n/**\n * Slot-driven FSM. The slot `loadActivated` is the canonical externally-\n * observable state; `deriveState` reads it (and the preconditions) to\n * derive the local FSM state. The slot is *both* the state and the data —\n * no separate internal bookkeeping.\n *\n * ```\n * 'preconditions-unmet' ⟷ 'monitoring' ⟷ 'load-active'\n *\n * preconditions-unmet → monitoring        element + URL appear\n * monitoring          → load-active       slot flips true (listener fires\n *                                         or external write)\n * load-active         → monitoring        within-state cleanup resets slot\n *                                         (URL or element identity change)\n * any                 → preconditions-unmet  element or URL → undefined\n *\n * any state → destroying → destroyed       on destroy()\n * ```\n */\nfunction deriveState(\n  presentation: MaybeResolvedPresentation | undefined,\n  mediaElement: HTMLMediaElement | undefined,\n  loadActivated: boolean | undefined\n): LoadTriggersFsmState {\n  if (!mediaElement || !presentation?.url) return 'preconditions-unmet';\n  if (loadActivated) return 'load-active';\n  return 'monitoring';\n}\n\n/**\n * Track preload-overriding events per source.\n *\n * Writes `state.loadActivated = true` the first time a `play` or `seeking`\n * event fires on the attached media element for the current source — or\n * immediately on entry if the element is already in such a state\n * (`!el.paused` or `el.seeking`), mirroring autoplay / native-controls /\n * direct-DOM-`play()` scenarios.\n *\n * Sticky-true *within a source identity*: subsequent play/pause/seek\n * cycles don't flip back. Source identity = (mediaElement, presentation\n * URL). Either changing — including direct in-place swap with no\n * `undefined` intermediate — resets the slot to `false`.\n *\n * Multi-writer with `hls/adapter.ts:play()` (which writes `true` directly\n * on programmatic play) is intentional — different domains. The adapter\n * records programmatic intent; this behavior is the DOM-side observer.\n * Pre-existing `true` writes are honored because `deriveState` reads the\n * slot — a `true` value routes directly to `'load-active'` without\n * entering `'monitoring'`.\n *\n * @example\n * const reactor = trackLoadTriggers.setup({ state, context });\n * // later:\n * reactor.destroy();\n */\nfunction trackLoadTriggersSetup({\n  state,\n  context,\n}: {\n  state: {\n    loadActivated: Signal<LoadTriggersState['loadActivated']>;\n    presentation: ReadonlySignal<LoadTriggersState['presentation']>;\n  };\n  context: { mediaElement: ReadonlySignal<LoadTriggersContext['mediaElement']> };\n}): Reactor<LoadTriggersFsmState | 'destroying' | 'destroyed'> {\n  const derivedStateSignal = computed(() =>\n    deriveState(state.presentation.get(), context.mediaElement.get(), state.loadActivated.get())\n  );\n  // Sparse-firing source-URL signal. Emits whenever `presentation?.url`\n  // resolves to a different value — covering both URL string changes\n  // (url_a → url_b) and transitions where the URL becomes defined or\n  // undefined (presentation set, cleared, or replaced without a URL\n  // field). Does NOT emit when `state.presentation` is rewritten with\n  // the same URL: manifest parsing, duration calc, track resolution,\n  // and other enrichment paths re-write the presentation object\n  // frequently — tracking raw `state.presentation` here would spuriously\n  // reset the 'load-active' slot.\n  const urlSignal = computed(() => state.presentation.get()?.url);\n\n  return createMachineReactor<LoadTriggersFsmState>({\n    initial: 'preconditions-unmet',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'preconditions-unmet': {},\n\n      monitoring: {\n        // effects (not entry) so element-identity change within this state\n        // re-fires and re-attaches listeners to the new element. The monitor\n        // guarantees mediaElement is truthy while we're in this state.\n        effects: () => {\n          const el = context.mediaElement.get()!;\n\n          const setLoadActivated = () => state.loadActivated.set(true);\n          if (!el.paused || el.seeking) {\n            setLoadActivated();\n            return;\n          }\n          const cleanupPlay = listen(el, 'play', setLoadActivated);\n          const cleanupSeeking = listen(el, 'seeking', setLoadActivated);\n          return () => {\n            cleanupPlay();\n            cleanupSeeking();\n          };\n        },\n      },\n\n      'load-active': {\n        // effects-based cleanup (not entry) because the cleanup must fire on\n        // BOTH state exit AND within-state identity change (url_a → url_b,\n        // element_a → element_b — both truthy, no state transition).\n        // Re-firing tracked reads → cleanup writes loadActivated=false →\n        // deriveState (which reads loadActivated) returns 'monitoring' →\n        // state transitions → fresh listeners attached for the new source.\n        effects: () => {\n          context.mediaElement.get();\n          urlSignal.get();\n          return () => state.loadActivated.set(false);\n        },\n      },\n    },\n  });\n}\n\nexport const trackLoadTriggers = defineBehavior({\n  stateKeys: ['loadActivated', 'presentation'],\n  contextKeys: ['mediaElement'],\n  setup: trackLoadTriggersSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAS,YACP,cACA,cACA,eACsB;AACtB,KAAI,CAAC,gBAAgB,CAAC,cAAc,IAAK,QAAO;AAChD,KAAI,cAAe,QAAO;AAC1B,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BT,SAAS,uBAAuB,EAC9B,OACA,WAO6D;CAC7D,MAAM,qBAAqB,eACzB,YAAY,MAAM,aAAa,KAAK,EAAE,QAAQ,aAAa,KAAK,EAAE,MAAM,cAAc,KAAK,CAAC,CAC7F;CAUD,MAAM,YAAY,eAAe,MAAM,aAAa,KAAK,EAAE,IAAI;AAE/D,QAAO,qBAA2C;EAChD,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,uBAAuB,EAAE;GAEzB,YAAY,EAIV,eAAe;IACb,MAAM,KAAK,QAAQ,aAAa,KAAK;IAErC,MAAM,yBAAyB,MAAM,cAAc,IAAI,KAAK;AAC5D,QAAI,CAAC,GAAG,UAAU,GAAG,SAAS;AAC5B,uBAAkB;AAClB;;IAEF,MAAM,cAAc,OAAO,IAAI,QAAQ,iBAAiB;IACxD,MAAM,iBAAiB,OAAO,IAAI,WAAW,iBAAiB;AAC9D,iBAAa;AACX,kBAAa;AACb,qBAAgB;;MAGrB;GAED,eAAe,EAOb,eAAe;AACb,YAAQ,aAAa,KAAK;AAC1B,cAAU,KAAK;AACf,iBAAa,MAAM,cAAc,IAAI,MAAM;MAE9C;GACF;EACF,CAAC;;AAGJ,MAAa,oBAAoB,eAAe;CAC9C,WAAW,CAAC,iBAAiB,eAAe;CAC5C,aAAa,CAAC,eAAe;CAC7B,OAAO;CACR,CAAC"}

package/dist/dev/playback/behaviors/dom/track-playback-rate.d.ts

@@ -0,0 +1,34 @@
+import { ReadonlySignal, Signal } from "../../../core/signals/primitives.js";
+
+//#region src/playback/behaviors/dom/track-playback-rate.d.ts
+interface PlaybackRateState {
+  playbackRate?: number;
+}
+interface PlaybackRateContext {
+  mediaElement?: HTMLMediaElement | undefined;
+}
+interface TrackPlaybackRateConfig {
+  /**
+   * Value written to `state.playbackRate` when no media element is attached.
+   * Defaults to `1` — the HTMLMediaElement spec default.
+   */
+  defaultPlaybackRate?: number;
+}
+declare const trackPlaybackRate: {
+  stateKeys: readonly ["playbackRate"];
+  contextKeys: readonly ["mediaElement"];
+  setup: (deps: {
+    state: {
+      playbackRate: Signal<PlaybackRateState['playbackRate']>;
+    };
+  } & {
+    context: {
+      mediaElement: ReadonlySignal<PlaybackRateContext['mediaElement']>;
+    };
+  } & {
+    config: TrackPlaybackRateConfig;
+  }) => () => void;
+};
+//#endregion
+export { PlaybackRateContext, PlaybackRateState, trackPlaybackRate };
+//# sourceMappingURL=track-playback-rate.d.ts.map

package/dist/dev/playback/behaviors/dom/track-playback-rate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-playback-rate.d.ts","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-playback-rate.ts"],"mappings":";;;UAgBiB,iBAAA;EACf,YAAA;AAAA;AAAA,UAGe,mBAAA;EACf,YAAA,GAAe,gBAAA;AAAA;AAAA,UAGA,uBAAA;EAJA;;;;EASf,mBAAA;AAAA;AAAA,cA2BW,iBAAA;;;;;oBAnBY,MAAA,CAAO,iBAAA;IAAA;EAAA;;oBACL,cAAA,CAAe,mBAAA;IAAA;EAAA"}

package/dist/dev/playback/behaviors/dom/track-playback-rate.js

@@ -0,0 +1,37 @@
+import { defineBehavior } from "../../../core/composition/create-composition.js";
+import { effect } from "../../../core/signals/effect.js";
+import { listen } from "@videojs/utils/dom";
+//#region src/playback/behaviors/dom/track-playback-rate.ts
+/**
+* Mirror `mediaElement.playbackRate` into reactive state. On each `ratechange`
+* event, write the new value to `state.playbackRate`. Also syncs immediately
+* when a media element becomes available so consumers don't wait for the first
+* event.
+*
+* When no media element is attached, writes `config.defaultPlaybackRate`
+* (default-default `1`, matching the HTMLMediaElement spec) so consumers
+* always see the rate a freshly attached element would have. Read-only mirror;
+* does not push `state.playbackRate` back to the element.
+*/
+function trackPlaybackRateSetup({ state, context, config }) {
+	const defaultPlaybackRate = config?.defaultPlaybackRate ?? 1;
+	return effect(() => {
+		const mediaElement = context.mediaElement.get();
+		if (!mediaElement) {
+			state.playbackRate.set(defaultPlaybackRate);
+			return;
+		}
+		const sync = () => state.playbackRate.set(mediaElement.playbackRate);
+		sync();
+		return listen(mediaElement, "ratechange", sync);
+	});
+}
+const trackPlaybackRate = defineBehavior({
+	stateKeys: ["playbackRate"],
+	contextKeys: ["mediaElement"],
+	setup: trackPlaybackRateSetup
+});
+//#endregion
+export { trackPlaybackRate };
+
+//# sourceMappingURL=track-playback-rate.js.map

package/dist/dev/playback/behaviors/dom/track-playback-rate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-playback-rate.js","names":[],"sources":["../../../../../src/playback/behaviors/dom/track-playback-rate.ts"],"sourcesContent":["/**\n * Mirror `mediaElement.playbackRate` into reactive state. On each `ratechange`\n * event, write the new value to `state.playbackRate`. Also syncs immediately\n * when a media element becomes available so consumers don't wait for the first\n * event.\n *\n * When no media element is attached, writes `config.defaultPlaybackRate`\n * (default-default `1`, matching the HTMLMediaElement spec) so consumers\n * always see the rate a freshly attached element would have. Read-only mirror;\n * does not push `state.playbackRate` back to the element.\n */\nimport { listen } from '@videojs/utils/dom';\nimport { defineBehavior } from '../../../core/composition/create-composition';\nimport { effect } from '../../../core/signals/effect';\nimport type { ReadonlySignal, Signal } from '../../../core/signals/primitives';\n\nexport interface PlaybackRateState {\n  playbackRate?: number;\n}\n\nexport interface PlaybackRateContext {\n  mediaElement?: HTMLMediaElement | undefined;\n}\n\nexport interface TrackPlaybackRateConfig {\n  /**\n   * Value written to `state.playbackRate` when no media element is attached.\n   * Defaults to `1` — the HTMLMediaElement spec default.\n   */\n  defaultPlaybackRate?: number;\n}\n\nfunction trackPlaybackRateSetup({\n  state,\n  context,\n  config,\n}: {\n  state: { playbackRate: Signal<PlaybackRateState['playbackRate']> };\n  context: { mediaElement: ReadonlySignal<PlaybackRateContext['mediaElement']> };\n  config?: TrackPlaybackRateConfig;\n}): () => void {\n  const defaultPlaybackRate = config?.defaultPlaybackRate ?? 1;\n\n  return effect(() => {\n    const mediaElement = context.mediaElement.get();\n    if (!mediaElement) {\n      state.playbackRate.set(defaultPlaybackRate);\n      return;\n    }\n\n    const sync = () => state.playbackRate.set(mediaElement.playbackRate);\n    sync();\n    return listen(mediaElement, 'ratechange', sync);\n  });\n}\n\nexport const trackPlaybackRate = defineBehavior({\n  stateKeys: ['playbackRate'],\n  contextKeys: ['mediaElement'],\n  setup: trackPlaybackRateSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;AAgCA,SAAS,uBAAuB,EAC9B,OACA,SACA,UAKa;CACb,MAAM,sBAAsB,QAAQ,uBAAuB;AAE3D,QAAO,aAAa;EAClB,MAAM,eAAe,QAAQ,aAAa,KAAK;AAC/C,MAAI,CAAC,cAAc;AACjB,SAAM,aAAa,IAAI,oBAAoB;AAC3C;;EAGF,MAAM,aAAa,MAAM,aAAa,IAAI,aAAa,aAAa;AACpE,QAAM;AACN,SAAO,OAAO,cAAc,cAAc,KAAK;GAC/C;;AAGJ,MAAa,oBAAoB,eAAe;CAC9C,WAAW,CAAC,eAAe;CAC3B,aAAa,CAAC,eAAe;CAC7B,OAAO;CACR,CAAC"}

package/dist/dev/playback/behaviors/dom/update-mediasource-duration.js

@@ -0,0 +1,90 @@
+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 { getMaxBufferedEnd, shouldUpdateDuration, waitForSourceBuffersReady } from "../../../media/dom/mse/duration.js";
+import { waitForMediaSourceOpen } from "../../../media/dom/mse/mediasource-setup.js";
+//#region src/playback/behaviors/dom/update-mediasource-duration.ts
+/**
+* **Propagate `presentation.duration` to `mediaSource.duration` — exactly
+* once per MediaSource.**
+*
+* When the presentation has a valid positive duration (including `Infinity`
+* for live) and a MediaSource is in context, writes the value through to
+* `mediaSource.duration` on initial setup — once, while `mediaSource.duration`
+* is still `NaN`. Once any non-NaN value is present (set by us, or by
+* `endOfStream` from the buffered end), the behavior leaves the property
+* alone; re-syncing a drift against `presentation.duration` would race with
+* concurrent `appendBuffer()` calls.
+*
+* The entry resolves three async preconditions in order before writing:
+*
+* 1. **MediaSource open** — `waitForMediaSourceOpen` defers until the first
+*    `sourceopen` event (or any readyState transition, since `'ended'` /
+*    `'closed'` mean we've missed the window and should bail).
+* 2. **All SourceBuffers idle** — `waitForSourceBuffersReady` defers per
+*    the MSE-spec rule that `duration` cannot be set while any buffer has
+*    `updating === true`.
+* 3. **Buffered-range clamp** — `getMaxBufferedEnd` ensures the written
+*    duration is at least the highest buffered end (MSE spec disallows
+*    a smaller `duration` than any buffered range).
+*
+* The buffer-set helpers operate across `mediaSource.sourceBuffers` (the
+* canonical aggregate), so the behavior composes uniformly across
+* audio-only, video-only, and mixed configurations.
+*
+* Single-positive-state reactor (`'preconditions-unmet'` ↔ `'duration-writable'`):
+* state derivation is purely signal-driven (presentation validity +
+* mediaSource existence). MediaSource lifecycle state (`readyState`) and
+* the `duration` itself are non-signal DOM properties resolved inside the
+* entry's async sequence. The state-exit cleanup aborts the in-flight
+* wait, so source resets and behavior destroy structurally cancel the
+* pending write. A post-await re-check of `mediaSource.readyState ===
+* 'open'` covers the narrow race where `endOfStream()` synchronously
+* transitions readyState to `'ended'` between our `waitForMediaSourceOpen`
+* resolution and the `mediaSource.duration` write.
+*
+* Downstream of `calculatePresentationDuration` (which writes
+* `presentation.duration`); concurrent with `endOfStream` (which may later
+* write `mediaSource.duration` — the "exactly once" contract keeps us out
+* of that path).
+*/
+function deriveState(presentation, mediaSource) {
+	return shouldUpdateDuration(presentation, mediaSource) ? "duration-writable" : "preconditions-unmet";
+}
+function updateMediaSourceDurationSetup({ state, context }) {
+	const derivedStateSignal = computed(() => deriveState(state.presentation.get(), context.mediaSource.get()));
+	return createMachineReactor({
+		initial: "preconditions-unmet",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"preconditions-unmet": {},
+			"duration-writable": { entry: () => {
+				const presentation = state.presentation.get();
+				const mediaSource = context.mediaSource.get();
+				if (!Number.isNaN(mediaSource.duration)) return;
+				const controller = new AbortController();
+				const writeWhenReady = async () => {
+					await waitForMediaSourceOpen(mediaSource, controller.signal);
+					if (controller.signal.aborted) return;
+					if (mediaSource.readyState !== "open") return;
+					await waitForSourceBuffersReady(mediaSource.sourceBuffers, controller.signal);
+					if (controller.signal.aborted) return;
+					if (mediaSource.readyState !== "open") return;
+					const maxBufferedEnd = getMaxBufferedEnd(mediaSource.sourceBuffers);
+					mediaSource.duration = maxBufferedEnd > presentation.duration ? maxBufferedEnd : presentation.duration;
+				};
+				writeWhenReady();
+				return () => controller.abort();
+			} }
+		}
+	});
+}
+const updateMediaSourceDuration = defineBehavior({
+	stateKeys: ["presentation"],
+	contextKeys: ["mediaSource"],
+	setup: updateMediaSourceDurationSetup
+});
+//#endregion
+export { updateMediaSourceDuration };
+
+//# sourceMappingURL=update-mediasource-duration.js.map

package/dist/dev/playback/behaviors/dom/update-mediasource-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-mediasource-duration.js","names":[],"sources":["../../../../../src/playback/behaviors/dom/update-mediasource-duration.ts"],"sourcesContent":["/**\n * **Propagate `presentation.duration` to `mediaSource.duration` — exactly\n * once per MediaSource.**\n *\n * When the presentation has a valid positive duration (including `Infinity`\n * for live) and a MediaSource is in context, writes the value through to\n * `mediaSource.duration` on initial setup — once, while `mediaSource.duration`\n * is still `NaN`. Once any non-NaN value is present (set by us, or by\n * `endOfStream` from the buffered end), the behavior leaves the property\n * alone; re-syncing a drift against `presentation.duration` would race with\n * concurrent `appendBuffer()` calls.\n *\n * The entry resolves three async preconditions in order before writing:\n *\n * 1. **MediaSource open** — `waitForMediaSourceOpen` defers until the first\n *    `sourceopen` event (or any readyState transition, since `'ended'` /\n *    `'closed'` mean we've missed the window and should bail).\n * 2. **All SourceBuffers idle** — `waitForSourceBuffersReady` defers per\n *    the MSE-spec rule that `duration` cannot be set while any buffer has\n *    `updating === true`.\n * 3. **Buffered-range clamp** — `getMaxBufferedEnd` ensures the written\n *    duration is at least the highest buffered end (MSE spec disallows\n *    a smaller `duration` than any buffered range).\n *\n * The buffer-set helpers operate across `mediaSource.sourceBuffers` (the\n * canonical aggregate), so the behavior composes uniformly across\n * audio-only, video-only, and mixed configurations.\n *\n * Single-positive-state reactor (`'preconditions-unmet'` ↔ `'duration-writable'`):\n * state derivation is purely signal-driven (presentation validity +\n * mediaSource existence). MediaSource lifecycle state (`readyState`) and\n * the `duration` itself are non-signal DOM properties resolved inside the\n * entry's async sequence. The state-exit cleanup aborts the in-flight\n * wait, so source resets and behavior destroy structurally cancel the\n * pending write. A post-await re-check of `mediaSource.readyState ===\n * 'open'` covers the narrow race where `endOfStream()` synchronously\n * transitions readyState to `'ended'` between our `waitForMediaSourceOpen`\n * resolution and the `mediaSource.duration` write.\n *\n * Downstream of `calculatePresentationDuration` (which writes\n * `presentation.duration`); concurrent with `endOfStream` (which may later\n * write `mediaSource.duration` — the \"exactly once\" contract keeps us out\n * of that path).\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 } from '../../../core/signals/primitives';\nimport { getMaxBufferedEnd, shouldUpdateDuration, waitForSourceBuffersReady } from '../../../media/dom/mse/duration';\nimport { waitForMediaSourceOpen } from '../../../media/dom/mse/mediasource-setup';\nimport type { MaybeResolvedPresentation } from '../../../media/types';\n\ntype DurationFsmState = 'preconditions-unmet' | 'duration-writable';\n\nfunction deriveState(\n  presentation: MaybeResolvedPresentation | undefined,\n  mediaSource: MediaSource | undefined\n): DurationFsmState {\n  return shouldUpdateDuration(presentation, mediaSource) ? 'duration-writable' : 'preconditions-unmet';\n}\n\nfunction updateMediaSourceDurationSetup({\n  state,\n  context,\n}: {\n  state: { presentation: ReadonlySignal<MaybeResolvedPresentation | undefined> };\n  context: { mediaSource: ReadonlySignal<MediaSource | undefined> };\n}): Reactor<DurationFsmState | 'destroying' | 'destroyed'> {\n  // Purely signal-driven derivation: only `presentation` validity and\n  // `mediaSource` existence. MediaSource lifecycle (`readyState`),\n  // its attached `sourceBuffers`, and `mediaSource.duration` itself are\n  // non-signal DOM properties consumed inside the entry — none of them\n  // sneak into `computed(...)`.\n  const derivedStateSignal = computed(() => deriveState(state.presentation.get(), context.mediaSource.get()));\n\n  return createMachineReactor<DurationFsmState>({\n    initial: 'preconditions-unmet',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'preconditions-unmet': {},\n\n      'duration-writable': {\n        // entry body is auto-untracked. The state machine handles source\n        // resets via deriveState; this entry resolves the MediaSource\n        // lifecycle preconditions in sequence and binds its cleanup\n        // (abort) to state exit + destroy.\n        entry: () => {\n          const presentation = state.presentation.get()!;\n          const mediaSource = context.mediaSource.get()!;\n\n          // Idempotency: someone (us on a prior entry, or concurrent\n          // `endOfStream`) has already written. No-op and leave the state\n          // alone — the next source-reset transition will produce a fresh\n          // entry against the new MediaSource (whose `duration` starts at\n          // `NaN` again).\n          if (!Number.isNaN(mediaSource.duration)) return;\n\n          const controller = new AbortController();\n\n          const writeWhenReady = async () => {\n            await waitForMediaSourceOpen(mediaSource, controller.signal);\n            if (controller.signal.aborted) return;\n            // `waitForMediaSourceOpen` resolves on any readyState transition\n            // out of 'closed'; if we landed in 'ended' / 'closed' instead of\n            // 'open', the write window is gone.\n            if (mediaSource.readyState !== 'open') return;\n\n            await waitForSourceBuffersReady(mediaSource.sourceBuffers, controller.signal);\n            if (controller.signal.aborted) return;\n\n            // Narrow race: `endOfStream()` synchronously transitions\n            // readyState to 'ended' AND writes `mediaSource.duration`\n            // between our `waitForMediaSourceOpen` resolution and here.\n            // Re-read the DOM property to catch this window.\n            if (mediaSource.readyState !== 'open') return;\n\n            // MSE spec: duration cannot be less than any buffered range.\n            // Re-read sourceBuffers after the await so any buffer added\n            // during the wait is included in the clamp.\n            const maxBufferedEnd = getMaxBufferedEnd(mediaSource.sourceBuffers);\n            const duration = maxBufferedEnd > presentation.duration! ? maxBufferedEnd : presentation.duration!;\n            mediaSource.duration = duration;\n          };\n\n          writeWhenReady();\n\n          return () => controller.abort();\n        },\n      },\n    },\n  });\n}\n\nexport const updateMediaSourceDuration = defineBehavior({\n  stateKeys: ['presentation'],\n  contextKeys: ['mediaSource'],\n  setup: updateMediaSourceDurationSetup,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAS,YACP,cACA,aACkB;AAClB,QAAO,qBAAqB,cAAc,YAAY,GAAG,sBAAsB;;AAGjF,SAAS,+BAA+B,EACtC,OACA,WAIyD;CAMzD,MAAM,qBAAqB,eAAe,YAAY,MAAM,aAAa,KAAK,EAAE,QAAQ,YAAY,KAAK,CAAC,CAAC;AAE3G,QAAO,qBAAuC;EAC5C,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,uBAAuB,EAAE;GAEzB,qBAAqB,EAKnB,aAAa;IACX,MAAM,eAAe,MAAM,aAAa,KAAK;IAC7C,MAAM,cAAc,QAAQ,YAAY,KAAK;AAO7C,QAAI,CAAC,OAAO,MAAM,YAAY,SAAS,CAAE;IAEzC,MAAM,aAAa,IAAI,iBAAiB;IAExC,MAAM,iBAAiB,YAAY;AACjC,WAAM,uBAAuB,aAAa,WAAW,OAAO;AAC5D,SAAI,WAAW,OAAO,QAAS;AAI/B,SAAI,YAAY,eAAe,OAAQ;AAEvC,WAAM,0BAA0B,YAAY,eAAe,WAAW,OAAO;AAC7E,SAAI,WAAW,OAAO,QAAS;AAM/B,SAAI,YAAY,eAAe,OAAQ;KAKvC,MAAM,iBAAiB,kBAAkB,YAAY,cAAc;AAEnE,iBAAY,WADK,iBAAiB,aAAa,WAAY,iBAAiB,aAAa;;AAI3F,oBAAgB;AAEhB,iBAAa,WAAW,OAAO;MAElC;GACF;EACF,CAAC;;AAGJ,MAAa,4BAA4B,eAAe;CACtD,WAAW,CAAC,eAAe;CAC3B,aAAa,CAAC,cAAc;CAC5B,OAAO;CACR,CAAC"}

package/dist/dev/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/dev/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/dev/playback/behaviors/resolve-presentation.d.ts

@@ -0,0 +1,7 @@
+import { MaybeResolvedPresentation, Presentation } from "../../media/types/index.js";
+
+//#region src/playback/behaviors/resolve-presentation.d.ts
+type ParsePresentation = (text: string, presentation: MaybeResolvedPresentation) => Presentation;
+//#endregion
+export { ParsePresentation };
+//# sourceMappingURL=resolve-presentation.d.ts.map

package/dist/dev/playback/behaviors/resolve-presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-presentation.d.ts","names":[],"sources":["../../../../src/playback/behaviors/resolve-presentation.ts"],"mappings":";;;KAiDY,iBAAA,IAAqB,IAAA,UAAc,YAAA,EAAc,yBAAA,KAA8B,YAAA"}