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

package/dist/default/core/create-machine-reactor.js

@@ -0,0 +1,83 @@
+import { effect } from "./signals/effect.js";
+import { untrack } from "./signals/primitives.js";
+import { createMachineCore } from "./machine.js";
+//#region src/core/create-machine-reactor.ts
+const toArray = (x) => x === void 0 ? [] : Array.isArray(x) ? x : [x];
+/**
+* Creates a reactive Reactor from a declarative definition.
+*
+* A Reactor is driven by subscriptions to external signals rather than
+* imperative messages. Each state holds an array of effect functions —
+* every element becomes one independent `effect()` call gated on that state,
+* with its own dependency tracking and cleanup lifecycle.
+*
+* `'destroying'` and `'destroyed'` are always implicit terminal states.
+* `destroy()` transitions through both in sequence: `'destroying'` first (for
+* potential async teardown in a future extension), then immediately `'destroyed'`
+* for the synchronous base case. Active effect cleanups fire via disposal.
+*
+* @example
+* const reactor = createMachineReactor({
+*   initial: 'waiting',
+*   monitor: () => srcSignal.get() ? 'active' : 'waiting',
+*   states: {
+*     active: {
+*       // entry: runs once on state entry; fn body is automatically untracked.
+*       entry: () => listen(el, 'play', handler),
+*       // effects: re-runs whenever tracked signals change.
+*       effects: () => { currentTimeSignal.get(); return cleanup; },
+*     },
+*     waiting: {},
+*   }
+* });
+*/
+function createMachineReactor(def) {
+	const { snapshotSignal, getState, transition } = createMachineCore({ value: def.initial });
+	const effectDisposals = [];
+	const wrapResult = (result) => {
+		if (!result) return void 0;
+		if (typeof result === "function") return result;
+		return () => result.abort();
+	};
+	const untracked = (baseCall) => () => untrack(baseCall);
+	const isTerminal = (snapshot) => snapshot.value === "destroying" || snapshot.value === "destroyed";
+	const descriptors = [...toArray(def.monitor).map((fn) => ({
+		fn: () => {
+			const target = fn();
+			if (target !== getState()) transition(target);
+		},
+		shouldSkip: isTerminal
+	})), ...Object.entries(def.states).flatMap(([state, stateDef]) => {
+		const isNotState = (snapshot) => snapshot.value !== state;
+		return [...toArray(stateDef.entry).map((fn) => ({
+			fn,
+			shouldSkip: isNotState,
+			toFnCall: untracked
+		})), ...toArray(stateDef.effects).map((fn) => ({
+			fn,
+			shouldSkip: isNotState
+		}))];
+	})];
+	const toEffect = ({ fn, shouldSkip, toFnCall = (baseCall) => baseCall }) => effect(() => {
+		if (shouldSkip(snapshotSignal.get())) return;
+		const baseCall = () => fn();
+		return wrapResult(toFnCall(baseCall)());
+	});
+	effectDisposals.push(...descriptors.map(toEffect));
+	return {
+		get snapshot() {
+			return snapshotSignal;
+		},
+		destroy() {
+			const state = getState();
+			if (state === "destroying" || state === "destroyed") return;
+			transition("destroying");
+			transition("destroyed");
+			for (const dispose of effectDisposals) dispose();
+		}
+	};
+}
+//#endregion
+export { createMachineReactor };
+
+//# sourceMappingURL=create-machine-reactor.js.map

