@smartimpact-it/modern-video-embed 2.0.5 → 2.0.7

package/README.md

@@ -1,6 +1,16 @@
 # Video Embed Components
 
-Modern, performant YouTube and Vimeo embed web components with lazy loading, event-driven architecture, and comprehensive API control.
+Modern, performant YouTube, Vimeo, and HTML5 video embed web components with lazy loading, event-driven architecture, and comprehensive API control.
+
+## 📋 Quick Reference
+
+| Component         | Best For           | Bundle Size (Min) | External API       |
+| ----------------- | ------------------ | ----------------- | ------------------ |
+| `<youtube-embed>` | YouTube videos     | 15KB              | YouTube iframe API |
+| `<vimeo-embed>`   | Vimeo videos       | 14KB              | Vimeo Player API   |
+| `<video-embed>`   | Self-hosted videos | 12KB              | Native HTML5       |
+
+**Need help?** See [AI Instructions](.ai-instructions.md) for development guidance.
 
 ## ✨ Features
 
@@ -11,9 +21,43 @@ Modern, performant YouTube and Vimeo embed web components with lazy loading, eve
 - **📱 Responsive** - Mobile-first design with touch-friendly controls
 - **♿ Accessible** - Keyboard navigation and screen reader support
 - **🎨 Customizable** - Custom overlay controls or native player controls
-- **🎬 Multi-Platform** - Both YouTube and Vimeo support
+- **🎬 Multi-Platform** - YouTube, Vimeo, and self-hosted HTML5 video support
 
-## 🚀 Quick Start
+## � Project Structure
+
+```
+si_video_embed/
+├── src/
+│   ├── components/          # Web Components
+│   │   ├── BaseVideoEmbed.ts       # Abstract base class (shared functionality)
+│   │   ├── YouTubeEmbed.ts         # YouTube iframe component
+│   │   ├── VimeoEmbed.ts           # Vimeo iframe component
+│   │   └── VideoEmbed.ts           # Native HTML5 video component
+│   ├── types/               # TypeScript type definitions
+│   └── styles/              # SCSS stylesheets
+│       ├── _shared-functions.scss  # Reusable SVG encoding functions
+│       ├── _embed-base.scss        # Shared component mixins
+│       ├── youtube-embed.scss      # YouTube-specific styles
+│       ├── vimeo-embed.scss        # Vimeo-specific styles
+│       └── video-embed.scss        # Video-specific styles
+├── dist/                    # Compiled output (auto-generated)
+│   ├── index.js/.min.js     # Full bundle (YouTube + Vimeo + Video)
+│   ├── youtube-only.js      # YouTube-only bundle (15KB min)
+│   ├── vimeo-only.js        # Vimeo-only bundle (14KB min)
+│   ├── video-only.js        # Native video-only bundle (12KB min)
+│   └── css/                 # Compiled styles
+├── examples/                # Live demos and usage examples
+├── test/                    # Automated test suite (67+ tests)
+└── scripts/                 # Build validation and cache-busting scripts
+```
+
+**Key Files:**
+
+- `.ai-instructions.md` - Development guide for AI agents and contributors
+- `package.json` - NPM scripts and dependencies
+- `tsconfig.json` - TypeScript configuration (strict mode)
+
+## �🚀 Quick Start
 
 ### Installation
 
@@ -25,14 +69,16 @@ npm install @smartimpact-it/modern-video-embed
 
 #### Via CDN (for quick prototypes)
 
