From 462972e736b49ca368e67e541b68c80289ab87ef Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Thu, 30 Oct 2025 02:55:32 +0000
Subject: [PATCH] chore(root): update architecture docs

---
 README.md                                |    2 +-
 docs/ARCHITECTURE.md                     | 1290 +---------------------
 docs/PLAYBACK_ENGINE_FRAMEWORK_VISION.md |  981 ----------------
 3 files changed, 45 insertions(+), 2228 deletions(-)
 delete mode 100644 docs/PLAYBACK_ENGINE_FRAMEWORK_VISION.md

diff --git a/README.md b/README.md
index f32e6525..576f4897 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,9 @@ Modern, modular, and composable media player framework for Web and React.
 Thanks for checking out the project! It's in its early stages and currently a mix of protoyping
 and early structure pointing in the direction we want to go with Video.js v10 (so be kind 🙏).
 
+- Read our early [architecture goals](./docs/architecture.md).
 - Read the [v10 discussion topic](https://github.com/videojs/video.js/discussions/9035)
 - Watch [Heff's recent presentation](https://players.brightcove.net/3737230800001/eyILA5XG7K_default/index.html?videoId=6379311036112)
-- More roadmap and architecture docs to come...
 
 ## Documentation
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d75a2a82..e3ff3d48 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,1260 +1,58 @@
-# VJS-10 Architecture & Design Philosophy
+# Video.js 10 Architecture
 
-## How to Read This Document
+**Status:** Technical Preview (initial working showcase for Demuxed)
 
-This document describes VJS-10's **architectural principles and patterns**, not implementation chronology.
+- Current codebase is an early push by the team to have a working showcase for Demuxed.
+- Architecture and patterns will evolve as we refine and plan the long‑term structure.
 
-**Status Indicators:**
+## Early Goals
 
-- ✅ **Implemented** - Currently exists in codebase with code references
-- 🚧 **In Progress** - Partially implemented, under active development
-- 📋 **Planned** - Architectural vision, not yet started
+- Establish a common, TanStack‑based core for consistent state management across supported platforms and frameworks.
+- Ensure composition and compound patterns are first‑class.
+- Adopt TypeScript throughout for safety and DX.
+- Design for modularity, tree‑shaking, and performance.
+- Fully support SSR / hydration.
+- Create a compiler to handle transformation and output across multiple JS and CSS frameworks.
 
-**Code References:**
+## Core Principles
 
-- File paths link to actual implementation locations
-- Examples show real patterns from working code
-- Sections without status indicators describe foundational principles
+- **Common Core:** TanStack state-driven architecture; DOM lives in a separate package; maps to web, React, and React Native.
+- **Composition-first:** Compound component and functional patterns. E.g., React has `render(attrs, state)` prop to allow full control of element type or animations.
+- **TypeScript everywhere.**
+- **Modular & tree-shakeable.**
+- **Performance-focused:** Minimal bundle size and payload, smooth 60+ FPS target.
+- **SSR + hydration safe/optimized.**
 
----
+## Accessibility
 
-## Overview
+- Non-negotiable.
+- Core owns ARIA roles, labels, navigation, and focus.
+- Captions, keyboard navigation/shortcuts, and focus management.
+- Meets WCAG 2.2 / CVAA standards out‑of‑box.
 
-VJS-10 is a media player component library that prioritizes platform-native development experiences while maintaining shared core logic. This document outlines the design philosophy, architectural influences, and key decisions that shape the VJS-10 ecosystem.
+## State & Reactivity
 
-## Architectural Influences & Inspirations
+- State hooks and components support **controlled/uncontrolled** mode (`value` / `onChange`).
+- State-driven architecture powers Web, React, and React‑Native.
+- Maintain 16 ms frame budget.
+- Offload heavy style computations to CSS.
+- Minimal playback engine per user case.
+- Stream + lazy caption parsing for large files.
+- SSR: preload rendition segments in document head, ship parsed manifest, minimal composed-playback engine for faster TTF (time‑to‑first‑frame).
 
-### Media Elements: Platform-Agnostic HTMLMediaElement Contract
+## Styling
 
-VJS-10's media state management architecture uses patterns from the [media-elements monorepo](https://github.com/muxinc/media-elements) for creating HTMLMediaElement-compatible elements that work across different media providers while maintaining consistent interfaces.
+- **Style‑agnostic core:** No CSS shipped in Core or Primitives.
+- **Style‑ready hooks:** Stable `data-*` attrs and CSS vars for easy theming.
+- Default skins in separate exports (optional entry points).
+- Primitives avoid Shadow DOM; themed skins may opt in.
+- DOM trees stay one level deep per component part (Root, Thumb, Track, etc.).
+- No internal JS animations.
+- Components toggle data attributes (`data-open`, `data-starting-style`, etc.) for CSS or Motion libraries to hook into.
 
-#### 1. Extended HTMLMediaElement Contract Foundation
+## Cross‑Browser Compatibility
 
-**Media Elements Pattern**: The media-elements monorepo established the pattern of creating custom elements that "look like" HTMLMediaElement but can be extended for different media providers (HLS, DASH, YouTube, Vimeo, etc.).
-
-**Core Architecture Pattern**:
-
-```typescript
-// Media Elements: CustomVideoElement extends HTMLElement, wraps native video
-// (Safari doesn't support extending built-in elements like HTMLVideoElement)
-export class CustomVideoElement extends HTMLElement {
-  readonly nativeEl: HTMLVideoElement; // Wrapped native element in shadow DOM
-
-  // Proxies HTMLMediaElement properties to wrapped native element
-  get currentTime() { return this.nativeEl?.currentTime ?? 0; }
-  set currentTime(val) { if (this.nativeEl) this.nativeEl.currentTime = val; }
-
-  play(): Promise<void> { return this.nativeEl?.play() ?? Promise.resolve(); }
-  pause(): void { this.nativeEl?.pause(); }
-}
-
-// Provider-specific implementations
-class HlsVideoElement extends CustomVideoElement {
-  api: Hls | null = null;
-
-  async load() {
-    if (Hls.isSupported()) {
-      this.api = new Hls(this.config);
-      this.api.loadSource(this.src);
-      this.api.attachMedia(this.nativeEl); // Native video wrapped in shadow DOM
-    }
-  }
-}
-```
-
-**Key Architectural Assumptions**:
-
-- Must extend `HTMLElement` (Safari limitation prevents extending built-in elements)
-- Wraps native `<video>` or `<audio>` element in shadow DOM
-- Proxies HTMLMediaElement properties/methods to wrapped native element
-- Provider-specific logic encapsulated in custom element classes
-- Shadow DOM for consistent styling and behavior
-
-**Reference**: [`packages/custom-media-element/custom-media-element.ts`](https://github.com/muxinc/media-elements/blob/main/packages/custom-media-element/custom-media-element.ts)
-
-#### 2. VJS-10's Platform-Agnostic Evolution
-
-**VJS-10 Approach**: Relaxed the HTMLElement requirement while maintaining the HTMLMediaElement contract, enabling true cross-platform compatibility.
-
-**Architectural Relaxation**:
-
-```typescript
-// VJS-10: MediaStateOwner - JavaScript interface only
-export type MediaStateOwner = Partial<HTMLVideoElement>
-  & Pick<HTMLMediaElement, 'play' | 'paused' | 'addEventListener' | 'removeEventListener'>
-  & EventTarget & { // Only requires EventTarget, not HTMLElement
-    // HTMLMediaElement contract maintained
-    currentTime?: number;
-    duration?: number;
-    volume?: number;
-    muted?: boolean;
-    paused?: boolean;
-
-    // Extended media-specific properties (Media Elements influence)
-    streamType?: StreamTypes;
-    targetLiveWindow?: number;
-    videoRenditions?: Rendition[] & EventTarget;
-    audioTracks?: AudioTrack[] & EventTarget;
-
-    // Platform-specific extensions
-    webkitDisplayingFullscreen?: boolean;
-    webkitCurrentPlaybackTargetIsWireless?: boolean;
-  };
-```
-
-**Cross-Platform Implementation**:
-
-**HTML Platform** (Media Elements Heritage):
-
-```typescript
-// Direct evolution from media-elements CustomVideoElement
-export class MediaVideoElement extends HTMLVideoElement implements MediaStateOwner {
-  connectedCallback() {
-    // Media Elements pattern: delegate to native element
-    this.mediaStore = createMediaStore(this.nativeEl);
-  }
-}
-```
-
-**React Platform** (Platform-Agnostic Contract):
-
-```typescript
-// Uses HTMLVideoElement but not as DOM element
-export function useVideoElement(): MediaStateOwner {
-  const videoRef = useRef<HTMLVideoElement>(null);
-
-  return useMemo(() => ({
-    // Maintains HTMLMediaElement contract without DOM assumptions
-    get currentTime() { return videoRef.current?.currentTime ?? 0; },
-    set currentTime(val) { if (videoRef.current) videoRef.current.currentTime = val; },
-
-    play: () => videoRef.current?.play() ?? Promise.resolve(),
-    pause: () => videoRef.current?.pause(),
-
-    addEventListener: (type, listener) => videoRef.current?.addEventListener(type, listener),
-    removeEventListener: (type, listener) => videoRef.current?.removeEventListener(type, listener),
-  }), []);
-}
-```
-
-**React Native Platform** (Contract Without HTMLMediaElement):
-
-```typescript
-// Implements MediaStateOwner contract with React Native Video
-export function useVideoElementNative(): MediaStateOwner {
-  const videoRef = useRef<Video>(null);
-
-  return useMemo(() => ({
-    // Same interface, different implementation
-    get currentTime() { return this.currentTime ?? 0; },
-    set currentTime(val) { videoRef.current?.seek(val); },
-
-    play: () => {
-      videoRef.current?.resume();
-      return Promise.resolve();
-    },
-    pause: () => videoRef.current?.pause(),
-
-    // EventTarget implementation for React Native
-    addEventListener: (type, listener) => this.eventEmitter.on(type, listener),
-    removeEventListener: (type, listener) => this.eventEmitter.off(type, listener),
-  }), []);
-};
-```
-
-#### 3. Well-Defined Playback Engine Contract
-
-**Media Elements Pattern**: Beyond creating HTMLMediaElement-compatible custom elements, media-elements established patterns for wrapping diverse playback engines (hls.js, dash.js, Shaka Player) behind a consistent interface. While each integration is currently a "one-off" implementation, the pattern demonstrates the value of a well-defined contract between media elements and the playback engines they wrap.
-
-**Current Media Elements Pattern** (one-off integrations):
-
-```typescript
-// HlsVideoElement wraps hls.js
-class HlsVideoElement extends CustomVideoElement {
-  api: Hls | null = null;
-
-  async load() {
-    this.api = new Hls(this.config);
-    this.api.loadSource(this.src);
-    this.api.attachMedia(this.nativeEl);
-  }
-}
-
-// DashVideoElement wraps dash.js (different API)
-class DashVideoElement extends CustomVideoElement {
-  player: dashjs.MediaPlayer | null = null;
-
-  async load() {
-    this.player = dashjs.MediaPlayer().create();
-    this.player.initialize(this.nativeEl, this.src, this.autoplay);
-  }
-}
-```
-
-**Key Observation**: Each playback engine has a unique API surface (hls.js's `loadSource/attachMedia`, dash.js's `initialize`, Shaka's `attach/load`), requiring custom integration code for each provider.
-
-**VJS-10 Vision**: Building on this pattern, VJS-10 aims to define a **standardized playback engine contract** that enables:
-
-1. **Unified Public-Facing API**: All playback engines expose the same interface regardless of internal implementation
-2. **Pluggable Providers**: Swap between HLS.js, Dash.js, Shaka, or native playback without changing consumer code
-3. **Composable Internals**: Playback engines composed from functional units rather than monolithic classes
-
-This vision is detailed in [`docs/PLAYBACK_ENGINE_VISION.md`](docs/PLAYBACK_ENGINE_VISION.md) and represents a evolution from media-elements' "one-off integration per provider" pattern to a formalized, extensible playback engine contract.
-
-**Contract Philosophy**:
-
-- **Outward-facing**: Consistent HTMLMediaElement-like API for all providers
-- **Inward-facing**: Composable functional units for internal implementation
-- **Provider-agnostic**: Consumer code doesn't need to know about hls.js vs dash.js vs Shaka
-
-**Reference**: See playback engine vision document for full architectural details.
-
-#### 4. Interface Abstraction vs. Implementation Requirements
-
-**Media Elements Approach**: Tight coupling between contract and DOM implementation
-
-- Must extend `HTMLElement` (Safari limitation prevents extending built-in elements)
-- Wraps native `<video>` or `<audio>` in shadow DOM
-- Requires Shadow DOM and custom element registration
-- Web Components as the primary abstraction layer
-
-**VJS-10 Evolution**: Contract-based abstraction with implementation flexibility
-
-- Interface defines behavior, implementation varies by platform
-- JavaScript properties and methods only (no DOM methods like `getAttribute()`)
-- EventTarget requirement for event-driven architecture
-
-**Contract Comparison**:
-
-| Aspect                        | Media Elements                          | VJS-10 Evolution          |
-| ----------------------------- | --------------------------------------- | ------------------------- |
-| **Base Class**                | `HTMLElement` with wrapped native video | `EventTarget` + interface |
-| **DOM Requirements**          | Shadow DOM, custom elements             | None (platform-dependent) |
-| **Platform Support**          | Web Components only                     | HTML, React, React Native |
-| **HTMLMediaElement Contract** | Proxied to wrapped native element       | JavaScript interface only |
-| **Extension Method**          | Class inheritance from `HTMLElement`    | Interface implementation  |
-
-#### 5. MediaStateOwner Contract and State Management
-
-This section covers two related concepts:
-
-1. **MediaStateOwner** - The interface custom elements implement (HTMLMediaElement-like contract)
-2. **State management layer** - How UI components interact with the MediaStateOwner
-
-The MediaStateOwner provides a consistent interface whether you're using:
-
-- A custom element wrapping hls.js (Media Elements pattern)
-- A React ref to HTMLVideoElement (VJS-10 React)
-- A React Native Video component wrapper (VJS-10 React Native)
-
-**Media Elements Pattern**: Custom elements implement HTMLMediaElement-like interface
-
-```typescript
-// Media Elements: Custom element implements the MediaStateOwner contract
-class HlsVideoElement extends CustomVideoElement {
-  // Implements HTMLMediaElement-like interface by proxying to nativeEl
-  // get/set currentTime, play(), pause(), etc. → this.nativeEl
-
-  load() {
-    // Provider logic (hls.js) mediates between source and native element
-    this.api = new Hls();
-    this.api.attachMedia(this.nativeEl); // Wraps native <video> in shadow DOM
-  }
-}
-```
-
-Key characteristics:
-
-- Custom element extends `HTMLElement`
-- Wraps native `<video>` in shadow DOM
-- Proxies HTMLMediaElement properties to wrapped element
-- Provider logic (hls.js, dash.js) manages source/playback
-
-**VJS-10 Pattern**: MediaStateOwner as platform-agnostic interface
-
-The MediaStateOwner interface abstracts away DOM requirements, enabling the state
-management layer to work with any object implementing the contract:
-
-```typescript
-// VJS-10: State mediator reads/writes MediaStateOwner interface
-export const temporal = {
-  currentTime: {
-    get(stateOwners: { media: MediaStateOwner }) {
-      // Reads from MediaStateOwner (could be custom element, React ref, RN wrapper)
-      return stateOwners.media?.currentTime ?? 0; // No DOM assumptions
-    },
-    set(value: number, stateOwners: { media: MediaStateOwner }) {
-      // Writes to MediaStateOwner through the interface
-      if (stateOwners.media) {
-        stateOwners.media.currentTime = value; // JavaScript interface only
-      }
-    },
-    mediaEvents: ['timeupdate', 'loadedmetadata'], // Events from MediaStateOwner
-  },
-};
-```
-
-Key characteristics:
-
-- State mediators interact with `MediaStateOwner` interface, not DOM directly
-- Same state management logic works across HTML, React, React Native
-- MediaStateOwner can be implemented differently per platform
-- Platform-agnostic state layer enabled by consistent contract
-
-#### 6. Event-Driven Architecture Continuity
-
-**Shared Foundation**: Both systems rely on EventTarget for reactive updates:
-
-**Media Elements Implementation**:
-
-```typescript
-// DOM event forwarding
-class MediaElement {
-  // ...
-  handleEvent(event: Event): void {
-    if (event.target === this.nativeEl) {
-      this.dispatchEvent(new CustomEvent(event.type, { detail: event.detail }));
-    }
-  }
-}
-```
-
-**VJS-10 Implementation**:
-
-```typescript
-// Platform-agnostic event handling
-const mediaStateOwner: MediaStateOwner = {
-  addEventListener(type: string, listener: EventListener) {
-    // Could be DOM element, React ref, or React Native component
-    this.targetElement?.addEventListener?.(type, listener)
-    || this.eventEmitter?.on?.(type, listener);
-  }
-};
-```
-
-#### Media Elements → VJS-10 Evolution Summary
-
-| Architecture Layer       | Media Elements Foundation    | VJS-10 Platform-Agnostic Evolution         |
-| ------------------------ | ---------------------------- | ------------------------------------------ |
-| **Contract Definition**  | HTMLVideoElement inheritance | MediaStateOwner interface                  |
-| **DOM Requirements**     | HTMLElement + Shadow DOM     | EventTarget only                           |
-| **Platform Support**     | Web Components only          | Multi-platform (HTML, React, React Native) |
-| **State Mediation**      | Element-based providers      | Interface-based state mediators            |
-| **Event Architecture**   | DOM event forwarding         | Platform-agnostic EventTarget              |
-| **Provider Integration** | Custom element classes       | State mediator functions                   |
-
-**Key Difference**: VJS-10 maintains the proven HTMLMediaElement contract from media-elements while removing platform-specific constraints, enabling the same state management patterns to work across web components, React components, and React Native.
-
-**References**:
-
-- [Media Elements Monorepo](https://github.com/muxinc/media-elements)
-- [Custom Media Element](https://github.com/muxinc/media-elements/tree/main/packages/custom-media-element)
-- [HLS Video Element](https://github.com/muxinc/media-elements/tree/main/packages/hls-video-element)
-
-### Media Chrome: Foundational State Management & Media Architecture
-
-VJS-10's core architectural principles use patterns from [Media Chrome](https://github.com/muxinc/media-chrome)'s approach to media player component architecture. Media Chrome established several foundational patterns that VJS-10 has evolved and adapted.
-
-#### 1. Extended HTMLMediaElement Contract
-
-**Media Chrome Pattern**: Built around an "extended HTMLMediaElement" contract that goes beyond standard web APIs to support modern media features like live streaming, quality selection, and advanced playback states.
-
-**VJS-10 Evolution**: Building on the MediaStateOwner contract from Media Elements (see [§Media Elements](#media-elements-platform-agnostic-htmlmediaelement-contract)), Media Chrome extended it with media-specific properties:
-
-```typescript
-// Media Chrome-inspired extensions to MediaStateOwner
-export type MediaStateOwner = Partial<HTMLVideoElement>
-  & Pick<HTMLMediaElement, 'play' | 'paused' | 'addEventListener' | 'removeEventListener'>
-  & EventTarget & {
-    // Media Chrome-inspired extensions
-    streamType?: StreamTypes; // Live vs. on-demand detection
-    targetLiveWindow?: number; // Live DVR window management
-    videoRenditions?: Rendition[] & EventTarget; // Quality selection
-    audioTracks?: AudioTrack[] & EventTarget; // Audio track switching
-    // ... additional media-specific properties
-  };
-```
-
-These extensions enable state mediators to handle modern media features while maintaining the platform-agnostic contract. The MediaStateOwner serves as the interface that state mediators read from and write to, abstracting away whether the underlying implementation is an HTMLMediaElement, React Native Video component, or other platform-specific element.
-
-**Reference**: [`packages/core/media-store/src/state-mediators/audible.ts`](packages/core/media-store/src/state-mediators/audible.ts)
-
-#### 2. State Mediator Pattern
-
-**Media Chrome Foundation**: Originated the **state mediator** concept as a pattern for managing media state transformations and side effects. Media Chrome's state mediators establish a crucial architectural layer that sits between the media store and the media element, working together with the MediaStateOwner contract.
-
-**Architectural Layers**:
-
-```
-┌─────────────────┐
-│  UI Components  │
-└────────┬────────┘
-         │
-    ┌────▼──────────┐
-    │  Media Store  │ ← Reactive state (nanostores, signals)
-    └────┬──────────┘
-         │
-    ┌────▼──────────────┐
-    │ State Mediators   │ ← Media Chrome pattern: transform, validate, side effects
-    │ (audible,         │
-    │  temporal, etc.)  │
-    └────┬──────────────┘
-         │
-    ┌────▼──────────────┐
-    │ MediaStateOwner   │ ← Media Elements contract: HTMLMediaElement-like interface
-    │ (custom element,  │
-    │  video ref, etc.) │
-    └───────────────────┘
-```
-
-**Media Chrome's State Mediator Pattern**:
-
-- Centralized MediaStore with state mediator objects
-- Each mediator handles a specific aspect of media state (volume, time, playback)
-- Mediators encapsulate get/set logic, event subscriptions, and side effects
-- Complete separation of state management from UI components
-
-**VJS-10 Evolution**: Modular state mediators work with the MediaStateOwner interface:
-
-```typescript
-// State mediator interacts with MediaStateOwner, not DOM directly
-export const audible = {
-  muted: {
-    get(stateOwners: { media: MediaStateOwner }) {
-      return stateOwners.media?.muted ?? false; // Read from MediaStateOwner
-    },
-    set(value: boolean, stateOwners: { media: MediaStateOwner }) {
-      if (!stateOwners.media) return;
-      stateOwners.media.muted = value; // Write to MediaStateOwner
-
-      // Side effect: smart volume restoration
-      if (!value && !stateOwners.media.volume) {
-        stateOwners.media.volume = 0.25;
-      }
-    },
-    mediaEvents: ['volumechange'], // Subscribe to MediaStateOwner events
-    actions: {
-      muterequest: () => true,
-      unmuterequest: () => false,
-    },
-  },
-};
-```
-
-**State Mediator Responsibilities**:
-
-- **Get/Set logic**: Read from and write to MediaStateOwner
-- **Event subscriptions**: Listen to MediaStateOwner events (timeupdate, volumechange, etc.)
-- **Side effects**: Smart defaults (e.g., unmute sets volume to 0.25)
-- **Validation**: Ensure state changes are valid
-
-**Why This Separation Matters**:
-
-The state mediator layer provides clean abstraction between:
-
-- Reactive state management (store layer)
-- Platform-specific media elements (MediaStateOwner contract)
-
-This enables the same state management logic to work across HTML custom elements, React refs, and React Native components.
-
-**VJS-10 Improvements**:
-
-- **Modular/Composable**: State mediators are independent modules (audible, temporal, playable)
-- **Framework-Agnostic**: Core mediator logic works across platforms (HTML, React, React Native)
-- **Cleaner API**: Simplified mediator structure with clear get/set/events/actions pattern
-- **Type-Safe**: Full TypeScript support with inference
-
-**Key Architectural Inheritances from Media Chrome**:
-
-- **State/UI Separation**: State logic completely independent of rendering
-- **Event-Driven Updates**: Media element events trigger state changes
-- **Side Effect Management**: Smart defaults and coordinated state changes
-- **Non-Optimistic Updates**: Wait for actual media element changes
-
-**DOM-Dependent Complexities**:
-
-Some Web APIs require tighter DOM coupling and can't be fully abstracted:
-
-- **Fullscreen API**: `requestFullscreen()` must be called on actual DOM element
-- **Picture-in-Picture**: `requestPictureInPicture()` requires HTMLVideoElement
-- **Remote Playback**: `remote.watchAvailability()` tied to DOM element lifecycle
-
-**VJS-10 Approach**:
-
-MediaStateOwner provides optional DOM element access when needed:
-
-```typescript
-export interface MediaStateOwner {
-  // ... HTMLMediaElement-like properties
-  element?: HTMLElement; // Optional DOM element access for platform-specific APIs
-}
-
-// Usage for fullscreen (requires DOM)
-if (mediaStateOwner.element) {
-  await mediaStateOwner.element.requestFullscreen();
-}
-```
-
-Platform-specific implementations handle these APIs appropriately:
-
-- **HTML**: Direct DOM element access via `mediaStateOwner.element`
-- **React**: Access via `ref.current` mapped to `element` property
-- **React Native**: Platform-specific APIs (not DOM-based fullscreen)
-
-This pragmatic approach maintains the MediaStateOwner abstraction while acknowledging when platform-specific handling is necessary.
-
-**Media-Specific State Examples**:
-
-Media Chrome introduced media-specific state concepts like `mediaVolumeLevel`, `streamType`, and advanced playback states. VJS-10 organizes these into specialized state mediators:
-
-```typescript
-// Temporal state management - time-based controls
-export const temporal = {
-  currentTime: {
-    get(stateOwners: any) {
-      const { media } = stateOwners;
-      return media?.currentTime ?? 0;
-    },
-    set(value: number, stateOwners: any) {
-      const { media } = stateOwners;
-      if (!media || !isValidNumber(value)) return;
-      media.currentTime = value;
-    },
-    mediaEvents: ['timeupdate', 'loadedmetadata'],
-    actions: {
-      seekrequest: ({ detail = 0 }) => +detail,
-    },
-  },
-  duration: {
-    get(stateOwners: any) {
-      const { media } = stateOwners;
-      return media?.duration ?? 0;
-    },
-    mediaEvents: ['durationchange', 'loadedmetadata'],
-  },
-};
-
-// Volume level abstraction - "off", "low", "medium", "high"
-// instead of raw numbers for better UI state management
-```
-
-**References**:
-
-- [`packages/core/media-store/src/state-mediators/audible.ts`](packages/core/media-store/src/state-mediators/audible.ts)
-- [`packages/core/media-store/src/state-mediators/temporal.ts`](packages/core/media-store/src/state-mediators/temporal.ts)
-
-#### 3. Side Effect Coordination
-
-**Media Chrome Pattern**: State changes trigger coordinated side effects across the media ecosystem.
-
-**VJS-10 Enhancement**: Systematic side effect management within state mediators:
-
-```typescript
-// Media Chrome's coordinated side effects -> VJS-10's systematic approach
-const mediatorExample = {
-  muted: {
-    set(value: boolean, stateOwners: any) {
-      const { media } = stateOwners;
-      if (!media) return;
-      media.muted = value;
-
-      // Media Chrome-inspired smart side effects
-      if (!value && !media.volume) {
-        media.volume = 0.25; // Auto-restore volume on unmute
-      }
-    },
-    // Multiple events can trigger state reevaluation
-    mediaEvents: ['volumechange'],
-  },
-
-  volume: {
-    set(value: number, stateOwners: any) {
-      const { media } = stateOwners;
-      if (!media || !Number.isFinite(+value)) return;
-      media.volume = +value;
-
-      // Coordinated state changes
-      if (+value > 0) {
-        media.muted = false; // Auto-unmute when volume increased
-      }
-    },
-  },
-};
-```
-
-**Key Side Effect Patterns**:
-
-- **Coordinated State Changes**: Volume changes affect mute state
-- **Smart Defaults**: Reasonable fallbacks for edge cases
-- **Event Cascade Management**: State changes trigger related updates
-
-#### 4. Event-Driven State Updates and Action Dispatch
-
-**Media Chrome Foundation**: All state changes flow through custom events, creating a reactive system.
-
-**Terminology Note**: State mediators respond to two types of inputs:
-
-- **Media events** (`mediaEvents`) - Signals from the MediaStateOwner describing state changes that occurred (e.g., `'volumechange'`, `'timeupdate'`). These originate from the underlying media element, whether that's an HTMLMediaElement, a React Native Video component, or another platform-specific implementation.
-- **Action dispatches** (`actions`) - Signals from UI components requesting state changes (e.g., `muterequest`, `seekrequest`)
-
-While termed "actions" (following Redux convention), these dispatches function like XState events - they're descriptive signals of user intent, not imperative commands. The state mediator layer transforms these signals into actual state changes with appropriate validation and side effects.
-
-**VJS-10 Evolution**: Maintained event-driven core with enhanced action system:
-
-```typescript
-// Media Chrome's custom events -> VJS-10's action-based system
-export const playable = {
-  paused: {
-    get(stateOwners: any) {
-      const { media } = stateOwners;
-      return media?.paused ?? true;
-    },
-    set(value: boolean, stateOwners: any) {
-      const { media } = stateOwners;
-      if (!media) return;
-      if (value) {
-        media.pause();
-      } else {
-        media.play().catch(() => {}); // Media Chrome's error handling pattern
-      }
-    },
-    mediaEvents: ['play', 'pause', 'loadstart'], // Media events from element
-    actions: {
-      // Action dispatches from UI components
-      playrequest: () => false, // false = not paused
-      pauserequest: () => true, // true = paused
-    },
-  },
-};
-```
-
-**Event Architecture Evolution**:
-
-- **Request/Response Pattern**: Components dispatch action requests, state mediators handle responses
-- **Event Normalization**: Consistent patterns across different media APIs
-- **Error Handling**: Graceful degradation following Media Chrome patterns
-
-#### 5. Web Component Foundation (vs. Common Core)
-
-**Media Chrome Legacy**: Established patterns for media-focused web components with Shadow DOM encapsulation, representing a web-first approach that contrasts with VidStack's common core strategy.
-
-**VJS-10 Platform Evolution**: Extended Media Chrome's component concepts across platforms while adopting VidStack's common core philosophy:
-
-**HTML Platform (Web Component Heritage)**:
-
-```typescript
-// Media Chrome's web component pattern -> VJS-10's HTML platform
-export class MuteButtonBase extends MediaChromeButton {
-  _state: MuteButtonState | undefined;
-
-  handleEvent(event: Event) {
-    const { type } = event;
-    const state = this._state;
-    if (state && type === 'click') {
-      // Media Chrome's state-driven interaction pattern
-      if (state.volumeLevel === 'off') {
-        state.requestUnmute();
-      } else {
-        state.requestMute();
-      }
-    }
-  }
-}
-```
-
-**React Platform (Component Pattern Evolution)**:
-
-```tsx
-// Media Chrome's component logic -> React platform adaptation
-export function renderMuteButton(props, state) {
-  return (
-    <button
-      {...props}
-      onClick={() => {
-      // Same Media Chrome interaction logic, different platform
-        if (state.volumeLevel === 'off') {
-          state.requestUnmute();
-        } else {
-          state.requestMute();
-        }
-      }}
-    >
-      {props.children}
-    </button>
-  );
-}
-```
-
-#### Media Chrome → VJS-10 Evolution Summary
-
-| Aspect                     | Media Chrome Foundation       | VJS-10 Evolution                           |
-| -------------------------- | ----------------------------- | ------------------------------------------ |
-| **State Management**       | Centralized MediaStore        | Distributed state mediators                |
-| **Media Interface**        | Extended HTMLMediaElement     | Systematic MediaStateOwner                 |
-| **Component Architecture** | Web Components only           | Multi-platform (HTML, React, React Native) |
-| **State Coupling**         | Event-driven decoupling       | Hook-based + event-driven                  |
-| **Side Effects**           | Coordinated state changes     | Systematic mediator side effects           |
-| **Platform Strategy**      | Web-first with React wrappers | Platform-native with shared core           |
-
-### Base UI Component Primitives
-
-VJS-10's React component architecture follows patterns from [Base UI](https://base-ui.com/), MUI's headless component library. This influence manifests in several key ways:
-
-#### 1. Primitive Component Philosophy
-
-**Base UI Approach**: Components are unstyled, behavior-focused primitives that provide functionality without imposing design decisions.
-
-**VJS-10 Implementation**: All React components follow the primitive pattern, requiring explicit styling and content:
-
-```tsx
-// Primitive approach - no default styling or icons
-<MuteButton className={styles.muteButton}>
-  <VolumeOffIcon className={styles.icon} />
-</MuteButton>;
-```
-
-**Reference**: [`packages/react/react/src/components/MuteButton.tsx`](packages/react/react/src/components/MuteButton.tsx)
-
-#### 2. Render Function Architecture
-
-**Base UI Pattern**: Components accept custom render props for complete presentation control.
-
-**VJS-10 Implementation**:
-
-```tsx
-// Built-in render prop support via component factory
-function ConnectedComponent({
-  render = defaultRender,
-  ...props
-}: TProps & { render?: TRenderFn }) {
-  const connectedState = useStateHook(props);
-  const connectedProps = usePropsHook(props, connectedState);
-  return render(connectedProps, connectedState);
-}
-```
-
-**References**:
-
-- [`packages/react/react/src/utils/component-factory.tsx`](packages/react/react/src/utils/component-factory.tsx)
-- [Base UI Button Documentation](https://base-ui.com/react/components/button)
-
-#### 3. Separation of State and Props in Render Functions
-
-**Base UI Pattern**: Render functions receive computed props and component state as separate arguments.
-
-**VJS-10 Implementation**:
-
-```tsx
-export function renderMuteButton(props: MuteButtonProps, // Computed props (data attrs, aria, etc.)
-  state: MuteButtonState) {
-  return (
-    <button
-      {...props}
-      onClick={() => {
-        if (state.volumeLevel === 'off') {
-          state.requestUnmute();
-        } else {
-          state.requestMute();
-        }
-      }}
-    >
-      {props.children}
-    </button>
-  );
-}
-```
-
-#### 4. Data Attributes for CSS-Driven State Changes
-
-**Base UI Philosophy**: Expose component state via data attributes for CSS targeting.
-
-**VJS-10 Implementation**:
-
-```tsx
-export function useMuteButtonProps(props, state) {
-  return {
-    'data-volume-level': state.volumeLevel, // "off", "low", "medium", "high"
-    'data-muted': state.muted ? '' : undefined,
-    'aria-label': state.muted ? 'unmute' : 'mute',
-    ...props,
-  };
-}
-```
-
-This enables CSS-driven visual state changes:
-
-```css
-[data-volume-level='off'] .volume-high-icon {
-  display: none;
-}
-[data-volume-level='off'] .volume-off-icon {
-  display: block;
-}
-[data-muted] {
-  opacity: 0.6;
-}
-```
-
-#### 5. Accessibility-First Design
-
-**Base UI Approach**: Accessibility attributes are built-in by default, not opt-in.
-
-**VJS-10 Implementation**: All components include accessibility props automatically:
-
-```tsx
-export function useMuteButtonProps(props, state) {
-  return {
-    role: 'button',
-    'aria-label': state.muted ? 'unmute' : 'mute', // Dynamic based on state
-    ...props, // External props can override
-  };
-}
-```
-
-#### 6. Children Expected in All Use Cases
-
-**Base UI Philosophy**: Even default implementations require explicit content provision.
-
-**VJS-10 Example**: The default media skin must explicitly provide all styling and content:
-
-```tsx
-// Even "default" skin requires explicit icons and styling
-<MuteButton className={`${styles.Button} ${styles.MediaMuteButton}`}>
-  <VolumeHighIcon className={`${styles.Icon} ${styles.VolumeHighIcon}`} />
-  <VolumeLowIcon className={`${styles.Icon} ${styles.VolumeLowIcon}`} />
-  <VolumeOffIcon className={`${styles.Icon} ${styles.VolumeOffIcon}`} />
-</MuteButton>;
-```
-
-**Reference**:
-
-- Default skin: [`packages/react/react/src/skins/default/MediaSkinDefault.tsx`](packages/react/react/src/skins/default/MediaSkinDefault.tsx)
-- Toasted skin: [`packages/react/react/src/skins/toasted/MediaSkinToasted.tsx`](packages/react/react/src/skins/toasted/MediaSkinToasted.tsx)
-
-#### 7. Compound Component Architecture
-
-**Status:** ✅ Implemented
-
-**Inspiration**: [Base UI Slider compound components](https://base-ui.com/react/components/slider) (`Slider.Root`, `Slider.Track`, `Slider.Thumb`)
-
-VJS-10 implements Base UI-inspired compound components for sliders, providing fine-grained control over each sub-component:
-
-**TimeSlider Implementation**:
-
-```tsx
-<TimeSlider.Root className={styles.SliderRoot}>
-  <TimeSlider.Track className={styles.SliderTrack}>
-    <TimeSlider.Progress className={styles.SliderProgress} />
-    <TimeSlider.Pointer className={styles.SliderPointer} />
-  </TimeSlider.Track>
-  <TimeSlider.Thumb className={styles.SliderThumb} />
-</TimeSlider.Root>;
-```
-
-**Components:**
-
-- `TimeSlider.Root` - Root container with state management and ARIA attributes
-- `TimeSlider.Track` - Track element for visual rail
-- `TimeSlider.Progress` - Filled portion showing current progress
-- `TimeSlider.Pointer` - Preview/hover indicator (media-specific enhancement)
-- `TimeSlider.Thumb` - Draggable thumb control
-
-**VolumeSlider Implementation**:
-
-```tsx
-<VolumeSlider.Root orientation="vertical" className={styles.SliderRoot}>
-  <VolumeSlider.Track className={styles.SliderTrack}>
-    <VolumeSlider.Progress className={styles.SliderProgress} />
-  </VolumeSlider.Track>
-  <VolumeSlider.Thumb className={styles.SliderThumb} />
-</VolumeSlider.Root>;
-```
-
-**Components:**
-
-- `VolumeSlider.Root` - Root container with volume state
-- `VolumeSlider.Track` - Track element
-- `VolumeSlider.Progress` - Filled portion showing current volume
-- `VolumeSlider.Thumb` - Draggable thumb control
-
-**Media-Specific Enhancements**:
-
-Unlike Base UI's generic sliders, VJS-10 sliders include media-specific features:
-
-- **`TimeSlider.Pointer`**: Hover preview indicator for scrubbing
-- **CSS Variables**: `--slider-fill`, `--slider-pointer` for styling
-- **Data Attributes**: `data-orientation`, `data-current-time`, `data-duration`
-- **Media State Integration**: Automatic synchronization with media playback
-
-**Architectural Benefits**:
-
-1. **Maximum Flexibility**: Fine-grained control over each sub-component
-2. **Base UI Consistency**: Familiar compound component API patterns
-3. **Styling Granularity**: Target specific sub-components with CSS selectors
-4. **Accessibility**: Built-in ARIA relationships between compound components
-5. **Primitive Philosophy**: Maintains unstyled, behavior-focused approach
-
-**References:**
-
-- Implementation: [`packages/react/react/src/components/TimeSlider.tsx`](packages/react/react/src/components/TimeSlider.tsx)
-- Implementation: [`packages/react/react/src/components/VolumeSlider.tsx`](packages/react/react/src/components/VolumeSlider.tsx)
-- Usage: [`packages/react/react/src/skins/default/MediaSkinDefault.tsx`](packages/react/react/src/skins/default/MediaSkinDefault.tsx)
-
-### VidStack: Framework-Agnostic Common Core Architecture
-
-**Primary Influence**: VJS-10's multi-platform architecture follows [VidStack](https://vidstack.io/)'s **framework-agnostic common core** pattern—a fundamental departure from the "thin wrapper" approach used by libraries like Media Chrome.
-
-#### 1. Framework-Agnostic Common Core (Primary Influence)
-
-**VidStack's Approach**: Unlike Media Chrome (which wraps Web Components for React), VidStack built a true **shared common core** using their Maverick library that provides framework-agnostic UI logic. This means the same business logic, state management, and component behaviors work across Web Components AND React without wrappers or translations.
-
-**Why This Matters**:
-
-- **Media Chrome Approach**: Web Component → React wrapper (thin abstraction, two implementations)
-- **VidStack Approach**: Common Core → Web Component adaptation + React adaptation (shared logic)
-- **Result**: VidStack avoids duplication while Media Chrome must maintain framework-specific logic
-
-**VJS-10 Adoption**: This philosophy directly shaped VJS-10's core package architecture:
-
-```tsx
-// HTML Platform Implementation
-export class MediaButton extends HTMLElement {
-  connectedCallback() {
-    this.mediaStore = getMediaStore(); // Shared core state
-  }
-}
-
-// React Platform Implementation
-export function useMediaButton() {
-  const mediaStore = useMediaStore(); // Same core state, different hook
-  return mediaStore.getState();
-};
-
-// React Native Platform Implementation
-export function MediaButtonNative() {
-  const store = useMediaStore(); // Same core, native platform
-  return <Pressable onPress={store.handlePress} />;
-};
-```
-
-**Key Architectural Benefits**:
-
-- **Code Sharing**: Core logic shared across HTML, React, React Native platforms
-- **Framework Abstraction**: State management independent of rendering framework
-- **Unified Developer Experience**: Consistent APIs across different platforms
-
-**Reference**: VJS-10's strict dependency hierarchy prevents circular dependencies while enabling core package reuse
-
-#### 2. Documentation-Based Copy-and-Own Philosophy
-
-**VidStack Approach**: While not providing CLI tooling like shadcn/ui, VidStack accomplishes component ownership through comprehensive copy-paste functionality in its hosted documentation.
-
-**VidStack Implementation**:
-
-- **Code Snippet Distribution**: Provides copy-paste functionality with snippet IDs (e.g., `docs/main`) for lazy-loading examples
-- **Example-Driven Development**: Maintains a dedicated examples repository showing implementation patterns across frameworks
-- **Developer Ownership via Documentation**: Enables component customization through well-documented, copy-pasteable code patterns
-
-**VJS-10 Planned Evolution**: VidStack's documentation-first approach influenced the decision to combine traditional npm packages with CLI-based copy-and-own tooling:
-
-```bash
-# Planned VJS-10 CLI (shadcn/ui inspired, VidStack documentation philosophy)
-npx vjs-10 add mute-button --framework=react --skin=default
-npx vjs-10 add time-range --framework=html --customizable=true
-```
-
-**Hybrid Distribution Model**:
-
-- **Traditional npm**: Standard package consumption for rapid prototyping
-- **Copy-and-Own CLI**: Full component source code ownership for production customization
-- **Documentation Examples**: VidStack-style copy-paste patterns for learning and integration
-
-#### 3. Cross-Platform Component Patterns
-
-**VidStack's Framework Strategy**: Base components define core logic independent of rendering, then adapt to specific frameworks via `Host(Component, HTMLElement)` for Web Components and `createReactComponent(Component)` for React.
-
-**VJS-10 Implementation**: While not using VidStack's exact adaptation pattern, the philosophical approach directly influenced VJS-10's component architecture:
-
-```typescript
-// VidStack's base component concept -> VJS-10's shared state definitions
-// Both separate behavior from presentation
-
-// VidStack Pattern
-class BaseButton {
-  onSetup() {
-    /* core logic */
-  }
-
-  onAttach() {
-    /* platform attachment */
-  }
-}
-const WebButton = Host(BaseButton, HTMLElement);
-const ReactButton = createReactComponent(BaseButton);
-
-// VJS-10 Pattern
-const muteButtonStateDefinition = {
-  stateTransform: state => ({
-    muted: state.muted,
-    volumeLevel: state.volumeLevel,
-  }),
-  createRequestMethods: dispatch => ({
-    requestMute: () => dispatch({ type: 'mute' }),
-    requestUnmute: () => dispatch({ type: 'unmute' }),
-  }),
-};
-
-// HTML Platform
-export class MuteButtonHTML extends HTMLElement {
-  connectedCallback() {
-    this.state = muteButtonStateDefinition.stateTransform(
-      getMediaStore().getState(),
-    );
-  }
-}
-
-// React Platform
-export function useMuteButtonState() {
-  const mediaState = useMediaSelector(muteButtonStateDefinition.stateTransform);
-  const methods = muteButtonStateDefinition.createRequestMethods(dispatch);
-  return { ...mediaState, ...methods };
-}
-```
-
-**Component Architecture Evolution**:
-
-| Aspect                   | VidStack Approach                     | VJS-10 Evolution                       |
-| ------------------------ | ------------------------------------- | -------------------------------------- |
-| **Base Components**      | Framework-agnostic base classes       | Framework-agnostic state definitions   |
-| **Framework Adaptation** | Host functions & createReactComponent | Platform-specific hook implementations |
-| **State Management**     | Maverick Signals                      | nanostores with shared transformations |
-| **Lifecycle Management** | onSetup/onAttach/onConnect/onDestroy  | Standard platform lifecycles           |
-
-#### VidStack → VJS-10 Architectural Summary
-
-| Influence Area                               | VidStack Foundation                   | VJS-10 Evolution                                     |
-| -------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
-| **Framework-Agnostic Common Core** (PRIMARY) | Maverick-based common core            | Core packages with strict dependency hierarchy       |
-| **Component Distribution**                   | Documentation-based copy-paste        | Hybrid npm + CLI copy-and-own (planned)              |
-| **Framework Adaptation**                     | Host functions + createReactComponent | Platform-specific implementations sharing core logic |
-| **State Management**                         | Maverick Signals                      | nanostores with state mediators                      |
-
-**Key Takeaway**: VidStack's most important influence on VJS-10 is the **framework-agnostic common core** pattern, which enables sharing UI logic across HTML, React, and React Native without thin wrappers or duplication.
-
-**References**:
-
-- [VidStack Player](https://vidstack.io/)
-- [VidStack Architecture](https://vidstack.io/docs/player/getting-started/architecture/)
-- [Maverick Signals](https://github.com/maverick-js/signals)
-- [VidStack GitHub](https://github.com/vidstack/player)
-
-### Adobe React Spectrum: State/Behavior/UI Hook Separation
-
-**Primary Influence**: VJS-10's hook-based component architecture uses [Adobe React Spectrum](https://react-spectrum.adobe.com/)'s **three-layer hook separation** pattern, which divides component logic into state, behavior, and UI layers.
-
-#### Adobe Spectrum Three-Layer Hook Architecture
-
-**Adobe's Philosophy**: "Split each component into three parts: state, behavior, and the rendered component, made possible by React Hooks."
-
-**The Three Layers**:
-
-1. **State Hooks** (React Stately) - "Implements state management and core logic for each component" - Platform-independent, no view system assumptions
-2. **Behavior Hooks** (React Aria) - "Implements event handling, accessibility, internationalization" - Platform-specific interactions, returns props to spread
-3. **Component Layer** (React Spectrum) - Renders actual platform elements with design system styling
-
-**Why This Separation Matters**:
-
-- **State hooks** can work across web, React Native, and other platforms
-- **Behavior hooks** handle web-specific concerns (keyboard, mouse, screen readers)
-- **Components** provide design system-specific styling without reimplementing logic
-
-**Reference**: [Adobe Spectrum Architecture Documentation](https://react-spectrum.adobe.com/architecture.html)
-
-#### VJS-10's Adaptation: Hook-Based Component Factory
-
-**Explicit Acknowledgment**: VJS-10's component factory directly references Adobe Spectrum as inspiration:
-
-```tsx
-/**
- * Generic factory function to create connected components following the hooks pattern
- * inspired by Adobe React Spectrum and Base UI architectures.
- */
-export function toConnectedComponent(useStateHook, // State layer - media-specific state management
-  usePropsHook, // Behavior layer - props transformation & accessibility
-  defaultRender, // Component layer - platform-specific rendering
-  displayName) {
-  /* ... */
-}
-```
-
-**Reference**: [`packages/react/react/src/utils/component-factory.tsx:20-27`](packages/react/react/src/utils/component-factory.tsx#L20-L27)
-
-#### Layer-by-Layer Implementation
-
-##### 1. State Layer: Framework-Agnostic Core Logic
-
-**Adobe Spectrum Pattern**: State hooks "make no assumptions about the view system" and implement "core logic for the component."
-
-**VJS-10 Implementation**: State hooks connect to framework-agnostic core packages:
-
-```tsx
-export function useMuteButtonState(_props: any) {
-  const mediaStore = useMediaStore();
-  const mediaState = useMediaSelector(
-    muteButtonStateDefinition.stateTransform, // Core package logic
-    shallowEqual,
-  );
-
-  const methods = React.useMemo(
-    () => muteButtonStateDefinition.createRequestMethods(mediaStore.dispatch),
-    [mediaStore],
-  );
-
-  return {
-    volumeLevel: mediaState.volumeLevel, // Framework-agnostic state
-    muted: mediaState.muted,
-    requestMute: methods.requestMute, // Framework-agnostic methods
-    requestUnmute: methods.requestUnmute,
-  } as const;
-}
-```
-
-**Key Characteristics**:
-
-- Uses core `muteButtonStateDefinition` from `@videojs/core/store`
-- No platform-specific assumptions
-- Could theoretically work with React Native or other platforms
-
-**Reference**: [`packages/react/react/src/components/MuteButton.tsx:10-29`](packages/react/react/src/components/MuteButton.tsx#L10-L29)
-
-##### 2. Behavior Layer: Props Transformation & Accessibility
-
-**Adobe Spectrum Pattern**: Behavior hooks "implement event handling, accessibility, internationalization" and "return platform specific props that can be spread onto elements."
-
-**VJS-10 Implementation**: Props hooks transform state into platform-specific attributes:
-
-```tsx
-export function useMuteButtonProps(props: React.PropsWithChildren<{ [k: string]: any }>, state: ReturnType<typeof useMuteButtonState>) {
-  const baseProps: Record<string, any> = {
-    // Accessibility (Adobe Spectrum influence)
-    role: 'button',
-    'aria-label': state.muted ? 'unmute' : 'mute',
-
-    // Platform-specific data attributes
-    'data-volume-level': state.volumeLevel,
-    'data-tooltip': state.muted ? 'Unmute' : 'Mute',
-
-    // Prop spreading pattern (Adobe Spectrum)
-    ...props,
-  };
-
-  // Boolean data attribute handling
-  if (state.muted) {
-    baseProps['data-muted'] = '';
-  }
-
-  return baseProps;
-}
-```
-
-**Key Adobe Spectrum Parallels**:
-
-- **Prop Spreading**: Returns props object to be spread onto DOM elements
-- **Accessibility Focus**: ARIA attributes built-in by default
-- **Platform Specificity**: Handles React/DOM-specific attribute patterns
-- **State Integration**: Takes state hook output as input parameter
-
-**Reference**: [`packages/react/react/src/components/MuteButton.tsx:34-57`](packages/react/react/src/components/MuteButton.tsx#L34-L57)
-
-##### 3. Component Layer: Platform-Specific Rendering
-
-**Adobe Spectrum Pattern**: Components "provide the theme and design system specific logic, and renders the actual platform elements."
-
-**VJS-10 Implementation**: Render functions compose the layers:
-
-```tsx
-export function renderMuteButton(props: MuteButtonProps, // From behavior layer
-  state: MuteButtonState) {
-  return (
-    <button
-      {...props} // Adobe Spectrum prop spreading pattern
-      onClick={() => {
-        if (state.volumeLevel === 'off') {
-          state.requestUnmute(); // Framework-agnostic state methods
-        } else {
-          state.requestMute();
-        }
-      }}
-    >
-      {props.children}
-      {' '}
-      // Platform-specific content
-    </button>
-  );
-}
-```
-
-**Adobe Spectrum Parallels**:
-
-- **Prop Spreading**: `{...props}` applies behavior layer props to DOM element
-- **State Method Usage**: Calls framework-agnostic state methods
-- **Platform Elements**: Renders actual React/DOM elements (`<button>`)
-
-#### Framework-Agnostic Benefits
-
-**Adobe Spectrum Goal**: "Make reusing behavior across design systems as easy as possible, while allowing full design customizability."
-
-**VJS-10 Achievement**: The three-layer separation enables:
-
-1. **Cross-Platform State**: Core state definitions work across HTML, React, React Native
-2. **Reusable Behavior**: Props transformation logic could be adapted to other frameworks
-3. **Complete Styling Control**: No imposed design decisions
-4. **Accessibility by Default**: ARIA patterns built into behavior layer
-
-#### Component Factory Pattern
-
-**Adobe Spectrum Inspiration**: Their architecture enables "complete control over the rendering" while maintaining clean separation.
-
-**VJS-10's Factory**: Automates the Adobe Spectrum pattern:
-
-```tsx
-// Automated composition of Adobe Spectrum's three layers
-export const MuteButton = toConnectedComponent(
-  useMuteButtonState, // State layer
-  useMuteButtonProps, // Behavior layer
-  renderMuteButton, // Component layer
-  'MuteButton',
-);
-```
-
-This factory pattern systematically applies Adobe Spectrum's architectural principles across all VJS-10 components.
-
-#### Adobe Spectrum → VJS-10 Summary
-
-**Primary Takeaway**: Adobe Spectrum's most important influence on VJS-10 is the **state/behavior/UI hook separation** pattern. This three-layer architecture enables:
-
-1. **State hooks** (`useMuteButtonState`) - Platform-agnostic, reusable across web/React Native
-2. **Behavior hooks** (`useMuteButtonProps`) - Platform-specific accessibility and prop transformation
-3. **UI layer** (`renderMuteButton`) - Design system rendering without business logic
-
-This clean separation of concerns is implemented systematically across all VJS-10 components via the `toConnectedComponent()` factory, directly mirroring Adobe Spectrum's architectural philosophy.
-
-**References**:
-
-- [Adobe React Spectrum Architecture](https://react-spectrum.adobe.com/architecture.html)
-- [React Aria Hooks](https://react-spectrum.adobe.com/react-aria/hooks.html)
-- [React Stately](https://react-spectrum.adobe.com/react-stately/index.html)
-
-## Additional Resources
-
-- [Base UI Documentation](https://base-ui.com/)
-- [Base UI Slider Component](https://base-ui.com/react/components/slider)
-- [Base UI Button Component](https://base-ui.com/react/components/button)
-- [Compound Component Pattern](https://www.patterns.dev/react/compound-pattern)
-- [Adobe React Spectrum](https://react-spectrum.adobe.com/)
-- [Adobe Spectrum Architecture](https://react-spectrum.adobe.com/architecture.html)
-- [React Aria Hooks](https://react-spectrum.adobe.com/react-aria/hooks.html)
-
----
-
-_This document will continue to evolve as VJS-10's architecture develops and new influences are incorporated._
+- Ensure consistent behavior across major browsers.
+- Abstract differences in media APIs (fullscreen, PiP, captions, streaming).
+- Normalize vendor‑specific features through adapters and polyfills.
+- Maintain uniform rendering, controls, and accessibility regardless of platform.
diff --git a/docs/PLAYBACK_ENGINE_FRAMEWORK_VISION.md b/docs/PLAYBACK_ENGINE_FRAMEWORK_VISION.md
deleted file mode 100644
index 70161ea4..00000000
--- a/docs/PLAYBACK_ENGINE_FRAMEWORK_VISION.md
+++ /dev/null
@@ -1,981 +0,0 @@
-# Composable Playback Engine Framework Architecture (Vision)
-
-_A Guide to Building Modular, Performance-Optimized Video Playback Systems_
-
-## Implementation Status
-
-**Status:** 📋 Planned - This document describes a future architectural vision
-
-**Current State (as of 2025-10-10):**
-
-- VJS-10 currently has a minimal `HlsJSPlaybackEngine` implementation ([`packages/core/playback-engine/src/HlsJSPlaybackEngine.ts`](packages/core/playback-engine/src/HlsJSPlaybackEngine.ts))
-- Current interface: `IBasePlaybackEngine` with basic src, mediaElement, element, and destroy properties
-- **This document describes the future composable architecture**, not the current implementation
-- The architecture described here represents design goals and principles we aim to achieve
-
-**Purpose of This Document:**
-
-- Articulate the architectural vision for VJS-10's future playback engine
-- Document design principles and patterns for composability
-- Provide reference for future implementation work
-- Explain the rationale behind the "outward vs inward" separation
-
-**What This Document Is NOT:**
-
-- NOT a description of current implementation
-- NOT an API reference for existing code
-- NOT a step-by-step implementation guide
-
-For current playback engine implementation details, see the actual source files in `packages/core/playback-engine/`.
-
-## Current Implementation vs Vision
-
-| Aspect                    | Current (HlsJSPlaybackEngine)                             | Vision (This Document)                                         |
-| ------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
-| **Architecture**          | Thin wrapper around hls.js                                | Composable functional core with multiple interfaces            |
-| **Interface**             | Simple `IBasePlaybackEngine` (src, mediaElement, destroy) | Full HTMLMediaElement subset + media-specific extensions       |
-| **Composition**           | Monolithic hls.js instance                                | Functional middleware composition                              |
-| **Use Case Support**      | HLS playback only                                         | Multiple content types, optimized builds per use case          |
-| **State Management**      | Internal to hls.js                                        | XState-based state machines                                    |
-| **Extensibility**         | Limited to hls.js configuration                           | Composable adapters, composable state machines                 |
-| **Bundle Optimization**   | Full hls.js bundle (~800KB)                               | Tree-shakeable functional units                                |
-| **Testing**               | Integration tests only                                    | Unit testable functional components                            |
-| **Framework Integration** | Event-based imperative API                                | Multiple interface options (imperative, reactive, declarative) |
-
-**Migration Path:**
-
-The vision architecture is designed to be implemented incrementally:
-
-1. **Phase 1**: Implement functional core with basic HLS support
-2. **Phase 2**: Add composable middleware system
-3. **Phase 3**: Build multiple interface adapters
-4. **Phase 4**: Optimize for different use cases (progressive, tree-shaking)
-
-The current `HlsJSPlaybackEngine` serves as a working baseline while the composable architecture is developed.
-
----
-
-# Executive Summary
-
-Current video playback engines suffer from “Swiss Army knife” architecture—monolithic systems that bundle all possible features regardless of actual use case needs. This creates performance penalties, integration friction, and maintenance complexity. This document outlines a composable architecture that solves these problems by separating **outward-facing interfaces** from **inward-facing implementations** and enabling functional composition of both layers.
-
-**Key Innovation**: Decouple what a playback engine exposes (outward API) from how it implements features (inward composition), allowing the same engine to serve multiple integration patterns while optimizing internal functionality for specific use cases.
-
-# The Problem Space
-
-## Current Architecture Limitations
-
-### Monolithic Design Issues
-
-- Bundle sizes routinely exceed 500KB-1MB (hls.js: ~800KB, Shaka: ~1.2MB)
-- Features are diffused throughout codebase, making subsetting nearly impossible
-- Tight coupling between components prevents modular replacement
-- One-size-fits-all approach optimizes for no specific use case
-
-### Performance Trade-offs
-
-- **Core Web Vitals Impact**: Large JavaScript bundles hurt Time to Interactive, Largest Contentful Paint
-- **Video QoE Impact**: Lazy loading improves CWV but delays video startup time
-- **Framework Integration**: Event-driven, imperative player APIs clash with modern declarative, reactive frameworks
-
-### Testing and Maintainability Challenges
-
-- **Unit Testing Limitations**: Testing discrete functional units in isolation is difficult to impossible due to tight coupling and shared dependencies
-- **Integration Testing Complexity**: Testing subsets of interrelated functional units is even more challenging, often requiring extensive mocking or full system setup
-- **Debugging and Root Cause Analysis**: Extremely difficult to debug complex real-world issues by “narrowing the problem space” - you can’t easily compose a simplified playback engine to isolate where/when particular issues are introduced
-- **Regression Prevention**: Avoiding regressions is nearly impossible due to interconnectedness of moving pieces - changes in one area can have unexpected effects in seemingly unrelated functionality
-
-### Real-World Impact
-
-- Media players often represent 30-50% of total page JavaScript
-- No viable path from simple to advanced use cases without “throwing developers into the deep end”
-- Custom implementations require either forking complex codebases or building from scratch
-- Bug fixes and feature additions carry high risk of unintended side effects
-
-# Architecture Vision: Outward vs Inward Separation
-
-## The Fundamental Architectural Principle
-
-Current playback engines fail to sufficiently separate their public-facing architecture from their internal implementation architecture. Both layers typically use the same OOP patterns: stateful, event-dispatching instances that manage complex internal state. Internally, this manifests as a collection of “Controllers,” “Managers,” and similar objects that mirror the external API patterns, creating tight coupling throughout the system.
-
-This architectural uniformity creates rigid, monolithic systems where internal implementation details leak into public APIs and vice versa. Our architecture establishes a clear separation:
-
-- **Outward-Facing Interface**: Stateful, event-based instances that provide familiar integration patterns
-- **Inward-Facing Implementation**: Functional, composable units optimized for the actual work of media processing
-
-This separation enables the same engine core to present multiple outward interfaces while optimizing internal behavior through functional composition rather than object orchestration.
-
-## Outward-Facing Interface (The “What”)
-
-The playback engine exposes a single, unified outward interface:
-
-### Core Interface Definition
-
-```tsx
-interface ComposablePlaybackEngine extends EventTarget {
-  // HTMLMediaElement subset
-  readonly currentTime: number;
-  readonly duration: number;
-  readonly buffered: TimeRanges;
-  readonly paused: boolean;
-  readonly ended: boolean;
-  readonly readyState: number;
-  src: string;
-  play: () => Promise<void>;
-  pause: () => void;
-
-  // Media-specific extensions for content permutations
-  // NOTE: These are placeholder examples - actual API surface TBD
-  // through implementation and testing of real use cases
-  readonly currentLevel: number;
-  // TODO: May need different structure for non-ABR content
-  readonly levels: Array<{
-    // TODO: This shape assumes HLS/DASH - needs generalization
-    index: number;
-    bitrate: number;
-    width?: number;
-    height?: number;
-    codecs: string;
-  }>;
-  readonly audioTracks: Array<{
-    // TODO: Consider relationship to native AudioTrackList
-    id: string;
-    label: string;
-    language: string;
-    enabled: boolean;
-  }>;
-  // Playback engine specific methods
-  // NOTE: Method signatures are provisional and subject to change based on  // composable architecture requirements
-  selectLevel: (level: number) => void; // TODO: How does this work with server-determined composition?
-  selectAudioTrack: (trackId: string) => void; // TODO: Should this mirror native audio track selection?}
-}
-```
-
-### Event Extensions for Media Content
-
-```tsx
-interface PlaybackEngineEventMap {
-  // Standard HTMLMediaElement events
-  loadstart: Event;
-  loadedmetadata: Event;
-  canplay: Event;
-  playing: Event;
-  pause: Event;
-  ended: Event;
-  error: ErrorEvent;
-
-  // Media-specific events
-  levelLoaded: CustomEvent<{ level: number; details: object }>;
-  manifestParsed: CustomEvent<{ levels: Array<object>; audioTracks: Array<object> }>;
-  fragmentLoaded: CustomEvent<{ frag: object; stats: object }>;
-  audioTrackSwitched: CustomEvent<{ trackId: string }>;
-  subtitleTrackLoaded: CustomEvent<{ track: object }>;
-}
-
-// Usage
-const engine: ComposablePlaybackEngine = new ComposablePlaybackEngineImpl(mediaElement, config);
-engine.addEventListener('levelLoaded', (event) => {
-  console.log('Level loaded:', event.detail.level);
-});
-engine.addEventListener('loadstart', handleLoadStart);
-engine.src = 'playlist.m3u8';
-```
-
-**Integration Adapters**:
-Other integration patterns (VideoJS Tech, React hooks, etc.) are **adapters** that wrap this core interface rather than separate implementations:
-
-```tsx
-// VideoJS Tech adapter
-class ComposableTech extends Tech {
-  private engine: ComposablePlaybackEngine;
-  constructor(options: object, ready: () => void) {
-    super(options, ready);
-    this.engine = new ComposablePlaybackEngineImpl(this.el(), options);
-    // Map engine events to VideoJS events
-  }
-}
-// React hook adapter
-function usePlaybackEngine(src: string, options: object): {
-  engine: ComposablePlaybackEngine;
-  state: PlaybackState;
-} {
-  const engine = useMemo(() => new ComposablePlaybackEngineImpl(null, options), []);
-  // Return reactive state derived from engine
-}
-```
-
-## Inward-Facing Implementation (The “How”)
-
-Internal architecture could use patterns **inspired by XState’s actors and state machines** as one approach to replace traditional “Controllers” and “Managers” with composable, event-driven functional units. The following examples are intended to demonstrate these concepts without requiring XState as a dependency. **_However_**, there are some core concepts and constructs in XState that would very likely be beneficial to this architecture. A non-exhaustive list includes:
-
-- A distinction between different kinds of “state”
-  - **Context** - Defines the state that is generically used for information and processing - things like modeling playlist, identifying what is(n’t) buffered, filter state, selection state, etc.
-  - **Finite State** - Defines the relationships between parts of the system and possible state and state transitions. In most architectures, this is some mix of modeled “state” (sometimes global, sometimes local, sometimes ethereal) and hardcoded relationships between functionality and (**_sometimes_**) some amount of overriding of “Controllers” and the like.
-- Declarative/Functional + Functional Reactive Principles - Both kinds of “state” (context and finite state) are updated in non-mutative ways. These “handcuffs” will at least help to make sure our architecture and building blocks avoid common assumptions and couplings in player/playback engine architectures.
-- Well defined generic core constructs and transforms
-  - Actors
-  - (Finite) State Machines (A particular kind of actor)
-  - Promises (can be translated as a simple state machine)
-  - Observables (can be translated as a simple state machine)
-  - Reducers (used for immutable and reactive context “state” transforms via e.g. “assign” functions)
-  - Actions vs. Events
-- JSON-serializable context and state machine composition definitions - Both kinds of state can be defined as POJOs that are JSON-(de)serializable. This unlocks several possibilities, including client+server use cases discussed elsewhere in the doc.
-
-### Actor-Based Composition Example:
-
-```tsx
-// Each functional unit could be modeled as an actor-like pattern
-// NOTE: This example uses XState-like syntax for illustration -
-// actual implementation may use different patterns or libraries
-
-const PlaylistParsingActor = setup({
-  types: {
-    context: {} as { manifest?: ParsedManifest; error?: Error },
-    events: {} as
-    | { type: 'PARSE_MANIFEST'; url: string }
-    | { type: 'RETRY' },
-    input: {} as { manifestUrl: string }
-  }
-}).createMachine({
-  id: 'playlist-parser',
-  initial: 'idle',
-  states: {
-    idle: {
-      on: { PARSE_MANIFEST: 'parsing' }
-    },
-    parsing: {
-      invoke: {
-        src: 'fetchAndParseManifest',
-        input: ({ event }) => ({ url: event.url }),
-        onDone: {
-          target: 'parsed',
-          actions: [
-            assign(({ event }) => ({ manifest: event.output })),
-            sendParent({ type: 'MANIFEST_PARSED', manifest: event.output })
-          ]
-        },
-        onError: { target: 'failed', actions: assign(({ event }) => ({ error: event.data })) }
-      }
-    },
-    parsed: { on: { PARSE_MANIFEST: 'parsing' } },
-    failed: { on: { RETRY: 'parsing' } }
-  }
-});
-
-const BufferManagementActor = setup({
-  types: {
-    context: {} as { bufferedRanges: TimeRanges; pendingSegments: Segment[] },
-    events: {} as
-    | { type: 'APPEND_SEGMENT'; segment: Segment }
-    | { type: 'FLUSH_BUFFER' }
-  }
-}).createMachine({
-  id: 'buffer-manager',
-  initial: 'idle',
-  states: {
-    idle: { on: { APPEND_SEGMENT: 'appending' } },
-    appending: {
-      invoke: {
-        src: 'appendToSourceBuffer',
-        input: ({ event }) => ({ segment: event.segment }),
-        onDone: {
-          target: 'idle',
-          actions: [
-            assign(({ context, event }) => ({
-              bufferedRanges: event.output.buffered,
-              pendingSegments: context.pendingSegments.slice(1)
-            })),
-            sendParent({ type: 'BUFFER_UPDATED', buffered: event.output.buffered })
-          ]
-        }
-      }
-    }
-  }
-});
-```
-
-**Server-Driven Composition Example**:
-
-```tsx
-// Server determines which actors to spawn based on content analysis
-// NOTE: This demonstrates the architectural concept - implementation
-// details may vary significantly from this XState-inspired example
-interface ServerContentAnalysis {
-  manifestType: 'hls' | 'dash';
-  hasMultipleRenditions: boolean;
-  requiresDRM: boolean;
-  hasSubtitles: boolean;
-  containerFormat: 'fmp4' | 'ts';
-  // Pre-processed data
-  initialManifest?: ParsedManifest;
-  initialRenditionSelection?: RenditionInfo;
-}
-
-const ComposablePlaybackEngine = setup({
-  types: {
-    context: {} as {
-      // Outward-facing state (maps to interface)
-      currentTime: number;
-      duration: number;
-      buffered: TimeRanges;
-      paused: boolean;
-      currentLevel: number;
-      levels: Level[];
-
-      // Server analysis results
-      contentAnalysis: ServerContentAnalysis;
-
-      // Actor references for communication
-      playlistParserRef?: ActorRefFrom<typeof PlaylistParsingActor>;
-      bufferManagerRef?: ActorRefFrom<typeof BufferManagementActor>;
-      abrLogicRef?: ActorRefFrom<typeof AdaptiveBitrateActor>;
-    },
-    events: {} as PlaybackEngineEvents,
-    input: {} as {
-      mediaElement: HTMLVideoElement;
-      contentAnalysis: ServerContentAnalysis;
-    }
-  },
-  actors: {
-    playlistParser: PlaylistParsingActor,
-    bufferManager: BufferManagementActor,
-    abrLogic: AdaptiveBitrateActor,
-    drmManager: DRMManagementActor,
-    subtitleManager: SubtitleManagementActor
-  }
-}).createMachine({
-  id: 'composable-playback-engine',
-  initial: 'initializing',
-  context: ({ input }) => ({
-    // Initialize outward-facing state
-    currentTime: 0,
-    duration: 0,
-    buffered: createTimeRanges([]),
-    paused: true,
-    currentLevel: 0,
-    levels: [],
-
-    // Server analysis
-    contentAnalysis: input.contentAnalysis
-  }),
-  states: {
-    initializing: {
-      entry: [
-        // Always spawn core actors
-        assign({
-          bufferManagerRef: ({ spawn }) => spawn('bufferManager')
-        }),
-
-        // Conditionally spawn based on server analysis
-        assign({
-          playlistParserRef: ({ spawn, context }) =>
-            context.contentAnalysis.initialManifest
-              ? undefined // No need to parse - already done server-side
-              : spawn('playlistParser'),
-
-          abrLogicRef: ({ spawn, context }) =>
-            context.contentAnalysis.hasMultipleRenditions
-              ? spawn('abrLogic')
-              : undefined,
-
-          // Only spawn DRM actor if content requires it
-          drmManagerRef: ({ spawn, context }) =>
-            context.contentAnalysis.requiresDRM
-              ? spawn('drmManager')
-              : undefined
-        }),
-
-        // If manifest was pre-processed, skip to ready state
-        choose([{
-          guard: ({ context }) => !!context.contentAnalysis.initialManifest,
-          actions: [
-            assign({
-              levels: ({ context }) => context.contentAnalysis.initialManifest!.levels,
-              duration: ({ context }) => context.contentAnalysis.initialManifest!.duration
-            }),
-            raise({ type: 'MANIFEST_READY' })
-          ]
-        }])
-      ],
-      on: {
-        MANIFEST_READY: 'ready',
-        LOAD_SOURCE: {
-          actions: sendTo(
-            ({ context }) => context.playlistParserRef!,
-            ({ event }) => ({ type: 'PARSE_MANIFEST', url: event.url })
-          )
-        }
-      }
-    },
-
-    ready: {
-      type: 'parallel',
-      states: {
-        playback: {
-          initial: 'paused',
-          states: {
-            paused: {
-              on: {
-                PLAY: {
-                  target: 'playing',
-                  actions: [
-                    assign({ paused: false }),
-                    // Notify outward interface
-                    emit({ type: 'playing' })
-                  ]
-                }
-              }
-            },
-            playing: {
-              // Handle time updates, seeking, etc.
-              on: {
-                PAUSE: {
-                  target: 'paused',
-                  actions: [
-                    assign({ paused: true }),
-                    emit({ type: 'pause' })
-                  ]
-                },
-                TIME_UPDATE: {
-                  actions: assign({
-                    currentTime: ({ event }) => event.time
-                  })
-                }
-              }
-            }
-          }
-        },
-
-        // Only active if ABR logic was spawned
-        adaptiveStreaming: {
-          initial: 'idle',
-          states: {
-            idle: {
-              on: {
-                LEVEL_SWITCH_REQUEST: {
-                  guard: ({ context }) => !!context.abrLogicRef,
-                  actions: sendTo(
-                    ({ context }) => context.abrLogicRef!,
-                    ({ event }) => ({ type: 'SELECT_LEVEL', level: event.level })
-                  )
-                }
-              }
-            }
-          }
-        }
-      },
-
-      // Hub-and-spoke event coordination
-      on: {
-        // Events from child actors update parent state
-        MANIFEST_PARSED: {
-          actions: assign({
-            levels: ({ event }) => event.manifest.levels,
-            duration: ({ event }) => event.manifest.duration
-          })
-        },
-        BUFFER_UPDATED: {
-          actions: assign({
-            buffered: ({ event }) => event.buffered
-          })
-        },
-        LEVEL_SWITCHED: {
-          actions: [
-            assign({ currentLevel: ({ event }) => event.level }),
-            emit({ type: 'levelLoaded', level: event.level })
-          ]
-        }
-      }
-    }
-  }
-});
-```
-
-**Server-Side Content Analysis Example**:
-
-```tsx
-// Server pre-processes content and determines client composition
-async function analyzeContentForClient(manifestUrl: string): Promise<ServerContentAnalysis> {
-  const manifest = await fetchAndParseManifest(manifestUrl);
-
-  return {
-    manifestType: detectManifestType(manifest),
-    hasMultipleRenditions: manifest.levels.length > 1,
-    requiresDRM: manifest.levels.some(level => level.encrypted),
-    hasSubtitles: manifest.subtitleTracks.length > 0,
-    containerFormat: detectContainerFormat(manifest),
-
-    // Pre-processed data reduces client work
-    initialManifest: manifest,
-    initialRenditionSelection: selectInitialRendition(manifest, clientHints)
-  };
-}
-
-// Client receives optimized bundle + analysis
-const contentAnalysis = await analyzeContentForClient('/playlist.m3u8');
-const engine = createActor(ComposablePlaybackEngine, {
-  input: { mediaElement, contentAnalysis }
-});
-```
-
-**Key Architectural Benefits of This Approach**:
-
-1. **Functional Composition**: Each unit encapsulates pure functions while a coordination layer manages interactions
-2. **Selective Composition**: Server analysis could determine which functional units to include
-3. **Event-Driven Communication**: Hub-and-spoke pattern via parent coordinator prevents tight coupling
-4. **Server Optimization**: Pre-processing could eliminate client-side work and code
-5. **Declarative State Management**: State machine patterns could replace imperative “Controller” architectures
-6. **Testable Units**: Each functional unit can be tested in isolation
-
-# Dimensions of Playback Engine Requirements
-
-Understanding what determines playback engine functionality helps explain why composable architecture is necessary. Rather than building one system that handles all permutations (the “Swiss Army knife” problem, also a bit of the “lowest common denominator” problem in this context), composable architecture allows selective optimization across multiple dimensions:
-
-## 1. Media Content Characteristics
-
-### Protocol and Standards
-
-- **Streaming Protocols**: HLS vs DASH vs MoQ vs progressive download
-- **Stream Types**: VOD vs live vs low-latency live vs DVR/EVENT
-- **Container Formats**: fMP4/CMAF vs MPEG-TS vs Matroska/WebM
-- **Codecs**: H.264/HEVC, AAC, VP9, AV1, etc.
-
-### Content Complexity
-
-- **Track Variations**: Video-only, audio-only, multi-track audio, subtitles/captions
-- **Adaptive Features**: Multiple bitrates/resolutions vs single rendition
-- **Content Security**: Clear vs encrypted vs DRM (Widevine/FairPlay/PlayReady)
-- **Content Structure**: Simple linear vs stitched content vs multi-cam vs interstitials
-- **Metadata Integration**: ID3, IMSC/TTML, CEA-608 text tracks, externally linked data
-
-## 2. Playback Environment
-
-### Runtime Platform
-
-- **Media APIs**: MediaSource vs ManagedMediaSource vs native playback
-- **Processing Context**: Main thread vs Web Workers vs WASM vs Service Workers
-- **Network Layer**: XHR vs fetch vs ReadableStream vs WebTransport
-- **Advanced APIs**: WebCodecs, Web Audio API, Screen API
-
-### Platform Constraints
-
-- **Device Capabilities**: Mobile vs desktop, memory/CPU limitations
-- **Browser Support**: Modern vs legacy browser feature sets
-- **Framework Context**: Server-side rendering vs client-only vs edge computing
-
-## 3. Desired Usage and Functionality
-
-### Playback Engine Requirements
-
-- **Interaction Models**:
-  - Background/ambient playback (no seeking, minimal buffering)
-  - Interactive playback (seeking, scrubbing, time-based navigation)
-  - Backgrounding/foregrounding playback
-- **Playback Patterns:**
-  - Audio-only playback (no video processing pipeline)
-  - Single media playback
-  - Playlist/sequential playback (shared buffer management)
-  - Player pools (multiple engine instances, resource sharing)
-  - Continuous stitching (single MediaSource, multiple sources)
-- **Content Lifecycle**:
-  - Short-form/ephemeral content (TikTok-style, minimal buffering)
-  - Long-form/persistent content (extensive buffering, gap handling)
-  - Live streaming (sliding window, latency management)
-
-### Performance Priorities
-
-- **Startup Optimization**: Time to first frame vs bandwidth efficiency
-- **Memory Management**: Buffer strategies, garbage collection, resource cleanup
-- **Error Recovery**: Retry strategies, failover logic, segment recovery
-
-## 4. Computational Distribution
-
-### Server-Side Pre-processing
-
-- **Content Analysis**: Manifest parsing, capability detection, optimization hints
-- **Data Pre-computation**: Rendition selection, buffer strategies, feature requirements
-- **Bundle Optimization**: Code splitting based on actual content needs
-
-### Client-Side Optimization
-
-- **Selective Loading**: Include only required functionality
-- **Runtime Adaptation**: Dynamic feature activation based on conditions
-- **Edge Computing**: CDN-level processing and optimization
-
-## The Multiplicative Complexity Problem
-
-Each dimension creates **multiplicative complexity** - a playback engine that attempts to handle all permutations becomes the monolithic “Swiss Army knife” architecture that our composable approach aims to replace.
-
-**Traditional Approach:** Build one engine that handles every combination
-
-- Results in large, complex codebases where features are diffused throughout
-- Impossible to remove unused functionality
-- One-size-fits-all optimization that optimizes for no specific case
-
-**Composable Approach:** Selective optimization across dimensions
-
-- **Media Content** determines which parsing/processing functions are needed
-- **Playback Environment** determines which APIs and runtime strategies to use
-- **Desired Usage** determines which interaction and lifecycle patterns to include
-- **Computational Distribution** determines what happens server-side vs client-side
-
-This multidimensional approach enables the server-side content analysis and conditional composition patterns described in the implementation sections.
-
-# Implementation Architecture
-
-## 1. Functional Core Design
-
-### Pure Functions Wherever Possible
-
-```jsx
-// Instead of:
-PlaylistManager.updatePlaylist(newData);
-// Use:
-const updatedState = updatePlaylist(currentState, newData);
-```
-
-### **State Management**
-
-- Immutable state updates
-- Well-defined state shape
-- Clear dependency injection for side effects
-- Event-driven communication between units before or after functional transitions
-
-### Avoid Legacy Patterns
-
-- No “Managers” or “Controllers” with implicit dependencies
-- No shared mutable state between components
-- No circular dependencies
-
-## 2. Compositional API Design
-
-### Use Case Based Composition
-
-```jsx
-// NOTE: This is "by way of example" and not a hard requirement of design
-// Background looping video
-const backgroundPlayer = createPlayer({
-  features: [
-    'hls-parsing',
-    'single-rendition',
-    'loop-optimization'
-  ],
-  exclude: [
-    'audio-support',
-    'seek-controls',
-    'live-streaming',
-    'drm',
-    'subtitles'
-  ]
-});
-
-// Full-featured streaming
-const fullPlayer = createPlayer({
-  features: [
-    'hls-parsing',
-    'adaptive-bitrate',
-    'live-streaming',
-    'drm-support',
-    'multi-audio',
-    'subtitles'
-  ]
-});
-```
-
-## 3. Server-Side Content Analysis
-
-### **Manifest Pre-processing**
-
-```jsx
-// Server-side analysis determines client requirements
-const contentAnalysis = await analyzeHLSManifest(playlistUrl);
-const requiredFeatures = determineFeatures(contentAnalysis);
-const optimizedBundle = buildClientBundle(requiredFeatures);
-```
-
-### Examples of Server-Side Optimization
-
-- **Single Rendition Detection**: Omit ABR logic entirely
-- **Container Format Analysis**: Include only fMP4 OR transport stream handling
-- **DRM Requirements**: Include encryption handling only when needed
-- **Subtitle Detection**: Skip text track parsing when no captions exist
-- **Live vs VOD**: Exclude live-specific buffering and timing logic for VOD
-
-## 4. Framework Integration Patterns
-
-### Modern Framework Support
-
-```jsx
-// React integration
-function VideoPlayer({ src, features }) {
-  const playerState = usePlaybackEngine({ src, features });
-  // eslint-disable-next-line jsx-a11y/media-has-caption
-  return <video ref={playerState.mediaRef} {...playerState.attributes} />;
-}
-
-// Vue composition API
-// eslint-disable-next-line react-hooks/rules-of-hooks
-const { playerState, controls } = usePlaybackEngine(src, options);
-
-// Svelte reactive integration
-$: player = createPlayer(src, $dynamicFeatures);
-```
-
-### Traditional Integration
-
-```jsx
-// Still support imperative APIs when needed
-const player = new ComposablePlayer(element, {
-  src: 'playlist.m3u8',
-  features: ['adaptive-streaming', 'subtitles']
-});
-```
-
-# Implementation Roadmap
-
-## Phase 1: Stable Outward Interface + Pragmatic Internal Foundation
-
-The primary goal of Phase 1 is to establish a **stable, well-defined outward interface** while building internal functionality using pragmatic patterns that align with our architectural principles without over-engineering the coordination system.
-
-### Outward Interface Stabilization
-
-- [ ] **Core Interface Definition**
-  - [ ] Finalize TypeScript interface extending EventTarget + HTMLMediaElement subset
-  - [ ] Define media-specific extensions (levels, tracks, etc.) with clear provisional status
-  - [ ] Establish event contracts and naming conventions
-  - [ ] Create comprehensive interface documentation
-- [ ] **Basic Integration Adapters**
-  - [ ] Web Components wrapper (following mux-background-video pattern)
-  - [ ] Simple React hook for state synchronization
-  - [ ] Basic imperative API for direct usage
-  - [ ] Framework-agnostic usage examples
-
-### Internal Building Blocks (Pragmatic Approach)
-
-Following the [**mux-background-video**](https://github.com/muxinc/mux-background-video) model, focus on creating pure, composable functions that can be “passed in” to core coordination logic:
-
-- [ ] **Pure Function Foundation**
-
-  ```tsx
-  // Example: Pure playlist parsing functionsconst parseHLSManifest = (manifestText: string): ParsedManifest => { /* pure */ }
-  function selectInitialRendition(manifest: ParsedManifest, hints: ClientHints): Rendition { /* pure */ }
-  function determineBufferStrategy(contentType: string, useCase: string): BufferConfig { /* pure */ }
-  ```
-
-- [ ] **Pluggable Function Architecture**
-
-  ```tsx
-  // Functions can be passed in rather than hard-coded
-  interface PlaybackEngineConfig {
-    parseManifest: (text: string) => ParsedManifest;
-    selectRendition: (manifest: ParsedManifest) => Rendition;
-    processSegment: (segment: ArrayBuffer) => ProcessedSegment;
-    // Start simple - don't over-architect coordination
-  }
-  ```
-
-- [ ] **Simple State Management**
-
-  ```tsx
-  // Pure state updates, avoid complex state machines initially
-  interface PlaybackState {
-    currentTime: number;
-    duration: number;
-    buffered: TimeRanges;
-    manifest?: ParsedManifest;
-    currentRendition?: Rendition;
-  }
-  // Pure reducer pattern
-  function updatePlaybackState(state: PlaybackState, action: StateAction): PlaybackState {
-    // Immutable updates, no side effects
-  }
-  ```
-
-### Minimal Viable Coordination
-
-Start with simple, direct coordination rather than complex actor systems:
-
-- [ ] **Basic Event-Driven Core**
-
-  ```tsx
-  class PlaybackEngineCore {
-    constructor(
-      private config: PlaybackEngineConfig,
-      private mediaElement: HTMLVideoElement,
-    ) {}
-
-    // Simple method calls to pluggable functions
-    private async loadManifest(url: string) {
-      const text = await fetch(url).then(r => r.text());
-      // Pure function call
-      const manifest = this.config.parseManifest(text);
-      this.updateState({ manifest });
-    }
-  }
-  ```
-
-- [ ] **Use Case Specific Configurations**
-
-  ```tsx
-  // Background video configuration (like mux-background-video)
-  const backgroundVideoConfig = {
-    parseManifest: parseHLSManifest,
-    selectRendition: manifest => selectLowestBandwidth(manifest), // No ABR needed
-    processSegment: processFMP4Segment, // Assume fMP4, skip TS transmuxing
-  };
-  // Full streaming configuration
-  const streamingConfig = {
-    parseManifest: parseHLSManifest,
-    selectRendition: selectAdaptiveRendition,
-    processSegment: detectContainerAndProcess, // Handle both fMP4 and TS
-  };
-  ```
-
-## Validation Criteria for Phase 1
-
-### Interface Stability:
-
-- [ ] Outward interface works consistently across multiple integration patterns
-- [ ] Event contracts remain (relatively) stable as internal implementation evolves
-- [ ] TypeScript types provide good developer experience
-
-### Internal Flexibility:
-
-- [ ] Core functions can be swapped without changing coordination logic
-- [ ] New use cases can be supported by providing different function configurations
-- [ ] State updates remain predictable and testable
-
-### Practical Functionality:
-
-- [ ] Basic HLS playback works end-to-end
-- [ ] Simple use cases (like background video) require minimal configuration
-- [ ] Foundation supports multiple integration patterns without architectural changes
-
-## Future Phases (Refined Based on Phase 1 Learnings)
-
-**Phase 2**: Server-side content analysis and dynamic function composition
-
-**Phase 3**: Advanced coordination patterns (informed by Phase 1 practical experience)
-
-**Phase 4**: Specialized optimizations and advanced features
-
-## Key Architectural Principles for Phase 1
-
-1. **“Don’t Let Perfect Be the Enemy of Good”**: Start with working functionality, refine architecture iteratively
-2. **Pure Functions First**: Break functionality into testable, composable pure functions
-3. **Pluggable by Design**: Functions are injected rather than hard-coded, enabling easy customization
-4. **Stable Outward Contract**: Interface remains consistent even as internal implementation evolves
-5. **Use Case Driven**: Prove the architecture with real scenarios (background video, basic streaming, etc.)
-
-This approach mirrors the **mux-background-video** philosophy: solve real problems with clean, composable code while keeping the door open for architectural improvements based on practical experience.
-
-## Technical Specifications
-
-None of these are set in stone, and the actual code implementations certainly are not. They are instead plausible candidates for functional/compositional building blocks and groupings of behaviors.
-
-### Compositional Units
-
-**Playlist Parsing**:
-
-```jsx
-// Composed of smaller units
-PlaylistParsing = compose([
-  MultivariantPlaylistParsing,
-  MediaPlaylistParsing,
-  TagParsing,
-  AttributeParsing
-]);
-```
-
-**Segment Processing**:
-
-```jsx
-// Conditional composition based on content
-const segmentProcessor = contentAnalysis.containerType === 'fmp4'
-  ? createFMP4Processor()
-  : createTransportStreamProcessor();
-```
-
-**Buffer Management**:
-
-```jsx
-// Use case specific optimization
-const bufferStrategy = useCase === 'background-loop'
-  ? createLoopOptimizedBuffer()
-  : createStandardBuffer();
-```
-
-### State Architecture
-
-**State Shape Example**:
-
-```jsx
-const playbackState = {
-  // Media state
-  currentTime: 0,
-  duration: 0,
-  buffered: TimeRanges,
-  // Playlist state
-  currentLevel: 0,
-  availableLevels: [],
-  // Loading state
-  loading: false,
-  error: null,
-  // Feature flags
-};
-```
-
-# Benefits & Outcomes
-
-## Performance Improvements
-
-- **Bundle Size**: 50-80% reduction for focused use cases
-- **Startup Time**: Faster initial load, no unused code parsing
-- **Core Web Vitals**: Better TTI and LCP scores
-- **Memory Usage**: Lower runtime footprint
-
-## Developer Experience
-
-- **Framework Integration**: Natural fit with React/Vue/Svelte patterns
-- **Customization**: Easy to modify behavior without forking
-- **Testing**: Isolated units are easier to test
-- **Debugging**: Clear separation of concerns aids troubleshooting
-
-## Business Value
-
-- **Cost Optimization**: Reduced bandwidth and CDN costs
-- **User Experience**: Better page performance + video QoE
-- **Development Velocity**: Faster iteration on new features
-- **Maintenance**: Easier to update and extend
-
-# Migration and Adoption Strategy
-
-The outward/inward separation enables flexible adoption without requiring complete rewrites.
-
-## Decision Framework
-
-**1. Analyze your requirements** against the Dimensions of Playback Engine Requirements above.
-
-**2. If the composable architecture covers your needs:** Use the Phase 1 approach with pure functions and pluggable configuration.
-
-**3. If your requirements exceed current support:** Wrap existing engines (hls.js, dash.js, shaka-player) to conform to the composable interface while maintaining full functionality.
-
-**4. If some of your use cases can use (2) and others require (3):** Use simple routing logic to direct supported cases to the composable engine and complex cases to wrapped engines.
-
-**5. For existing applications:** Incrementally migrate integration points to use the composable interface while preserving functionality through wrapper strategies.
-
-**6. Regardless of approach:** You can build individual pure functions using composable principles and contribute them back to existing engines or use in your forks.
-
-# Call to Action
-
-The composable playback engine architecture solves fundamental problems in video delivery while unlocking new possibilities for optimization and integration. Implementation should begin with core infrastructure, focusing on functional composition and state management primitives.
-
-**Next Steps**:
-
-1. Review existing codebases for composable patterns
-2. Identify first use case for prototype (possible candidate: single-rendition VOD or https://github.com/muxinc/mux-background-video or similar)
-3. Design state management system
-4. Build playlist parsing as first composable module
-5. Validate performance improvements with real-world testing
-
-This architecture represents the future of web video delivery—one that doesn’t force compromises between application performance and media quality of experience.