package/dist/default/core/create-machine-reactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-machine-reactor.js","names":[],"sources":["../../../src/core/create-machine-reactor.ts"],"sourcesContent":["import type { Machine, MachineSnapshot } from './machine';\nimport { createMachineCore } from './machine';\nimport { effect } from './signals/effect';\nimport { untrack } from './signals/primitives';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reactive state-deriving function used in the `monitor` field.\n *\n * Returns the target state the reactor should be in. Any signals read inside\n * the fn body create reactive dependencies — the framework re-evaluates it when\n * those signals change and automatically calls `transition()` when the returned\n * state differs from the current one.\n */\nexport type ReactorDeriveFn<State extends string> = () => State;\n\n/**\n * An effect function used in reactor `entry` and `effects` blocks.\n *\n * May return a cleanup function that runs before each re-evaluation and on\n * state exit (including destroy).\n */\nexport type ReactorEffectFn = () => (() => void) | { abort(): void } | void;\n\n/**\n * Per-state effect grouping for a single reactor state.\n *\n * - `entry` effects run once on state entry. The fn body is automatically\n *   untracked — no `untrack()` calls are needed inside. Use this for\n *   one-time setup: reading current values, attaching event listeners, etc.\n * - `effects` run on state entry and re-run whenever a signal read inside\n *   the fn body changes. Use `untrack()` for reads you do not want to track.\n *   Use this for work that must stay in sync with reactive state.\n *\n * Both are optional; pass `{}` for states with no effects.\n */\nexport type ReactorStateDefinition = {\n  entry?: ReactorEffectFn | ReactorEffectFn[];\n  effects?: ReactorEffectFn | ReactorEffectFn[];\n};\n\n/**\n * Full reactor definition passed to `createMachineReactor`.\n *\n * `State` is the set of domain-meaningful states. `'destroying'` and\n * `'destroyed'` are always added by the framework as implicit terminal states —\n * do not include them here.\n */\nexport type ReactorDefinition<State extends string> = {\n  /** Initial state. */\n  initial: State;\n  /**\n   * Reactive state derivation. Registered before per-state effects — the\n   * ordering guarantee ensures transitions fired here take effect before\n   * per-state effects re-evaluate in the same flush.\n   */\n  monitor?: ReactorDeriveFn<State> | ReactorDeriveFn<State>[];\n  /**\n   * Per-state effect groupings. Every valid state must be declared — pass `{}`\n   * for states with no effects. `entry` and `effects` each become independent\n   * `effect()` calls gated on that state, with their own cleanup lifecycles.\n   */\n  states: Record<State, ReactorStateDefinition>;\n};\n\n// =============================================================================\n// Live reactor interface\n// =============================================================================\n\n/** Live reactor instance returned by `createMachineReactor`. */\nexport type Reactor<State extends string> = Machine<MachineSnapshot<State>>;\n\n// =============================================================================\n// Implementation helpers\n// =============================================================================\n\nconst toArray = <T>(x: T | T[] | undefined): T[] => (x === undefined ? [] : Array.isArray(x) ? x : [x]);\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reactive Reactor from a declarative definition.\n *\n * A Reactor is driven by subscriptions to external signals rather than\n * imperative messages. Each state holds an array of effect functions —\n * every element becomes one independent `effect()` call gated on that state,\n * with its own dependency tracking and cleanup lifecycle.\n *\n * `'destroying'` and `'destroyed'` are always implicit terminal states.\n * `destroy()` transitions through both in sequence: `'destroying'` first (for\n * potential async teardown in a future extension), then immediately `'destroyed'`\n * for the synchronous base case. Active effect cleanups fire via disposal.\n *\n * @example\n * const reactor = createMachineReactor({\n *   initial: 'waiting',\n *   monitor: () => srcSignal.get() ? 'active' : 'waiting',\n *   states: {\n *     active: {\n *       // entry: runs once on state entry; fn body is automatically untracked.\n *       entry: () => listen(el, 'play', handler),\n *       // effects: re-runs whenever tracked signals change.\n *       effects: () => { currentTimeSignal.get(); return cleanup; },\n *     },\n *     waiting: {},\n *   }\n * });\n */\nexport function createMachineReactor<State extends string>(\n  def: ReactorDefinition<State>\n): Reactor<State | 'destroying' | 'destroyed'> {\n  type FullState = State | 'destroying' | 'destroyed';\n\n  const { snapshotSignal, getState, transition } = createMachineCore<FullState, MachineSnapshot<FullState>>({\n    value: def.initial as FullState,\n  });\n\n  const effectDisposals: Array<() => void> = [];\n\n  const wrapResult = (result: ReturnType<ReactorEffectFn>) => {\n    if (!result) return undefined;\n    if (typeof result === 'function') return result;\n    return () => result.abort();\n  };\n\n  type EffectCall = () => ReturnType<ReactorEffectFn>;\n\n  type EffectDescriptor = {\n    fn: ReactorEffectFn;\n    shouldSkip: (snapshot: { value: FullState }) => boolean;\n    toFnCall?: (baseCall: EffectCall) => EffectCall;\n  };\n\n  const untracked: EffectDescriptor['toFnCall'] = (baseCall) => () => untrack(baseCall);\n\n  const isTerminal = (snapshot: { value: FullState }) =>\n    snapshot.value === 'destroying' || snapshot.value === 'destroyed';\n\n  // `monitor` descriptors are built first — the ordering guarantee ensures\n  // transitions they trigger take effect before per-state effects re-evaluate\n  // in the same flush. See the comment on effect registration order in the\n  // previous implementation for full details.\n  const descriptors: EffectDescriptor[] = [\n    ...toArray(def.monitor).map((fn) => ({\n      fn: () => {\n        const target = fn();\n        if (target !== (getState() as State)) transition(target as FullState);\n      },\n      shouldSkip: isTerminal,\n    })),\n    ...(Object.entries(def.states) as Array<[State, ReactorStateDefinition]>).flatMap(([state, stateDef]) => {\n      const isNotState = (snapshot: { value: FullState }) => snapshot.value !== state;\n      return [\n        ...toArray(stateDef.entry).map((fn) => ({ fn, shouldSkip: isNotState, toFnCall: untracked })),\n        ...toArray(stateDef.effects).map((fn) => ({ fn, shouldSkip: isNotState })),\n      ];\n    }),\n  ];\n\n  const toEffect = ({ fn, shouldSkip, toFnCall = (baseCall) => baseCall }: EffectDescriptor) =>\n    effect(() => {\n      const snapshot = snapshotSignal.get();\n      if (shouldSkip(snapshot)) return;\n      const baseCall = () => fn();\n      return wrapResult(toFnCall(baseCall)());\n    });\n\n  effectDisposals.push(...descriptors.map(toEffect));\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    destroy(): void {\n      const state = getState();\n      if (state === 'destroying' || state === 'destroyed') return;\n      // Two-step teardown: transition through 'destroying' first to leave room\n      // for async teardown in a future extension, then immediately 'destroyed'\n      // for the synchronous base case. Active effect cleanups fire via disposal.\n      transition('destroying');\n      transition('destroyed');\n      for (const dispose of effectDisposals) dispose();\n    },\n  };\n}\n"],"mappings":";;;;AA+EA,MAAM,WAAc,MAAiC,MAAM,KAAA,IAAY,EAAE,GAAG,MAAM,QAAQ,EAAE,GAAG,IAAI,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCtG,SAAgB,qBACd,KAC6C;CAG7C,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAyD,EACxG,OAAO,IAAI,SACZ,CAAC;CAEF,MAAM,kBAAqC,EAAE;CAE7C,MAAM,cAAc,WAAwC;AAC1D,MAAI,CAAC,OAAQ,QAAO,KAAA;AACpB,MAAI,OAAO,WAAW,WAAY,QAAO;AACzC,eAAa,OAAO,OAAO;;CAW7B,MAAM,aAA2C,mBAAmB,QAAQ,SAAS;CAErF,MAAM,cAAc,aAClB,SAAS,UAAU,gBAAgB,SAAS,UAAU;CAMxD,MAAM,cAAkC,CACtC,GAAG,QAAQ,IAAI,QAAQ,CAAC,KAAK,QAAQ;EACnC,UAAU;GACR,MAAM,SAAS,IAAI;AACnB,OAAI,WAAY,UAAU,CAAY,YAAW,OAAoB;;EAEvE,YAAY;EACb,EAAE,EACH,GAAI,OAAO,QAAQ,IAAI,OAAO,CAA4C,SAAS,CAAC,OAAO,cAAc;EACvG,MAAM,cAAc,aAAmC,SAAS,UAAU;AAC1E,SAAO,CACL,GAAG,QAAQ,SAAS,MAAM,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,UAAU;GAAW,EAAE,EAC7F,GAAG,QAAQ,SAAS,QAAQ,CAAC,KAAK,QAAQ;GAAE;GAAI,YAAY;GAAY,EAAE,CAC3E;GACD,CACH;CAED,MAAM,YAAY,EAAE,IAAI,YAAY,YAAY,aAAa,eAC3D,aAAa;AAEX,MAAI,WADa,eAAe,KAAK,CACb,CAAE;EAC1B,MAAM,iBAAiB,IAAI;AAC3B,SAAO,WAAW,SAAS,SAAS,EAAE,CAAC;GACvC;AAEJ,iBAAgB,KAAK,GAAG,YAAY,IAAI,SAAS,CAAC;AAElD,QAAO;EACL,IAAI,WAAW;AACb,UAAO;;EAGT,UAAgB;GACd,MAAM,QAAQ,UAAU;AACxB,OAAI,UAAU,gBAAgB,UAAU,YAAa;AAIrD,cAAW,aAAa;AACxB,cAAW,YAAY;AACvB,QAAK,MAAM,WAAW,gBAAiB,UAAS;;EAEnD"}