-```html
-<script
-  type="module"
-  src="https://unpkg.com/@smartimpact-it/modern-video-embed@latest/dist/index.js"
-></script>
-<link
-  rel="stylesheet"
-  href="https://unpkg.com/@smartimpact-it/modern-video-embed@latest/dist/css/components.css"
+```html |
+| ----------------- | ------------------------- | ---------- | ----------- |
+----------------------- | | **Full** | `dist/index.js` | 58KB | **29KB** | All
+three components | | **YouTube Only** | `dist/youtube-only.js` | 29KB | **15KB**
+| Only YouTube embeds | | **Vimeo Only** | `dist/vimeo-only.js` | 29KB |
+**14KB** | Only Vimeo embeds | | **Video Only** | `dist/video-only.js` | 24KB |
+**12KB** | Only HTML5 video embeds | | **Styles (Core)** |
+`dist/css/components.css` | 9KB | **7KB** | Component styles only | | **Styles
+(Full)** | `dist/css/main.css` | 276KB | **224KB** | With Bootstrap (demos)
+href="https://unpkg.com/@smartimpact-it/modern-video-embed@latest/dist/css/components.css"
 />
 ```
 
@@ -126,6 +172,20 @@ Choose the right bundle for your needs:
 <vimeo-embed url="https://vimeo.com/76979871" controls> </vimeo-embed>
 ```
 
+# HTML5 Video (Self-hosted)
+
+```html
+<!-- Use in HTML with self-hosted videos -->
+<video-embed
+  url="https://example.com/videos/demo.mp4"
+  controls
+  poster="thumbnail.jpg"
+>
+</video-embed>
+```
+
+###
+
 ### Advanced Usage
 
 #### YouTube
@@ -144,17 +204,34 @@ Choose the right bundle for your needs:
 
 #### Vimeo
 
-```html
+````html
 <!-- Lazy loading with custom poster -->
 <vimeo-embed
-  video-id="123456789"
+  ## HTML5 Video
+
+```html
+<!-- Self-hostedAll Components)
+
+| Attribute     | Type    | YouTube | Vimeo | Video | Description                                  |
+| ------------- | ------- | ------- | ----- | ----- | -------------------------------------------- |
+| `url`         | String  | ✅      | ✅    | ✅    | Full video URL                               |
+| `video-id`    | String  | ✅      | ✅    | ❌    | Video ID (YouTube: 11 chars, Vimeo: numeric) |
+| `autoplay`    | Boolean | ✅      | ✅    | ✅    | Auto-play video when loaded                  |
+| `controls`    | Boolean | ✅      | ✅    | ✅    | Show native player controls                  |
+| `lazy`        | Boolean | ✅      | ✅    | ✅    | Enable lazy loading with poster              |
+| `muted`       | Boolean | ✅      | ✅    | ✅    | Start video muted                            |
+| `poster`      | String  | ✅      | ✅    | ✅    | Custom poster image URL                      |
+| `background`  | Boolean | ✅      | ✅    | ✅    | Enable background video mode                 |
+| `player-vars` | JSON    | ✅      | ✅    | ❌    | JSON object of extra player parameters       |
+| `loop`        | Boolean | ❌      | ❌    | ✅    | Loop video (native video only)               |
+| `preload`     | String  | ❌      | ❌    | ✅    | Preload strategy: "none", "metadata", "auto"
   lazy
   autoplay
   muted
   poster="custom-poster.jpg"
 >
 </vimeo-embed>
-```
+````
 
 ## 📖 API Reference
 
@@ -179,16 +256,25 @@ Choose the right bundle for your needs:
 ```javascript
 const embed = document.querySelector("youtube-embed");
 
-// Playback control
-embed.play(); // ▶️ Play video
-embed.pause(); // ⏸️ Pause video
-embed.stopVideo(); // ⏹️ Stop video
+// Playback control (wraps YouTube IFrame API Player methods)
+// Reference: https://developers.google.com/youtube/iframe_api_reference#Playback_controls
+embed.play(); // ▶️ Play video (calls playVideo())
+embed.pause(); // ⏸️ Pause video (calls pauseVideo())
+embed.stopVideo(); // ⏹️ Stop video (calls stopVideo())
 embed.togglePlay(); // ⏯️ Toggle play/pause
 
 // Audio control
-embed.mute(); // 🔇 Mute audio
-embed.unmute(); // 🔊 Unmute audio
+// Reference: https://developers.google.com/youtube/iframe_api_reference#Playback_volume
+embed.mute(); // 🔇 Mute audio (calls mute())
+embed.unmute(); // 🔊 Unmute audio (calls unMute())
 embed.toggleMute(); // 🔇 Toggle mute
