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

package/dist/default/dom/network/fetch.js

@@ -0,0 +1,54 @@
+//#region src/dom/network/fetch.ts
+/**
+* Fetch resolvable from AddressableObject.
+*
+* Handles byte range requests if byteRange is present.
+* Returns native fetch Response for composability (can extract text, stream, etc.).
+*
+* @param addressable - Resource to fetch (url + optional byteRange)
+* @returns Promise resolving to Response
+*
+* @example
+* const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });
+* const text = await getResponseText(response);
+*
+* @example
+* // With byte range
+* const response = await fetchResolvable({
+*   url: 'https://example.com/file.mp4',
+*   byteRange: { start: 1000, end: 1999 }
+* });
+*/
+async function fetchResolvable(addressable, options) {
+	const headers = new Headers(options?.headers);
+	if (addressable.byteRange) {
+		const { start, end } = addressable.byteRange;
+		headers.set("Range", `bytes=${start}-${end}`);
+	}
+	const request = new Request(addressable.url, {
+		method: "GET",
+		headers,
+		...options
+	});
+	return fetch(request);
+}
+/**
+* Extract text from Response.
+*
+* Accepts minimal Response-like object (just needs text() method).
+* Returns promise from response.text().
+*
+* @param response - Response-like object with text() method
+* @returns Promise resolving to text content
+*
+* @example
+* const response = await fetchResolvable(addressable);
+* const text = await getResponseText(response);
+*/
+function getResponseText(response) {
+	return response.text();
+}
+//#endregion
+export { fetchResolvable, getResponseText };
+
+//# sourceMappingURL=fetch.js.map

package/dist/default/dom/network/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","names":[],"sources":["../../../../src/dom/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Two-function approach for composability:\n * 1. fetchResolvable() - Fetch AddressableObject (handles byte ranges)\n * 2. getResponseText() - Extract text from Response\n * 3. fetchResolvableStream() - Stream body as Uint8Array chunks\n */\n\nimport type { AddressableObject } from '../../core/types';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/**\n * Minimal Response-like interface for text extraction.\n * Allows testing without full Response object.\n */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * Fetch resolvable from AddressableObject.\n *\n * Handles byte range requests if byteRange is present.\n * Returns native fetch Response for composability (can extract text, stream, etc.).\n *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\n *\n * @example\n * const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });\n * const text = await getResponseText(response);\n *\n * @example\n * // With byte range\n * const response = await fetchResolvable({\n *   url: 'https://example.com/file.mp4',\n *   byteRange: { start: 1000, end: 1999 }\n * });\n */\nexport async function fetchResolvable(addressable: AddressableObject, options?: RequestInit): Promise<Response> {\n  const headers = new Headers(options?.headers);\n\n  // Add Range header for byte range requests\n  if (addressable.byteRange) {\n    const { start, end } = addressable.byteRange;\n    headers.set('Range', `bytes=${start}-${end}`);\n  }\n\n  const request = new Request(addressable.url, {\n    method: 'GET',\n    headers,\n    ...options,\n  });\n\n  return fetch(request);\n}\n\n/**\n * Fetch resolvable as bytes.\n *\n * Convenience wrapper around fetchResolvable that resolves the body as an\n * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).\n * For text or streaming consumption, use fetchResolvable directly.\n */\nexport async function fetchResolvableBytes(\n  addressable: AddressableObject,\n  options?: RequestInit\n): Promise<ArrayBuffer> {\n  const response = await fetchResolvable(addressable, options);\n  return response.arrayBuffer();\n}\n\n/**\n * Fetch resolvable as a stream of Uint8Array chunks.\n *\n * Convenience wrapper around fetchResolvable that yields the body as chunks\n * via ChunkedStreamIterable. Headers are awaited before the first chunk is\n * yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status).\n * Errors from the underlying stream propagate naturally as thrown errors.\n */\nexport async function* fetchResolvableStream(\n  addressable: AddressableObject,\n  options?: RequestInit & ChunkedStreamIterableOptions\n): AsyncGenerator<Uint8Array> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  yield* new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Extract text from Response.\n *\n * Accepts minimal Response-like object (just needs text() method).\n * Returns promise from response.text().\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\n *\n * @example\n * const response = await fetchResolvable(addressable);\n * const text = await getResponseText(response);\n */\nexport function getResponseText(response: ResponseLike): Promise<string> {\n  return response.text();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwCA,eAAsB,gBAAgB,aAAgC,SAA0C;CAC9G,MAAM,UAAU,IAAI,QAAQ,SAAS,QAAQ;AAG7C,KAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;AACnC,UAAQ,IAAI,SAAS,SAAS,MAAM,GAAG,MAAM;;CAG/C,MAAM,UAAU,IAAI,QAAQ,YAAY,KAAK;EAC3C,QAAQ;EACR;EACA,GAAG;EACJ,CAAC;AAEF,QAAO,MAAM,QAAQ;;;;;;;;;;;;;;;AAmDvB,SAAgB,gBAAgB,UAAyC;AACvE,QAAO,SAAS,MAAM"}

package/dist/default/dom/playback-engine/adapter.js

