@videojs/spf 10.0.0-beta.14 → 10.0.0-beta.16

package/dist/dev/dom/features/load-text-track-cues.js

@@ -1,159 +1,102 @@
-import { getSegmentsToLoad } from "../../core/buffer/forward-buffer.js";
-import { effect } from "../../core/signals/effect.js";
-import { computed } from "../../core/signals/primitives.js";
+import { computed, untrack, update } from "../../core/signals/primitives.js";
 import { isResolvedTrack } from "../../core/types/index.js";
-import { parseVttSegment } from "../text/parse-vtt-segment.js";
+import { createMachineReactor } from "../../core/create-machine-reactor.js";
+import { createTextTrackSegmentLoaderActor } from "./text-track-segment-loader-actor.js";
+import { createTextTracksActor } from "./text-tracks-actor.js";
 //#region src/dom/features/load-text-track-cues.ts
-const CueKeys = [
-	"startTime",
-	"endTime",
-	"text"
-];
-function isDuplicateCue(cue, existingCues) {
-	return Array.prototype.some.call(existingCues ?? [], (existingCue) => {
-		return CueKeys.every((k) => existingCue[k] === cue[k]);
-	});
+function getTextTracks(presentation) {
+	return presentation?.selectionSets?.find((s) => s.type === "text")?.switchingSets[0]?.tracks;
 }
-const loadVttSegmentTask = async ({ segment }, { textTrack }) => {
-	(await parseVttSegment(segment.url)).forEach((cue) => {
-		if (isDuplicateCue(cue, textTrack.cues)) return;
-		textTrack.addCue(cue);
-	});
-};
-/**
-* Load text track cues task (composite - orchestrates VTT segment subtasks).
-*/
-const loadTextTrackCuesTask = async ({ currentState }, context) => {
-	const track = findSelectedTextTrack(currentState);
-	if (!track || !isResolvedTrack(track)) return;
-	const { segments } = track;
-	if (segments.length === 0) return;
-	const trackId = track.id;
-	const loadedIds = new Set((currentState.textBufferState?.[trackId]?.segments ?? []).map((s) => s.id));
-	const segmentsToLoad = getSegmentsToLoad(segments, segments.filter((s) => loadedIds.has(s.id)), currentState.currentTime ?? 0).filter((s) => !loadedIds.has(s.id));
-	if (segmentsToLoad.length === 0) return;
-	for (const segment of segmentsToLoad) {
-		if (context.signal.aborted) break;
-		try {
-			await loadVttSegmentTask({ segment }, { textTrack: context.textTrack });
-			const latestState = context.state.get();
-			const latest = latestState.textBufferState ?? {};
-			const trackState = latest[trackId] ?? { segments: [] };
-			context.state.set({
-				...latestState,
-				textBufferState: {
-					...latest,
-					[trackId]: { segments: [...trackState.segments, { id: segment.id }] }
-				}
-			});
-		} catch (error) {
-			if (error instanceof Error && error.name === "AbortError") break;
-			console.error("Failed to load VTT segment:", error);
-		}
-	}
-	if (context.textTrack.mode === "showing" && context.textTrack.cues) Array.from(context.textTrack.cues).forEach((cue) => {
-		context.textTrack.addCue(cue);
-	});
-	await new Promise((resolve) => requestAnimationFrame(resolve));
-};
-/**
-* Find the selected text track in the presentation.
-*/
-function findSelectedTextTrack(state) {
-	if (!state.presentation || !state.selectedTextTrackId) return;
-	const textSet = state.presentation.selectionSets.find((set) => set.type === "text");
-	if (!textSet?.switchingSets?.[0]?.tracks) return;
-	return textSet.switchingSets[0].tracks.find((t) => t.id === state.selectedTextTrackId);
+function findSelectedTrack(state) {
+	const track = getTextTracks(state.presentation)?.find((t) => t.id === state.selectedTextTrackId);
+	return track && isResolvedTrack(track) ? track : void 0;
 }
 /**
-* Get the browser's TextTrack object for the selected text track.
-*
-* Retrieves the live TextTrack interface from the track element in owners,
-* which is used for adding cues, checking mode, and managing track state.
+* Derives the correct state from current state and owners.
 *
-* Note: Returns the DOM TextTrack interface (HTMLTrackElement.track),
-* not the presentation Track metadata type.
-*
-* @param state - Current playback state (track selection)
-* @param owners - DOM owners containing track elements map
-* @returns DOM TextTrack interface or undefined if not found
+* States are mutually exclusive and exhaustive:
+* - `'preconditions-unmet'`: no mediaElement, or no resolved presentation with text tracks
+* - `'setting-up'`:          preconditions met; actors not yet in owners
+* - `'pending'`:             actors alive; no selection, or selected track not yet resolved/in DOM
+* - `'monitoring-for-loads'`: selected track resolved, in DOM — ready to dispatch load messages
 */
-function getSelectedTextTrackFromOwners(state, owners) {
-	const trackId = state.selectedTextTrackId;
-	if (!trackId || !owners.textTracks) return;
-	return owners.textTracks.get(trackId)?.track;
+function deriveState(state, owners) {
+	if (!owners.mediaElement || !getTextTracks(state.presentation)?.length) return "preconditions-unmet";
+	if (!owners.textTracksActor || !owners.segmentLoaderActor) return "setting-up";
+	const track = findSelectedTrack(state);
+	if (!track || track.segments.length === 0) return "pending";
+	if (!Array.from(owners.mediaElement.textTracks).some((t) => t.id === state.selectedTextTrackId)) return "pending";
+	return "monitoring-for-loads";
 }
-/**
-* Check if we can load text track cues.
-*
-* Requires:
-* - Selected text track ID exists
-* - Track elements map exists
-* - Track element exists for selected track
-*/
-function canLoadTextTrackCues(state, owners) {
-	return !!state.selectedTextTrackId && !!owners.textTracks && owners.textTracks.has(state.selectedTextTrackId);
+function teardownActors(owners) {
+	const { textTracksActor, segmentLoaderActor } = untrack(() => owners.get());
+	if (!textTracksActor && !segmentLoaderActor) return;
+	textTracksActor?.destroy();
+	segmentLoaderActor?.destroy();
+	update(owners, {
+		textTracksActor: void 0,
+		segmentLoaderActor: void 0
+	});
 }
 /**
-* Check if we should load text track cues.
+* Text track cue loading orchestration.
 *
-* Only load if:
-* - Track is resolved (has segments)
-* - Track has at least one segment
-* - Track element exists
-*/
-function shouldLoadTextTrackCues(state, owners) {
-	if (!canLoadTextTrackCues(state, owners)) return false;
-	const track = findSelectedTextTrack(state);
-	if (!track || !isResolvedTrack(track) || track.segments.length === 0) return false;
-	if (!getSelectedTextTrackFromOwners(state, owners)) return false;
-	return true;
-}
-/**
-* Load text track cues orchestration.
+* A single `always` monitor keeps the reactor in sync with conditions.
+* Actor lifecycle is managed across two states:
 *
-* Triggers when:
-* - Text track is selected
-* - Track is resolved (has segments)
-* - Track element exists
+* - **`'setting-up'`** — creates `TextTracksActor` and `TextTrackSegmentLoaderActor`
+*   and writes them to owners. Entry resets any stale actors first.
+* - **`'preconditions-unmet'`** — destroys any actors in owners and resets them to
+*   `undefined`. Handles all paths back from active states.
+* - **`'monitoring-for-loads'`** — reactive dispatch: re-runs whenever `state`
+*   changes (selection, currentTime, presentation) and sends a `load` message to
+*   the segment loader.
 *
-* Fetches and parses VTT segments within the forward buffer window, then adds
-* cues to the track incrementally. Continues on segment errors to provide
-* partial subtitles.
+* **Destroy note:** actors written to owners are NOT auto-destroyed when
+* `reactor.destroy()` is called. Callers must read them from owners and destroy
+* them explicitly alongside the reactor.
 *
 * @example
-* const cleanup = loadTextTrackCues({ state, owners });
+* const reactor = loadTextTrackCues({ state, owners });
+* // later:
+* const { textTracksActor, segmentLoaderActor } = owners.get();
+* textTracksActor?.destroy();
+* segmentLoaderActor?.destroy();
+* reactor.destroy();
 */
 function loadTextTrackCues({ state, owners }) {
-	let currentTask = null;
-	let abortController = null;
-	let lastTrackId;
-	const selectedTrackId = computed(() => state.get().selectedTextTrackId);
-	const cleanupEffect = effect(() => {
-		const s = state.get();
-		const o = owners.get();
-		if (selectedTrackId.get() !== lastTrackId) {
-			lastTrackId = selectedTrackId.get();
-			abortController?.abort();
-			currentTask = null;
+	const derivedStateSignal = computed(() => deriveState(state.get(), owners.get()));
+	const currentTimeSignal = computed(() => state.get().currentTime ?? 0);
+	const selectedTrackSignal = computed(() => findSelectedTrack(state.get()));
+	return createMachineReactor({
+		initial: "preconditions-unmet",
+		monitor: () => derivedStateSignal.get(),
+		states: {
+			"preconditions-unmet": { entry: () => {
+				teardownActors(owners);
+			} },
+			"setting-up": { entry: () => {
+				teardownActors(owners);
+				const mediaElement = owners.get().mediaElement;
+				const textTracksActor = createTextTracksActor(mediaElement);
+				update(owners, {
+					textTracksActor,
+					segmentLoaderActor: createTextTrackSegmentLoaderActor(textTracksActor)
+				});
+			} },
+			pending: {},
+			"monitoring-for-loads": { effects: () => {
+				const currentTime = currentTimeSignal.get();
+				const track = selectedTrackSignal.get();
+				const { segmentLoaderActor } = untrack(() => owners.get());
+				segmentLoaderActor.send({
+					type: "load",
+					track,
+					currentTime
+				});
+			} }
 		}
-		if (currentTask) return;
-		if (!shouldLoadTextTrackCues(s, o)) return;
-		const textTrack = getSelectedTextTrackFromOwners(s, o);
-		if (!textTrack) return;
-		abortController = new AbortController();
-		currentTask = loadTextTrackCuesTask({ currentState: s }, {
-			signal: abortController.signal,
-			textTrack,
-			state
-		}).finally(() => {
-			currentTask = null;
-		});
 	});
-	return () => {
-		abortController?.abort();
-		cleanupEffect();
-	};
 }
 //#endregion
 export { loadTextTrackCues };

package/dist/dev/dom/features/load-text-track-cues.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-text-track-cues.js","names":[],"sources":["../../../../src/dom/features/load-text-track-cues.ts"],"sourcesContent":["import { getSegmentsToLoad } from '../../core/buffer/forward-buffer';\nimport { effect } from '../../core/signals/effect';\nimport { computed, type Signal } from '../../core/signals/primitives';\nimport type { Presentation, Segment, TextTrack } from '../../core/types';\nimport { isResolvedTrack } from '../../core/types';\nimport { parseVttSegment } from '../text/parse-vtt-segment';\n\nconst CueKeys = ['startTime', 'endTime', 'text'] as const;\nfunction isDuplicateCue(cue: VTTCue, existingCues: globalThis.TextTrack['cues']): boolean {\n  return Array.prototype.some.call(existingCues ?? [], (existingCue) => {\n    return CueKeys.every((k) => existingCue[k] === cue[k]);\n  });\n}\n\nconst loadVttSegmentTask = async (\n  { segment }: { segment: Segment },\n  { textTrack }: { textTrack: globalThis.TextTrack }\n): Promise<void> => {\n  const cues = await parseVttSegment(segment.url);\n  cues.forEach((cue) => {\n    if (isDuplicateCue(cue, textTrack.cues)) return;\n    textTrack.addCue(cue);\n  });\n};\n\n// ============================================================================\n// MAIN TASK (composite - orchestrates subtasks)\n// ============================================================================\n\n/**\n * Load text track cues task (composite - orchestrates VTT segment subtasks).\n */\nconst loadTextTrackCuesTask = async <S extends TextTrackCueLoadingState>(\n  { currentState }: { currentState: S },\n  context: {\n    signal: AbortSignal;\n    textTrack: globalThis.TextTrack;\n    state: Signal<S>;\n  }\n): Promise<void> => {\n  const track = findSelectedTextTrack(currentState);\n  if (!track || !isResolvedTrack(track)) return;\n\n  const { segments } = track;\n  if (segments.length === 0) return;\n\n  const trackId = track.id;\n\n  // Resolve segments already recorded in the state model for this track.\n  // Keyed by track ID so multiple text tracks don't interfere with each other.\n  const loadedIds = new Set((currentState.textBufferState?.[trackId]?.segments ?? []).map((s) => s.id));\n  const alreadyLoaded = segments.filter((s) => loadedIds.has(s.id));\n\n  // Apply the same forward buffer window as audio/video segment loading.\n  const currentTime = currentState.currentTime ?? 0;\n  const segmentsToLoad = getSegmentsToLoad(segments, alreadyLoaded, currentTime).filter((s) => !loadedIds.has(s.id));\n\n  if (segmentsToLoad.length === 0) return;\n\n  // Execute subtasks sequentially, recording each loaded segment in state.\n  for (const segment of segmentsToLoad) {\n    if (context.signal.aborted) break;\n\n    try {\n      await loadVttSegmentTask({ segment }, { textTrack: context.textTrack });\n\n      // Record the loaded segment in shared state — mirrors bufferState for\n      // audio/video and supports N text tracks keyed by track ID.\n      const latestState = context.state.get();\n      const latest = latestState.textBufferState ?? {};\n      const trackState = latest[trackId] ?? { segments: [] };\n      context.state.set({\n        ...latestState,\n        textBufferState: {\n          ...latest,\n          [trackId]: { segments: [...trackState.segments, { id: segment.id }] },\n        },\n      } as S);\n    } catch (error) {\n      if (error instanceof Error && error.name === 'AbortError') break;\n      console.error('Failed to load VTT segment:', error);\n      // Continue to next segment (graceful degradation)\n    }\n  }\n\n  // Chrome bug: after a track goes through mode='disabled' (which clears cues) and back\n  // to 'showing', cues added to the track aren't activated. Re-adding all cues forces\n  // Chrome to re-process them. Safe no-op in other browsers.\n  // Mirrors the workaround in HlsMediaTextTracksMixin (packages/core/src/dom/media/hls/text-tracks.ts).\n  if (context.textTrack.mode === 'showing' && context.textTrack.cues) {\n    Array.from(context.textTrack.cues).forEach((cue) => {\n      context.textTrack.addCue(cue);\n    });\n  }\n\n  // Wait a frame before completing to allow state updates to flush\n  await new Promise((resolve) => requestAnimationFrame(resolve));\n};\n\n// ============================================================================\n// STATE & OWNERS\n// ============================================================================\n\n/**\n * Loaded-segment record for a single text track.\n */\nexport interface TextTrackSegmentState {\n  segments: Array<{ id: string }>;\n}\n\n/**\n * Buffer model for text track cues — keyed by track ID.\n *\n * Using a per-track-ID map (rather than fixed 'video'/'audio' keys) because\n * there can be N text tracks — one per language/subtitle variant.\n */\nexport type TextTrackBufferState = Record<string, TextTrackSegmentState>;\n\n/**\n * State shape for text track cue loading.\n */\nexport interface TextTrackCueLoadingState {\n  selectedTextTrackId?: string;\n  presentation?: Presentation;\n  /** Current playback position — used to gate VTT segment fetching to the forward buffer window. */\n  currentTime?: number;\n  /** Loaded-segment model for text tracks, keyed by track ID. */\n  textBufferState?: TextTrackBufferState;\n}\n\n/**\n * Owners shape for text track cue loading.\n */\nexport interface TextTrackCueLoadingOwners {\n  textTracks?: Map<string, HTMLTrackElement>;\n}\n\n/**\n * Find the selected text track in the presentation.\n */\nfunction findSelectedTextTrack(state: TextTrackCueLoadingState): TextTrack | undefined {\n  if (!state.presentation || !state.selectedTextTrackId) {\n    return undefined;\n  }\n\n  const textSet = state.presentation.selectionSets.find((set) => set.type === 'text');\n  if (!textSet?.switchingSets?.[0]?.tracks) {\n    return undefined;\n  }\n\n  const track = textSet.switchingSets[0].tracks.find((t) => t.id === state.selectedTextTrackId);\n\n  return track as TextTrack | undefined;\n}\n\n/**\n * Get the browser's TextTrack object for the selected text track.\n *\n * Retrieves the live TextTrack interface from the track element in owners,\n * which is used for adding cues, checking mode, and managing track state.\n *\n * Note: Returns the DOM TextTrack interface (HTMLTrackElement.track),\n * not the presentation Track metadata type.\n *\n * @param state - Current playback state (track selection)\n * @param owners - DOM owners containing track elements map\n * @returns DOM TextTrack interface or undefined if not found\n */\nfunction getSelectedTextTrackFromOwners(\n  state: TextTrackCueLoadingState,\n  owners: TextTrackCueLoadingOwners\n): globalThis.TextTrack | undefined {\n  const trackId = state.selectedTextTrackId;\n  if (!trackId || !owners.textTracks) {\n    return undefined;\n  }\n\n  const trackElement = owners.textTracks.get(trackId);\n  return trackElement?.track;\n}\n\n/**\n * Check if we can load text track cues.\n *\n * Requires:\n * - Selected text track ID exists\n * - Track elements map exists\n * - Track element exists for selected track\n */\nexport function canLoadTextTrackCues(state: TextTrackCueLoadingState, owners: TextTrackCueLoadingOwners): boolean {\n  return !!state.selectedTextTrackId && !!owners.textTracks && owners.textTracks.has(state.selectedTextTrackId);\n}\n\n/**\n * Check if we should load text track cues.\n *\n * Only load if:\n * - Track is resolved (has segments)\n * - Track has at least one segment\n * - Track element exists\n */\nexport function shouldLoadTextTrackCues(state: TextTrackCueLoadingState, owners: TextTrackCueLoadingOwners): boolean {\n  if (!canLoadTextTrackCues(state, owners)) {\n    return false;\n  }\n\n  const track = findSelectedTextTrack(state);\n  if (!track || !isResolvedTrack(track) || track.segments.length === 0) {\n    return false;\n  }\n\n  const textTrack = getSelectedTextTrackFromOwners(state, owners);\n  if (!textTrack) {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Load text track cues orchestration.\n *\n * Triggers when:\n * - Text track is selected\n * - Track is resolved (has segments)\n * - Track element exists\n *\n * Fetches and parses VTT segments within the forward buffer window, then adds\n * cues to the track incrementally. Continues on segment errors to provide\n * partial subtitles.\n *\n * @example\n * const cleanup = loadTextTrackCues({ state, owners });\n */\nexport function loadTextTrackCues<S extends TextTrackCueLoadingState, O extends TextTrackCueLoadingOwners>({\n  state,\n  owners,\n}: {\n  state: Signal<S>;\n  owners: Signal<O>;\n}): () => void {\n  let currentTask: Promise<void> | null = null;\n  let abortController: AbortController | null = null;\n  let lastTrackId: string | undefined;\n\n  const selectedTrackId = computed(() => state.get().selectedTextTrackId);\n\n  const cleanupEffect = effect(() => {\n    const s = state.get();\n    const o = owners.get();\n\n    // Abort any in-progress task when the selected track changes.\n    // The new track's textBufferState entry will be empty, so the task\n    // naturally starts fresh without needing any explicit reset.\n    if (selectedTrackId.get() !== lastTrackId) {\n      lastTrackId = selectedTrackId.get();\n      abortController?.abort();\n      currentTask = null;\n    }\n\n    if (currentTask) return;\n    if (!shouldLoadTextTrackCues(s, o)) return;\n\n    const textTrack = getSelectedTextTrackFromOwners(s, o);\n    if (!textTrack) return;\n\n    abortController = new AbortController();\n    currentTask = loadTextTrackCuesTask(\n      { currentState: s },\n      { signal: abortController.signal, textTrack, state }\n    ).finally(() => {\n      currentTask = null;\n    });\n  });\n\n  return () => {\n    abortController?.abort();\n    cleanupEffect();\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"load-text-track-cues.js","names":[],"sources":["../../../../src/dom/features/load-text-track-cues.ts"],"sourcesContent":["import type { Reactor } from '../../core/create-machine-reactor';\nimport { createMachineReactor } from '../../core/create-machine-reactor';\nimport { computed, type Signal, untrack, update } from '../../core/signals/primitives';\nimport type { Presentation, TextTrack } from '../../core/types';\nimport { isResolvedTrack } from '../../core/types';\nimport type { TextTrackSegmentLoaderActor } from './text-track-segment-loader-actor';\nimport { createTextTrackSegmentLoaderActor } from './text-track-segment-loader-actor';\nimport type { TextTracksActor } from './text-tracks-actor';\nimport { createTextTracksActor } from './text-tracks-actor';\n\n/**\n * FSM states for text track cue loading.\n *\n * ```\n * 'preconditions-unmet' ── mediaElement + presentation + text tracks ──→ 'setting-up'\n *        ↑                                                                      |\n *        │                                                             actors created\n *        │                                                             in owners\n *        │                                                                      ↓\n *        ├───────────────── preconditions lost ─────────────────────── 'pending'\n *        │                                                                      |\n *        │                                                  selectedTrack resolved + in DOM\n *        │                                                                      ↓\n *        └───────────────── preconditions lost ──────────── 'monitoring-for-loads'\n *\n * any state ──── destroy() ────→ 'destroying' ────→ 'destroyed'\n * ```\n */\nexport type LoadTextTrackCuesState = 'preconditions-unmet' | 'setting-up' | 'pending' | 'monitoring-for-loads';\n\n/**\n * State shape for text track cue loading.\n */\nexport interface TextTrackCueLoadingState {\n  selectedTextTrackId?: string;\n  presentation?: Presentation;\n  /** Current playback position — used to gate VTT segment fetching to the forward buffer window. */\n  currentTime?: number;\n}\n\n/**\n * Owners shape for text track cue loading.\n *\n * `textTracksActor` and `segmentLoaderActor` are managed by this reactor:\n * written to owners in `'setting-up'` and reset to `undefined` on entry to\n * `'preconditions-unmet'` or `'setting-up'`. Callers are responsible for\n * destroying them when the reactor itself is destroyed (actors are not\n * auto-cleaned on `destroy()` — read them from owners and destroy explicitly).\n */\nexport interface TextTrackCueLoadingOwners {\n  mediaElement?: HTMLMediaElement | undefined;\n  textTracksActor?: TextTracksActor | undefined;\n  segmentLoaderActor?: TextTrackSegmentLoaderActor | undefined;\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nfunction getTextTracks(presentation: Presentation | undefined) {\n  return presentation?.selectionSets?.find((s) => s.type === 'text')?.switchingSets[0]?.tracks;\n}\n\nfunction findSelectedTrack(state: TextTrackCueLoadingState): TextTrack | undefined {\n  const track = getTextTracks(state.presentation)?.find((t) => t.id === state.selectedTextTrackId);\n  return track && isResolvedTrack(track) ? track : undefined;\n}\n\n/**\n * Derives the correct state from current state and owners.\n *\n * States are mutually exclusive and exhaustive:\n * - `'preconditions-unmet'`: no mediaElement, or no resolved presentation with text tracks\n * - `'setting-up'`:          preconditions met; actors not yet in owners\n * - `'pending'`:             actors alive; no selection, or selected track not yet resolved/in DOM\n * - `'monitoring-for-loads'`: selected track resolved, in DOM — ready to dispatch load messages\n */\nfunction deriveState(state: TextTrackCueLoadingState, owners: TextTrackCueLoadingOwners): LoadTextTrackCuesState {\n  if (!owners.mediaElement || !getTextTracks(state.presentation)?.length) {\n    return 'preconditions-unmet';\n  }\n  if (!owners.textTracksActor || !owners.segmentLoaderActor) {\n    return 'setting-up';\n  }\n  const track = findSelectedTrack(state);\n  if (!track || track.segments.length === 0) return 'pending';\n  if (!Array.from(owners.mediaElement.textTracks).some((t) => t.id === state.selectedTextTrackId)) {\n    return 'pending';\n  }\n  return 'monitoring-for-loads';\n}\n\nfunction teardownActors(owners: Signal<TextTrackCueLoadingOwners>) {\n  const { textTracksActor, segmentLoaderActor } = untrack(() => owners.get());\n  // Only update owners if there are actors to clean up — avoids spurious\n  // signal writes on initial startup that would re-trigger other features.\n  if (!textTracksActor && !segmentLoaderActor) return;\n  textTracksActor?.destroy();\n  segmentLoaderActor?.destroy();\n  update(owners, { textTracksActor: undefined, segmentLoaderActor: undefined });\n}\n\n// ============================================================================\n// Main export\n// ============================================================================\n\n/**\n * Text track cue loading orchestration.\n *\n * A single `always` monitor keeps the reactor in sync with conditions.\n * Actor lifecycle is managed across two states:\n *\n * - **`'setting-up'`** — creates `TextTracksActor` and `TextTrackSegmentLoaderActor`\n *   and writes them to owners. Entry resets any stale actors first.\n * - **`'preconditions-unmet'`** — destroys any actors in owners and resets them to\n *   `undefined`. Handles all paths back from active states.\n * - **`'monitoring-for-loads'`** — reactive dispatch: re-runs whenever `state`\n *   changes (selection, currentTime, presentation) and sends a `load` message to\n *   the segment loader.\n *\n * **Destroy note:** actors written to owners are NOT auto-destroyed when\n * `reactor.destroy()` is called. Callers must read them from owners and destroy\n * them explicitly alongside the reactor.\n *\n * @example\n * const reactor = loadTextTrackCues({ state, owners });\n * // later:\n * const { textTracksActor, segmentLoaderActor } = owners.get();\n * textTracksActor?.destroy();\n * segmentLoaderActor?.destroy();\n * reactor.destroy();\n */\nexport function loadTextTrackCues<S extends TextTrackCueLoadingState, O extends TextTrackCueLoadingOwners>({\n  state,\n  owners,\n}: {\n  state: Signal<S>;\n  owners: Signal<O>;\n}): Reactor<LoadTextTrackCuesState | 'destroying' | 'destroyed'> {\n  const derivedStateSignal = computed(() => deriveState(state.get(), owners.get()));\n  const currentTimeSignal = computed(() => state.get().currentTime ?? 0);\n  const selectedTrackSignal = computed(() => findSelectedTrack(state.get()));\n\n  return createMachineReactor<LoadTextTrackCuesState>({\n    initial: 'preconditions-unmet',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'preconditions-unmet': {\n        // Entry: defensive actor reset on state entry (no-op if already undefined).\n        entry: () => {\n          teardownActors(owners);\n        },\n      },\n\n      'setting-up': {\n        // Entry: reset any stale actors, then create fresh ones and write to owners.\n        // The fn body is automatically untracked — no untrack() needed for mediaElement.\n        entry: () => {\n          teardownActors(owners);\n          const mediaElement = owners.get().mediaElement as HTMLMediaElement;\n          const textTracksActor = createTextTracksActor(mediaElement);\n          const segmentLoaderActor = createTextTrackSegmentLoaderActor(textTracksActor);\n          update(owners, { textTracksActor, segmentLoaderActor } as Partial<O>);\n        },\n      },\n\n      pending: {},\n\n      'monitoring-for-loads': {\n        // Reaction: re-runs whenever currentTime or selectedTrack changes, dispatching\n        // a load message to the segment loader. owners is read with untrack() since\n        // actor presence is guaranteed by deriveState when in this state.\n        effects: () => {\n          const currentTime = currentTimeSignal.get();\n          const track = selectedTrackSignal.get()!;\n          // deriveState guarantees segmentLoaderActor is in owners and findSelectedTrack\n          // returns a valid resolved track when in this state. The always monitor\n          // (registered before this effect) transitions us out before this re-runs\n          // if either invariant ever stops holding.\n          const { segmentLoaderActor } = untrack(() => owners.get());\n          segmentLoaderActor!.send({ type: 'load', track, currentTime });\n        },\n      },\n    },\n  });\n}\n"],"mappings":";;;;;;AA2DA,SAAS,cAAc,cAAwC;AAC7D,QAAO,cAAc,eAAe,MAAM,MAAM,EAAE,SAAS,OAAO,EAAE,cAAc,IAAI;;AAGxF,SAAS,kBAAkB,OAAwD;CACjF,MAAM,QAAQ,cAAc,MAAM,aAAa,EAAE,MAAM,MAAM,EAAE,OAAO,MAAM,oBAAoB;AAChG,QAAO,SAAS,gBAAgB,MAAM,GAAG,QAAQ,KAAA;;;;;;;;;;;AAYnD,SAAS,YAAY,OAAiC,QAA2D;AAC/G,KAAI,CAAC,OAAO,gBAAgB,CAAC,cAAc,MAAM,aAAa,EAAE,OAC9D,QAAO;AAET,KAAI,CAAC,OAAO,mBAAmB,CAAC,OAAO,mBACrC,QAAO;CAET,MAAM,QAAQ,kBAAkB,MAAM;AACtC,KAAI,CAAC,SAAS,MAAM,SAAS,WAAW,EAAG,QAAO;AAClD,KAAI,CAAC,MAAM,KAAK,OAAO,aAAa,WAAW,CAAC,MAAM,MAAM,EAAE,OAAO,MAAM,oBAAoB,CAC7F,QAAO;AAET,QAAO;;AAGT,SAAS,eAAe,QAA2C;CACjE,MAAM,EAAE,iBAAiB,uBAAuB,cAAc,OAAO,KAAK,CAAC;AAG3E,KAAI,CAAC,mBAAmB,CAAC,mBAAoB;AAC7C,kBAAiB,SAAS;AAC1B,qBAAoB,SAAS;AAC7B,QAAO,QAAQ;EAAE,iBAAiB,KAAA;EAAW,oBAAoB,KAAA;EAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiC/E,SAAgB,kBAA2F,EACzG,OACA,UAI+D;CAC/D,MAAM,qBAAqB,eAAe,YAAY,MAAM,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;CACjF,MAAM,oBAAoB,eAAe,MAAM,KAAK,CAAC,eAAe,EAAE;CACtE,MAAM,sBAAsB,eAAe,kBAAkB,MAAM,KAAK,CAAC,CAAC;AAE1E,QAAO,qBAA6C;EAClD,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,uBAAuB,EAErB,aAAa;AACX,mBAAe,OAAO;MAEzB;GAED,cAAc,EAGZ,aAAa;AACX,mBAAe,OAAO;IACtB,MAAM,eAAe,OAAO,KAAK,CAAC;IAClC,MAAM,kBAAkB,sBAAsB,aAAa;AAE3D,WAAO,QAAQ;KAAE;KAAiB,oBADP,kCAAkC,gBAAgB;KACvB,CAAe;MAExE;GAED,SAAS,EAAE;GAEX,wBAAwB,EAItB,eAAe;IACb,MAAM,cAAc,kBAAkB,KAAK;IAC3C,MAAM,QAAQ,oBAAoB,KAAK;IAKvC,MAAM,EAAE,uBAAuB,cAAc,OAAO,KAAK,CAAC;AAC1D,uBAAoB,KAAK;KAAE,MAAM;KAAQ;KAAO;KAAa,CAAC;MAEjE;GACF;EACF,CAAC"}

package/dist/dev/dom/features/segment-loader-actor.js

@@ -1,17 +1,121 @@
 import { calculateForwardFlushPoint, getSegmentsToLoad } from "../../core/buffer/forward-buffer.js";
+import { effect } from "../../core/signals/effect.js";
 import { calculateBackBufferFlushPoint } from "../../core/buffer/back-buffer.js";
+import { createMachineActor } from "../../core/create-machine-actor.js";
+import { SerialRunner, Task } from "../../core/task.js";
 //#region src/dom/features/segment-loader-actor.ts
 /**
+* Resolves when the SourceBufferActor snapshot reaches 'idle'.
+* Rejects if the signal is aborted or the actor is destroyed.
+*
+* Used to sequence SourceBufferActor operations without awaiting send()
+* directly — send() is fire-and-forget; callers observe completion via
+* state transition.
+*/
+function waitForIdle(snapshot, signal) {
+	return new Promise((resolve, reject) => {
+		if (snapshot.get().value === "idle") {
+			resolve();
+			return;
+		}
+		if (snapshot.get().value === "destroyed") {
+			reject(new DOMException("Aborted", "AbortError"));
+			return;
+		}
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		let stop;
+		const cleanup = (fn) => {
+			stop?.();
+			signal.removeEventListener("abort", onAbort);
+			fn();
+		};
+		const onAbort = () => cleanup(() => reject(signal.reason));
+		stop = effect(() => {
+			const value = snapshot.get().value;
+			if (value === "idle") cleanup(resolve);
+			else if (value === "destroyed") cleanup(() => reject(new DOMException("Aborted", "AbortError")));
+		});
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Wraps a LoadTask descriptor into a Task that fetches (if needed) and
+* forwards to SourceBufferActor. Updates in-flight context around async
+* operations so the loading handler can make accurate continue/preempt
+* decisions at any point.
+*/
+function makeLoadTask(op, { getContext, setContext, fetchBytes, sourceBufferActor }) {
+	return new Task(async (taskSignal) => {
+		if (taskSignal.aborted) return;
+		if (op.type === "remove") {
+			sourceBufferActor.send(op);
+			await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			return;
+		}
+		if (op.type === "append-init") {
+			setContext({
+				...getContext(),
+				inFlightInitTrackId: op.meta.trackId
+			});
+			try {
+				const data = await fetchBytes(op, {
+					signal: taskSignal,
+					minChunkSize: Infinity
+				});
+				if (!taskSignal.aborted) {
+					sourceBufferActor.send({
+						type: "append-init",
+						data,
+						meta: op.meta
+					});
+					await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+				}
+			} finally {
+				setContext({
+					...getContext(),
+					inFlightInitTrackId: null
+				});
+			}
+			return;
+		}
+		setContext({
+			...getContext(),
+			inFlightSegmentId: op.meta.id
+		});
+		try {
+			const stream = await fetchBytes(op, { signal: taskSignal });
+			if (!taskSignal.aborted) {
+				sourceBufferActor.send({
+					type: "append-segment",
+					data: stream,
+					meta: op.meta
+				});
+				await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			}
+		} finally {
+			setContext({
+				...getContext(),
+				inFlightSegmentId: 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 `send()` on every incoming message, producing
-* an ordered LoadTask list. The runner drains that list sequentially. When a new
-* message arrives mid-run, send() replans and either continues the in-flight
-* operation (if still needed) or preempts it.
+* 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).
@@ -19,19 +123,13 @@ import { calculateBackBufferFlushPoint } from "../../core/buffer/back-buffer.js"
 *   so the entire body accumulates as one chunk before appending.
 */
 function createSegmentLoaderActor(sourceBufferActor, fetchBytes) {
-	let pendingTasks = null;
-	let inFlightInitTrackId = null;
-	let inFlightSegmentId = null;
-	let abortController = null;
-	let running = false;
-	let destroyed = false;
 	const getBufferedSegments = (allSegments) => {
 		const bufferedIds = new Set(sourceBufferActor.snapshot.get().context.segments.filter((s) => !s.partial).map((s) => s.id));
 		return allSegments.filter((s) => bufferedIds.has(s.id));
 	};
 	/**
 	* Translate a load message into an ordered LoadTask list based on committed
-	* actor state. In-flight awareness is handled separately in send().
+	* actor state. In-flight awareness is handled separately in the load handler.
 	*
 	* @todo Rename alongside LoadTask (e.g. planOps).
 	*
@@ -93,102 +191,51 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes) {
 		}
 		return tasks;
 	};
-	/**
-	* Execute a single LoadTask: fetch (if needed) then forward to SourceBufferActor.
-	* Sets/clears in-flight tracking around async operations so send() can make
-	* accurate continue/preempt decisions at any point during execution.
-	*
-	* @todo Rename alongside LoadTask (e.g. executeOp).
-	*/
-	const executeLoadTask = async (task) => {
-		const signal = abortController.signal;
-		try {
-			if (task.type === "remove") {
-				await sourceBufferActor.send(task, signal);
-				return;
-			}
-			if (task.type === "append-init") {
-				inFlightInitTrackId = task.meta.trackId;
-				if (!signal.aborted) {
-					const data = await fetchBytes(task, {
-						signal,
-						minChunkSize: Infinity
-					});
-					const isTrackSwitch = pendingTasks?.some((t) => t.type === "append-init" && t.meta.trackId !== task.meta.trackId);
-					if (!signal.aborted || !isTrackSwitch) {
-						const appendSignal = signal.aborted ? new AbortController().signal : signal;
-						await sourceBufferActor.send({
-							type: "append-init",
-							data,
-							meta: task.meta
-						}, appendSignal);
-					}
-				}
-				return;
-			}
-			inFlightSegmentId = task.meta.id;
-			if (!signal.aborted) {
-				const stream = await fetchBytes(task, { signal });
-				if (!signal.aborted) await sourceBufferActor.send({
-					type: "append-segment",
-					data: stream,
-					meta: task.meta
-				}, signal);
-			}
-		} finally {
-			inFlightInitTrackId = null;
-			inFlightSegmentId = null;
-		}
-	};
-	/**
-	* Drain the scheduled task list sequentially.
-	* After each task completes, checks for a pending replacement plan from send().
-	* If the signal was aborted and no new plan arrived, stops immediately.
-	*/
-	const runScheduled = async (initialTasks) => {
-		running = true;
-		abortController = new AbortController();
-		let scheduled = initialTasks;
-		while (scheduled.length > 0 && !destroyed) {
-			const task = scheduled[0];
-			scheduled = scheduled.slice(1);
-			try {
-				await executeLoadTask(task);
-			} catch (error) {
-				if (error instanceof Error && error.name === "AbortError") {} else {
-					console.error("Unexpected error in segment loader:", error);
-					scheduled = [];
-				}
-			}
-			if (pendingTasks !== null) {
-				scheduled = pendingTasks;
-				pendingTasks = null;
-				abortController = new AbortController();
-			} else if (abortController.signal.aborted) break;
-		}
-		abortController = null;
-		running = false;
+	const scheduleAll = (tasks, { getContext, setContext, runner }) => {
+		tasks.forEach((op) => {
+			runner.schedule(makeLoadTask(op, {
+				getContext,
+				setContext,
+				fetchBytes,
+				sourceBufferActor
+			})).then(void 0, (e) => {
+				if (e instanceof Error && e.name === "AbortError") return;
+				console.error("Unexpected error in segment loader:", e);
+				runner.abortPending();
+			});
+		});
 	};
-	return {
-		send(message) {
-			if (destroyed) return;
-			const allTasks = planTasks(message);
-			if (!running) {
+	return createMachineActor({
+		runner: () => new SerialRunner(),
+		initial: "idle",
+		context: {
+			inFlightInitTrackId: null,
+			inFlightSegmentId: null
+		},
+		states: {
+			idle: { on: { load: (msg, ctx) => {
+				const allTasks = planTasks(msg);
 				if (allTasks.length === 0) return;
-				runScheduled(allTasks);
-				return;
-			}
-			if (inFlightSegmentId !== null && allTasks.some((t) => t.type === "append-segment" && t.meta.id === inFlightSegmentId) || inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === inFlightInitTrackId)) pendingTasks = allTasks.filter((t) => !(t.type === "append-segment" && t.meta.id === inFlightSegmentId) && !(t.type === "append-init" && t.meta.trackId === inFlightInitTrackId));
-			else {
-				pendingTasks = allTasks;
-				abortController?.abort();
+				ctx.transition("loading");
+				scheduleAll(allTasks, ctx);
+			} } },
+			loading: {
+				onSettled: "idle",
+				on: { load: (msg, ctx) => {
+					const { context, runner } = ctx;
+					const allTasks = planTasks(msg);
+					if (context.inFlightSegmentId !== null && allTasks.some((t) => t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
+						runner.abortPending();
+						scheduleAll(allTasks.filter((t) => !(t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
+					} else {
+						runner.abortAll();
+						if (context.inFlightSegmentId !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
+						scheduleAll(allTasks, ctx);
+					}
+				} }
 			}
-		},
-		destroy() {
-			destroyed = true;
-			abortController?.abort();
 		}
-	};
+	});
 }
 //#endregion
 export { createSegmentLoaderActor };