+const isMuted = embed.isMuted(); // Check if muted (calls isMuted())
+
+// Playback time control
+// Reference: https://developers.google.com/youtube/iframe_api_reference#Playback_status
+const currentTime = embed.getCurrentTime(); // Get current time in seconds (calls getCurrentTime())
+embed.seekTo(30); // Seek to 30 seconds (calls seekTo())
+embed.currentTime = 45; // Seek to 45 seconds using property setter
 
 // Video management
 embed.loadVideo("dQw4w9WgXcQ"); // Load by video ID
@@ -198,10 +284,12 @@ embed.loadVideo("https://youtu.be/dQw4w9WgXcQ"); // Load by URL
 const state = embed.getPlayerState();
 // Returns: { playing: boolean, muted: boolean, videoId: string, ready: boolean, initialized: boolean }
 
-// Quality control
-const qualities = embed.getAvailableQualities(); // Get available quality levels
-const current = embed.getCurrentQuality(); // Get current quality
-embed.setQuality("hd1080"); // Set quality to 1080p
+// Quality control (DEPRECATED as of October 2019 - YouTube controls quality automatically)
+// Reference: https://developers.google.com/youtube/iframe_api_reference#Playback_quality
+// WARNING: These methods are NO-OPS and have no effect on YouTube videos
+const qualities = embed.getAvailableQualities(); // ⚠️ DEPRECATED - Returns empty array
+const current = embed.getCurrentQuality(); // ⚠️ DEPRECATED - Returns "auto"
+embed.setQuality("hd1080"); // ⚠️ DEPRECATED - Does nothing (no-op function)
 
 // Fullscreen control
 embed.enterFullscreen(); // Enter fullscreen mode
@@ -210,12 +298,15 @@ embed.toggleFullscreen(); // Toggle fullscreen
 const isFs = embed.isFullscreen(); // Check fullscreen state
 
 // Set extra player parameters
+// Reference: https://developers.google.com/youtube/player_parameters
 embed.playerVars = { loop: 1, playlist: "dQw4w9WgXcQ" };
 ```
 
 **Passing Extra Parameters:**
 
-You can pass additional parameters to the YouTube or Vimeo player using the `player-vars` attribute or `playerVars` property:
+You can pass additional parameters to the YouTube or Vimeo player using the `player-vars` attribute or `playerVars` property.
+
+For YouTube, see the [YouTube Player Parameters Reference](https://developers.google.com/youtube/player_parameters) for all available options.
 
 ```html
 <!-- YouTube: Loop a video -->
@@ -289,7 +380,7 @@ const isFs = embed.isFullscreen(); // Check fullscreen state
 
 You can pass additional parameters to the Vimeo player using the `player-vars` attribute or `playerVars` property:
 
