From 0cfd3bb395332b19cf85e9dc7eb08f656bec3e2b Mon Sep 17 00:00:00 2001
From: Christian Pillsbury <cpillsbury@mux.com>
Date: Tue, 5 May 2026 12:07:26 -0700
Subject: [PATCH] feat(spf): HLS engine composition walkthrough + doc-driven
 cleanups (#1512)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../templates/spf-segment-loading/main.ts     |  10 +-
 .../core/src/dom/media/simple-hls/index.ts    |   4 +-
 .../src/media/simple-hls-video/index.tsx      |  10 +-
 packages/spf/docs/explainer.md                | 303 ++++++++++++++
 packages/spf/docs/hls-engine.md               | 386 ++++++++++++++++++
 packages/spf/package.json                     |   8 +-
 packages/spf/src/CLAUDE.md                    |  77 ++++
 packages/spf/src/all.ts                       |  31 +-
 .../core/composition/create-composition.ts    |  56 +--
 .../tests/create-composition-types.test-d.ts  |  42 +-
 .../tests/create-composition-types.test.ts    |  28 +-
 packages/spf/src/core/tasks/task.ts           |   2 +-
 packages/spf/src/core/tsconfig.json           |  11 +
 packages/spf/src/core/utils/generate-id.ts    |  16 -
 packages/spf/src/dom.ts                       |  22 +
 .../src/dom/features/load-text-track-cues.ts  | 186 ---------
 packages/spf/src/dom/index.ts                 |  17 -
 packages/spf/src/dom/playback-engine/index.ts |   8 -
 packages/spf/src/dom/tsconfig.json            |  10 -
 packages/spf/src/index.ts                     |   2 +-
 .../media => media/dom/mse}/append-segment.ts |   0
 .../media => media/dom/mse}/buffer-flusher.ts |   0
 .../dom/mse}/mediasource-setup.ts             |  33 +-
 .../media => media/dom/mse}/mediasource.d.ts  |   0
 .../dom/mse}/tests/append-segment.test.ts     |   0
 .../dom/mse}/tests/buffer-flusher.test.ts     |   0
 .../dom/mse}/tests/mediasource-setup.test.ts  |   0
 .../dom/text/resolve-vtt-segment.ts}          |   4 +-
 .../cue-persistence-investigation.test.ts     |   0
 .../text/tests/resolve-vtt-segment.test.ts}   |  44 +-
 packages/spf/src/media/dom/tsconfig.json      |  11 +
 .../spf/src/media/hls/parse-multivariant.ts   |   2 +-
 .../{features => primitives}/select-tracks.ts | 115 +-----
 .../tests/select-tracks.test.ts               | 209 +---------
 packages/spf/src/media/tsconfig.json          |  12 +
 packages/spf/src/media/types/index.ts         |  56 ++-
 .../spf/src/media/types/tests/guards.test.ts  |  72 +++-
 .../spf/src/media/utils/track-selection.ts    |   8 +-
 .../network/chunked-stream-iterable.ts        |   0
 packages/spf/src/{dom => }/network/fetch.ts   |  28 +-
 .../tests/chunked-stream-iterable.test.ts     |   0
 .../src/{dom => }/network/tests/fetch.test.ts |  17 +-
 packages/spf/src/network/tsconfig.json        |  11 +
 .../actors/dom/segment-loader.ts}             |  19 +-
 .../actors/dom/source-buffer.ts}              |  10 +-
 .../actors/dom/tests/source-buffer.test.ts}   |   4 +-
 .../text-track-mode-cue-preservation.test.ts  |   0
 .../tests/text-track-segment-loader.test.ts}  |  53 +--
 .../actors/dom/tests/text-tracks.test.ts}     |   4 +-
 .../actors/dom/text-tracks.ts}                |  45 +-
 .../spf/src/playback/actors/dom/tsconfig.json |  18 +
 .../actors/text-track-segment-loader.ts}      |  40 +-
 .../spf/src/playback/actors/text-tracks.ts    |  33 ++
 .../spf/src/playback/actors/tsconfig.json     |  12 +
 .../calculate-presentation-duration.ts        |   8 +-
 .../behaviors/dom}/end-of-stream.ts           |  28 +-
 .../behaviors/dom}/load-segments.ts           |  24 +-
 .../behaviors/dom}/setup-mediasource.ts       |  29 +-
 .../behaviors/dom}/setup-sourcebuffer.ts      |  18 +-
 .../behaviors/dom/setup-text-track-actors.ts  |  80 ++++
 .../behaviors/dom}/sync-text-tracks.ts        |  12 +-
 .../end-of-stream-partial-resolution.test.ts} |   8 +-
 .../dom}/tests/end-of-stream.test.ts          |  43 +-
 .../tests/load-segments-track-switch.test.ts  |  18 +-
 .../dom}/tests/load-segments.test.ts          |   6 +-
 .../dom}/tests/load-text-track-cues.test.ts   | 132 +++---
 .../dom}/tests/setup-mediasource.test.ts      |  47 +--
 .../dom}/tests/setup-sourcebuffer.test.ts     |  20 +-
 .../dom}/tests/sync-text-tracks.test.ts       |   2 +-
 .../dom}/tests/track-current-time.test.ts     |   2 +-
 .../tests/track-playback-initiated.test.ts    |   4 +-
 .../dom}/tests/track-playback-rate.test.ts    |   2 +-
 .../dom}/tests/update-duration.test.ts        |  11 +-
 .../behaviors/dom}/track-current-time.ts      |   4 +-
 .../dom}/track-playback-initiated.ts          |   9 +-
 .../behaviors/dom}/track-playback-rate.ts     |   4 +-
 .../src/playback/behaviors/dom/tsconfig.json  |  20 +
 .../behaviors/dom}/update-duration.ts         |  21 +-
 .../behaviors/load-text-track-cues.ts         | 141 +++++++
 .../behaviors}/quality-switching.ts           |  12 +-
 .../behaviors}/resolve-presentation.ts        |  61 ++-
 .../behaviors}/resolve-track.ts               |  15 +-
 .../src/playback/behaviors/select-tracks.ts   | 114 ++++++
 .../behaviors}/sync-preload-attribute.ts      |   4 +-
 .../calculate-presentation-duration.test.ts   |   2 +-
 .../tests/quality-switching.test.ts           |   4 +-
 .../tests/resolve-presentation.test.ts        |  83 ++--
 .../behaviors}/tests/resolve-track.test.ts    |  12 +-
 .../behaviors/tests/select-tracks.test.ts     | 268 ++++++++++++
 .../tests/sync-preload-attribute.test.ts      |  26 +-
 .../spf/src/playback/behaviors/tsconfig.json  |  18 +
 .../engines/hls}/adapter.ts                   |  46 +--
 .../engines/hls/engine.ts}                    | 120 +++---
 .../spf/src/playback/engines/hls/index.ts     |   8 +
 .../engines/hls}/tests/adapter.test.ts        |  74 ++--
 .../engines/hls/tests/engine.test.ts}         |  52 +--
 .../src/playback/engines/hls/tsconfig.json    |  21 +
 packages/spf/tsdown.config.ts                 |   4 +-
 packages/spf/vitest.config.ts                 |  38 +-
 packages/utils/src/string/generate-id.ts      |  11 +
 packages/utils/src/string/index.ts            |   1 +
 .../src/string}/tests/generate-id.test.ts     |   0
 tsconfig.json                                 |  10 +-
 103 files changed, 2509 insertions(+), 1277 deletions(-)
 create mode 100644 packages/spf/docs/explainer.md
 create mode 100644 packages/spf/docs/hls-engine.md
 create mode 100644 packages/spf/src/CLAUDE.md
 create mode 100644 packages/spf/src/core/tsconfig.json
 delete mode 100644 packages/spf/src/core/utils/generate-id.ts
 create mode 100644 packages/spf/src/dom.ts
 delete mode 100644 packages/spf/src/dom/features/load-text-track-cues.ts
 delete mode 100644 packages/spf/src/dom/index.ts
 delete mode 100644 packages/spf/src/dom/playback-engine/index.ts
 delete mode 100644 packages/spf/src/dom/tsconfig.json
 rename packages/spf/src/{dom/media => media/dom/mse}/append-segment.ts (100%)
 rename packages/spf/src/{dom/media => media/dom/mse}/buffer-flusher.ts (100%)
 rename packages/spf/src/{dom/media => media/dom/mse}/mediasource-setup.ts (84%)
 rename packages/spf/src/{dom/media => media/dom/mse}/mediasource.d.ts (100%)
 rename packages/spf/src/{dom/media => media/dom/mse}/tests/append-segment.test.ts (100%)
 rename packages/spf/src/{dom/media => media/dom/mse}/tests/buffer-flusher.test.ts (100%)
 rename packages/spf/src/{dom/media => media/dom/mse}/tests/mediasource-setup.test.ts (100%)
 rename packages/spf/src/{dom/text/parse-vtt-segment.ts => media/dom/text/resolve-vtt-segment.ts} (93%)
 rename packages/spf/src/{ => media}/dom/text/tests/cue-persistence-investigation.test.ts (100%)
 rename packages/spf/src/{dom/text/tests/parse-vtt-segment.test.ts => media/dom/text/tests/resolve-vtt-segment.test.ts} (77%)
 create mode 100644 packages/spf/src/media/dom/tsconfig.json
 rename packages/spf/src/media/{features => primitives}/select-tracks.ts (71%)
 rename packages/spf/src/media/{features => primitives}/tests/select-tracks.test.ts (74%)
 create mode 100644 packages/spf/src/media/tsconfig.json
 rename packages/spf/src/{dom => }/network/chunked-stream-iterable.ts (100%)
 rename packages/spf/src/{dom => }/network/fetch.ts (82%)
 rename packages/spf/src/{dom => }/network/tests/chunked-stream-iterable.test.ts (100%)
 rename packages/spf/src/{dom => }/network/tests/fetch.test.ts (91%)
 create mode 100644 packages/spf/src/network/tsconfig.json
 rename packages/spf/src/{dom/features/segment-loader-actor.ts => playback/actors/dom/segment-loader.ts} (97%)
 rename packages/spf/src/{dom/media/source-buffer-actor.ts => playback/actors/dom/source-buffer.ts} (96%)
 rename packages/spf/src/{dom/media/tests/source-buffer-actor.test.ts => playback/actors/dom/tests/source-buffer.test.ts} (99%)
 rename packages/spf/src/{dom/features => playback/actors/dom}/tests/text-track-mode-cue-preservation.test.ts (100%)
 rename packages/spf/src/{dom/features/tests/text-track-segment-loader-actor.test.ts => playback/actors/dom/tests/text-track-segment-loader.test.ts} (80%)
 rename packages/spf/src/{dom/features/tests/text-tracks-actor.test.ts => playback/actors/dom/tests/text-tracks.test.ts} (98%)
 rename packages/spf/src/{dom/features/text-tracks-actor.ts => playback/actors/dom/text-tracks.ts} (59%)
 create mode 100644 packages/spf/src/playback/actors/dom/tsconfig.json
 rename packages/spf/src/{dom/features/text-track-segment-loader-actor.ts => playback/actors/text-track-segment-loader.ts} (60%)
 create mode 100644 packages/spf/src/playback/actors/text-tracks.ts
 create mode 100644 packages/spf/src/playback/actors/tsconfig.json
 rename packages/spf/src/{media/features => playback/behaviors}/calculate-presentation-duration.ts (91%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/end-of-stream.ts (92%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/load-segments.ts (94%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/setup-mediasource.ts (72%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/setup-sourcebuffer.ts (88%)
 create mode 100644 packages/spf/src/playback/behaviors/dom/setup-text-track-actors.ts
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/sync-text-tracks.ts (93%)
 rename packages/spf/src/{dom/tests/end-of-stream.test.ts => playback/behaviors/dom/tests/end-of-stream-partial-resolution.test.ts} (96%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/end-of-stream.test.ts (95%)
 rename packages/spf/src/{ => playback/behaviors}/dom/tests/load-segments-track-switch.test.ts (94%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/load-segments.test.ts (99%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/load-text-track-cues.test.ts (71%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/setup-mediasource.test.ts (70%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/setup-sourcebuffer.test.ts (92%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/sync-text-tracks.test.ts (99%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/track-current-time.test.ts (99%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/track-playback-initiated.test.ts (98%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/track-playback-rate.test.ts (98%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/tests/update-duration.test.ts (97%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/track-current-time.ts (94%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/track-playback-initiated.ts (92%)
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/track-playback-rate.ts (90%)
 create mode 100644 packages/spf/src/playback/behaviors/dom/tsconfig.json
 rename packages/spf/src/{dom/features => playback/behaviors/dom}/update-duration.ts (87%)
 create mode 100644 packages/spf/src/playback/behaviors/load-text-track-cues.ts
 rename packages/spf/src/{media/features => playback/behaviors}/quality-switching.ts (92%)
 rename packages/spf/src/{media/features => playback/behaviors}/resolve-presentation.ts (67%)
 rename packages/spf/src/{media/features => playback/behaviors}/resolve-track.ts (88%)
 create mode 100644 packages/spf/src/playback/behaviors/select-tracks.ts
 rename packages/spf/src/{media/features => playback/behaviors}/sync-preload-attribute.ts (89%)
 rename packages/spf/src/{media/features => playback/behaviors}/tests/calculate-presentation-duration.test.ts (99%)
 rename packages/spf/src/{media/features => playback/behaviors}/tests/quality-switching.test.ts (99%)
 rename packages/spf/src/{media/features => playback/behaviors}/tests/resolve-presentation.test.ts (85%)
 rename packages/spf/src/{media/features => playback/behaviors}/tests/resolve-track.test.ts (97%)
 create mode 100644 packages/spf/src/playback/behaviors/tests/select-tracks.test.ts
 rename packages/spf/src/{media/features => playback/behaviors}/tests/sync-preload-attribute.test.ts (80%)
 create mode 100644 packages/spf/src/playback/behaviors/tsconfig.json
 rename packages/spf/src/{dom/playback-engine => playback/engines/hls}/adapter.ts (79%)
 rename packages/spf/src/{dom/playback-engine/hls-engine.ts => playback/engines/hls/engine.ts} (59%)
 create mode 100644 packages/spf/src/playback/engines/hls/index.ts
 rename packages/spf/src/{dom/playback-engine => playback/engines/hls}/tests/adapter.test.ts (87%)
 rename packages/spf/src/{dom/tests/playback-engine.test.ts => playback/engines/hls/tests/engine.test.ts} (97%)
 create mode 100644 packages/spf/src/playback/engines/hls/tsconfig.json
 create mode 100644 packages/utils/src/string/generate-id.ts
 rename packages/{spf/src/core/utils => utils/src/string}/tests/generate-id.test.ts (100%)

diff --git a/apps/sandbox/templates/spf-segment-loading/main.ts b/apps/sandbox/templates/spf-segment-loading/main.ts
index 38560192..938d6b5e 100644
--- a/apps/sandbox/templates/spf-segment-loading/main.ts
+++ b/apps/sandbox/templates/spf-segment-loading/main.ts
@@ -9,8 +9,8 @@ import '@app/styles.css';
 //   preload=auto|metadata|none  Initial preload mode
 
 import { effect } from '@videojs/spf';
-import type { HlsPlaybackEngineState } from '@videojs/spf/playback-engine';
-import { createHlsPlaybackEngine } from '@videojs/spf/playback-engine';
+import type { SimpleHlsEngineState } from '@videojs/spf/hls';
+import { createSimpleHlsEngine } from '@videojs/spf/hls';
 
 // ── DOM refs ──────────────────────────────────────────────────────────────────
 const video = document.getElementById('video') as HTMLVideoElement;
@@ -58,7 +58,7 @@ function formatBandwidth(bps: number): string {
   return `${Math.round(bps / 1000)} Kbps`;
 }
 
-function getVideoTracks(state: HlsPlaybackEngineState) {
+function getVideoTracks(state: SimpleHlsEngineState) {
   return state.presentation?.selectionSets?.find((s) => s.type === 'video')?.switchingSets[0]?.tracks ?? [];
 }
 
@@ -265,14 +265,14 @@ function inspectState() {
 log('=== SPF Segment Loading POC Test ===');
 log(`Stream: ${INITIAL_SRC}`);
 
-let engine: ReturnType<typeof createHlsPlaybackEngine>;
+let engine: ReturnType<typeof createSimpleHlsEngine>;
 let cleanupEffects: () => void = () => {};
 
 function startEngine(src: string) {
   cleanupEffects();
   if (engine) engine.destroy();
 
-  engine = createHlsPlaybackEngine({ initialBandwidth: 1_000_000 });
+  engine = createSimpleHlsEngine({ initialBandwidth: 1_000_000 });
   (window as any).engine = engine;
   (window as any).state = () => engine.state.get();
   (window as any).owners = () => engine.owners.get();
diff --git a/packages/core/src/dom/media/simple-hls/index.ts b/packages/core/src/dom/media/simple-hls/index.ts
index 4f69276f..8ca5afe2 100644
--- a/packages/core/src/dom/media/simple-hls/index.ts
+++ b/packages/core/src/dom/media/simple-hls/index.ts
@@ -1,4 +1,4 @@
-import { SpfMediaMixin } from '@videojs/spf/dom';
+import { SimpleHlsMediaMixin } from '@videojs/spf/hls';
 import { HTMLVideoElementHost } from '../video-host';
 
-export class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+export class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}
diff --git a/packages/react/src/media/simple-hls-video/index.tsx b/packages/react/src/media/simple-hls-video/index.tsx
index 732492cf..94a87a69 100644
--- a/packages/react/src/media/simple-hls-video/index.tsx
+++ b/packages/react/src/media/simple-hls-video/index.tsx
@@ -1,8 +1,8 @@
 'use client';
 
 import { SimpleHlsMedia } from '@videojs/core/dom/media/simple-hls';
-import type { SpfMediaProps } from '@videojs/spf/dom';
-import { spfMediaDefaultProps } from '@videojs/spf/dom';
+import type { SimpleHlsMediaProps } from '@videojs/spf/hls';
+import { simpleHlsMediaDefaultProps } from '@videojs/spf/hls';
 import type { ReactNode, VideoHTMLAttributes } from 'react';
 import { forwardRef } from 'react';
 import { useAttachMedia } from '../../utils/use-attach-media';
@@ -11,8 +11,8 @@ import { useMediaInstance } from '../../utils/use-media-instance';
 import { useSyncProps } from '../../utils/use-sync-props';
 
 export interface SimpleHlsVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof SpfMediaProps>,
-    Partial<SpfMediaProps> {
+  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof SimpleHlsMediaProps>,
+    Partial<SimpleHlsMediaProps> {
   children?: ReactNode;
 }
 
@@ -23,7 +23,7 @@ export const SimpleHlsVideo = forwardRef<HTMLVideoElement, SimpleHlsVideoProps>(
   const media = useMediaInstance(SimpleHlsMedia);
   const attachRef = useAttachMedia(media);
   const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, spfMediaDefaultProps);
+  const htmlProps = useSyncProps(media, props, simpleHlsMediaDefaultProps);
 
   return (
     <video ref={composedRef} {...htmlProps}>
diff --git a/packages/spf/docs/explainer.md b/packages/spf/docs/explainer.md
new file mode 100644
index 00000000..61426d70
--- /dev/null
+++ b/packages/spf/docs/explainer.md
@@ -0,0 +1,303 @@
+# SPF — Stream Processing Framework
+
+SPF is a general-purpose framework for building streaming playback engines. It provides a small set of composable primitives — reactive state, actors, reactors, and tasks — that let you assemble a playback engine from independent, decoupled features.
+
+SPF keeps its opinions as localized as possible. The framework doesn't know about HLS, DASH, or any specific protocol. It provides the composition model; you provide the features.
+
+---
+
+## The Engine
+
+A playback engine is a composition of **features** — functions that each handle one concern (manifest resolution, segment loading, ABR, etc.). The engine wires them together with shared reactive state and runs them.
+
+```ts
+import { createPlaybackEngine } from '@videojs/spf';
+
+const engine = createPlaybackEngine([
+  resolvePresentation,
+  selectVideoTrack,
+  loadVideoSegments,
+  endOfStream,
+]);
+```
+
+`createPlaybackEngine` is generic. It:
+
+1. Creates shared **state** and **owners** signals
+2. Passes them (along with **config**) to each feature
+3. Returns the engine interface: `{ state, owners, destroy() }`
+
+```ts
+function createPlaybackEngine(
+  features: Feature[],
+  options?: {
+    config?: C;
+    initialState?: S;
+    initialOwners?: O;
+  }
+): PlaybackEngine;
+```
+
+All options are optional. The simplest engine is just `createPlaybackEngine([myFeature])`.
+
+### State, Owners, and Config
+
+An engine has three shared channels:
+
+| Channel | What it holds | Lifecycle |
+|---------|--------------|-----------|
+| **state** | Application state (selected tracks, bandwidth estimates, current time, etc.) | Reactive signal — read and written throughout the engine's lifetime |
+| **owners** | Platform objects (media elements, SourceBuffers, actors) | Reactive signal — populated by features as resources are created |
+| **config** | Static configuration (initial bandwidth, preferred languages, etc.) | Passed once at creation — not reactive |
+
+None of these have a fixed shape. Their types are determined by the features in the composition — each feature declares what state, owners, and config fields it needs, and the engine's types are the intersection of those requirements.
+
+### Features
+
+A feature is a function that receives `{ state, owners, config }` and optionally returns a cleanup handle:
+
+```ts
+type Feature = (deps: { state, owners, config }) => void | (() => void) | { destroy(): void };
+```
+
+Features are independent. They don't know about each other — they communicate through shared state. A feature might:
+
+- Observe state changes and react (a **reactor**)
+- Own a stateful worker that processes messages (an **actor**)
+- Run a one-time side effect on setup
+- Do nothing but return a cleanup function
+
+The engine doesn't care which. It calls the feature, collects any cleanup, and moves on.
+
+---
+
+## An HLS Engine
+
+An HLS playback engine is one specific composition of features. There's nothing special about it from SPF's perspective — it's just a list of features and some config.
+
+```ts
+import { createPlaybackEngine } from '@videojs/spf';
+
+function createSimpleHlsEngine(config = {}) {
+  return createPlaybackEngine(
+    [
+      // Preload and playback tracking
+      syncPreloadAttribute,
+      trackPlaybackInitiated,
+
+      // Manifest resolution
+      resolvePresentation,
+
+      // Track selection (reads config for initial preferences)
+      selectVideoTrackFromConfig,
+      selectAudioTrackFromConfig,
+      selectTextTrackFromConfig,
+
+      // Resolve selected tracks (fetch media playlists)
+      resolveVideoTrack,
+      resolveAudioTrack,
+      resolveTextTrack,
+
+      // Presentation duration
+      calculatePresentationDuration,
+
+      // MSE setup
+      setupMediaSource,
+      updateDuration,
+      setupSourceBuffers,
+
+      // Playback tracking and ABR
+      trackCurrentTime,
+      switchQualityFromConfig,
+
+      // Segment loading
+      loadVideoSegments,
+      loadAudioSegments,
+
+      // End of stream coordination
+      endOfStream,
+
+      // Text tracks
+      syncTextTracks,
+      loadTextTrackCues,
+    ],
+    { config, initialState: { bandwidthState: initialBandwidthState() } }
+  );
+}
+```
+
+Reading top to bottom, the engine tells a story: resolve a manifest, pick tracks, set up MSE, load segments, coordinate end-of-stream. Each line is a feature. To build a different engine — fewer features, different features, different protocol — you change the list.
+
+### Config threading
+
+Features that need configuration read it from `deps.config`. The engine passes config to every feature; each one destructures what it needs:
+
+```ts
+// A feature that reads config
+const selectVideoTrackFromConfig = ({ config, ...deps }) =>
+  selectVideoTrack(deps, {
+    type: 'video',
+    ...(config.initialBandwidth !== undefined && { initialBandwidth: config.initialBandwidth }),
+  });
+
+// A feature that doesn't need config — just ignores it
+function resolvePresentation({ state }) {
+  // ...
+}
+```
+
+### Media-type wrappers
+
+Some features are parameterized by media type (video, audio, text). Rather than passing `{ type: 'video' }` as inline config, we define thin wrappers that close over the type:
+
+```ts
+const loadVideoSegments = (deps) => loadSegments(deps, { type: 'video' });
+const loadAudioSegments = (deps) => loadSegments(deps, { type: 'audio' });
+```
+
+This keeps the engine composition readable — a flat list of named features.
+
+---
+
+## The Three Layers
+
+Features are built from three layers of primitives. Data flows in one direction:
+
+```
+  Reactive State (signals)
+      │ observed by
+      ▼
+  Reactors (thin subscribers)
+      │ send messages to
+      ▼
+  Actors (stateful workers)
+      │ execute
+      ▼
+  Tasks (async work units)
+```
+
+### Reactive State — Signals
+
+All shared state in SPF is built on [TC39 Signals](https://github.com/tc39/proposal-signals). A signal is a reactive value: it always has a current reading, and computations that read it are automatically notified when it changes.
+
+```ts
+import { signal, computed, effect } from '@videojs/spf';
+
+const count = signal(0);
+const doubled = computed(() => count.get() * 2);
+
+effect(() => {
+  console.log(doubled.get()); // re-runs when count changes
+});
+
+count.set(5); // logs: 10
+```
+
+SPF chose signals over observables because all SPF state is **state-over-time** — current track, buffer contents, bandwidth estimate. These are naturally modeled as "a value that changes" rather than "a stream of events." Signals give you automatic dependency tracking for derived state, synchronous reads, and a lower barrier to entry than observable pipelines.
+
+### Reactors
+
+A reactor observes reactive state and responds to changes. It has its own finite state machine and can run per-state effects. Reactors don't receive messages — they're driven entirely by signal observation.
+
+```ts
+const reactor = createMachineReactor({
+  initial: 'preconditions-unmet',
+  monitor: () => canResolve(state.get()) ? 'resolving' : 'preconditions-unmet',
+  states: {
+    'preconditions-unmet': {},
+    resolving: {
+      entry: () => {
+        // Run once on state entry (automatically untracked)
+        const ac = new AbortController();
+        fetchAndParse(state, ac.signal);
+        return ac; // cleanup on state exit
+      },
+    },
+  },
+});
+```
+
+Key concepts:
+- **`monitor`** — derives the target state from signals. The framework drives the transition.
+- **`entry`** — runs once on state entry, automatically untracked. Return a cleanup.
+- **`effects`** — re-run when tracked signals change. For reactive sync.
+
+### Actors
+
+An actor is a long-lived stateful worker that processes messages serially. It owns a reactive snapshot (status + context) and uses tasks and runners to execute work.
+
+```ts
+const actor = createMachineActor({
+  runner: () => new SerialRunner(),
+  initial: 'idle',
+  context: { segments: [], initTrackId: undefined },
+  states: {
+    idle: {
+      on: {
+        'append-segment': (msg, { transition, runner, setContext }) => {
+          transition('updating');
+          const task = makeAppendTask(msg);
+          runner.schedule(task).then(setContext);
+        },
+      },
+    },
+    updating: {
+      onSettled: 'idle', // auto-return when runner settles
+    },
+  },
+});
+```
+
+Key concepts:
+- **`send(message)`** — the only way to communicate with an actor
+- **`snapshot`** — reactive read-only state, observable by reactors and other consumers
+- **`runner`** — schedules and executes tasks (serial, concurrent, etc.)
+- **`onSettled`** — automatic transition when all tasks complete
+
+### How they connect
+
+A reactor observes state, decides something needs to happen, and sends a message to an actor. The actor does the work and updates its snapshot. Other reactors (or the engine) observe the actor's snapshot and react.
+
+```
+state changes → reactor observes → actor.send({ type: 'load', track })
+                                        ↓
+                                   actor executes tasks
+                                        ↓
+                                   actor.snapshot updates
+                                        ↓
+                              other reactors observe snapshot
+```
+
+This separation means:
+- **Actors don't know about external state.** They receive messages and produce state changes.
+- **Reactors don't do work.** They observe and coordinate.
+- **State is the single source of truth.** Features communicate through it, not through each other.
+
+---
+
+## Tasks
+
+A task is an ephemeral unit of async work with lifecycle tracking. Unlike a Promise, a task:
+
+- Starts in a **pending** state before it runs — it can be inspected, queued, or aborted before any work begins
+- Can be **aborted** from outside at any point
+- Exposes its **status synchronously** (`pending`, `running`, `done`, `error`)
+- Carries a typed **value** and **error**, readable once settled
+
+Tasks are the unit of work inside actors. They're not exposed externally — actors plan and execute tasks, and the task's status may or may not surface in the actor's snapshot.
+
+**Task runners** control scheduling:
+- **SerialRunner** — one task at a time (used for SourceBuffer operations, which are inherently serial)
+- **ConcurrentRunner** — parallel with deduplication by ID
+
+---
+
+## Open Questions
+
+> These are areas where the design direction is clear but implementation details are still being worked through.
+
+- **`presentation?: any`** — The engine-level state type uses `any` for the presentation field because it transitions from unresolved (`{ url }`) to resolved (`Presentation`) at runtime. Individual features narrow the type themselves. Signal invariance prevents using a union type here. A cleaner pattern is needed.
+- **Feature state interfaces and Signal invariance** — More broadly, how should features declare their state requirements given that `Signal<T>` is invariant? The current pattern (features use generic constraints, engine state uses `any` where types conflict) works but has rough edges.
+- **Task `aborted` as a distinct terminal state** — Currently abort lands in `error`. Should be first-class: `pending → running → done | error | aborted`.
+- **Effect scheduling semantics** — Effects are deferred via `queueMicrotask`. The exact behavior under compound state changes (multiple signal writes in one turn) is behavioral, not formally specified.
+- **Reactor lifecycle ownership** — Currently the engine explicitly creates and destroys everything. With signals, reactors could self-scope to a reactive context and auto-dispose.
diff --git a/packages/spf/docs/hls-engine.md b/packages/spf/docs/hls-engine.md
new file mode 100644
index 00000000..494b4a88
--- /dev/null
+++ b/packages/spf/docs/hls-engine.md
@@ -0,0 +1,386 @@
+# The HLS Engine
+
+A reference walkthrough of how SPF composes a playback engine.
+
+The HLS engine in `@videojs/spf/hls` is one specific composition — manifest resolution, track selection, MSE setup, segment loading, end-of-stream — but the patterns it uses are how any SPF playback engine is built. This doc walks the composition stage-by-stage and calls out the patterns that recur.
+
+It assumes familiarity with HLS, MSE, and adaptive streaming. If you want to learn what a "switching set" is, look elsewhere. If you want to learn how SPF lets you turn those concepts into a composable, declarative engine, you're in the right place.
+
+For SPF primitives (signals, reactors, tasks, actors), see [fundamentals.md](./fundamentals.md).
+
+---
+
+## The engine at a glance
+
+`createSimpleHlsEngine` is a thin wrapper around `createComposition`. The full composition, lifted from `src/playback/engines/hls/engine.ts`:
+
+```ts
+export function createSimpleHlsEngine(
+  config: SimpleHlsEngineConfig = {}
+): Composition<SimpleHlsEngineState, SimpleHlsEngineOwners> {
+  return createComposition(
+    [
+      syncPreloadAttribute,
+      trackPlaybackInitiated,
+      resolvePresentation,
+
+      // Track selection (reads config for initial preferences)
+      selectVideoTrack,
+      selectAudioTrack,
+      selectTextTrack,
+
+      // Resolve selected tracks (fetch media playlists)
+      resolveVideoTrack,
+      resolveAudioTrack,
+      resolveTextTrack,
+
+      // Presentation duration
+      calculatePresentationDuration,
+
+      // MSE setup
+      setupMediaSource,
+      updateDuration,
+      setupSourceBuffers,
+
+      // Playback tracking
+      trackCurrentTime,
+      switchQuality,
+
+      // Segment loading
+      loadVideoSegments,
+      loadAudioSegments,
+
+      // End of stream coordination
+      endOfStream,
+
+      // Text tracks
+      syncTextTracks,
+      setupTextTrackActors,
+      loadTextTrackCues,
+    ],
+    { config, initialState, initialOwners }
+  );
+}
+```
+
+Read top to bottom, the engine tells a story: resolve a manifest, pick tracks, set up MSE, load segments, coordinate end-of-stream, render text tracks. Each line is a behavior — a small, focused unit of logic that owns one job. To build a different engine — fewer behaviors, different protocol, different platform — you change the list.
+
+Three things are doing the work here:
+
+1. **`createComposition`** — the SPF primitive that wires the behaviors together. It owns the lifecycle and gives each behavior access to two shared reactive channels — `state` and `owners` — plus the engine's static `config`.
+2. **The behaviors** — independent functions, each declaring its slice of the state and owners shapes and its job.
+3. **The engine wrapper** — a few small helpers that adapt behaviors to the engine's specific needs (closing over media types, threading config). Nothing structural; just glue.
+
+The rest of this doc walks each stage.
+
+---
+
+## State, owners, and config
+
+Every SPF composition is parameterized by three shapes:
+
+```ts
+export interface SimpleHlsEngineState {
+  /**
+   * The presentation being played. A caller writes `{ url }`;
+   * `resolvePresentation` parses the manifest and populates the rest.
+   */
+  presentation?: MaybeResolvedPresentation;
+  preload?: 'auto' | 'metadata' | 'none';
+  selectedVideoTrackId?: string;
+  selectedAudioTrackId?: string;
+  selectedTextTrackId?: string;
+  bandwidthState?: BandwidthState;
+  abrDisabled?: boolean;
+  currentTime?: number;
+  playbackInitiated?: boolean;
+  mediaSourceReadyState?: MediaSource['readyState'];
+}
+
+export interface SimpleHlsEngineOwners {
+  mediaElement?: HTMLMediaElement;
+  mediaSource?: MediaSource;
+  videoBuffer?: SourceBuffer;
+  audioBuffer?: SourceBuffer;
+  videoBufferActor?: SourceBufferActor;
+  audioBufferActor?: SourceBufferActor;
+  textTracksActor?: TextTracksActor;
+  segmentLoaderActor?: TextTrackSegmentLoaderActor;
+}
+
+export interface SimpleHlsEngineConfig {
+  initialBandwidth?: number;
+  preferredAudioLanguage?: string;
+  preferredSubtitleLanguage?: string;
+  includeForcedTracks?: boolean;
+  enableDefaultTrack?: boolean;
+}
+```
+
+The split:
+
+- **State** holds reactive playback data — the manifest, selected track ids, current time, bandwidth estimate. It flows through the composition over time. Each field is a slot in the state signal that any behavior can read or write.
+- **Owners** holds **resources** — values with identity and imperative interfaces, not just data. The `<video>` element, the `MediaSource`, source buffers, the actors managing text-track lifecycles. If you'd pass the thing around by reference and call methods on it, it belongs in owners. Behaviors observe and act on resources directly; the signal makes their lifecycle (appearance, replacement, removal) reactive.
+- **Config** holds static creation-time options — thresholds, language preferences, feature flags. It doesn't change during the engine's lifetime. Behaviors read it directly, usually with a fallback.
+
+The shapes are unions of what every behavior in the composition needs. Adding a new behavior that requires a new state field means adding it to the engine's state interface. Removing a behavior is the inverse.
+
+Each behavior receives `{ state, owners, config }` and reads or writes only the slots it cares about. Nothing else. A behavior that only reads `mediaElement` doesn't know about `bandwidthState` and can't accidentally interact with it. (The HLS engine's source aliases this argument shape as `Deps` for brevity in the wrapper helpers — it's a local convenience, not framework vocabulary.)
+
+---
+
+## Stage 1 — Initial state and manifest resolution
+
+The first three entries are the lead-in:
+
+```ts
+syncPreloadAttribute,
+trackPlaybackInitiated,
+resolvePresentation,
+```
+
+**`syncPreloadAttribute`** mirrors the `<video preload>` attribute into `state.preload`. This makes the preload mode reactive — anything downstream that wants to react to preload changes (for example, "should we eagerly fetch the manifest?") can subscribe to a signal instead of polling the DOM.
+
+**`trackPlaybackInitiated`** sets `state.playbackInitiated` to `true` once the user has tried to play (the element is no longer paused). It's a small reactor that watches the media element's `play`/`pause` events. Why it matters: behaviors that should only run after the user interacts (or after autoplay fires) can gate on `state.playbackInitiated`.
+
+**`resolvePresentation`** is the first behavior that does real network work. It watches `state.presentation` and, when it sees an unresolved value (`{ url }` with no `id`), fetches the multivariant playlist, parses it, and writes the resolved `Presentation` back to the same slot. The lifecycle lives in one slot: a caller writes `{ url }`, the resolver replaces it with a fully populated `Presentation`. Behaviors that only need the URL read `presentation.url`; behaviors that need resolved fields use `isResolvedPresentation` (or check for `selectionSets`) to narrow.
+
+A pattern shows up here that recurs throughout: **behaviors gate themselves on preconditions and write their results back to state.** They don't take inputs as function arguments. They read from a known signal slot, do their work, and write to a known signal slot. The composition is wired through state, not through call ordering.
+
+---
+
+## Stage 2 — Track selection
+
+Once the manifest is resolved, the engine picks one track per type:
+
+```ts
+selectVideoTrack,
+selectAudioTrack,
+selectTextTrack,
+```
+
+These are *wrappers* defined in `engine.ts` that share their names with — and close over — the imported behaviors from `playback/behaviors/select-tracks.ts`. The imported behaviors accept their own configuration parameter (initial bandwidth for video, preferred language for audio, and so on); the wrapper closes over the engine's config and threads the relevant fields into the behavior:
+
+```ts
+import { selectVideoTrack as _selectVideoTrack } from '../../behaviors/select-tracks';
+
+const selectVideoTrack = ({ config, ...deps }: Deps) =>
+  _selectVideoTrack(deps, {
+    type: 'video',
+    ...(config.initialBandwidth !== undefined && { initialBandwidth: config.initialBandwidth }),
+  });
+```
+
+The wrapper takes the natural name; the imported behavior gets a leading-underscore alias for local use. The composition list reads as a flat list of behaviors at the right level of abstraction — the wrappers vanish into anonymity, which is exactly right since they're just adapter glue.
+
+This is the **wrapper pattern** that recurs throughout the engine. Two kinds, both visible in the composition list:
+
+- **Media-type wrappers** (`loadVideoSegments`, `resolveVideoTrack`, …) close over a fixed `type: 'video' | 'audio' | 'text'` value. Their underlying behavior takes the type as config; the wrapper makes it concrete.
+- **Config-aware wrappers** (`selectVideoTrack`, `switchQuality`, the engine-local versions) close over the engine's config and pass relevant fields to the underlying behavior's own config parameter.
+
+The wrappers exist because the underlying behaviors are **engine-agnostic** — `_selectVideoTrack` doesn't know about `SimpleHlsEngineConfig` or that `bandwidthState` lives on engine state. It accepts a `VideoSelectionConfig` from its caller. The engine wrapper is the thin layer that says "for this engine's config, the initial bandwidth comes from `config.initialBandwidth`."
+
+The behaviors themselves are split across two locations on purpose:
+
+- **Pure logic** lives in `media/primitives/select-tracks.ts` — `pickVideoTrack`, `pickAudioTrack`, `pickTextTrack`, `canSelectTrack`, `shouldSelectTrack`. No signals, no effects. Just functions that take a `Presentation` and a config and return an id.
+- **Orchestrations** live in `playback/behaviors/select-tracks.ts` — `selectVideoTrack`, `selectAudioTrack`, `selectTextTrack`. These wrap the pure logic in `effect()`, gate on preconditions, and write the chosen id to `state.selected{Video,Audio,Text}TrackId`.
+
+The split keeps the SPF-free CML-style helpers reusable outside SPF, while the SPF-integrated behaviors stay thin and easy to swap.
+
+---
+
+## Stage 3 — Track resolution
+
+A selected track is just an id at first — its segment list still has to come from a *media playlist*. The next three behaviors fetch and parse those:
+
+```ts
+resolveVideoTrack,
+resolveAudioTrack,
+resolveTextTrack,
+```
+
+These are media-type wrappers around the same `resolveTrack` behavior:
+
+```ts
+const resolveVideoTrack = (deps: Deps) => resolveTrack(deps, { type: 'video' as const });
+```
+
+`resolveTrack` watches `state.presentation` and the matching `selectedXTrackId` for its type. When both are set, it finds the partially-resolved track, fetches its media playlist, parses it into segments, and writes the now-resolved track back into `state.presentation`. (The `Presentation` type allows tracks to hold either a partially-resolved or fully-resolved shape — the URL is enough to find a track; the segments are what loadSegments needs.)
+
+Three behaviors, one shared `resolveTrack`. Each closes over its `type` so the composition list stays flat. From outside, you'd hardly know they share an implementation.
+
+Now `state.presentation` is fully populated for the selected tracks. Everything downstream — duration, MSE, segment loading, end-of-stream — reads from there.
+
+---
+
+## Stage 4 — Presentation duration
+
+```ts
+calculatePresentationDuration,
+```
+
+`calculatePresentationDuration` reads the resolved tracks and computes the presentation's total duration (max of selected track durations). It writes the result back to `state.presentation.duration`. This is a small bookkeeping behavior — the duration is derived from data already in state — but breaking it out keeps the derivation reactive: any downstream behavior that needs to know the duration just reads `state.presentation.duration`, and re-runs when it changes.
+
+It's separated from `resolveTrack` because the duration depends on *which* tracks are selected (the engine could change selection later, in theory, with a different duration). Keeping the derivation in its own behavior means every track-selection change automatically re-derives.
+
+---
+
+## Stage 5 — MSE setup
+
+The next three behaviors stand up the MSE pipeline:
+
+```ts
+setupMediaSource,
+updateDuration,
+setupSourceBuffers,
+```
+
+This is where the engine first touches the media element directly. Up until now, behaviors have been operating on plain data in `state` — manifests, URLs, ids, durations. MSE is the bridge: a `MediaSource` attaches to the `<video>` element via `srcObject` (or an object URL), and `SourceBuffer`s under it accept appended segments.
+
+**`setupMediaSource`** waits for two preconditions: a `mediaElement` in owners and a `presentation.url` in state. When both arrive, it creates a `MediaSource`, attaches it to the element, and writes both back to owners (`mediaSource`) and state (`mediaSourceReadyState`). The DOM event for "MediaSource is open" is bridged onto `state.mediaSourceReadyState` via the `onMediaSourceReadyStateChange` callback primitive — once that flips to `'open'`, the `mediaSource` is published to owners so downstream behaviors can use it.
+
+The split between owners and state is deliberate. The MediaSource itself is a resource — you call `addSourceBuffer()` on it, you set its `duration` — so it lives in owners. Its readyState is data — a string that other behaviors gate decisions on — so it lives in state. The DOM events that drive readyState changes get bridged into the SPF signal graph by the small primitive in `media/dom/mse/`, keeping `setupMediaSource` clean.
+
+**`updateDuration`** waits for the resolved presentation duration (from stage 4) and a MediaSource that's open with idle source buffers, then writes `mediaSource.duration = presentation.duration`. The order matters: setting duration while a SourceBuffer has `updating === true` throws `InvalidStateError`, so the behavior waits for any in-flight appends to settle before writing.
+
+This is the first place the engine has real coordination concerns: timing among multiple resources. The behavior expresses it declaratively — `effect()` re-runs when any input signal changes, and the gate function checks every precondition. There's no manual sequencing, no callbacks-on-callbacks. Each precondition becomes a signal read; the framework figures out when to fire.
+
+**`setupSourceBuffers`** does the same lifecycle dance as `setupMediaSource`, but per-track: when a video or audio track is resolved and the MediaSource is open, it calls `addSourceBuffer()` with the track's mime/codec, wraps the resulting `SourceBuffer` in a `SourceBufferActor`, and publishes both the raw buffer and the actor onto owners.
+
+The actor wrapping is worth pausing on. A raw `SourceBuffer` is imperative: you call `appendBuffer(data)`, you wait for the `updateend` event, you handle errors. Multiple appends can collide. An actor — a state machine that owns the buffer — gives every consumer a single point of contact. They send a message ("append this segment"); the actor serializes the work, exposes its current state via a snapshot signal, and behaves predictably even when several behaviors want to write at once.
+
+So owners ends up with both `videoBuffer` (the raw `SourceBuffer`, used by `endOfStream` to read `buffered` ranges) and `videoBufferActor` (the wrapper, used by `loadSegments` to send append messages). Same lifetime, two roles.
+
+---
+
+## Stage 6 — Playback tracking and ABR
+
+Once buffers are live and segments can be appended, the engine starts watching playback:
+
+```ts
+trackCurrentTime,
+switchQuality,
+```
+
+**`trackCurrentTime`** mirrors the media element's `currentTime` onto `state.currentTime`. Same shape as `syncPreloadAttribute` from stage 1: the DOM event becomes a signal write, and downstream behaviors gate on the reactive value rather than polling the element. `loadSegments` reads it to know how far ahead to fetch; `endOfStream` reads it to know whether the user has reached the end.
+
+**`switchQuality`** is the ABR loop. It watches `state.bandwidthState` (a running estimate, written by `loadSegments` after each successful segment fetch) and `state.selectedVideoTrackId`. When the estimate moves enough to justify a switch, it writes a different `selectedVideoTrackId`. That triggers `resolveVideoTrack` → `setupSourceBuffers` (if mime/codec changes) → `loadSegments` to start fetching from the new variant. (Like the track-selection wrappers, this is the engine's local version that closes over engine config; the underlying behavior is imported as `_switchQuality`.)
+
+Two patterns worth pausing on:
+
+- **State is the bus.** The bandwidth estimator doesn't push to the quality switcher. The quality switcher doesn't pull from the loader. Both read `state.bandwidthState` and respond. Adding a third behavior that needs the estimate (a buffer-health probe, a telemetry stream) is the same: another reader, no rewiring.
+- **Selection cascades.** Changing `selectedVideoTrackId` doesn't tell anything to "re-resolve, re-buffer, re-load." It just changes the value. The behaviors downstream were already reading it; they'll re-run because `effect()` tracked their reads. Re-resolution and re-buffering happen because the framework noticed.
+
+The engine has no orchestrator. Each behavior is a small reactor plus a cleanup. The composition is the dataflow.
+
+---
+
+## Stage 7 — Segment loading
+
+```ts
+loadVideoSegments,
+loadAudioSegments,
+```
+
+Two media-type wrappers around `loadSegments`. This is the busiest behavior — the one that actually fetches segments, samples bandwidth, and pushes data into the source buffers.
+
+`loadSegments` watches:
+- `state.presentation` — for the resolved track of its type
+- `state.selectedVideoTrackId` (or audio) — to know which track's segments to load
+- `state.currentTime` — to know how far ahead to fetch
+- `state.bandwidthState` — to keep a running estimate after each fetch
+- `owners.videoBufferActor` (or audio) — to send append messages
+- `owners.mediaSource` — to know it's safe to operate on the buffer
+
+When the preconditions are met, the behavior:
+
+1. **Plans** which segments to fetch using a forward-buffer policy (look ahead from currentTime by some target buffer length, find segments whose ranges aren't already buffered). The planner is a pure function from `media/buffer/forward-buffer.ts` — given the segments, the buffered ranges, and currentTime, return the list of segments to fetch.
+2. **Fetches and appends** each segment via the network layer, sampling timing to update `state.bandwidthState`. The `SourceBufferActor` receives `append` messages and serializes them; multiple in-flight calls don't collide.
+3. **Records** segment metadata (id, byte size, timestamp) into the actor's context so `endOfStream` later knows the last segment is loaded.
+
+The pure planner from `media/buffer/` is the same kind of split we saw in track selection: framework-free logic that takes data and returns data, lifted out of the orchestration. The behavior wraps it in `effect()`, gates on preconditions, and pushes the results to the actor.
+
+A subtle bit: `loadSegments` doesn't await the actor's append messages serially in JS — it sends them and lets the actor own ordering. The actor's `SerialRunner` ensures `appendBuffer` calls happen one at a time on the underlying `SourceBuffer`, which is what the MSE spec requires. The behavior just sends.
+
+---
+
+## Stage 8 — End of stream
+
+```ts
+endOfStream,
+```
+
+A single behavior, but one that has to coordinate across the rest of the pipeline. Calling `MediaSource.endOfStream()` tells the browser the stream is done — without it, playback stalls at the end of the buffered range waiting for data that will never arrive. Calling it too early (or while a SourceBuffer is updating) causes errors that crash the demuxer.
+
+`endOfStream` reads:
+- `state.presentation` and `state.selected{Video,Audio}TrackId` — to know which tracks' last segments to wait for
+- `state.mediaSourceReadyState` — must be `'open'` (not `'ended'` or `'closed'`)
+- `owners.mediaElement` — to check `readyState >= HAVE_METADATA` (a precondition Chrome enforces)
+- `owners.{video,audio}Buffer` — must exist for selected tracks
+- `owners.{video,audio}BufferActor` — to know if any are still updating
+- `owners.{video,audio}BufferActor.snapshot.context.segments` — to verify the last segment of each selected track has been appended
+
+Every one of those reads happens inside an `effect()`. When *any* changes, the gate function reruns. When all preconditions line up, the behavior calls `mediaSource.endOfStream()`.
+
+Two things this behavior makes visible about SPF compositions:
+
+- **Coordination is just reading.** No callbacks, no publish/subscribe, no event bus. The behavior reads from state and owners; the reactive graph re-runs it whenever any read changes. A composition with N behaviors and one shared state signal has N inputs to coordinate, not N² connections.
+- **Actor snapshots are signals too.** `owners.videoBufferActor?.snapshot.get()` is a regular signal read inside the effect. When the actor transitions from `'updating'` to `'idle'`, the snapshot signal fires, the effect re-runs, and `endOfStream` re-evaluates whether the gate is now passable. Actor state and engine state are the same kind of channel from a behavior's point of view.
+
+The behavior also handles the seek-back case: if `appendBuffer` re-opens an `'ended'` MediaSource (per the MSE spec, a fresh append on an ended buffer transitions readyState back to `'open'`), `endOfStream` re-evaluates and may call `endOfStream()` again once the new last segment lands.
+
+---
+
+## Stage 9 — Text tracks
+
+```ts
+syncTextTracks,
+setupTextTrackActors,
+loadTextTrackCues,
+```
+
+Text tracks are an interesting wrinkle. They don't go through MSE — VTT cues land directly on the `<track>` elements of the media element. The shape of this stage is therefore different from the MSE pipeline above: there are no source buffers, no append serialization, no end-of-stream gate. But the SPF patterns are the same.
+
+**`syncTextTracks`** mirrors the resolved text-track list onto `<track>` elements under the media element. When a text track is selected (`state.selectedTextTrackId`), the matching `<track>` element gets `mode = 'showing'`; others go to `'disabled'`. This is reactive: changing the selection in state re-runs the effect, which flips the modes.
+
+**`setupTextTrackActors`** is the actor-provider for text tracks, parallel to `setupSourceBuffers` for video/audio. It creates two actors — `TextTracksActor` (owns the cue list per track) and `TextTrackSegmentLoaderActor` (orchestrates per-segment fetches via the VTT resolver) — and publishes them onto owners.
+
+In the engine, this is a wrapper that closes over the DOM-bound VTT resolver (`resolveVttSegment`):
+
+```ts
+import { setupTextTrackActors as _setupTextTrackActors } from '../../behaviors/dom/setup-text-track-actors';
+
+const setupTextTrackActors = ({ owners }: Deps) =>
+  _setupTextTrackActors({ owners, config: { resolveTextTrackSegment: resolveVttSegment } });
+```
+
+The underlying `_setupTextTrackActors` (in `playback/behaviors/dom/`) is parser-agnostic — it accepts any `resolveTextTrackSegment` function. The DOM-specific binding (using a hidden `<video>` + `<track>` element to leverage the browser's VTT parser) happens at the engine layer. A different engine could supply a different parser without changing the behavior.
+
+**`loadTextTrackCues`** is the orchestrator. It watches the resolved text track and the actors, and dispatches `load` messages to the segment loader actor whenever new segments need fetching. The actor handles per-segment fetching (and abort on track switch); the orchestrator decides *when* to ask.
+
+This is the same pattern as MSE: actor-as-resource (`setupTextTrackActors` puts it on owners), orchestrator-as-behavior (`loadTextTrackCues` decides when to send messages). Different platform, same shape.
+
+---
+
+## Two ways to call `createComposition`
+
+A note on the engine's call to `createComposition` itself.
+
+The HLS engine uses the *explicit* form — passing `<S, O, C>` type arguments to fix the engine's shape directly:
+
+```ts
+return createComposition<SimpleHlsEngineState, SimpleHlsEngineOwners, SimpleHlsEngineConfig>(
+  [...behaviors],
+  { config, initialState, initialOwners }
+);
+```
+
+The minimal/inferred form lets TypeScript intersect each behavior's deps to compute the engine's shape:
+
+```ts
+const engine = createComposition([myBehavior]);
+```
+
+For engines that aggregate many wrapper-style behaviors (`(deps: Deps) => behavior(deps, {...})`) all sharing the same `Behavior<S, O, C>` type, TypeScript's distributive intersection inference can drop fields — e.g. for the HLS engine, `bandwidthState` would silently disappear from the inferred state, and `initialState: { bandwidthState: ... }` would be flagged as an unknown property. The explicit form sidesteps the inference and uses the engine's declared shapes directly.
+
+The inferred form remains the right call for small or single-behavior compositions where the per-feature state slices are the source of truth. For aggregating engines, prefer explicit.
diff --git a/packages/spf/package.json b/packages/spf/package.json
index 9695d030..4e641657 100644
--- a/packages/spf/package.json
+++ b/packages/spf/package.json
@@ -28,10 +28,10 @@
       "development": "./dist/dev/dom.js",
       "default": "./dist/default/dom.js"
     },
-    "./playback-engine": {
-      "types": "./dist/dev/dom/playback-engine.d.ts",
-      "development": "./dist/dev/dom/playback-engine.js",
-      "default": "./dist/default/dom/playback-engine.js"
+    "./hls": {
+      "types": "./dist/dev/hls.d.ts",
+      "development": "./dist/dev/hls.js",
+      "default": "./dist/default/hls.js"
     }
   },
   "main": "dist/default/index.js",
diff --git a/packages/spf/src/CLAUDE.md b/packages/spf/src/CLAUDE.md
new file mode 100644
index 00000000..92516e6a
--- /dev/null
+++ b/packages/spf/src/CLAUDE.md
@@ -0,0 +1,77 @@
+# `@videojs/spf` source layout
+
+Guidance for AI agents and contributors working in `packages/spf/src/`.
+
+## Top-level layout
+
+```
+src/
+  core/        SPF runtime primitives — signals, effects, tasks, actors, reactors, composition
+  media/       CML-like media building blocks — types, parsers, ABR, buffer logic, MSE/VTT primitives
+  network/     HTTP fetch utilities, chunked-stream iterables
+  playback/    Playback domain — composes core+media+network into engines
+    behaviors/ Compositional behaviors that drive playback (use signals/effects)
+    actors/    Actor factories used inside behaviors
+    engines/   Assembled playback engines (currently just hls/)
+```
+
+`media/`, `network/`, and `playback/behaviors/` each have a `dom/` subdirectory for DOM-bound code (browser APIs like `HTMLMediaElement`, `MediaSource`, `VTTCue`). DOM-free code lives outside those subdirs.
+
+## Dependency rules
+
+| From → To | Allowed? | Enforced by |
+|---|---|---|
+| `media/` → `core/` | ❌ | `media/tsconfig.json` does not reference `core` |
+| `media/` → `network/` | ❌ | `media/tsconfig.json` does not reference `network` |
+| `media/` → `playback/` | ❌ | `playback/` not referenced |
+| `network/` → `core/` | ❌ | `network/tsconfig.json` has empty `references` |
+| `network/` → `media/` | ❌ | same |
+| `network/` → `playback/` | ❌ | same |
+| `core/` → `media/`, `network/`, `playback/` | ❌ | `core/tsconfig.json` does not reference downstream subtrees |
+| `core/` → DOM | ❌ | `core/tsconfig.json` `lib` excludes `DOM` |
+| `media/` (non-dom) → DOM | ❌ | `media/tsconfig.json` `lib` excludes `DOM` |
+| `network/` → DOM | ❌ | `network/tsconfig.json` `lib` excludes `DOM` |
+| `playback/behaviors/` (non-dom) → DOM | ❌ | tsconfig `lib` excludes `DOM` |
+| `playback/actors/` (non-dom) → DOM | ❌ | tsconfig `lib` excludes `DOM` |
+| `playback/` → `core/`, `network/`, `media/` | ✅ | references in playback tsconfigs |
+| `playback/engines/hls/` → `playback/behaviors/`, `playback/actors/` | ✅ | references |
+| `playback/engines/hls/` → `core/`, `media/` | ✅ — engines compose primitives directly | references |
+
+The substance: `core/`, `media/`, `network/` are framework-agnostic foundations. `playback/` is the SPF-integrated layer that composes them. Engines live at the top of the dependency tree and may reach into any foundation.
+
+## Where to put new code
+
+- **Pure media/streaming logic** (parsers, types, selection algorithms, MSE/VTT helpers without signals): `media/` or `media/dom/`. Must not import from `core/`.
+- **Compositional behavior driving state** (uses `effect`/`computed`/`update` against owners or state signals): `playback/behaviors/` or `playback/behaviors/dom/`.
+- **Actor factories** (long-lived stateful units that receive messages): `playback/actors/` or `playback/actors/dom/`.
+- **Engine compositions** (wiring behaviors+actors+config into a `createComposition` call): `playback/engines/<name>/`.
+- **Generic, framework-agnostic utilities** that aren't media-specific: prefer `@videojs/utils` over creating new homes inside spf.
+
+If a module looks like a primitive but reaches into `core/`, that's a smell — consider whether the signal binding can move to the call site (see `onMediaSourceReadyStateChange` for a callback-shaped primitive that lets the consumer create the signal).
+
+## DOM-vs-not enforcement
+
+The DOM/no-DOM split is enforced by `lib` settings on each subtree's `tsconfig.json`:
+- DOM-free subtrees use `lib: ["ES2022", "WebWorker"]` — referencing `HTMLMediaElement`, `document`, etc. fails typecheck.
+- DOM subtrees use `lib: ["ES2022", "DOM", "DOM.Iterable"]`.
+
+This is structural — you cannot accidentally import DOM types into a non-DOM module without surfacing a typecheck error.
+
+## Public exports
+
+External consumers go through three entry points (defined in `packages/spf/package.json`):
+- `@videojs/spf` — main entry (`src/index.ts`): runtime-agnostic primitives + media/network helpers.
+- `@videojs/spf/dom` — DOM-bound exports (`src/dom.ts`): re-exports from `playback/behaviors/dom/` and `media/dom/`.
+- `@videojs/spf/hls` — HLS engine (`src/playback/engines/hls/index.ts`).
+
+Internal paths are not part of the public API. Don't import from `@videojs/spf/playback/...` or similar deep paths in other workspace packages.
+
+## Vitest projects
+
+`packages/spf/vitest.config.ts` shards tests by area:
+- `core`, `media`, `network`, `behaviors` — Node, no browser
+- `dom` — Chromium via Playwright, covers all `**/dom/**/*.test.ts` across subtrees
+- `playback-engines` — Chromium, covers engines/
+- `types` — type-only tests via tsgo
+
+When adding a test in a new location, check the project globs match.
diff --git a/packages/spf/src/all.ts b/packages/spf/src/all.ts
index 1ca43183..7a3060e1 100644
--- a/packages/spf/src/all.ts
+++ b/packages/spf/src/all.ts
@@ -51,6 +51,7 @@ export { DEFAULT_FORWARD_BUFFER_CONFIG, getSegmentsToLoad } from './media/buffer
 export type {
   AudioTrack,
   FrameRate,
+  MaybeResolvedPresentation,
   MediaElementLike,
   PartiallyResolvedAudioTrack,
   PartiallyResolvedTextTrack,
@@ -63,7 +64,7 @@ export type {
   Track,
   VideoTrack,
 } from './media/types';
-export { hasPresentationDuration, isResolvedTrack } from './media/types';
+export { hasPresentationDuration, isResolvedPresentation, isResolvedTrack } from './media/types';
 
 // =============================================================================
 // DOM APIs (P4, P12, P16)
@@ -72,7 +73,7 @@ export { hasPresentationDuration, isResolvedTrack } from './media/types';
 export type {
   AttachMediaSourceResult,
   CreateMediaSourceOptions,
-} from './dom/media/mediasource-setup';
+} from './media/dom/mse/mediasource-setup';
 export {
   attachMediaSource,
   createMediaSource,
@@ -80,26 +81,18 @@ export {
   isCodecSupported,
   supportsManagedMediaSource,
   supportsMediaSource,
-} from './dom/media/mediasource-setup';
-export type { ResponseLike } from './dom/network/fetch';
-export { fetchResolvable, getResponseText } from './dom/network/fetch';
+} from './media/dom/mse/mediasource-setup';
+export type { ResponseLike } from './network/fetch';
+export { fetchResolvable, getResponseText } from './network/fetch';
 
 // =============================================================================
 // Features (F1)
 // =============================================================================
 
-export type {
-  PresentationState,
-  UnresolvedPresentation,
-} from './media/features/resolve-presentation';
-export {
-  canResolve,
-  isUnresolved,
-  resolvePresentation,
-  shouldResolve,
-} from './media/features/resolve-presentation';
-export type { PlatformOwners } from './media/features/sync-preload-attribute';
-export { syncPreloadAttribute } from './media/features/sync-preload-attribute';
+export type { PresentationState } from './playback/behaviors/resolve-presentation';
+export { canResolve, resolvePresentation, shouldResolve } from './playback/behaviors/resolve-presentation';
+export type { PlatformOwners } from './playback/behaviors/sync-preload-attribute';
+export { syncPreloadAttribute } from './playback/behaviors/sync-preload-attribute';
 
 // =============================================================================
 // Features (F9 - Quality Switching)
@@ -108,5 +101,5 @@ export { syncPreloadAttribute } from './media/features/sync-preload-attribute';
 export type {
   QualitySwitchingConfig,
   QualitySwitchingState,
-} from './media/features/quality-switching';
-export { DEFAULT_SWITCHING_CONFIG, switchQuality } from './media/features/quality-switching';
+} from './playback/behaviors/quality-switching';
+export { DEFAULT_SWITCHING_CONFIG, switchQuality } from './playback/behaviors/quality-switching';
diff --git a/packages/spf/src/core/composition/create-composition.ts b/packages/spf/src/core/composition/create-composition.ts
index 40e7f054..e567b8e0 100644
--- a/packages/spf/src/core/composition/create-composition.ts
+++ b/packages/spf/src/core/composition/create-composition.ts
@@ -189,25 +189,29 @@ export interface CompositionOptions<S extends object, O extends object, C extend
  * or any specific protocol. It creates shared reactive state, wires
  * each behavior to that state, and returns the composition interface.
  *
- * The state, owners, and config types are inferred from the behaviors:
- * each behavior declares what it needs via its parameter type, and the
- * engine computes the intersection of all requirements.
+ * Two ways to call:
+ *
+ * 1. **Inferred** — pass behaviors and let TypeScript intersect their
+ *    deps to compute the engine's state, owners, and config shapes.
+ *    Best when behaviors declare narrow per-feature shapes.
+ * 2. **Explicit** — supply `<S, O, C>` type arguments and the engine
+ *    uses those shapes directly. Best for engines that aggregate many
+ *    wrapper-style behaviors all sharing the same `Behavior<S, O, C>`
+ *    type — TypeScript's distributive intersection inference can drop
+ *    types in that case, so explicit arguments are more reliable.
  *
  * @param behaviors - Array of behavior functions
  * @param options - Optional config, initial state, and initial owners
  *
  * @example
  * ```ts
- * // Minimal — just behaviors
- * const engine = createComposition([myBehavior]);
+ * // 1. Inferred
+ * const engine = createComposition([resolvePresentation, selectVideoTrack]);
  *
- * // With config and initial state
- * const engine = createComposition(
- *   [resolvePresentation, selectVideoTrack, loadVideoSegments],
- *   {
- *     config: { initialBandwidth: 2_000_000 },
- *     initialState: { bandwidthState: initialBandwidthState() },
- *   }
+ * // 2. Explicit (engine declares its full state/owners/config up front)
+ * const engine = createComposition<MyState, MyOwners, MyConfig>(
+ *   [behavior1, behavior2, ...],
+ *   { config, initialState, initialOwners }
  * );
  * ```
  */
@@ -218,19 +222,21 @@ export function createComposition<const Behaviors extends readonly AnyBehavior[]
     ResolveBehaviorOwners<Behaviors>,
     ResolveBehaviorConfig<Behaviors>
   >
-): Composition<ResolveBehaviorState<Behaviors>, ResolveBehaviorOwners<Behaviors>> {
-  type S = ResolveBehaviorState<Behaviors>;
-  type O = ResolveBehaviorOwners<Behaviors>;
-  type C = ResolveBehaviorConfig<Behaviors>;
+): Composition<ResolveBehaviorState<Behaviors>, ResolveBehaviorOwners<Behaviors>>;
+export function createComposition<S extends object, O extends object, C extends object>(
+  behaviors: readonly Behavior<S, O, C>[],
+  options?: CompositionOptions<S, O, C>
+): Composition<S, O>;
+export function createComposition(
+  behaviors: readonly AnyBehavior[],
+  options?: CompositionOptions<object, object, object>
+): Composition<object, object> {
+  const state = signal(options?.initialState ?? {});
+  const owners = signal(options?.initialOwners ?? {});
+  const config = options?.config ?? {};
 
-  const state = signal((options?.initialState ?? {}) as S);
-  const owners = signal((options?.initialOwners ?? {}) as O);
-  const config = (options?.config ?? {}) as C;
-
-  const deps: BehaviorDeps<S, O, C> = { state, owners, config };
-  // ValidateComposition resolves to [...Behaviors] for valid compositions;
-  // the cast is needed because the type is unresolved in the generic context.
-  const cleanups = (behaviors as unknown as AnyBehavior[]).map((f) => f(deps));
+  const deps: BehaviorDeps<object, object, object> = { state, owners, config };
+  const cleanups = behaviors.map((f) => f(deps));
 
   return {
     state,
@@ -248,7 +254,7 @@ export function createComposition<const Behaviors extends readonly AnyBehavior[]
       await Promise.all(results);
       // Clear any keys behaviors registered — or callers seeded via
       // initialOwners — so the composition ends with an empty owners map.
-      owners.set({} as O);
+      owners.set({});
     },
   };
 }
diff --git a/packages/spf/src/core/composition/tests/create-composition-types.test-d.ts b/packages/spf/src/core/composition/tests/create-composition-types.test-d.ts
index e3604a25..a04e74be 100644
--- a/packages/spf/src/core/composition/tests/create-composition-types.test-d.ts
+++ b/packages/spf/src/core/composition/tests/create-composition-types.test-d.ts
@@ -4,6 +4,24 @@ import type { Signal } from '../../signals/primitives';
 import { update } from '../../signals/primitives';
 import { createComposition } from '../create-composition';
 
+// =============================================================================
+// Host-agnostic stand-in types
+// -----------------------------------------------------------------------------
+// Core is DOM-free. The tests need a small, concrete type to stand in for the
+// kind of thing a user would pass as an owner — something with a writable
+// surface and clear subtype relationships for covariance / non-covariance tests.
+// =============================================================================
+
+interface Surface {
+  textContent?: string | null;
+}
+interface VideoSurface extends Surface {
+  kind: 'video';
+}
+interface CanvasSurface extends Surface {
+  kind: 'canvas';
+}
+
 // =============================================================================
 // Test behaviors
 // =============================================================================
@@ -21,7 +39,7 @@ function render({
   config,
 }: {
   state: Signal<{ count?: number }>;
-  owners: Signal<{ renderElement?: HTMLElement }>;
+  owners: Signal<{ renderElement?: Surface }>;
   config: { defaultText?: string };
 }) {
   return effect(() => {
@@ -60,7 +78,7 @@ describe('createComposition type errors', () => {
   });
 
   it('errors when initialOwners has wrong types', () => {
-    // @ts-expect-error — renderElement expects HTMLElement, not number
+    // @ts-expect-error — renderElement expects Surface, not number
     createComposition([render], { initialOwners: { renderElement: 42 } });
   });
 
@@ -94,10 +112,10 @@ describe('createComposition type errors', () => {
   });
 
   it('errors when composing behaviors with incompatible owners class types', () => {
-    const expectsCanvas = (_deps: { owners: Signal<{ el?: HTMLCanvasElement }> }) => {};
-    const expectsVideo = (_deps: { owners: Signal<{ el?: HTMLVideoElement }> }) => {};
+    const expectsCanvas = (_deps: { owners: Signal<{ el?: CanvasSurface }> }) => {};
+    const expectsVideo = (_deps: { owners: Signal<{ el?: VideoSurface }> }) => {};
 
-    // @ts-expect-error — neither HTMLCanvasElement nor HTMLVideoElement extends the other
+    // @ts-expect-error — neither CanvasSurface nor VideoSurface extends the other
     createComposition([expectsCanvas, expectsVideo]);
   });
 
@@ -106,16 +124,16 @@ describe('createComposition type errors', () => {
   // =========================================================================
 
   it('allows composing behaviors with owners in a subtype relationship', () => {
-    const expectsElement = (_deps: { owners: Signal<{ el?: HTMLElement }> }) => {};
-    const expectsVideo = (_deps: { owners: Signal<{ el?: HTMLVideoElement }> }) => {};
+    const expectsSurface = (_deps: { owners: Signal<{ el?: Surface }> }) => {};
+    const expectsVideo = (_deps: { owners: Signal<{ el?: VideoSurface }> }) => {};
 
-    // No error — HTMLVideoElement extends HTMLElement
-    createComposition([expectsElement, expectsVideo]);
+    // No error — VideoSurface extends Surface
+    createComposition([expectsSurface, expectsVideo]);
   });
 
   it('allows composing behaviors that omit owners', () => {
     const stateOnly = (_deps: { state: Signal<{ count?: number }> }) => {};
-    const withOwners = (_deps: { state: Signal<{ count?: number }>; owners: Signal<{ el?: HTMLElement }> }) => {};
+    const withOwners = (_deps: { state: Signal<{ count?: number }>; owners: Signal<{ el?: Surface }> }) => {};
 
     // No error — omitting owners is not a conflict
     createComposition([stateOnly, withOwners]);
@@ -139,7 +157,7 @@ describe('createComposition type errors', () => {
 
   it('allows composing behaviors where each omits different channels', () => {
     const onlyState = (_deps: { state: Signal<{ count?: number }> }) => {};
-    const onlyOwners = (_deps: { owners: Signal<{ el?: HTMLElement }> }) => {};
+    const onlyOwners = (_deps: { owners: Signal<{ el?: Surface }> }) => {};
     const onlyConfig = (_deps: { config: { interval?: number } }) => {};
 
     // No error — behaviors with disjoint channels don't conflict
@@ -161,7 +179,7 @@ describe('createComposition type errors', () => {
   });
 
   it('allows resetting optional owners fields to undefined', () => {
-    const behavior = (_deps: { owners: Signal<{ el?: HTMLElement }> }) => {};
+    const behavior = (_deps: { owners: Signal<{ el?: Surface }> }) => {};
     const engine = createComposition([behavior]);
 
     // No error — clearing an owner (e.g. on source switch)
diff --git a/packages/spf/src/core/composition/tests/create-composition-types.test.ts b/packages/spf/src/core/composition/tests/create-composition-types.test.ts
index 98f07d42..c57372e7 100644
--- a/packages/spf/src/core/composition/tests/create-composition-types.test.ts
+++ b/packages/spf/src/core/composition/tests/create-composition-types.test.ts
@@ -11,6 +11,18 @@ import {
   type ResolveBehaviorState,
 } from '../create-composition';
 
+// =============================================================================
+// Host-agnostic stand-in types
+// -----------------------------------------------------------------------------
+// Core is DOM-free. The tests need a small, concrete type to stand in for the
+// kind of thing a user would pass as an owner — something with a writable
+// surface and clear subtype relationships for covariance tests.
+// =============================================================================
+
+interface Surface {
+  textContent?: string | null;
+}
+
 // =============================================================================
 // Test behaviors — concrete parameter types
 // =============================================================================
@@ -28,7 +40,7 @@ function render({
   config,
 }: {
   state: Signal<{ count?: number }>;
-  owners: Signal<{ renderElement?: HTMLElement }>;
+  owners: Signal<{ renderElement?: Surface }>;
   config: { defaultText?: string };
 }) {
   return effect(() => {
@@ -87,7 +99,7 @@ describe('InferBehaviorState', () => {
 
 describe('InferBehaviorOwners', () => {
   it('extracts owners type from a behavior that uses owners', () => {
-    expectTypeOf<InferBehaviorOwners<typeof render>>().toEqualTypeOf<{ renderElement?: HTMLElement }>();
+    expectTypeOf<InferBehaviorOwners<typeof render>>().toEqualTypeOf<{ renderElement?: Surface }>();
   });
 
   it('returns object for a behavior with no owners in params', () => {
@@ -136,8 +148,8 @@ describe('ResolveBehaviorOwners', () => {
   it('resolves owners from mixed behaviors (some without owners)', () => {
     // counter has no owners, render has renderElement
     type Behaviors = [typeof counter, typeof render];
-    // object & { renderElement?: HTMLElement } should simplify
-    expectTypeOf<ResolveBehaviorOwners<Behaviors>>().toExtend<{ renderElement?: HTMLElement }>();
+    // object & { renderElement?: Surface } should simplify
+    expectTypeOf<ResolveBehaviorOwners<Behaviors>>().toExtend<{ renderElement?: Surface }>();
   });
 });
 
@@ -178,11 +190,11 @@ describe('createComposition', () => {
       const engine = createComposition([counter, render, persist], {
         initialState: { count: 0 },
         config: { interval: 250, defaultText: '--', saveEvery: 5 },
-        initialOwners: { renderElement: null as unknown as HTMLElement },
+        initialOwners: { renderElement: null as unknown as Surface },
       });
 
       expectTypeOf(engine.state.get()).toExtend<{ count?: number }>();
-      expectTypeOf(engine.owners.get()).toExtend<{ renderElement?: HTMLElement }>();
+      expectTypeOf(engine.owners.get()).toExtend<{ renderElement?: Surface }>();
     });
 
     it('infers combined state from behaviors with different state shapes', () => {
@@ -225,12 +237,12 @@ describe('createComposition', () => {
 
     it('allows update() with undefined for optional owners fields', () => {
       const engine = createComposition([render], {
-        initialOwners: { renderElement: null as unknown as HTMLElement },
+        initialOwners: { renderElement: null as unknown as Surface },
       });
 
       // Clearing an owner (e.g. on source switch)
       update(engine.owners, { renderElement: undefined });
-      expectTypeOf(engine.owners.get().renderElement).toEqualTypeOf<HTMLElement | undefined>();
+      expectTypeOf(engine.owners.get().renderElement).toEqualTypeOf<Surface | undefined>();
     });
   });
 
diff --git a/packages/spf/src/core/tasks/task.ts b/packages/spf/src/core/tasks/task.ts
index 38d76045..e66d602a 100644
--- a/packages/spf/src/core/tasks/task.ts
+++ b/packages/spf/src/core/tasks/task.ts
@@ -1,5 +1,5 @@
 import { anyAbortSignal } from '@videojs/utils/events';
-import { generateId } from '../utils/generate-id';
+import { generateId } from '@videojs/utils/string';
 
 // =============================================================================
 // DeepReadonly
diff --git a/packages/spf/src/core/tsconfig.json b/packages/spf/src/core/tsconfig.json
new file mode 100644
index 00000000..0bc5e2ec
--- /dev/null
+++ b/packages/spf/src/core/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "WebWorker"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../types/core"
+  },
+  "references": [{ "path": "../../../utils" }],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/src/core/utils/generate-id.ts b/packages/spf/src/core/utils/generate-id.ts
deleted file mode 100644
index 13e19ee3..00000000
--- a/packages/spf/src/core/utils/generate-id.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-/**
- * Generate unique ID for HAM objects.
- *
- * Uses timestamp + random number for sufficient uniqueness.
- * IDs are strings without decimals.
- *
- * @returns Unique string ID in format: timestamp-random
- *
- * @example
- * ```ts
- * const id = generateId();  // "1738423156789-542891"
- * ```
- */
-export function generateId(): string {
-  return `${Date.now()}-${Math.floor(Math.random() * 1000000)}`;
-}
diff --git a/packages/spf/src/dom.ts b/packages/spf/src/dom.ts
new file mode 100644
index 00000000..4bd930c0
--- /dev/null
+++ b/packages/spf/src/dom.ts
@@ -0,0 +1,22 @@
+/**
+ * DOM/Browser-specific SPF bindings
+ *
+ * This is a convenience aggregate of DOM-bound exports drawn from across
+ * the package. The underlying pieces live alongside their DOM-free peers
+ * in `behaviors/` (with `dom/` subdirs where applicable) and `media/dom/`.
+ */
+
+export { appendSegment } from './media/dom/mse/append-segment';
+export { flushBuffer } from './media/dom/mse/buffer-flusher';
+export { destroyVttResolver, resolveVttSegment } from './media/dom/text/resolve-vtt-segment';
+export { loadSegments } from './playback/behaviors/dom/load-segments';
+export { setupTextTrackActors } from './playback/behaviors/dom/setup-text-track-actors';
+export type { CurrentTimeOwners, CurrentTimeState } from './playback/behaviors/dom/track-current-time';
+export { trackCurrentTime } from './playback/behaviors/dom/track-current-time';
+export type {
+  PlaybackInitiatedOwners,
+  PlaybackInitiatedState,
+} from './playback/behaviors/dom/track-playback-initiated';
+export { trackPlaybackInitiated } from './playback/behaviors/dom/track-playback-initiated';
+export type { PlaybackRateOwners, PlaybackRateState } from './playback/behaviors/dom/track-playback-rate';
+export { trackPlaybackRate } from './playback/behaviors/dom/track-playback-rate';
diff --git a/packages/spf/src/dom/features/load-text-track-cues.ts b/packages/spf/src/dom/features/load-text-track-cues.ts
deleted file mode 100644
index 620c0242..00000000
--- a/packages/spf/src/dom/features/load-text-track-cues.ts
+++ /dev/null
@@ -1,186 +0,0 @@
-import type { Reactor } from '../../core/reactors/create-machine-reactor';
-import { createMachineReactor } from '../../core/reactors/create-machine-reactor';
-import { computed, type Signal, untrack, update } from '../../core/signals/primitives';
-import type { Presentation, TextTrack } from '../../media/types';
-import { isResolvedTrack } from '../../media/types';
-import type { TextTrackSegmentLoaderActor } from './text-track-segment-loader-actor';
-import { createTextTrackSegmentLoaderActor } from './text-track-segment-loader-actor';
-import type { TextTracksActor } from './text-tracks-actor';
-import { createTextTracksActor } from './text-tracks-actor';
-
-/**
- * FSM states for text track cue loading.
- *
- * ```
- * 'preconditions-unmet' ── mediaElement + presentation + text tracks ──→ 'setting-up'
- *        ↑                                                                      |
- *        │                                                             actors created
- *        │                                                             in owners
- *        │                                                                      ↓
- *        ├───────────────── preconditions lost ─────────────────────── 'pending'
- *        │                                                                      |
- *        │                                                  selectedTrack resolved + in DOM
- *        │                                                                      ↓
- *        └───────────────── preconditions lost ──────────── 'monitoring-for-loads'
- *
- * any state ──── destroy() ────→ 'destroying' ────→ 'destroyed'
- * ```
- */
-export type LoadTextTrackCuesState = 'preconditions-unmet' | 'setting-up' | 'pending' | 'monitoring-for-loads';
-
-/**
- * State shape for text track cue loading.
- */
-export interface TextTrackCueLoadingState {
-  selectedTextTrackId?: string;
-  presentation?: Presentation;
-  /** Current playback position — used to gate VTT segment fetching to the forward buffer window. */
-  currentTime?: number;
-}
-
-/**
- * Owners shape for text track cue loading.
- *
- * `textTracksActor` and `segmentLoaderActor` are managed by this reactor:
- * written to owners in `'setting-up'` and reset to `undefined` on entry to
- * `'preconditions-unmet'` or `'setting-up'`. Callers are responsible for
- * destroying them when the reactor itself is destroyed (actors are not
- * auto-cleaned on `destroy()` — read them from owners and destroy explicitly).
- */
-export interface TextTrackCueLoadingOwners {
-  mediaElement?: HTMLMediaElement | undefined;
-  textTracksActor?: TextTracksActor | undefined;
-  segmentLoaderActor?: TextTrackSegmentLoaderActor | undefined;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function getTextTracks(presentation: Presentation | undefined) {
-  return presentation?.selectionSets?.find((s) => s.type === 'text')?.switchingSets[0]?.tracks;
-}
-
-function findSelectedTrack(state: TextTrackCueLoadingState): TextTrack | undefined {
-  const track = getTextTracks(state.presentation)?.find((t) => t.id === state.selectedTextTrackId);
-  return track && isResolvedTrack(track) ? track : undefined;
-}
-
-/**
- * Derives the correct state from current state and owners.
- *
- * 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 deriveState(state: TextTrackCueLoadingState, owners: TextTrackCueLoadingOwners): LoadTextTrackCuesState {
-  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';
-}
-
-function teardownActors(owners: Signal<TextTrackCueLoadingOwners>) {
-  const { textTracksActor, segmentLoaderActor } = untrack(() => owners.get());
-  // Only update owners if there are actors to clean up — avoids spurious
-  // signal writes on initial startup that would re-trigger other features.
-  if (!textTracksActor && !segmentLoaderActor) return;
-  textTracksActor?.destroy();
-  segmentLoaderActor?.destroy();
-  update(owners, { textTracksActor: undefined, segmentLoaderActor: undefined });
-}
-
-// ============================================================================
-// Main export
-// ============================================================================
-
-/**
- * Text track cue loading orchestration.
- *
- * A single `always` monitor keeps the reactor in sync with conditions.
- * Actor lifecycle is managed across two states:
- *
- * - **`'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.
- *
- * **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 reactor = loadTextTrackCues({ state, owners });
- * // later:
- * const { textTracksActor, segmentLoaderActor } = owners.get();
- * textTracksActor?.destroy();
- * segmentLoaderActor?.destroy();
- * reactor.destroy();
- */
-export function loadTextTrackCues<S extends TextTrackCueLoadingState, O extends TextTrackCueLoadingOwners>({
-  state,
-  owners,
-}: {
-  state: Signal<S>;
-  owners: Signal<O>;
-}): Reactor<LoadTextTrackCuesState | 'destroying' | 'destroyed'> {
-  const derivedStateSignal = computed(() => deriveState(state.get(), owners.get()));
-  const currentTimeSignal = computed(() => state.get().currentTime ?? 0);
-  const selectedTrackSignal = computed(() => findSelectedTrack(state.get()));
-
-  return createMachineReactor<LoadTextTrackCuesState>({
-    initial: 'preconditions-unmet',
-    monitor: () => derivedStateSignal.get(),
-    states: {
-      'preconditions-unmet': {
-        // Entry: defensive actor reset on state entry (no-op if already undefined).
-        entry: () => {
-          teardownActors(owners);
-        },
-      },
-
-      'setting-up': {
-        // Entry: reset any stale actors, then create fresh ones and write to owners.
-        // The fn body is automatically untracked — no untrack() needed for mediaElement.
-        entry: () => {
-          teardownActors(owners);
-          const mediaElement = owners.get().mediaElement as HTMLMediaElement;
-          const textTracksActor = createTextTracksActor(mediaElement);
-          const segmentLoaderActor = createTextTrackSegmentLoaderActor(textTracksActor);
-          update(owners, { textTracksActor, segmentLoaderActor } as Partial<O>);
-        },
-      },
-
-      pending: {},
-
-      'monitoring-for-loads': {
-        // Reaction: re-runs whenever currentTime or selectedTrack changes, dispatching
-        // a load message to the segment loader. owners is read with untrack() since
-        // actor presence is guaranteed by deriveState when in this state.
-        effects: () => {
-          const currentTime = currentTimeSignal.get();
-          const track = selectedTrackSignal.get()!;
-          // deriveState guarantees segmentLoaderActor is in owners and findSelectedTrack
-          // returns a valid resolved track when in this state. The always monitor
-          // (registered before this effect) transitions us out before this re-runs
-          // if either invariant ever stops holding.
-          const { segmentLoaderActor } = untrack(() => owners.get());
-          segmentLoaderActor!.send({ type: 'load', track, currentTime });
-        },
-      },
-    },
-  });
-}
diff --git a/packages/spf/src/dom/index.ts b/packages/spf/src/dom/index.ts
deleted file mode 100644
index eb0572dd..00000000
--- a/packages/spf/src/dom/index.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-/**
- * DOM/Browser-specific SPF bindings
- */
-
-export { loadSegments } from './features/load-segments';
-export { loadTextTrackCues } from './features/load-text-track-cues';
-export type { CurrentTimeOwners, CurrentTimeState } from './features/track-current-time';
-export { trackCurrentTime } from './features/track-current-time';
-export type { PlaybackInitiatedOwners, PlaybackInitiatedState } from './features/track-playback-initiated';
-export { trackPlaybackInitiated } from './features/track-playback-initiated';
-export type { PlaybackRateOwners, PlaybackRateState } from './features/track-playback-rate';
-export { trackPlaybackRate } from './features/track-playback-rate';
-export { appendSegment } from './media/append-segment';
-export { flushBuffer } from './media/buffer-flusher';
-export type { SpfMediaAPI, SpfMediaProps } from './playback-engine/adapter';
-export { SpfMedia, SpfMediaMixin, spfMediaDefaultProps } from './playback-engine/adapter';
-export { destroyVttParser, parseVttSegment } from './text/parse-vtt-segment';
diff --git a/packages/spf/src/dom/playback-engine/index.ts b/packages/spf/src/dom/playback-engine/index.ts
deleted file mode 100644
index 07b77cc3..00000000
--- a/packages/spf/src/dom/playback-engine/index.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-export type { SpfMediaAPI } from './adapter';
-export { SpfMedia, SpfMediaMixin } from './adapter';
-export type {
-  HlsPlaybackEngineConfig,
-  HlsPlaybackEngineOwners,
-  HlsPlaybackEngineState,
-} from './hls-engine';
-export { createHlsPlaybackEngine } from './hls-engine';
diff --git a/packages/spf/src/dom/tsconfig.json b/packages/spf/src/dom/tsconfig.json
deleted file mode 100644
index 0b7af1f5..00000000
--- a/packages/spf/src/dom/tsconfig.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "extends": "../../../../tsconfig.base.json",
-  "compilerOptions": {
-    "composite": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "declarationDir": "../../types/dom"
-  },
-  "references": [{ "path": "../.." }],
-  "include": ["./**/*.ts"]
-}
diff --git a/packages/spf/src/index.ts b/packages/spf/src/index.ts
index b6eb1b3c..48797182 100644
--- a/packages/spf/src/index.ts
+++ b/packages/spf/src/index.ts
@@ -3,7 +3,7 @@
  *
  * The compositional primitives: createComposition, signals, tasks, actors,
  * reactors. Media-domain helpers and the HLS playback engine live behind
- * the `./dom` and `./playback-engine` subpaths.
+ * the `./dom` and `./hls` subpaths.
  *
  * @packageDocumentation
  */
diff --git a/packages/spf/src/dom/media/append-segment.ts b/packages/spf/src/media/dom/mse/append-segment.ts
similarity index 100%
rename from packages/spf/src/dom/media/append-segment.ts
rename to packages/spf/src/media/dom/mse/append-segment.ts
diff --git a/packages/spf/src/dom/media/buffer-flusher.ts b/packages/spf/src/media/dom/mse/buffer-flusher.ts
similarity index 100%
rename from packages/spf/src/dom/media/buffer-flusher.ts
rename to packages/spf/src/media/dom/mse/buffer-flusher.ts
diff --git a/packages/spf/src/dom/media/mediasource-setup.ts b/packages/spf/src/media/dom/mse/mediasource-setup.ts
similarity index 84%
rename from packages/spf/src/dom/media/mediasource-setup.ts
rename to packages/spf/src/media/dom/mse/mediasource-setup.ts
index b81b168c..968d5752 100644
--- a/packages/spf/src/dom/media/mediasource-setup.ts
+++ b/packages/spf/src/media/dom/mse/mediasource-setup.ts
@@ -7,8 +7,6 @@
  * Global ManagedMediaSource types are defined in ./mediasource.d.ts
  */
 
-import { type ReadonlySignal, signal } from '../../core/signals/primitives';
-
 /**
  * Check if MediaSource API is supported.
  */
@@ -160,34 +158,31 @@ export function isCodecSupported(mimeCodec: string): boolean {
 }
 
 /**
- * Create a reactive signal that mirrors `mediaSource.readyState`.
+ * Observe `mediaSource.readyState` changes via DOM events.
  *
- * Listens to `sourceopen`, `sourceended`, and `sourceclose` events and updates
- * the signal accordingly, making readyState visible to the TC39 signal graph.
- * Listeners are automatically removed when `signal` is aborted.
+ * Listens to `sourceopen`, `sourceended`, and `sourceclose` and invokes
+ * `onChange` with the current `readyState` after each event. Listeners
+ * are automatically removed when `abortSignal` is aborted.
  *
  * @param mediaSource - The MediaSource to observe
- * @param signal - AbortSignal that controls listener lifetime
- * @returns A `Signal.ReadonlyState` that reflects the current `readyState`
+ * @param abortSignal - AbortSignal that controls listener lifetime
+ * @param onChange - Called with the current readyState after each change
  *
  * @example
  * const controller = new AbortController();
- * const readyState = observeMediaSourceReadyState(mediaSource, controller.signal);
- * effect(() => {
- *   if (readyState.get() === 'open') { ... }
+ * onMediaSourceReadyStateChange(mediaSource, controller.signal, (state) => {
+ *   if (state === 'open') { ... }
  * });
- * // Later:
- * controller.abort();
+ * // Later: controller.abort();
  */
-export function observeMediaSourceReadyState(
+export function onMediaSourceReadyStateChange(
   mediaSource: MediaSource,
-  abortSignal: AbortSignal
-): ReadonlySignal<MediaSource['readyState']> {
-  const readyState = signal<MediaSource['readyState']>(mediaSource.readyState);
-  const update = () => readyState.set(mediaSource.readyState);
+  abortSignal: AbortSignal,
+  onChange: (readyState: MediaSource['readyState']) => void
+): void {
+  const update = () => onChange(mediaSource.readyState);
   const options = { signal: abortSignal };
   mediaSource.addEventListener('sourceopen', update, options);
   mediaSource.addEventListener('sourceended', update, options);
   mediaSource.addEventListener('sourceclose', update, options);
-  return readyState;
 }
diff --git a/packages/spf/src/dom/media/mediasource.d.ts b/packages/spf/src/media/dom/mse/mediasource.d.ts
similarity index 100%
rename from packages/spf/src/dom/media/mediasource.d.ts
rename to packages/spf/src/media/dom/mse/mediasource.d.ts
diff --git a/packages/spf/src/dom/media/tests/append-segment.test.ts b/packages/spf/src/media/dom/mse/tests/append-segment.test.ts
similarity index 100%
rename from packages/spf/src/dom/media/tests/append-segment.test.ts
rename to packages/spf/src/media/dom/mse/tests/append-segment.test.ts
diff --git a/packages/spf/src/dom/media/tests/buffer-flusher.test.ts b/packages/spf/src/media/dom/mse/tests/buffer-flusher.test.ts
similarity index 100%
rename from packages/spf/src/dom/media/tests/buffer-flusher.test.ts
rename to packages/spf/src/media/dom/mse/tests/buffer-flusher.test.ts
diff --git a/packages/spf/src/dom/media/tests/mediasource-setup.test.ts b/packages/spf/src/media/dom/mse/tests/mediasource-setup.test.ts
similarity index 100%
rename from packages/spf/src/dom/media/tests/mediasource-setup.test.ts
rename to packages/spf/src/media/dom/mse/tests/mediasource-setup.test.ts
diff --git a/packages/spf/src/dom/text/parse-vtt-segment.ts b/packages/spf/src/media/dom/text/resolve-vtt-segment.ts
similarity index 93%
rename from packages/spf/src/dom/text/parse-vtt-segment.ts
rename to packages/spf/src/media/dom/text/resolve-vtt-segment.ts
index 82460b25..980d591b 100644
--- a/packages/spf/src/dom/text/parse-vtt-segment.ts
+++ b/packages/spf/src/media/dom/text/resolve-vtt-segment.ts
@@ -19,7 +19,7 @@ function ensureDummyVideo(): HTMLVideoElement {
   return dummyVideo;
 }
 
-export function parseVttSegment(url: string): Promise<VTTCue[]> {
+export function resolveVttSegment(url: string): Promise<VTTCue[]> {
   const video = ensureDummyVideo();
   const track = document.createElement('track');
   track.kind = 'subtitles';
@@ -61,6 +61,6 @@ export function parseVttSegment(url: string): Promise<VTTCue[]> {
   });
 }
 
-export function destroyVttParser(): void {
+export function destroyVttResolver(): void {
   dummyVideo = null;
 }
diff --git a/packages/spf/src/dom/text/tests/cue-persistence-investigation.test.ts b/packages/spf/src/media/dom/text/tests/cue-persistence-investigation.test.ts
similarity index 100%
rename from packages/spf/src/dom/text/tests/cue-persistence-investigation.test.ts
rename to packages/spf/src/media/dom/text/tests/cue-persistence-investigation.test.ts
diff --git a/packages/spf/src/dom/text/tests/parse-vtt-segment.test.ts b/packages/spf/src/media/dom/text/tests/resolve-vtt-segment.test.ts
similarity index 77%
rename from packages/spf/src/dom/text/tests/parse-vtt-segment.test.ts
rename to packages/spf/src/media/dom/text/tests/resolve-vtt-segment.test.ts
index be8fd823..41e45298 100644
--- a/packages/spf/src/dom/text/tests/parse-vtt-segment.test.ts
+++ b/packages/spf/src/media/dom/text/tests/resolve-vtt-segment.test.ts
@@ -1,9 +1,9 @@
 import { beforeEach, describe, expect, it } from 'vitest';
-import { destroyVttParser, parseVttSegment } from '../parse-vtt-segment';
+import { destroyVttResolver, resolveVttSegment } from '../resolve-vtt-segment';
 
-describe('parseVttSegment', () => {
+describe('resolveVttSegment', () => {
   beforeEach(() => {
-    destroyVttParser();
+    destroyVttResolver();
   });
 
   it('parses valid VTT segment with single cue', async () => {
@@ -15,7 +15,7 @@ describe('parseVttSegment', () => {
 First subtitle
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(1);
     expect(cues[0]).toBeInstanceOf(VTTCue);
@@ -39,7 +39,7 @@ Second subtitle
 Third subtitle
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(3);
     expect(cues[0]!.text).toBe('First subtitle');
@@ -56,7 +56,7 @@ Third subtitle
 Test subtitle with precise timing
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(1);
     expect(cues[0]!.startTime).toBe(1.5);
@@ -73,7 +73,7 @@ Test subtitle with precise timing
 <v Speaker>Positioned subtitle</v>
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(1);
     expect(cues[0]!.startTime).toBe(0);
@@ -94,7 +94,7 @@ Second line
 Third line
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(1);
     expect(cues[0]!.text).toContain('First line');
@@ -103,7 +103,7 @@ Third line
   });
 
   it('rejects on invalid URL', async () => {
-    await expect(parseVttSegment('https://invalid.example.com/missing.vtt')).rejects.toThrow(
+    await expect(resolveVttSegment('https://invalid.example.com/missing.vtt')).rejects.toThrow(
       'Failed to load VTT segment'
     );
   });
@@ -111,13 +111,13 @@ Third line
   it('rejects on malformed VTT', async () => {
     const invalidVtt = `data:text/vtt,${encodeURIComponent('NOT VALID VTT CONTENT')}`;
 
-    await expect(parseVttSegment(invalidVtt)).rejects.toThrow('Failed to load VTT segment');
+    await expect(resolveVttSegment(invalidVtt)).rejects.toThrow('Failed to load VTT segment');
   });
 
   it('returns empty array for VTT with no cues', async () => {
     const vttDataUrl = `data:text/vtt,${encodeURIComponent('WEBVTT\n\n')}`;
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
 
     expect(cues).toHaveLength(0);
   });
@@ -139,11 +139,11 @@ First
 Second
 `);
 
-    const cues1 = await parseVttSegment(vtt1);
+    const cues1 = await resolveVttSegment(vtt1);
     expect(cues1).toHaveLength(1);
     expect(cues1[0]!.text).toBe('First');
 
-    const cues2 = await parseVttSegment(vtt2);
+    const cues2 = await resolveVttSegment(vtt2);
     expect(cues2).toHaveLength(1);
     expect(cues2[0]!.text).toBe('Second');
   });
@@ -157,27 +157,27 @@ Second
 Test
 `);
 
-    await parseVttSegment(vttDataUrl);
+    await resolveVttSegment(vttDataUrl);
 
-    destroyVttParser();
+    destroyVttResolver();
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
     expect(cues).toHaveLength(1);
     expect(cues[0]!.text).toBe('Test');
   });
 });
 
-describe('destroyVttParser', () => {
+describe('destroyVttResolver', () => {
   it('can be called multiple times safely', () => {
     expect(() => {
-      destroyVttParser();
-      destroyVttParser();
-      destroyVttParser();
+      destroyVttResolver();
+      destroyVttResolver();
+      destroyVttResolver();
     }).not.toThrow();
   });
 
   it('allows parsing after destroy', async () => {
-    destroyVttParser();
+    destroyVttResolver();
 
     const vttDataUrl =
       'data:text/vtt,' +
@@ -187,7 +187,7 @@ describe('destroyVttParser', () => {
 Test
 `);
 
-    const cues = await parseVttSegment(vttDataUrl);
+    const cues = await resolveVttSegment(vttDataUrl);
     expect(cues).toHaveLength(1);
   });
 });
diff --git a/packages/spf/src/media/dom/tsconfig.json b/packages/spf/src/media/dom/tsconfig.json
new file mode 100644
index 00000000..2b6a75c6
--- /dev/null
+++ b/packages/spf/src/media/dom/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../types/media/dom"
+  },
+  "references": [{ "path": "../../../../utils" }, { "path": "../../media" }],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/src/media/hls/parse-multivariant.ts b/packages/spf/src/media/hls/parse-multivariant.ts
index 29fb034d..a7278e50 100644
--- a/packages/spf/src/media/hls/parse-multivariant.ts
+++ b/packages/spf/src/media/hls/parse-multivariant.ts
@@ -1,4 +1,4 @@
-import { generateId } from '../../core/utils/generate-id';
+import { generateId } from '@videojs/utils/string';
 import type {
   AddressableObject,
   AudioSelectionSet,
diff --git a/packages/spf/src/media/features/select-tracks.ts b/packages/spf/src/media/primitives/select-tracks.ts
similarity index 71%
rename from packages/spf/src/media/features/select-tracks.ts
rename to packages/spf/src/media/primitives/select-tracks.ts
index a157c417..c895eef0 100644
--- a/packages/spf/src/media/features/select-tracks.ts
+++ b/packages/spf/src/media/primitives/select-tracks.ts
@@ -1,7 +1,11 @@
-import { effect } from '../../core/signals/effect';
-import { type Signal, update } from '../../core/signals/primitives';
 import { DEFAULT_QUALITY_CONFIG, selectQuality } from '../abr/quality-selection';
-import type { AudioSelectionSet, Presentation, TrackType, VideoSelectionSet } from '../types';
+import type {
+  AudioSelectionSet,
+  MaybeResolvedPresentation,
+  Presentation,
+  TrackType,
+  VideoSelectionSet,
+} from '../types';
 import { SelectedTrackIdKeyByType } from '../utils/track-selection';
 
 /**
@@ -14,7 +18,7 @@ export const DEFAULT_INITIAL_BANDWIDTH = 1_000_000;
  * State shape for track selection.
  */
 export interface TrackSelectionState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
   selectedVideoTrackId?: string;
   selectedAudioTrackId?: string;
   selectedTextTrackId?: string;
@@ -263,106 +267,3 @@ export function shouldSelectTrack<T extends TrackType>(
 ): boolean {
   return !state[SelectedTrackIdKeyByType[config.type]];
 }
-
-// =============================================================================
-// Orchestrations
-// =============================================================================
-
-/**
- * Select video track orchestration.
- *
- * Selects video track when:
- * - Presentation exists
- * - No video track is selected yet
- *
- * Uses bandwidth-based quality selection algorithm.
- *
- * @example
- * const cleanup = selectVideoTrack(
- *   { state, owners, events },
- *   { initialBandwidth: 2_000_000 }
- * );
- */
-export function selectVideoTrack<S extends TrackSelectionState>(
-  { state }: { state: Signal<S> },
-  config: VideoSelectionConfig = { type: 'video' }
-): () => void {
-  return effect(() => {
-    const currentState = state.get();
-    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
-
-    // Just to have basic functionality/POC, simply selecting the first track
-    const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === config.type)
-      ?.switchingSets[0]?.tracks[0]?.id;
-
-    if (selectedTrackId) {
-      const selectedTrackKey = SelectedTrackIdKeyByType[config.type];
-      const patch: Partial<TrackSelectionState> = { [selectedTrackKey]: selectedTrackId };
-      update(state, patch);
-    }
-  });
-}
-
-/**
- * Select audio track orchestration.
- *
- * Selects audio track when:
- * - Presentation exists
- * - No audio track is selected yet
- *
- * Uses language and preference-based selection.
- *
- * @example
- * const cleanup = selectAudioTrack(
- *   { state, owners, events },
- *   { preferredAudioLanguage: 'en' }
- * );
- */
-export function selectAudioTrack<S extends TrackSelectionState>(
-  { state }: { state: Signal<S> },
-  config: AudioSelectionConfig = { type: 'audio' }
-): () => void {
-  return effect(() => {
-    const currentState = state.get();
-    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
-
-    // Just to have basic functionality/POC, simply selecting the first track
-    const selectedTrackId = currentState.presentation?.selectionSets.find(({ type }) => type === 'audio')
-      ?.switchingSets[0]?.tracks[0]?.id;
-
-    if (selectedTrackId) {
-      const patch: Partial<TrackSelectionState> = { selectedAudioTrackId: selectedTrackId };
-      update(state, patch);
-    }
-  });
-}
-
-/**
- * Select text track orchestration.
- *
- * Selects text track when:
- * - Presentation exists
- * - No text track is selected yet
- *
- * Note: Currently does not auto-select (user opt-in).
- *
- * @example
- * const cleanup = selectTextTrack({ state, owners, events }, {});
- */
-export function selectTextTrack<S extends TrackSelectionState>(
-  { state }: { state: Signal<S> },
-  config: TextSelectionConfig = { type: 'text' }
-): () => void {
-  return effect(() => {
-    const currentState = state.get();
-    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
-
-    // Text tracks are user opt-in - don't auto-select
-    const selectedTextTrackId = pickTextTrack(currentState.presentation!, config);
-
-    if (selectedTextTrackId) {
-      const patch: Partial<TrackSelectionState> = { selectedTextTrackId };
-      update(state, patch);
-    }
-  });
-}
diff --git a/packages/spf/src/media/features/tests/select-tracks.test.ts b/packages/spf/src/media/primitives/tests/select-tracks.test.ts
similarity index 74%
rename from packages/spf/src/media/features/tests/select-tracks.test.ts
rename to packages/spf/src/media/primitives/tests/select-tracks.test.ts
index a0271221..67c3b875 100644
--- a/packages/spf/src/media/features/tests/select-tracks.test.ts
+++ b/packages/spf/src/media/primitives/tests/select-tracks.test.ts
@@ -1,5 +1,4 @@
 import { describe, expect, it } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
 import type {
   AudioSelectionSet,
   PartiallyResolvedAudioTrack,
@@ -8,15 +7,7 @@ import type {
   TextSelectionSet,
   VideoSelectionSet,
 } from '../../types';
-import {
-  pickAudioTrack,
-  pickTextTrack,
-  pickVideoTrack,
-  selectAudioTrack,
-  selectTextTrack,
-  selectVideoTrack,
-  type TrackSelectionState,
-} from '../select-tracks';
+import { pickAudioTrack, pickTextTrack, pickVideoTrack } from '../select-tracks';
 
 // Helper to create a minimal presentation
 function createPresentation(config: {
@@ -615,201 +606,3 @@ describe('pickTextTrack', () => {
     expect(selected).toBeUndefined();
   });
 });
-
-describe('selectVideoTrack', () => {
-  it('selects video track when presentation loaded', async () => {
-    const videoTracks: PartiallyResolvedVideoTrack[] = [
-      {
-        type: 'video',
-        id: 'video-360p',
-        url: 'http://example.com/360p.m3u8',
-        bandwidth: 500_000,
-        mimeType: 'video/mp4',
-        codecs: ['avc1.42E01E'],
-      },
-    ];
-
-    const presentation = createPresentation({ video: videoTracks });
-
-    const state = signal<TrackSelectionState>({ presentation });
-
-    const cleanup = selectVideoTrack({ state }, { type: 'video' });
-
-    // Wait for selection
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedVideoTrackId).toBe('video-360p');
-
-    cleanup();
-  });
-
-  it('does not select when video track already selected', async () => {
-    const presentation = createPresentation({ video: [] });
-
-    const state = signal<TrackSelectionState>({
-      presentation,
-      selectedVideoTrackId: 'existing-video',
-    });
-
-    const cleanup = selectVideoTrack({ state }, { type: 'video' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedVideoTrackId).toBe('existing-video');
-
-    cleanup();
-  });
-
-  it.skip('uses bandwidth configuration for initial selection', async () => {
-    const videoTracks: PartiallyResolvedVideoTrack[] = [
-      {
-        type: 'video',
-        id: 'video-360p',
-        url: 'http://example.com/360p.m3u8',
-        bandwidth: 500_000,
-        mimeType: 'video/mp4',
-        codecs: ['avc1.42E01E'],
-      },
-      {
-        type: 'video',
-        id: 'video-720p',
-        url: 'http://example.com/720p.m3u8',
-        bandwidth: 2_000_000,
-        mimeType: 'video/mp4',
-        codecs: ['avc1.42E01E'],
-      },
-    ];
-
-    const presentation = createPresentation({ video: videoTracks });
-
-    const state = signal<TrackSelectionState>({ presentation });
-
-    const cleanup = selectVideoTrack({ state }, { initialBandwidth: 3_000_000, type: 'video' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedVideoTrackId).toBe('video-720p');
-
-    cleanup();
-  });
-});
-
-describe('selectAudioTrack', () => {
-  it('selects audio track when presentation loaded', async () => {
-    const audioTracks: PartiallyResolvedAudioTrack[] = [
-      {
-        type: 'audio',
-        id: 'audio-en',
-        url: 'http://example.com/audio-en.m3u8',
-        bandwidth: 128_000,
-        mimeType: 'audio/mp4',
-        codecs: ['mp4a.40.2'],
-        groupId: 'audio',
-        name: 'English',
-        sampleRate: 48000,
-        channels: 2,
-      },
-    ];
-
-    const presentation = createPresentation({ audio: audioTracks });
-
-    const state = signal<TrackSelectionState>({ presentation });
-
-    const cleanup = selectAudioTrack({ state }, { type: 'audio' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedAudioTrackId).toBe('audio-en');
-
-    cleanup();
-  });
-
-  it('does not select when audio track already selected', async () => {
-    const presentation = createPresentation({ audio: [] });
-
-    const state = signal<TrackSelectionState>({
-      presentation,
-      selectedAudioTrackId: 'existing-audio',
-    });
-
-    const cleanup = selectAudioTrack({ state }, { type: 'audio' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedAudioTrackId).toBe('existing-audio');
-
-    cleanup();
-  });
-
-  it.skip('uses preferred language configuration', async () => {
-    const audioTracks: PartiallyResolvedAudioTrack[] = [
-      {
-        type: 'audio',
-        id: 'audio-en',
-        url: 'http://example.com/audio-en.m3u8',
-        bandwidth: 128_000,
-        mimeType: 'audio/mp4',
-        codecs: ['mp4a.40.2'],
-        groupId: 'audio',
-        name: 'English',
-        language: 'en',
-        sampleRate: 48000,
-        channels: 2,
-      },
-      {
-        type: 'audio',
-        id: 'audio-es',
-        url: 'http://example.com/audio-es.m3u8',
-        bandwidth: 128_000,
-        mimeType: 'audio/mp4',
-        codecs: ['mp4a.40.2'],
-        groupId: 'audio',
-        name: 'Spanish',
-        language: 'es',
-        sampleRate: 48000,
-        channels: 2,
-      },
-    ];
-
-    const presentation = createPresentation({ audio: audioTracks });
-
-    const state = signal<TrackSelectionState>({ presentation });
-
-    const cleanup = selectAudioTrack({ state }, { type: 'audio', preferredAudioLanguage: 'es' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedAudioTrackId).toBe('audio-es');
-
-    cleanup();
-  });
-});
-
-describe('selectTextTrack', () => {
-  it('does not auto-select text track', async () => {
-    const textTracks = [
-      {
-        type: 'text' as const,
-        id: 'text-en',
-        url: 'http://example.com/text-en.m3u8',
-        bandwidth: 256,
-        mimeType: 'application/mp4',
-        groupId: 'text',
-        label: 'English',
-        kind: 'subtitles' as const,
-      },
-    ];
-
-    const presentation = createPresentation({ text: textTracks });
-
-    const state = signal<TrackSelectionState>({ presentation });
-
-    const cleanup = selectTextTrack({ state }, { type: 'text' });
-
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    expect(state.get().selectedTextTrackId).toBeUndefined();
-
-    cleanup();
-  });
-});
diff --git a/packages/spf/src/media/tsconfig.json b/packages/spf/src/media/tsconfig.json
new file mode 100644
index 00000000..4db958f6
--- /dev/null
+++ b/packages/spf/src/media/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "WebWorker"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../types/media"
+  },
+  "references": [{ "path": "../../../utils" }],
+  "include": ["./**/*.ts"],
+  "exclude": ["./dom/**"]
+}
diff --git a/packages/spf/src/media/types/index.ts b/packages/spf/src/media/types/index.ts
index 23c48011..e01cf463 100644
--- a/packages/spf/src/media/types/index.ts
+++ b/packages/spf/src/media/types/index.ts
@@ -174,6 +174,32 @@ export type TextTrack = Track & {
   forced?: boolean;
 };
 
+/**
+ * Minimal text-track cue shape — start time, end time, and display text.
+ *
+ * Host-agnostic representation. `VTTCue` structurally satisfies this
+ * interface, so DOM consumers pass `VTTCue` values directly. Non-DOM
+ * hosts (workers, test fakes, non-browser engines) can satisfy the same
+ * shape without pulling in DOM types.
+ */
+export interface Cue {
+  startTime: number;
+  endTime: number;
+  text: string;
+}
+
+/**
+ * Media element with an iterable text-track list, host-agnostic.
+ *
+ * Extends `MediaElementLike` with the minimum surface needed to observe
+ * which text tracks are currently mounted on the media. `HTMLMediaElement`
+ * structurally satisfies this (its `textTracks` is a `TextTrackList`,
+ * which is iterable with `{ id }` items).
+ */
+export interface MediaElementWithTextTracks extends MediaElementLike {
+  readonly textTracks: Iterable<{ readonly id: string }>;
+}
+
 /**
  * Partially resolved text track from multivariant playlist.
  * Has metadata but no segments or initialization yet (media playlist not fetched).
@@ -306,6 +332,17 @@ export type Presentation = Ham &
     selectionSets: SelectionSet[];
   };
 
+/**
+ * State-shaped presentation that may or may not be resolved yet.
+ *
+ * The lifecycle is a single value: a caller writes `{ url }`, and the
+ * resolver populates the rest in place. `url` is always present; resolved
+ * fields (`id`, `selectionSets`, duration) appear once parsing succeeds.
+ *
+ * Use `isResolvedPresentation` to narrow to `Presentation`.
+ */
+export type MaybeResolvedPresentation = AddressableObject & Partial<Omit<Presentation, keyof AddressableObject>>;
+
 // =============================================================================
 // Type Guards
 // =============================================================================
@@ -327,7 +364,22 @@ export function isResolvedTrack(track: PartiallyResolvedTrack | ResolvedTrack):
  * Narrows type to include required duration.
  */
 export function hasPresentationDuration(
-  presentation: Presentation
-): presentation is Presentation & { duration: number } {
+  presentation: MaybeResolvedPresentation
+): presentation is MaybeResolvedPresentation & { duration: number } {
   return presentation.duration !== undefined;
 }
+
+/**
+ * Narrows a `MaybeResolvedPresentation` to a fully resolved `Presentation`.
+ *
+ * A presentation is resolved once `resolvePresentation` has parsed the
+ * manifest and populated both `id` and `selectionSets`. Both must be
+ * present — a partial value with only one of them isn't usable, and
+ * letting it through would have downstream behaviors crash when they
+ * access `selectionSets`.
+ */
+export function isResolvedPresentation(
+  presentation: MaybeResolvedPresentation | undefined
+): presentation is Presentation {
+  return presentation !== undefined && presentation.id !== undefined && presentation.selectionSets !== undefined;
+}
diff --git a/packages/spf/src/media/types/tests/guards.test.ts b/packages/spf/src/media/types/tests/guards.test.ts
index aca06628..a424f167 100644
--- a/packages/spf/src/media/types/tests/guards.test.ts
+++ b/packages/spf/src/media/types/tests/guards.test.ts
@@ -1,12 +1,13 @@
 import { describe, expect, it } from 'vitest';
 import type {
+  MaybeResolvedPresentation,
   PartiallyResolvedAudioTrack,
   PartiallyResolvedTextTrack,
   PartiallyResolvedVideoTrack,
   Presentation,
   VideoTrack,
 } from '../index';
-import { hasPresentationDuration, isResolvedTrack } from '../index';
+import { hasPresentationDuration, isResolvedPresentation, isResolvedTrack } from '../index';
 
 describe('Type Guards', () => {
   describe('isResolvedTrack', () => {
@@ -142,4 +143,73 @@ describe('Type Guards', () => {
       }
     });
   });
+
+  describe('isResolvedPresentation', () => {
+    it('returns false for undefined', () => {
+      expect(isResolvedPresentation(undefined)).toBe(false);
+    });
+
+    it('returns false for an unresolved presentation (url only)', () => {
+      const unresolved: MaybeResolvedPresentation = {
+        url: 'https://example.com/master.m3u8',
+      };
+      expect(isResolvedPresentation(unresolved)).toBe(false);
+    });
+
+    it('returns false when id is set but selectionSets is missing', () => {
+      // Guards against partial values that would crash downstream behaviors
+      // when they access selectionSets — only `id` is not enough.
+      const partial: MaybeResolvedPresentation = {
+        url: 'https://example.com/master.m3u8',
+        id: 'presentation-0',
+      };
+      expect(isResolvedPresentation(partial)).toBe(false);
+    });
+
+    it('returns false when selectionSets is set but id is missing', () => {
+      const partial: MaybeResolvedPresentation = {
+        url: 'https://example.com/master.m3u8',
+        selectionSets: [],
+      };
+      expect(isResolvedPresentation(partial)).toBe(false);
+    });
+
+    it('returns true when both id and selectionSets are present', () => {
+      const resolved: Presentation = {
+        id: 'presentation-0',
+        url: 'https://example.com/master.m3u8',
+        startTime: 0,
+        selectionSets: [],
+      };
+      expect(isResolvedPresentation(resolved)).toBe(true);
+    });
+
+    it('returns true when selectionSets is empty (still resolved)', () => {
+      // Empty selectionSets is a valid resolved manifest (no playable tracks),
+      // distinct from "selectionSets not yet known".
+      const resolved: Presentation = {
+        id: 'presentation-0',
+        url: 'https://example.com/master.m3u8',
+        startTime: 0,
+        selectionSets: [],
+      };
+      expect(isResolvedPresentation(resolved)).toBe(true);
+    });
+
+    it('narrows MaybeResolvedPresentation to Presentation', () => {
+      const presentation: MaybeResolvedPresentation = {
+        id: 'presentation-0',
+        url: 'https://example.com/master.m3u8',
+        selectionSets: [],
+      };
+
+      if (isResolvedPresentation(presentation)) {
+        // TypeScript should know presentation is Presentation here
+        const id: string = presentation.id;
+        const sets = presentation.selectionSets;
+        expect(id).toBe('presentation-0');
+        expect(sets).toBeDefined();
+      }
+    });
+  });
 });
diff --git a/packages/spf/src/media/utils/track-selection.ts b/packages/spf/src/media/utils/track-selection.ts
index 9449d644..40fe641b 100644
--- a/packages/spf/src/media/utils/track-selection.ts
+++ b/packages/spf/src/media/utils/track-selection.ts
@@ -1,10 +1,9 @@
 import type {
-  AddressableObject,
   AudioTrack,
+  MaybeResolvedPresentation,
   PartiallyResolvedAudioTrack,
   PartiallyResolvedTextTrack,
   PartiallyResolvedVideoTrack,
-  Presentation,
   TextTrack,
   TrackType,
   VideoTrack,
@@ -15,7 +14,7 @@ import type {
  * Minimal shape containing presentation and selected track IDs.
  */
 export interface TrackSelectionState {
-  presentation?: AddressableObject | Presentation | undefined;
+  presentation?: MaybeResolvedPresentation;
   selectedVideoTrackId?: string | undefined;
   selectedAudioTrackId?: string | undefined;
   selectedTextTrackId?: string | undefined;
@@ -62,8 +61,7 @@ export function getSelectedTrack<T extends TrackType>(
       : never {
   const { presentation } = state;
 
-  /** @TODO Consider moving and reusing isUnresolved(presentation) (CJP) */
-  if (!presentation || !('id' in presentation)) return undefined as any;
+  if (!presentation?.selectionSets) return undefined as any;
 
   // Get track ID based on type
   const trackIdKey = SelectedTrackIdKeyByType[type];
diff --git a/packages/spf/src/dom/network/chunked-stream-iterable.ts b/packages/spf/src/network/chunked-stream-iterable.ts
similarity index 100%
rename from packages/spf/src/dom/network/chunked-stream-iterable.ts
rename to packages/spf/src/network/chunked-stream-iterable.ts
diff --git a/packages/spf/src/dom/network/fetch.ts b/packages/spf/src/network/fetch.ts
similarity index 82%
rename from packages/spf/src/dom/network/fetch.ts
rename to packages/spf/src/network/fetch.ts
index e701b07f..7d1ebc3a 100644
--- a/packages/spf/src/dom/network/fetch.ts
+++ b/packages/spf/src/network/fetch.ts
@@ -2,12 +2,11 @@
  * HTTP Fetch Wrapper
  *
  * Two-function approach for composability:
- * 1. fetchResolvable() - Fetch AddressableObject (handles byte ranges)
+ * 1. fetchResolvable() - Fetch Resource (handles byte ranges)
  * 2. getResponseText() - Extract text from Response
  * 3. fetchResolvableStream() - Stream body as Uint8Array chunks
  */
 
-import type { AddressableObject } from '../../media/types';
 import { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';
 
 /**
@@ -19,7 +18,21 @@ export interface ResponseLike {
 }
 
 /**
- * Fetch resolvable from AddressableObject.
+ * An HTTP-addressable resource — URL plus optional byte range.
+ * Media's `AddressableObject` (and anything else with the same shape)
+ * is structurally compatible; kept local so this module stays
+ * domain-agnostic.
+ */
+export interface Resource {
+  url: string;
+  byteRange?: {
+    start: number;
+    end: number;
+  };
+}
+
+/**
+ * Fetch resolvable from a Resource.
  *
  * Handles byte range requests if byteRange is present.
  * Returns native fetch Response for composability (can extract text, stream, etc.).
@@ -38,7 +51,7 @@ export interface ResponseLike {
  *   byteRange: { start: 1000, end: 1999 }
  * });
  */
-export async function fetchResolvable(addressable: AddressableObject, options?: RequestInit): Promise<Response> {
+export async function fetchResolvable(addressable: Resource, options?: RequestInit): Promise<Response> {
   const headers = new Headers(options?.headers);
 
   // Add Range header for byte range requests
@@ -63,10 +76,7 @@ export async function fetchResolvable(addressable: AddressableObject, options?:
  * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).
  * For text or streaming consumption, use fetchResolvable directly.
  */
-export async function fetchResolvableBytes(
-  addressable: AddressableObject,
-  options?: RequestInit
-): Promise<ArrayBuffer> {
+export async function fetchResolvableBytes(addressable: Resource, options?: RequestInit): Promise<ArrayBuffer> {
   const response = await fetchResolvable(addressable, options);
   return response.arrayBuffer();
 }
@@ -82,7 +92,7 @@ export async function fetchResolvableBytes(
  * Errors from the underlying stream propagate naturally as thrown errors.
  */
 export async function* fetchResolvableStream(
-  addressable: AddressableObject,
+  addressable: Resource,
   options?: RequestInit & ChunkedStreamIterableOptions
 ): AsyncGenerator<Uint8Array> {
   const { minChunkSize, ...fetchOptions } = options ?? {};
diff --git a/packages/spf/src/dom/network/tests/chunked-stream-iterable.test.ts b/packages/spf/src/network/tests/chunked-stream-iterable.test.ts
similarity index 100%
rename from packages/spf/src/dom/network/tests/chunked-stream-iterable.test.ts
rename to packages/spf/src/network/tests/chunked-stream-iterable.test.ts
diff --git a/packages/spf/src/dom/network/tests/fetch.test.ts b/packages/spf/src/network/tests/fetch.test.ts
similarity index 91%
rename from packages/spf/src/dom/network/tests/fetch.test.ts
rename to packages/spf/src/network/tests/fetch.test.ts
index 28267d26..7469fba8 100644
--- a/packages/spf/src/dom/network/tests/fetch.test.ts
+++ b/packages/spf/src/network/tests/fetch.test.ts
@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import type { AddressableObject } from '../../../media/types';
-import type { ResponseLike } from '../fetch';
+import type { Resource, ResponseLike } from '../fetch';
 import { fetchResolvable, fetchResolvableStream, getResponseText } from '../fetch';
 
 describe('fetchResolvable', () => {
@@ -8,10 +7,10 @@ describe('fetchResolvable', () => {
     vi.restoreAllMocks();
   });
 
-  it('fetches from AddressableObject URL', async () => {
+  it('fetches from Resource URL', async () => {
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('content'));
 
-    const addressable: AddressableObject = {
+    const addressable: Resource = {
       url: 'https://example.com/playlist.m3u8',
     };
 
@@ -30,20 +29,20 @@ describe('fetchResolvable', () => {
     expect(response).toBe(mockResponse);
   });
 
-  it('accepts AddressableObject with just url', async () => {
+  it('accepts Resource with just url', async () => {
     vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(''));
 
-    const addressable: AddressableObject = {
+    const addressable: Resource = {
       url: 'https://example.com/playlist.m3u8',
     };
 
     await expect(fetchResolvable(addressable)).resolves.toBeDefined();
   });
 
-  it('accepts AddressableObject with byteRange', async () => {
+  it('accepts Resource with byteRange', async () => {
     vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(''));
 
-    const addressable: AddressableObject = {
+    const addressable: Resource = {
       url: 'https://example.com/segment.m4s',
       byteRange: { start: 1000, end: 1999 },
     };
@@ -54,7 +53,7 @@ describe('fetchResolvable', () => {
   it('handles zero-offset byte range', async () => {
     vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(''));
 
-    const addressable: AddressableObject = {
+    const addressable: Resource = {
       url: 'https://example.com/init.mp4',
       byteRange: { start: 0, end: 999 },
     };
diff --git a/packages/spf/src/network/tsconfig.json b/packages/spf/src/network/tsconfig.json
new file mode 100644
index 00000000..ae6afff8
--- /dev/null
+++ b/packages/spf/src/network/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "WebWorker"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../types/network"
+  },
+  "references": [],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/src/dom/features/segment-loader-actor.ts b/packages/spf/src/playback/actors/dom/segment-loader.ts
similarity index 97%
rename from packages/spf/src/dom/features/segment-loader-actor.ts
rename to packages/spf/src/playback/actors/dom/segment-loader.ts
index 13e3bae4..e8328fd1 100644
--- a/packages/spf/src/dom/features/segment-loader-actor.ts
+++ b/packages/spf/src/playback/actors/dom/segment-loader.ts
@@ -1,15 +1,10 @@
-import { createMachineActor, type HandlerContext, type MessageActor } from '../../core/actors/create-machine-actor';
-import { effect } from '../../core/signals/effect';
-import { SerialRunner, Task } from '../../core/tasks/task';
-import { calculateBackBufferFlushPoint } from '../../media/buffer/back-buffer';
-import { calculateForwardFlushPoint, getSegmentsToLoad } from '../../media/buffer/forward-buffer';
-import type { AddressableObject, AudioTrack, Segment, VideoTrack } from '../../media/types';
-import type {
-  AppendInitMessage,
-  AppendSegmentMessage,
-  RemoveMessage,
-  SourceBufferActor,
-} from '../media/source-buffer-actor';
+import { createMachineActor, type HandlerContext, type MessageActor } from '../../../core/actors/create-machine-actor';
+import { effect } from '../../../core/signals/effect';
+import { SerialRunner, Task } from '../../../core/tasks/task';
+import { calculateBackBufferFlushPoint } from '../../../media/buffer/back-buffer';
+import { calculateForwardFlushPoint, getSegmentsToLoad } from '../../../media/buffer/forward-buffer';
+import type { AddressableObject, AudioTrack, Segment, VideoTrack } from '../../../media/types';
+import type { AppendInitMessage, AppendSegmentMessage, RemoveMessage, SourceBufferActor } from './source-buffer';
 
 // ============================================================================
 // BUFFER STATE TYPES
diff --git a/packages/spf/src/dom/media/source-buffer-actor.ts b/packages/spf/src/playback/actors/dom/source-buffer.ts
similarity index 96%
rename from packages/spf/src/dom/media/source-buffer-actor.ts
rename to packages/spf/src/playback/actors/dom/source-buffer.ts
index aac7bb21..08c30e36 100644
--- a/packages/spf/src/dom/media/source-buffer-actor.ts
+++ b/packages/spf/src/playback/actors/dom/source-buffer.ts
@@ -1,8 +1,8 @@
-import { createMachineActor, type HandlerContext, type MessageActor } from '../../core/actors/create-machine-actor';
-import { SerialRunner, Task } from '../../core/tasks/task';
-import type { Segment, Track } from '../../media/types';
-import { type AppendData, appendSegment } from './append-segment';
-import { flushBuffer } from './buffer-flusher';
+import { createMachineActor, type HandlerContext, type MessageActor } from '../../../core/actors/create-machine-actor';
+import { SerialRunner, Task } from '../../../core/tasks/task';
+import { type AppendData, appendSegment } from '../../../media/dom/mse/append-segment';
+import { flushBuffer } from '../../../media/dom/mse/buffer-flusher';
+import type { Segment, Track } from '../../../media/types';
 
 // =============================================================================
 // Types
diff --git a/packages/spf/src/dom/media/tests/source-buffer-actor.test.ts b/packages/spf/src/playback/actors/dom/tests/source-buffer.test.ts
similarity index 99%
rename from packages/spf/src/dom/media/tests/source-buffer-actor.test.ts
rename to packages/spf/src/playback/actors/dom/tests/source-buffer.test.ts
index 3467cbf1..5c276973 100644
--- a/packages/spf/src/dom/media/tests/source-buffer-actor.test.ts
+++ b/packages/spf/src/playback/actors/dom/tests/source-buffer.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
-import { effect } from '../../../core/signals/effect';
-import { createSourceBufferActor } from '../source-buffer-actor';
+import { effect } from '../../../../core/signals/effect';
+import { createSourceBufferActor } from '../source-buffer';
 
 // ---------------------------------------------------------------------------
 // Helpers
diff --git a/packages/spf/src/dom/features/tests/text-track-mode-cue-preservation.test.ts b/packages/spf/src/playback/actors/dom/tests/text-track-mode-cue-preservation.test.ts
similarity index 100%
rename from packages/spf/src/dom/features/tests/text-track-mode-cue-preservation.test.ts
rename to packages/spf/src/playback/actors/dom/tests/text-track-mode-cue-preservation.test.ts
diff --git a/packages/spf/src/dom/features/tests/text-track-segment-loader-actor.test.ts b/packages/spf/src/playback/actors/dom/tests/text-track-segment-loader.test.ts
similarity index 80%
rename from packages/spf/src/dom/features/tests/text-track-segment-loader-actor.test.ts
rename to packages/spf/src/playback/actors/dom/tests/text-track-segment-loader.test.ts
index 74d6cde5..38459579 100644
--- a/packages/spf/src/dom/features/tests/text-track-segment-loader-actor.test.ts
+++ b/packages/spf/src/playback/actors/dom/tests/text-track-segment-loader.test.ts
@@ -1,16 +1,17 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import type { TextTrack } from '../../../media/types';
-import { createTextTrackSegmentLoaderActor } from '../text-track-segment-loader-actor';
-import { createTextTracksActor } from '../text-tracks-actor';
+import { resolveVttSegment } from '../../../../media/dom/text/resolve-vtt-segment';
+import type { TextTrack } from '../../../../media/types';
+import { createTextTrackSegmentLoaderActor } from '../../text-track-segment-loader';
+import { createTextTracksActor } from '../text-tracks';
 
-vi.mock('../../text/parse-vtt-segment', () => ({
-  parseVttSegment: vi.fn((url: string) => {
+vi.mock('../../../../media/dom/text/resolve-vtt-segment', () => ({
+  resolveVttSegment: vi.fn((url: string) => {
     if (url.includes('fail')) {
       return Promise.reject(new Error('Network error'));
     }
     return Promise.resolve([new VTTCue(0, 5, `Cue from ${url}`)]);
   }),
-  destroyVttParser: vi.fn(),
+  destroyVttResolver: vi.fn(),
 }));
 
 function makeMediaElement(trackIds: string[]): HTMLMediaElement {
@@ -55,22 +56,22 @@ describe('TextTrackSegmentLoaderActor', () => {
   it('can be created and destroyed without error', () => {
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     actor.destroy();
     textTracksActor.destroy();
   });
 
   it('does not fetch when no segments need loading', async () => {
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
 
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     const track = makeResolvedTextTrack('track-en', []);
 
     actor.send({ type: 'load', track, currentTime: 0 });
 
-    expect(parseVttSegment).not.toHaveBeenCalled();
+    expect(resolveVttSegment).not.toHaveBeenCalled();
 
     actor.destroy();
     textTracksActor.destroy();
@@ -79,7 +80,7 @@ describe('TextTrackSegmentLoaderActor', () => {
   it('delegates cue loading to TextTracksActor', async () => {
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     const track = makeResolvedTextTrack('track-en', ['https://example.com/seg-0.vtt', 'https://example.com/seg-1.vtt']);
 
     actor.send({ type: 'load', track, currentTime: 0 });
@@ -95,28 +96,28 @@ describe('TextTrackSegmentLoaderActor', () => {
   });
 
   it('skips already-loaded segments on repeat send()', async () => {
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
 
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     const track = makeResolvedTextTrack('track-en', ['https://example.com/seg-0.vtt', 'https://example.com/seg-1.vtt']);
 
     actor.send({ type: 'load', track, currentTime: 0 });
     await vi.waitFor(() => expect(textTracksActor.snapshot.get().context.segments['track-en']).toHaveLength(2));
-    expect(parseVttSegment).toHaveBeenCalledTimes(2);
+    expect(resolveVttSegment).toHaveBeenCalledTimes(2);
 
     // Repeat send — all segments already in TextTracksActor context
     actor.send({ type: 'load', track, currentTime: 0 });
-    expect(parseVttSegment).toHaveBeenCalledTimes(2);
+    expect(resolveVttSegment).toHaveBeenCalledTimes(2);
 
     actor.destroy();
     textTracksActor.destroy();
   });
 
   it('continues loading remaining segments after a fetch error', async () => {
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-    vi.mocked(parseVttSegment)
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+    vi.mocked(resolveVttSegment)
       .mockResolvedValueOnce([new VTTCue(0, 5, 'Good')])
       .mockRejectedValueOnce(new Error('Network error'))
       .mockResolvedValueOnce([new VTTCue(20, 25, 'Also good')]);
@@ -125,7 +126,7 @@ describe('TextTrackSegmentLoaderActor', () => {
 
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     const track = makeResolvedTextTrack('track-en', [
       'https://example.com/seg-0.vtt',
       'https://example.com/fail.vtt',
@@ -136,7 +137,7 @@ describe('TextTrackSegmentLoaderActor', () => {
 
     // Segments 0 and 2 succeeded; the failed segment is not recorded
     await vi.waitFor(() => expect(textTracksActor.snapshot.get().context.segments['track-en']).toHaveLength(2));
-    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to load VTT segment:', expect.any(Error));
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to load text-track segment:', expect.any(Error));
 
     consoleErrorSpy.mockRestore();
     actor.destroy();
@@ -144,10 +145,10 @@ describe('TextTrackSegmentLoaderActor', () => {
   });
 
   it('preempts in-flight work when a new send() arrives', async () => {
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
 
     let resolveSeg0!: (cues: VTTCue[]) => void;
-    vi.mocked(parseVttSegment)
+    vi.mocked(resolveVttSegment)
       .mockImplementationOnce(
         () =>
           new Promise((resolve) => {
@@ -158,7 +159,7 @@ describe('TextTrackSegmentLoaderActor', () => {
 
     const video = makeMediaElement(['track-en', 'track-es']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
 
     const track1 = makeResolvedTextTrack('track-en', ['https://example.com/seg-0.vtt']);
     const track2 = makeResolvedTextTrack('track-es', ['https://example.com/seg-1.vtt']);
@@ -167,7 +168,7 @@ describe('TextTrackSegmentLoaderActor', () => {
     actor.send({ type: 'load', track: track1, currentTime: 0 });
 
     // Wait for the Task to actually start running
-    await vi.waitFor(() => expect(parseVttSegment).toHaveBeenCalledTimes(1));
+    await vi.waitFor(() => expect(resolveVttSegment).toHaveBeenCalledTimes(1));
 
     // Switch to track2 — preempts track1
     actor.send({ type: 'load', track: track2, currentTime: 0 });
@@ -186,11 +187,11 @@ describe('TextTrackSegmentLoaderActor', () => {
   });
 
   it('does not schedule work after destroy()', async () => {
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
 
     const video = makeMediaElement(['track-en']);
     const textTracksActor = createTextTracksActor(video);
-    const actor = createTextTrackSegmentLoaderActor(textTracksActor);
+    const actor = createTextTrackSegmentLoaderActor(textTracksActor, resolveVttSegment);
     const track = makeResolvedTextTrack('track-en', ['https://example.com/seg-0.vtt']);
 
     actor.destroy();
@@ -198,7 +199,7 @@ describe('TextTrackSegmentLoaderActor', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 10));
 
-    expect(parseVttSegment).not.toHaveBeenCalled();
+    expect(resolveVttSegment).not.toHaveBeenCalled();
 
     textTracksActor.destroy();
   });
diff --git a/packages/spf/src/dom/features/tests/text-tracks-actor.test.ts b/packages/spf/src/playback/actors/dom/tests/text-tracks.test.ts
similarity index 98%
rename from packages/spf/src/dom/features/tests/text-tracks-actor.test.ts
rename to packages/spf/src/playback/actors/dom/tests/text-tracks.test.ts
index 4f17ca1c..b5573dce 100644
--- a/packages/spf/src/dom/features/tests/text-tracks-actor.test.ts
+++ b/packages/spf/src/playback/actors/dom/tests/text-tracks.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import type { CueSegmentMeta } from '../text-tracks-actor';
-import { createTextTracksActor } from '../text-tracks-actor';
+import type { CueSegmentMeta } from '../text-tracks';
+import { createTextTracksActor } from '../text-tracks';
 
 function makeMediaElement(trackIds: string[]): HTMLMediaElement {
   const video = document.createElement('video');
diff --git a/packages/spf/src/dom/features/text-tracks-actor.ts b/packages/spf/src/playback/actors/dom/text-tracks.ts
similarity index 59%
rename from packages/spf/src/dom/features/text-tracks-actor.ts
rename to packages/spf/src/playback/actors/dom/text-tracks.ts
index fcaa7218..f8709aa1 100644
--- a/packages/spf/src/dom/features/text-tracks-actor.ts
+++ b/packages/spf/src/playback/actors/dom/text-tracks.ts
@@ -1,39 +1,22 @@
-import type { TransitionActor } from '../../core/actors/create-transition-actor';
-import { createTransitionActor } from '../../core/actors/create-transition-actor';
-import type { Segment } from '../../media/types';
+import { createTransitionActor } from '../../../core/actors/create-transition-actor';
+import type { Cue } from '../../../media/types';
+import type {
+  AddCuesMessage,
+  CueSegmentMeta,
+  TextTracksActor,
+  TextTracksActorContext,
+  TextTracksActorMessage,
+} from '../text-tracks';
 
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Minimal cue record — enough for deduplication and snapshot observability. */
-export interface CueRecord {
-  startTime: number;
-  endTime: number;
-  text: string;
-}
-
-/** Segment identity and timing — mirrors AppendSegmentMeta without trackId (keyed separately). */
-export type CueSegmentMeta = Pick<Segment, 'id' | 'startTime' | 'duration'> & { trackId: string };
-
-/** Non-finite (extended) data managed by the actor — the XState "context". */
-export interface TextTracksActorContext {
-  /** Cues added per track ID. Used for duplicate detection and snapshot observability. */
-  loaded: Record<string, CueRecord[]>;
-  /** Segments whose cues have been fully added, keyed by track ID. Used for load planning. */
-  segments: Record<string, Array<Pick<Segment, 'id' | 'startTime' | 'duration'>>>;
-}
-
-export type AddCuesMessage = { type: 'add-cues'; meta: CueSegmentMeta; cues: VTTCue[] };
-export type TextTracksActorMessage = AddCuesMessage;
-
-export type TextTracksActor = TransitionActor<TextTracksActorContext, TextTracksActorMessage>;
+// Re-export the host-agnostic types so existing dom-side consumers can keep
+// importing from this module.
+export type { AddCuesMessage, CueSegmentMeta, TextTracksActor, TextTracksActorContext, TextTracksActorMessage };
 
 // =============================================================================
 // Helpers
 // =============================================================================
 
-function isDuplicateCue(cue: VTTCue, existing: CueRecord[]): boolean {
+function isDuplicateCue(cue: VTTCue, existing: Cue[]): boolean {
   return existing.some((r) => r.startTime === cue.startTime && r.endTime === cue.endTime && r.text === cue.text);
 }
 
@@ -42,7 +25,7 @@ function isDuplicateCue(cue: VTTCue, existing: CueRecord[]): boolean {
 // =============================================================================
 
 /** TextTrack actor: wraps all text tracks on a media element, owns cue operations. */
-export function createTextTracksActor(mediaElement: HTMLMediaElement): TextTracksActor {
+export function createTextTracksActor(mediaElement: HTMLMediaElement): TextTracksActor<VTTCue> {
   return createTransitionActor({ loaded: {}, segments: {} } as TextTracksActorContext, (context, message) => {
     // NOTE: Currently assumes cues are applied to a non-disabled TextTrack. Discuss different approaches here, including:
     // - Making the message responsible for auto-selection of the textTrack (changes logic in sync-text-tracks)
diff --git a/packages/spf/src/playback/actors/dom/tsconfig.json b/packages/spf/src/playback/actors/dom/tsconfig.json
new file mode 100644
index 00000000..a7004700
--- /dev/null
+++ b/packages/spf/src/playback/actors/dom/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../../types/playback/actors/dom"
+  },
+  "references": [
+    { "path": "../../../../../utils" },
+    { "path": "../../../core" },
+    { "path": "../../../network" },
+    { "path": "../../../media" },
+    { "path": "../../../media/dom" },
+    { "path": "../" }
+  ],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/src/dom/features/text-track-segment-loader-actor.ts b/packages/spf/src/playback/actors/text-track-segment-loader.ts
similarity index 60%
rename from packages/spf/src/dom/features/text-track-segment-loader-actor.ts
rename to packages/spf/src/playback/actors/text-track-segment-loader.ts
index c268f1e6..707c324c 100644
--- a/packages/spf/src/dom/features/text-track-segment-loader-actor.ts
+++ b/packages/spf/src/playback/actors/text-track-segment-loader.ts
@@ -2,12 +2,11 @@ import type { CallbackActor } from '../../core/actors/actor';
 import { untrack } from '../../core/signals/primitives';
 import { SerialRunner, Task } from '../../core/tasks/task';
 import { getSegmentsToLoad } from '../../media/buffer/forward-buffer';
-import type { TextTrack } from '../../media/types';
-import { parseVttSegment } from '../text/parse-vtt-segment';
-import type { TextTracksActor } from './text-tracks-actor';
+import type { Cue, TextTrack } from '../../media/types';
+import type { TextTracksActor } from './text-tracks';
 
 // =============================================================================
-// Types
+// Message / actor types
 // =============================================================================
 
 export type TextTrackSegmentLoaderMessage = {
@@ -18,20 +17,37 @@ export type TextTrackSegmentLoaderMessage = {
 
 export type TextTrackSegmentLoaderActor = CallbackActor<TextTrackSegmentLoaderMessage>;
 
+/**
+ * Resolves a text-track segment URL into the array of cues it contains.
+ *
+ * "Resolve" because the fn covers both network fetch and parse into the
+ * domain model. Host-agnostic — the concrete resolver (e.g. the
+ * browser's native VTT resolver) is supplied at engine-assembly time,
+ * so this actor stays DOM-free.
+ */
+export type TextTrackSegmentResolver<C extends Cue = Cue> = (url: string) => Promise<C[]>;
+
 // =============================================================================
 // Implementation
 // =============================================================================
 
 /**
- * Loads VTT segments for a text track and delegates cue management to a
- * TextTracksActor. Mirrors the SegmentLoaderActor/SourceBufferActor pattern
- * for the text track equivalent.
+ * Loads text-track segments for a track and delegates cue management
+ * to a TextTracksActor. Mirrors the SegmentLoaderActor/SourceBufferActor
+ * pattern for the text-track equivalent.
  *
  * Planning is done in the load handler: segments already recorded in
- * TextTracksActor's context are skipped. Each load preempts in-flight work
- * via abortAll() before scheduling fresh tasks.
+ * TextTracksActor's context are skipped. Each load preempts in-flight
+ * work via abortAll() before scheduling fresh tasks.
+ *
+ * The cue parser is injected so this factory is host-agnostic. A DOM
+ * host supplies a VTT parser backed by `<track>`/`TextTrack` APIs; a
+ * non-DOM host (worker, test fake, alternate runtime) supplies its own.
  */
-export function createTextTrackSegmentLoaderActor(textTracksActor: TextTracksActor): TextTrackSegmentLoaderActor {
+export function createTextTrackSegmentLoaderActor<C extends Cue>(
+  textTracksActor: TextTracksActor<C>,
+  resolveSegment: TextTrackSegmentResolver<C>
+): TextTrackSegmentLoaderActor {
   const runner = new SerialRunner();
   let destroyed = false;
 
@@ -48,7 +64,7 @@ export function createTextTrackSegmentLoaderActor(textTracksActor: TextTracksAct
           new Task(async (signal) => {
             if (signal.aborted) return;
             try {
-              const cues = await parseVttSegment(segment.url);
+              const cues = await resolveSegment(segment.url);
               if (signal.aborted) return;
               textTracksActor.send({
                 type: 'add-cues',
@@ -57,7 +73,7 @@ export function createTextTrackSegmentLoaderActor(textTracksActor: TextTracksAct
               });
             } catch (error) {
               // Graceful degradation: log and continue to the next segment.
-              console.error('Failed to load VTT segment:', error);
+              console.error('Failed to load text-track segment:', error);
             }
           })
         );
diff --git a/packages/spf/src/playback/actors/text-tracks.ts b/packages/spf/src/playback/actors/text-tracks.ts
new file mode 100644
index 00000000..2a220bfa
--- /dev/null
+++ b/packages/spf/src/playback/actors/text-tracks.ts
@@ -0,0 +1,33 @@
+import type { TransitionActor } from '../../core/actors/create-transition-actor';
+import type { Cue, Segment } from '../../media/types';
+
+// =============================================================================
+// Message / context shapes
+// =============================================================================
+
+/** Segment identity and timing — mirrors AppendSegmentMeta without trackId (keyed separately). */
+export type CueSegmentMeta = Pick<Segment, 'id' | 'startTime' | 'duration'> & { trackId: string };
+
+/** Non-finite (extended) data managed by the actor — the XState "context". */
+export interface TextTracksActorContext {
+  /** Cues added per track ID. Used for duplicate detection and snapshot observability. */
+  loaded: Record<string, Cue[]>;
+  /** Segments whose cues have been fully added, keyed by track ID. Used for load planning. */
+  segments: Record<string, Array<Pick<Segment, 'id' | 'startTime' | 'duration'>>>;
+}
+
+export interface AddCuesMessage<C extends Cue = Cue> {
+  type: 'add-cues';
+  meta: CueSegmentMeta;
+  cues: C[];
+}
+
+export type TextTracksActorMessage<C extends Cue = Cue> = AddCuesMessage<C>;
+
+/**
+ * Host-agnostic text-track actor type.
+ *
+ * Generic over the concrete cue shape `C` so DOM hosts (using `VTTCue`)
+ * and non-DOM hosts (custom cue representations) can both satisfy it.
+ */
+export type TextTracksActor<C extends Cue = Cue> = TransitionActor<TextTracksActorContext, TextTracksActorMessage<C>>;
diff --git a/packages/spf/src/playback/actors/tsconfig.json b/packages/spf/src/playback/actors/tsconfig.json
new file mode 100644
index 00000000..fe864a4e
--- /dev/null
+++ b/packages/spf/src/playback/actors/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "WebWorker"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../types/playback/actors"
+  },
+  "references": [{ "path": "../../../../utils" }, { "path": "../../core" }, { "path": "../../media" }],
+  "include": ["./*.ts", "./tests/**/*.ts"],
+  "exclude": ["./dom/**"]
+}
diff --git a/packages/spf/src/media/features/calculate-presentation-duration.ts b/packages/spf/src/playback/behaviors/calculate-presentation-duration.ts
similarity index 91%
rename from packages/spf/src/media/features/calculate-presentation-duration.ts
rename to packages/spf/src/playback/behaviors/calculate-presentation-duration.ts
index 119e3380..c53c0463 100644
--- a/packages/spf/src/media/features/calculate-presentation-duration.ts
+++ b/packages/spf/src/playback/behaviors/calculate-presentation-duration.ts
@@ -1,11 +1,11 @@
 import { effect } from '../../core/signals/effect';
 import type { Signal } from '../../core/signals/primitives';
-import type { AudioTrack, Presentation, VideoTrack } from '../types';
-import { isResolvedTrack } from '../types';
-import { getSelectedTrack } from '../utils/track-selection';
+import type { AudioTrack, MaybeResolvedPresentation, VideoTrack } from '../../media/types';
+import { isResolvedTrack } from '../../media/types';
+import { getSelectedTrack } from '../../media/utils/track-selection';
 
 export interface PresentationDurationState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
   selectedVideoTrackId?: string;
   selectedAudioTrackId?: string;
 }
diff --git a/packages/spf/src/dom/features/end-of-stream.ts b/packages/spf/src/playback/behaviors/dom/end-of-stream.ts
similarity index 92%
rename from packages/spf/src/dom/features/end-of-stream.ts
rename to packages/spf/src/playback/behaviors/dom/end-of-stream.ts
index ae90c341..c794fcb3 100644
--- a/packages/spf/src/dom/features/end-of-stream.ts
+++ b/packages/spf/src/playback/behaviors/dom/end-of-stream.ts
@@ -1,18 +1,18 @@
-import { effect } from '../../core/signals/effect';
-import { computed, type ReadonlySignal, type Signal } from '../../core/signals/primitives';
-import type { Presentation } from '../../media/types';
-import { isResolvedTrack } from '../../media/types';
-import { getSelectedTrack, type TrackSelectionState } from '../../media/utils/track-selection';
-import type { SourceBufferActor } from '../media/source-buffer-actor';
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal } from '../../../core/signals/primitives';
+import type { MaybeResolvedPresentation } from '../../../media/types';
+import { isResolvedTrack } from '../../../media/types';
+import { getSelectedTrack, type TrackSelectionState } from '../../../media/utils/track-selection';
+import type { SourceBufferActor } from '../../actors/dom/source-buffer';
 
 export interface EndOfStreamState extends TrackSelectionState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
+  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
+  mediaSourceReadyState?: MediaSource['readyState'];
 }
 
 export interface EndOfStreamOwners {
   mediaSource?: MediaSource;
-  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
-  mediaSourceReadyState?: ReadonlySignal<MediaSource['readyState']>;
   mediaElement?: HTMLMediaElement | undefined;
   videoBuffer?: SourceBuffer;
   audioBuffer?: SourceBuffer;
@@ -111,10 +111,9 @@ export function shouldEndStream(state: EndOfStreamState, owners: EndOfStreamOwne
 
   const { mediaElement } = owners;
 
-  // MediaSource must be open — use reactive readyState signal when available
-  // so the computed re-evaluates when readyState changes (e.g. 'ended' → 'open' on seek-back).
-  const readyState = owners.mediaSourceReadyState?.get() ?? owners.mediaSource?.readyState;
-  if (readyState !== 'open') return false;
+  // MediaSource must be open — read from state.mediaSourceReadyState so the
+  // computed re-evaluates when readyState changes (e.g. 'ended' → 'open' on seek-back).
+  if (state.mediaSourceReadyState !== 'open') return false;
 
   // CRITICAL: MediaElement must have metadata before calling endOfStream
   // Calling endOfStream before HAVE_METADATA causes DEMUXER_ERROR
@@ -286,8 +285,7 @@ export function endOfStream<S extends EndOfStreamState, O extends EndOfStreamOwn
       // readyState is 'ended' automatically transitions it back to 'open'.
       // This happens on seek-back after end-of-stream — allow endOfStream()
       // to be called again once the last segment is reloaded.
-      const readyState = currentOwners.mediaSourceReadyState?.get() ?? currentOwners.mediaSource?.readyState;
-      if (readyState !== 'open') return;
+      if (state.get().mediaSourceReadyState !== 'open') return;
       hasEnded = false;
     }
 
diff --git a/packages/spf/src/dom/features/load-segments.ts b/packages/spf/src/playback/behaviors/dom/load-segments.ts
similarity index 94%
rename from packages/spf/src/dom/features/load-segments.ts
rename to packages/spf/src/playback/behaviors/dom/load-segments.ts
index 1b46e96f..d9295b67 100644
--- a/packages/spf/src/dom/features/load-segments.ts
+++ b/packages/spf/src/playback/behaviors/dom/load-segments.ts
@@ -1,19 +1,19 @@
-import { effect } from '../../core/signals/effect';
-import { computed, type Signal, signal } from '../../core/signals/primitives';
-import { type BandwidthState, sampleBandwidth } from '../../media/abr/bandwidth-estimator';
-import { DEFAULT_FORWARD_BUFFER_CONFIG } from '../../media/buffer/forward-buffer';
-import type { AddressableObject, Presentation, ResolvedTrack } from '../../media/types';
-import { isResolvedTrack } from '../../media/types';
-import { getSelectedTrack, type TrackSelectionState } from '../../media/utils/track-selection';
-import type { SourceBufferActor } from '../media/source-buffer-actor';
-import { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from '../network/chunked-stream-iterable';
-import { fetchResolvable } from '../network/fetch';
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal, signal } from '../../../core/signals/primitives';
+import { type BandwidthState, sampleBandwidth } from '../../../media/abr/bandwidth-estimator';
+import { DEFAULT_FORWARD_BUFFER_CONFIG } from '../../../media/buffer/forward-buffer';
+import type { AddressableObject, MaybeResolvedPresentation, ResolvedTrack } from '../../../media/types';
+import { isResolvedTrack } from '../../../media/types';
+import { getSelectedTrack, type TrackSelectionState } from '../../../media/utils/track-selection';
+import { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from '../../../network/chunked-stream-iterable';
+import { fetchResolvable } from '../../../network/fetch';
 import {
   type BufferState,
   createSegmentLoaderActor,
   type SegmentLoaderActor,
   type SourceBufferState,
-} from './segment-loader-actor';
+} from '../../actors/dom/segment-loader';
+import type { SourceBufferActor } from '../../actors/dom/source-buffer';
 import type { MediaTrackType } from './setup-sourcebuffer';
 
 // Re-export buffer state types for consumers that import them from this module.
@@ -92,7 +92,7 @@ async function fetchStream(addressable: AddressableObject, options?: FetchOption
  * State shape for segment loading.
  */
 export interface SegmentLoadingState extends TrackSelectionState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
   preload?: string;
   bandwidthState?: BandwidthState;
   /** Current playback position in seconds. Defaults to 0 when undefined. */
diff --git a/packages/spf/src/dom/features/setup-mediasource.ts b/packages/spf/src/playback/behaviors/dom/setup-mediasource.ts
similarity index 72%
rename from packages/spf/src/dom/features/setup-mediasource.ts
rename to packages/spf/src/playback/behaviors/dom/setup-mediasource.ts
index 8c8c4b09..ea133c38 100644
--- a/packages/spf/src/dom/features/setup-mediasource.ts
+++ b/packages/spf/src/playback/behaviors/dom/setup-mediasource.ts
@@ -1,13 +1,19 @@
-import { effect } from '../../core/signals/effect';
-import { computed, type ReadonlySignal, type Signal } from '../../core/signals/primitives';
-import type { Presentation } from '../../media/types';
-import { attachMediaSource, createMediaSource, observeMediaSourceReadyState } from '../media/mediasource-setup';
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal, update } from '../../../core/signals/primitives';
+import {
+  attachMediaSource,
+  createMediaSource,
+  onMediaSourceReadyStateChange,
+} from '../../../media/dom/mse/mediasource-setup';
+import type { MaybeResolvedPresentation } from '../../../media/types';
 
 /**
  * State shape required for MediaSource setup.
  */
 export interface MediaSourceState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
+  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
+  mediaSourceReadyState?: MediaSource['readyState'];
 }
 
 /**
@@ -16,8 +22,6 @@ export interface MediaSourceState {
 export interface MediaSourceOwners {
   mediaElement?: HTMLMediaElement | undefined;
   mediaSource?: MediaSource;
-  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
-  mediaSourceReadyState?: ReadonlySignal<MediaSource['readyState']>;
 }
 
 /**
@@ -55,17 +59,20 @@ export function setupMediaSource<S extends MediaSourceState, O extends MediaSour
   const cleanupEffect = effect(() => {
     if (!canSetupSignal.get() || !shouldSetupSignal.get()) return;
     const mediaElement = mediaElementSignal.get() as HTMLMediaElement;
-    const { signal } = abortController;
+    const { signal: abortSignal } = abortController;
 
     const mediaSource = createMediaSource({ preferManaged: true });
     // NOTE: Consider making MediaSource an Actor and using this in it.
-    const mediaSourceReadyState = observeMediaSourceReadyState(mediaSource, signal);
+    update(state, { mediaSourceReadyState: mediaSource.readyState } as Partial<S>);
+    onMediaSourceReadyStateChange(mediaSource, abortSignal, (readyState) => {
+      update(state, { mediaSourceReadyState: readyState } as Partial<S>);
+    });
     attachMediaSource(mediaSource, mediaElement);
 
     const cleanupOwnersUpdateEffect = effect(() => {
       // If we already have a MediaSource or the *internal* mediaSource is not yet fully attached, wait to add it to owners;
-      if (!!mediaSourceSignal.get() || mediaSourceReadyState.get() !== 'open') return;
-      owners.set(Object.assign({}, owners.get(), { mediaSource, mediaSourceReadyState }) as O);
+      if (!!mediaSourceSignal.get() || state.get().mediaSourceReadyState !== 'open') return;
+      owners.set(Object.assign({}, owners.get(), { mediaSource }) as O);
     });
 
     return () => {
diff --git a/packages/spf/src/dom/features/setup-sourcebuffer.ts b/packages/spf/src/playback/behaviors/dom/setup-sourcebuffer.ts
similarity index 88%
rename from packages/spf/src/dom/features/setup-sourcebuffer.ts
rename to packages/spf/src/playback/behaviors/dom/setup-sourcebuffer.ts
index 9a73edd7..0d6cb03b 100644
--- a/packages/spf/src/dom/features/setup-sourcebuffer.ts
+++ b/packages/spf/src/playback/behaviors/dom/setup-sourcebuffer.ts
@@ -1,10 +1,10 @@
-import { effect } from '../../core/signals/effect';
-import { computed, type Signal, update } from '../../core/signals/primitives';
-import type { Presentation, ResolvedTrack } from '../../media/types';
-import { isResolvedTrack } from '../../media/types';
-import { BufferKeyByType, getSelectedTrack, type TrackSelectionState } from '../../media/utils/track-selection';
-import { createSourceBuffer } from '../media/mediasource-setup';
-import { createSourceBufferActor, type SourceBufferActor } from '../media/source-buffer-actor';
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal, update } from '../../../core/signals/primitives';
+import { createSourceBuffer } from '../../../media/dom/mse/mediasource-setup';
+import type { MaybeResolvedPresentation, ResolvedTrack } from '../../../media/types';
+import { isResolvedTrack } from '../../../media/types';
+import { BufferKeyByType, getSelectedTrack, type TrackSelectionState } from '../../../media/utils/track-selection';
+import { createSourceBufferActor, type SourceBufferActor } from '../../actors/dom/source-buffer';
 
 /**
  * Media track type for SourceBuffer setup.
@@ -21,7 +21,7 @@ const ActorKeyByType = {
  * State shape for SourceBuffer setup.
  */
 export interface SourceBufferState extends TrackSelectionState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
   selectedVideoTrackId?: string;
   selectedAudioTrackId?: string;
 }
@@ -78,7 +78,7 @@ export function setupSourceBuffers<S extends SourceBufferState, O extends Source
   // Derive which media track types this presentation actually contains
   const presentationTypesSignal = computed((): MediaTrackType[] => {
     const { presentation } = state.get();
-    if (!presentation || !('selectionSets' in presentation)) return [];
+    if (!presentation?.selectionSets) return [];
     return presentation.selectionSets
       .map(({ type }) => type)
       .filter((type): type is MediaTrackType => type === 'video' || type === 'audio');
diff --git a/packages/spf/src/playback/behaviors/dom/setup-text-track-actors.ts b/packages/spf/src/playback/behaviors/dom/setup-text-track-actors.ts
new file mode 100644
index 00000000..cb95adeb
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/dom/setup-text-track-actors.ts
@@ -0,0 +1,80 @@
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal, update } from '../../../core/signals/primitives';
+import { createTextTracksActor } from '../../actors/dom/text-tracks';
+import {
+  createTextTrackSegmentLoaderActor,
+  type TextTrackSegmentLoaderActor,
+  type TextTrackSegmentResolver,
+} from '../../actors/text-track-segment-loader';
+import type { TextTracksActor } from '../../actors/text-tracks';
+
+/**
+ * Owners shape for text-track actors setup.
+ *
+ * Mirrors the shape `loadTextTrackCues` expects, but with `mediaElement`
+ * typed as `HTMLMediaElement` (the concrete input the DOM factory needs)
+ * and the actors parameterized over `VTTCue` (what the DOM factory produces).
+ */
+export interface TextTrackActorsOwners {
+  mediaElement?: HTMLMediaElement | undefined;
+  textTracksActor?: TextTracksActor<VTTCue> | undefined;
+  segmentLoaderActor?: TextTrackSegmentLoaderActor | undefined;
+}
+
+/**
+ * Config for text-track actors setup.
+ *
+ * The cue parser is the only piece that genuinely needs the host's
+ * capabilities; injecting it via config means this behavior binds only
+ * `createTextTracksActor` internally (which needs the `HTMLMediaElement`
+ * argument) and relies on the composition assembler to supply the parser.
+ */
+export interface TextTrackActorsConfig {
+  resolveTextTrackSegment: TextTrackSegmentResolver<VTTCue>;
+}
+
+/**
+ * Setup text-track actors orchestration.
+ *
+ * Creates the `TextTracksActor` (bound to the element's `textTracks`) and
+ * the `TextTrackSegmentLoaderActor` (bound to the supplied cue parser)
+ * whenever a media element is available; the effect's cleanup destroys them
+ * on change or unmount.
+ *
+ * Subscribes to a `computed` projection of `mediaElement` rather than the
+ * full owners signal, so writing the actor slots back to `owners` from
+ * inside the effect does not re-trigger it.
+ *
+ * Pairs with the host-agnostic `loadTextTrackCues` behavior in
+ * `behaviors/`: this setup manages actor lifecycle, the loader
+ * orchestrates state transitions and dispatches load messages.
+ *
+ * @example
+ * createComposition([setupTextTrackActors, loadTextTrackCues, ...], {
+ *   config: { resolveTextTrackSegment: resolveVttSegment },
+ * });
+ */
+export function setupTextTrackActors<O extends TextTrackActorsOwners>({
+  owners,
+  config,
+}: {
+  owners: Signal<O>;
+  config: TextTrackActorsConfig;
+}): () => void {
+  const mediaElementSignal = computed(() => owners.get().mediaElement);
+
+  return effect(() => {
+    const mediaElement = mediaElementSignal.get();
+    if (!mediaElement) return;
+
+    const textTracksActor = createTextTracksActor(mediaElement);
+    const segmentLoaderActor = createTextTrackSegmentLoaderActor(textTracksActor, config.resolveTextTrackSegment);
+    update(owners, { textTracksActor, segmentLoaderActor } as Partial<O>);
+
+    return () => {
+      textTracksActor.destroy();
+      segmentLoaderActor.destroy();
+      update(owners, { textTracksActor: undefined, segmentLoaderActor: undefined } as Partial<O>);
+    };
+  });
+}
diff --git a/packages/spf/src/dom/features/sync-text-tracks.ts b/packages/spf/src/playback/behaviors/dom/sync-text-tracks.ts
similarity index 93%
rename from packages/spf/src/dom/features/sync-text-tracks.ts
rename to packages/spf/src/playback/behaviors/dom/sync-text-tracks.ts
index 635edacc..854c7186 100644
--- a/packages/spf/src/dom/features/sync-text-tracks.ts
+++ b/packages/spf/src/playback/behaviors/dom/sync-text-tracks.ts
@@ -1,8 +1,8 @@
 import { listen } from '@videojs/utils/dom';
-import type { Reactor } from '../../core/reactors/create-machine-reactor';
-import { createMachineReactor } from '../../core/reactors/create-machine-reactor';
-import { computed, type Signal, untrack, update } from '../../core/signals/primitives';
-import type { PartiallyResolvedTextTrack, Presentation, TextTrack } from '../../media/types';
+import type { Reactor } from '../../../core/reactors/create-machine-reactor';
+import { createMachineReactor } from '../../../core/reactors/create-machine-reactor';
+import { computed, type Signal, untrack, update } from '../../../core/signals/primitives';
+import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../../../media/types';
 
 /**
  * FSM states for text track sync.
@@ -19,7 +19,7 @@ import type { PartiallyResolvedTextTrack, Presentation, TextTrack } from '../../
  * State shape for text track sync.
  */
 export interface TextTrackSyncState {
-  presentation?: Presentation | undefined;
+  presentation?: MaybeResolvedPresentation;
   selectedTextTrackId?: string | undefined;
 }
 
@@ -46,7 +46,7 @@ function createTrackElement(track: PartiallyResolvedTextTrack | TextTrack): HTML
 }
 
 function getModelTextTracks(
-  presentation: Presentation | undefined
+  presentation: MaybeResolvedPresentation | undefined
 ): (PartiallyResolvedTextTrack | TextTrack)[] | undefined {
   return presentation?.selectionSets?.find((s) => s.type === 'text')?.switchingSets[0]?.tracks;
 }
diff --git a/packages/spf/src/dom/tests/end-of-stream.test.ts b/packages/spf/src/playback/behaviors/dom/tests/end-of-stream-partial-resolution.test.ts
similarity index 96%
rename from packages/spf/src/dom/tests/end-of-stream.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/end-of-stream-partial-resolution.test.ts
index e965e746..97d8fdcc 100644
--- a/packages/spf/src/dom/tests/end-of-stream.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/end-of-stream-partial-resolution.test.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import type { PartiallyResolvedVideoTrack, Presentation, VideoSelectionSet } from '../../media/types';
-import type { EndOfStreamOwners, EndOfStreamState } from '../features/end-of-stream';
-import { hasLastSegmentLoaded } from '../features/end-of-stream';
-import { createSourceBufferActor } from '../media/source-buffer-actor';
+import type { PartiallyResolvedVideoTrack, Presentation, VideoSelectionSet } from '../../../../media/types';
+import { createSourceBufferActor } from '../../../actors/dom/source-buffer';
+import type { EndOfStreamOwners, EndOfStreamState } from '../end-of-stream';
+import { hasLastSegmentLoaded } from '../end-of-stream';
 
 // ============================================================================
 // Helpers
diff --git a/packages/spf/src/dom/features/tests/end-of-stream.test.ts b/packages/spf/src/playback/behaviors/dom/tests/end-of-stream.test.ts
similarity index 95%
rename from packages/spf/src/dom/features/tests/end-of-stream.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/end-of-stream.test.ts
index cbfbc605..dc2d51f0 100644
--- a/packages/spf/src/dom/features/tests/end-of-stream.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/end-of-stream.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { Presentation, Segment, VideoTrack } from '../../../media/types';
-import { createSourceBufferActor, type SourceBufferActor } from '../../media/source-buffer-actor';
+import { signal } from '../../../../core/signals/primitives';
+import type { Presentation, Segment, VideoTrack } from '../../../../media/types';
+import { createSourceBufferActor, type SourceBufferActor } from '../../../actors/dom/source-buffer';
 import {
   canEndStream,
   type EndOfStreamOwners,
@@ -12,7 +12,10 @@ import {
 } from '../end-of-stream';
 
 function setupEndOfStream(initialState: EndOfStreamState, initialOwners: EndOfStreamOwners) {
-  const state = signal<EndOfStreamState>(initialState);
+  // Default mediaSourceReadyState to 'open' to mirror what setupMediaSource
+  // would have written. Tests that exercise other readyState values pass it
+  // explicitly.
+  const state = signal<EndOfStreamState>({ mediaSourceReadyState: 'open', ...initialState });
   const owners = signal<EndOfStreamOwners>(initialOwners);
   const cleanup = endOfStream({ state, owners });
   return { state, owners, cleanup };
@@ -278,6 +281,7 @@ describe('shouldEndStream', () => {
     const state: EndOfStreamState = {
       selectedVideoTrackId: 'video-1',
       presentation: makePresentation(track),
+      mediaSourceReadyState: 'ended',
     };
     expect(
       shouldEndStream(state, {
@@ -333,6 +337,7 @@ describe('shouldEndStream', () => {
     const state: EndOfStreamState = {
       selectedVideoTrackId: 'video-1',
       presentation: makePresentation(track),
+      mediaSourceReadyState: 'open',
     };
     expect(
       shouldEndStream(state, {
@@ -348,6 +353,7 @@ describe('shouldEndStream', () => {
     const state: EndOfStreamState = {
       selectedVideoTrackId: 'video-1',
       presentation: makePresentation(track),
+      mediaSourceReadyState: 'open',
     };
     expect(
       shouldEndStream(state, {
@@ -454,36 +460,37 @@ describe('endOfStream', () => {
   it('calls endOfStream() again after seek-back re-opens the MediaSource', async () => {
     const track = makeResolvedVideoTrack(4);
     const mockMs = makeMediaSource();
-    // Reactive readyState signal — drives re-evaluation when MSE transitions readyState.
-    const msReadyState = signal<MediaSource['readyState']>('open');
 
-    // Simulate real MSE: endOfStream() transitions readyState to 'ended'.
-    (mockMs.endOfStream as ReturnType<typeof vi.fn>).mockImplementation(() => {
-      (mockMs as unknown as { readyState: string }).readyState = 'ended';
-      msReadyState.set('ended');
-    });
-
-    const { cleanup } = setupEndOfStream(
-      { selectedVideoTrackId: 'video-1', presentation: makePresentation(track) },
+    const { state, cleanup } = setupEndOfStream(
+      {
+        selectedVideoTrackId: 'video-1',
+        presentation: makePresentation(track),
+        mediaSourceReadyState: 'open',
+      },
       {
         mediaSource: mockMs,
-        mediaSourceReadyState: msReadyState,
         videoBuffer: makeSourceBuffer(),
         videoBufferActor: makeActorWithSegments(['seg-0', 'seg-1', 'seg-2', 'seg-3']),
       }
     );
 
+    // Simulate real MSE: endOfStream() transitions readyState to 'ended'.
+    (mockMs.endOfStream as ReturnType<typeof vi.fn>).mockImplementation(() => {
+      (mockMs as unknown as { readyState: string }).readyState = 'ended';
+      state.set({ ...state.get(), mediaSourceReadyState: 'ended' });
+    });
+
     // First play-through: endOfStream() is called, readyState transitions to 'ended'.
     await vi.waitFor(() => {
       expect(mockMs.endOfStream).toHaveBeenCalledTimes(1);
     });
 
     // Simulate seek-back: appendBuffer() re-opens the MediaSource per MSE spec.
-    // The reactive signal update drives re-evaluation — no owners.patch needed.
+    // The state update drives re-evaluation.
     (mockMs as unknown as { readyState: string }).readyState = 'open';
-    msReadyState.set('open');
+    state.set({ ...state.get(), mediaSourceReadyState: 'open' });
 
-    // endOfStream() should be called again driven purely by the readyState signal.
+    // endOfStream() should be called again driven purely by the state update.
     await vi.waitFor(() => {
       expect(mockMs.endOfStream).toHaveBeenCalledTimes(2);
     });
diff --git a/packages/spf/src/dom/tests/load-segments-track-switch.test.ts b/packages/spf/src/playback/behaviors/dom/tests/load-segments-track-switch.test.ts
similarity index 94%
rename from packages/spf/src/dom/tests/load-segments-track-switch.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/load-segments-track-switch.test.ts
index 6e524dfe..2d0b9bd4 100644
--- a/packages/spf/src/dom/tests/load-segments-track-switch.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/load-segments-track-switch.test.ts
@@ -1,19 +1,19 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { signal } from '../../core/signals/primitives';
-import type { Presentation, VideoSelectionSet } from '../../media/types';
-import type { SegmentLoadingOwners, SegmentLoadingState } from '../features/load-segments';
-import { loadSegments } from '../features/load-segments';
-import { createSourceBufferActor } from '../media/source-buffer-actor';
+import { signal } from '../../../../core/signals/primitives';
+import type { Presentation, VideoSelectionSet } from '../../../../media/types';
+import { createSourceBufferActor } from '../../../actors/dom/source-buffer';
+import type { SegmentLoadingOwners, SegmentLoadingState } from '../load-segments';
+import { loadSegments } from '../load-segments';
 
 // ============================================================================
 // Mocks
 // ============================================================================
 
-vi.mock('../media/append-segment', () => ({
+vi.mock('../../../../media/dom/mse/append-segment', () => ({
   appendSegment: vi.fn().mockResolvedValue(undefined),
 }));
 
-vi.mock('../media/buffer-flusher', () => ({
+vi.mock('../../../../media/dom/mse/buffer-flusher', () => ({
   flushBuffer: vi.fn().mockResolvedValue(undefined),
 }));
 
@@ -113,7 +113,7 @@ describe('loadSegments — track switch', () => {
   });
 
   it('does not flush SourceBuffer on track switch; new content overwrites old via deduplication', async () => {
-    const { flushBuffer } = await import('../media/buffer-flusher');
+    const { flushBuffer } = await import('../../../../media/dom/mse/buffer-flusher');
     const flushSpy = vi.mocked(flushBuffer);
 
     const trackA = makeResolvedVideoTrack('track-a', [seg('a1', 0), seg('a2', 10)]);
@@ -271,7 +271,7 @@ describe('loadSegments — track switch', () => {
   });
 
   it('does NOT flush on first init load (no prior track)', async () => {
-    const { flushBuffer } = await import('../media/buffer-flusher');
+    const { flushBuffer } = await import('../../../../media/dom/mse/buffer-flusher');
     const flushSpy = vi.mocked(flushBuffer);
 
     const trackA = makeResolvedVideoTrack('track-a', [seg('a1', 0)]);
diff --git a/packages/spf/src/dom/features/tests/load-segments.test.ts b/packages/spf/src/playback/behaviors/dom/tests/load-segments.test.ts
similarity index 99%
rename from packages/spf/src/dom/features/tests/load-segments.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/load-segments.test.ts
index f185af5a..16ae1eac 100644
--- a/packages/spf/src/dom/features/tests/load-segments.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/load-segments.test.ts
@@ -3,9 +3,9 @@
  */
 
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { Segment } from '../../../media/types';
-import { createSourceBufferActor } from '../../media/source-buffer-actor';
+import { signal } from '../../../../core/signals/primitives';
+import type { Segment } from '../../../../media/types';
+import { createSourceBufferActor } from '../../../actors/dom/source-buffer';
 import { loadSegments, type SegmentLoadingOwners, type SegmentLoadingState } from '../load-segments';
 
 // ---------------------------------------------------------------------------
diff --git a/packages/spf/src/dom/features/tests/load-text-track-cues.test.ts b/packages/spf/src/playback/behaviors/dom/tests/load-text-track-cues.test.ts
similarity index 71%
rename from packages/spf/src/dom/features/tests/load-text-track-cues.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/load-text-track-cues.test.ts
index 379a37bc..5dce8dfc 100644
--- a/packages/spf/src/dom/features/tests/load-text-track-cues.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/load-text-track-cues.test.ts
@@ -1,21 +1,29 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { Presentation, Segment, TextTrack } from '../../../media/types';
+import { signal } from '../../../../core/signals/primitives';
+import { resolveVttSegment } from '../../../../media/dom/text/resolve-vtt-segment';
+import type { Presentation, Segment, TextTrack } from '../../../../media/types';
 import {
   loadTextTrackCues,
   type TextTrackCueLoadingOwners,
   type TextTrackCueLoadingState,
-} from '../load-text-track-cues';
+} from '../../load-text-track-cues';
+import { setupTextTrackActors, type TextTrackActorsOwners } from '../setup-text-track-actors';
 
-// Mock parseVttSegment
-vi.mock('../../text/parse-vtt-segment', () => ({
-  parseVttSegment: vi.fn((url: string) => {
+// The composed behaviors (setup in dom + loader in media) intersect their
+// owner-shape contracts. The setup narrows `mediaElement` to
+// `HTMLMediaElement`; the loader keeps the abstract actor types. The test
+// signal has to satisfy both.
+type ComposedOwners = TextTrackCueLoadingOwners & TextTrackActorsOwners;
+
+// Mock resolveVttSegment
+vi.mock('../../../../media/dom/text/resolve-vtt-segment', () => ({
+  resolveVttSegment: vi.fn((url: string) => {
     if (url.includes('fail')) {
       return Promise.reject(new Error('Failed to load'));
     }
     return Promise.resolve([new VTTCue(0, 5, `Subtitle from ${url}`)]);
   }),
-  destroyVttParser: vi.fn(),
+  destroyVttResolver: vi.fn(),
 }));
 
 function createMockPresentation(tracks: Partial<TextTrack>[]): Presentation {
@@ -56,18 +64,18 @@ function createMockSegments(count: number): Segment[] {
 }
 
 /**
- * Sets up loadTextTrackCues with the given state/owners and returns a
- * combined cleanup that destroys actors from owners before destroying the reactor.
+ * Sets up the composition of `setupTextTrackActors` (DOM-side actor
+ * setup) and `loadTextTrackCues` (host-agnostic orchestrator). Returns
+ * the composed reactive channels and a combined cleanup.
  */
-function setupLoadTextTrackCues(initialState: TextTrackCueLoadingState, initialOwners: TextTrackCueLoadingOwners) {
+function setupLoadTextTrackCues(initialState: TextTrackCueLoadingState, initialOwners: ComposedOwners) {
   const state = signal<TextTrackCueLoadingState>(initialState);
-  const owners = signal<TextTrackCueLoadingOwners>(initialOwners);
+  const owners = signal<ComposedOwners>(initialOwners);
+  const setupCleanup = setupTextTrackActors({ owners, config: { resolveTextTrackSegment: resolveVttSegment } });
   const reactor = loadTextTrackCues({ state, owners });
   const cleanup = () => {
-    const { textTracksActor, segmentLoaderActor } = owners.get();
-    textTracksActor?.destroy();
-    segmentLoaderActor?.destroy();
     reactor.destroy();
+    setupCleanup();
   };
   return { state, owners, cleanup };
 }
@@ -79,7 +87,7 @@ describe('loadTextTrackCues', () => {
 
   // Note: We cannot test actual cue addition in unit tests because the vitest
   // browser environment clears manually added cues after async operations.
-  // These tests verify the orchestration logic and that parseVttSegment is called.
+  // These tests verify the orchestration logic and that resolveVttSegment is called.
 
   describe('cue deduplication', () => {
     // Deduplication checks textTrack.cues directly. Since the vitest browser
@@ -110,8 +118,8 @@ describe('loadTextTrackCues', () => {
     }
 
     it('adds all cues when there are no duplicates', async () => {
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      vi.mocked(parseVttSegment)
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      vi.mocked(resolveVttSegment)
         .mockResolvedValueOnce([new VTTCue(0, 5, 'Cue A')])
         .mockResolvedValueOnce([new VTTCue(5, 10, 'Cue B')])
         .mockResolvedValueOnce([new VTTCue(10, 15, 'Cue C')]);
@@ -132,9 +140,9 @@ describe('loadTextTrackCues', () => {
     });
 
     it('drops a duplicate cue from a subsequent segment', async () => {
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
       // Boundary-spanning cue appears in both adjacent segments per HLS spec
-      vi.mocked(parseVttSegment)
+      vi.mocked(resolveVttSegment)
         .mockResolvedValueOnce([new VTTCue(8, 12, 'Boundary cue')])
         .mockResolvedValueOnce([new VTTCue(8, 12, 'Boundary cue')]);
 
@@ -154,8 +162,8 @@ describe('loadTextTrackCues', () => {
     });
 
     it('keeps cues with identical timing but different text', async () => {
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      vi.mocked(parseVttSegment)
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      vi.mocked(resolveVttSegment)
         .mockResolvedValueOnce([new VTTCue(0, 5, 'Hello')])
         .mockResolvedValueOnce([new VTTCue(0, 5, 'World')]); // same timing, different text — not a duplicate
 
@@ -175,8 +183,8 @@ describe('loadTextTrackCues', () => {
     });
 
     it('handles mixed: boundary duplicate dropped, unique cues kept', async () => {
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      vi.mocked(parseVttSegment)
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      vi.mocked(resolveVttSegment)
         .mockResolvedValueOnce([new VTTCue(0, 8, 'Unique to seg 0'), new VTTCue(8, 12, 'Boundary cue')])
         .mockResolvedValueOnce([new VTTCue(8, 12, 'Boundary cue'), new VTTCue(12, 20, 'Unique to seg 1')]);
 
@@ -202,8 +210,8 @@ describe('loadTextTrackCues', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-    expect(parseVttSegment).not.toHaveBeenCalled();
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+    expect(resolveVttSegment).not.toHaveBeenCalled();
 
     cleanup();
   });
@@ -225,9 +233,9 @@ describe('loadTextTrackCues', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-    expect(parseVttSegment).toHaveBeenCalledTimes(1);
-    expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+    expect(resolveVttSegment).toHaveBeenCalledTimes(1);
+    expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
 
     cleanup();
   });
@@ -249,11 +257,11 @@ describe('loadTextTrackCues', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-    expect(parseVttSegment).toHaveBeenCalledTimes(3);
-    expect(parseVttSegment).toHaveBeenNthCalledWith(1, 'https://example.com/segment-0.vtt');
-    expect(parseVttSegment).toHaveBeenNthCalledWith(2, 'https://example.com/segment-1.vtt');
-    expect(parseVttSegment).toHaveBeenNthCalledWith(3, 'https://example.com/segment-2.vtt');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+    expect(resolveVttSegment).toHaveBeenCalledTimes(3);
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(1, 'https://example.com/segment-0.vtt');
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(2, 'https://example.com/segment-1.vtt');
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(3, 'https://example.com/segment-2.vtt');
 
     cleanup();
   });
@@ -290,16 +298,16 @@ describe('loadTextTrackCues', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
     // Verify all segments were attempted
-    expect(parseVttSegment).toHaveBeenCalledTimes(3);
-    expect(parseVttSegment).toHaveBeenNthCalledWith(1, 'https://example.com/segment-0.vtt');
-    expect(parseVttSegment).toHaveBeenNthCalledWith(2, 'https://example.com/fail.vtt');
-    expect(parseVttSegment).toHaveBeenNthCalledWith(3, 'https://example.com/segment-2.vtt');
+    expect(resolveVttSegment).toHaveBeenCalledTimes(3);
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(1, 'https://example.com/segment-0.vtt');
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(2, 'https://example.com/fail.vtt');
+    expect(resolveVttSegment).toHaveBeenNthCalledWith(3, 'https://example.com/segment-2.vtt');
 
     // Verify error was logged for the failing segment
     expect(consoleErrorSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Failed to load VTT segment'),
+      expect.stringContaining('Failed to load text-track segment'),
       expect.any(Error)
     );
 
@@ -323,8 +331,8 @@ describe('loadTextTrackCues', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-    expect(parseVttSegment).not.toHaveBeenCalled();
+    const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+    expect(resolveVttSegment).not.toHaveBeenCalled();
 
     cleanup();
   });
@@ -357,14 +365,14 @@ describe('loadTextTrackCues', () => {
 
       await new Promise((resolve) => setTimeout(resolve, 50));
 
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
       // Window [0, 30): seg-0 (0s), seg-1 (10s), seg-2 (20s) — seg-3 starts at 30 (excluded)
-      expect(parseVttSegment).toHaveBeenCalledTimes(3);
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-1.vtt');
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-2.vtt');
-      expect(parseVttSegment).not.toHaveBeenCalledWith('https://example.com/segment-3.vtt');
-      expect(parseVttSegment).not.toHaveBeenCalledWith('https://example.com/segment-4.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledTimes(3);
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-1.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-2.vtt');
+      expect(resolveVttSegment).not.toHaveBeenCalledWith('https://example.com/segment-3.vtt');
+      expect(resolveVttSegment).not.toHaveBeenCalledWith('https://example.com/segment-4.vtt');
 
       cleanup();
     });
@@ -375,18 +383,18 @@ describe('loadTextTrackCues', () => {
       // Wait for initial window load (seg-0..seg-2)
       await new Promise((resolve) => setTimeout(resolve, 50));
 
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      expect(parseVttSegment).toHaveBeenCalledTimes(3);
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      expect(resolveVttSegment).toHaveBeenCalledTimes(3);
 
       // Advance currentTime so seg-3 and seg-4 enter the window [15, 45)
       state.set({ ...state.get(), currentTime: 15 });
 
       await vi.waitFor(() => {
-        expect(parseVttSegment).toHaveBeenCalledTimes(5);
+        expect(resolveVttSegment).toHaveBeenCalledTimes(5);
       });
 
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-3.vtt');
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-4.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-3.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-4.vtt');
 
       cleanup();
     });
@@ -396,17 +404,17 @@ describe('loadTextTrackCues', () => {
 
       await new Promise((resolve) => setTimeout(resolve, 50));
 
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      const callsBefore = (parseVttSegment as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]);
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      const callsBefore = (resolveVttSegment as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]);
       expect(callsBefore).toContain('https://example.com/segment-0.vtt');
 
       state.set({ ...state.get(), currentTime: 15 });
       await vi.waitFor(() => {
-        expect(parseVttSegment).toHaveBeenCalledTimes(5);
+        expect(resolveVttSegment).toHaveBeenCalledTimes(5);
       });
 
       // seg-0..seg-2 should each appear exactly once across all calls
-      const allCalls = (parseVttSegment as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]);
+      const allCalls = (resolveVttSegment as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]);
       expect(allCalls.filter((u) => u === 'https://example.com/segment-0.vtt')).toHaveLength(1);
       expect(allCalls.filter((u) => u === 'https://example.com/segment-1.vtt')).toHaveLength(1);
       expect(allCalls.filter((u) => u === 'https://example.com/segment-2.vtt')).toHaveLength(1);
@@ -434,11 +442,11 @@ describe('loadTextTrackCues', () => {
 
       await new Promise((resolve) => setTimeout(resolve, 50));
 
-      const { parseVttSegment } = await import('../../text/parse-vtt-segment');
-      expect(parseVttSegment).toHaveBeenCalledTimes(3);
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-1.vtt');
-      expect(parseVttSegment).toHaveBeenCalledWith('https://example.com/segment-2.vtt');
+      const { resolveVttSegment } = await import('../../../../media/dom/text/resolve-vtt-segment');
+      expect(resolveVttSegment).toHaveBeenCalledTimes(3);
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-0.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-1.vtt');
+      expect(resolveVttSegment).toHaveBeenCalledWith('https://example.com/segment-2.vtt');
 
       cleanup();
     });
diff --git a/packages/spf/src/dom/features/tests/setup-mediasource.test.ts b/packages/spf/src/playback/behaviors/dom/tests/setup-mediasource.test.ts
similarity index 70%
rename from packages/spf/src/dom/features/tests/setup-mediasource.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/setup-mediasource.test.ts
index 5f2c9e2f..8db3ac05 100644
--- a/packages/spf/src/dom/features/tests/setup-mediasource.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/setup-mediasource.test.ts
@@ -1,13 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { Presentation } from '../../../media/types';
+import { signal } from '../../../../core/signals/primitives';
 import { type MediaSourceOwners, type MediaSourceState, setupMediaSource } from '../setup-mediasource';
 
 // Mock the DOM utilities.
-// observeMediaSourceReadyState returns 'open' immediately — simulates the
-// MediaSource having opened, which is the condition the inner effect waits on
-// before writing to owners.
-vi.mock('../../media/mediasource-setup', () => ({
+// onMediaSourceReadyStateChange fires `onChange('open')` immediately — simulates
+// the MediaSource having opened, which is the condition the inner effect waits
+// on before writing to owners.
+vi.mock('../../../../media/dom/mse/mediasource-setup', () => ({
   createMediaSource: vi.fn(() => ({
     addEventListener: vi.fn(),
     removeEventListener: vi.fn(),
@@ -16,9 +15,11 @@ vi.mock('../../media/mediasource-setup', () => ({
   attachMediaSource: vi.fn(() => ({
     detach: vi.fn(),
   })),
-  observeMediaSourceReadyState: vi.fn((_ms: MediaSource, _signal: AbortSignal) => ({
-    get: () => 'open' as MediaSource['readyState'],
-  })),
+  onMediaSourceReadyStateChange: vi.fn(
+    (_ms: MediaSource, _signal: AbortSignal, onChange: (state: MediaSource['readyState']) => void) => {
+      onChange('open');
+    }
+  ),
 }));
 
 function setupSetupMediaSource(initialState: MediaSourceState, initialOwners: MediaSourceOwners) {
@@ -34,14 +35,14 @@ describe('setupMediaSource', () => {
   });
 
   it('creates MediaSource when mediaElement and presentation.url exist', async () => {
-    const { createMediaSource } = await import('../../media/mediasource-setup');
+    const { createMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const { state, owners, cleanup } = setupSetupMediaSource({}, {});
 
     owners.set({ ...owners.get(), mediaElement: {} as HTMLMediaElement });
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await vi.waitFor(() => {
@@ -52,7 +53,7 @@ describe('setupMediaSource', () => {
   });
 
   it('attaches MediaSource to mediaElement', async () => {
-    const { createMediaSource, attachMediaSource } = await import('../../media/mediasource-setup');
+    const { createMediaSource, attachMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const mockMediaSource = {
       addEventListener: vi.fn(),
@@ -67,7 +68,7 @@ describe('setupMediaSource', () => {
     owners.set({ ...owners.get(), mediaElement });
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await vi.waitFor(() => {
@@ -77,8 +78,8 @@ describe('setupMediaSource', () => {
     cleanup();
   });
 
-  it('updates owners with mediaSource and mediaSourceReadyState', async () => {
-    const { createMediaSource } = await import('../../media/mediasource-setup');
+  it('publishes mediaSource on owners and mediaSourceReadyState on state', async () => {
+    const { createMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const mockMediaSource = {
       addEventListener: vi.fn(),
@@ -92,25 +93,25 @@ describe('setupMediaSource', () => {
     owners.set({ ...owners.get(), mediaElement: {} as HTMLMediaElement });
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await vi.waitFor(() => {
       expect(owners.get().mediaSource).toBe(mockMediaSource);
-      expect(owners.get().mediaSourceReadyState).toBeDefined();
+      expect(state.get().mediaSourceReadyState).toBe('open');
     });
 
     cleanup();
   });
 
   it('does not create MediaSource if mediaElement is missing', async () => {
-    const { createMediaSource } = await import('../../media/mediasource-setup');
+    const { createMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const { state, cleanup } = setupSetupMediaSource({}, {});
 
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await new Promise((resolve) => setTimeout(resolve, 50));
@@ -121,7 +122,7 @@ describe('setupMediaSource', () => {
   });
 
   it('does not create MediaSource if presentation.url is missing', async () => {
-    const { createMediaSource } = await import('../../media/mediasource-setup');
+    const { createMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const { owners, cleanup } = setupSetupMediaSource({}, {});
 
@@ -135,14 +136,14 @@ describe('setupMediaSource', () => {
   });
 
   it('does not create multiple MediaSources (deduplication)', async () => {
-    const { createMediaSource } = await import('../../media/mediasource-setup');
+    const { createMediaSource } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const { state, owners, cleanup } = setupSetupMediaSource({}, {});
 
     owners.set({ ...owners.get(), mediaElement: {} as HTMLMediaElement });
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await vi.waitFor(() => {
@@ -151,7 +152,7 @@ describe('setupMediaSource', () => {
 
     state.set({
       ...state.get(),
-      presentation: { url: 'https://example.com/video.m3u8' } as Presentation,
+      presentation: { url: 'https://example.com/video.m3u8' },
     });
 
     await new Promise((resolve) => setTimeout(resolve, 50));
diff --git a/packages/spf/src/dom/features/tests/setup-sourcebuffer.test.ts b/packages/spf/src/playback/behaviors/dom/tests/setup-sourcebuffer.test.ts
similarity index 92%
rename from packages/spf/src/dom/features/tests/setup-sourcebuffer.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/setup-sourcebuffer.test.ts
index b9307924..b80839b0 100644
--- a/packages/spf/src/dom/features/tests/setup-sourcebuffer.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/setup-sourcebuffer.test.ts
@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { AudioTrack, Presentation, VideoTrack } from '../../../media/types';
+import { signal } from '../../../../core/signals/primitives';
+import type { AudioTrack, Presentation, VideoTrack } from '../../../../media/types';
 import {
   buildMimeCodec,
   type SourceBufferOwners,
@@ -9,7 +9,7 @@ import {
 } from '../setup-sourcebuffer';
 
 // Mock the DOM utilities
-vi.mock('../../media/mediasource-setup', () => ({
+vi.mock('../../../../media/dom/mse/mediasource-setup', () => ({
   createSourceBuffer: vi.fn((_mediaSource: MediaSource, mimeCodec: string) => ({
     mimeCodec,
     mode: 'segments',
@@ -148,7 +148,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('creates video SourceBuffer for video-only source', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack = createResolvedVideoTrack();
     const { state, owners, cleanup } = setupSetupSourceBuffers();
@@ -171,7 +171,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('creates audio SourceBuffer for audio-only source', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const audioTrack = createResolvedAudioTrack();
     const { state, owners, cleanup } = setupSetupSourceBuffers();
@@ -194,7 +194,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('creates both SourceBuffers together when both tracks are selected', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack = createResolvedVideoTrack();
     const audioTrack = createResolvedAudioTrack();
@@ -221,7 +221,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('waits for audio to resolve before creating video SourceBuffer when both are selected', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack = createResolvedVideoTrack();
     const unresolvedAudio = createResolvedAudioTrack();
@@ -268,7 +268,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('does not create SourceBuffer when track has no codecs', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack: VideoTrack = { ...createResolvedVideoTrack(), codecs: [] };
     const { state, owners, cleanup } = setupSetupSourceBuffers();
@@ -287,7 +287,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('does not create SourceBuffers more than once', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack = createResolvedVideoTrack();
     const { state, owners, cleanup } = setupSetupSourceBuffers();
@@ -309,7 +309,7 @@ describe('setupSourceBuffers', () => {
   });
 
   it('does not create without a MediaSource', async () => {
-    const { createSourceBuffer } = await import('../../media/mediasource-setup');
+    const { createSourceBuffer } = await import('../../../../media/dom/mse/mediasource-setup');
 
     const videoTrack = createResolvedVideoTrack();
     const { state, cleanup } = setupSetupSourceBuffers();
diff --git a/packages/spf/src/dom/features/tests/sync-text-tracks.test.ts b/packages/spf/src/playback/behaviors/dom/tests/sync-text-tracks.test.ts
similarity index 99%
rename from packages/spf/src/dom/features/tests/sync-text-tracks.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/sync-text-tracks.test.ts
index 47f7dbaf..eaf485cd 100644
--- a/packages/spf/src/dom/features/tests/sync-text-tracks.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/sync-text-tracks.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
+import { signal } from '../../../../core/signals/primitives';
 import { syncTextTracks, type TextTrackSyncOwners, type TextTrackSyncState } from '../sync-text-tracks';
 
 function makePresentation(tracks: Array<{ id: string; kind?: string; language?: string }>) {
diff --git a/packages/spf/src/dom/features/tests/track-current-time.test.ts b/packages/spf/src/playback/behaviors/dom/tests/track-current-time.test.ts
similarity index 99%
rename from packages/spf/src/dom/features/tests/track-current-time.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/track-current-time.test.ts
index 4465198b..870e046d 100644
--- a/packages/spf/src/dom/features/tests/track-current-time.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/track-current-time.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
+import { signal } from '../../../../core/signals/primitives';
 import {
   type CurrentTimeOwners,
   type CurrentTimeState,
diff --git a/packages/spf/src/dom/features/tests/track-playback-initiated.test.ts b/packages/spf/src/playback/behaviors/dom/tests/track-playback-initiated.test.ts
similarity index 98%
rename from packages/spf/src/dom/features/tests/track-playback-initiated.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/track-playback-initiated.test.ts
index 12229b27..408db8eb 100644
--- a/packages/spf/src/dom/features/tests/track-playback-initiated.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/track-playback-initiated.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
+import { signal } from '../../../../core/signals/primitives';
 import {
   type PlaybackInitiatedOwners,
   type PlaybackInitiatedState,
@@ -129,7 +129,7 @@ describe('trackPlaybackInitiated', () => {
     await new Promise((resolve) => setTimeout(resolve, 10));
     expect(state.get().playbackInitiated).toBe(true);
 
-    state.set({ ...state.get(), presentation: {} });
+    state.set({ ...state.get(), presentation: undefined });
     await new Promise((resolve) => setTimeout(resolve, 20));
 
     expect(state.get().playbackInitiated).toBe(false);
diff --git a/packages/spf/src/dom/features/tests/track-playback-rate.test.ts b/packages/spf/src/playback/behaviors/dom/tests/track-playback-rate.test.ts
similarity index 98%
rename from packages/spf/src/dom/features/tests/track-playback-rate.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/track-playback-rate.test.ts
index 25ec0420..23641bd3 100644
--- a/packages/spf/src/dom/features/tests/track-playback-rate.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/track-playback-rate.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
+import { signal } from '../../../../core/signals/primitives';
 import { type PlaybackRateOwners, type PlaybackRateState, trackPlaybackRate } from '../track-playback-rate';
 
 function setupTrackPlaybackRate(initialState: PlaybackRateState = {}, initialOwners: PlaybackRateOwners = {}) {
diff --git a/packages/spf/src/dom/features/tests/update-duration.test.ts b/packages/spf/src/playback/behaviors/dom/tests/update-duration.test.ts
similarity index 97%
rename from packages/spf/src/dom/features/tests/update-duration.test.ts
rename to packages/spf/src/playback/behaviors/dom/tests/update-duration.test.ts
index 1f121ba5..d37e8615 100644
--- a/packages/spf/src/dom/features/tests/update-duration.test.ts
+++ b/packages/spf/src/playback/behaviors/dom/tests/update-duration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
-import { signal } from '../../../core/signals/primitives';
-import type { Presentation } from '../../../media/types';
+import { signal } from '../../../../core/signals/primitives';
+import type { Presentation } from '../../../../media/types';
 import {
   canUpdateDuration,
   type DurationUpdateOwners,
@@ -10,7 +10,10 @@ import {
 } from '../update-duration';
 
 function setupUpdateDuration(initialState: DurationUpdateState, initialOwners: DurationUpdateOwners) {
-  const state = signal<DurationUpdateState>(initialState);
+  // Default mediaSourceReadyState to 'open' to mirror what setupMediaSource
+  // would have written. Tests that exercise other readyState values pass it
+  // explicitly.
+  const state = signal<DurationUpdateState>({ mediaSourceReadyState: 'open', ...initialState });
   const owners = signal<DurationUpdateOwners>(initialOwners);
   const cleanup = updateDuration({ state, owners });
   return { state, owners, cleanup };
@@ -89,6 +92,7 @@ describe('shouldUpdateDuration', () => {
   it('returns true when MediaSource duration is NaN (initial state)', () => {
     const state: DurationUpdateState = {
       presentation: { duration: 60 } as Presentation,
+      mediaSourceReadyState: 'open',
     };
     const owners: DurationUpdateOwners = {
       mediaSource: { readyState: 'open', duration: NaN } as MediaSource,
@@ -100,6 +104,7 @@ describe('shouldUpdateDuration', () => {
   it('returns false when MediaSource is not open', () => {
     const state: DurationUpdateState = {
       presentation: { duration: 60 } as Presentation,
+      mediaSourceReadyState: 'closed',
     };
     const owners: DurationUpdateOwners = {
       mediaSource: { readyState: 'closed', duration: 0 } as MediaSource,
diff --git a/packages/spf/src/dom/features/track-current-time.ts b/packages/spf/src/playback/behaviors/dom/track-current-time.ts
similarity index 94%
rename from packages/spf/src/dom/features/track-current-time.ts
rename to packages/spf/src/playback/behaviors/dom/track-current-time.ts
index b6030544..5fee712f 100644
--- a/packages/spf/src/dom/features/track-current-time.ts
+++ b/packages/spf/src/playback/behaviors/dom/track-current-time.ts
@@ -1,6 +1,6 @@
 import { listen } from '@videojs/utils/dom';
-import { effect } from '../../core/signals/effect';
-import { type Signal, update } from '../../core/signals/primitives';
+import { effect } from '../../../core/signals/effect';
+import { type Signal, update } from '../../../core/signals/primitives';
 
 /**
  * State shape for current time tracking.
diff --git a/packages/spf/src/dom/features/track-playback-initiated.ts b/packages/spf/src/playback/behaviors/dom/track-playback-initiated.ts
similarity index 92%
rename from packages/spf/src/dom/features/track-playback-initiated.ts
rename to packages/spf/src/playback/behaviors/dom/track-playback-initiated.ts
index 0ab18310..e468dc13 100644
--- a/packages/spf/src/dom/features/track-playback-initiated.ts
+++ b/packages/spf/src/playback/behaviors/dom/track-playback-initiated.ts
@@ -1,7 +1,8 @@
 import { listen } from '@videojs/utils/dom';
-import type { Reactor } from '../../core/reactors/create-machine-reactor';
-import { createMachineReactor } from '../../core/reactors/create-machine-reactor';
-import { computed, type Signal, update } from '../../core/signals/primitives';
+import type { Reactor } from '../../../core/reactors/create-machine-reactor';
+import { createMachineReactor } from '../../../core/reactors/create-machine-reactor';
+import { computed, type Signal, update } from '../../../core/signals/primitives';
+import type { MaybeResolvedPresentation } from '../../../media/types';
 
 /**
  * State shape for playback initiation tracking.
@@ -10,7 +11,7 @@ export interface PlaybackInitiatedState {
   /** True once play has been requested for the current presentation URL. */
   playbackInitiated?: boolean;
   /** Current presentation — URL is used to detect source changes. */
-  presentation?: { url?: string };
+  presentation?: MaybeResolvedPresentation;
 }
 
 /**
diff --git a/packages/spf/src/dom/features/track-playback-rate.ts b/packages/spf/src/playback/behaviors/dom/track-playback-rate.ts
similarity index 90%
rename from packages/spf/src/dom/features/track-playback-rate.ts
rename to packages/spf/src/playback/behaviors/dom/track-playback-rate.ts
index 2fd4a052..94c5fc4d 100644
--- a/packages/spf/src/dom/features/track-playback-rate.ts
+++ b/packages/spf/src/playback/behaviors/dom/track-playback-rate.ts
@@ -1,6 +1,6 @@
 import { listen } from '@videojs/utils/dom';
-import { effect } from '../../core/signals/effect';
-import { computed, type Signal, update } from '../../core/signals/primitives';
+import { effect } from '../../../core/signals/effect';
+import { computed, type Signal, update } from '../../../core/signals/primitives';
 
 /**
  * State shape for playback rate tracking.
diff --git a/packages/spf/src/playback/behaviors/dom/tsconfig.json b/packages/spf/src/playback/behaviors/dom/tsconfig.json
new file mode 100644
index 00000000..71ba98dc
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/dom/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../../types/playback/behaviors/dom"
+  },
+  "references": [
+    { "path": "../../../../../utils" },
+    { "path": "../../../core" },
+    { "path": "../../../network" },
+    { "path": "../../../media" },
+    { "path": "../../../media/dom" },
+    { "path": "../" },
+    { "path": "../../actors" },
+    { "path": "../../actors/dom" }
+  ],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/src/dom/features/update-duration.ts b/packages/spf/src/playback/behaviors/dom/update-duration.ts
similarity index 87%
rename from packages/spf/src/dom/features/update-duration.ts
rename to packages/spf/src/playback/behaviors/dom/update-duration.ts
index 27e5e44b..c3576d30 100644
--- a/packages/spf/src/dom/features/update-duration.ts
+++ b/packages/spf/src/playback/behaviors/dom/update-duration.ts
@@ -1,16 +1,16 @@
-import { effect } from '../../core/signals/effect';
-import type { ReadonlySignal, Signal } from '../../core/signals/primitives';
-import type { Presentation } from '../../media/types';
-import { hasPresentationDuration } from '../../media/types';
+import { effect } from '../../../core/signals/effect';
+import type { Signal } from '../../../core/signals/primitives';
+import type { MaybeResolvedPresentation } from '../../../media/types';
+import { hasPresentationDuration } from '../../../media/types';
 
 export interface DurationUpdateState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
+  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
+  mediaSourceReadyState?: MediaSource['readyState'];
 }
 
 export interface DurationUpdateOwners {
   mediaSource?: MediaSource;
-  /** Reactive mirror of `mediaSource.readyState` — updated via DOM events. */
-  mediaSourceReadyState?: ReadonlySignal<MediaSource['readyState']>;
   videoSourceBuffer?: SourceBuffer;
   audioSourceBuffer?: SourceBuffer;
 }
@@ -54,10 +54,9 @@ export function shouldUpdateDuration(state: DurationUpdateState, owners: Duratio
   const { mediaSource } = owners;
   const { presentation } = state;
 
-  // MediaSource must be open — use reactive readyState signal when available
-  // so the effect re-evaluates when readyState changes from 'closed' to 'open'.
-  const readyState = owners.mediaSourceReadyState?.get() ?? owners.mediaSource?.readyState;
-  if (readyState !== 'open') return false;
+  // MediaSource must be open — read from state.mediaSourceReadyState so the
+  // effect re-evaluates when readyState changes from 'closed' to 'open'.
+  if (state.mediaSourceReadyState !== 'open') return false;
 
   const duration = presentation!.duration!;
 
diff --git a/packages/spf/src/playback/behaviors/load-text-track-cues.ts b/packages/spf/src/playback/behaviors/load-text-track-cues.ts
new file mode 100644
index 00000000..ccccfe8d
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/load-text-track-cues.ts
@@ -0,0 +1,141 @@
+import type { Reactor } from '../../core/reactors/create-machine-reactor';
+import { createMachineReactor } from '../../core/reactors/create-machine-reactor';
+import { computed, type Signal, untrack } from '../../core/signals/primitives';
+import type { Cue, MaybeResolvedPresentation, MediaElementWithTextTracks, TextTrack } from '../../media/types';
+import { isResolvedTrack } from '../../media/types';
+import type { TextTrackSegmentLoaderActor } from '../actors/text-track-segment-loader';
+import type { TextTracksActor } from '../actors/text-tracks';
+
+/**
+ * FSM states for text-track cue loading.
+ *
+ * ```
+ * 'preconditions-unmet' ── mediaElement + presentation + text tracks + actors ──→ 'pending'
+ *        ↑                                                                              |
+ *        │                                                            selectedTrack resolved + in element
+ *        │                                                                              ↓
+ *        └──── preconditions lost ───── 'monitoring-for-loads'
+ *
+ * any state ──── destroy() ────→ 'destroying' ────→ 'destroyed'
+ * ```
+ *
+ * Actor lifecycle is NOT managed by this behavior — it reads
+ * `textTracksActor` and `segmentLoaderActor` from owners. A host-side
+ * setup behavior (e.g. `setupTextTrackActors` in dom/) is
+ * responsible for creating and destroying them when the media element
+ * appears/disappears.
+ */
+export type LoadTextTrackCuesState = 'preconditions-unmet' | 'pending' | 'monitoring-for-loads';
+
+/**
+ * State shape for text-track cue loading.
+ */
+export interface TextTrackCueLoadingState {
+  selectedTextTrackId?: string;
+  presentation?: MaybeResolvedPresentation;
+  /** Current playback position — used to gate segment fetching to the forward buffer window. */
+  currentTime?: number;
+}
+
+/**
+ * Owners shape for text-track cue loading.
+ *
+ * The `mediaElement` is typed against the host-agnostic
+ * `MediaElementWithTextTracks` shape; `HTMLMediaElement` satisfies it
+ * structurally. Actors are expected to be supplied by a companion
+ * provider behavior.
+ */
+export interface TextTrackCueLoadingOwners {
+  mediaElement?: MediaElementWithTextTracks | undefined;
+  textTracksActor?: TextTracksActor<Cue> | undefined;
+  segmentLoaderActor?: TextTrackSegmentLoaderActor | undefined;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function getTextTracks(presentation: MaybeResolvedPresentation | undefined) {
+  return presentation?.selectionSets?.find((s) => s.type === 'text')?.switchingSets[0]?.tracks;
+}
+
+function findSelectedTrack(state: TextTrackCueLoadingState): TextTrack | undefined {
+  const track = getTextTracks(state.presentation)?.find((t) => t.id === state.selectedTextTrackId);
+  return track && isResolvedTrack(track) ? track : undefined;
+}
+
+function hasMountedTrack(mediaElement: MediaElementWithTextTracks, id: string): boolean {
+  for (const t of mediaElement.textTracks) {
+    if (t.id === id) return true;
+  }
+  return false;
+}
+
+function deriveState(state: TextTrackCueLoadingState, owners: TextTrackCueLoadingOwners): LoadTextTrackCuesState {
+  if (
+    !owners.mediaElement ||
+    !getTextTracks(state.presentation)?.length ||
+    !owners.textTracksActor ||
+    !owners.segmentLoaderActor
+  ) {
+    return 'preconditions-unmet';
+  }
+  const track = findSelectedTrack(state);
+  if (!track || track.segments.length === 0) return 'pending';
+  if (!hasMountedTrack(owners.mediaElement, state.selectedTextTrackId ?? '')) {
+    return 'pending';
+  }
+  return 'monitoring-for-loads';
+}
+
+// ============================================================================
+// Main export
+// ============================================================================
+
+/**
+ * Text-track cue loading orchestration (host-agnostic).
+ *
+ * Waits for preconditions (mediaElement, presentation with text tracks,
+ * actors in owners, selected track mounted), then sends `load` messages
+ * to the `segmentLoaderActor` whenever `currentTime` or the selected
+ * track changes.
+ *
+ * Actors are provided by a host-side companion behavior — this behavior
+ * does not create or destroy them.
+ *
+ * @example
+ * const reactor = loadTextTrackCues({ state, owners });
+ */
+export function loadTextTrackCues<S extends TextTrackCueLoadingState, O extends TextTrackCueLoadingOwners>({
+  state,
+  owners,
+}: {
+  state: Signal<S>;
+  owners: Signal<O>;
+}): Reactor<LoadTextTrackCuesState | 'destroying' | 'destroyed'> {
+  const derivedStateSignal = computed(() => deriveState(state.get(), owners.get()));
+  const currentTimeSignal = computed(() => state.get().currentTime ?? 0);
+  const selectedTrackSignal = computed(() => findSelectedTrack(state.get()));
+
+  return createMachineReactor<LoadTextTrackCuesState>({
+    initial: 'preconditions-unmet',
+    monitor: () => derivedStateSignal.get(),
+    states: {
+      'preconditions-unmet': {},
+      pending: {},
+      'monitoring-for-loads': {
+        // Re-runs whenever currentTime or selectedTrack changes, dispatching
+        // a load message. owners is read with untrack() since actor presence
+        // is guaranteed by deriveState when in this state. The always monitor
+        // (registered before this effect) transitions us out before this
+        // re-runs if either invariant stops holding.
+        effects: () => {
+          const currentTime = currentTimeSignal.get();
+          const track = selectedTrackSignal.get()!;
+          const { segmentLoaderActor } = untrack(() => owners.get());
+          segmentLoaderActor!.send({ type: 'load', track, currentTime });
+        },
+      },
+    },
+  });
+}
diff --git a/packages/spf/src/media/features/quality-switching.ts b/packages/spf/src/playback/behaviors/quality-switching.ts
similarity index 92%
rename from packages/spf/src/media/features/quality-switching.ts
rename to packages/spf/src/playback/behaviors/quality-switching.ts
index 3d351f92..0168dcaa 100644
--- a/packages/spf/src/media/features/quality-switching.ts
+++ b/packages/spf/src/playback/behaviors/quality-switching.ts
@@ -1,15 +1,15 @@
 import { effect } from '../../core/signals/effect';
 import { type Signal, update } from '../../core/signals/primitives';
-import type { BandwidthState } from '../abr/bandwidth-estimator';
-import { getBandwidthEstimate } from '../abr/bandwidth-estimator';
-import { selectQuality } from '../abr/quality-selection';
-import type { Presentation, VideoSelectionSet } from '../types';
+import type { BandwidthState } from '../../media/abr/bandwidth-estimator';
+import { getBandwidthEstimate } from '../../media/abr/bandwidth-estimator';
+import { selectQuality } from '../../media/abr/quality-selection';
+import type { MaybeResolvedPresentation, VideoSelectionSet } from '../../media/types';
 
 /**
  * State shape for quality switching.
  */
 export interface QualitySwitchingState {
-  presentation?: Presentation;
+  presentation?: MaybeResolvedPresentation;
   bandwidthState?: BandwidthState;
   selectedVideoTrackId?: string;
   // TODO: abrDisabled is a blunt instrument — it requires callers to know they're
@@ -60,7 +60,7 @@ export const DEFAULT_SWITCHING_CONFIG: Required<QualitySwitchingConfig> = {
  * Get all video tracks from a presentation's first switching set.
  * Returns [] when the presentation is still unresolved (no selectionSets yet).
  */
-function getVideoTracks(presentation: Presentation) {
+function getVideoTracks(presentation: MaybeResolvedPresentation) {
   const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;
   return videoSet?.switchingSets[0]?.tracks ?? [];
 }
diff --git a/packages/spf/src/media/features/resolve-presentation.ts b/packages/spf/src/playback/behaviors/resolve-presentation.ts
similarity index 67%
rename from packages/spf/src/media/features/resolve-presentation.ts
rename to packages/spf/src/playback/behaviors/resolve-presentation.ts
index 0a67d825..259544bc 100644
--- a/packages/spf/src/media/features/resolve-presentation.ts
+++ b/packages/spf/src/playback/behaviors/resolve-presentation.ts
@@ -1,50 +1,30 @@
 import type { Reactor } from '../../core/reactors/create-machine-reactor';
 import { createMachineReactor } from '../../core/reactors/create-machine-reactor';
 import { computed, type Signal, update } from '../../core/signals/primitives';
-import { fetchResolvable, getResponseText } from '../../dom/network/fetch';
-import { parseMultivariantPlaylist } from '../hls/parse-multivariant';
-import type { AddressableObject, Presentation } from '../types';
-
-/**
- * Unresolved presentation - has a URL but no data yet.
- * Identical to AddressableObject per user requirement.
- */
-export type UnresolvedPresentation = AddressableObject;
+import { parseMultivariantPlaylist } from '../../media/hls/parse-multivariant';
+import { isResolvedPresentation, type MaybeResolvedPresentation } from '../../media/types';
+import { fetchResolvable, getResponseText } from '../../network/fetch';
 
 /**
  * State shape for presentation resolution.
+ *
+ * `presentation` is a single slot whose value may or may not be resolved.
+ * A caller writes `{ url }`; resolvePresentation parses the manifest and
+ * populates the rest in place.
  */
 export interface PresentationState {
-  presentation?: UnresolvedPresentation | Presentation | undefined;
+  presentation?: MaybeResolvedPresentation;
   preload?: 'auto' | 'metadata' | 'none' | undefined;
   /** True once the user has initiated playback — enables resolution regardless of preload. */
   playbackInitiated?: boolean;
 }
 
-/**
- * Type guard to check if presentation is unresolved.
- */
-export function isUnresolved(
-  presentation: UnresolvedPresentation | Presentation | undefined
-): presentation is UnresolvedPresentation {
-  return presentation !== undefined && 'url' in presentation && !('id' in presentation);
-}
-
-export function canResolve(
-  state: PresentationState
-): state is PresentationState & { presentation: UnresolvedPresentation } {
-  return isUnresolved(state.presentation);
-}
-
 /**
  * Determines if resolution conditions are met based on preload policy and playback state.
  *
  * Resolution conditions:
  * - State-driven: preload is 'auto' or 'metadata'
  * - Playback-driven: playbackInitiated is true
- *
- * @param state - Current presentation state
- * @returns true if resolution conditions are met
  */
 export function shouldResolve(state: PresentationState): boolean {
   const { preload, playbackInitiated } = state;
@@ -56,26 +36,35 @@ export function shouldResolve(state: PresentationState): boolean {
   );
 }
 
+/**
+ * True when there's a presentation with a URL that hasn't been resolved yet.
+ */
+export function canResolve(
+  state: PresentationState
+): state is PresentationState & { presentation: MaybeResolvedPresentation } {
+  return !!state.presentation?.url && !isResolvedPresentation(state.presentation);
+}
+
 export type ResolvePresentationState = 'preconditions-unmet' | 'idle' | 'resolving' | 'resolved';
 
 /**
- * Derives the correct state from current state conditions.
+ * Derives the current state from current state conditions.
  *
  * States are mutually exclusive and exhaustive:
  * - `'preconditions-unmet'`: no presentation, or presentation has no URL
- * - `'idle'`:     URL present, unresolved (no id), shouldResolve not met
- * - `'resolving'`: URL present, unresolved (no id), shouldResolve met
- * - `'resolved'`:  URL present, resolved (has id)
+ * - `'idle'`: URL present, unresolved, shouldResolve not met
+ * - `'resolving'`: URL present, unresolved, shouldResolve met
+ * - `'resolved'`: presentation has been resolved
  */
 function deriveState(state: PresentationState): ResolvePresentationState {
   const { presentation } = state;
-  if (!presentation || !('url' in presentation)) return 'preconditions-unmet';
-  if ('id' in presentation) return 'resolved';
+  if (!presentation?.url) return 'preconditions-unmet';
+  if (isResolvedPresentation(presentation)) return 'resolved';
   return shouldResolve(state) ? 'resolving' : 'idle';
 }
 
 /**
- * Resolves unresolved presentations using reactive composition.
+ * Resolves an unresolved presentation into a parsed `Presentation`.
  *
  * FSM driven by `deriveState` — a single `always` monitor keeps the state in
  * sync with conditions at all times. `'resolving'` additionally runs the fetch
@@ -103,7 +92,7 @@ export function resolvePresentation<S extends PresentationState>({
         // Entry: start fetch on state entry; return AbortController so the
         // framework aborts the in-flight request on state exit.
         entry: () => {
-          const presentation = state.get().presentation as UnresolvedPresentation;
+          const presentation = state.get().presentation!;
           const ac = new AbortController();
 
           fetchResolvable(presentation, { signal: ac.signal })
diff --git a/packages/spf/src/media/features/resolve-track.ts b/packages/spf/src/playback/behaviors/resolve-track.ts
similarity index 88%
rename from packages/spf/src/media/features/resolve-track.ts
rename to packages/spf/src/playback/behaviors/resolve-track.ts
index df05c0d1..0c9630d1 100644
--- a/packages/spf/src/media/features/resolve-track.ts
+++ b/packages/spf/src/playback/behaviors/resolve-track.ts
@@ -1,17 +1,17 @@
 import { effect } from '../../core/signals/effect';
 import type { Signal } from '../../core/signals/primitives';
 import { ConcurrentRunner, Task } from '../../core/tasks/task';
-import { fetchResolvable, getResponseText } from '../../dom/network/fetch';
-import { parseMediaPlaylist } from '../hls/parse-media-playlist';
-import type { Presentation, ResolvedTrack, TrackType } from '../types';
-import { isResolvedTrack } from '../types';
-import { getSelectedTrack, type TrackSelectionState } from '../utils/track-selection';
+import { parseMediaPlaylist } from '../../media/hls/parse-media-playlist';
+import type { MaybeResolvedPresentation, Presentation, ResolvedTrack, TrackType } from '../../media/types';
+import { isResolvedPresentation, isResolvedTrack } from '../../media/types';
+import { getSelectedTrack, type TrackSelectionState } from '../../media/utils/track-selection';
+import { fetchResolvable, getResponseText } from '../../network/fetch';
 
 /**
  * State shape for track resolution.
  */
 export interface TrackResolutionState extends TrackSelectionState {
-  presentation?: Presentation | undefined;
+  presentation?: MaybeResolvedPresentation;
   selectedVideoTrackId?: string | undefined;
   selectedAudioTrackId?: string | undefined;
   selectedTextTrackId?: string | undefined;
@@ -103,7 +103,8 @@ export function resolveTrack<S extends TrackResolutionState, T extends TrackType
           // presentation with its own resolved track. Reading live state ensures each
           // task builds on top of whatever has been committed so far.
           const latest = state.get();
-          const updatedPresentation = updateTrackInPresentation(latest.presentation!, mediaTrack);
+          if (!isResolvedPresentation(latest.presentation)) return;
+          const updatedPresentation = updateTrackInPresentation(latest.presentation, mediaTrack);
           state.set({ ...latest, presentation: updatedPresentation } as S);
         },
         { id: track.id }
diff --git a/packages/spf/src/playback/behaviors/select-tracks.ts b/packages/spf/src/playback/behaviors/select-tracks.ts
new file mode 100644
index 00000000..197dcb51
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/select-tracks.ts
@@ -0,0 +1,114 @@
+import { effect } from '../../core/signals/effect';
+import { type Signal, update } from '../../core/signals/primitives';
+import {
+  type AudioSelectionConfig,
+  canSelectTrack,
+  pickTextTrack,
+  shouldSelectTrack,
+  type TextSelectionConfig,
+  type TrackSelectionState,
+  type VideoSelectionConfig,
+} from '../../media/primitives/select-tracks';
+import { isResolvedPresentation } from '../../media/types';
+import { SelectedTrackIdKeyByType } from '../../media/utils/track-selection';
+
+/**
+ * Select video track orchestration.
+ *
+ * Selects video track when:
+ * - Presentation exists
+ * - No video track is selected yet
+ *
+ * Uses bandwidth-based quality selection algorithm.
+ *
+ * @example
+ * const cleanup = selectVideoTrack(
+ *   { state, owners, events },
+ *   { initialBandwidth: 2_000_000 }
+ * );
+ */
+export function selectVideoTrack<S extends TrackSelectionState>(
+  { state }: { state: Signal<S> },
+  config: VideoSelectionConfig = { type: 'video' }
+): () => void {
+  return effect(() => {
+    const currentState = state.get();
+    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+
+    // Just to have basic functionality/POC, simply selecting the first track
+    const selectedTrackId = currentState.presentation?.selectionSets?.find(({ type }) => type === config.type)
+      ?.switchingSets[0]?.tracks[0]?.id;
+
+    if (selectedTrackId) {
+      const selectedTrackKey = SelectedTrackIdKeyByType[config.type];
+      const patch: Partial<TrackSelectionState> = { [selectedTrackKey]: selectedTrackId };
+      update(state, patch);
+    }
+  });
+}
+
+/**
+ * Select audio track orchestration.
+ *
+ * Selects audio track when:
+ * - Presentation exists
+ * - No audio track is selected yet
+ *
+ * Uses language and preference-based selection.
+ *
+ * @example
+ * const cleanup = selectAudioTrack(
+ *   { state, owners, events },
+ *   { preferredAudioLanguage: 'en' }
+ * );
+ */
+export function selectAudioTrack<S extends TrackSelectionState>(
+  { state }: { state: Signal<S> },
+  config: AudioSelectionConfig = { type: 'audio' }
+): () => void {
+  return effect(() => {
+    const currentState = state.get();
+    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+
+    // Just to have basic functionality/POC, simply selecting the first track
+    const selectedTrackId = currentState.presentation?.selectionSets?.find(({ type }) => type === 'audio')
+      ?.switchingSets[0]?.tracks[0]?.id;
+
+    if (selectedTrackId) {
+      const patch: Partial<TrackSelectionState> = { selectedAudioTrackId: selectedTrackId };
+      update(state, patch);
+    }
+  });
+}
+
+/**
+ * Select text track orchestration.
+ *
+ * Selects text track when:
+ * - Presentation exists
+ * - No text track is selected yet
+ *
+ * Note: Currently does not auto-select (user opt-in).
+ *
+ * @example
+ * const cleanup = selectTextTrack({ state, owners, events }, {});
+ */
+export function selectTextTrack<S extends TrackSelectionState>(
+  { state }: { state: Signal<S> },
+  config: TextSelectionConfig = { type: 'text' }
+): () => void {
+  return effect(() => {
+    const currentState = state.get();
+    if (!canSelectTrack(currentState, config) || !shouldSelectTrack(currentState, config)) return;
+
+    if (!isResolvedPresentation(currentState.presentation)) return;
+
+    // Text tracks are user opt-in - don't auto-select
+    const selectedTextTrackId = pickTextTrack(currentState.presentation, config);
+
+    if (selectedTextTrackId) {
+      const patch: Partial<TrackSelectionState> = { selectedTextTrackId };
+      update(state, patch);
+    }
+  });
+}
diff --git a/packages/spf/src/media/features/sync-preload-attribute.ts b/packages/spf/src/playback/behaviors/sync-preload-attribute.ts
similarity index 89%
rename from packages/spf/src/media/features/sync-preload-attribute.ts
rename to packages/spf/src/playback/behaviors/sync-preload-attribute.ts
index af053fc1..9adb6497 100644
--- a/packages/spf/src/media/features/sync-preload-attribute.ts
+++ b/packages/spf/src/playback/behaviors/sync-preload-attribute.ts
@@ -1,6 +1,6 @@
 import { effect } from '../../core/signals/effect';
 import { computed, type Signal, update } from '../../core/signals/primitives';
-import type { MediaElementLike } from '../types';
+import type { MediaElementLike } from '../../media/types';
 import type { PresentationState } from './resolve-presentation';
 
 /**
@@ -15,7 +15,7 @@ export interface PlatformOwners {
  *
  * Watches the owners signal for mediaElement changes and copies the
  * preload attribute to state when no explicit value has been set.
- * An explicit value (set via SpfMedia.preload) always wins.
+ * An explicit value (set via SimpleHlsMediaElement.preload) always wins.
  *
  * @example
  * const cleanup = syncPreloadAttribute({ state, owners });
diff --git a/packages/spf/src/media/features/tests/calculate-presentation-duration.test.ts b/packages/spf/src/playback/behaviors/tests/calculate-presentation-duration.test.ts
similarity index 99%
rename from packages/spf/src/media/features/tests/calculate-presentation-duration.test.ts
rename to packages/spf/src/playback/behaviors/tests/calculate-presentation-duration.test.ts
index 6b7610b7..e94b9b75 100644
--- a/packages/spf/src/media/features/tests/calculate-presentation-duration.test.ts
+++ b/packages/spf/src/playback/behaviors/tests/calculate-presentation-duration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { signal } from '../../../core/signals/primitives';
-import type { AudioTrack, Presentation, VideoTrack } from '../../types';
+import type { AudioTrack, Presentation, VideoTrack } from '../../../media/types';
 import {
   calculatePresentationDuration,
   canCalculateDuration,
diff --git a/packages/spf/src/media/features/tests/quality-switching.test.ts b/packages/spf/src/playback/behaviors/tests/quality-switching.test.ts
similarity index 99%
rename from packages/spf/src/media/features/tests/quality-switching.test.ts
rename to packages/spf/src/playback/behaviors/tests/quality-switching.test.ts
index d03ad6be..ee1c25ae 100644
--- a/packages/spf/src/media/features/tests/quality-switching.test.ts
+++ b/packages/spf/src/playback/behaviors/tests/quality-switching.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { signal } from '../../../core/signals/primitives';
-import type { BandwidthState } from '../../abr/bandwidth-estimator';
-import type { PartiallyResolvedVideoTrack, Presentation, VideoSelectionSet } from '../../types';
+import type { BandwidthState } from '../../../media/abr/bandwidth-estimator';
+import type { PartiallyResolvedVideoTrack, Presentation, VideoSelectionSet } from '../../../media/types';
 import {
   DEFAULT_SWITCHING_CONFIG,
   type QualitySwitchingConfig,
diff --git a/packages/spf/src/media/features/tests/resolve-presentation.test.ts b/packages/spf/src/playback/behaviors/tests/resolve-presentation.test.ts
similarity index 85%
rename from packages/spf/src/media/features/tests/resolve-presentation.test.ts
rename to packages/spf/src/playback/behaviors/tests/resolve-presentation.test.ts
index 2370f42d..585441db 100644
--- a/packages/spf/src/media/features/tests/resolve-presentation.test.ts
+++ b/packages/spf/src/playback/behaviors/tests/resolve-presentation.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { signal } from '../../../core/signals/primitives';
-import type { AddressableObject, Presentation } from '../../types';
-import { isUnresolved, resolvePresentation, shouldResolve } from '../resolve-presentation';
+import type { MaybeResolvedPresentation, Presentation } from '../../../media/types';
+import { resolvePresentation, shouldResolve } from '../resolve-presentation';
 
 describe('resolvePresentation', () => {
   afterEach(() => {
@@ -10,7 +10,7 @@ describe('resolvePresentation', () => {
   it('resolves unresolved presentation', async () => {
     // Arrange
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
+      presentation?: MaybeResolvedPresentation;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
@@ -61,7 +61,7 @@ variant2.m3u8`)
   it('does not trigger resolution when other state fields change', async () => {
     // Arrange
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
+      presentation?: MaybeResolvedPresentation;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
       volume: number;
     }
@@ -113,7 +113,7 @@ variant1.m3u8`)
   it('resolves presentation initialized as unresolved', async () => {
     // Arrange
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
+      presentation?: MaybeResolvedPresentation;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
@@ -151,7 +151,7 @@ variant1.m3u8`)
   it('does not re-resolve presentation initialized as resolved', async () => {
     // Arrange
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
+      presentation?: MaybeResolvedPresentation;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
@@ -209,7 +209,7 @@ variant1.m3u8`)
   it('resolves new unresolved presentation after resolved one', async () => {
     // Arrange
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
+      presentation?: MaybeResolvedPresentation;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
@@ -258,7 +258,7 @@ variant2.m3u8`)
   describe('preload policy', () => {
     it('resolves when preload is "auto"', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -284,7 +284,7 @@ variant1.m3u8`)
 
     it('resolves when preload is "metadata"', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -310,7 +310,7 @@ variant1.m3u8`)
 
     it('does not resolve when preload is "none"', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -326,14 +326,15 @@ variant1.m3u8`)
       await new Promise((resolve) => setTimeout(resolve, 50));
 
       expect(fetchSpy).not.toHaveBeenCalled();
-      expect(state.get().presentation).toEqual({ url: 'http://example.com/playlist.m3u8' });
+      expect(state.get().presentation?.url).toBe('http://example.com/playlist.m3u8');
+      expect(state.get().presentation).not.toHaveProperty('id');
 
       reactor.destroy();
     });
 
     it('does not resolve when preload is undefined', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -349,7 +350,8 @@ variant1.m3u8`)
       await new Promise((resolve) => setTimeout(resolve, 50));
 
       expect(fetchSpy).not.toHaveBeenCalled();
-      expect(state.get().presentation).toEqual({ url: 'http://example.com/playlist.m3u8' });
+      expect(state.get().presentation?.url).toBe('http://example.com/playlist.m3u8');
+      expect(state.get().presentation).not.toHaveProperty('id');
 
       reactor.destroy();
     });
@@ -358,7 +360,7 @@ variant1.m3u8`)
   describe('playbackInitiated resolution', () => {
     it('resolves when playbackInitiated is set to true with preload "none"', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
         playbackInitiated?: boolean;
       }
@@ -394,7 +396,7 @@ variant1.m3u8`)
 
     it('does not resolve when playbackInitiated is false with preload "none"', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
         playbackInitiated?: boolean;
       }
@@ -411,7 +413,8 @@ variant1.m3u8`)
       await new Promise((resolve) => setTimeout(resolve, 50));
 
       expect(fetchSpy).not.toHaveBeenCalled();
-      expect(state.get().presentation).toEqual({ url: 'http://example.com/playlist.m3u8' });
+      expect(state.get().presentation?.url).toBe('http://example.com/playlist.m3u8');
+      expect(state.get().presentation).not.toHaveProperty('id');
 
       reactor.destroy();
     });
@@ -420,7 +423,7 @@ variant1.m3u8`)
   describe('deduplication', () => {
     it('does not trigger multiple fetches for same presentation', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -454,7 +457,7 @@ variant1.m3u8`)
 
     it('allows resolving different presentations sequentially', async () => {
       interface State {
-        presentation?: AddressableObject | Presentation | undefined;
+        presentation?: MaybeResolvedPresentation;
         preload?: 'auto' | 'metadata' | 'none' | undefined;
       }
 
@@ -479,7 +482,7 @@ variant1.m3u8`)
 
       expect(fetchSpy).toHaveBeenCalledOnce();
 
-      // Now load a different presentation
+      // Now load a different presentation (overwrites the resolved one with an unresolved one)
       state.set({ ...state.get(), presentation: { url: 'http://example.com/second.m3u8' } });
 
       // Wait for second resolution — check id to confirm the fetch actually completed
@@ -499,13 +502,19 @@ variant1.m3u8`)
 
 describe('shouldResolve', () => {
   it('returns true when preload is "auto"', () => {
-    const result = shouldResolve({ presentation: { url: 'http://example.com/playlist.m3u8' }, preload: 'auto' });
+    const result = shouldResolve({
+      presentation: { url: 'http://example.com/playlist.m3u8' },
+      preload: 'auto',
+    });
 
     expect(result).toBe(true);
   });
 
   it('returns true when preload is "metadata"', () => {
-    const result = shouldResolve({ presentation: { url: 'http://example.com/playlist.m3u8' }, preload: 'metadata' });
+    const result = shouldResolve({
+      presentation: { url: 'http://example.com/playlist.m3u8' },
+      preload: 'metadata',
+    });
 
     expect(result).toBe(true);
   });
@@ -521,7 +530,10 @@ describe('shouldResolve', () => {
   });
 
   it('returns false when preload is "none" and playbackInitiated is false', () => {
-    const result = shouldResolve({ presentation: { url: 'http://example.com/playlist.m3u8' }, preload: 'none' });
+    const result = shouldResolve({
+      presentation: { url: 'http://example.com/playlist.m3u8' },
+      preload: 'none',
+    });
 
     expect(result).toBe(false);
   });
@@ -535,30 +547,3 @@ describe('shouldResolve', () => {
     expect(result).toBe(false);
   });
 });
-
-describe('isUnresolved', () => {
-  const resolvedPresentation: Presentation = {
-    id: 'pres-1',
-    url: 'http://example.com/resolved.m3u8',
-    selectionSets: [],
-    startTime: 0,
-  };
-
-  it('returns true for unresolved presentation', () => {
-    const result = isUnresolved({ url: 'http://example.com/playlist.m3u8' });
-
-    expect(result).toBe(true);
-  });
-
-  it('returns false for resolved presentation', () => {
-    const result = isUnresolved(resolvedPresentation);
-
-    expect(result).toBe(false);
-  });
-
-  it('returns false for undefined', () => {
-    const result = isUnresolved(undefined);
-
-    expect(result).toBe(false);
-  });
-});
diff --git a/packages/spf/src/media/features/tests/resolve-track.test.ts b/packages/spf/src/playback/behaviors/tests/resolve-track.test.ts
similarity index 97%
rename from packages/spf/src/media/features/tests/resolve-track.test.ts
rename to packages/spf/src/playback/behaviors/tests/resolve-track.test.ts
index 475607df..ac4769f6 100644
--- a/packages/spf/src/media/features/tests/resolve-track.test.ts
+++ b/packages/spf/src/playback/behaviors/tests/resolve-track.test.ts
@@ -1,12 +1,13 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { signal } from '../../../core/signals/primitives';
 import type {
+  MaybeResolvedPresentation,
   PartiallyResolvedAudioTrack,
   PartiallyResolvedTextTrack,
   PartiallyResolvedVideoTrack,
   Presentation,
-} from '../../types';
-import { isResolvedTrack } from '../../types';
+} from '../../../media/types';
+import { isResolvedTrack } from '../../../media/types';
 import type { TrackResolutionState } from '../resolve-track';
 import { resolveTrack } from '../resolve-track';
 
@@ -436,8 +437,11 @@ http://example.com/a-seg1.m4s
 });
 
 // Helper to find track by ID in presentation
-function findTrackById(presentation: Presentation, trackId: string): PartiallyResolvedVideoTrack | any | undefined {
-  for (const selectionSet of presentation.selectionSets) {
+function findTrackById(
+  presentation: MaybeResolvedPresentation,
+  trackId: string
+): PartiallyResolvedVideoTrack | any | undefined {
+  for (const selectionSet of presentation.selectionSets ?? []) {
     for (const switchingSet of selectionSet.switchingSets) {
       const track = switchingSet.tracks.find((t) => t.id === trackId);
       if (track) return track;
diff --git a/packages/spf/src/playback/behaviors/tests/select-tracks.test.ts b/packages/spf/src/playback/behaviors/tests/select-tracks.test.ts
new file mode 100644
index 00000000..b51a9205
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/tests/select-tracks.test.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it } from 'vitest';
+import { signal } from '../../../core/signals/primitives';
+import type { TrackSelectionState } from '../../../media/primitives/select-tracks';
+import type {
+  AudioSelectionSet,
+  PartiallyResolvedAudioTrack,
+  PartiallyResolvedVideoTrack,
+  Presentation,
+  TextSelectionSet,
+  VideoSelectionSet,
+} from '../../../media/types';
+import { selectAudioTrack, selectTextTrack, selectVideoTrack } from '../select-tracks';
+
+// Helper to create a minimal presentation
+function createPresentation(config: {
+  video?: PartiallyResolvedVideoTrack[];
+  audio?: PartiallyResolvedAudioTrack[];
+  text?: any[];
+}): Presentation {
+  const selectionSets = [];
+
+  if (config.video && config.video.length > 0) {
+    selectionSets.push({
+      id: 'video-set',
+      type: 'video' as const,
+      switchingSets: [
+        {
+          id: 'video-switching',
+          type: 'video' as const,
+          tracks: config.video,
+        },
+      ],
+    } as VideoSelectionSet);
+  }
+
+  if (config.audio && config.audio.length > 0) {
+    selectionSets.push({
+      id: 'audio-set',
+      type: 'audio' as const,
+      switchingSets: [
+        {
+          id: 'audio-switching',
+          type: 'audio' as const,
+          tracks: config.audio,
+        },
+      ],
+    } as AudioSelectionSet);
+  }
+
+  if (config.text && config.text.length > 0) {
+    selectionSets.push({
+      id: 'text-set',
+      type: 'text' as const,
+      switchingSets: [
+        {
+          id: 'text-switching',
+          type: 'text' as const,
+          tracks: config.text,
+        },
+      ],
+    } as TextSelectionSet);
+  }
+
+  return {
+    id: 'pres-1',
+    url: 'http://example.com/playlist.m3u8',
+    selectionSets,
+    startTime: 0,
+  };
+}
+
+describe('selectVideoTrack', () => {
+  it('selects video track when presentation loaded', async () => {
+    const videoTracks: PartiallyResolvedVideoTrack[] = [
+      {
+        type: 'video',
+        id: 'video-360p',
+        url: 'http://example.com/360p.m3u8',
+        bandwidth: 500_000,
+        mimeType: 'video/mp4',
+        codecs: ['avc1.42E01E'],
+      },
+    ];
+
+    const presentation = createPresentation({ video: videoTracks });
+
+    const state = signal<TrackSelectionState>({ presentation });
+
+    const cleanup = selectVideoTrack({ state }, { type: 'video' });
+
+    // Wait for selection
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedVideoTrackId).toBe('video-360p');
+
+    cleanup();
+  });
+
+  it('does not select when video track already selected', async () => {
+    const presentation = createPresentation({ video: [] });
+
+    const state = signal<TrackSelectionState>({
+      presentation,
+      selectedVideoTrackId: 'existing-video',
+    });
+
+    const cleanup = selectVideoTrack({ state }, { type: 'video' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedVideoTrackId).toBe('existing-video');
+
+    cleanup();
+  });
+
+  it.skip('uses bandwidth configuration for initial selection', async () => {
+    const videoTracks: PartiallyResolvedVideoTrack[] = [
+      {
+        type: 'video',
+        id: 'video-360p',
+        url: 'http://example.com/360p.m3u8',
+        bandwidth: 500_000,
+        mimeType: 'video/mp4',
+        codecs: ['avc1.42E01E'],
+      },
+      {
+        type: 'video',
+        id: 'video-720p',
+        url: 'http://example.com/720p.m3u8',
+        bandwidth: 2_000_000,
+        mimeType: 'video/mp4',
+        codecs: ['avc1.42E01E'],
+      },
+    ];
+
+    const presentation = createPresentation({ video: videoTracks });
+
+    const state = signal<TrackSelectionState>({ presentation });
+
+    const cleanup = selectVideoTrack({ state }, { initialBandwidth: 3_000_000, type: 'video' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedVideoTrackId).toBe('video-720p');
+
+    cleanup();
+  });
+});
+
+describe('selectAudioTrack', () => {
+  it('selects audio track when presentation loaded', async () => {
+    const audioTracks: PartiallyResolvedAudioTrack[] = [
+      {
+        type: 'audio',
+        id: 'audio-en',
+        url: 'http://example.com/audio-en.m3u8',
+        bandwidth: 128_000,
+        mimeType: 'audio/mp4',
+        codecs: ['mp4a.40.2'],
+        groupId: 'audio',
+        name: 'English',
+        sampleRate: 48000,
+        channels: 2,
+      },
+    ];
+
+    const presentation = createPresentation({ audio: audioTracks });
+
+    const state = signal<TrackSelectionState>({ presentation });
+
+    const cleanup = selectAudioTrack({ state }, { type: 'audio' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedAudioTrackId).toBe('audio-en');
+
+    cleanup();
+  });
+
+  it('does not select when audio track already selected', async () => {
+    const presentation = createPresentation({ audio: [] });
+
+    const state = signal<TrackSelectionState>({
+      presentation,
+      selectedAudioTrackId: 'existing-audio',
+    });
+
+    const cleanup = selectAudioTrack({ state }, { type: 'audio' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedAudioTrackId).toBe('existing-audio');
+
+    cleanup();
+  });
+
+  it.skip('uses preferred language configuration', async () => {
+    const audioTracks: PartiallyResolvedAudioTrack[] = [
+      {
+        type: 'audio',
+        id: 'audio-en',
+        url: 'http://example.com/audio-en.m3u8',
+        bandwidth: 128_000,
+        mimeType: 'audio/mp4',
+        codecs: ['mp4a.40.2'],
+        groupId: 'audio',
+        name: 'English',
+        language: 'en',
+        sampleRate: 48000,
+        channels: 2,
+      },
+      {
+        type: 'audio',
+        id: 'audio-es',
+        url: 'http://example.com/audio-es.m3u8',
+        bandwidth: 128_000,
+        mimeType: 'audio/mp4',
+        codecs: ['mp4a.40.2'],
+        groupId: 'audio',
+        name: 'Spanish',
+        language: 'es',
+        sampleRate: 48000,
+        channels: 2,
+      },
+    ];
+
+    const presentation = createPresentation({ audio: audioTracks });
+
+    const state = signal<TrackSelectionState>({ presentation });
+
+    const cleanup = selectAudioTrack({ state }, { type: 'audio', preferredAudioLanguage: 'es' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedAudioTrackId).toBe('audio-es');
+
+    cleanup();
+  });
+});
+
+describe('selectTextTrack', () => {
+  it('does not auto-select text track', async () => {
+    const textTracks = [
+      {
+        type: 'text' as const,
+        id: 'text-en',
+        url: 'http://example.com/text-en.m3u8',
+        bandwidth: 256,
+        mimeType: 'application/mp4',
+        groupId: 'text',
+        label: 'English',
+        kind: 'subtitles' as const,
+      },
+    ];
+
+    const presentation = createPresentation({ text: textTracks });
+
+    const state = signal<TrackSelectionState>({ presentation });
+
+    const cleanup = selectTextTrack({ state }, { type: 'text' });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(state.get().selectedTextTrackId).toBeUndefined();
+
+    cleanup();
+  });
+});
diff --git a/packages/spf/src/media/features/tests/sync-preload-attribute.test.ts b/packages/spf/src/playback/behaviors/tests/sync-preload-attribute.test.ts
similarity index 80%
rename from packages/spf/src/media/features/tests/sync-preload-attribute.test.ts
rename to packages/spf/src/playback/behaviors/tests/sync-preload-attribute.test.ts
index 175bd104..3112deb7 100644
--- a/packages/spf/src/media/features/tests/sync-preload-attribute.test.ts
+++ b/packages/spf/src/playback/behaviors/tests/sync-preload-attribute.test.ts
@@ -1,26 +1,24 @@
 import { describe, expect, it, vi } from 'vitest';
 import { signal } from '../../../core/signals/primitives';
-import type { AddressableObject, Presentation } from '../../types';
+import type { MediaElementLike } from '../../../media/types';
 import { syncPreloadAttribute } from '../sync-preload-attribute';
 
 describe('syncPreloadAttribute', () => {
   it('syncs preload from mediaElement to state', async () => {
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
     interface Owners {
-      mediaElement?: HTMLMediaElement | undefined;
+      mediaElement?: MediaElementLike | undefined;
     }
 
     const state = signal<State>({
-      presentation: undefined,
       preload: undefined,
     });
 
     // Start with media element already set
-    const video = { preload: 'auto' } as HTMLMediaElement;
+    const video = { preload: 'auto' } as MediaElementLike;
     const owners = signal<Owners>({
       mediaElement: video,
     });
@@ -35,20 +33,18 @@ describe('syncPreloadAttribute', () => {
 
   it('does not override preload when mediaElement changes and preload is already set', async () => {
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
     interface Owners {
-      mediaElement?: HTMLMediaElement | undefined;
+      mediaElement?: MediaElementLike | undefined;
     }
 
     const state = signal<State>({
-      presentation: undefined,
       preload: undefined,
     });
 
-    const video = { preload: 'auto' } as HTMLMediaElement;
+    const video = { preload: 'auto' } as MediaElementLike;
     const owners = signal<Owners>({
       mediaElement: video,
     });
@@ -60,7 +56,7 @@ describe('syncPreloadAttribute', () => {
 
     // Swap to a different mediaElement with a different preload value.
     // Since preload is already set, the new element's value is ignored.
-    const updatedVideo = { preload: 'metadata' } as HTMLMediaElement;
+    const updatedVideo = { preload: 'metadata' } as MediaElementLike;
     owners.set({ ...owners.get(), mediaElement: updatedVideo });
 
     await vi.waitFor(() => {
@@ -77,7 +73,7 @@ describe('syncPreloadAttribute', () => {
     }
 
     interface Owners {
-      mediaElement?: HTMLMediaElement | undefined;
+      mediaElement?: MediaElementLike | undefined;
     }
 
     const state = signal<State>({ preload: undefined });
@@ -98,12 +94,12 @@ describe('syncPreloadAttribute', () => {
     }
 
     interface Owners {
-      mediaElement?: HTMLMediaElement | undefined;
+      mediaElement?: MediaElementLike | undefined;
     }
 
     const state = signal<State>({ preload: undefined });
     // Browsers return '' when the preload attribute is absent
-    const owners = signal<Owners>({ mediaElement: { preload: '' } as HTMLMediaElement });
+    const owners = signal<Owners>({ mediaElement: { preload: '' } as MediaElementLike });
 
     const cleanup = syncPreloadAttribute({ state, owners });
 
@@ -114,16 +110,14 @@ describe('syncPreloadAttribute', () => {
 
   it('does not clear preload when mediaElement is removed and preload is already set', async () => {
     interface State {
-      presentation?: AddressableObject | Presentation | undefined;
       preload?: 'auto' | 'metadata' | 'none' | undefined;
     }
 
     interface Owners {
-      mediaElement?: HTMLMediaElement | undefined;
+      mediaElement?: MediaElementLike | undefined;
     }
 
     const state = signal<State>({
-      presentation: undefined,
       preload: 'auto',
     });
 
diff --git a/packages/spf/src/playback/behaviors/tsconfig.json b/packages/spf/src/playback/behaviors/tsconfig.json
new file mode 100644
index 00000000..3ba6006f
--- /dev/null
+++ b/packages/spf/src/playback/behaviors/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "WebWorker"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../types/playback/behaviors"
+  },
+  "references": [
+    { "path": "../../../../utils" },
+    { "path": "../../core" },
+    { "path": "../../network" },
+    { "path": "../../media" },
+    { "path": "../actors" }
+  ],
+  "include": ["./*.ts", "./tests/**/*.ts"],
+  "exclude": ["./dom/**"]
+}
diff --git a/packages/spf/src/dom/playback-engine/adapter.ts b/packages/spf/src/playback/engines/hls/adapter.ts
similarity index 79%
rename from packages/spf/src/dom/playback-engine/adapter.ts
rename to packages/spf/src/playback/engines/hls/adapter.ts
index 4a851499..a4f0308b 100644
--- a/packages/spf/src/dom/playback-engine/adapter.ts
+++ b/packages/spf/src/playback/engines/hls/adapter.ts
@@ -1,25 +1,25 @@
 import type { Constructor, MixinReturn } from '@videojs/utils/types';
-import type { Composition } from '../../core/composition/create-composition';
-import { update } from '../../core/signals/primitives';
+import type { Composition } from '../../../core/composition/create-composition';
+import { update } from '../../../core/signals/primitives';
 import {
-  createHlsPlaybackEngine,
-  type HlsPlaybackEngineConfig,
-  type HlsPlaybackEngineOwners,
-  type HlsPlaybackEngineState,
-} from './hls-engine';
+  createSimpleHlsEngine,
+  type SimpleHlsEngineConfig,
+  type SimpleHlsEngineOwners,
+  type SimpleHlsEngineState,
+} from './engine';
 
-export interface SpfMediaProps {
+export interface SimpleHlsMediaProps {
   src: string;
   preload: '' | 'none' | 'metadata' | 'auto';
 }
 
-export const spfMediaDefaultProps: SpfMediaProps = {
+export const simpleHlsMediaDefaultProps: SimpleHlsMediaProps = {
   src: '',
   preload: '',
 };
 
-export interface SpfMediaAPI extends SpfMediaProps {
-  readonly engine: Composition<HlsPlaybackEngineState, HlsPlaybackEngineOwners>;
+export interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {
+  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineOwners>;
   attach(mediaElement: HTMLMediaElement): void;
   detach(): void;
   destroy(): void;
@@ -38,17 +38,17 @@ export interface SpfMediaAPI extends SpfMediaProps {
  * changes and re-applied to the new engine automatically.
  *
  * @example
- * class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+ * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}
  *
  * const media = new SimpleHlsMedia();
  * media.attach(document.querySelector('video'));
  * media.src = 'https://stream.mux.com/abc123.m3u8';
  */
-export function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
-  class SpfMediaImpl extends BaseClass {
-    #engine: Composition<HlsPlaybackEngineState, HlsPlaybackEngineOwners>;
-    #config: HlsPlaybackEngineConfig;
-    #preload: '' | 'none' | 'metadata' | 'auto' = spfMediaDefaultProps.preload;
+export function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
+  class SimpleHlsMediaImpl extends BaseClass {
+    #engine: Composition<SimpleHlsEngineState, SimpleHlsEngineOwners>;
+    #config: SimpleHlsEngineConfig;
+    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsMediaDefaultProps.preload;
 
     /** Pending loadstart listener from a deferred play() retry, if any. */
     #loadstartListener: (() => void) | null = null;
@@ -58,10 +58,10 @@ export function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
 
       const { config } = args?.[0] ?? {};
       this.#config = config;
-      this.#engine = createHlsPlaybackEngine(config);
+      this.#engine = createSimpleHlsEngine(config);
     }
 
-    get engine(): Composition<HlsPlaybackEngineState, HlsPlaybackEngineOwners> {
+    get engine(): Composition<SimpleHlsEngineState, SimpleHlsEngineOwners> {
       return this.#engine;
     }
 
@@ -118,7 +118,7 @@ export function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
 
       this.#cancelPendingPlay();
       this.#engine.destroy();
-      this.#engine = createHlsPlaybackEngine(this.#config);
+      this.#engine = createSimpleHlsEngine(this.#config);
 
       // Apply explicit preload before setting owners so syncPreloadAttribute skips
       // element inference and the explicit value is preserved across src changes.
@@ -143,7 +143,7 @@ export function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
     play(): Promise<void> {
       const { mediaElement } = this.#engine.owners.get();
       if (!mediaElement) {
-        return Promise.reject(new Error('SpfMedia: no media element attached'));
+        return Promise.reject(new Error('SimpleHlsMediaElement: no media element attached'));
       }
 
       // Signal play intent — enables loading even with preload="none"
@@ -179,8 +179,8 @@ export function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {
     }
   }
 
-  return SpfMediaImpl as unknown as MixinReturn<Base, SpfMediaAPI>;
+  return SimpleHlsMediaImpl as unknown as MixinReturn<Base, SimpleHlsMediaAPI>;
 }
 
 /** Standalone SPF media adapter with no base class. */
-export class SpfMedia extends SpfMediaMixin(class {}) {}
+export class SimpleHlsMediaElement extends SimpleHlsMediaMixin(class {}) {}
diff --git a/packages/spf/src/dom/playback-engine/hls-engine.ts b/packages/spf/src/playback/engines/hls/engine.ts
similarity index 59%
rename from packages/spf/src/dom/playback-engine/hls-engine.ts
rename to packages/spf/src/playback/engines/hls/engine.ts
index 026d61c8..2667eb6f 100644
--- a/packages/spf/src/dom/playback-engine/hls-engine.ts
+++ b/packages/spf/src/playback/engines/hls/engine.ts
@@ -1,25 +1,31 @@
-import { type Composition, createComposition } from '../../core/composition/create-composition';
-import type { ReadonlySignal, Signal } from '../../core/signals/primitives';
-import type { BandwidthState } from '../../media/abr/bandwidth-estimator';
-import { calculatePresentationDuration } from '../../media/features/calculate-presentation-duration';
-import { switchQuality } from '../../media/features/quality-switching';
-import { resolvePresentation } from '../../media/features/resolve-presentation';
-import { resolveTrack } from '../../media/features/resolve-track';
-import { selectAudioTrack, selectTextTrack, selectVideoTrack } from '../../media/features/select-tracks';
-import { syncPreloadAttribute } from '../../media/features/sync-preload-attribute';
-import { endOfStream } from '../features/end-of-stream';
-import { loadSegments } from '../features/load-segments';
-import { loadTextTrackCues } from '../features/load-text-track-cues';
-import { setupMediaSource } from '../features/setup-mediasource';
-import { setupSourceBuffers } from '../features/setup-sourcebuffer';
-import { syncTextTracks } from '../features/sync-text-tracks';
-import type { TextTrackSegmentLoaderActor } from '../features/text-track-segment-loader-actor';
-import type { TextTracksActor } from '../features/text-tracks-actor';
-import { trackCurrentTime } from '../features/track-current-time';
-import { trackPlaybackInitiated } from '../features/track-playback-initiated';
-import { updateDuration } from '../features/update-duration';
-import type { SourceBufferActor } from '../media/source-buffer-actor';
-import { destroyVttParser } from '../text/parse-vtt-segment';
+import { type Composition, createComposition } from '../../../core/composition/create-composition';
+import type { Signal } from '../../../core/signals/primitives';
+import type { BandwidthState } from '../../../media/abr/bandwidth-estimator';
+import { resolveVttSegment } from '../../../media/dom/text/resolve-vtt-segment';
+import type { MaybeResolvedPresentation } from '../../../media/types';
+import type { SourceBufferActor } from '../../actors/dom/source-buffer';
+import type { TextTracksActor } from '../../actors/dom/text-tracks';
+import type { TextTrackSegmentLoaderActor } from '../../actors/text-track-segment-loader';
+import { calculatePresentationDuration } from '../../behaviors/calculate-presentation-duration';
+import { endOfStream } from '../../behaviors/dom/end-of-stream';
+import { loadSegments } from '../../behaviors/dom/load-segments';
+import { setupMediaSource } from '../../behaviors/dom/setup-mediasource';
+import { setupSourceBuffers } from '../../behaviors/dom/setup-sourcebuffer';
+import { setupTextTrackActors as _setupTextTrackActors } from '../../behaviors/dom/setup-text-track-actors';
+import { syncTextTracks } from '../../behaviors/dom/sync-text-tracks';
+import { trackCurrentTime } from '../../behaviors/dom/track-current-time';
+import { trackPlaybackInitiated } from '../../behaviors/dom/track-playback-initiated';
+import { updateDuration } from '../../behaviors/dom/update-duration';
+import { loadTextTrackCues } from '../../behaviors/load-text-track-cues';
+import { switchQuality as _switchQuality } from '../../behaviors/quality-switching';
+import { resolvePresentation } from '../../behaviors/resolve-presentation';
+import { resolveTrack } from '../../behaviors/resolve-track';
+import {
+  selectAudioTrack as _selectAudioTrack,
+  selectTextTrack as _selectTextTrack,
+  selectVideoTrack as _selectVideoTrack,
+} from '../../behaviors/select-tracks';
+import { syncPreloadAttribute } from '../../behaviors/sync-preload-attribute';
 
 // ============================================================================
 // HLS Engine State & Owners
@@ -32,12 +38,12 @@ import { destroyVttParser } from '../text/parse-vtt-segment';
  * the HLS engine. Each behavior declares its own state interface; this
  * type satisfies all of them.
  */
-export interface HlsPlaybackEngineState {
-  // `any` is intentional: the presentation field transitions from unresolved
-  // ({ url: string }) to resolved (Presentation) at runtime. Individual behaviors
-  // declare narrower constraints and narrow the type themselves. Using a union
-  // here would break Signal invariance against the behavior interfaces.
-  presentation?: any;
+export interface SimpleHlsEngineState {
+  /**
+   * The presentation being played. A caller writes `{ url }`;
+   * `resolvePresentation` parses the manifest and populates the rest.
+   */
+  presentation?: MaybeResolvedPresentation;
   preload?: 'auto' | 'metadata' | 'none';
   selectedVideoTrackId?: string;
   selectedAudioTrackId?: string;
@@ -46,6 +52,7 @@ export interface HlsPlaybackEngineState {
   abrDisabled?: boolean;
   currentTime?: number;
   playbackInitiated?: boolean;
+  mediaSourceReadyState?: MediaSource['readyState'];
 }
 
 /**
@@ -53,10 +60,9 @@ export interface HlsPlaybackEngineState {
  *
  * Platform objects and actor references managed by HLS behaviors.
  */
-export interface HlsPlaybackEngineOwners {
+export interface SimpleHlsEngineOwners {
   mediaElement?: HTMLMediaElement | undefined;
   mediaSource?: MediaSource;
-  mediaSourceReadyState?: ReadonlySignal<MediaSource['readyState']>;
   videoBuffer?: SourceBuffer;
   audioBuffer?: SourceBuffer;
   videoBufferActor?: SourceBufferActor;
@@ -71,7 +77,7 @@ export interface HlsPlaybackEngineOwners {
  * Each option is consumed by the appropriate behavior — the engine itself
  * has no config beyond what its behaviors read.
  */
-export interface HlsPlaybackEngineConfig {
+export interface SimpleHlsEngineConfig {
   initialBandwidth?: number;
   preferredAudioLanguage?: string;
   preferredSubtitleLanguage?: string;
@@ -81,9 +87,9 @@ export interface HlsPlaybackEngineConfig {
 
 /** Shorthand for the deps shape used by HLS engine behaviors. */
 type Deps = {
-  state: Signal<HlsPlaybackEngineState>;
-  owners: Signal<HlsPlaybackEngineOwners>;
-  config: HlsPlaybackEngineConfig;
+  state: Signal<SimpleHlsEngineState>;
+  owners: Signal<SimpleHlsEngineOwners>;
+  config: SimpleHlsEngineConfig;
 };
 
 // ============================================================================
@@ -101,6 +107,9 @@ const resolveVideoTrack = (deps: Deps) => resolveTrack(deps, { type: 'video' as
 const resolveAudioTrack = (deps: Deps) => resolveTrack(deps, { type: 'audio' as const });
 const resolveTextTrack = (deps: Deps) => resolveTrack(deps, { type: 'text' as const });
 
+const setupTextTrackActors = ({ owners }: Deps) =>
+  _setupTextTrackActors({ owners, config: { resolveTextTrackSegment: resolveVttSegment } });
+
 // ============================================================================
 // Config-aware behavior wrappers
 //
@@ -108,22 +117,22 @@ const resolveTextTrack = (deps: Deps) => resolveTrack(deps, { type: 'text' as co
 // relevant config fields into the behavior's own config parameter.
 // ============================================================================
 
-const selectVideoTrackFromConfig = ({ config, ...deps }: Deps) =>
-  selectVideoTrack(deps, {
+const selectVideoTrack = ({ config, ...deps }: Deps) =>
+  _selectVideoTrack(deps, {
     type: 'video',
     ...(config.initialBandwidth !== undefined && { initialBandwidth: config.initialBandwidth }),
   });
 
-const selectAudioTrackFromConfig = ({ config, ...deps }: Deps) =>
-  selectAudioTrack(deps, {
+const selectAudioTrack = ({ config, ...deps }: Deps) =>
+  _selectAudioTrack(deps, {
     type: 'audio',
     ...(config.preferredAudioLanguage !== undefined && {
       preferredAudioLanguage: config.preferredAudioLanguage,
     }),
   });
 
-const selectTextTrackFromConfig = ({ config, ...deps }: Deps) =>
-  selectTextTrack(deps, {
+const selectTextTrack = ({ config, ...deps }: Deps) =>
+  _selectTextTrack(deps, {
     type: 'text',
     ...(config.preferredSubtitleLanguage !== undefined && {
       preferredSubtitleLanguage: config.preferredSubtitleLanguage,
@@ -132,8 +141,8 @@ const selectTextTrackFromConfig = ({ config, ...deps }: Deps) =>
     ...(config.enableDefaultTrack !== undefined && { enableDefaultTrack: config.enableDefaultTrack }),
   });
 
-const switchQualityFromConfig = ({ config, ...deps }: Deps) =>
-  switchQuality(deps, config.initialBandwidth !== undefined ? { defaultBandwidth: config.initialBandwidth } : {});
+const switchQuality = ({ config, ...deps }: Deps) =>
+  _switchQuality(deps, config.initialBandwidth !== undefined ? { defaultBandwidth: config.initialBandwidth } : {});
 
 // ============================================================================
 // HLS Playback Engine
@@ -148,7 +157,7 @@ const switchQualityFromConfig = ({ config, ...deps }: Deps) =>
  *
  * @example
  * ```ts
- * const engine = createHlsPlaybackEngine({
+ * const engine = createSimpleHlsEngine({
  *   initialBandwidth: 2_000_000,
  *   preferredAudioLanguage: 'en',
  * });
@@ -161,19 +170,19 @@ const switchQualityFromConfig = ({ config, ...deps }: Deps) =>
  * await engine.destroy();
  * ```
  */
-export function createHlsPlaybackEngine(
-  config: HlsPlaybackEngineConfig = {}
-): Composition<HlsPlaybackEngineState, HlsPlaybackEngineOwners> {
-  return createComposition(
+export function createSimpleHlsEngine(
+  config: SimpleHlsEngineConfig = {}
+): Composition<SimpleHlsEngineState, SimpleHlsEngineOwners> {
+  return createComposition<SimpleHlsEngineState, SimpleHlsEngineOwners, SimpleHlsEngineConfig>(
     [
       syncPreloadAttribute,
       trackPlaybackInitiated,
       resolvePresentation,
 
       // Track selection (reads config for initial preferences)
-      selectVideoTrackFromConfig,
-      selectAudioTrackFromConfig,
-      selectTextTrackFromConfig,
+      selectVideoTrack,
+      selectAudioTrack,
+      selectTextTrack,
 
       // Resolve selected tracks (fetch media playlists)
       resolveVideoTrack,
@@ -190,7 +199,7 @@ export function createHlsPlaybackEngine(
 
       // Playback tracking
       trackCurrentTime,
-      switchQualityFromConfig,
+      switchQuality,
 
       // Segment loading
       loadVideoSegments,
@@ -201,11 +210,8 @@ export function createHlsPlaybackEngine(
 
       // Text tracks
       syncTextTracks,
+      setupTextTrackActors,
       loadTextTrackCues,
-
-      // Module-level VTT parser cleanup
-      // TODO: this should be owned by loadTextTrackCues
-      () => destroyVttParser(),
     ],
     {
       config,
@@ -217,8 +223,8 @@ export function createHlsPlaybackEngine(
           slowTotalWeight: 0,
           bytesSampled: 0,
         },
-      } as HlsPlaybackEngineState,
-      initialOwners: {} as HlsPlaybackEngineOwners,
+      },
+      initialOwners: {},
     }
   );
 }
diff --git a/packages/spf/src/playback/engines/hls/index.ts b/packages/spf/src/playback/engines/hls/index.ts
new file mode 100644
index 00000000..bd344528
--- /dev/null
+++ b/packages/spf/src/playback/engines/hls/index.ts
@@ -0,0 +1,8 @@
+export type { SimpleHlsMediaAPI, SimpleHlsMediaProps } from './adapter';
+export { SimpleHlsMediaElement, SimpleHlsMediaMixin, simpleHlsMediaDefaultProps } from './adapter';
+export type {
+  SimpleHlsEngineConfig,
+  SimpleHlsEngineOwners,
+  SimpleHlsEngineState,
+} from './engine';
+export { createSimpleHlsEngine } from './engine';
diff --git a/packages/spf/src/dom/playback-engine/tests/adapter.test.ts b/packages/spf/src/playback/engines/hls/tests/adapter.test.ts
similarity index 87%
rename from packages/spf/src/dom/playback-engine/tests/adapter.test.ts
rename to packages/spf/src/playback/engines/hls/tests/adapter.test.ts
index 547858ea..6786e58c 100644
--- a/packages/spf/src/dom/playback-engine/tests/adapter.test.ts
+++ b/packages/spf/src/playback/engines/hls/tests/adapter.test.ts
@@ -1,5 +1,5 @@
 /**
- * SpfMedia adapter tests.
+ * SimpleHlsMediaElement adapter tests.
  *
  * Covers the HTMLMediaElement-compatible contract for src and play(), per the
  * WHATWG HTML spec (https://html.spec.whatwg.org/multipage/media.html).
@@ -15,9 +15,9 @@
  * Future: consider web-platform-tests (wpt) fixtures for deeper spec coverage.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { SpfMedia } from '../adapter';
+import { SimpleHlsMediaElement } from '../adapter';
 
-describe('SpfMedia', () => {
+describe('SimpleHlsMediaElement', () => {
   // Prevent real network calls from engines that auto-trigger resolution
   // (e.g. when a media element with default preload="auto" is attached alongside a src).
   // A never-settling promise avoids unhandled rejections without affecting test assertions.
@@ -37,26 +37,26 @@ describe('SpfMedia', () => {
   // ---------------------------------------------------------------------------
   describe('src', () => {
     it('returns empty string before any src is set', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       expect(media.src).toBe('');
     });
 
     it('reflects the set value synchronously', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       // Must be synchronous — no await needed
       expect(media.src).toBe('https://example.com/v.m3u8');
     });
 
     it('reflects the most recently set value', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v1.m3u8';
       media.src = 'https://example.com/v2.m3u8';
       expect(media.src).toBe('https://example.com/v2.m3u8');
     });
 
     it('reflects empty string when set to empty', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       media.src = '';
       expect(media.src).toBe('');
@@ -64,23 +64,23 @@ describe('SpfMedia', () => {
 
     // Setting src triggers the load algorithm — engine state update is synchronous
     it('synchronously updates engine presentation state when src is set', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       expect(media.engine.state.get().presentation?.url).toBe('https://example.com/v.m3u8');
     });
 
     it('synchronously updates engine presentation state when src changes', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v1.m3u8';
       media.src = 'https://example.com/v2.m3u8';
       expect(media.engine.state.get().presentation?.url).toBe('https://example.com/v2.m3u8');
     });
 
     it('clears engine presentation state when src is set to empty string', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       media.src = '';
-      expect(media.engine.state.get().presentation).toBeUndefined();
+      expect(media.engine.state.get().presentation?.url).toBeFalsy();
     });
   });
 
@@ -89,12 +89,12 @@ describe('SpfMedia', () => {
   // ---------------------------------------------------------------------------
   describe('attach / detach', () => {
     it('exposes the engine immediately (created at construction, not on attach)', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       expect(media.engine).not.toBeNull();
     });
 
     it('reuses the same engine instance across attach calls', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el1 = document.createElement('video');
       const el2 = document.createElement('video');
       media.attach(el1);
@@ -104,7 +104,7 @@ describe('SpfMedia', () => {
     });
 
     it('reuses the same engine instance across attach/detach cycles', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.attach(document.createElement('video'));
       const engine = media.engine;
       media.detach();
@@ -113,14 +113,14 @@ describe('SpfMedia', () => {
     });
 
     it('creates a new engine when src is set', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const initial = media.engine;
       media.src = 'https://example.com/v1.m3u8';
       expect(media.engine).not.toBe(initial);
     });
 
     it('destroys the old engine when src changes', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v1.m3u8';
       const spy = vi.spyOn(media.engine, 'destroy');
       media.src = 'https://example.com/v2.m3u8';
@@ -128,7 +128,7 @@ describe('SpfMedia', () => {
     });
 
     it('re-attaches the media element to the new engine when src changes', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.src = 'https://example.com/v1.m3u8';
@@ -136,7 +136,7 @@ describe('SpfMedia', () => {
     });
 
     it('cancels pending play listener when src changes', async () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.src = 'https://example.com/v1.m3u8';
@@ -150,21 +150,21 @@ describe('SpfMedia', () => {
     });
 
     it('sets mediaElement in owners when attached', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       expect(media.engine.owners.get().mediaElement).toBe(el);
     });
 
     it('clears mediaElement in owners when detached', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.attach(document.createElement('video'));
       media.detach();
       expect(media.engine.owners.get().mediaElement).toBeUndefined();
     });
 
     it('updates mediaElement when re-attached to a different element', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el1 = document.createElement('video');
       const el2 = document.createElement('video');
       media.attach(el1);
@@ -173,7 +173,7 @@ describe('SpfMedia', () => {
     });
 
     it('preserves src across attach/detach cycles', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       media.attach(document.createElement('video'));
       media.detach();
@@ -181,14 +181,14 @@ describe('SpfMedia', () => {
     });
 
     it('src set before attach is reflected in engine state', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.src = 'https://example.com/v.m3u8';
       media.attach(document.createElement('video'));
       expect(media.engine.state.get().presentation?.url).toBe('https://example.com/v.m3u8');
     });
 
     it('detach does not destroy the engine', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.attach(document.createElement('video'));
       const spy = vi.spyOn(media.engine, 'destroy');
       media.detach();
@@ -201,7 +201,7 @@ describe('SpfMedia', () => {
   // ---------------------------------------------------------------------------
   describe('play()', () => {
     it('returns a Promise', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.attach(document.createElement('video'));
       const result = media.play();
       expect(result).toBeInstanceOf(Promise);
@@ -210,14 +210,14 @@ describe('SpfMedia', () => {
     });
 
     it('sets playbackInitiated on engine state when called', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.attach(document.createElement('video'));
       media.play().catch(() => {});
       expect(media.engine.state.get().playbackInitiated).toBe(true);
     });
 
     it('retries play() via loadstart when element has no src but adapter has one', async () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.src = 'https://example.com/v.m3u8';
@@ -248,7 +248,7 @@ describe('SpfMedia', () => {
     });
 
     it('re-throws when play() rejects and no adapter src is set', async () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       // No src on adapter — nothing pending to wait for
@@ -260,7 +260,7 @@ describe('SpfMedia', () => {
     });
 
     it('removes the pending loadstart listener on detach', async () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.src = 'https://example.com/v.m3u8';
@@ -277,7 +277,7 @@ describe('SpfMedia', () => {
     });
 
     it('removes the pending loadstart listener on destroy', async () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.src = 'https://example.com/v.m3u8';
@@ -303,24 +303,24 @@ describe('SpfMedia', () => {
   // ---------------------------------------------------------------------------
   describe('preload', () => {
     it('returns empty string before any preload is set', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       expect(media.preload).toBe('');
     });
 
     it('reflects the set value synchronously', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.preload = 'auto';
       expect(media.preload).toBe('auto');
     });
 
     it('updates engine state immediately when set', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.preload = 'none';
       expect(media.engine.state.get().preload).toBe('none');
     });
 
     it('setting preload to empty string resets the stored value but does not clear current engine state', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.preload = 'auto';
       media.preload = '';
       // '' only clears #preload so the next engine recreation won't re-apply
@@ -329,7 +329,7 @@ describe('SpfMedia', () => {
     });
 
     it('survives src reassignment — explicit preload is preserved across engine recreation', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       media.preload = 'none';
       media.src = 'https://example.com/v.m3u8';
       expect(media.preload).toBe('none');
@@ -337,7 +337,7 @@ describe('SpfMedia', () => {
     });
 
     it('explicit preload is re-applied before owners.patch on src change so syncPreloadAttribute skips inference', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const el = document.createElement('video');
       media.attach(el);
       media.preload = 'none';
@@ -353,7 +353,7 @@ describe('SpfMedia', () => {
   // ---------------------------------------------------------------------------
   describe('destroy()', () => {
     it('destroys the underlying engine', () => {
-      const media = new SpfMedia();
+      const media = new SimpleHlsMediaElement();
       const spy = vi.spyOn(media.engine, 'destroy');
       media.destroy();
       expect(spy).toHaveBeenCalledOnce();
diff --git a/packages/spf/src/dom/tests/playback-engine.test.ts b/packages/spf/src/playback/engines/hls/tests/engine.test.ts
similarity index 97%
rename from packages/spf/src/dom/tests/playback-engine.test.ts
rename to packages/spf/src/playback/engines/hls/tests/engine.test.ts
index d7531b58..e08126a9 100644
--- a/packages/spf/src/dom/tests/playback-engine.test.ts
+++ b/packages/spf/src/playback/engines/hls/tests/engine.test.ts
@@ -1,12 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createHlsPlaybackEngine } from '../playback-engine/hls-engine';
+import { createSimpleHlsEngine } from '../engine';
 
 // Mock appendSegment to succeed without real MP4 data
-vi.mock('../media/append-segment', () => ({
+vi.mock('../../../../media/dom/mse/append-segment', () => ({
   appendSegment: vi.fn().mockResolvedValue(undefined),
 }));
 
-describe('createHlsPlaybackEngine', () => {
+describe('createSimpleHlsEngine', () => {
   let originalFetch: typeof globalThis.fetch;
 
   beforeEach(() => {
@@ -19,7 +19,7 @@ describe('createHlsPlaybackEngine', () => {
     globalThis.fetch = originalFetch;
   });
   it('creates engine with state, owners, and destroy', () => {
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     expect(engine.state).toBeDefined();
     expect(engine.owners).toBeDefined();
@@ -30,7 +30,7 @@ describe('createHlsPlaybackEngine', () => {
   });
 
   it('initializes with empty state and owners', () => {
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     expect(engine.state.get()).toEqual({
       bandwidthState: {
@@ -47,7 +47,7 @@ describe('createHlsPlaybackEngine', () => {
   });
 
   it('allows patching state and owners from outside', async () => {
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
@@ -68,7 +68,7 @@ describe('createHlsPlaybackEngine', () => {
   });
 
   it('accepts custom configuration', () => {
-    const engine = createHlsPlaybackEngine({
+    const engine = createSimpleHlsEngine({
       initialBandwidth: 3_000_000,
       preferredAudioLanguage: 'es',
     });
@@ -80,14 +80,14 @@ describe('createHlsPlaybackEngine', () => {
   });
 
   it('cleans up all orchestrations on destroy', () => {
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     // Should not throw
     expect(() => engine.destroy()).not.toThrow();
   });
 
   it('can be destroyed multiple times safely', () => {
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     engine.destroy();
 
@@ -128,7 +128,7 @@ http://example.com/segment1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     // Patch state to trigger presentation resolution
     engine.state.set({
@@ -199,7 +199,7 @@ http://example.com/audio-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -294,7 +294,7 @@ http://example.com/video-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -359,7 +359,7 @@ http://example.com/audio-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -424,7 +424,7 @@ http://example.com/video-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -482,7 +482,7 @@ http://example.com/video-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
 
     // Patch state but NOT owners (no mediaElement)
     engine.state.set({
@@ -562,7 +562,7 @@ http://example.com/audio-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'none';
 
@@ -643,7 +643,7 @@ http://example.com/seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'metadata';
 
@@ -721,7 +721,7 @@ http://example.com/seg1.m4s
 
     // Use a conservative initialBandwidth so switchQuality also selects 360p and
     // doesn't immediately upgrade — verifying only the selected track is resolved.
-    const engine = createHlsPlaybackEngine({ initialBandwidth: 600_000 });
+    const engine = createSimpleHlsEngine({ initialBandwidth: 600_000 });
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -822,7 +822,7 @@ http://example.com/text-es-seg1.vtt
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -920,7 +920,7 @@ http://example.com/text-es-seg1.vtt
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine({
+    const engine = createSimpleHlsEngine({
       enableDefaultTrack: true,
     });
     const mediaElement = document.createElement('video');
@@ -999,7 +999,7 @@ http://example.com/text-fr-seg1.vtt
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine({
+    const engine = createSimpleHlsEngine({
       preferredSubtitleLanguage: 'fr',
     });
     const mediaElement = document.createElement('video');
@@ -1087,7 +1087,7 @@ http://example.com/text-es-seg1.vtt
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -1188,7 +1188,7 @@ http://example.com/video-seg1.m4s
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -1285,7 +1285,7 @@ http://example.com/text-es-seg1.vtt
     });
     globalThis.fetch = mockFetch;
 
-    const engine = createHlsPlaybackEngine();
+    const engine = createSimpleHlsEngine();
     const mediaElement = document.createElement('video');
     mediaElement.preload = 'auto';
 
@@ -1394,7 +1394,7 @@ http://example.com/seg2.m4s
   });
   globalThis.fetch = mockFetch;
 
-  const engine = createHlsPlaybackEngine();
+  const engine = createSimpleHlsEngine();
   const mediaElement = document.createElement('video');
   mediaElement.preload = 'auto';
 
@@ -1472,7 +1472,7 @@ http://example.com/audio-seg1.m4s
   });
   globalThis.fetch = mockFetch;
 
-  const engine = createHlsPlaybackEngine();
+  const engine = createSimpleHlsEngine();
   const mediaElement = document.createElement('video');
   mediaElement.preload = 'auto';
 
diff --git a/packages/spf/src/playback/engines/hls/tsconfig.json b/packages/spf/src/playback/engines/hls/tsconfig.json
new file mode 100644
index 00000000..acb1ab38
--- /dev/null
+++ b/packages/spf/src/playback/engines/hls/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "extends": "../../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "exactOptionalPropertyTypes": false,
+    "declarationDir": "../../../../types/playback/engines/hls"
+  },
+  "references": [
+    { "path": "../../../../../utils" },
+    { "path": "../../../core" },
+    { "path": "../../../network" },
+    { "path": "../../../media" },
+    { "path": "../../../media/dom" },
+    { "path": "../../behaviors" },
+    { "path": "../../behaviors/dom" },
+    { "path": "../../actors" },
+    { "path": "../../actors/dom" }
+  ],
+  "include": ["./**/*.ts"]
+}
diff --git a/packages/spf/tsdown.config.ts b/packages/spf/tsdown.config.ts
index d116707d..e32a0b1b 100644
--- a/packages/spf/tsdown.config.ts
+++ b/packages/spf/tsdown.config.ts
@@ -8,8 +8,8 @@ const buildModes: BuildMode[] = ['dev', 'default'];
 const createConfig = (mode: BuildMode): UserConfig => ({
   entry: {
     index: 'src/index.ts',
-    dom: 'src/dom/index.ts',
-    'dom/playback-engine': 'src/dom/playback-engine/index.ts',
+    dom: 'src/dom.ts',
+    hls: 'src/playback/engines/hls/index.ts',
   },
   platform: 'neutral',
   format: 'es',
diff --git a/packages/spf/vitest.config.ts b/packages/spf/vitest.config.ts
index e7f5130b..b9f8b2b6 100644
--- a/packages/spf/vitest.config.ts
+++ b/packages/spf/vitest.config.ts
@@ -28,13 +28,49 @@ export default defineConfig({
         test: {
           name: 'media',
           include: ['src/media/**/*.test.ts'],
+          exclude: ['src/media/dom/**'],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: 'network',
+          include: ['src/network/**/*.test.ts'],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: 'behaviors',
+          include: ['src/playback/behaviors/**/*.test.ts', 'src/playback/actors/**/*.test.ts'],
+          exclude: ['src/playback/behaviors/dom/**', 'src/playback/actors/dom/**'],
         },
       },
       {
         extends: true,
         test: {
           name: 'dom',
-          include: ['src/dom/**/*.test.ts'],
+          // All DOM-bound tests across the package — MSE/VTT primitives,
+          // DOM-bound behaviors, DOM-bound actor factories.
+          include: [
+            'src/media/dom/**/*.test.ts',
+            'src/playback/behaviors/dom/**/*.test.ts',
+            'src/playback/actors/dom/**/*.test.ts',
+          ],
+          browser: {
+            enabled: true,
+            headless: true,
+            provider: playwright(),
+            screenshotFailures: false,
+            instances: [{ browser: 'chromium' }],
+          },
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: 'playback-engines',
+          include: ['src/playback/engines/**/*.test.ts'],
           browser: {
             enabled: true,
             headless: true,
diff --git a/packages/utils/src/string/generate-id.ts b/packages/utils/src/string/generate-id.ts
new file mode 100644
index 00000000..7981cffd
--- /dev/null
+++ b/packages/utils/src/string/generate-id.ts
@@ -0,0 +1,11 @@
+/**
+ * Generate a unique-ish string ID via timestamp + random.
+ *
+ * @returns String in `timestamp-random` format (e.g. `"1738423156789-542891"`).
+ *
+ * @example
+ * const id = generateId(); // "1738423156789-542891"
+ */
+export function generateId(): string {
+  return `${Date.now()}-${Math.floor(Math.random() * 1000000)}`;
+}
diff --git a/packages/utils/src/string/index.ts b/packages/utils/src/string/index.ts
index bba4fbbf..fcff136b 100644
--- a/packages/utils/src/string/index.ts
+++ b/packages/utils/src/string/index.ts
@@ -1 +1,2 @@
 export * from './casing';
+export * from './generate-id';
diff --git a/packages/spf/src/core/utils/tests/generate-id.test.ts b/packages/utils/src/string/tests/generate-id.test.ts
similarity index 100%
rename from packages/spf/src/core/utils/tests/generate-id.test.ts
rename to packages/utils/src/string/tests/generate-id.test.ts
diff --git a/tsconfig.json b/tsconfig.json
index 12b1c017..e860ba15 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -19,7 +19,15 @@
     { "path": "packages/skins" },
 
     { "path": "packages/spf" },
-    { "path": "packages/spf/src/dom" },
+    { "path": "packages/spf/src/core" },
+    { "path": "packages/spf/src/network" },
+    { "path": "packages/spf/src/media" },
+    { "path": "packages/spf/src/media/dom" },
+    { "path": "packages/spf/src/playback/behaviors" },
+    { "path": "packages/spf/src/playback/behaviors/dom" },
+    { "path": "packages/spf/src/playback/actors" },
+    { "path": "packages/spf/src/playback/actors/dom" },
+    { "path": "packages/spf/src/playback/engines/hls" },
 
     { "path": "packages/html" },
     { "path": "packages/react" },