feat: accept a slotted <video> as the custom element's source (issue #6) (#7)

* feat: accept a slotted <video> as the custom element's source (issue #6)

<chroma-key-video> now accepts a light-DOM <video> child as its source,
taking precedence over the src attribute. This lets the element key any
source the video element itself supports (WebRTC, hls.js/dash.js-attached
media, MediaStream via srcObject, etc.) instead of only a plain URL, without
adding per-source-type properties. The slotted video is caller-owned:
destroy()/disconnection never pauses or clears it, and swapping the slotted
element at runtime rebuilds the player.

Tests exercise real sources rather than only synthetic captureStream():
a loopback RTCPeerConnection pair for genuine WebRTC SRTP encode/decode,
and hls.js loading a real generated VOD fixture (test/assets/hls/).

* fix(chromakey): address adversarial audit findings on issue #6 slotted-source

- attributeChangedCallback('src', ...) no longer rebuilds the player while
  a slotted <video> is active, since src is a no-op in that state
- ::slotted(video) -> ::slotted(*) so a non-video slotted child stays
  hidden (pre-PR behavior), avoiding a rendering regression from the new
  default <slot>
- document that autoplay/loop/muted/crossorigin only affect a
  library-created video, not a slotted one (JSDoc + README)
- README: document the slotted-<video> source and its precedence over src
- test harness: close WebRTC peer connections and destroy hls.js instances
  after each test instead of leaking them for the rest of the page's life
- add regression test proving a src change is a no-op while a video is
  slotted

Author: zoharbabin

README.md

@@ -105,6 +105,11 @@ The output canvas behaves like an `<img>`. Give it a CSS size, or let it default
 
 `defineChromaKeyVideoElement(tagName?)` registers the element.
 
+- **Source:** either a slotted `<video>` child or the `src` attribute. A slotted `<video>` takes precedence over `src` when both are present, and can be any source the video element itself supports — file, `MediaStream`, WebRTC, hls.js/dash.js-attached, etc.:
+  ```html
+  <chroma-key-video auto-tune><video id="my-live-video"></video></chroma-key-video>
+  ```
+  The slotted video is caller-owned: `autoplay`/`loop`/`muted`/`crossorigin` have no effect on it (configure it directly), and it's never paused or cleared by `destroy()`/disconnection. Swapping the slotted `<video>` at runtime rebuilds the player against the new source.
 - **Attributes:** `src`, `autoplay`, `loop`, `muted`, `channel`, `min-key`, `bias`, `softness`, `spill`, `edge-dissolve`, `auto-tune` (empty = once, `"adaptive"` = continuous), `fade-top`, `fade-bottom`, `max-pixel-ratio`.
 - Numeric attributes update live.
 - The underlying player is exposed as `element.player`.

package-lock.json

@@ -35,6 +35,7 @@
   "license": "MIT",
   "devDependencies": {
     "@playwright/test": "^1.49.0",
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "hls.js": "^1.7.1"
   }
 }

package.json