-```html
+````html
 <!-- Vimeo: Loop a video -->
 <vimeo-embed video-id="76979871" player-vars='{"loop": true}'></vimeo-embed>
 
@@ -304,7 +395,57 @@ You can pass additional parameters to the Vimeo player using the `player-vars` a
   video-id="76979871"
   player-vars='{"dnt": true, "title": false, "byline": false, "portrait": false}'
 ></vimeo-embed>
-```
+```# Video Embed (HTML5) All three components support the same event interface:
+```javascript // Listen to player events (works for youtube-embed, vimeo-embed,
+and video-embed) embed.addEventListener("ready", () => console.log("Player
+ready")); embed.addEventListener("play", () => console.log("Playing"));
+embed.addEventListener("pause", () => console.log("Paused"));
+embed.addEventListener("ended", () => console.log("Video ended"));
+embed.addEventListener("error", (e) => console.error("Error:", e.detail));
+embed.addEventListener("qualitychange", (e) => { console.log( "Quality
+changed:", e.detail.oldQuality, "→", e.detail.newQuality, );
+console.log("Available qualities:", e.detail.availableQualities); });
+````
+
+**Supported Events:**
+
+- `ready` - Player initialized and ready to use (wraps YouTube's [`onReady`](https://developers.google.com/youtube/iframe_api_reference#onReady))
+- `play` - Video playback started (wraps YouTube's [`onStateChange`](https://developers.google.com/youtube/iframe_api_reference#onStateChange) with state `YT.PlayerState.PLAYING`)
+- `pause` - Video playback paused (wraps `onStateChange` with state `YT.PlayerState.PAUSED`)
+- `stop` - Video playback stopped
+- `ended` - Video playback finished (wraps `onStateChange` with state `YT.PlayerState.ENDED`)
+- `error` - An error occurred (wraps YouTube's [`onError`](https://developers.google.com/youtube/iframe_api_reference#onError), check `event.detail` for details)
+- `timeupdate` - Current time position updated
+- `qualitychange` - Video quality level changed (wraps YouTube's [`onPlaybackQualityChange`](https://developers.google.com/youtube/iframe_api_reference#onPlaybackQualityChange))
+- `loadstart` - Video loading started (native video)
+- `connected` - Component connected to DOM
+- `disconnected` - Component disconnected from DOMst state = embed.getPlayerState();
+  // Returns: { playing: boolean, muted: boolean, videoId: string, ready: boolean, initialized: boolean }
+
+const currentTime = embed.getCurrentTime();
+const isMuted = embed.isMuted();
+
+// Native video attributes
+embed.loop = true; // Enable looping
+embed.preload = "metadata"; // Set preload strategy
+
+````
+
+**Native HTML5 Video Attributes:**
+
+```html
+<!-- HTML5-specific attributes -->
+<video-embed
+  url="video.mp4"
+  loop
+  preload="metadata"
+  controls
+  poster="thumb.jpg"
+>
+</video-embed>
+````
+
+###
 
 ```javascript
 // Set via JavaScript
@@ -347,7 +488,13 @@ embed.addEventListener("qualitychange", (e) => {
 
 Both components support programmatic quality control and emit events when quality changes.
 
-#### YouTube Quality Levels
+**⚠️ IMPORTANT: YouTube Quality APIs Deprecated (October 2019)**
+
+YouTube deprecated manual quality control methods as of October 24, 2019. The quality methods for YouTube (`getAvailableQualities()`, `getCurrentQuality()`, `setQuality()`) are **no-op functions** that have no effect. YouTube now automatically adjusts quality based on network conditions. See the [YouTube Help Center](https://support.google.com/youtube/answer/91449) for details.
+
+**Use Vimeo or HTML5 Video if you need manual quality control.**
+
+#### YouTube Quality Levels (Reference Only - APIs Deprecated)
 
 | Quality Level | Resolution | Description         |
 | ------------- | ---------- | ------------------- |
@@ -379,18 +526,20 @@ Both components support programmatic quality control and emit events when qualit
 
 ```html
 <!-- Set initial quality via attribute -->
+<!-- WARNING: YouTube quality attribute is ignored (APIs deprecated Oct 2019) -->
 <youtube-embed video-id="dQw4w9WgXcQ" quality="hd1080"></youtube-embed>
+<!-- Vimeo quality control works normally -->
 <vimeo-embed video-id="76979871" quality="720p"></vimeo-embed>
 ```
 
 ```javascript
-// YouTube quality control
+// YouTube quality control (DEPRECATED - These are no-op functions)
 const ytEmbed = document.querySelector("youtube-embed");
-const qualities = ytEmbed.getAvailableQualities(); // ["auto", "hd1080", "hd720", "large", "medium"]
-const current = ytEmbed.getCurrentQuality(); // "hd720"
-ytEmbed.setQuality("hd1080"); // Switch to 1080p
+const qualities = ytEmbed.getAvailableQualities(); // ⚠️ Returns empty array - DEPRECATED
+const current = ytEmbed.getCurrentQuality(); // ⚠️ Returns "auto" - DEPRECATED
+ytEmbed.setQuality("hd1080"); // ⚠️ Does nothing - DEPRECATED (no-op)
 
-// Vimeo quality control (async)
+// Vimeo quality control (Works normally - async)
 const vimeoEmbed = document.querySelector("vimeo-embed");
 const qualities = await vimeoEmbed.getAvailableQualities(); // ["auto", "1080p", "720p", "540p"]
 const current = await vimeoEmbed.getCurrentQuality(); // "720p"
@@ -407,6 +556,32 @@ embed.addEventListener("qualitychange", (event) => {
 });
 ```
 
+**⚠️ CRITICAL: YouTube Quality Control APIs Are DEPRECATED (October 2019)**
+
+As of **October 24, 2019**, YouTube deprecated all manual quality control functions. According to the [official documentation update](https://developers.google.com/youtube/iframe_api_reference#Revision_History):
+
+**These methods are NO LONGER FUNCTIONAL:**
+
+- [`getPlaybackQuality()`](https://developers.google.com/youtube/iframe_api_reference#getPlaybackQuality) - No longer returns accurate quality information
+- [`setPlaybackQuality()`](https://developers.google.com/youtube/iframe_api_reference#setPlaybackQuality) - **No-op function** (does nothing)
+- [`getAvailableQualityLevels()`](https://developers.google.com/youtube/iframe_api_reference#getAvailableQualityLevels) - No longer returns quality options
+
+**Why these were deprecated:**
+YouTube now automatically adjusts video quality based on viewing conditions (network bandwidth, device capabilities, viewport size) to provide the best viewing experience. Manual quality selection interferes with YouTube's adaptive streaming algorithms.
+
+**What still works:**
+
+- [`onPlaybackQualityChange`](https://developers.google.com/youtube/iframe_api_reference#onPlaybackQualityChange) event - Still fires when YouTube automatically changes quality
+- The `qualitychange` event in this library still works and reports YouTube's automatic quality changes
+
+**For developers:**
+The quality methods (`getAvailableQualities()`, `getCurrentQuality()`, `setQuality()`) are kept in this library for API compatibility but **have no effect** on YouTube videos. They are maintained only to prevent breaking existing code. Use the Vimeo or native HTML5 video components if manual quality control is required.
+
+**Official YouTube Help Article:**
+[Why does YouTube adjust video quality?](https://support.google.com/youtube/answer/91449)
+
+Vimeo's quality control is more reliable and respects quality changes consistently.
+
 ### Error Handling
 
 Components include comprehensive error handling with automatic retry and user-friendly feedback:
@@ -430,12 +605,20 @@ embed.addEventListener("error", (e) => {
 
 #### Common Error Scenarios
 
-| Error Type           | Cause                      | Solution                             |
-| -------------------- | -------------------------- | ------------------------------------ |
-| API Load Timeout     | Ad blocker or slow network | Disable ad blocker, check connection |
-| Script Load Failed   | Network issue or CORS      | Verify internet connection           |
-| Video Not Found      | Invalid video ID           | Check video ID/URL                   |
-| Embedding Restricted | Video owner restrictions   | Use different video                  |
+| Error Type         | Cause                      | Solution                             |
+| ------------------ | -------------------------- | ------------------------------------ |
+| API Load Timeout   | Ad blocker or slow network | Disable ad blocker, check connection |
+| Script Load Failed | Network issue or CORS      | Verify internet connection           |
+| Video Not Found    | Invalid video ID           | Check video ID/URL                   |
+
+| EmHTML5 Video Demos:\*\*
+
+- `video-basic-demo.html` - Self-hosted video usage
+- `video-lazy-loading-demo.html` - Native video lazy loading
+- `video-background-demo.html` - Background video patterns
+- **`platform-comparison-demo.html`** - Side-by-side platform comparison
+- **`quality-control-demo.html`** - Quality selection and switching
+- **`fullscreen-accessibility-demo.html`** - Fullscreen and accessibility featureso |
 
 ### Accessibility
 
@@ -551,9 +734,26 @@ This component includes a comprehensive automated test suite to ensure reliabili
 
 - Initialization speed benchmarks (< 200ms target)
 - Memory leak detection
-- Resource optimization verification
-- Scalability testing (20+ instances)
-- Bundle size impact assessment
+- Resource build:cache-bust`| Update cache-busting params    | Updates query strings in files  |
+|`npm run test:build`    | Build + ready message            | One-command test preparation    |
+|`npm run test:validate` | Build + comprehensive check      | Full environment validation     |
+|`npm run watch`         | Watch mode (TypeScript + SCSS)   | Auto-rebuild during development |
+|`npm run examples` | Build + examples ready | Prepare examples for viewing |
+
+#### Build Scripts
+
+The project includes helper scripts in the `scripts/` directory:
+
+- **`verify-build.js`** - Validates that all required build outputs exist and are valid
+  - Checks for compiled JS files (index.js, youtube-only.js, vimeo-only.js, video-only.js)
+  - Verifies CSS compilation (main.css, components.css)
+  - Ensures test files are accessible
+  - Automatically run as part of `npm run build`
+
+- **`update-cache-busters.js`** - Updates cache-busting query parameters in built files
+  - Appends version-based timestamps to asset references
+  - Ensures browsers load fresh assets after updates
+  - Automatically run as part of `npm run build`
 
 ### Test Framework Features
 
@@ -714,8 +914,43 @@ For detailed testing documentation, see `test/README.md`.
 
 - Modern browsers with Web Components support
 - ES6+ JavaScript features
-- YouTube iframe API integration
-- Vimeo Player API integration
+- YouTube IFrame API integration ([API Reference](https://developers.google.com/youtube/iframe_api_reference))
+- Vimeo Player API integration ([API Reference](https://developer.vimeo.com/player/sdk/reference))
+
+### YouTube IFrame API Integration
+
+The `<youtube-embed>` component wraps the [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) to provide a consistent, web-component-based interface.
+
+**API Loading:**
+
+- Dynamically loads `https://www.youtube.com/iframe_api`
+- Implements retry mechanism (up to 3 attempts) for reliability
+- Handles API initialization via `onYouTubeIframeAPIReady` callback
+- 10-second timeout protection against blocked scripts
+
+**Player Methods Used:**
+
+- [`playVideo()`](https://developers.google.com/youtube/iframe_api_reference#playVideo) - Start video playback ✅
+- [`pauseVideo()`](https://developers.google.com/youtube/iframe_api_reference#pauseVideo) - Pause video playback ✅
+- [`stopVideo()`](https://developers.google.com/youtube/iframe_api_reference#stopVideo) - Stop video and reset ✅
+- [`seekTo(seconds, allowSeekAhead)`](https://developers.google.com/youtube/iframe_api_reference#seekTo) - Seek to specific time ✅
+- [`mute()`](https://developers.google.com/youtube/iframe_api_reference#mute) - Mute the player ✅
+- [`unMute()`](https://developers.google.com/youtube/iframe_api_reference#unMute) - Unmute the player ✅
+- [`isMuted()`](https://developers.google.com/youtube/iframe_api_reference#isMuted) - Check mute state ✅
+- [`getCurrentTime()`](https://developers.google.com/youtube/iframe_api_reference#getCurrentTime) - Get current playback time ✅
+- ~~[`getPlaybackQuality()`](https://developers.google.com/youtube/iframe_api_reference#getPlaybackQuality)~~ - ⚠️ **DEPRECATED Oct 2019** - No longer functional
+- ~~[`setPlaybackQuality(suggestedQuality)`](https://developers.google.com/youtube/iframe_api_reference#setPlaybackQuality)~~ - ⚠️ **DEPRECATED Oct 2019** - No-op function
+- ~~[`getAvailableQualityLevels()`](https://developers.google.com/youtube/iframe_api_reference#getAvailableQualityLevels)~~ - ⚠️ **DEPRECATED Oct 2019** - No longer returns data
+
+**Event Handlers:**
+
+- [`onReady`](https://developers.google.com/youtube/iframe_api_reference#onReady) - Player is ready
+- [`onStateChange`](https://developers.google.com/youtube/iframe_api_reference#onStateChange) - Player state changed (playing, paused, ended, etc.)
+- [`onPlaybackQualityChange`](https://developers.google.com/youtube/iframe_api_reference#onPlaybackQualityChange) - Quality level changed
+- [`onError`](https://developers.google.com/youtube/iframe_api_reference#onError) - Error occurred
+
+**Player Parameters:**
+Supports all [YouTube Player Parameters](https://developers.google.com/youtube/player_parameters) via the `player-vars` attribute, including `autoplay`, `loop`, `controls`, `modestbranding`, `rel`, `showinfo`, and more.
 
 ## 📝 Migration Guide
 
@@ -1075,31 +1310,35 @@ npm run build:prod
 This creates optimized `.min.js` and `.min.css` files with:
 
 - **Terser** minification for JavaScript (removes whitespace, shortens variable names)
-- **CSSO** optimization for CSS (removes redundant rules, merges selectors)
-- **~50% smaller** file sizes compared to development builds
+- **CSSO** opt (all three components)
+  import "@smartimpact-it/modern-video-embed";
 
-### Build Output Structure
+// YouTube only
+import "@smartimpact-it/modern-video-embed/dist/youtube-only.js";
 
-```
-dist/
-├── index.js                      # Full bundle (58KB)
-├── index.min.js                  # Full bundle minified (29KB) ⭐ Production
-├── youtube-only.js               # YouTube bundle (29KB)
-├── youtube-only.min.js           # YouTube minified (15KB) ⭐ Production
-├── vimeo-only.js                 # Vimeo bundle (29KB)
-├── vimeo-only.min.js             # Vimeo minified (14KB) ⭐ Production
+// Vimeo only
+import "@smartimpact-it/modern-video-embed/dist/vimeo-only.js";
+
+// Native video only
+import "@smartimpact-it/modern-video-embed/dist/vidKB)
+├── index.min.js # Full bundle minified (29KB) ⭐ Production
+├── youtube-only.js # YouTube bundle (29KB)
+├── youtube-only.min.js # YouTube minified (15KB) ⭐ Production
+├── vimeo-only.js # Vimeo bundle (29KB)
+├── vimeo-only.min.js # Vimeo minified (14KB) ⭐ Production
 ├── components/
-│   ├── YouTubeEmbed.js           # YouTube component (58KB)
-│   ├── YouTubeEmbed.min.js       # YouTube minified (29KB)
-│   ├── VimeoEmbed.js             # Vimeo component (49KB)
-│   └── VimeoEmbed.min.js         # Vimeo minified (27KB)
+│ ├── YouTubeEmbed.js # YouTube component (58KB)
+│ ├── YouTubeEmbed.min.js # YouTube minified (29KB)
+│ ├── VimeoEmbed.js # Vimeo component (49KB)
+│ └── VimeoEmbed.min.js # Vimeo minified (27KB)
 ├── css/
-│   ├── components.css            # Core styles (9KB)
-│   ├── components.min.css        # Core minified (7KB) ⭐ Production
-│   ├── main.css                  # With Bootstrap (276KB)
-│   └── main.min.css              # Bootstrap minified (224KB)
-└── types/                        # TypeScript declarations
-```
+│ ├── components.css # Core styles (9KB)
+│ ├── components.min.css # Core minified (7KB) ⭐ Production
+│ ├── main.css # With Bootstrap (276KB)
+│ └── main.min.css # Bootstrap minified (224KB)
+└── types/ # TypeScript declarations
+
+````
 
 ### Performance Optimization
 
@@ -1107,11 +1346,23 @@ dist/
 
 | Configuration        | Size (Dev) | Size (Prod) | With gzip\* |
 | -------------------- | ---------- | ----------- | ----------- |
-| YouTube + Core CSS   | 38KB       | **22KB**    | ~7KB        |
-| Vimeo + Core CSS     | 38KB       | **21KB**    | ~7KB        |
-| Both + Core CSS      | 67KB       | **36KB**    | ~12KB       |
-| Both + Bootstrap CSS | 343KB      | **253KB**   | ~45KB       |
-
+We welcome contributions! Here's how to get started:
+
+1. **Read the docs**: Check [`.ai-instructions.md`](.ai-instructions.md) for development guidelines
+2. **Fork the repository**: Create your own fork on GitHub
+3. **Create a feature branch**: `git checkout -b feature/your-feature-name`
+4. **Make your changes**: Follow TypeScript strict mode and existing patterns
+5. **Build and test**: Run `npm run build` and test with `test/index.html`
+6. **Update documentation**: Update README and type definitions if needed
+7. **Submit a pull request**: Include a clear description of changes
+
+**Development Checklist:**
+- ✅ Code follows existing patterns and conventions
+- ✅ TypeScript compiles without errors (strict mode)
+- ✅ All tests pass in `test/index.html`
+- ✅ Type definitions updated if API changed
+- ✅ README updated for user-facing changes
+- ✅ Examples added/updated if needed
 \*Estimated with gzip compression enabled on server
 
 **Optimization Tips:**
@@ -1128,7 +1379,7 @@ dist/
 <!-- YouTube only: 22KB total (7KB gzipped) -->
 <script type="module" src="dist/youtube-only.min.js"></script>
 <link rel="stylesheet" href="dist/css/components.min.css" />
-```
+````
 
 ### Bundle Sizes
 

package/dist/components/BaseVideoEmbed.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Base class for all video embed components (VideoEmbed, YouTubeEmbed, VimeoEmbed).
+ * Contains shared functionality to reduce code duplication and ensure consistency.
+ */
+export declare abstract class BaseVideoEmbed extends HTMLElement {
+    protected static instanceCount: number;
+    protected static DEBUG: boolean;
+    protected playerReady: boolean;
+    protected initialized: boolean;
+    protected updatingAttribute: boolean;
+    protected playPauseButton: HTMLDivElement | null;
+    protected setCustomControlState: ((playing: boolean) => void) | null;
+    protected ariaLiveRegion: HTMLElement | null;
+    protected intersectionObserver: IntersectionObserver | null;
+    protected hasLoadedVideo: boolean;
+    protected posterClickHandler: EventListener | null;
+    protected keyboardHandler: ((e: KeyboardEvent) => void) | null;
+    protected _playing: boolean;
+    protected _autoplay: boolean;
+    protected _muted: boolean;
+    protected _controls: boolean;
+    protected _lazy: boolean;
+    protected _background: boolean;
+    protected _poster: string;
+    /**
+     * Abstract methods that subclasses must implement
+     */
+    protected abstract initializePlayer(...args: any[]): Promise<void> | void;
+    protected abstract reinitializePlayer(): void;
+    protected abstract destroyPlayer(): void;
+    protected abstract getComponentName(): string;
+    /**
+     * Logging utilities
+     */
+    protected log(...args: any[]): void;
+    protected warn(...args: any[]): void;
+    protected error(...args: any[]): void;
+    /**
+     * Event dispatching
+     */
+    protected dispatchCustomEvent(eventName: string, detail?: any): void;
+    /**
+     * Attribute reflection helpers
+     */
+    protected reflectBooleanAttribute(name: string, value: boolean): void;
+    protected reflectAttribute(name: string, value: string): void;
+    /**
+     * Error message display (common across all components)
+     */
+    protected showErrorMessage(message: string, errorClass: string): void;
+    /**
+     * Retry handler - subclasses can override
+     */
+    protected handleRetry(): void;
+    /**
+     * Background mode management (common across all components)
+     */
+    protected updateBackgroundMode(): void;
+    /**
+     * Automatically set aspect ratio CSS custom properties
+     * This allows background videos to maintain correct proportions
+     */
+    protected setAspectRatio(width: number, height: number): void;
+    /**
+     * Custom controls creation (similar pattern across components)
+     */
+    protected addCustomControls(containerClass: string): void;
+    /**
+     * Play/Pause handlers - subclasses override with platform-specific logic
+     */
+    protected abstract handlePlay(): void;
+    protected abstract handlePause(): void;
+    /**
+     * Lazy loading setup (common pattern)
+     */
+    protected setupLazyLoading(callback: () => void): void;
+    /**
+     * ARIA announcements for accessibility
+     */
+    protected announceToScreenReader(message: string): void;
+    /**
+     * Lifecycle management
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Static debug toggle
+     */
+    static toggleDebug(forceState?: boolean): void;
+}
+//# sourceMappingURL=BaseVideoEmbed.d.ts.map

package/dist/components/BaseVideoEmbed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseVideoEmbed.d.ts","sourceRoot":"","sources":["../../src/components/BaseVideoEmbed.ts"],"names":[],"mappings":"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"}