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

package/src/components/YouTubeEmbed.ts

@@ -1,49 +1,24 @@
-export class YouTubeEmbed extends HTMLElement {
+import { BaseVideoEmbed } from "./BaseVideoEmbed.js";
+
+export class YouTubeEmbed extends BaseVideoEmbed {
   private iframe: HTMLIFrameElement | null = null;
   private player: YT["Player"] | null = null;
   private static apiLoaded = false;
   private static apiReady = false;
-  private static instanceCount = 0; // Track active instances
-  private static DEBUG = false; // Enable/disable debug logging
-  private playerReady = false;
-  private playPauseButton: HTMLDivElement | null = null;
-  private initialized = false;
-  private setCustomControlState: ((playing: boolean) => void) | null = null;
-  private updatingAttribute = false; // Flag to prevent recursive attribute updates
+  private static apiLoadingPromise: Promise<void> | null = null;
+  private static readonly MAX_API_RETRIES = 3;
+  private static readonly API_RETRY_DELAY = 2000;
+  private static readonly API_LOAD_TIMEOUT = 10000;
   private updatingMutedState = false; // Flag to prevent sync from overwriting programmatic mute changes
+  private apiLoadRetries = 0;
 
   /** The full YouTube URL (e.g., "https://www.youtube.com/watch?v=...") */
   #url: string = "";
   /** The 11-character YouTube video ID. */
   #videoId: string = "";
-  /** Whether the video should autoplay when loaded. Requires `muted` to be true. */
-  #autoplay: boolean = false;
-  /** Whether the video audio is muted. */
-  #muted: boolean = false;
-  /** Whether to show the native YouTube player controls. */
-  #controls: boolean = false;
-  /** Whether to lazy-load the video, showing a poster image until interaction. */
-  #lazy: boolean = false;
-  /** URL for a custom poster image. Defaults to YouTube's thumbnail. */
-  #poster: string = "";
-  /** Read-only property to check if the video is currently playing. */
-  #playing: boolean = false;
-  /** Whether the video should act as a background, covering its container. */
-  #background: boolean = false;
   /** Extra parameters to pass to the YouTube player. */
   #playerVars: Record<string, string | number | boolean> = {};
 
-  // Declare the event listener properties
-  private posterClickHandler: EventListener | null = null;
-  private keyboardHandler: ((e: KeyboardEvent) => void) | null = null;
-  private ariaLiveRegion: HTMLElement | null = null;
-  private apiLoadRetries = 0;
-  private static readonly MAX_API_RETRIES = 3;
-  private static readonly API_RETRY_DELAY = 2000;
-  private static readonly API_LOAD_TIMEOUT = 10000;
-  private intersectionObserver: IntersectionObserver | null = null;
-  private hasLoadedVideo = false;
-
   static get observedAttributes() {
     return [
       "url",
@@ -82,35 +57,36 @@ export class YouTubeEmbed extends HTMLElement {
         }
         break;
       case "video-id":
-        this.#videoId = newValue || "";
+        // Sanitize video ID to prevent XSS
+        this.#videoId = this.sanitizeVideoId(newValue || "");
         if (this.initialized) {
           this.reinitializePlayer();
         }
         break;
       case "autoplay":
-        this.#autoplay = newValue !== null;
+        this._autoplay = newValue !== null;
         if (
-          !this.#playing &&
-          this.#autoplay &&
-          !this.#lazy &&
+          !this._playing &&
+          this._autoplay &&
+          !this._lazy &&
           this.initialized
         ) {
           this.play();
         }
         break;
       case "controls":
-        this.#controls = newValue !== null;
+        this._controls = newValue !== null;
         if (this.initialized) {
           this.reinitializePlayer();
         }
         break;
       case "lazy":
-        this.#lazy = newValue !== null;
+        this._lazy = newValue !== null;
         break;
       case "muted":
-        this.#muted = newValue !== null;
+        this._muted = newValue !== null;
         if (this.player && this.playerReady) {
-          if (this.#muted) {
+          if (this._muted) {
             this.player.mute();
           } else {
             this.player.unMute();
@@ -118,14 +94,14 @@ export class YouTubeEmbed extends HTMLElement {
         }
         break;
       case "poster":
-        this.#poster = newValue || "";
-        if (this.#lazy && !this.player) {
+        this._poster = newValue || "";
+        if (this._lazy && !this.player) {
           this.showPoster(this.#videoId);
         }
         break;
       case "background":
-        this.#background = newValue !== null;
-        this.#updateBackgroundMode();
+        this._background = newValue !== null;
+        this.updateBackgroundMode();
         break;
       case "player-vars":
         try {
@@ -181,12 +157,12 @@ export class YouTubeEmbed extends HTMLElement {
    * Note: Autoplay is subject to browser policies and usually requires the video to be muted.
    */
   get autoplay() {
-    return this.#autoplay;
+    return this._autoplay;
   }
   set autoplay(value: boolean) {
-    this.#autoplay = value;
-    this.#reflectBooleanAttribute("autoplay", value);
-    if (!this.#playing && value && !this.#lazy && this.initialized) {
+    this._autoplay = value;
+    this.reflectBooleanAttribute("autoplay", value);
+    if (!this._playing && value && !this._lazy && this.initialized) {
       this.play();
     }
   }
@@ -195,11 +171,16 @@ export class YouTubeEmbed extends HTMLElement {
    * Gets or sets whether native YouTube player controls are visible.
    */
   get controls() {
-    return this.#controls;
+    return this._controls;
   }
   set controls(value: boolean) {
-    this.#controls = value;
-    this.#reflectBooleanAttribute("controls", value);
+    // Background mode videos must not have controls
+    if (this._background && value) {
+      this.warn("Cannot enable controls on background video");
+      return;
+    }
+    this._controls = value;
+    this.reflectBooleanAttribute("controls", value);
     if (this.initialized) {
       this.reinitializePlayer();
     }
@@ -210,22 +191,27 @@ export class YouTubeEmbed extends HTMLElement {
    * If true, a poster is shown, and the video loads only on user interaction.
    */
   get lazy() {
-    return this.#lazy;
+    return this._lazy;
   }
   set lazy(value: boolean) {
-    this.#lazy = value;
-    this.#reflectBooleanAttribute("lazy", value);
+    this._lazy = value;
+    this.reflectBooleanAttribute("lazy", value);
   }
 
   /**
    * Gets or sets the muted state of the video.
    */
   get muted() {
-    return this.#muted;
+    return this._muted;
   }
   set muted(value: boolean) {
-    this.#muted = value;
-    this.#reflectBooleanAttribute("muted", value);
+    // Background mode videos must be muted
+    if (this._background && !value) {
+      this.warn("Cannot unmute background video");
+      return;
+    }
+    this._muted = value;
+    this.reflectBooleanAttribute("muted", value);
     if (this.player && this.playerReady) {
       this.updatingMutedState = true;
       if (value) {
@@ -245,10 +231,10 @@ export class YouTubeEmbed extends HTMLElement {
    * If not set, a default YouTube thumbnail is used for lazy-loaded videos.
    */
   get poster() {
-    return this.#poster;
+    return this._poster;
   }
   set poster(value: string) {
-    this.#poster = value;
+    this._poster = value;
     this.updatingAttribute = true;
     if (value) {
       this.setAttribute("poster", value);
@@ -256,7 +242,7 @@ export class YouTubeEmbed extends HTMLElement {
       this.removeAttribute("poster");
     }
     this.updatingAttribute = false;
-    if (this.#lazy && !this.player) {
+    if (this._lazy && !this.player) {
       this.showPoster(this.#videoId);
     }
   }
@@ -265,7 +251,7 @@ export class YouTubeEmbed extends HTMLElement {
    * Returns `true` if the video is currently playing.
    */
   get playing() {
-    return this.#playing;
+    return this._playing;
   }
 
   /**
@@ -273,12 +259,12 @@ export class YouTubeEmbed extends HTMLElement {
    * In background mode, the video covers its container, is muted, and has no controls.
    */
   get background() {
-    return this.#background;
+    return this._background;
   }
   set background(value: boolean) {
-    this.#background = value;
-    this.#reflectBooleanAttribute("background", value);
-    this.#updateBackgroundMode();
+    this._background = value;
+    this.reflectBooleanAttribute("background", value);
+    this.updateBackgroundMode();
   }
 
   /**
@@ -296,22 +282,13 @@ export class YouTubeEmbed extends HTMLElement {
     }
   }
 
-  #reflectBooleanAttribute(name: string, value: boolean) {
-    this.updatingAttribute = true;
-    if (value) {
-      this.setAttribute(name, "");
-    } else {
-      this.removeAttribute(name);
-    }
-    this.updatingAttribute = false;
-  }
-
   private extractVideoId(url: string): string {
     if (!url) return "";
 
     // Comprehensive regex to handle various YouTube URL formats
+    // Match video IDs that are typically 11 characters but allow for variation (10-12 chars)
     const regex =
-      /(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^"&?\/ ]{11})/;
+      /(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^"&?\/ ]{10,12})/;
     const match = url.match(regex);
 
     if (match && match[1]) {
@@ -319,7 +296,7 @@ export class YouTubeEmbed extends HTMLElement {
     }
 
     // If it's already just an ID
-    if (/^[a-zA-Z0-9_-]{11}$/.test(url)) {
+    if (/^[a-zA-Z0-9_-]{10,12}$/.test(url)) {
       return url;
     }
 
@@ -327,28 +304,59 @@ export class YouTubeEmbed extends HTMLElement {
     return "";
   }
 
-  private log(...args: any[]) {
-    if (YouTubeEmbed.DEBUG) {
-      console.log("YouTubeEmbed:", ...args);
+  /**
+   * Sanitize video ID to prevent XSS attacks
+   */
+  private sanitizeVideoId(videoId: string): string {
+    if (!videoId) return "";
+
+    // YouTube video IDs should only contain alphanumeric characters, hyphens, and underscores
+    // and be 10-12 characters long
+    if (/^[a-zA-Z0-9_-]{10,12}$/.test(videoId)) {
+      return videoId;
+    }
+
+    this.warn(`YouTubeEmbed: Invalid video ID format "${videoId}"`);
+    return "";
+  }
+
+  // Implement abstract methods from BaseVideoEmbed
+  protected getComponentName(): string {
+    return "YouTubeEmbed";
+  }
+
+  protected handlePlay(): void {
+    if (this.player && typeof this.player.playVideo === "function") {
+      this.player.playVideo();
     }
   }
 
-  private warn(...args: any[]) {
-    console.warn(...args);
+  protected handlePause(): void {
+    if (this.player && typeof this.player.pauseVideo === "function") {
+      this.player.pauseVideo();
+    }
   }
 
-  private error(...args: any[]) {
-    console.error(...args);
+  protected override handleRetry(): void {
+    this.apiLoadRetries = 0;
+    if (this.#videoId) {
+      this.initializePlayer(this.#videoId);
+    }
   }
 
-  private dispatchCustomEvent(eventName: string, detail?: any) {
-    this.dispatchEvent(
-      new CustomEvent(eventName, {
-        detail,
-        bubbles: true,
-        composed: true,
-      }),
-    );
+  protected destroyPlayer(): void {
+    if (this.player) {
+      try {
+        this.player.destroy();
+      } catch (e) {
+        this.warn("Error destroying player:", e);
+      }
+      this.player = null;
+    }
+    if (this.iframe) {
+      this.iframe.remove();
+      this.iframe = null;
+    }
   }
 
   private isValidPosterUrl(url: string): boolean {
@@ -362,91 +370,6 @@ export class YouTubeEmbed extends HTMLElement {
     }
   }
 
-  /**
-   * Setup fullscreen change event listener
-   */
-  private setupFullscreenListener(): void {
-    const handleFullscreenChange = () => {
-      const isFullscreen = this.isFullscreen();
-      this.dispatchCustomEvent("fullscreenchange", { isFullscreen });
-
-      if (isFullscreen) {
-        this.classList.add("is-fullscreen");
-      } else {
-        this.classList.remove("is-fullscreen");
-      }
-    };
-
-    document.addEventListener("fullscreenchange", handleFullscreenChange);
-    document.addEventListener("webkitfullscreenchange", handleFullscreenChange);
-    document.addEventListener("mozfullscreenchange", handleFullscreenChange);
-    document.addEventListener("MSFullscreenChange", handleFullscreenChange);
-  }
-
-  /**
-   * Setup keyboard event handlers for accessibility
-   */
-  private setupKeyboardHandlers(): void {
-    this.keyboardHandler = (e: KeyboardEvent) => {
-      // Only handle if player is ready and not in input element
-      if (!this.playerReady || (e.target as HTMLElement)?.tagName === "INPUT") {
-        return;
-      }
-
-      switch (e.key.toLowerCase()) {
-        case "k":
-        case " ":
-          // Play/Pause
-          e.preventDefault();
-          this.togglePlay();
-          this.announceToScreenReader(
-            this.#playing ? "Video playing" : "Video paused",
-          );
-          break;
-
-        case "m":
-          // Mute/Unmute
-          e.preventDefault();
-          this.toggleMute();
-          this.player?.isMuted().then((muted: boolean) => {
-            this.announceToScreenReader(
-              muted ? "Video muted" : "Video unmuted",
-            );
-          });
-          break;
-
-        case "f":
-          // Fullscreen toggle
-          e.preventDefault();
-          if (document.fullscreenElement) {
-            document.exitFullscreen();
-            this.announceToScreenReader("Exited fullscreen");
-          } else if (this.enterFullscreen) {
-            this.enterFullscreen();
-            this.announceToScreenReader("Entered fullscreen");
-          }
-          break;
-      }
-    };
-
-    this.addEventListener("keydown", this.keyboardHandler as EventListener);
-  }
-
-  /**
-   * Announce message to screen readers
-   */
-  private announceToScreenReader(message: string): void {
-    if (this.ariaLiveRegion) {
-      this.ariaLiveRegion.textContent = message;
-      // Clear after a brief delay
-      setTimeout(() => {
-        if (this.ariaLiveRegion) {
-          this.ariaLiveRegion.textContent = "";
-        }
-      }, 1000);
-    }
-  }
-
   /**
    * Add preconnect and dns-prefetch hints for YouTube domains
    */
@@ -472,52 +395,65 @@ export class YouTubeEmbed extends HTMLElement {
   }
 
   /**
-   * Setup Intersection Observer for lazy loading
+   * Clear content while preserving accessibility elements
    */
-  private setupIntersectionObserver(): void {
-    if (!("IntersectionObserver" in window)) {
-      // Fallback: load immediately if IntersectionObserver not supported
-      return;
+  private clearContent(): void {
+    // Temporarily remove and preserve ariaLiveRegion
+    const preservedAriaLive = this.ariaLiveRegion;
+    if (preservedAriaLive && preservedAriaLive.parentNode === this) {
+      this.removeChild(preservedAriaLive);
     }
 
-    const options: IntersectionObserverInit = {
-      root: null,
-      rootMargin: "50px", // Start loading 50px before entering viewport
-      threshold: 0.01,
-    };
-
-    this.intersectionObserver = new IntersectionObserver((entries) => {
-      entries.forEach((entry) => {
-        if (entry.isIntersecting && !this.hasLoadedVideo) {
-          this.hasLoadedVideo = true;
-          this.log("YouTubeEmbed: Video entering viewport, loading...");
-
-          // Check if poster was clicked before intersection
-          const shouldAutoplay =
-            this.getAttribute("data-poster-autoplay") === "true";
+    // Clear all content
+    this.innerHTML = "";
 
-          if (!shouldAutoplay) {
-            // Just load the player, don't autoplay
-            this.initializePlayer(this.#videoId);
-          }
+    // Re-append preserved elements
+    if (preservedAriaLive) {
+      this.appendChild(preservedAriaLive);
+    }
+  }
 
-          // Disconnect observer after loading
-          if (this.intersectionObserver) {
-            this.intersectionObserver.disconnect();
-          }
-        }
-      });
-    }, options);
+  /**
+   * Ensure aria-live region is present in DOM
+   */
+  private ensureAriaLiveRegion(): void {
+    if (this.ariaLiveRegion && !this.contains(this.ariaLiveRegion)) {
+      this.appendChild(this.ariaLiveRegion);
+    }
+  }
 
-    this.intersectionObserver.observe(this);
+  /**
+   * Set up accessibility features
+   */
+  private setupAccessibility(): void {
+    // Create screen reader announcements container
+    if (!this.ariaLiveRegion) {
+      this.ariaLiveRegion = document.createElement("div");
+      this.ariaLiveRegion.setAttribute("role", "status");
+      this.ariaLiveRegion.setAttribute("aria-live", "polite");
+      this.ariaLiveRegion.setAttribute("aria-atomic", "true");
+      this.ariaLiveRegion.style.position = "absolute";
+      this.ariaLiveRegion.style.left = "-10000px";
+      this.ariaLiveRegion.style.width = "1px";
+      this.ariaLiveRegion.style.height = "1px";
+      this.ariaLiveRegion.style.overflow = "hidden";
+      this.appendChild(this.ariaLiveRegion);
+    }
+
+    // Set up ARIA label
+    this.setAttribute("role", "region");
+    this.setAttribute("aria-label", "YouTube video player");
   }
 
   /**
    * Display error message to user with retry option
    */
-  private showErrorMessage(message: string): void {
+  protected override showErrorMessage(
+    message: string,
+    errorClass?: string,
+  ): void {
     const errorDiv = document.createElement("div");
-    errorDiv.className = "youtube-error-message";
+    errorDiv.className = errorClass || "youtube-error-message";
     errorDiv.setAttribute("role", "alert");
     errorDiv.innerHTML = `
       <div class="error-content">
@@ -542,24 +478,18 @@ export class YouTubeEmbed extends HTMLElement {
       });
     }
 
-    // Clear existing content
-    this.innerHTML = "";
+    // Clear existing content while preserving accessibility elements
+    this.clearContent();
     this.appendChild(errorDiv);
   }
 
-  connectedCallback() {
-    YouTubeEmbed.instanceCount++;
-    this.log(
-      "YouTubeEmbed: connectedCallback called, instance count:",
-      YouTubeEmbed.instanceCount,
-    );
+  override connectedCallback() {
+    super.connectedCallback();
 
-    // Add resource hints on first instance
-    if (YouTubeEmbed.instanceCount === 1) {
-      this.addResourceHints();
-    }
+    // Add resource hints on first connection
+    this.addResourceHints();
 
-    // Initialize attributes from HTML
+    // Initialize YouTube-specific attributes
     const urlAttr = this.getAttribute("url");
     const videoIdAttr = this.getAttribute("video-id");
 
@@ -567,18 +497,10 @@ export class YouTubeEmbed extends HTMLElement {
       this.#url = urlAttr;
       this.#videoId = this.extractVideoId(urlAttr);
     } else if (videoIdAttr) {
-      this.#videoId = videoIdAttr;
+      this.#videoId = this.sanitizeVideoId(videoIdAttr);
     }
 
-    // Set boolean attributes
-    this.#autoplay = this.hasAttribute("autoplay");
-    this.#controls = this.hasAttribute("controls");
-    this.#lazy = this.hasAttribute("lazy");
-    this.#muted = this.hasAttribute("muted");
-    this.#background = this.hasAttribute("background");
-
-    // Set string attributes
-    this.#poster = this.getAttribute("poster") || "";
+    // Parse player vars JSON
     try {
       const playerVarsAttr = this.getAttribute("player-vars");
       this.#playerVars = playerVarsAttr ? JSON.parse(playerVarsAttr) : {};
@@ -595,53 +517,30 @@ export class YouTubeEmbed extends HTMLElement {
       return;
     }
 
-    // Use the element itself as the container
+    // Add wrapper class when video ID is present
     this.classList.add("youtube-embed-wrapper");
 
-    // Add ARIA role and tabindex for accessibility
-    this.setAttribute("role", "region");
-    this.setAttribute("aria-label", "Video player");
-    if (!this.hasAttribute("tabindex")) {
-      this.setAttribute("tabindex", "0");
-    }
-
-    // Create ARIA live region for screen reader announcements
-    this.ariaLiveRegion = document.createElement("div");
-    this.ariaLiveRegion.setAttribute("aria-live", "polite");
-    this.ariaLiveRegion.setAttribute("aria-atomic", "true");
-    this.ariaLiveRegion.className = "sr-only";
-    this.ariaLiveRegion.style.cssText =
-      "position:absolute;left:-10000px;width:1px;height:1px;overflow:hidden;";
-    this.appendChild(this.ariaLiveRegion);
+    // Set up accessibility features
+    this.setupAccessibility();
 
-    // Setup keyboard event handlers
-    this.setupKeyboardHandlers();
-
-    // Setup fullscreen change listener
-    this.setupFullscreenListener();
-
-    this.#updateBackgroundMode();
-
-    if (this.#lazy) {
+    if (this._lazy) {
       this.showPoster(this.#videoId);
-      // Setup Intersection Observer for better performance
-      this.setupIntersectionObserver();
+      this.setupLazyLoading(() => {
+        const shouldAutoplay =
+          this.getAttribute("data-poster-autoplay") === "true";
+        if (!shouldAutoplay) {
+          this.initializePlayer(this.#videoId);
+        }
+      });
     } else {
-      // Initialize the player immediately
       this.initializePlayer(this.#videoId);
     }
-    this.initialized = true;
-    this.dispatchCustomEvent("connected");
   }
 
-  disconnectedCallback() {
-    YouTubeEmbed.instanceCount--;
-    this.log(
-      "YouTubeEmbed: disconnectedCallback called, remaining instances:",
-      YouTubeEmbed.instanceCount,
-    );
+  override disconnectedCallback() {
+    super.disconnectedCallback();
 
-    // Stop the video and destroy the player instance
+    // Cleanup YouTube-specific resources
     if (this.player) {
       try {
         this.player.destroy();
@@ -652,71 +551,10 @@ export class YouTubeEmbed extends HTMLElement {
       this.player = null;
     }
 
-    // Remove keyboard event handlers
-    if (this.keyboardHandler) {
-      this.removeEventListener(
-        "keydown",
-        this.keyboardHandler as EventListener,
-      );
-      this.keyboardHandler = null;
-    }
-
-    // Remove event listeners from poster and play button
-    const poster = this.querySelector(".youtube-poster");
-    const buttonOverlay = this.querySelector(".button-overlay");
-
-    if (poster && this.posterClickHandler) {
-      poster.removeEventListener("click", this.posterClickHandler);
-      this.posterClickHandler = null;
-    }
-
-    if (buttonOverlay && this.posterClickHandler) {
-      buttonOverlay.removeEventListener("click", this.posterClickHandler);
-    }
-
-    // Clear element content
-    this.innerHTML = "";
-    this.classList.remove(
-      "youtube-embed-wrapper",
-      "youtube-embed-container",
-      "is-playing",
-    );
-
-    // Only clean up global resources if this is the last instance
-    if (YouTubeEmbed.instanceCount === 0) {
-      this.log("YouTubeEmbed: Last instance, cleaning up global resources");
-
-      // Remove the YouTube API script
-      const script = document.querySelector(
-        'script[src="https://www.youtube.com/iframe_api"]',
-      );
-      if (script) {
-        script.remove();
-        this.log("YouTubeEmbed: YouTube API script removed.");
-      }
-
-      // Clear global references
-      if (window.onYouTubeIframeAPIReady) {
-        delete window.onYouTubeIframeAPIReady;
-      }
-
-      // Reset static flags
-      YouTubeEmbed.apiLoaded = false;
-      YouTubeEmbed.apiReady = false;
-    }
-
-    // Nullify DOM references
     this.iframe = null;
-    this.playPauseButton = null;
-    this.setCustomControlState = null;
-
-    // Dispatch disconnected event
-    this.dispatchCustomEvent("disconnected");
-
-    this.log("YouTubeEmbed: Cleanup complete.");
   }
 
-  private reinitializePlayer() {
+  protected reinitializePlayer() {
     if (!this.initialized || !this.#videoId) {
       return;
     }
@@ -731,7 +569,7 @@ export class YouTubeEmbed extends HTMLElement {
     }
 
     // Clear and reinitialize
-    if (this.#lazy) {
+    if (this._lazy) {
       this.showPoster(this.#videoId);
     } else {
       this.initializePlayer(this.#videoId);
@@ -740,14 +578,14 @@ export class YouTubeEmbed extends HTMLElement {
 
   private showPoster(videoId: string) {
     // Use custom poster if valid, otherwise use YouTube thumbnail
-    const thumbnailUrl = this.isValidPosterUrl(this.#poster)
-      ? this.#poster
+    const thumbnailUrl = this.isValidPosterUrl(this._poster)
+      ? this._poster
       : `https://img.youtube.com/vi/${videoId}/hqdefault.jpg`;
 
     this.log("YouTubeEmbed: Using poster URL:", thumbnailUrl);
 
-    // Clear any existing content and event listeners
-    this.innerHTML = "";
+    // Clear any existing content and event listeners while preserving accessibility elements
+    this.clearContent();
 
     // Clear old event listeners if they exist
     if (this.posterClickHandler) {
@@ -820,10 +658,10 @@ export class YouTubeEmbed extends HTMLElement {
     this.log("YouTubeEmbed: Poster displayed for lazy loading");
   }
 
-  private async initializePlayer(videoId: string) {
+  protected async initializePlayer(videoId: string) {
     this.log("YouTubeEmbed: Initializing player for video ID:", videoId);
 
-    const isBackground = this.#background;
+    const isBackground = this._background;
     // Background videos must autoplay and be muted, with no controls.
     const autoplay =
       isBackground ||
@@ -849,8 +687,8 @@ export class YouTubeEmbed extends HTMLElement {
     );
 
     // Update internal muted state if autoplay forces muting
-    if (autoplay && !this.#muted) {
-      this.#muted = true;
+    if (autoplay && !this._muted) {
+      this._muted = true;
       this.log(
         "YouTubeEmbed: Autoplay enabled, forcing muted state for compliance",
       );
@@ -858,16 +696,15 @@ export class YouTubeEmbed extends HTMLElement {
 
     // Create a container div for the YouTube player
     const playerContainer = document.createElement("div");
-    playerContainer.style.position = "absolute";
-    playerContainer.style.top = "0";
-    playerContainer.style.left = "0";
-    playerContainer.style.width = "100%";
-    playerContainer.style.height = "100%";
+    // Let CSS handle positioning and sizing
 
     this.replaceChildren(playerContainer);
 
+    // Ensure aria-live region persists after replaceChildren
+    this.ensureAriaLiveRegion();
+
     if (!controls) {
-      this.addCustomControls();
+      this.addCustomControls("youtube-embed-container");
     }
 
     // Build playerVars object for YouTube Player API
@@ -881,7 +718,7 @@ export class YouTubeEmbed extends HTMLElement {
     };
 
     // Only add mute parameter when muting
-    if (mute || this.#muted) {
+    if (mute || this._muted) {
       playerVars.mute = 1;
     }
 
@@ -910,13 +747,26 @@ export class YouTubeEmbed extends HTMLElement {
             // Get the iframe element that YT.Player created
             this.iframe = this.player.getIframe();
 
-            // Apply background mode styling if needed
-            if (this.#background && this.iframe) {
-              this.iframe.style.pointerEvents = "none";
+            // Set aspect ratio (YouTube is typically 16:9)
+            this.setAspectRatio(16, 9);
+
+            // Apply styling to iframe
+            if (this.iframe) {
+              if (this._background) {
+                // In background mode, let CSS handle sizing with aspect-ratio
+                this.iframe.style.pointerEvents = "none";
+                // Remove any inline sizing to let CSS aspect-ratio work
+                this.iframe.style.removeProperty("width");
+                this.iframe.style.removeProperty("height");
+              } else {
+                // In normal mode, fill the container
+                this.iframe.style.width = "100%";
+                this.iframe.style.height = "100%";
+              }
             }
 
             // Sync muted state with YouTube player
-            if (this.#muted) {
+            if (this._muted) {
               this.player.mute();
             } else {
               this.player.unMute();
@@ -925,7 +775,7 @@ export class YouTubeEmbed extends HTMLElement {
             // Check if autoplay was enabled during initialization and update custom control state
             if (autoplay && this.setCustomControlState) {
               this.setCustomControlState(true);
-              this.#playing = true;
+              this._playing = true;
             }
 
             this.dispatchCustomEvent("ready");
@@ -935,7 +785,7 @@ export class YouTubeEmbed extends HTMLElement {
             const isPaused = event.data === YT.PlayerState.PAUSED;
             const isEnded = event.data === YT.PlayerState.ENDED;
 
-            this.#playing = isPlaying;
+            this._playing = isPlaying;
 
             // Sync muted state with actual player state (only if not programmatically updating)
             try {
@@ -945,8 +795,8 @@ export class YouTubeEmbed extends HTMLElement {
                 typeof this.player.isMuted === "function"
               ) {
                 const actualMuted = this.player.isMuted();
-                if (actualMuted !== this.#muted) {
-                  this.#muted = actualMuted;
+                if (actualMuted !== this._muted) {
+                  this._muted = actualMuted;
                   this.log("YouTubeEmbed: Synced muted state:", actualMuted);
                 }
               }
@@ -997,6 +847,17 @@ export class YouTubeEmbed extends HTMLElement {
               code: event.data,
             });
           },
+          onPlaybackQualityChange: (event: any) => {
+            const quality = event.data;
+            this.log("YouTubeEmbed: Quality changed to:", quality);
+
+            // Dispatch quality change event
+            this.dispatchCustomEvent("qualitychange", {
+              newQuality: quality,
+              oldQuality: this.getCurrentQuality(),
+              availableQualities: this.getAvailableQualities(),
+            });
+          },
         },
       });
     } catch (error) {
@@ -1005,6 +866,7 @@ export class YouTubeEmbed extends HTMLElement {
         error instanceof Error
           ? error.message
           : "Failed to load YouTube player. Please refresh the page or check your connection.",
+        "youtube-error-message",
       );
       this.dispatchCustomEvent("error", {
         message: error instanceof Error ? error.message : "API load failed",
@@ -1015,14 +877,21 @@ export class YouTubeEmbed extends HTMLElement {
   }
 
   private static async loadYouTubeAPI(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      if (this.apiReady) {
-        resolve();
-        return;
-      }
+    // If API is already ready, return immediately
+    if (this.apiReady) {
+      return Promise.resolve();
+    }
 
+    // If another instance is already loading, wait for that promise
+    if (this.apiLoadingPromise) {
+      return this.apiLoadingPromise;
+    }
+
+    // Create a new loading promise that all instances will share
+    this.apiLoadingPromise = new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
         cleanup();
+        this.apiLoadingPromise = null;
         reject(
           new Error(
             "YouTube API loading timeout. The API script may be blocked by an ad blocker or network issue.",
@@ -1035,11 +904,13 @@ export class YouTubeEmbed extends HTMLElement {
         delete window.onYouTubeIframeAPIReady;
       };
 
+      // Only add the script if it hasn't been added yet
       if (!this.apiLoaded) {
         const script = document.createElement("script");
         script.src = "https://www.youtube.com/iframe_api";
         script.onerror = () => {
           cleanup();
+          this.apiLoadingPromise = null;
           reject(
             new Error(
               "Failed to load YouTube API script. Please check your network connection or disable ad blockers.",
@@ -1056,6 +927,8 @@ export class YouTubeEmbed extends HTMLElement {
         resolve();
       };
     });
+
+    return this.apiLoadingPromise;
   }
 
   /**
@@ -1080,8 +953,8 @@ export class YouTubeEmbed extends HTMLElement {
     }
   }
 
-  private addCustomControls() {
-    this.classList.add("youtube-embed-container");
+  protected override addCustomControls(containerClass: string) {
+    this.classList.add(containerClass || "youtube-embed-container");
 
     // Create button overlay
     const buttonOverlay = document.createElement("div");
@@ -1136,26 +1009,18 @@ export class YouTubeEmbed extends HTMLElement {
     this.appendChild(buttonOverlay);
   }
 
-  #updateBackgroundMode() {
-    if (this.#background) {
-      this.classList.add("is-background");
-      // Ensure properties for background mode are set
-      this.#autoplay = true;
-      this.#muted = true;
-      this.#controls = false;
-      this.#lazy = false; // Background videos should load immediately
-    } else {
-      this.classList.remove("is-background");
-    }
-  }
-
   // Update the playVideo method to wait for the player to be ready
   /**
    * Plays the video. If the video is lazy-loaded and not yet initialized, it will be loaded first.
+   *
+   * Wraps YouTube IFrame API's `playVideo()` method.
+   * Note: Autoplay is subject to browser policies and usually requires the video to be muted.
+   *
+   * @see https://developers.google.com/youtube/iframe_api_reference#playVideo
    */
   public async play(): Promise<void> {
     // Check if this is a lazy-loaded video that hasn't been initialized yet
-    if (this.#lazy && !this.player && !this.iframe) {
+    if (this._lazy && !this.player && !this.iframe) {
       this.log(
         "YouTubeEmbed: Lazy video needs to be loaded first. Initializing...",
       );
@@ -1203,7 +1068,7 @@ export class YouTubeEmbed extends HTMLElement {
       }
     }
 
-    this.#playing = true;
+    this._playing = true;
     // Update custom control state
     if (this.setCustomControlState) {
       this.setCustomControlState(true);
@@ -1214,6 +1079,10 @@ export class YouTubeEmbed extends HTMLElement {
 
   /**
    * Pauses the currently playing video.
+   *
+   * Wraps YouTube IFrame API's `pauseVideo()` method.
+   *
+   * @see https://developers.google.com/youtube/iframe_api_reference#pauseVideo
    */
   public pause() {
     if (this.player && typeof this.player.pauseVideo === "function") {
@@ -1230,7 +1099,7 @@ export class YouTubeEmbed extends HTMLElement {
       }
     }
 
-    this.#playing = false;
+    this._playing = false;
     // Update custom control state
     if (this.setCustomControlState) {
       this.setCustomControlState(false);
@@ -1241,6 +1110,10 @@ export class YouTubeEmbed extends HTMLElement {
 
   /**
    * Stops the video and resets it to the beginning.
+   *
+   * Wraps YouTube IFrame API's `stopVideo()` method.
+   *
+   * @see https://developers.google.com/youtube/iframe_api_reference#stopVideo
    */
   public stopVideo() {
     if (this.player && typeof this.player.stopVideo === "function") {
@@ -1257,7 +1130,7 @@ export class YouTubeEmbed extends HTMLElement {
       }
     }
 
-    this.#playing = false;
+    this._playing = false;
     // Update custom control state
     if (this.setCustomControlState) {
       this.setCustomControlState(false);
@@ -1268,6 +1141,10 @@ export class YouTubeEmbed extends HTMLElement {
 
   /**
    * Mutes the video audio.
+   *
+   * Wraps YouTube IFrame API's `mute()` method.
+   *
+   * @see https://developers.google.com/youtube/iframe_api_reference#mute
    */
   public mute() {
     this.muted = true;
@@ -1275,6 +1152,10 @@ export class YouTubeEmbed extends HTMLElement {
 
   /**
    * Unmutes the video audio.
+   *
+   * Wraps YouTube IFrame API's `unMute()` method.
+   *
+   * @see https://developers.google.com/youtube/iframe_api_reference#unMute
    */
   public unmute() {
     this.muted = false;
@@ -1284,7 +1165,7 @@ export class YouTubeEmbed extends HTMLElement {
    * Toggles the video between playing and paused.
    */
   public togglePlay() {
-    if (this.#playing) {
+    if (this._playing) {
       this.pause();
     } else {
       this.play();
@@ -1295,21 +1176,15 @@ export class YouTubeEmbed extends HTMLElement {
    * Toggles the audio between muted and unmuted.
    */
   public toggleMute() {
-    this.muted = !this.#muted;
+    this.muted = !this._muted;
   }
 
   /**
    * Toggles the debug logging for all component instances.
    * @param {boolean} [forceState] - Optional: force debug mode on or off.
    */
-  public static toggleDebug(forceState?: boolean) {
-    YouTubeEmbed.DEBUG =
-      forceState !== undefined ? forceState : !YouTubeEmbed.DEBUG;
-    console.log(
-      `YouTubeEmbed: Debugging is now ${
-        YouTubeEmbed.DEBUG ? "ENABLED" : "DISABLED"
-      }.`,
-    );
+  public static override toggleDebug(forceState?: boolean) {
+    BaseVideoEmbed.toggleDebug(forceState);
   }
 
   // Public API for getting player state
@@ -1319,13 +1194,13 @@ export class YouTubeEmbed extends HTMLElement {
    */
   public getPlayerState() {
     // Get actual muted state from YouTube player if available
-    let actualMutedState = this.#muted;
+    let actualMutedState = this._muted;
     if (this.player && this.playerReady) {
       try {
         actualMutedState = this.player.isMuted();
         // Sync internal state with actual player state
-        if (actualMutedState !== this.#muted) {
-          this.#muted = actualMutedState;
+        if (actualMutedState !== this._muted) {
+          this._muted = actualMutedState;
         }
       } catch (error) {
         // Fallback to internal state if player method fails
@@ -1337,7 +1212,7 @@ export class YouTubeEmbed extends HTMLElement {
     }
 
     return {
-      playing: this.#playing,
+      playing: this._playing,
       muted: actualMutedState,
       videoId: this.#videoId,
       ready: this.playerReady,
@@ -1351,13 +1226,17 @@ export class YouTubeEmbed extends HTMLElement {
    * @returns `true` if the video is playing.
    */
   public isPlaying(): boolean {
-    return this.#playing;
+    return this._playing;
   }
 
   // Public API for checking if video is muted
   /**
    * Checks if the video is currently muted.
+   *
+   * Wraps YouTube IFrame API's `isMuted()` method.
+   *
    * @returns `true` if the video is muted.
+   * @see https://developers.google.com/youtube/iframe_api_reference#isMuted
    */
   public isMuted(): boolean {
     if (this.player && this.playerReady) {
@@ -1370,7 +1249,7 @@ export class YouTubeEmbed extends HTMLElement {
         );
       }
     }
-    return this.#muted;
+    return this._muted;
   }
 
   /**
@@ -1411,10 +1290,15 @@ export class YouTubeEmbed extends HTMLElement {
    * Toggle fullscreen mode
    */
   async toggleFullscreen(): Promise<void> {
-    if (this.isFullscreen()) {
-      await this.exitFullscreen();
-    } else {
-      await this.enterFullscreen();
+    try {
+      if (this.isFullscreen()) {
+        await this.exitFullscreen();
+      } else {
+        await this.enterFullscreen();
+      }
+    } catch (error) {
+      this.warn("YouTubeEmbed: Toggle fullscreen failed:", error);
+      throw error;
     }
   }
 
@@ -1432,8 +1316,17 @@ export class YouTubeEmbed extends HTMLElement {
   }
 
   /**
-   * Get available quality levels for the current video
-   * @returns Array of available quality levels
+   * Get available quality levels for the current video.
+   *
+   * @deprecated Since October 2019 - YouTube deprecated this API. This method is a no-op and returns an empty array.
+   * YouTube now automatically controls quality based on network conditions and device capabilities.
+   * See: https://support.google.com/youtube/answer/91449
+   *
+   * Wraps YouTube IFrame API's `getAvailableQualityLevels()` method (deprecated).
+   *
+   * @returns Array of available quality levels (always returns empty array [])
+   * @see https://developers.google.com/youtube/iframe_api_reference#getAvailableQualityLevels
+   * @see https://developers.google.com/youtube/iframe_api_reference#Revision_History (October 24, 2019)
    */
   getAvailableQualities(): string[] {
     if (this.player && this.playerReady) {
@@ -1447,8 +1340,17 @@ export class YouTubeEmbed extends HTMLElement {
   }
 
   /**
-   * Get the current playback quality
-   * @returns Current quality level
+   * Get the current playback quality.
+   *
+   * @deprecated Since October 2019 - YouTube deprecated this API. This method is a no-op and always returns "auto".
+   * YouTube now automatically controls quality based on network conditions and device capabilities.
+   * See: https://support.google.com/youtube/answer/91449
+   *
+   * Wraps YouTube IFrame API's `getPlaybackQuality()` method (deprecated).
+   *
+   * @returns Current quality level (always returns "auto")
+   * @see https://developers.google.com/youtube/iframe_api_reference#getPlaybackQuality
+   * @see https://developers.google.com/youtube/iframe_api_reference#Revision_History (October 24, 2019)
    */
   getCurrentQuality(): string {
     if (this.player && this.playerReady) {
@@ -1462,8 +1364,22 @@ export class YouTubeEmbed extends HTMLElement {
   }
 
   /**
-   * Set the playback quality
-   * @param quality The desired quality level
+   * Set the playback quality.
+   *
+   * @deprecated Since October 2019 - YouTube deprecated this API. This method is a NO-OP and has NO EFFECT.
+   * According to YouTube's official documentation update (Oct 24, 2019), setPlaybackQuality() is now a no-op function
+   * that does nothing. YouTube automatically controls quality based on network conditions and device capabilities.
+   * Any calls to this method will be silently ignored by YouTube's player.
+   * See: https://support.google.com/youtube/answer/91449
+   *
+   * CRITICAL: This method is kept for API compatibility only to prevent breaking existing code.
+   * It does NOT change video quality for YouTube videos. Use Vimeo or HTML5 video if manual quality control is required.
+   *
+   * Wraps YouTube IFrame API's `setPlaybackQuality(suggestedQuality)` method (deprecated - no-op).
+   *
+   * @param quality The desired quality level (IGNORED by YouTube)
+   * @see https://developers.google.com/youtube/iframe_api_reference#setPlaybackQuality
+   * @see https://developers.google.com/youtube/iframe_api_reference#Revision_History (October 24, 2019)
    */
   setQuality(quality: string): void {
     if (!this.player || !this.playerReady) {
@@ -1472,20 +1388,12 @@ export class YouTubeEmbed extends HTMLElement {
     }
 
     try {
-      const oldQuality = this.getCurrentQuality();
+      // Set playback quality
+      // Note: This is only a suggestion - YouTube may ignore it based on various factors
       this.player.setPlaybackQuality(quality);
-
-      // Dispatch quality change event
-      const event = new CustomEvent("qualitychange", {
-        detail: {
-          oldQuality,
-          newQuality: quality,
-          availableQualities: this.getAvailableQualities(),
-        },
-        bubbles: true,
-        composed: true,
-      });
-      this.dispatchEvent(event);
+      this.log("YouTubeEmbed: Quality change requested:", quality);
+      // Note: Quality change event will be dispatched by onPlaybackQualityChange callback
+      // if YouTube honors the request
     } catch (error) {
       this.warn("YouTubeEmbed: Could not set quality:", error);
     }
@@ -1494,7 +1402,11 @@ export class YouTubeEmbed extends HTMLElement {
   // Public API for getting current playback time
   /**
    * Gets the current playback time in seconds.
+   *
+   * Wraps YouTube IFrame API's `getCurrentTime()` method.
+   *
    * @returns The current time in seconds.
+   * @see https://developers.google.com/youtube/iframe_api_reference#getCurrentTime
    */
   public getCurrentTime(): number {
     if (this.player && this.playerReady) {
@@ -1510,23 +1422,57 @@ export class YouTubeEmbed extends HTMLElement {
     return 0;
   }
 
+  /**
+   * Seeks to a specific time in the video.
+   *
+   * Wraps YouTube IFrame API's `seekTo(seconds, allowSeekAhead)` method.
+   *
+   * @param seconds The time in seconds to seek to.
+   * @see https://developers.google.com/youtube/iframe_api_reference#seekTo
+   */
+  public seekTo(seconds: number): void {
+    if (this.player && this.playerReady) {
+      try {
+        this.player.seekTo(seconds, true);
+        this.log("YouTubeEmbed: Seeked to:", seconds);
+      } catch (error) {
+        this.warn("YouTubeEmbed: Could not seek to time:", error);
+      }
+    } else {
+      this.warn("YouTubeEmbed: Player not ready for seeking");
+    }
+  }
+
+  /**
+   * Property getter/setter for current playback time
+   */
+  get currentTime(): number {
+    return this.getCurrentTime();
+  }
+
+  set currentTime(seconds: number) {
+    this.seekTo(seconds);
+  }
+
   // Public API for setting video by ID or URL
   /**
-   * Loads a new video by its ID or URL.
+   * Loads a new video by its ID or URL. If no parameter is provided, loads the current video (useful for triggering lazy load).
    * @param videoIdOrUrl The 11-character video ID or the full YouTube URL.
    */
-  public loadVideo(videoIdOrUrl: string) {
-    // Determine if input is a full URL or a plain video ID
-    const extracted = this.extractVideoId(videoIdOrUrl);
-    if (extracted) {
-      this.#url = videoIdOrUrl;
-      this.#videoId = extracted;
-    } else {
-      this.#videoId = videoIdOrUrl;
+  public loadVideo(videoIdOrUrl?: string) {
+    if (videoIdOrUrl) {
+      // Determine if input is a full URL or a plain video ID
+      const extracted = this.extractVideoId(videoIdOrUrl);
+      if (extracted) {
+        this.#url = videoIdOrUrl;
+        this.#videoId = extracted;
+      } else {
+        this.#videoId = videoIdOrUrl;
+      }
     }
 
     // If component is lazy, load immediately when requested
-    if (this.#lazy && !this.player) {
+    if (this._lazy && !this.player) {
       try {
         this.initializePlayer(this.#videoId);
       } catch (error) {