diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b8300e98..1cb3c30b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -20,26 +20,27 @@ This document describes VJS-10's **architectural principles and patterns**, not ## Overview -VJS-10 represents a significant architectural evolution in media player component libraries, prioritizing 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. +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. ## Architectural Influences & Inspirations ### Media Elements: Platform-Agnostic HTMLMediaElement Contract -VJS-10's media state management architecture draws significant inspiration from the [media-elements monorepo](https://github.com/muxinc/media-elements), which pioneered the concept of creating HTMLMediaElement-compatible elements that work across different media providers while maintaining consistent interfaces. +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. #### 1. Extended HTMLMediaElement Contract Foundation -**Media Elements Innovation**: 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.). +**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 HTMLVideoElement -export class CustomVideoElement extends HTMLVideoElement implements HTMLVideoElement { - readonly nativeEl: HTMLVideoElement; +// 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 - // Maintains HTMLMediaElement contract + // Proxies HTMLMediaElement properties to wrapped native element get currentTime() { return this.nativeEl?.currentTime ?? 0; } set currentTime(val) { if (this.nativeEl) this.nativeEl.currentTime = val; } @@ -55,7 +56,7 @@ class HlsVideoElement extends CustomVideoElement { if (Hls.isSupported()) { this.api = new Hls(this.config); this.api.loadSource(this.src); - this.api.attachMedia(this.nativeEl); + this.api.attachMedia(this.nativeEl); // Native video wrapped in shadow DOM } } } @@ -63,8 +64,9 @@ class HlsVideoElement extends CustomVideoElement { **Key Architectural Assumptions**: -- Media state owner must be an `HTMLElement` (DOM-based) -- Must implement the complete `HTMLMediaElement` interface +- Must extend `HTMLElement` (Safari limitation prevents extending built-in elements) +- Wraps native `