@@ -0,0 +1,100 @@
+import { update } from "../../core/signals/primitives.js";
+import { createPlaybackEngine } from "./engine.js";
+//#region src/dom/playback-engine/adapter.ts
+/**
+* Mixin that adds SPF playback engine behavior to any base class.
+*
+* Implements the src/play() contract per the WHATWG HTML spec so that SPF can
+* be used anywhere a media element API is expected.
+*
+* A new engine is created on every src assignment — this fully tears down all
+* state, SourceBuffers, and in-flight requests from the previous source before
+* the next one begins. The media element reference is preserved across src
+* changes and re-applied to the new engine automatically.
+*
+* @example
+* class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+*
+* const media = new SimpleHlsMedia();
+* media.attach(document.querySelector('video'));
+* media.src = 'https://stream.mux.com/abc123.m3u8';
+*/
+function SpfMediaMixin(BaseClass) {
+	class SpfMediaImpl extends BaseClass {
+		#engine;
+		#config;
+		#preload = "";
+		/** Pending loadstart listener from a deferred play() retry, if any. */
+		#loadstartListener = null;
+		constructor(...args) {
+			super(...args);
+			const { config } = args?.[0] ?? {};
+			this.#config = config;
+			this.#engine = createPlaybackEngine(config);
+		}
+		get engine() {
+			return this.#engine;
+		}
+		attach(mediaElement) {
+			super.attach?.(mediaElement);
+			update(this.#engine.owners, { mediaElement });
+		}
+		detach() {
+			this.#cancelPendingPlay();
+			update(this.#engine.owners, { mediaElement: void 0 });
+			super.detach?.();
+		}
+		destroy() {
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+		}
+		get preload() {
+			return this.#preload;
+		}
+		set preload(value) {
+			this.#preload = value;
+			if (value) update(this.#engine.state, { preload: value });
+		}
+		get src() {
+			return this.#engine.state.get().presentation?.url ?? "";
+		}
+		set src(value) {
+			const prevMediaElement = this.#engine.owners.get().mediaElement;
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+			this.#engine = createPlaybackEngine(this.#config);
+			if (this.#preload) update(this.#engine.state, { preload: this.#preload });
+			if (prevMediaElement) update(this.#engine.owners, { mediaElement: prevMediaElement });
+			if (value) update(this.#engine.state, { presentation: { url: value } });
+		}
+		play() {
+			const { mediaElement } = this.#engine.owners.get();
+			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("SpfMedia: no media element attached"));
+			update(this.#engine.state, { playbackInitiated: true });
+			return mediaElement.play().catch((err) => {
+				if (this.src) return new Promise((resolve, reject) => {
+					const listener = () => {
+						this.#loadstartListener = null;
+						mediaElement.play().then(resolve, reject);
+					};
+					this.#loadstartListener = listener;
+					mediaElement.addEventListener("loadstart", listener, { once: true });
+				});
+				throw err;
+			});
+		}
+		#cancelPendingPlay() {
+			if (!this.#loadstartListener) return;
+			const { mediaElement } = this.#engine.owners.get();
+			mediaElement?.removeEventListener("loadstart", this.#loadstartListener);
+			this.#loadstartListener = null;
+		}
+	}
+	return SpfMediaImpl;
+}
+/** Standalone SPF media adapter with no base class. */
+var SpfMedia = class extends SpfMediaMixin(class {}) {};
+//#endregion
+export { SpfMedia, SpfMediaMixin };
+
+//# sourceMappingURL=adapter.js.map

package/dist/default/dom/playback-engine/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["#config","#engine","#cancelPendingPlay","#preload","#loadstartListener"],"sources":["../../../../src/dom/playback-engine/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport { update } from '../../core/signals/primitives';\nimport type { PlaybackEngineConfig } from './engine';\nimport { createPlaybackEngine, type PlaybackEngine } from './engine';\n\nexport interface SpfMediaAPI {\n  readonly engine: PlaybackEngine;\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds SPF playback engine behavior to any base class.\n *\n * Implements the src/play() contract per the WHATWG HTML spec so that SPF can\n * be used anywhere a media element API is expected.\n *\n * A new engine is created on every src assignment — this fully tears down all\n * state, SourceBuffers, and in-flight requests from the previous source before\n * the next one begins. The media element reference is preserved across src\n * changes and re-applied to the new engine automatically.\n *\n * @example\n * class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new SimpleHlsMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n */\nexport function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class SpfMediaImpl extends BaseClass {\n    #engine: PlaybackEngine;\n    #config: PlaybackEngineConfig;\n    #preload: '' | 'none' | 'metadata' | 'auto' = '';\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n      this.#engine = createPlaybackEngine(config);\n    }\n\n    get engine(): PlaybackEngine {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      update(this.#engine.owners, { mediaElement });\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      update(this.#engine.owners, { mediaElement: undefined });\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // preload — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get preload(): '' | 'none' | 'metadata' | 'auto' {\n      return this.#preload;\n    }\n\n    set preload(value: '' | 'none' | 'metadata' | 'auto') {\n      this.#preload = value;\n      if (value) {\n        update(this.#engine.state, { preload: value });\n      }\n      // value = '' clears #preload (so the next engine recreation won't re-apply\n      // an explicit value) but does not patch current state — the existing preload\n      // stays in effect until the next src change creates a fresh engine.\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // Each assignment destroys the current engine and starts a fresh one, exactly\n    // as the browser's load algorithm resets all media element state on src change.\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#engine.state.get().presentation?.url ?? '';\n    }\n\n    set src(value: string) {\n      const prevMediaElement = this.#engine.owners.get().mediaElement;\n\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n      this.#engine = createPlaybackEngine(this.#config);\n\n      // Apply explicit preload before setting owners so syncPreloadAttribute skips\n      // element inference and the explicit value is preserved across src changes.\n      if (this.#preload) {\n        update(this.#engine.state, { preload: this.#preload });\n      }\n\n      if (prevMediaElement) {\n        update(this.#engine.owners, { mediaElement: prevMediaElement });\n      }\n\n      if (value) {\n        update(this.#engine.state, { presentation: { url: value } });\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    play(): Promise<void> {\n      const { mediaElement } = this.#engine.owners.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('SpfMedia: no media element attached'));\n      }\n\n      // Signal play intent — enables loading even with preload=\"none\"\n      update(this.#engine.state, { playbackInitiated: true });\n\n      return mediaElement.play().catch((err: unknown) => {\n        // If we have a pending HLS source, the rejection may be because MSE\n        // hasn't attached a blob URL yet. Wait for loadstart (src assigned\n        // by MSE setup) and retry once.\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      });\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const { mediaElement } = this.#engine.owners.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return SpfMediaImpl as unknown as MixinReturn<Base, SpfMediaAPI>;\n}\n\n/** Standalone SPF media adapter with no base class. */\nexport class SpfMedia extends SpfMediaMixin(class {}) {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,cAA6C,WAAiB;CAC5E,MAAM,qBAAqB,UAAU;EACnC;EACA;EACA,WAA8C;;EAG9C,qBAA0C;EAE1C,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;GAEd,MAAM,EAAE,WAAW,OAAO,MAAM,EAAE;AAClC,SAAA,SAAe;AACf,SAAA,SAAe,qBAAqB,OAAO;;EAG7C,IAAI,SAAyB;AAC3B,UAAO,MAAA;;EAOT,OAAO,cAAsC;AAC3C,SAAM,SAAS,aAAa;AAC5B,UAAO,MAAA,OAAa,QAAQ,EAAE,cAAc,CAAC;;EAG/C,SAAe;AACb,SAAA,mBAAyB;AACzB,UAAO,MAAA,OAAa,QAAQ,EAAE,cAAc,KAAA,GAAW,CAAC;AACxD,SAAM,UAAU;;EAGlB,UAAgB;AACd,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;;EAOxB,IAAI,UAA6C;AAC/C,UAAO,MAAA;;EAGT,IAAI,QAAQ,OAA0C;AACpD,SAAA,UAAgB;AAChB,OAAI,MACF,QAAO,MAAA,OAAa,OAAO,EAAE,SAAS,OAAO,CAAC;;EAalD,IAAI,MAAc;AAChB,UAAO,MAAA,OAAa,MAAM,KAAK,CAAC,cAAc,OAAO;;EAGvD,IAAI,IAAI,OAAe;GACrB,MAAM,mBAAmB,MAAA,OAAa,OAAO,KAAK,CAAC;AAEnD,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;AACtB,SAAA,SAAe,qBAAqB,MAAA,OAAa;AAIjD,OAAI,MAAA,QACF,QAAO,MAAA,OAAa,OAAO,EAAE,SAAS,MAAA,SAAe,CAAC;AAGxD,OAAI,iBACF,QAAO,MAAA,OAAa,QAAQ,EAAE,cAAc,kBAAkB,CAAC;AAGjE,OAAI,MACF,QAAO,MAAA,OAAa,OAAO,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,CAAC;;EAShE,OAAsB;GACpB,MAAM,EAAE,iBAAiB,MAAA,OAAa,OAAO,KAAK;AAClD,OAAI,CAAC,aACH,QAAO,QAAQ,uBAAO,IAAI,MAAM,sCAAsC,CAAC;AAIzE,UAAO,MAAA,OAAa,OAAO,EAAE,mBAAmB,MAAM,CAAC;AAEvD,UAAO,aAAa,MAAM,CAAC,OAAO,QAAiB;AAIjD,QAAI,KAAK,IACP,QAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;AACrB,YAAA,oBAA0B;AAC1B,mBAAa,MAAM,CAAC,KAAK,SAAS,OAAO;;AAE3C,WAAA,oBAA0B;AAC1B,kBAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,MAAM,CAAC;MACpE;AAEJ,UAAM;KACN;;EAOJ,qBAA2B;AACzB,OAAI,CAAC,MAAA,kBAAyB;GAC9B,MAAM,EAAE,iBAAiB,MAAA,OAAa,OAAO,KAAK;AAClD,iBAAc,oBAAoB,aAAa,MAAA,kBAAwB;AACvE,SAAA,oBAA0B;;;AAI9B,QAAO;;;AAIT,IAAa,WAAb,cAA8B,cAAc,MAAM,GAAG,CAAC"}

package/dist/default/dom/playback-engine/engine.js

@@ -0,0 +1,142 @@
+import { signal } from "../../core/signals/primitives.js";
+import { loadSegments } from "../features/load-segments.js";
+import { destroyVttParser } from "../text/parse-vtt-segment.js";
+import { loadTextTrackCues } from "../features/load-text-track-cues.js";
+import { trackCurrentTime } from "../features/track-current-time.js";
+import { trackPlaybackInitiated } from "../features/track-playback-initiated.js";
+import { calculatePresentationDuration } from "../../core/features/calculate-presentation-duration.js";
+import { switchQuality } from "../../core/features/quality-switching.js";
+import { resolvePresentation } from "../../core/features/resolve-presentation.js";
+import { resolveTrack } from "../../core/features/resolve-track.js";
+import { selectAudioTrack, selectTextTrack, selectVideoTrack } from "../../core/features/select-tracks.js";
+import { syncPreloadAttribute } from "../../core/features/sync-preload-attribute.js";
+import { endOfStream } from "../features/end-of-stream.js";
+import { setupMediaSource } from "../features/setup-mediasource.js";
+import { setupSourceBuffers } from "../features/setup-sourcebuffer.js";
+import { syncTextTracks } from "../features/sync-text-tracks.js";
+import { updateDuration } from "../features/update-duration.js";
+//#region src/dom/playback-engine/engine.ts
+/**
+* Create a POC playback engine.
+*
+* Wires together all orchestrations to create a reactive playback pipeline:
+* 1. Resolve presentation (multivariant playlist)
+* 2. Select initial video and audio tracks
+* 3. Resolve selected tracks (media playlists)
+* 4. Setup MediaSource
+* 5. Setup SourceBuffers for video and audio
+*
+* Note: This is a POC - does not yet load/append segments.
+*
+* @param config - Playback engine configuration
+* @returns Playback engine instance with state, owners, and destroy function
+*
+* @example
+* const engine = createPlaybackEngine({
+*   initialBandwidth: 2_000_000,
+*   preferredAudioLanguage: 'en',
+* });
+*
+* // Initialize by setting state and owners
+* engine.owners.set({ ...engine.owners.get(), mediaElement: document.querySelector('video') });
+* engine.state.set({
+*   ...engine.state.get(),
+*   presentation: { url: 'https://example.com/playlist.m3u8' },
+*   preload: 'auto',
+* });
+*
+* // Inspect state
+* console.log(engine.state.get());
+*
+* // Cleanup
+* engine.destroy();
+*/
+function createPlaybackEngine(config = {}) {
+	const state = signal({ bandwidthState: {
+		fastEstimate: 0,
+		fastTotalWeight: 0,
+		slowEstimate: 0,
+		slowTotalWeight: 0,
+		bytesSampled: 0
+	} });
+	const owners = signal({});
+	const cleanups = [
+		syncPreloadAttribute({
+			state,
+			owners
+		}),
+		trackPlaybackInitiated({
+			state,
+			owners
+		}),
+		resolvePresentation({ state }),
+		selectVideoTrack({ state }, {
+			type: "video",
+			...config.initialBandwidth !== void 0 && { initialBandwidth: config.initialBandwidth }
+		}),
+		selectAudioTrack({ state }, {
+			type: "audio",
+			...config.preferredAudioLanguage !== void 0 && { preferredAudioLanguage: config.preferredAudioLanguage }
+		}),
+		selectTextTrack({ state }, {
+			type: "text",
+			...config.preferredSubtitleLanguage !== void 0 && { preferredSubtitleLanguage: config.preferredSubtitleLanguage },
+			...config.includeForcedTracks !== void 0 && { includeForcedTracks: config.includeForcedTracks },
+			...config.enableDefaultTrack !== void 0 && { enableDefaultTrack: config.enableDefaultTrack }
+		}),
+		resolveTrack({ state }, { type: "video" }),
+		resolveTrack({ state }, { type: "audio" }),
+		resolveTrack({ state }, { type: "text" }),
+		calculatePresentationDuration({ state }),
+		setupMediaSource({
+			state,
+			owners
+		}),
+		updateDuration({
+			state,
+			owners
+		}),
+		setupSourceBuffers({
+			state,
+			owners
+		}),
+		trackCurrentTime({
+			state,
+			owners
+		}),
+		switchQuality({ state }, config.initialBandwidth !== void 0 ? { defaultBandwidth: config.initialBandwidth } : {}),
+		loadSegments({
+			state,
+			owners
+		}, { type: "video" }),
+		loadSegments({
+			state,
+			owners
+		}, { type: "audio" }),
+		endOfStream({
+			state,
+			owners
+		}),
+		syncTextTracks({
+			state,
+			owners
+		}),
+		loadTextTrackCues({
+			state,
+			owners
+		})
+	];
+	return {
+		state,
+		owners,
+		destroy: () => {
+			cleanups.forEach((cleanup) => typeof cleanup === "function" ? cleanup() : cleanup.destroy());
+			for (const value of Object.values(owners.get())) if (value !== null && typeof value === "object" && typeof value.destroy === "function") value.destroy();
+			destroyVttParser();
+		}
+	};
+}
+//#endregion
+export { createPlaybackEngine };
+
+//# sourceMappingURL=engine.js.map

package/dist/default/dom/playback-engine/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":[],"sources":["../../../../src/dom/playback-engine/engine.ts"],"sourcesContent":["import type { BandwidthState } from '../../core/abr/bandwidth-estimator';\nimport { calculatePresentationDuration } from '../../core/features/calculate-presentation-duration';\nimport { switchQuality } from '../../core/features/quality-switching';\nimport { resolvePresentation } from '../../core/features/resolve-presentation';\nimport { resolveTrack } from '../../core/features/resolve-track';\nimport { selectAudioTrack, selectTextTrack, selectVideoTrack } from '../../core/features/select-tracks';\nimport { syncPreloadAttribute } from '../../core/features/sync-preload-attribute';\nimport type { ReadonlySignal, Signal } from '../../core/signals/primitives';\nimport { signal } from '../../core/signals/primitives';\nimport { endOfStream } from '../features/end-of-stream';\nimport { loadSegments } from '../features/load-segments';\nimport { loadTextTrackCues } from '../features/load-text-track-cues';\nimport { setupMediaSource } from '../features/setup-mediasource';\nimport { setupSourceBuffers } from '../features/setup-sourcebuffer';\nimport { syncTextTracks } from '../features/sync-text-tracks';\nimport type { TextTrackSegmentLoaderActor } from '../features/text-track-segment-loader-actor';\nimport type { TextTracksActor } from '../features/text-tracks-actor';\nimport { trackCurrentTime } from '../features/track-current-time';\nimport { trackPlaybackInitiated } from '../features/track-playback-initiated';\nimport { updateDuration } from '../features/update-duration';\nimport type { SourceBufferActor } from '../media/source-buffer-actor';\nimport { destroyVttParser } from '../text/parse-vtt-segment';\n\n/**\n * Configuration for the playback engine.\n */\nexport interface PlaybackEngineConfig {\n  /**\n   * Initial bandwidth estimate for cold start (bits per second).\n   * Default: 1 Mbps (conservative).\n   */\n  initialBandwidth?: number;\n\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching text track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   */\n  enableDefaultTrack?: boolean;\n}\n\n/**\n * Combined state shape for the playback engine.\n * Includes all state needed by orchestrations.\n */\nexport interface PlaybackEngineState {\n  // Presentation state\n  presentation?: any;\n  preload?: 'auto' | 'metadata' | 'none';\n\n  // Track selection state\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  // NOTE: Text Tracks (subtitles/ccs) can be unselected\n  selectedTextTrackId?: string;\n\n  // Bandwidth estimation state\n  bandwidthState?: BandwidthState;\n\n  // ABR control — set to true to suppress automatic quality switching (manual selection mode).\n  // TODO: replace with separate manualVideoTrackId / abrVideoTrackId fields so the two\n  // concerns don't share a field; see quality-switching.ts for the full design note.\n  abrDisabled?: boolean;\n\n  // Current playback position (mirrored from mediaElement via trackCurrentTime)\n  currentTime?: number;\n\n  // True once the user has initiated playback (enables segment loading regardless of preload)\n  playbackInitiated?: boolean;\n}\n\n/**\n * Combined owners shape for the playback engine.\n * Includes all mutable platform objects.\n */\nexport interface PlaybackEngineOwners {\n  // Media element\n  mediaElement?: HTMLMediaElement | undefined;\n\n  // MediaSource\n  mediaSource?: MediaSource;\n  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */\n  mediaSourceReadyState?: ReadonlySignal<MediaSource['readyState']>;\n\n  // SourceBuffers and their actors (created together by setupSourceBuffer)\n  videoBuffer?: SourceBuffer;\n  audioBuffer?: SourceBuffer;\n  videoBufferActor?: SourceBufferActor;\n  audioBufferActor?: SourceBufferActor;\n\n  // Text track actors (written by loadTextTrackCues; destroyed by engine on destroy)\n  textTracksActor?: TextTracksActor;\n  segmentLoaderActor?: TextTrackSegmentLoaderActor;\n}\n\n/**\n * Playback engine instance.\n */\nexport interface PlaybackEngine {\n  /**\n   * Reactive state signal (for inspection/testing).\n   */\n  state: Signal<PlaybackEngineState>;\n\n  /**\n   * Mutable owners signal (for inspection/testing).\n   */\n  owners: Signal<PlaybackEngineOwners>;\n\n  /**\n   * Cleanup function to destroy all orchestrations.\n   */\n  destroy: () => void;\n}\n\n/**\n * Create a POC playback engine.\n *\n * Wires together all orchestrations to create a reactive playback pipeline:\n * 1. Resolve presentation (multivariant playlist)\n * 2. Select initial video and audio tracks\n * 3. Resolve selected tracks (media playlists)\n * 4. Setup MediaSource\n * 5. Setup SourceBuffers for video and audio\n *\n * Note: This is a POC - does not yet load/append segments.\n *\n * @param config - Playback engine configuration\n * @returns Playback engine instance with state, owners, and destroy function\n *\n * @example\n * const engine = createPlaybackEngine({\n *   initialBandwidth: 2_000_000,\n *   preferredAudioLanguage: 'en',\n * });\n *\n * // Initialize by setting state and owners\n * engine.owners.set({ ...engine.owners.get(), mediaElement: document.querySelector('video') });\n * engine.state.set({\n *   ...engine.state.get(),\n *   presentation: { url: 'https://example.com/playlist.m3u8' },\n *   preload: 'auto',\n * });\n *\n * // Inspect state\n * console.log(engine.state.get());\n *\n * // Cleanup\n * engine.destroy();\n */\nexport function createPlaybackEngine(config: PlaybackEngineConfig = {}): PlaybackEngine {\n  // Create reactive state and owners as signals\n  const state = signal<PlaybackEngineState>({\n    bandwidthState: {\n      fastEstimate: 0,\n      fastTotalWeight: 0,\n      slowEstimate: 0,\n      slowTotalWeight: 0,\n      bytesSampled: 0,\n    },\n  });\n  const owners = signal<PlaybackEngineOwners>({});\n\n  // Wire up orchestrations\n  const cleanups = [\n    // 0a. Sync preload attribute from mediaElement → state.preload\n    //     Normalises '' (absent attribute) to 'auto' (browser default).\n    syncPreloadAttribute({ state, owners }),\n\n    // 0b. Track media element play event → state.playbackInitiated\n    //     Enables preload=\"none\" resolution via native controls / element.play()\n    trackPlaybackInitiated({ state, owners }),\n\n    // 1. Resolve presentation (URL already in state)\n    resolvePresentation({ state }),\n\n    // 2. Select initial tracks (when presentation loads)\n    selectVideoTrack(\n      { state },\n      {\n        type: 'video',\n        ...(config.initialBandwidth !== undefined && { initialBandwidth: config.initialBandwidth }),\n      }\n    ),\n    selectAudioTrack(\n      { state },\n      {\n        type: 'audio',\n        ...(config.preferredAudioLanguage !== undefined && { preferredAudioLanguage: config.preferredAudioLanguage }),\n      }\n    ),\n    selectTextTrack(\n      { state },\n      {\n        type: 'text',\n        ...(config.preferredSubtitleLanguage !== undefined && {\n          preferredSubtitleLanguage: config.preferredSubtitleLanguage,\n        }),\n        ...(config.includeForcedTracks !== undefined && { includeForcedTracks: config.includeForcedTracks }),\n        ...(config.enableDefaultTrack !== undefined && { enableDefaultTrack: config.enableDefaultTrack }),\n      }\n    ),\n\n    // 3. Resolve selected tracks (fetch media playlists)\n    resolveTrack({ state }, { type: 'video' as const }),\n    resolveTrack({ state }, { type: 'audio' as const }),\n    resolveTrack({ state }, { type: 'text' as const }),\n\n    // 3.5. Calculate presentation duration from resolved tracks\n    calculatePresentationDuration({ state }),\n\n    // 4. Setup MediaSource (when presentation loaded)\n    setupMediaSource({ state, owners }),\n\n    // 4.5. Update MediaSource duration (when presentation duration available)\n    updateDuration({ state, owners }),\n\n    // 5. Setup SourceBuffers (when MediaSource ready and all selected tracks resolved)\n    // Both SourceBuffers are created in a single synchronous operation to guarantee\n    // neither is visible to loadSegments before the other exists — preventing the\n    // Firefox bug where appending video data before audio SB is created causes\n    // mozHasAudio to be permanently false.\n    setupSourceBuffers({ state, owners }),\n\n    // 5.5. Track currentTime from mediaElement (feeds forward buffer management)\n    //\n    // NOTE: SourceBufferActor wiring is intentionally absent here in Phase 1.\n    //\n    // Attempting to wire actors into the engine at this layer revealed a\n    // brittleness in the current architecture: every patch to `owners` —\n    // regardless of which field changed — wakes up ALL combineLatest subscribers\n    // (loadSegments, endOfStream, etc.). Storing actor references in owners\n    // caused loadSegments to re-evaluate mid-task, store a spurious pending\n    // state, and run a second loading cycle on completion.\n    //\n    // This means any future feature that needs to introduce new reactive state\n    // alongside SourceBuffers faces the same hazard. The right fix is for\n    // loadSegments (and other orchestrations) to route their MSE operations\n    // through the actor directly, at which point the actor lifecycle is\n    // co-located with its consumer rather than managed centrally here.\n    //\n    // Actor wiring will be introduced in Phase 2 as part of the loadSegments\n    // refactor. See .claude/plans/spf/buffer-state-shadow-actual-model.md.\n    trackCurrentTime({ state, owners }),\n\n    // 5.75. ABR quality switching (reacts to bandwidth samples from loadSegments)\n    switchQuality(\n      { state },\n      config.initialBandwidth !== undefined ? { defaultBandwidth: config.initialBandwidth } : {}\n    ),\n\n    // 6. Load segments (when SourceBuffer ready and track resolved)\n    loadSegments({ state, owners }, { type: 'video' }),\n    loadSegments({ state, owners }, { type: 'audio' }),\n\n    // 6.5. Signal end of stream when all segments loaded\n    endOfStream({ state, owners }),\n\n    // 7-8.5. Text track sync: setup, mode sync, and DOM bridge.\n    //        Consolidates setupTextTracks, syncTextTrackModes, syncSelectedTextTrackFromDom.\n    syncTextTracks({ state, owners }),\n\n    // 9. Load text track cues (when track resolved and mode set)\n    loadTextTrackCues({ state, owners }),\n  ];\n\n  // Return engine instance\n  return {\n    state,\n    owners,\n    destroy: () => {\n      cleanups.forEach((cleanup) => (typeof cleanup === 'function' ? cleanup() : cleanup.destroy()));\n      // Destroy any actors that orchestrations wrote into owners during their lifetime.\n      for (const value of Object.values(owners.get())) {\n        if (\n          value !== null &&\n          typeof value === 'object' &&\n          typeof (value as { destroy?: unknown }).destroy === 'function'\n        ) {\n          (value as { destroy(): void }).destroy();\n        }\n      }\n      destroyVttParser();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuKA,SAAgB,qBAAqB,SAA+B,EAAE,EAAkB;CAEtF,MAAM,QAAQ,OAA4B,EACxC,gBAAgB;EACd,cAAc;EACd,iBAAiB;EACjB,cAAc;EACd,iBAAiB;EACjB,cAAc;EACf,EACF,CAAC;CACF,MAAM,SAAS,OAA6B,EAAE,CAAC;CAG/C,MAAM,WAAW;EAGf,qBAAqB;GAAE;GAAO;GAAQ,CAAC;EAIvC,uBAAuB;GAAE;GAAO;GAAQ,CAAC;EAGzC,oBAAoB,EAAE,OAAO,CAAC;EAG9B,iBACE,EAAE,OAAO,EACT;GACE,MAAM;GACN,GAAI,OAAO,qBAAqB,KAAA,KAAa,EAAE,kBAAkB,OAAO,kBAAkB;GAC3F,CACF;EACD,iBACE,EAAE,OAAO,EACT;GACE,MAAM;GACN,GAAI,OAAO,2BAA2B,KAAA,KAAa,EAAE,wBAAwB,OAAO,wBAAwB;GAC7G,CACF;EACD,gBACE,EAAE,OAAO,EACT;GACE,MAAM;GACN,GAAI,OAAO,8BAA8B,KAAA,KAAa,EACpD,2BAA2B,OAAO,2BACnC;GACD,GAAI,OAAO,wBAAwB,KAAA,KAAa,EAAE,qBAAqB,OAAO,qBAAqB;GACnG,GAAI,OAAO,uBAAuB,KAAA,KAAa,EAAE,oBAAoB,OAAO,oBAAoB;GACjG,CACF;EAGD,aAAa,EAAE,OAAO,EAAE,EAAE,MAAM,SAAkB,CAAC;EACnD,aAAa,EAAE,OAAO,EAAE,EAAE,MAAM,SAAkB,CAAC;EACnD,aAAa,EAAE,OAAO,EAAE,EAAE,MAAM,QAAiB,CAAC;EAGlD,8BAA8B,EAAE,OAAO,CAAC;EAGxC,iBAAiB;GAAE;GAAO;GAAQ,CAAC;EAGnC,eAAe;GAAE;GAAO;GAAQ,CAAC;EAOjC,mBAAmB;GAAE;GAAO;GAAQ,CAAC;EAqBrC,iBAAiB;GAAE;GAAO;GAAQ,CAAC;EAGnC,cACE,EAAE,OAAO,EACT,OAAO,qBAAqB,KAAA,IAAY,EAAE,kBAAkB,OAAO,kBAAkB,GAAG,EAAE,CAC3F;EAGD,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAS,CAAC;EAClD,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAS,CAAC;EAGlD,YAAY;GAAE;GAAO;GAAQ,CAAC;EAI9B,eAAe;GAAE;GAAO;GAAQ,CAAC;EAGjC,kBAAkB;GAAE;GAAO;GAAQ,CAAC;EACrC;AAGD,QAAO;EACL;EACA;EACA,eAAe;AACb,YAAS,SAAS,YAAa,OAAO,YAAY,aAAa,SAAS,GAAG,QAAQ,SAAS,CAAE;AAE9F,QAAK,MAAM,SAAS,OAAO,OAAO,OAAO,KAAK,CAAC,CAC7C,KACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAgC,YAAY,WAEnD,OAA8B,SAAS;AAG5C,qBAAkB;;EAErB"}

package/dist/default/dom/playback-engine.js

@@ -0,0 +1,4 @@
+import { effect } from "../core/signals/effect.js";
+import { createPlaybackEngine } from "./playback-engine/engine.js";
+import { SpfMedia, SpfMediaMixin } from "./playback-engine/adapter.js";
+export { SpfMedia, SpfMediaMixin, createPlaybackEngine, effect };

package/dist/default/dom/text/parse-vtt-segment.js

@@ -0,0 +1,56 @@
+//#region src/dom/text/parse-vtt-segment.ts
+/**
+* Parse a VTT segment using browser's native parser.
+*
+* Creates a dummy video element with a track element to leverage
+* the browser's optimized VTT parsing. Returns parsed VTTCue objects.
+*/
+let dummyVideo = null;
+function ensureDummyVideo() {
+	if (!dummyVideo) {
+		dummyVideo = document.createElement("video");
+		dummyVideo.muted = true;
+		dummyVideo.preload = "none";
+		dummyVideo.style.display = "none";
+		dummyVideo.crossOrigin = "anonymous";
+	}
+	return dummyVideo;
+}
+function parseVttSegment(url) {
+	const video = ensureDummyVideo();
+	const track = document.createElement("track");
+	track.kind = "subtitles";
+	track.default = true;
+	return new Promise((resolve, reject) => {
+		const onLoad = () => {
+			const cues = [];
+			const textTrack = track.track;
+			if (textTrack.cues) for (let i = 0; i < textTrack.cues.length; i++) {
+				const cue = textTrack.cues[i];
+				if (cue) cues.push(cue);
+			}
+			cleanup();
+			resolve(cues);
+		};
+		const onError = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`Failed to load VTT segment: ${url}`));
+		};
+		const cleanup = () => {
+			track.removeEventListener("load", onLoad);
+			track.removeEventListener("error", onError);
+			video.removeChild(track);
+		};
+		track.addEventListener("load", onLoad);
+		track.addEventListener("error", onError);
+		video.appendChild(track);
+		track.src = url;
+	});
+}
+function destroyVttParser() {
+	dummyVideo = null;
+}
+//#endregion
+export { destroyVttParser, parseVttSegment };
+
+//# sourceMappingURL=parse-vtt-segment.js.map

package/dist/default/dom/text/parse-vtt-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-vtt-segment.js","names":[],"sources":["../../../../src/dom/text/parse-vtt-segment.ts"],"sourcesContent":["/**\n * Parse a VTT segment using browser's native parser.\n *\n * Creates a dummy video element with a track element to leverage\n * the browser's optimized VTT parsing. Returns parsed VTTCue objects.\n */\n\n// Singleton dummy video (reused across all parsing)\nlet dummyVideo: HTMLVideoElement | null = null;\n\nfunction ensureDummyVideo(): HTMLVideoElement {\n  if (!dummyVideo) {\n    dummyVideo = document.createElement('video');\n    dummyVideo.muted = true;\n    dummyVideo.preload = 'none';\n    dummyVideo.style.display = 'none';\n    dummyVideo.crossOrigin = 'anonymous';\n  }\n  return dummyVideo;\n}\n\nexport function parseVttSegment(url: string): Promise<VTTCue[]> {\n  const video = ensureDummyVideo();\n  const track = document.createElement('track');\n  track.kind = 'subtitles';\n  track.default = true;\n\n  return new Promise((resolve, reject) => {\n    const onLoad = (): void => {\n      const cues: VTTCue[] = [];\n      const textTrack = track.track;\n\n      if (textTrack.cues) {\n        for (let i = 0; i < textTrack.cues.length; i++) {\n          const cue = textTrack.cues[i];\n          if (cue) {\n            cues.push(cue as VTTCue);\n          }\n        }\n      }\n\n      cleanup();\n      resolve(cues);\n    };\n\n    const onError = (): void => {\n      cleanup();\n      reject(new Error(`Failed to load VTT segment: ${url}`));\n    };\n\n    const cleanup = (): void => {\n      track.removeEventListener('load', onLoad);\n      track.removeEventListener('error', onError);\n      video.removeChild(track);\n    };\n\n    track.addEventListener('load', onLoad);\n    track.addEventListener('error', onError);\n    video.appendChild(track);\n    track.src = url;\n  });\n}\n\nexport function destroyVttParser(): void {\n  dummyVideo = null;\n}\n"],"mappings":";;;;;;;AAQA,IAAI,aAAsC;AAE1C,SAAS,mBAAqC;AAC5C,KAAI,CAAC,YAAY;AACf,eAAa,SAAS,cAAc,QAAQ;AAC5C,aAAW,QAAQ;AACnB,aAAW,UAAU;AACrB,aAAW,MAAM,UAAU;AAC3B,aAAW,cAAc;;AAE3B,QAAO;;AAGT,SAAgB,gBAAgB,KAAgC;CAC9D,MAAM,QAAQ,kBAAkB;CAChC,MAAM,QAAQ,SAAS,cAAc,QAAQ;AAC7C,OAAM,OAAO;AACb,OAAM,UAAU;AAEhB,QAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,eAAqB;GACzB,MAAM,OAAiB,EAAE;GACzB,MAAM,YAAY,MAAM;AAExB,OAAI,UAAU,KACZ,MAAK,IAAI,IAAI,GAAG,IAAI,UAAU,KAAK,QAAQ,KAAK;IAC9C,MAAM,MAAM,UAAU,KAAK;AAC3B,QAAI,IACF,MAAK,KAAK,IAAc;;AAK9B,YAAS;AACT,WAAQ,KAAK;;EAGf,MAAM,gBAAsB;AAC1B,YAAS;AACT,0BAAO,IAAI,MAAM,+BAA+B,MAAM,CAAC;;EAGzD,MAAM,gBAAsB;AAC1B,SAAM,oBAAoB,QAAQ,OAAO;AACzC,SAAM,oBAAoB,SAAS,QAAQ;AAC3C,SAAM,YAAY,MAAM;;AAG1B,QAAM,iBAAiB,QAAQ,OAAO;AACtC,QAAM,iBAAiB,SAAS,QAAQ;AACxC,QAAM,YAAY,MAAM;AACxB,QAAM,MAAM;GACZ;;AAGJ,SAAgB,mBAAyB;AACvC,cAAa"}

package/dist/default/dom.js

@@ -0,0 +1,10 @@
+import { loadSegments } from "./dom/features/load-segments.js";
+import { destroyVttParser, parseVttSegment } from "./dom/text/parse-vtt-segment.js";
+import { loadTextTrackCues } from "./dom/features/load-text-track-cues.js";
+import { trackCurrentTime } from "./dom/features/track-current-time.js";
+import { trackPlaybackInitiated } from "./dom/features/track-playback-initiated.js";
+import { trackPlaybackRate } from "./dom/features/track-playback-rate.js";
+import { appendSegment } from "./dom/media/append-segment.js";
+import { flushBuffer } from "./dom/media/buffer-flusher.js";
+import { SpfMedia, SpfMediaMixin } from "./dom/playback-engine/adapter.js";
+export { SpfMedia, SpfMediaMixin, appendSegment, destroyVttParser, flushBuffer, loadSegments, loadTextTrackCues, parseVttSegment, trackCurrentTime, trackPlaybackInitiated, trackPlaybackRate };

package/dist/{src-DRsS_H80.js → default/index.js}

@@ -8,7 +8,7 @@
 * @packageDocumentation
 */
 const VERSION = "0.1.0";
-
 //#endregion
-export { VERSION as t };
-//# sourceMappingURL=src-DRsS_H80.js.map
+export { VERSION };
+
+//# sourceMappingURL=index.js.map

package/dist/default/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Stream Processing Framework (SPF) for Video.js 10\n *\n * Bundle size target: < 20KB (minified + gzipped)\n * Primary use case: CMAF HLS playback with Video.js v10\n *\n * @packageDocumentation\n */\n\n// Public API exports will be added here as features are implemented\n\nexport const VERSION = '0.1.0';\n"],"mappings":";;;;;;;;;AAWA,MAAa,UAAU"}

package/dist/dev/core/abr/bandwidth-estimator.d.ts

@@ -0,0 +1,35 @@
+//#region src/core/abr/bandwidth-estimator.d.ts
+/**
+ * Dual EWMA Bandwidth Estimator
+ *
+ * Estimates available bandwidth using two EWMA calculations with different
+ * half-lives, taking the minimum of both. This approach (from Shaka Player):
+ *
+ * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops
+ * - **Slow EWMA** (5s half-life): Provides stability during fluctuations
+ * - **min(fast, slow)**: Adapts down quickly, up slowly
+ *
+ * This naturally provides asymmetric behavior needed for good QoE:
+ * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).
+ */
+/**
+ * Bandwidth estimator state.
+ *
+ * This state structure will be managed by O1 (State Container).
+ * Functions in this module operate on this state immutably.
+ */
+interface BandwidthState {
+  /** Fast-moving EWMA estimate (raw, uncorrected). */
+  fastEstimate: number;
+  /** Total weight accumulated in fast EWMA. */
+  fastTotalWeight: number;
+  /** Slow-moving EWMA estimate (raw, uncorrected). */
+  slowEstimate: number;
+  /** Total weight accumulated in slow EWMA. */
+  slowTotalWeight: number;
+  /** Total bytes sampled across all valid samples. */
+  bytesSampled: number;
+}
+//#endregion
+export { BandwidthState };
+//# sourceMappingURL=bandwidth-estimator.d.ts.map

package/dist/dev/core/abr/bandwidth-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.d.ts","names":[],"sources":["../../../../src/core/abr/bandwidth-estimator.ts"],"mappings":";;AAsBA;;;;;;;;;;;;;;;;;;UAAiB,cAAA;;EAEf,YAAA;;EAEA,eAAA;;EAEA,YAAA;;EAEA,eAAA;;EAEA,YAAA;AAAA"}

package/dist/dev/core/abr/bandwidth-estimator.js

@@ -0,0 +1,95 @@
+import { applyZeroFactor, calculateEwma } from "./ewma.js";
+//#region src/core/abr/bandwidth-estimator.ts
+/**
+* Dual EWMA Bandwidth Estimator
+*
+* Estimates available bandwidth using two EWMA calculations with different
+* half-lives, taking the minimum of both. This approach (from Shaka Player):
+*
+* - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops
+* - **Slow EWMA** (5s half-life): Provides stability during fluctuations
+* - **min(fast, slow)**: Adapts down quickly, up slowly
+*
+* This naturally provides asymmetric behavior needed for good QoE:
+* avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).
+*/
+/**
+* Default bandwidth estimator configuration.
+*
+* Values match Shaka Player defaults based on experimentation.
+*/
+const DEFAULT_BANDWIDTH_CONFIG = {
+	fastHalfLife: 2,
+	slowHalfLife: 5,
+	minTotalBytes: 128e3,
+	minBytes: 16e3,
+	minDuration: 5
+};
+/**
+* Add a bandwidth sample from a segment download.
+*
+* Samples are filtered based on:
+* - Minimum bytes (filters TTFB-dominated small segments)
+* - Minimum duration (filters cached responses)
+*
+* Valid samples update both fast and slow EWMA estimates.
+*
+* @param state - Current estimator state
+* @param durationMs - Download duration in milliseconds
+* @param numBytes - Number of bytes downloaded
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns New estimator state with sample incorporated (or unchanged if filtered)
+*
+* @example
+* let state = { fastEstimate: 0, fastTotalWeight: 0, ... };
+* // Sample: 1MB in 1 second
+* state = sampleBandwidth(state, 1000, 1_000_000);
+*/
+function sampleBandwidth(state, durationMs, numBytes, config = DEFAULT_BANDWIDTH_CONFIG) {
+	const updatedBytesSampled = state.bytesSampled + numBytes;
+	if (numBytes < config.minBytes) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	if (durationMs < config.minDuration) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	const bandwidth = 8e3 * numBytes / durationMs;
+	const weight = durationMs / 1e3;
+	return {
+		fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),
+		fastTotalWeight: state.fastTotalWeight + weight,
+		slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),
+		slowTotalWeight: state.slowTotalWeight + weight,
+		bytesSampled: updatedBytesSampled
+	};
+}
+/**
+* Get the current bandwidth estimate.
+*
+* Returns the **minimum** of the fast and slow EWMA estimates.
+* This provides the key asymmetric behavior:
+* - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)
+* - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)
+*
+* Uses default estimate until enough data has been sampled.
+*
+* @param state - Current estimator state
+* @param defaultEstimate - Fallback estimate before sufficient samples (bps)
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns Bandwidth estimate in bits per second
+*
+* @example
+* const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default
+*/
+function getBandwidthEstimate(state, defaultEstimate, config = DEFAULT_BANDWIDTH_CONFIG) {
+	if (state.bytesSampled < config.minTotalBytes) return defaultEstimate;
+	const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);
+	const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);
+	return Math.min(fastEstimate, slowEstimate);
+}
+//#endregion
+export { getBandwidthEstimate, sampleBandwidth };
+
+//# sourceMappingURL=bandwidth-estimator.js.map

package/dist/dev/core/abr/bandwidth-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../../src/core/abr/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled.\n *\n * @param state - Current estimator state\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,MAAM,eAAe,OAAO,cAC9B,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}