@smartimpact-it/modern-video-embed 2.0.1

package/src/components/YouTubeEmbed.ts

@@ -0,0 +1,1568 @@
+export class YouTubeEmbed extends HTMLElement {
+  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 updatingMutedState = false; // Flag to prevent sync from overwriting programmatic mute changes
+
+  /** 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",
+      "video-id",
+      "autoplay",
+      "controls",
+      "lazy",
+      "muted",
+      "poster",
+      "background",
+      "player-vars",
+      "quality",
+    ];
+  }
+
+  attributeChangedCallback(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null
+  ) {
+    // Skip processing if we're currently updating an attribute to prevent infinite loops
+    if (this.updatingAttribute) {
+      return;
+    }
+
+    this.log(
+      `YouTubeEmbed: Attribute changed - ${name}: ${oldValue} -> ${newValue}`
+    );
+
+    switch (name) {
+      case "url":
+        this.#url = newValue || "";
+        this.#videoId = this.extractVideoId(this.#url);
+        if (this.initialized) {
+          this.reinitializePlayer();
+        }
+        break;
+      case "video-id":
+        this.#videoId = newValue || "";
+        if (this.initialized) {
+          this.reinitializePlayer();
+        }
+        break;
+      case "autoplay":
+        this.#autoplay = newValue !== null;
+        if (
+          !this.#playing &&
+          this.#autoplay &&
+          !this.#lazy &&
+          this.initialized
+        ) {
+          this.play();
+        }
+        break;
+      case "controls":
+        this.#controls = newValue !== null;
+        if (this.initialized) {
+          this.reinitializePlayer();
+        }
+        break;
+      case "lazy":
+        this.#lazy = newValue !== null;
+        break;
+      case "muted":
+        this.#muted = newValue !== null;
+        if (this.player && this.playerReady) {
+          if (this.#muted) {
+            this.player.mute();
+          } else {
+            this.player.unMute();
+          }
+        }
+        break;
+      case "poster":
+        this.#poster = newValue || "";
+        if (this.#lazy && !this.player) {
+          this.showPoster(this.#videoId);
+        }
+        break;
+      case "background":
+        this.#background = newValue !== null;
+        this.#updateBackgroundMode();
+        break;
+      case "player-vars":
+        try {
+          this.#playerVars = newValue ? JSON.parse(newValue) : {};
+        } catch (e) {
+          this.error("YouTubeEmbed: Invalid player-vars JSON:", e);
+          this.#playerVars = {};
+        }
+        if (this.initialized) {
+          this.reinitializePlayer();
+        }
+        break;
+      case "quality":
+        if (newValue && this.player && this.playerReady) {
+          this.setQuality(newValue);
+        }
+        break;
+    }
+  }
+
+  // Getters and setters for attributes
+  /**
+   * Gets or sets the full YouTube URL.
+   * When set, it automatically extracts the video ID and reinitializes the player.
+   */
+  get url() {
+    return this.#url;
+  }
+  set url(value: string) {
+    this.#url = value;
+    this.#videoId = this.extractVideoId(value);
+    if (this.initialized) {
+      this.reinitializePlayer();
+    }
+  }
+
+  /**
+   * Gets or sets the 11-character YouTube video ID.
+   * Reinitializes the player when set.
+   */
+  get videoId() {
+    return this.#videoId;
+  }
+  set videoId(value: string) {
+    this.#videoId = value;
+    if (this.initialized) {
+      this.reinitializePlayer();
+    }
+  }
+
+  /**
+   * Gets or sets the autoplay state.
+   * Note: Autoplay is subject to browser policies and usually requires the video to be muted.
+   */
+  get autoplay() {
+    return this.#autoplay;
+  }
+  set autoplay(value: boolean) {
+    this.#autoplay = value;
+    this.#reflectBooleanAttribute("autoplay", value);
+    if (!this.#playing && value && !this.#lazy && this.initialized) {
+      this.play();
+    }
+  }
+
+  /**
+   * Gets or sets whether native YouTube player controls are visible.
+   */
+  get controls() {
+    return this.#controls;
+  }
+  set controls(value: boolean) {
+    this.#controls = value;
+    this.#reflectBooleanAttribute("controls", value);
+    if (this.initialized) {
+      this.reinitializePlayer();
+    }
+  }
+
+  /**
+   * Gets or sets the lazy-loading behavior.
+   * If true, a poster is shown, and the video loads only on user interaction.
+   */
+  get lazy() {
+    return this.#lazy;
+  }
+  set lazy(value: boolean) {
+    this.#lazy = value;
+    this.#reflectBooleanAttribute("lazy", value);
+  }
+
+  /**
+   * Gets or sets the muted state of the video.
+   */
+  get muted() {
+    return this.#muted;
+  }
+  set muted(value: boolean) {
+    this.#muted = value;
+    this.#reflectBooleanAttribute("muted", value);
+    if (this.player && this.playerReady) {
+      this.updatingMutedState = true;
+      if (value) {
+        this.player.mute();
+      } else {
+        this.player.unMute();
+      }
+      // Reset flag after a short delay to allow YouTube API to process
+      setTimeout(() => {
+        this.updatingMutedState = false;
+      }, 100);
+    }
+  }
+
+  /**
+   * Gets or sets the URL for a custom poster image.
+   * If not set, a default YouTube thumbnail is used for lazy-loaded videos.
+   */
+  get poster() {
+    return this.#poster;
+  }
+  set poster(value: string) {
+    this.#poster = value;
+    this.updatingAttribute = true;
+    if (value) {
+      this.setAttribute("poster", value);
+    } else {
+      this.removeAttribute("poster");
+    }
+    this.updatingAttribute = false;
+    if (this.#lazy && !this.player) {
+      this.showPoster(this.#videoId);
+    }
+  }
+
+  /**
+   * Returns `true` if the video is currently playing.
+   */
+  get playing() {
+    return this.#playing;
+  }
+
+  /**
+   * Gets or sets the background mode.
+   * In background mode, the video covers its container, is muted, and has no controls.
+   */
+  get background() {
+    return this.#background;
+  }
+  set background(value: boolean) {
+    this.#background = value;
+    this.#reflectBooleanAttribute("background", value);
+    this.#updateBackgroundMode();
+  }
+
+  /**
+   * Gets or sets extra player parameters.
+   * @param {Record<string, string | number | boolean>} vars - An object of key-value pairs to pass to the player.
+   */
+  get playerVars() {
+    return this.#playerVars;
+  }
+  set playerVars(vars: Record<string, string | number | boolean>) {
+    this.#playerVars = vars;
+    this.setAttribute("player-vars", JSON.stringify(vars));
+    if (this.initialized) {
+      this.reinitializePlayer();
+    }
+  }
+
+  #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
+    const regex =
+      /(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^"&?\/ ]{11})/;
+    const match = url.match(regex);
+
+    if (match && match[1]) {
+      return match[1];
+    }
+
+    // If it's already just an ID
+    if (/^[a-zA-Z0-9_-]{11}$/.test(url)) {
+      return url;
+    }
+
+    this.warn(`YouTubeEmbed: Could not extract video ID from "${url}"`);
+    return "";
+  }
+
+  private log(...args: any[]) {
+    if (YouTubeEmbed.DEBUG) {
+      console.log("YouTubeEmbed:", ...args);
+    }
+  }
+
+  private warn(...args: any[]) {
+    console.warn(...args);
+  }
+
+  private error(...args: any[]) {
+    console.error(...args);
+  }
+
+  private dispatchCustomEvent(eventName: string, detail?: any) {
+    this.dispatchEvent(
+      new CustomEvent(eventName, {
+        detail,
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private isValidPosterUrl(url: string): boolean {
+    if (!url) return false;
+    try {
+      new URL(url);
+      // Exclude known problematic domains
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 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
+   */
+  private addResourceHints(): void {
+    const hints = [
+      { rel: "preconnect", href: "https://www.youtube.com" },
+      { rel: "preconnect", href: "https://i.ytimg.com" },
+      { rel: "dns-prefetch", href: "https://www.youtube.com" },
+      { rel: "dns-prefetch", href: "https://i.ytimg.com" },
+    ];
+
+    hints.forEach(({ rel, href }) => {
+      if (!document.querySelector(`link[rel="${rel}"][href="${href}"]`)) {
+        const link = document.createElement("link");
+        link.rel = rel;
+        link.href = href;
+        if (rel === "preconnect") {
+          link.crossOrigin = "anonymous";
+        }
+        document.head.appendChild(link);
+      }
+    });
+  }
+
+  /**
+   * Setup Intersection Observer for lazy loading
+   */
+  private setupIntersectionObserver(): void {
+    if (!("IntersectionObserver" in window)) {
+      // Fallback: load immediately if IntersectionObserver not supported
+      return;
+    }
+
+    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";
+
+          if (!shouldAutoplay) {
+            // Just load the player, don't autoplay
+            this.initializePlayer(this.#videoId);
+          }
+
+          // Disconnect observer after loading
+          if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+          }
+        }
+      });
+    }, options);
+
+    this.intersectionObserver.observe(this);
+  }
+
+  /**
+   * Display error message to user with retry option
+   */
+  private showErrorMessage(message: string): void {
+    const errorDiv = document.createElement("div");
+    errorDiv.className = "youtube-error-message";
+    errorDiv.setAttribute("role", "alert");
+    errorDiv.innerHTML = `
+      <div class="error-content">
+        <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <circle cx="12" cy="12" r="10"></circle>
+          <line x1="12" y1="8" x2="12" y2="12"></line>
+          <line x1="12" y1="16" x2="12.01" y2="16"></line>
+        </svg>
+        <p class="error-message">${message}</p>
+        <button class="retry-button">Retry</button>
+      </div>
+    `;
+
+    const retryButton = errorDiv.querySelector(".retry-button");
+    if (retryButton) {
+      retryButton.addEventListener("click", () => {
+        this.apiLoadRetries = 0;
+        errorDiv.remove();
+        if (this.#videoId) {
+          this.initializePlayer(this.#videoId);
+        }
+      });
+    }
+
+    // Clear existing content
+    this.innerHTML = "";
+    this.appendChild(errorDiv);
+  }
+
+  connectedCallback() {
+    YouTubeEmbed.instanceCount++;
+    this.log(
+      "YouTubeEmbed: connectedCallback called, instance count:",
+      YouTubeEmbed.instanceCount
+    );
+
+    // Add resource hints on first instance
+    if (YouTubeEmbed.instanceCount === 1) {
+      this.addResourceHints();
+    }
+
+    // Initialize attributes from HTML
+    const urlAttr = this.getAttribute("url");
+    const videoIdAttr = this.getAttribute("video-id");
+
+    if (urlAttr) {
+      this.#url = urlAttr;
+      this.#videoId = this.extractVideoId(urlAttr);
+    } else if (videoIdAttr) {
+      this.#videoId = 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") || "";
+    try {
+      const playerVarsAttr = this.getAttribute("player-vars");
+      this.#playerVars = playerVarsAttr ? JSON.parse(playerVarsAttr) : {};
+    } catch (e) {
+      this.error("YouTubeEmbed: Invalid player-vars JSON on init:", e);
+      this.#playerVars = {};
+    }
+
+    if (!this.#videoId) {
+      this.error("YouTubeEmbed: Missing or invalid video ID");
+      this.dispatchCustomEvent("error", {
+        message: "Missing or invalid video ID",
+      });
+      return;
+    }
+
+    // Use the element itself as the container
+    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);
+
+    // Setup keyboard event handlers
+    this.setupKeyboardHandlers();
+
+    // Setup fullscreen change listener
+    this.setupFullscreenListener();
+
+    this.#updateBackgroundMode();
+
+    if (this.#lazy) {
+      this.showPoster(this.#videoId);
+      // Setup Intersection Observer for better performance
+      this.setupIntersectionObserver();
+    } 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
+    );
+
+    // Stop the video and destroy the player instance
+    if (this.player) {
+      try {
+        this.player.destroy();
+        this.log("YouTubeEmbed: Player destroyed.");
+      } catch (error) {
+        this.warn("YouTubeEmbed: Error destroying player:", error);
+      }
+      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() {
+    if (!this.initialized || !this.#videoId) {
+      return;
+    }
+
+    // Remove existing player
+    if (this.player) {
+      try {
+        this.player.destroy();
+      } catch (error) {
+        this.warn("YouTubeEmbed: Error destroying player:", error);
+      }
+    }
+
+    // Clear and reinitialize
+    if (this.#lazy) {
+      this.showPoster(this.#videoId);
+    } else {
+      this.initializePlayer(this.#videoId);
+    }
+  }
+
+  private showPoster(videoId: string) {
+    // Use custom poster if valid, otherwise use YouTube thumbnail
+    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 old event listeners if they exist
+    if (this.posterClickHandler) {
+      this.posterClickHandler = null;
+    }
+
+    // Create poster image
+    const poster = document.createElement("img");
+    poster.src = thumbnailUrl;
+    poster.alt = "YouTube Video Thumbnail";
+    poster.classList.add("youtube-poster", "video-poster"); // Add both classes for compatibility
+    poster.loading = "lazy"; // Optimize image loading
+
+    // Add error handling for poster loading
+    poster.onerror = () => {
+      this.warn("YouTubeEmbed: Poster failed to load, using white background.");
+      poster.style.display = "none";
+      this.style.backgroundColor = "#FFFFFF";
+    };
+
+    // Create button overlay with play button
+    const buttonOverlay = document.createElement("div");
+    buttonOverlay.classList.add("button-overlay");
+    buttonOverlay.setAttribute("role", "button");
+    buttonOverlay.setAttribute("tabindex", "0");
+    buttonOverlay.setAttribute("aria-label", "Play video");
+
+    const button = document.createElement("div");
+    button.classList.add("button");
+    button.setAttribute("aria-hidden", "true");
+
+    buttonOverlay.appendChild(button);
+
+    // Handle click to load video - store reference for cleanup
+    const loadVideo: EventListener = () => {
+      this.log("YouTubeEmbed: Loading video from poster click");
+      this.setAttribute("data-poster-autoplay", "true");
+      try {
+        this.initializePlayer(videoId);
+      } catch (error) {
+        this.error(
+          "YouTubeEmbed: Error initializing player from poster:",
+          error
+        );
+        this.dispatchCustomEvent("error", { message: "Failed to load video" });
+      }
+    };
+
+    // Store reference for cleanup
+    this.posterClickHandler = loadVideo;
+
+    // Add keyboard support
+    const keyboardActivate = (e: KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        loadVideo(e);
+      }
+    };
+
+    poster.addEventListener("click", loadVideo);
+    buttonOverlay.addEventListener("click", loadVideo);
+    buttonOverlay.addEventListener(
+      "keydown",
+      keyboardActivate as EventListener
+    );
+
+    this.appendChild(poster);
+    this.appendChild(buttonOverlay);
+
+    this.log("YouTubeEmbed: Poster displayed for lazy loading");
+  }
+
+  private async initializePlayer(videoId: string) {
+    this.log("YouTubeEmbed: Initializing player for video ID:", videoId);
+
+    const isBackground = this.#background;
+    // Background videos must autoplay and be muted, with no controls.
+    const autoplay =
+      isBackground ||
+      this.hasAttribute("autoplay") ||
+      this.hasAttribute("data-poster-autoplay") ||
+      this.hasAttribute("data-should-autoplay");
+    const controls = isBackground ? false : this.hasAttribute("controls");
+    const mute = isBackground || autoplay; // Mute if background or if autoplaying
+
+    // Remove the temporary autoplay flags
+    if (this.hasAttribute("data-poster-autoplay")) {
+      this.removeAttribute("data-poster-autoplay");
+    }
+    if (this.hasAttribute("data-should-autoplay")) {
+      this.removeAttribute("data-should-autoplay");
+    }
+
+    this.log(
+      "YouTubeEmbed: Creating iframe with autoplay:",
+      autoplay,
+      "controls:",
+      controls
+    );
+
+    this.iframe = document.createElement("iframe");
+
+    // Build URL parameters to handle YouTube's strict policies
+    const params = new URLSearchParams({
+      enablejsapi: "1",
+      autoplay: autoplay ? "1" : "0",
+      controls: !controls && !isBackground ? "1" : "0",
+      mute: mute ? "1" : "0",
+      playsinline: "1", // Better mobile support
+      rel: "0", // Don't show related videos
+      modestbranding: "1", // Reduce YouTube branding
+      origin: window.location.origin || "localhost", // CORS safety
+      ...this.#playerVars,
+    });
+
+    // Add muted state if explicitly set
+    if (this.#muted) {
+      params.set("mute", "1");
+    }
+
+    // Update internal muted state if autoplay forces muting
+    if (autoplay && !this.#muted) {
+      this.#muted = true;
+      this.log(
+        "YouTubeEmbed: Autoplay enabled, forcing muted state for compliance"
+      );
+    }
+
+    this.iframe.src = `https://www.youtube.com/embed/${videoId}?${params.toString()}`;
+    this.iframe.allow =
+      "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share";
+    this.iframe.allowFullscreen = true;
+    this.iframe.style.position = "absolute";
+    this.iframe.style.border = "none";
+
+    // Disable pointer events in background mode to allow clicks to pass through
+    if (this.#background) {
+      this.iframe.style.pointerEvents = "none";
+      // CSS handles the sizing for background videos
+    } else {
+      this.iframe.style.top = "0";
+      this.iframe.style.left = "0";
+      this.iframe.style.width = "100%";
+      this.iframe.style.height = "100%";
+    }
+
+    this.log("YouTubeEmbed: Iframe created with src:", this.iframe.src);
+
+    this.replaceChildren(this.iframe);
+
+    if (!controls) {
+      this.addCustomControls();
+    }
+
+    // Initialize the YouTube API player for advanced control
+    try {
+      await YouTubeEmbed.loadYouTubeAPIWithRetry(this.apiLoadRetries);
+      this.player = new YT.Player(this.iframe, {
+        videoId,
+        events: {
+          onReady: () => {
+            this.log("YouTubeEmbed: Player is ready.");
+            this.playerReady = true;
+
+            // Sync muted state with YouTube player
+            if (this.#muted) {
+              this.player.mute();
+            } else {
+              this.player.unMute();
+            }
+
+            // Check if autoplay was enabled during initialization and update custom control state
+            if (autoplay && this.setCustomControlState) {
+              this.setCustomControlState(true);
+              this.#playing = true;
+            }
+
+            this.dispatchCustomEvent("ready");
+          },
+          onStateChange: (event: any) => {
+            const isPlaying = event.data === YT.PlayerState.PLAYING;
+            const isPaused = event.data === YT.PlayerState.PAUSED;
+            const isEnded = event.data === YT.PlayerState.ENDED;
+
+            this.#playing = isPlaying;
+
+            // Sync muted state with actual player state (only if not programmatically updating)
+            try {
+              if (
+                !this.updatingMutedState &&
+                this.player &&
+                typeof this.player.isMuted === "function"
+              ) {
+                const actualMuted = this.player.isMuted();
+                if (actualMuted !== this.#muted) {
+                  this.#muted = actualMuted;
+                  this.log("YouTubeEmbed: Synced muted state:", actualMuted);
+                }
+              }
+            } catch (error) {
+              this.warn("YouTubeEmbed: Could not sync muted state:", error);
+            }
+
+            // Update custom control state based on player state
+            if (this.setCustomControlState) {
+              this.setCustomControlState(isPlaying);
+            }
+
+            // Dispatch appropriate events
+            if (isPlaying) {
+              this.dispatchCustomEvent("play");
+            } else if (isPaused) {
+              this.dispatchCustomEvent("pause");
+            } else if (isEnded) {
+              this.dispatchCustomEvent("ended");
+            }
+          },
+          onError: (event: YT["OnErrorEvent"]) => {
+            this.error("YouTubeEmbed: Player encountered an error:", event);
+            let errorMessage = "Unknown error occurred";
+
+            // Handle specific YouTube error codes
+            switch (event.data) {
+              case 2:
+                errorMessage = "Invalid video ID";
+                break;
+              case 5:
+                errorMessage = "HTML5 player error";
+                break;
+              case 100:
+                errorMessage = "Video not found or private";
+                break;
+              case 101:
+              case 150:
+                errorMessage =
+                  "Video cannot be embedded (restrictions by owner)";
+                break;
+              default:
+                errorMessage = `YouTube error code: ${event.data}`;
+            }
+
+            this.dispatchCustomEvent("error", {
+              message: errorMessage,
+              code: event.data,
+            });
+          },
+        },
+      });
+    } catch (error) {
+      this.error("YouTubeEmbed: YouTube API initialization failed:", error);
+      this.showErrorMessage(
+        error instanceof Error
+          ? error.message
+          : "Failed to load YouTube player. Please refresh the page or check your connection."
+      );
+      this.dispatchCustomEvent("error", {
+        message: error instanceof Error ? error.message : "API load failed",
+        code: "API_LOAD_ERROR",
+        retryable: true,
+      });
+    }
+  }
+
+  private static async loadYouTubeAPI(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.apiReady) {
+        resolve();
+        return;
+      }
+
+      const timeoutId = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            "YouTube API loading timeout. The API script may be blocked by an ad blocker or network issue."
+          )
+        );
+      }, this.API_LOAD_TIMEOUT);
+
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        delete window.onYouTubeIframeAPIReady;
+      };
+
+      if (!this.apiLoaded) {
+        const script = document.createElement("script");
+        script.src = "https://www.youtube.com/iframe_api";
+        script.onerror = () => {
+          cleanup();
+          reject(
+            new Error(
+              "Failed to load YouTube API script. Please check your network connection or disable ad blockers."
+            )
+          );
+        };
+        document.head.appendChild(script);
+        this.apiLoaded = true;
+      }
+
+      window.onYouTubeIframeAPIReady = () => {
+        this.apiReady = true;
+        cleanup();
+        resolve();
+      };
+    });
+  }
+
+  /**
+   * Load YouTube API with retry mechanism
+   */
+  private static async loadYouTubeAPIWithRetry(retries = 0): Promise<void> {
+    try {
+      await this.loadYouTubeAPI();
+    } catch (error) {
+      if (retries < this.MAX_API_RETRIES) {
+        console.warn(
+          `YouTubeEmbed: API load failed, retrying (${retries + 1}/${
+            this.MAX_API_RETRIES
+          })...`
+        );
+        await new Promise((resolve) =>
+          setTimeout(resolve, this.API_RETRY_DELAY)
+        );
+        return this.loadYouTubeAPIWithRetry(retries + 1);
+      }
+      throw error;
+    }
+  }
+
+  private addCustomControls() {
+    this.classList.add("youtube-embed-container");
+
+    // Create button overlay
+    const buttonOverlay = document.createElement("div");
+    buttonOverlay.classList.add("button-overlay");
+
+    this.playPauseButton = document.createElement("div");
+    this.playPauseButton.classList.add("button");
+    let isPlaying = false;
+
+    const setPlayingState = (playing: boolean) => {
+      isPlaying = playing;
+      if (playing) {
+        this.classList.add("is-playing");
+      } else {
+        this.classList.remove("is-playing");
+      }
+    };
+
+    const togglePlayPause = () => {
+      if (isPlaying) {
+        // Pause the video
+        if (this.player && typeof this.player.pauseVideo === "function") {
+          this.player.pauseVideo();
+        } else if (this.iframe && this.iframe.contentWindow) {
+          this.iframe.contentWindow.postMessage(
+            '{"event":"command","func":"pauseVideo","args":""}',
+            "*"
+          );
+        }
+        setPlayingState(false);
+      } else {
+        // Play the video
+        if (this.player && typeof this.player.playVideo === "function") {
+          this.player.playVideo();
+        } else if (this.iframe && this.iframe.contentWindow) {
+          this.iframe.contentWindow.postMessage(
+            '{"event":"command","func":"playVideo","args":""}',
+            "*"
+          );
+        }
+        setPlayingState(true);
+      }
+    };
+
+    // Store reference to setPlayingState for external control
+    this.setCustomControlState = setPlayingState;
+
+    buttonOverlay.addEventListener("click", togglePlayPause);
+    if (this.playPauseButton) {
+      buttonOverlay.appendChild(this.playPauseButton);
+    }
+    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.
+   */
+  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) {
+      this.log(
+        "YouTubeEmbed: Lazy video needs to be loaded first. Initializing..."
+      );
+      // Set a flag to auto-play after initialization
+      this.setAttribute("data-should-autoplay", "true");
+      // Initialize the player (this will load the video and replace the poster)
+      await this.initializePlayer(this.#videoId);
+      // Wait a bit for the player to be ready after initialization
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    if (!this.playerReady) {
+      this.warn(
+        "YouTubeEmbed: Player is not ready. Waiting for initialization."
+      );
+      await new Promise((resolve) => {
+        const interval = setInterval(() => {
+          if (this.playerReady) {
+            clearInterval(interval);
+            resolve(null);
+          }
+        }, 100);
+        // Timeout after 5 seconds
+        setTimeout(() => {
+          clearInterval(interval);
+          resolve(null);
+        }, 5000);
+      });
+    }
+
+    // Remove the autoplay flag if it was set
+    this.removeAttribute("data-should-autoplay");
+
+    if (this.player && typeof this.player.playVideo === "function") {
+      this.player.playVideo();
+      this.log("YouTubeEmbed: Video playback started via API.");
+    } else {
+      this.log("YouTubeEmbed: Using iframe postMessage for play.");
+      // Fallback: try to use postMessage to control iframe
+      if (this.iframe && this.iframe.contentWindow) {
+        this.iframe.contentWindow.postMessage(
+          '{"event":"command","func":"playVideo","args":""}',
+          "*"
+        );
+      }
+    }
+
+    this.#playing = true;
+    // Update custom control state
+    if (this.setCustomControlState) {
+      this.setCustomControlState(true);
+    }
+
+    this.dispatchCustomEvent("play");
+  }
+
+  /**
+   * Pauses the currently playing video.
+   */
+  public pause() {
+    if (this.player && typeof this.player.pauseVideo === "function") {
+      this.player.pauseVideo();
+      this.log("YouTubeEmbed: Video paused via API.");
+    } else {
+      this.log("YouTubeEmbed: Using iframe postMessage for pause.");
+      // Fallback: try to use postMessage to control iframe
+      if (this.iframe && this.iframe.contentWindow) {
+        this.iframe.contentWindow.postMessage(
+          '{"event":"command","func":"pauseVideo","args":""}',
+          "*"
+        );
+      }
+    }
+
+    this.#playing = false;
+    // Update custom control state
+    if (this.setCustomControlState) {
+      this.setCustomControlState(false);
+    }
+
+    this.dispatchCustomEvent("pause");
+  }
+
+  /**
+   * Stops the video and resets it to the beginning.
+   */
+  public stopVideo() {
+    if (this.player && typeof this.player.stopVideo === "function") {
+      this.player.stopVideo();
+      this.log("YouTubeEmbed: Video stopped via API.");
+    } else {
+      this.log("YouTubeEmbed: Using iframe postMessage for stop.");
+      // Fallback: try to use postMessage to control iframe
+      if (this.iframe && this.iframe.contentWindow) {
+        this.iframe.contentWindow.postMessage(
+          '{"event":"command","func":"stopVideo","args":""}',
+          "*"
+        );
+      }
+    }
+
+    this.#playing = false;
+    // Update custom control state
+    if (this.setCustomControlState) {
+      this.setCustomControlState(false);
+    }
+
+    this.dispatchCustomEvent("stop");
+  }
+
+  /**
+   * Mutes the video audio.
+   */
+  public mute() {
+    this.muted = true;
+  }
+
+  /**
+   * Unmutes the video audio.
+   */
+  public unmute() {
+    this.muted = false;
+  }
+
+  /**
+   * Toggles the video between playing and paused.
+   */
+  public togglePlay() {
+    if (this.#playing) {
+      this.pause();
+    } else {
+      this.play();
+    }
+  }
+
+  /**
+   * Toggles the audio between muted and unmuted.
+   */
+  public toggleMute() {
+    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 API for getting player state
+  /**
+   * Retrieves the current state of the player.
+   * @returns An object with the current player state.
+   */
+  public getPlayerState() {
+    // Get actual muted state from YouTube player if available
+    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;
+        }
+      } catch (error) {
+        // Fallback to internal state if player method fails
+        this.warn(
+          "YouTubeEmbed: Could not get muted state from player:",
+          error
+        );
+      }
+    }
+
+    return {
+      playing: this.#playing,
+      muted: actualMutedState,
+      videoId: this.#videoId,
+      ready: this.playerReady,
+      initialized: this.initialized,
+    };
+  }
+
+  // Public API for checking if video is playing
+  /**
+   * Checks if the video is currently playing.
+   * @returns `true` if the video is playing.
+   */
+  public isPlaying(): boolean {
+    return this.#playing;
+  }
+
+  // Public API for checking if video is muted
+  /**
+   * Checks if the video is currently muted.
+   * @returns `true` if the video is muted.
+   */
+  public isMuted(): boolean {
+    if (this.player && this.playerReady) {
+      try {
+        return this.player.isMuted();
+      } catch (error) {
+        this.warn(
+          "YouTubeEmbed: Could not get muted state from player:",
+          error
+        );
+      }
+    }
+    return this.#muted;
+  }
+
+  /**
+   * Request fullscreen mode
+   */
+  enterFullscreen(): Promise<void> {
+    const elem = this as any;
+    if (elem.requestFullscreen) {
+      return elem.requestFullscreen();
+    } else if (elem.webkitRequestFullscreen) {
+      return elem.webkitRequestFullscreen();
+    } else if (elem.mozRequestFullScreen) {
+      return elem.mozRequestFullScreen();
+    } else if (elem.msRequestFullscreen) {
+      return elem.msRequestFullscreen();
+    }
+    return Promise.reject(new Error("Fullscreen API not supported"));
+  }
+
+  /**
+   * Exit fullscreen mode
+   */
+  exitFullscreen(): Promise<void> {
+    const doc = document as any;
+    if (doc.exitFullscreen) {
+      return doc.exitFullscreen();
+    } else if (doc.webkitExitFullscreen) {
+      return doc.webkitExitFullscreen();
+    } else if (doc.mozCancelFullScreen) {
+      return doc.mozCancelFullScreen();
+    } else if (doc.msExitFullscreen) {
+      return doc.msExitFullscreen();
+    }
+    return Promise.reject(new Error("Fullscreen API not supported"));
+  }
+
+  /**
+   * Toggle fullscreen mode
+   */
+  async toggleFullscreen(): Promise<void> {
+    if (this.isFullscreen()) {
+      await this.exitFullscreen();
+    } else {
+      await this.enterFullscreen();
+    }
+  }
+
+  /**
+   * Check if currently in fullscreen mode
+   */
+  isFullscreen(): boolean {
+    const doc = document as any;
+    return !!(
+      doc.fullscreenElement ||
+      doc.webkitFullscreenElement ||
+      doc.mozFullScreenElement ||
+      doc.msFullscreenElement
+    );
+  }
+
+  /**
+   * Get available quality levels for the current video
+   * @returns Array of available quality levels
+   */
+  getAvailableQualities(): string[] {
+    if (this.player && this.playerReady) {
+      try {
+        return this.player.getAvailableQualityLevels() || [];
+      } catch (error) {
+        this.warn("YouTubeEmbed: Could not get available qualities:", error);
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Get the current playback quality
+   * @returns Current quality level
+   */
+  getCurrentQuality(): string {
+    if (this.player && this.playerReady) {
+      try {
+        return this.player.getPlaybackQuality() || "auto";
+      } catch (error) {
+        this.warn("YouTubeEmbed: Could not get current quality:", error);
+      }
+    }
+    return "auto";
+  }
+
+  /**
+   * Set the playback quality
+   * @param quality The desired quality level
+   */
+  setQuality(quality: string): void {
+    if (!this.player || !this.playerReady) {
+      this.warn("YouTubeEmbed: Player not ready for quality change");
+      return;
+    }
+
+    try {
+      const oldQuality = this.getCurrentQuality();
+      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);
+    } catch (error) {
+      this.warn("YouTubeEmbed: Could not set quality:", error);
+    }
+  }
+
+  // Public API for getting current playback time
+  /**
+   * Gets the current playback time in seconds.
+   * @returns The current time in seconds.
+   */
+  public getCurrentTime(): number {
+    if (this.player && this.playerReady) {
+      try {
+        return this.player.getCurrentTime() || 0;
+      } catch (error) {
+        this.warn(
+          "YouTubeEmbed: Could not get current time from player:",
+          error
+        );
+      }
+    }
+    return 0;
+  }
+
+  // Public API for setting video by ID or URL
+  /**
+   * Loads a new video by its ID or URL.
+   * @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;
+    }
+
+    // If component is lazy, load immediately when requested
+    if (this.#lazy && !this.player) {
+      try {
+        this.initializePlayer(this.#videoId);
+      } catch (error) {
+        this.warn(
+          "YouTubeEmbed: loadVideo failed to initialize player:",
+          error
+        );
+      }
+      return;
+    }
+
+    // If already initialized, reinitialize player with the new video
+    if (this.initialized) {
+      this.reinitializePlayer();
+    }
+  }
+}
+
+customElements.define("youtube-embed", YouTubeEmbed);
+
+declare global {
+  interface Window {
+    onYouTubeIframeAPIReady?: () => void;
+  }
+}
+
+// Add the YouTube Player API namespace declaration
+interface YT {
+  Player: any;
+  PlayerState: {
+    PLAYING: number;
+    PAUSED: number;
+    ENDED: number;
+  };
+  OnErrorEvent: any; // Add this line
+}
+
+declare const YT: YT;
+
+export {};
+
+// Component ready for testing