@@ -1373,10 +1373,21 @@ const ELEMENT_OPTION_ATTRIBUTES = {
 /**
  * Register the `<chroma-key-video>` custom element.
  *
- * Supported attributes: `src` (required), `autoplay`, `loop`, `muted`,
- * `channel`, `min-key`, `bias`, `softness`, `spill`, `edge-dissolve`,
+ * Source: either a slotted `<video>` child (any source the video element
+ * itself supports — file, MediaStream via `srcObject`, WebRTC, hls.js/
+ * dash.js-attached, etc.) or the `src` attribute (a plain URL). A slotted
+ * video takes precedence over `src` when both are present. Swapping the
+ * slotted `<video>` at runtime rebuilds the player; the slotted element is
+ * caller-owned throughout, so `destroy()`/disconnection never pauses or
+ * clears it (see issue #6).
+ *
+ * Other supported attributes: `autoplay`, `loop`, `muted`, `channel`,
+ * `min-key`, `bias`, `softness`, `spill`, `edge-dissolve`,
  * `auto-tune` (empty = once, `"adaptive"` = continuous), `fade-top`,
- * `fade-bottom`, `max-pixel-ratio`, `stall-timeout`.
+ * `fade-bottom`, `max-pixel-ratio`, `stall-timeout`. `autoplay`/`loop`/
+ * `muted`/`crossorigin` only affect a video the element creates itself
+ * (from `src`) — a slotted `<video>` is caller-owned and caller-configured,
+ * so these attributes have no effect on it.
  *
  * The underlying player is exposed as the element's `.player` property for
  * full programmatic control (events, `update()`, the video element, etc.).
@@ -1393,8 +1404,12 @@ export function defineChromaKeyVideoElement(tagName = 'chroma-key-video') {
       super();
       this._root = this.attachShadow({ mode: 'closed' });
       const style = document.createElement('style');
-      style.textContent = ':host{display:inline-block;line-height:0}canvas{display:block;width:100%;height:100%}';
+      style.textContent = ':host{display:inline-block;line-height:0}canvas{display:block;width:100%;height:100%}::slotted(*){display:none}';
       this._root.appendChild(style);
+      this._slot = document.createElement('slot');
+      this._slot.addEventListener('slotchange', () => this._handleSlotChange());
+      this._root.appendChild(this._slot);
+      this._activeVideoSource = null;
       this._player = null;
     }
 
@@ -1405,9 +1420,29 @@ export function defineChromaKeyVideoElement(tagName = 'chroma-key-video') {
 
     disconnectedCallback() { this._teardown(); }
 
+    /** First slotted light-DOM <video> child, or null. */
+    _getSlottedVideo() {
+      for (const child of this.children) {
+        if (child instanceof HTMLVideoElement) return child;
+      }
+      return null;
+    }
+
+    _handleSlotChange() {
+      if (!this.isConnected) return;
+      const newVideo = this._getSlottedVideo();
+      if (newVideo === this._activeVideoSource) return;
+      this._teardown();
+      this._build();
+    }
+
     attributeChangedCallback(name, oldValue, newValue) {
       if (!this.isConnected || oldValue === newValue) return;
       if (name === 'src') {
+        // A slotted video (if present) always wins over src (see _build()),
+        // so a src change is a no-op while one is active — rebuilding here
+        // would destroy and recreate the player against the same source.
+        if (this._getSlottedVideo()) return;
         this._teardown();
         this._build();
         return;
@@ -1441,9 +1476,11 @@ export function defineChromaKeyVideoElement(tagName = 'chroma-key-video') {
     }
 
     _build() {
-      const src = this.getAttribute('src');
-      if (!src) return;
-      this._player = new ChromaKeyVideo(src, this._collectOptions());
+      const slottedVideo = this._getSlottedVideo();
+      const source = slottedVideo || this.getAttribute('src');
+      if (!source) return;
+      this._activeVideoSource = slottedVideo;
+      this._player = new ChromaKeyVideo(source, this._collectOptions());
       this._root.appendChild(this._player.canvas);
       this._lastAppliedAspect = '';
       this._syncAspect = () => syncAspectRatio(this, this._player.video, this);
@@ -1459,6 +1496,7 @@ export function defineChromaKeyVideoElement(tagName = 'chroma-key-video') {
         this._player.destroy();
         this._player = null;
       }
+      this._activeVideoSource = null;
     }
   }
 

src/chromakey.js

@@ -0,0 +1,12 @@
+#EXTM3U
+#EXT-X-VERSION:3
+#EXT-X-TARGETDURATION:1
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXTINF:1.200000,
+segment0.ts
+#EXTINF:1.200000,
+segment1.ts
+#EXTINF:0.600000,
+segment2.ts
+#EXT-X-ENDLIST

test/assets/hls/playlist.m3u8

@@ -44,6 +44,28 @@ function backend(page, id) {
   return page.evaluate((pid) => window.players[pid].player.backend, id);
 }
 
+function webrtcVideo(page, channel = 'green') {
+  return page.evaluate((c) => window.createWebRTCVideo(c), channel);
+}
+
+function hlsVideo(page) {
+  return page.evaluate(() => window.createHlsVideo());
+}
+
+function mountElement(page, attrs = {}, videoId = null) {
+  return page.evaluate(
+    ([a, v]) => window.mountElement(a, v),
+    [attrs, videoId],
+  );
+}
+
+function sampleElement(page, id, point) {
+  return page.evaluate(
+    ([eid, [x, y]]) => window.sampleElement(eid, x, y),
+    [id, point],
+  );
+}
+
 // Resolves with the detail of the next `type` event on player `id`, or
 // rejects if it doesn't fire within `timeoutMs`.
 function waitForEvent(page, id, type, timeoutMs = 5000) {
@@ -69,6 +91,13 @@ test.describe('chroma-key-video', () => {
     await openFixture(page);
   });
 
+  test.afterEach(async ({ page }) => {
+    // Releases RTCPeerConnections/hls.js instances/redraw timers created by
+    // createWebRTCVideo()/createHlsVideo() (issue #6), so they don't linger
+    // for the rest of this page's lifetime across a whole file's test run.
+    await page.evaluate(() => window.cleanupMedia());
+  });
+
   test('WebGL backend keys green to transparent and keeps foreground', async ({ page }) => {
     const id = await create(page);
     expect(await backend(page, id)).toBe('webgl');
@@ -530,4 +559,119 @@ test.describe('chroma-key-video', () => {
 
     expect(await didFire(page, b, 'stalled', 500)).toBe(false);
   });
+
+  test('custom element: keys a slotted <video> fed by a real WebRTC track (issue #6)', async ({ page }) => {
+    const videoId = await webrtcVideo(page);
+    const id = await mountElement(page, {}, videoId);
+
+    const bg = await sampleElement(page, id, SAMPLES.background);
+    expect(bg[3]).toBeLessThanOrEqual(2);
+    const fg = await sampleElement(page, id, SAMPLES.stripe);
+    expect(fg[3]).toBe(255);
+    expect(fg[0]).toBeGreaterThan(180);
+  });
+
+  test('custom element: keys a slotted <video> loaded by hls.js from a real HLS stream (issue #6)', async ({ page }) => {
+    const videoId = await hlsVideo(page);
+    const id = await mountElement(page, { 'auto-tune': true }, videoId);
+
+    const metrics = await page.evaluate((eid) => {
+      const { player } = window.elements[eid];
+      const c = player.canvas;
+      const ctx = c.getContext('2d');
+      const data = ctx.getImageData(0, 0, c.width, c.height).data;
+      let transparent = 0, opaque = 0;
+      const total = data.length / 4;
+      for (let i = 0; i < data.length; i += 4) {
+        if (data[i + 3] < 8) transparent++;
+        if (data[i + 3] > 247) opaque++;
+      }
+      return { transparentFraction: transparent / total, opaqueFraction: opaque / total };
+    }, id);
+
+    expect(metrics.transparentFraction).toBeGreaterThan(0.45);
+    expect(metrics.opaqueFraction).toBeGreaterThan(0.15);
+  });
+
+  test('custom element: a slotted <video> takes precedence over the src attribute (issue #6)', async ({ page }) => {
+    const videoId = await webrtcVideo(page);
+    const url = await page.evaluate(() => window.makePatternVideoURL());
+    const id = await mountElement(page, { src: url }, videoId);
+
+    const usesSlotted = await page.evaluate(
+      ([eid, vid]) => window.elements[eid].player.video.id === vid,
+      [id, videoId],
+    );
+    expect(usesSlotted).toBe(true);
+  });
+
+  test('custom element: changing src while a video is slotted does not rebuild the player (issue #6)', async ({ page }) => {
+    const videoId = await webrtcVideo(page);
+    const url = await page.evaluate(() => window.makePatternVideoURL());
+    const id = await mountElement(page, {}, videoId);
+
+    const rebuilt = await page.evaluate(async ([eid, u]) => {
+      const el = window.elements[eid];
+      const player = el.player;
+      el.setAttribute('src', u);
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      return el.player !== player || player.isDestroyed;
+    }, [id, url]);
+    expect(rebuilt).toBe(false);
+  });
+
+  test('custom element: swapping the slotted <video> at runtime rebuilds the player without leaking the old one (issue #6)', async ({ page }) => {
+    const videoIdA = await webrtcVideo(page);
+    const id = await mountElement(page, {}, videoIdA);
+    const videoIdB = await webrtcVideo(page);
+
+    const result = await page.evaluate(async ([eid, oldVid, newVid]) => {
+      const el = window.elements[eid];
+      const oldPlayer = el.player;
+      el.removeChild(document.getElementById(oldVid));
+      el.appendChild(document.getElementById(newVid));
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error('rebuild never happened')), 10000);
+        const check = () => {
+          if (el.player && el.player !== oldPlayer && el.player.video.id === newVid) {
+            clearTimeout(t);
+            resolve();
+            return;
+          }
+          setTimeout(check, 30);
+        };
+        check();
+      });
+      return { oldDestroyed: oldPlayer.isDestroyed, newVideoId: el.player.video.id };
+    }, [id, videoIdA, videoIdB]);
+
+    expect(result.oldDestroyed).toBe(true);
+    expect(result.newVideoId).toBe(videoIdB);
+  });
+
+  test('custom element: destroy() does not pause or dispose an externally-owned slotted <video> (issue #6)', async ({ page }) => {
+    const videoId = await webrtcVideo(page);
+    const id = await mountElement(page, {}, videoId);
+
+    const before = await page.evaluate((vid) => {
+      const v = document.getElementById(vid);
+      return { paused: v.paused, hasSrcObject: !!v.srcObject };
+    }, videoId);
+    expect(before.paused).toBe(false);
+    expect(before.hasSrcObject).toBe(true);
+
+    // Reclaim the video back into the document (as if the caller keeps it
+    // mounted elsewhere) before tearing the element down, so Chromium's
+    // native "pause on remove from document" behavior for a srcObject video
+    // doesn't mask what destroy() itself does to a caller-owned video.
+    const after = await page.evaluate(([eid, vid]) => {
+      const el = window.elements[eid];
+      const v = document.getElementById(vid);
+      document.body.appendChild(v);
+      el.remove();
+      return { paused: v.paused, hasSrcObject: !!v.srcObject };
+    }, [id, videoId]);
+    expect(after.paused).toBe(false);
+    expect(after.hasSrcObject).toBe(true);
+  });
 });