package/dist/default/core/create-transition-actor.js

@@ -0,0 +1,46 @@
+import { untrack, update } from "./signals/primitives.js";
+import { createMachineCore } from "./machine.js";
+//#region src/core/create-transition-actor.ts
+/**
+* Creates a reducer-shaped actor from an initial context and a reducer function.
+*
+* The reducer receives the current context and a message and returns the next
+* context. Returning the same reference (by identity) skips the signal update —
+* so early-returning `context` unchanged is both the no-op and the optimization.
+*
+* Side effects (e.g. DOM mutations) may be performed inside the reducer.
+* They run synchronously before the signal is updated.
+*
+* @example
+* const actor = createTransitionActor(
+*   { count: 0 },
+*   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })
+* );
+*/
+function createTransitionActor(initialContext, reducer) {
+	const { snapshotSignal, getState, transition } = createMachineCore({
+		value: "active",
+		context: initialContext
+	});
+	const getContext = () => untrack(() => snapshotSignal.get().context);
+	const setContext = (context) => update(snapshotSignal, { context });
+	return {
+		get snapshot() {
+			return snapshotSignal;
+		},
+		send(message) {
+			if (getState() === "destroyed") return;
+			const context = getContext();
+			const newContext = reducer(context, message);
+			if (newContext !== context) setContext(newContext);
+		},
+		destroy() {
+			if (getState() === "destroyed") return;
+			transition("destroyed");
+		}
+	};
+}
+//#endregion
+export { createTransitionActor };
+
+//# sourceMappingURL=create-transition-actor.js.map

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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