@videojs/spf 10.0.0-beta.3 → 10.0.0-beta.31

package/dist/default/playback/actors/dom/segment-loader.js

@@ -0,0 +1,249 @@
+import { peek } from "../../../core/signals/primitives.js";
+import { SerialRunner, Task } from "../../../core/tasks/task.js";
+import { createMachineActor } from "../../../core/actors/create-machine-actor.js";
+import "../../../media/types/index.js";
+import { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad, isTimeRangeCovered, mergeTimeRanges } from "../../../media/buffer/forward-buffer.js";
+import { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint } from "../../../media/buffer/back-buffer.js";
+import { DEFAULT_MESSAGE_PIPELINES } from "../../primitives/segment-load-pipeline.js";
+//#region src/playback/actors/dom/segment-loader.ts
+/**
+* Wraps a LoadTask descriptor into a Task that runs the op's message pipeline
+* (fetch/discover/stamp/dispatch, per the composition's `messagePipelines`).
+* Updates in-flight context around the async region so the loading handler can
+* make accurate continue/preempt decisions at any point, and checks the abort
+* signal before each step.
+*/
+function makeLoadTask(op, { getContext, setContext, pipelines, deps }) {
+	return new Task(async (taskSignal) => {
+		if (taskSignal.aborted) return;
+		const frame = op.type === "append-segment" ? {
+			op,
+			meta: op.meta
+		} : { op };
+		try {
+			if (op.type === "append-init") setContext({
+				...getContext(),
+				inFlightInitTrackId: op.meta.trackId
+			});
+			else if (op.type === "append-segment") setContext({
+				...getContext(),
+				inFlightSegment: {
+					id: op.meta.id,
+					trackId: op.meta.trackId
+				}
+			});
+			for (const step of pipelines[op.type]) {
+				if (taskSignal.aborted) return;
+				await step(frame, taskSignal, deps);
+			}
+		} finally {
+			if (op.type === "append-init") setContext({
+				...getContext(),
+				inFlightInitTrackId: null
+			});
+			else if (op.type === "append-segment") setContext({
+				...getContext(),
+				inFlightSegment: null
+			});
+		}
+	});
+}
+/**
+* Creates a SegmentLoaderActor for one track type (video or audio).
+*
+* Receives load assignments via `send()` and owns all execution: planning,
+* removes, fetches, and appends. Coordinates with the SourceBufferActor for
+* all physical SourceBuffer operations.
+*
+* Planning (Cases 1–3) happens in the `load` handler on every incoming
+* message, producing an ordered LoadTask list. The runner drains that list
+* sequentially via SerialRunner. When a new message arrives mid-run, the
+* handler replans and either continues the in-flight operation (abortPending
+* + schedule new remainder) or preempts it (abortAll + cancel SourceBuffer
+* if needed + schedule new plan).
+*
+* @param sourceBufferActor - Shared SourceBufferActor reference (not owned)
+* @param fetchBytes - Tracked fetch closure (owns throughput sampling for segments).
+*   Accepts an optional `minChunkSize` in options; init segments pass `Infinity`
+*   so the entire body accumulates as one chunk before appending.
+* @param compositionDeps - The composition's `state`/`context`/`config`, threaded
+*   opaquely into each step's {@link StepDeps} (the loader never reads them). Lets
+*   injected steps (relocation) read composition signals at call time. Defaults to
+*   empty for standalone / base-pipeline use.
+*/
+function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}, compositionDeps = {
+	state: {},
+	context: {},
+	config: {}
+}) {
+	const forwardBufferConfig = {
+		...DEFAULT_FORWARD_BUFFER_CONFIG,
+		...config.forwardBuffer
+	};
+	const backBufferConfig = {
+		...DEFAULT_BACK_BUFFER_CONFIG,
+		...config.backBuffer
+	};
+	const deps = {
+		state: compositionDeps.state,
+		context: compositionDeps.context,
+		config: {
+			...compositionDeps.config,
+			sourceBufferActor,
+			fetch: fetchBytes
+		}
+	};
+	const pipelines = (config.messagePipelines ?? DEFAULT_MESSAGE_PIPELINES)();
+	const getBufferedSegments = (allSegments) => {
+		const merged = mergeTimeRanges(peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial).map((s) => ({
+			start: s.startTime,
+			end: s.startTime + s.duration
+		})));
+		return allSegments.filter((s) => isTimeRangeCovered(s.startTime, s.startTime + s.duration, merged));
+	};
+	/**
+	* Translate a load message into an ordered LoadTask list based on committed
+	* actor state. In-flight awareness is handled separately in the load handler.
+	*
+	* @todo Rename alongside LoadTask (e.g. planOps).
+	*
+	* Case 1 — Removes: forward and back buffer flush points, segment-aligned.
+	*   ABR-style track switches (same content, different bitrate) do not flush:
+	*   appending new content overwrites existing buffer ranges, and the actor's
+	*   time-aligned deduplication keeps the segment model accurate as new
+	*   segments arrive.
+	*
+	*   Cross-rendition track switches (audio language change, text language
+	*   change) do flush: the buffered content is semantically incompatible with
+	*   the newly-selected track, so overwrite-on-append would leave stale
+	*   content playing until each replacement segment lands. Today's predicate:
+	*   `actorCtx.initTrackLanguage !== track.language` — fires for language
+	*   changes, no-ops for video / same-language audio bitrate switches.
+	*   Future stage: pluggable predicate / strategy at actor construction time
+	*   for codec-change (5.1 surround) and other cross-rendition shapes.
+	*
+	* Case 2 — Init: schedule if not yet committed for this track.
+	*
+	* Case 3 — Segments: all segments in the load window not yet committed.
+	*/
+	const planTasks = (message) => {
+		const { track, range } = message;
+		const actorCtx = peek(sourceBufferActor.snapshot).context;
+		const bufferedSegments = getBufferedSegments(track.segments);
+		const currentTime = range?.start ?? 0;
+		const tasks = [];
+		const isCrossRenditionSwitch = actorCtx.initTrackId !== void 0 && actorCtx.initTrackId !== track.id && actorCtx.initTrackLanguage !== track.language;
+		const removes = [];
+		const staleRanges = [];
+		if (range) {
+			if (isCrossRenditionSwitch) {
+				const staleStart = actorCtx.segments.find((s) => s.startTime <= currentTime && s.startTime + s.duration > currentTime)?.startTime ?? actorCtx.segments.find((s) => s.startTime > currentTime)?.startTime;
+				if (staleStart !== void 0) staleRanges.push({
+					start: staleStart,
+					end: Infinity
+				});
+			}
+			const forwardFlushStart = calculateForwardFlushPoint(bufferedSegments, currentTime, forwardBufferConfig);
+			if (forwardFlushStart < Infinity) removes.push({
+				start: forwardFlushStart,
+				end: Infinity
+			});
+			const backFlushEnd = calculateBackBufferFlushPoint(bufferedSegments, currentTime, backBufferConfig);
+			if (backFlushEnd > 0) removes.push({
+				start: 0,
+				end: backFlushEnd
+			});
+			for (const r of removes) tasks.push({
+				type: "remove",
+				start: r.start,
+				end: r.end
+			});
+		}
+		const overlapsStale = (seg) => {
+			const segEnd = seg.startTime + seg.duration;
+			return removes.some((r) => seg.startTime < r.end && segEnd > r.start) || staleRanges.some((r) => seg.startTime < r.end && segEnd > r.start);
+		};
+		const effectiveBuffered = removes.length + staleRanges.length > 0 ? bufferedSegments.filter((s) => !overlapsStale(s)) : bufferedSegments;
+		if (actorCtx.initTrackId !== track.id) tasks.push({
+			type: "append-init",
+			meta: {
+				trackId: track.id,
+				language: track.language
+			},
+			url: track.initialization.url,
+			...track.initialization.byteRange !== void 0 && { byteRange: track.initialization.byteRange }
+		});
+		if (range) {
+			const segmentsToLoad = getSegmentsToLoad(track.segments, effectiveBuffered, currentTime, forwardBufferConfig).filter((seg) => {
+				const existing = actorCtx.segments.find((s) => !overlapsStale(s) && Math.abs(s.startTime - seg.startTime) < 1e-4);
+				if (existing?.partial) return true;
+				if (!existing?.trackBandwidth || !track.bandwidth) return true;
+				return track.bandwidth > existing.trackBandwidth;
+			});
+			for (const segment of segmentsToLoad) tasks.push({
+				type: "append-segment",
+				meta: {
+					id: segment.id,
+					startTime: segment.startTime,
+					duration: segment.duration,
+					trackId: track.id,
+					trackBandwidth: track.bandwidth
+				},
+				url: segment.url,
+				...segment.byteRange !== void 0 && { byteRange: segment.byteRange }
+			});
+		}
+		return tasks;
+	};
+	const scheduleAll = (tasks, { getContext, setContext, runner }) => {
+		tasks.forEach((op) => {
+			runner.schedule(makeLoadTask(op, {
+				getContext,
+				setContext,
+				pipelines,
+				deps
+			})).then(void 0, (e) => {
+				if (e instanceof Error && e.name === "AbortError") return;
+				console.error("Unexpected error in segment loader:", e);
+				runner.abortPending();
+			});
+		});
+	};
+	return createMachineActor({
+		runner: () => new SerialRunner(),
+		initial: "idle",
+		context: {
+			inFlightInitTrackId: null,
+			inFlightSegment: null
+		},
+		states: {
+			idle: { on: { load: (msg, ctx) => {
+				const allTasks = planTasks(msg);
+				if (allTasks.length === 0) return;
+				ctx.transition("loading");
+				scheduleAll(allTasks, ctx);
+			} } },
+			loading: {
+				onSettled: "idle",
+				on: { load: (msg, ctx) => {
+					const { context, runner } = ctx;
+					const allTasks = planTasks(msg);
+					const inFlight = context.inFlightSegment;
+					const segmentInFlightStillNeeded = (t) => t.type === "append-segment" && inFlight !== null && t.meta.id === inFlight.id && t.meta.trackId === inFlight.trackId;
+					if (inFlight !== null && allTasks.some(segmentInFlightStillNeeded) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
+						runner.abortPending();
+						scheduleAll(allTasks.filter((t) => !segmentInFlightStillNeeded(t) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
+					} else {
+						runner.abortAll();
+						if (context.inFlightSegment !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
+						scheduleAll(allTasks, ctx);
+					}
+				} }
+			}
+		}
+	});
+}
+//#endregion
+export { createSegmentLoaderActor };
+
+//# sourceMappingURL=segment-loader.js.map

package/dist/default/playback/actors/dom/segment-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-loader.js","names":[],"sources":["../../../../../src/playback/actors/dom/segment-loader.ts"],"sourcesContent":["import { createMachineActor, type HandlerContext, type MessageActor } from '../../../core/actors/create-machine-actor';\nimport { peek } from '../../../core/signals/primitives';\nimport { SerialRunner, Task } from '../../../core/tasks/task';\nimport {\n  type BackBufferConfig,\n  calculateBackBufferFlushPoint,\n  DEFAULT_BACK_BUFFER_CONFIG,\n} from '../../../media/buffer/back-buffer';\nimport {\n  calculateForwardFlushPoint,\n  DEFAULT_FORWARD_BUFFER_CONFIG,\n  type ForwardBufferConfig,\n  getSegmentsToLoad,\n  isTimeRangeCovered,\n  mergeTimeRanges,\n} from '../../../media/buffer/forward-buffer';\nimport { type AudioTrack, SEGMENT_TIME_EPSILON, type Segment, type VideoTrack } from '../../../media/types';\nimport {\n  DEFAULT_MESSAGE_PIPELINES,\n  type FetchBytes,\n  type Frame,\n  type LoadStep,\n  type LoadTask,\n  type MessagePipelines,\n  type StepDeps,\n} from '../../primitives/segment-load-pipeline';\nimport type { SourceBufferActor } from './source-buffer';\n\n// ============================================================================\n// BUFFER STATE TYPES\n// ============================================================================\n\n/**\n * Buffer state for a single SourceBuffer.\n * Tracks which init segment and media segments are loaded.\n */\nexport interface SourceBufferState {\n  /** Track ID of the loaded init segment */\n  initTrackId?: string;\n  /** Loaded media segments (unordered - selectors derive ordering) */\n  segments: Array<{ id: string; trackId: string }>;\n}\n\n/**\n * Buffer state for all SourceBuffers.\n */\nexport interface BufferState {\n  video?: SourceBufferState;\n  audio?: SourceBufferState;\n}\n\n// ============================================================================\n// MESSAGE PROTOCOL\n// ============================================================================\n\n/** Track types that have SourceBuffers (video and audio only). */\nexport type SegmentLoaderTrack = VideoTrack | AudioTrack;\n\n/**\n * Message sent to a SegmentLoaderActor.\n *\n * `range` is optional to distinguish loading modes:\n * - No range: load init segment only (metadata preload mode)\n * - With range: load init + all segments overlapping [start, end]\n *\n * `start` and `end` are raw time values — no segment snapping.\n * The actor maps them onto segment boundaries internally.\n */\nexport type SegmentLoaderMessage = {\n  type: 'load';\n  track: SegmentLoaderTrack;\n  range?: { start: number; end: number };\n};\n\n// ============================================================================\n// ACTOR INTERFACE\n// ============================================================================\n\n/** Finite states of the actor. */\nexport type SegmentLoaderActorState = 'idle' | 'loading' | 'destroyed';\n\n/** Non-finite (extended) data managed by the actor. */\nexport interface SegmentLoaderActorContext {\n  /** Track ID of the init segment currently being fetched/appended, or null. */\n  inFlightInitTrackId: string | null;\n  /**\n   * Identity of the segment currently being fetched/appended, or null. Tracks\n   * the `trackId` alongside the positional `id` because renditions number\n   * segments independently (`segment-N`): an in-flight LOW `segment-0` must not\n   * be mistaken for a needed HIGH `segment-0` on a switch (see the loading\n   * handler's continue/preempt decision). Mirrors the text-track loader, which\n   * already matches its in-flight segment on `(inFlightTrackId, inFlightSegmentId)`.\n   */\n  inFlightSegment: { id: string; trackId: string } | null;\n}\n\nexport type SegmentLoaderActor = MessageActor<SegmentLoaderActorState, SegmentLoaderActorContext, SegmentLoaderMessage>;\n\n/**\n * Configuration for `createSegmentLoaderActor`. Each sub-config is\n * spread over the corresponding `DEFAULT_*_CONFIG` so callers can\n * override individual fields.\n */\nexport interface SegmentLoaderActorConfig {\n  forwardBuffer?: Partial<ForwardBufferConfig>;\n  backBuffer?: Partial<BackBufferConfig>;\n  /** Per-message-type step pipelines. Defaults to {@link DEFAULT_MESSAGE_PIPELINES} (`fetch → dispatch`). */\n  messagePipelines?: MessagePipelines;\n}\n\n// ============================================================================\n// LOAD TASK FACTORY\n// ============================================================================\n\ninterface LoadTaskOptions {\n  getContext: () => SegmentLoaderActorContext;\n  setContext: (ctx: SegmentLoaderActorContext) => void;\n  pipelines: Record<LoadTask['type'], LoadStep[]>;\n  deps: StepDeps;\n}\n\n/**\n * Wraps a LoadTask descriptor into a Task that runs the op's message pipeline\n * (fetch/discover/stamp/dispatch, per the composition's `messagePipelines`).\n * Updates in-flight context around the async region so the loading handler can\n * make accurate continue/preempt decisions at any point, and checks the abort\n * signal before each step.\n */\nfunction makeLoadTask(op: LoadTask, { getContext, setContext, pipelines, deps }: LoadTaskOptions): Task<void> {\n  return new Task(async (taskSignal) => {\n    if (taskSignal.aborted) return;\n\n    const frame: Frame = op.type === 'append-segment' ? { op, meta: op.meta } : { op };\n\n    // In-flight bookkeeping brackets the async region; the `finally` resets it\n    // even if a step aborts or throws mid-pipeline. Only append ops track it.\n    try {\n      if (op.type === 'append-init') setContext({ ...getContext(), inFlightInitTrackId: op.meta.trackId });\n      else if (op.type === 'append-segment')\n        setContext({ ...getContext(), inFlightSegment: { id: op.meta.id, trackId: op.meta.trackId } });\n\n      for (const step of pipelines[op.type]) {\n        if (taskSignal.aborted) return;\n        await step(frame, taskSignal, deps);\n      }\n    } finally {\n      if (op.type === 'append-init') setContext({ ...getContext(), inFlightInitTrackId: null });\n      else if (op.type === 'append-segment') setContext({ ...getContext(), inFlightSegment: null });\n    }\n  });\n}\n\n// ============================================================================\n// IMPLEMENTATION\n// ============================================================================\n\n/**\n * Creates a SegmentLoaderActor for one track type (video or audio).\n *\n * Receives load assignments via `send()` and owns all execution: planning,\n * removes, fetches, and appends. Coordinates with the SourceBufferActor for\n * all physical SourceBuffer operations.\n *\n * Planning (Cases 1–3) happens in the `load` handler on every incoming\n * message, producing an ordered LoadTask list. The runner drains that list\n * sequentially via SerialRunner. When a new message arrives mid-run, the\n * handler replans and either continues the in-flight operation (abortPending\n * + schedule new remainder) or preempts it (abortAll + cancel SourceBuffer\n * if needed + schedule new plan).\n *\n * @param sourceBufferActor - Shared SourceBufferActor reference (not owned)\n * @param fetchBytes - Tracked fetch closure (owns throughput sampling for segments).\n *   Accepts an optional `minChunkSize` in options; init segments pass `Infinity`\n *   so the entire body accumulates as one chunk before appending.\n * @param compositionDeps - The composition's `state`/`context`/`config`, threaded\n *   opaquely into each step's {@link StepDeps} (the loader never reads them). Lets\n *   injected steps (relocation) read composition signals at call time. Defaults to\n *   empty for standalone / base-pipeline use.\n */\nexport function createSegmentLoaderActor(\n  sourceBufferActor: SourceBufferActor,\n  fetchBytes: FetchBytes,\n  config: SegmentLoaderActorConfig = {},\n  compositionDeps: StepDeps = { state: {}, context: {}, config: {} }\n): SegmentLoaderActor {\n  type UserState = Exclude<SegmentLoaderActorState, 'destroyed'>;\n  type Ctx = HandlerContext<UserState, SegmentLoaderActorContext, () => SerialRunner>;\n\n  const forwardBufferConfig: ForwardBufferConfig = { ...DEFAULT_FORWARD_BUFFER_CONFIG, ...config.forwardBuffer };\n  const backBufferConfig: BackBufferConfig = { ...DEFAULT_BACK_BUFFER_CONFIG, ...config.backBuffer };\n  // Fold the loader's own wiring into the passthrough `config` (see `stepWiring`) so\n  // base steps read it from the uniform `{state,context,config}` — present in both\n  // composition and standalone use.\n  const deps: StepDeps = {\n    state: compositionDeps.state,\n    context: compositionDeps.context,\n    config: { ...compositionDeps.config, sourceBufferActor, fetch: fetchBytes },\n  };\n  // Built once per actor (fresh stateful steps per source); default is `fetch → dispatch`.\n  const pipelines = (config.messagePipelines ?? DEFAULT_MESSAGE_PIPELINES)();\n\n  const getBufferedSegments = (allSegments: readonly Segment[]): Segment[] => {\n    // A candidate segment counts as \"already buffered\" only when its whole time\n    // span is covered by appended content — a TIME question, not a positional-id\n    // one. Renditions are numbered independently per playlist (`segment-N`), so\n    // matching by id assumes every rung shares the same segment grid. That fails\n    // for renditions whose boundaries don't align (e.g. a 30fps rung cuts its\n    // first GOP at 7.13s, a 60fps rung at 7.98s): the switched-to rung's segment\n    // reuses a buffered id but spans a *later*-ending range, so an id match would\n    // skip it and leave its uncovered tail as a gap. Covering by time refetches\n    // exactly that straddling segment (MSE overwrites the overlap on append).\n    //\n    // Exclude partial segments — they are still streaming and must not count as\n    // fully buffered for load planning or buffer window calculations.\n    //\n    // `peek` defensively: `load` handlers run synchronously inside `send()`,\n    // which is called from inside the dispatcher reactor's `effects:` body.\n    // A tracked `.snapshot.get()` here would leak the source-buffer-actor's\n    // snapshot into the dispatcher's dep set, causing the dispatcher to re-\n    // fire on every SourceBufferActor state change. Mirrors the fix applied\n    // to the text-track loader in `b3f44efe`.\n    const appended = peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial);\n    const merged = mergeTimeRanges(appended.map((s) => ({ start: s.startTime, end: s.startTime + s.duration })));\n    return allSegments.filter((s) => isTimeRangeCovered(s.startTime, s.startTime + s.duration, merged));\n  };\n\n  /**\n   * Translate a load message into an ordered LoadTask list based on committed\n   * actor state. In-flight awareness is handled separately in the load handler.\n   *\n   * @todo Rename alongside LoadTask (e.g. planOps).\n   *\n   * Case 1 — Removes: forward and back buffer flush points, segment-aligned.\n   *   ABR-style track switches (same content, different bitrate) do not flush:\n   *   appending new content overwrites existing buffer ranges, and the actor's\n   *   time-aligned deduplication keeps the segment model accurate as new\n   *   segments arrive.\n   *\n   *   Cross-rendition track switches (audio language change, text language\n   *   change) do flush: the buffered content is semantically incompatible with\n   *   the newly-selected track, so overwrite-on-append would leave stale\n   *   content playing until each replacement segment lands. Today's predicate:\n   *   `actorCtx.initTrackLanguage !== track.language` — fires for language\n   *   changes, no-ops for video / same-language audio bitrate switches.\n   *   Future stage: pluggable predicate / strategy at actor construction time\n   *   for codec-change (5.1 surround) and other cross-rendition shapes.\n   *\n   * Case 2 — Init: schedule if not yet committed for this track.\n   *\n   * Case 3 — Segments: all segments in the load window not yet committed.\n   */\n  const planTasks = (message: SegmentLoaderMessage): LoadTask[] => {\n    const { track, range } = message;\n    // `peek` for the same reason as `getBufferedSegments` above — avoid\n    // leaking the SourceBufferActor snapshot into the calling dispatcher's\n    // tracking scope.\n    const actorCtx = peek(sourceBufferActor.snapshot).context;\n    const bufferedSegments = getBufferedSegments(track.segments);\n    const currentTime = range?.start ?? 0;\n    const tasks: LoadTask[] = [];\n\n    // Cross-rendition switch check (mid-stream language change). Fires when\n    // (a) an init segment has already been committed for some track,\n    // (b) the newly-selected track is a different track, and\n    // (c) the languages differ. The buffered range from the current segment\n    // boundary forward is treated as stale (new track's same-timestamp\n    // segments will overwrite it via MSE append-at-same-timestamp); no\n    // explicit `remove` task is emitted for the cross-rendition range.\n    // Computed against the currently-buffered segments (stable reference;\n    // new track's playlist may not be resolved yet at first load).\n    const isCrossRenditionSwitch =\n      actorCtx.initTrackId !== undefined &&\n      actorCtx.initTrackId !== track.id &&\n      actorCtx.initTrackLanguage !== track.language;\n\n    // Two categories of \"buffered content that should not gate planning\":\n    //\n    // - `removes` — content that needs an explicit `remove` task (out-of-window\n    //   forward content, back-buffer content beyond the keep window). Emitted\n    //   as `{ type: 'remove' }` tasks.\n    // - `staleRanges` — content that the new appends will overwrite at the\n    //   same timestamps (cross-rendition switch). No explicit `remove` —\n    //   MSE's overwrite-on-append handles it, which gives a much smaller\n    //   perceived audio gap than `remove`-then-fetch-then-append.\n    //\n    // Both categories affect `effectiveBuffered` so `getSegmentsToLoad`\n    // re-plans new-track segments inside them.\n    const removes: Array<{ start: number; end: number }> = [];\n    const staleRanges: Array<{ start: number; end: number }> = [];\n    if (range) {\n      if (isCrossRenditionSwitch) {\n        // Mark current-segment-start onward as stale. Falls back to the\n        // first buffered segment after currentTime when the playhead sits\n        // in a buffer gap.\n        const currentSeg = actorCtx.segments.find(\n          (s) => s.startTime <= currentTime && s.startTime + s.duration > currentTime\n        );\n        const staleStart = currentSeg?.startTime ?? actorCtx.segments.find((s) => s.startTime > currentTime)?.startTime;\n        if (staleStart !== undefined) {\n          staleRanges.push({ start: staleStart, end: Infinity });\n        }\n      }\n      const forwardFlushStart = calculateForwardFlushPoint(bufferedSegments, currentTime, forwardBufferConfig);\n      if (forwardFlushStart < Infinity) {\n        removes.push({ start: forwardFlushStart, end: Infinity });\n      }\n      const backFlushEnd = calculateBackBufferFlushPoint(bufferedSegments, currentTime, backBufferConfig);\n      if (backFlushEnd > 0) {\n        removes.push({ start: 0, end: backFlushEnd });\n      }\n      for (const r of removes) tasks.push({ type: 'remove', start: r.start, end: r.end });\n    }\n\n    // Treat any segment overlapping a planned remove OR a stale range as\n    // not-buffered. Without this, sibling renditions that share segment IDs\n    // and startTimes (audio language variants) would see the new track's\n    // same-startTime segments marked \"buffered\" by the pre-flush snapshot,\n    // skip them in `getSegmentsToLoad`, and leave a permanent gap from\n    // `currentSegmentStart` to the end of the old buffer window — stalling\n    // playback.\n    const overlapsStale = (seg: { startTime: number; duration: number }): boolean => {\n      const segEnd = seg.startTime + seg.duration;\n      return (\n        removes.some((r) => seg.startTime < r.end && segEnd > r.start) ||\n        staleRanges.some((r) => seg.startTime < r.end && segEnd > r.start)\n      );\n    };\n    const effectiveBuffered =\n      removes.length + staleRanges.length > 0 ? bufferedSegments.filter((s) => !overlapsStale(s)) : bufferedSegments;\n\n    // Case 2: Init\n    if (actorCtx.initTrackId !== track.id) {\n      tasks.push({\n        type: 'append-init',\n        meta: { trackId: track.id, language: track.language },\n        url: track.initialization.url,\n        ...(track.initialization.byteRange !== undefined && { byteRange: track.initialization.byteRange }),\n      });\n    }\n\n    // Case 3: Segments\n    if (range) {\n      const segmentsToLoad = getSegmentsToLoad(\n        track.segments,\n        effectiveBuffered,\n        currentTime,\n        forwardBufferConfig\n      ).filter((seg) => {\n        // Quality-aware filter: skip segments already covered by equal-or-higher-quality\n        // content in the actor context. Preserves buffered high-quality content during\n        // ABR downgrades; loads during upgrades and for uncovered positions.\n        // Actor entries that overlap a planned remove OR a stale range are treated\n        // as nonexistent here — they're about to be flushed or overwritten, so the\n        // new-track segment must load regardless of the existing entry's bandwidth.\n        const existing = actorCtx.segments.find(\n          (s) => !overlapsStale(s) && Math.abs(s.startTime - seg.startTime) < SEGMENT_TIME_EPSILON\n        );\n        // Partial segments are still streaming — treat as not buffered so they\n        // are always re-planned (avoids relying on incomplete data).\n        if (existing?.partial) return true;\n        if (!existing?.trackBandwidth || !track.bandwidth) return true;\n        return track.bandwidth > existing.trackBandwidth;\n      });\n      for (const segment of segmentsToLoad) {\n        tasks.push({\n          type: 'append-segment',\n          meta: {\n            id: segment.id,\n            startTime: segment.startTime,\n            duration: segment.duration,\n            trackId: track.id,\n            trackBandwidth: track.bandwidth,\n          },\n          url: segment.url,\n          ...(segment.byteRange !== undefined && { byteRange: segment.byteRange }),\n        });\n      }\n    }\n\n    return tasks;\n  };\n\n  const scheduleAll = (tasks: LoadTask[], { getContext, setContext, runner }: Ctx): void => {\n    tasks.forEach((op) => {\n      runner.schedule(makeLoadTask(op, { getContext, setContext, pipelines, deps })).then(undefined, (e: unknown) => {\n        if (e instanceof Error && e.name === 'AbortError') return;\n        // On unexpected fetch/append errors, abort remaining tasks so a failed\n        // init doesn't cause segment fetches to proceed with no init segment.\n        console.error('Unexpected error in segment loader:', e);\n        runner.abortPending();\n      });\n    });\n  };\n\n  return createMachineActor<UserState, SegmentLoaderActorContext, SegmentLoaderMessage, () => SerialRunner>({\n    runner: () => new SerialRunner(),\n    initial: 'idle',\n    context: { inFlightInitTrackId: null, inFlightSegment: null },\n    states: {\n      idle: {\n        on: {\n          load: (msg, ctx) => {\n            const allTasks = planTasks(msg);\n            if (allTasks.length === 0) return;\n            ctx.transition('loading');\n            scheduleAll(allTasks, ctx);\n          },\n        },\n      },\n      loading: {\n        onSettled: 'idle',\n        on: {\n          load: (msg, ctx) => {\n            const { context, runner } = ctx;\n            const allTasks = planTasks(msg);\n\n            // Determine whether the in-flight operation is still needed. The\n            // segment match requires BOTH the positional id AND the trackId:\n            // renditions number segments independently, so an in-flight LOW\n            // `segment-0` (spanning [0, 7.13]) must NOT be treated as covering a\n            // switched-to HIGH `segment-0` (spanning [0, 7.98]). Matching by id\n            // alone kept the LOW fetch, skipped HIGH's leading segment, and left\n            // its tail as a gap — intermittently, only when the switch beat the\n            // in-flight append. A track switch now always preempts (correct: the\n            // new rendition's same-slot segment must be (re)fetched).\n            const inFlight = context.inFlightSegment;\n            const segmentInFlightStillNeeded = (t: LoadTask): boolean =>\n              t.type === 'append-segment' &&\n              inFlight !== null &&\n              t.meta.id === inFlight.id &&\n              t.meta.trackId === inFlight.trackId;\n            const inFlightStillNeeded =\n              (inFlight !== null && allTasks.some(segmentInFlightStillNeeded)) ||\n              (context.inFlightInitTrackId !== null &&\n                allTasks.some((t) => t.type === 'append-init' && t.meta.trackId === context.inFlightInitTrackId));\n\n            if (inFlightStillNeeded) {\n              // Continue: abort only the pending queue, let the in-flight task finish.\n              // Schedule everything except the in-flight item — it covers that slot.\n              runner.abortPending();\n              scheduleAll(\n                allTasks.filter(\n                  (t) =>\n                    !segmentInFlightStillNeeded(t) &&\n                    !(t.type === 'append-init' && t.meta.trackId === context.inFlightInitTrackId)\n                ),\n                ctx\n              );\n            } else {\n              // Preempt: abort everything and replan.\n              runner.abortAll();\n              // Cancel SourceBufferActor tasks when a segment is in-flight (always\n              // discard) or when a track switch is happening (new track's init follows).\n              // For a same-track seek with an in-flight init, skip cancel — the task's\n              // signal is not aborted (abortAll was called on the runner, but the init\n              // task already completed or will complete via its own signal path).\n              const cancelSourceBuffer =\n                context.inFlightSegment !== null ||\n                (context.inFlightInitTrackId !== null &&\n                  allTasks.some((t) => t.type === 'append-init' && t.meta.trackId !== context.inFlightInitTrackId));\n              if (cancelSourceBuffer) {\n                sourceBufferActor.send({ type: 'cancel' });\n              }\n              scheduleAll(allTasks, ctx);\n            }\n          },\n        },\n      },\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/default/playback/actors/dom/source-buffer.js

@@ -0,0 +1,139 @@
+import { SerialRunner, Task } from "../../../core/tasks/task.js";
+import { createMachineActor } from "../../../core/actors/create-machine-actor.js";
+import { appendSegment } from "../../../media/dom/mse/append-segment.js";
+import { flushBuffer } from "../../../media/dom/mse/buffer-flusher.js";
+import { SEGMENT_TIME_EPSILON } from "../../../media/types/index.js";
+//#region src/playback/actors/dom/source-buffer.ts
+function snapshotBuffered(buffered) {
+	const ranges = [];
+	for (let i = 0; i < buffered.length; i++) ranges.push({
+		start: buffered.start(i),
+		end: buffered.end(i)
+	});
+	return ranges;
+}
+function appendInitTask(message, { getContext, sourceBuffer }) {
+	return new Task(async (taskSignal) => {
+		const ctx = getContext();
+		if (taskSignal.aborted) return ctx;
+		await appendSegment(sourceBuffer, message.data);
+		return {
+			...ctx,
+			initTrackId: message.meta.trackId,
+			initTrackLanguage: message.meta.language
+		};
+	});
+}
+function appendSegmentTask(message, { getContext, sourceBuffer, setContext }) {
+	return new Task(async (taskSignal) => {
+		const ctx = getContext();
+		if (taskSignal.aborted) return ctx;
+		const { meta } = message;
+		const filtered = ctx.segments.filter((s) => Math.abs(s.startTime - meta.startTime) >= SEGMENT_TIME_EPSILON);
+		if (!(message.data instanceof ArrayBuffer)) setContext({
+			...ctx,
+			segments: [...filtered, {
+				id: meta.id,
+				startTime: meta.startTime,
+				duration: meta.duration,
+				trackId: meta.trackId,
+				...meta.trackBandwidth !== void 0 && { trackBandwidth: meta.trackBandwidth },
+				partial: true
+			}],
+			bufferedRanges: ctx.bufferedRanges
+		});
+		if (meta.timestampOffset != null && sourceBuffer.timestampOffset !== meta.timestampOffset) sourceBuffer.timestampOffset = meta.timestampOffset;
+		await appendSegment(sourceBuffer, message.data, taskSignal);
+		return {
+			...ctx,
+			segments: [...filtered, {
+				id: meta.id,
+				startTime: meta.startTime,
+				duration: meta.duration,
+				trackId: meta.trackId,
+				...meta.trackBandwidth !== void 0 && { trackBandwidth: meta.trackBandwidth }
+			}],
+			bufferedRanges: snapshotBuffered(sourceBuffer.buffered)
+		};
+	});
+}
+function removeTask(message, { getContext, sourceBuffer }) {
+	return new Task(async (taskSignal) => {
+		const ctx = getContext();
+		if (taskSignal.aborted) return ctx;
+		await flushBuffer(sourceBuffer, message.start, message.end);
+		const bufferedRanges = snapshotBuffered(sourceBuffer.buffered);
+		const filtered = ctx.segments.filter((s) => {
+			const midpoint = s.startTime + s.duration / 2;
+			return bufferedRanges.some((r) => midpoint >= r.start && midpoint < r.end);
+		});
+		return {
+			...ctx,
+			segments: filtered,
+			bufferedRanges
+		};
+	});
+}
+const messageTaskFactories = {
+	"append-init": appendInitTask,
+	"append-segment": appendSegmentTask,
+	remove: removeTask
+};
+function messageToTask(message, options) {
+	const factory = messageTaskFactories[message.type];
+	return factory(message, options);
+}
+function createSourceBufferActor(sourceBuffer, initialContext) {
+	const handleError = (e) => {
+		if (!(e instanceof Error && e.name === "AbortError")) console.error("SourceBuffer operation failed:", e);
+	};
+	const onMessage = (msg, { transition, setContext, getContext, runner }) => {
+		transition("updating");
+		const task = messageToTask(msg, {
+			getContext,
+			sourceBuffer,
+			setContext
+		});
+		runner.schedule(task).then(setContext, handleError);
+	};
+	return createMachineActor({
+		runner: () => new SerialRunner(),
+		initial: "idle",
+		context: {
+			segments: [],
+			bufferedRanges: [],
+			initTrackId: void 0,
+			...initialContext
+		},
+		states: {
+			idle: { on: {
+				"append-init": onMessage,
+				"append-segment": onMessage,
+				remove: onMessage,
+				batch: (msg, { transition, setContext, getContext, runner }) => {
+					const { messages } = msg;
+					if (messages.length === 0) return;
+					transition("updating");
+					messages.forEach((msg) => {
+						const task = messageToTask(msg, {
+							getContext,
+							sourceBuffer,
+							setContext
+						});
+						runner.schedule(task).then(setContext, handleError);
+					});
+				}
+			} },
+			updating: {
+				onSettled: "idle",
+				on: { cancel: (_, { runner }) => {
+					runner.abortAll();
+				} }
+			}
+		}
+	});
+}
+//#endregion
+export { createSourceBufferActor };
+
+//# sourceMappingURL=source-buffer.js.map

package/dist/default/playback/actors/dom/source-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-buffer.js","names":[],"sources":["../../../../../src/playback/actors/dom/source-buffer.ts"],"sourcesContent":["import { createMachineActor, type HandlerContext, type MessageActor } from '../../../core/actors/create-machine-actor';\nimport { SerialRunner, Task } from '../../../core/tasks/task';\nimport { type AppendData, appendSegment } from '../../../media/dom/mse/append-segment';\nimport { flushBuffer } from '../../../media/dom/mse/buffer-flusher';\nimport { SEGMENT_TIME_EPSILON, type Segment, type Track } from '../../../media/types';\nimport type {\n  AppendInitMessage,\n  AppendSegmentMessage,\n  IndividualSourceBufferMessage,\n  RemoveMessage,\n} from '../../primitives/source-buffer-messages';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface BufferedRange {\n  start: number;\n  end: number;\n}\n\nexport type { AppendData };\n\nexport type BatchMessage = { type: 'batch'; messages: IndividualSourceBufferMessage[] };\nexport type CancelMessage = { type: 'cancel' };\n\n/** All messages accepted by a SourceBufferActor. */\nexport type SourceBufferMessage = IndividualSourceBufferMessage | BatchMessage | CancelMessage;\n\n/** Finite states of the actor. */\nexport type SourceBufferActorState = 'idle' | 'updating' | 'destroyed';\n\n/** Non-finite (extended) data managed by the actor — the XState \"context\". */\nexport interface SourceBufferActorContext {\n  initTrackId?: string | undefined;\n  /**\n   * Language of the most recently appended init segment's track (when\n   * present on the playlist). Used by the segment-loader's `planTasks`\n   * to detect cross-language switches and schedule ahead-buffer flush.\n   * Undefined for video and for language-less audio.\n   */\n  initTrackLanguage?: string | undefined;\n  segments: Array<\n    Pick<Segment, 'id' | 'startTime' | 'duration'> & {\n      trackId: Track['id'];\n      trackBandwidth?: number;\n      /**\n       * True while a streaming append is in progress for this segment.\n       * The segment's data is partially present in the SourceBuffer.\n       * Downstream code must not treat a partial segment as fully buffered.\n       */\n      partial?: boolean;\n    }\n  >;\n  bufferedRanges: BufferedRange[];\n}\n\n/** SourceBuffer actor: queues operations, owns its snapshot. */\nexport type SourceBufferActor = MessageActor<SourceBufferActorState, SourceBufferActorContext, SourceBufferMessage>;\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\nfunction snapshotBuffered(buffered: TimeRanges): BufferedRange[] {\n  const ranges: BufferedRange[] = [];\n  for (let i = 0; i < buffered.length; i++) {\n    ranges.push({ start: buffered.start(i), end: buffered.end(i) });\n  }\n  return ranges;\n}\n\n// =============================================================================\n// Message task factories\n// =============================================================================\n\n// Context is read lazily via getContext at task execution time — not at creation\n// time — so each task always operates on the most recent context regardless of\n// when it was scheduled.\n\ninterface MessageTaskOptions {\n  getContext: () => SourceBufferActorContext;\n  sourceBuffer: SourceBuffer;\n  setContext: (ctx: SourceBufferActorContext) => void;\n}\n\nfunction appendInitTask(\n  message: AppendInitMessage,\n  { getContext, sourceBuffer }: MessageTaskOptions\n): Task<SourceBufferActorContext> {\n  return new Task(async (taskSignal) => {\n    const ctx = getContext();\n    if (taskSignal.aborted) return ctx;\n    await appendSegment(sourceBuffer, message.data);\n    // No abort check here: the physical SourceBuffer has been modified, so\n    // the model must be updated to match regardless of signal state.\n    return { ...ctx, initTrackId: message.meta.trackId, initTrackLanguage: message.meta.language };\n  });\n}\n\nfunction appendSegmentTask(\n  message: AppendSegmentMessage,\n  { getContext, sourceBuffer, setContext }: MessageTaskOptions\n): Task<SourceBufferActorContext> {\n  return new Task(async (taskSignal) => {\n    const ctx = getContext();\n    if (taskSignal.aborted) return ctx;\n\n    const { meta } = message;\n    // Remove any existing entry at the same start time (same \"slot\" in the\n    // timeline), then record the new segment. Assumes time-aligned segments\n    // across playlists. `SEGMENT_TIME_EPSILON` guards against floating-point\n    // drift in parsed timestamps (shared with the segment-loader quality\n    // filter — single source of truth).\n    //\n    // Misaligned renditions (e.g. 30fps vs 60fps rungs) break the same-slot\n    // assumption: the switched-to segment's differing startTime is kept as a\n    // separate overlapping entry rather than truncating the older one to the\n    // portion MSE didn't overwrite. Cosmetic today (see #1865 for the\n    // most-recent-append-wins model); coverage/flush stay correct.\n    const filtered = ctx.segments.filter((s) => Math.abs(s.startTime - meta.startTime) >= SEGMENT_TIME_EPSILON);\n\n    // For streaming data: emit partial state before the first chunk so\n    // downstream code can see the in-progress segment and treat it as\n    // incomplete. ArrayBuffer appends are atomic so no partial state is\n    // needed — context is updated once at task completion.\n    if (!(message.data instanceof ArrayBuffer)) {\n      setContext({\n        ...ctx,\n        segments: [\n          ...filtered,\n          {\n            id: meta.id,\n            startTime: meta.startTime,\n            duration: meta.duration,\n            trackId: meta.trackId,\n            ...(meta.trackBandwidth !== undefined && { trackBandwidth: meta.trackBandwidth }),\n            partial: true,\n          },\n        ],\n        bufferedRanges: ctx.bufferedRanges,\n      });\n    }\n\n    // Relocation: set the offset before the coded frames are appended. The\n    // SerialRunner guarantees the buffer is idle here, so the assignment is safe.\n    // Guarded so re-stamping the (constant) offset on later appends is a no-op.\n    if (meta.timestampOffset != null && sourceBuffer.timestampOffset !== meta.timestampOffset) {\n      sourceBuffer.timestampOffset = meta.timestampOffset;\n    }\n    await appendSegment(sourceBuffer, message.data, taskSignal);\n    // No abort check here: the physical SourceBuffer has been modified, so\n    // the model must be updated to match regardless of signal state.\n    return {\n      ...ctx,\n      segments: [\n        ...filtered,\n        {\n          id: meta.id,\n          startTime: meta.startTime,\n          duration: meta.duration,\n          trackId: meta.trackId,\n          ...(meta.trackBandwidth !== undefined && { trackBandwidth: meta.trackBandwidth }),\n        },\n      ],\n      bufferedRanges: snapshotBuffered(sourceBuffer.buffered),\n    };\n  });\n}\n\nfunction removeTask(\n  message: RemoveMessage,\n  { getContext, sourceBuffer }: MessageTaskOptions\n): Task<SourceBufferActorContext> {\n  return new Task(async (taskSignal) => {\n    const ctx = getContext();\n    if (taskSignal.aborted) return ctx;\n    await flushBuffer(sourceBuffer, message.start, message.end);\n    // No abort check here: the physical SourceBuffer has been modified, so\n    // the model must be updated to match regardless of signal state.\n    //\n    // Use the post-flush buffered ranges as ground truth. A segment is kept\n    // in the model only if its midpoint falls within a buffered range.\n    // Midpoint-based membership handles flush boundaries that don't align\n    // exactly with segment edges without over-removing adjacent segments.\n    const bufferedRanges = snapshotBuffered(sourceBuffer.buffered);\n    const filtered = ctx.segments.filter((s) => {\n      const midpoint = s.startTime + s.duration / 2;\n      return bufferedRanges.some((r) => midpoint >= r.start && midpoint < r.end);\n    });\n    return { ...ctx, segments: filtered, bufferedRanges };\n  });\n}\n\ntype MessageTaskFactory<T extends IndividualSourceBufferMessage> = (\n  message: T,\n  options: MessageTaskOptions\n) => Task<SourceBufferActorContext>;\n\nconst messageTaskFactories = {\n  'append-init': appendInitTask,\n  'append-segment': appendSegmentTask,\n  remove: removeTask,\n} satisfies {\n  [K in IndividualSourceBufferMessage['type']]: MessageTaskFactory<Extract<IndividualSourceBufferMessage, { type: K }>>;\n};\n\nfunction messageToTask(\n  message: IndividualSourceBufferMessage,\n  options: MessageTaskOptions\n): Task<SourceBufferActorContext> {\n  const factory = messageTaskFactories[message.type] as MessageTaskFactory<typeof message>;\n  return factory(message, options);\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\nexport function createSourceBufferActor(\n  sourceBuffer: SourceBuffer,\n  initialContext?: Partial<SourceBufferActorContext>\n): SourceBufferActor {\n  type UserState = Exclude<SourceBufferActorState, 'destroyed'>;\n\n  const handleError = (e: unknown): void => {\n    if (!(e instanceof Error && e.name === 'AbortError')) {\n      console.error('SourceBuffer operation failed:', e);\n    }\n  };\n\n  type Ctx = HandlerContext<UserState, SourceBufferActorContext, () => SerialRunner>;\n\n  const onMessage = (msg: IndividualSourceBufferMessage, { transition, setContext, getContext, runner }: Ctx): void => {\n    transition('updating');\n    const task = messageToTask(msg, { getContext, sourceBuffer, setContext });\n    runner.schedule(task).then(setContext, handleError);\n  };\n\n  return createMachineActor<UserState, SourceBufferActorContext, SourceBufferMessage, () => SerialRunner>({\n    runner: () => new SerialRunner(),\n    initial: 'idle',\n    context: { segments: [], bufferedRanges: [], initTrackId: undefined, ...initialContext },\n    states: {\n      idle: {\n        on: {\n          'append-init': onMessage,\n          'append-segment': onMessage,\n          remove: onMessage,\n          batch: (msg, { transition, setContext, getContext, runner }) => {\n            const { messages } = msg;\n            if (messages.length === 0) return;\n\n            transition('updating');\n            messages.forEach((msg) => {\n              const task = messageToTask(msg, { getContext, sourceBuffer, setContext });\n              runner.schedule(task).then(setContext, handleError);\n            });\n          },\n        },\n      },\n      updating: {\n        // Automatically return to idle once all scheduled tasks settle.\n        onSettled: 'idle',\n        on: {\n          // Abort all in-progress and pending tasks. onSettled handles → 'idle'\n          // once the aborted tasks drain.\n          cancel: (_, { runner }) => {\n            runner.abortAll();\n          },\n        },\n      },\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/default/playback/actors/dom/text-tracks.js

@@ -0,0 +1,46 @@
+import { createTransitionActor } from "../../../core/actors/create-transition-actor.js";
+//#region src/playback/actors/dom/text-tracks.ts
+function isDuplicateCue(cue, existing) {
+	return existing.some((r) => r.startTime === cue.startTime && r.endTime === cue.endTime && r.text === cue.text);
+}
+/** TextTrack actor: wraps all text tracks on a media element, owns cue operations. */
+function createTextTracksActor(mediaElement) {
+	return createTransitionActor({
+		loaded: {},
+		segments: {}
+	}, (context, message) => {
+		if (message.type === "clear") return {
+			loaded: {},
+			segments: {}
+		};
+		const { meta, cues } = message;
+		const { trackId, id: segmentId, startTime, duration } = meta;
+		const textTrack = Array.from(mediaElement.textTracks).find((t) => t.id === trackId);
+		if (!textTrack) return context;
+		const existingCues = context.loaded[trackId] ?? [];
+		const existingSegments = context.segments[trackId] ?? [];
+		const prunedCues = cues.filter((cue) => !isDuplicateCue(cue, existingCues));
+		const segmentAlreadyLoaded = existingSegments.some((s) => s.id === segmentId);
+		if (prunedCues.length === 0 && segmentAlreadyLoaded) return context;
+		for (const cue of prunedCues) textTrack.addCue(cue);
+		return {
+			...context,
+			loaded: {
+				...context.loaded,
+				[trackId]: [...existingCues, ...prunedCues]
+			},
+			segments: segmentAlreadyLoaded ? context.segments : {
+				...context.segments,
+				[trackId]: [...existingSegments, {
+					id: segmentId,
+					startTime,
+					duration
+				}]
+			}
+		};
+	});
+}
+//#endregion
+export { createTextTracksActor };
+
+//# sourceMappingURL=text-tracks.js.map

package/dist/default/playback/actors/dom/text-tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-tracks.js","names":[],"sources":["../../../../../src/playback/actors/dom/text-tracks.ts"],"sourcesContent":["import { createTransitionActor } from '../../../core/actors/create-transition-actor';\nimport type { Cue } from '../../../media/types';\nimport type { AddCuesMessage, CueSegmentMeta } from '../../primitives/text-track-messages';\nimport type { ClearMessage, TextTracksActor, TextTracksActorContext, TextTracksActorMessage } from '../text-tracks';\n\n// Re-export the host-agnostic types so existing dom-side consumers can keep\n// importing from this module.\nexport type {\n  AddCuesMessage,\n  ClearMessage,\n  CueSegmentMeta,\n  TextTracksActor,\n  TextTracksActorContext,\n  TextTracksActorMessage,\n};\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\nfunction isDuplicateCue(cue: VTTCue, existing: Cue[]): boolean {\n  return existing.some((r) => r.startTime === cue.startTime && r.endTime === cue.endTime && r.text === cue.text);\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/** TextTrack actor: wraps all text tracks on a media element, owns cue operations. */\nexport function createTextTracksActor(mediaElement: HTMLMediaElement): TextTracksActor<VTTCue> {\n  return createTransitionActor({ loaded: {}, segments: {} } as TextTracksActorContext, (context, message) => {\n    if (message.type === 'clear') {\n      // Reset the cue + segment cache. DOM cleanup is the caller's job —\n      // by the time we get here, `syncTextTracks` has already removed\n      // the `<track>` children (and their cues) via\n      // `removeAllSubtitlesTracksFromMedia`.\n      return { loaded: {}, segments: {} };\n    }\n\n    // NOTE: Currently assumes cues are applied to a non-disabled TextTrack. Discuss different approaches here, including:\n    // - Making the message responsible for auto-selection of the textTrack (changes logic in sync-text-tracks)\n    // - Silent gating/console warning + early bail\n    // - throwing a domain-specific error\n    // - accepting as is (which would result in errors, but also \"shouldn't ever happen\" unless a bug is introduced)\n    // (CJP)\n    const { meta, cues } = message;\n    const { trackId, id: segmentId, startTime, duration } = meta;\n    const textTrack = Array.from(mediaElement.textTracks).find((t) => t.id === trackId);\n    if (!textTrack) return context;\n\n    const existingCues = context.loaded[trackId] ?? [];\n    const existingSegments = context.segments[trackId] ?? [];\n    const prunedCues = cues.filter((cue) => !isDuplicateCue(cue, existingCues));\n    const segmentAlreadyLoaded = existingSegments.some((s) => s.id === segmentId);\n\n    if (prunedCues.length === 0 && segmentAlreadyLoaded) return context;\n\n    for (const cue of prunedCues) textTrack.addCue(cue);\n    return {\n      ...context,\n      loaded: {\n        ...context.loaded,\n        [trackId]: [...existingCues, ...prunedCues],\n      },\n      segments: segmentAlreadyLoaded\n        ? context.segments\n        : {\n            ...context.segments,\n            [trackId]: [...existingSegments, { id: segmentId, startTime, duration }],\n          },\n    };\n  });\n}\n"],"mappings":";;AAoBA,SAAS,eAAe,KAAa,UAA0B;CAC7D,OAAO,SAAS,MAAM,MAAM,EAAE,cAAc,IAAI,aAAa,EAAE,YAAY,IAAI,WAAW,EAAE,SAAS,IAAI,IAAI;AAC/G;;AAOA,SAAgB,sBAAsB,cAAyD;CAC7F,OAAO,sBAAsB;EAAE,QAAQ,CAAC;EAAG,UAAU,CAAC;CAAE,IAA8B,SAAS,YAAY;EACzG,IAAI,QAAQ,SAAS,SAKnB,OAAO;GAAE,QAAQ,CAAC;GAAG,UAAU,CAAC;EAAE;EASpC,MAAM,EAAE,MAAM,SAAS;EACvB,MAAM,EAAE,SAAS,IAAI,WAAW,WAAW,aAAa;EACxD,MAAM,YAAY,MAAM,KAAK,aAAa,UAAU,CAAC,CAAC,MAAM,MAAM,EAAE,OAAO,OAAO;EAClF,IAAI,CAAC,WAAW,OAAO;EAEvB,MAAM,eAAe,QAAQ,OAAO,YAAY,CAAC;EACjD,MAAM,mBAAmB,QAAQ,SAAS,YAAY,CAAC;EACvD,MAAM,aAAa,KAAK,QAAQ,QAAQ,CAAC,eAAe,KAAK,YAAY,CAAC;EAC1E,MAAM,uBAAuB,iBAAiB,MAAM,MAAM,EAAE,OAAO,SAAS;EAE5E,IAAI,WAAW,WAAW,KAAK,sBAAsB,OAAO;EAE5D,KAAK,MAAM,OAAO,YAAY,UAAU,OAAO,GAAG;EAClD,OAAO;GACL,GAAG;GACH,QAAQ;IACN,GAAG,QAAQ;KACV,UAAU,CAAC,GAAG,cAAc,GAAG,UAAU;GAC5C;GACA,UAAU,uBACN,QAAQ,WACR;IACE,GAAG,QAAQ;KACV,UAAU,CAAC,GAAG,kBAAkB;KAAE,IAAI;KAAW;KAAW;IAAS,CAAC;GACzE;EACN;CACF,CAAC;AACH"}