fix(youtube-video-element): destroy the player on disconnect

The YouTube iframe API keeps an internal reference to every player it
creates, so removing the element is not enough to release the <iframe>:
it stays detached but reachable from `window.YT`, along with everything
the player's event handlers close over. `api.destroy()` is currently
only reachable from `load()` when `src` is cleared, and the element
defines no `disconnectedCallback`, so every mount/unmount cycle leaks a
player. In React this shows up as `Detached HTMLIFrameElement` nodes
accumulating across route changes with `window.YT` as the retainer.

Add `connectedCallback`/`disconnectedCallback` following the pattern
already used in vimeo-video-element: destroy the player and reset the
load state on disconnect, and reload on reconnect so a DOM move still
works (`load()` is otherwise only triggered by attributeChangedCallback,
which does not fire on a move).

Also guard the load itself. `load()` awaits the API script, so an
element disconnected while that is in flight would still attach a player
afterwards, which nothing would ever destroy. A #loadId generation
counter, bumped on disconnect and on each load, makes the superseded
attempt bail out before constructing the player.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 2 people

packages/youtube-video-element/test/test.js

@@ -250,6 +250,48 @@ test('t parameter - case insensitive', async function (t) {
   t.equal(startParam, '171', 'start parameter is set from uppercase T parameter');
 });
 
+test('destroys the player when disconnected', async function (t) {
+  const video = await createVideoElement();
+  await video.loadComplete;
+
+  t.ok(video.api, 'has a player once loaded');
+  t.ok(video.shadowRoot.querySelector('iframe'), 'has an iframe once loaded');
+
+  video.remove();
+
+  t.equal(video.api, null, 'the player reference is released on disconnect');
+  t.equal(video.isLoaded, false, 'the element is no longer marked loaded');
+  t.equal(
+    video.shadowRoot.querySelector('iframe'),
+    null,
+    'destroy() removed the iframe from the shadow root'
+  );
+});
+
+test('creates a new player when reconnected', async function (t) {
+  const video = await createVideoElement();
+  await video.loadComplete;
+
+  const firstApi = video.api;
+  video.remove();
+  document.body.append(video);
+
+  await video.loadComplete;
+
+  t.ok(video.api, 'has a player again after reconnecting');
+  t.ok(video.api !== firstApi, 'a new player was created, not the destroyed one');
+  t.ok(video.shadowRoot.querySelector('iframe'), 'the iframe was rebuilt');
+});
+
+test('disconnecting before the player is ready does not throw', async function (t) {
+  const video = await createVideoElement();
+  // Do not await loadComplete: the API may still be loading.
+  video.remove();
+
+  t.equal(video.api, null, 'no player is left behind');
+  t.ok(true, 'disconnecting mid-load did not throw');
+});
+
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

packages/youtube-video-element/youtube-video-element.js

@@ -147,6 +147,8 @@ class YoutubeVideoElement extends MediaPlayedRangesMixin(globalThis.HTMLElement
   loadComplete = new PublicPromise();
   #loadRequested;
   #hasLoaded;
+  #wasDisconnected = false;
+  #loadId = 0;
   #readyState = 0;
   #seeking = false;
   #seekComplete;
@@ -172,6 +174,12 @@ class YoutubeVideoElement extends MediaPlayedRangesMixin(globalThis.HTMLElement
   async load() {
     if (this.#loadRequested) return;
 
+    // Identifies this load attempt. `load()` awaits the API script, so the
+    // element can be disconnected (or asked to load again) while this one is
+    // still in flight; those bump #loadId and this attempt bails out below
+    // instead of attaching a player nothing will ever destroy.
+    const loadId = ++this.#loadId;
+
     if (!this.shadowRoot) {
       this.attachShadow({ mode: 'open' });
     }
@@ -223,6 +231,10 @@ class YoutubeVideoElement extends MediaPlayedRangesMixin(globalThis.HTMLElement
     }
 
     const YT = await loadScript(API_URL, API_GLOBAL, API_GLOBAL_READY);
+
+    // Superseded by a disconnect or a newer load() while awaiting the API.
+    if (loadId !== this.#loadId) return;
+
     this.api = new YT.Player(iframe, {
       events: {
         onReady: () => {
@@ -357,6 +369,33 @@ class YoutubeVideoElement extends MediaPlayedRangesMixin(globalThis.HTMLElement
     }, 100);
   }
 
+  connectedCallback() {
+    // `load()` is only triggered by attributeChangedCallback, so an element that
+    // is moved in the DOM (disconnected and reconnected without its attributes
+    // changing) has to ask for a new player itself.
+    if (this.#wasDisconnected) {
+      this.#wasDisconnected = false;
+      this.load();
+    }
+    super.connectedCallback?.();
+  }
+
+  disconnectedCallback() {
+    this.#wasDisconnected = true;
+    this.#loadId++;
+    this.#loadRequested = null;
+    this.#hasLoaded = null;
+    this.isLoaded = false;
+    this.loadComplete = new PublicPromise();
+    // The YouTube iframe API holds a reference to every player it creates, so
+    // dropping the element is not enough to release the <iframe>: it stays
+    // detached but reachable from window.YT. destroy() removes the iframe and
+    // deregisters the player.
+    this.api?.destroy?.();
+    this.api = null;
+    super.disconnectedCallback?.();
+  }
+
   async attributeChangedCallback(attrName, oldValue, newValue) {
     if (oldValue === newValue) return;