From 460a3bea4468916d56b9260a09bcd54dcd18bf93 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Wed, 2 Sep 2026 16:47:58 -0700
Subject: [PATCH 01/25] feat(html): add createMediaElement

`createMediaElement(tag, Adapter)` builds a custom element that renders a
native `<video>` or `<audio>`, drives it through the adapter, and registers
with the surrounding player. It is `MediaAttachMixin(CustomMediaElement(...))`
under one name, so an adapter package's consumer can expose an element in one
line the same way the built-in `<hlsjs-video>`, `<dash-video>`, `<hls-video>`,
and Mux elements now do.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/html/src/index.ts                    |  1 +
 .../src/media/cloudflare-video/adapter.ts     | 75 +++++++--------
 .../html/src/media/create-media-element.ts    | 37 ++++++++
 packages/html/src/media/dash-video/adapter.ts |  5 +-
 packages/html/src/media/hls-audio/adapter.ts  |  5 +-
 packages/html/src/media/hls-video/adapter.ts  |  5 +-
 .../html/src/media/hlsjs-video/adapter.ts     |  5 +-
 packages/html/src/media/mux-audio/hls-js.ts   |  5 +-
 packages/html/src/media/mux-audio/spf.ts      |  5 +-
 packages/html/src/media/mux-video/hls-js.ts   |  5 +-
 packages/html/src/media/mux-video/spf.ts      |  5 +-
 .../src/media/native-hls-video/adapter.ts     |  5 +-
 .../html/src/media/shaka-video/adapter.ts     |  5 +-
 .../html/src/media/spotify-audio/adapter.ts   | 87 +++++++++--------
 .../media/tests/create-media-element.test.ts  | 85 +++++++++++++++++
 .../html/src/media/tiktok-video/adapter.ts    | 93 +++++++++----------
 .../html/src/media/twitch-video/adapter.ts    | 77 ++++++++-------
 .../html/src/media/vimeo-video/adapter.ts     | 75 +++++++--------
 .../html/src/media/youtube-video/adapter.ts   | 75 +++++++--------
 .../docs/reference/create-media-element.mdx   | 46 +++++++++
 .../docs/reference/media-attach-mixin.mdx     |  2 +-
 site/src/docs.config.ts                       |  1 +
 22 files changed, 423 insertions(+), 281 deletions(-)
 create mode 100644 packages/html/src/media/create-media-element.ts
 create mode 100644 packages/html/src/media/tests/create-media-element.test.ts
 create mode 100644 site/src/content/docs/reference/create-media-element.mdx

diff --git a/packages/html/src/index.ts b/packages/html/src/index.ts
index 809213e68d..7b444e7b80 100644
--- a/packages/html/src/index.ts
+++ b/packages/html/src/index.ts
@@ -69,6 +69,7 @@ export { i18nContext } from './i18n/context';
 export * from './player/context';
 export * from './player/create-player';
 export { PlayerController, type PlayerControllerHost } from './player/player-controller';
+export { createMediaElement } from './media/create-media-element';
 export * from './store/media-attach-mixin';
 export * from './store/types';
 export { AirPlayButtonElement } from './ui/airplay-button/airplay-button-element';
diff --git a/packages/html/src/media/cloudflare-video/adapter.ts b/packages/html/src/media/cloudflare-video/adapter.ts
index dfae74c0b2..4d6cbbd0d8 100644
--- a/packages/html/src/media/cloudflare-video/adapter.ts
+++ b/packages/html/src/media/cloudflare-video/adapter.ts
@@ -1,46 +1,43 @@
 import { buildCloudflareIframeSrc, CloudflareAdapter } from '@videojs/cloudflare-video';
-import { CustomMediaElement } from '@videojs/media/dom';
 import { escapeHtml } from '@videojs/utils/string';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class CloudflareCustomMediaElement extends CustomMediaElement('iframe', CloudflareAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildCloudflareIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildCloudflareIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-block;
-          min-width: 300px;
-          min-height: 150px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        :host(:not([controls])) {
-          pointer-events: none;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        ${srcAttr}
-        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-        allowfullscreen
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: inline-block;
+        min-width: 300px;
+        min-height: 150px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      :host(:not([controls])) {
+        pointer-events: none;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      ${srcAttr}
+      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   return {
@@ -54,4 +51,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class CloudflareVideo extends MediaAttachMixin(CloudflareCustomMediaElement) {}
+export class CloudflareVideo extends createMediaElement(CloudflareAdapter, { tag: 'iframe', template }) {}
diff --git a/packages/html/src/media/create-media-element.ts b/packages/html/src/media/create-media-element.ts
new file mode 100644
index 0000000000..ba1ad3d2cf
--- /dev/null
+++ b/packages/html/src/media/create-media-element.ts
@@ -0,0 +1,37 @@
+import { CustomMediaElement, type PlaybackAdapter } from '@videojs/media/dom';
+import type { Constructor } from '@videojs/utils/types';
+
+import { MediaAttachMixin } from '../store/media-attach-mixin';
+
+export interface CreateMediaElementOptions {
+  /** Native element the adapter attaches to, rendered in the shadow root. Defaults to `'video'`. */
+  tag?: 'video' | 'audio' | 'iframe';
+  /**
+   * Shadow template for the element, given its initial attributes. Defaults to the bare native tag; embeds pass one
+   * that renders their `<iframe>` with the provider's attributes and initial URL.
+   */
+  template?: (attrs: Record<string, string>) => string;
+}
+
+/**
+ * Build a custom element that plays through an adapter and registers itself with the surrounding player.
+ *
+ * The element renders its target (`<video>` by default) in its shadow root, attaches the adapter to it, and mirrors its
+ * attributes onto the adapter's properties. Connecting it inside a player registers it as the player's media, the same
+ * way the built-in `<hlsjs-video>`, `<dash-video>`, and `<vimeo-video>` elements do. Subclass the result to add element
+ * behavior, then register it with `customElements.define()`.
+ *
+ * @param Adapter - Adapter class that drives playback, for example `HlsJsAdapter` from `@videojs/hlsjs-video`.
+ * @param options - The target tag and, for embeds, the shadow template that renders it.
+ */
+export function createMediaElement<Adapter extends Constructor<PlaybackAdapter>>(
+  Adapter: Adapter,
+  options: CreateMediaElementOptions = {}
+): ReturnType<typeof CustomMediaElement<Adapter>> {
+  const { tag = 'video', template } = options;
+  const Element = CustomMediaElement(tag, Adapter);
+
+  if (template) Element.getTemplateHTML = template;
+
+  return MediaAttachMixin(Element);
+}
diff --git a/packages/html/src/media/dash-video/adapter.ts b/packages/html/src/media/dash-video/adapter.ts
index a59c807104..43590cc45d 100644
--- a/packages/html/src/media/dash-video/adapter.ts
+++ b/packages/html/src/media/dash-video/adapter.ts
@@ -1,6 +1,5 @@
 import { DashAdapter } from '@videojs/dash-video';
-import { CustomMediaElement } from '@videojs/media/dom';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class DashVideo extends MediaAttachMixin(CustomMediaElement('video', DashAdapter)) {}
+export class DashVideo extends createMediaElement(DashAdapter) {}
diff --git a/packages/html/src/media/hls-audio/adapter.ts b/packages/html/src/media/hls-audio/adapter.ts
index 3dc8fe12a8..8665ea0fa8 100644
--- a/packages/html/src/media/hls-audio/adapter.ts
+++ b/packages/html/src/media/hls-audio/adapter.ts
@@ -1,6 +1,5 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { HlsAudioAdapter } from '@videojs/spf/hls-audio';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class HlsAudio extends MediaAttachMixin(CustomMediaElement('audio', HlsAudioAdapter)) {}
+export class HlsAudio extends createMediaElement(HlsAudioAdapter, { tag: 'audio' }) {}
diff --git a/packages/html/src/media/hls-video/adapter.ts b/packages/html/src/media/hls-video/adapter.ts
index 5f97216d3a..753be67d57 100644
--- a/packages/html/src/media/hls-video/adapter.ts
+++ b/packages/html/src/media/hls-video/adapter.ts
@@ -1,6 +1,5 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { HlsVideoAdapter } from '@videojs/spf/hls-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class HlsVideo extends MediaAttachMixin(CustomMediaElement('video', HlsVideoAdapter)) {}
+export class HlsVideo extends createMediaElement(HlsVideoAdapter) {}
diff --git a/packages/html/src/media/hlsjs-video/adapter.ts b/packages/html/src/media/hlsjs-video/adapter.ts
index 3830dbb3b2..fa508c939c 100644
--- a/packages/html/src/media/hlsjs-video/adapter.ts
+++ b/packages/html/src/media/hlsjs-video/adapter.ts
@@ -1,6 +1,5 @@
 import { HlsJsAdapter } from '@videojs/hlsjs-video';
-import { CustomMediaElement } from '@videojs/media/dom';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class HlsJsVideo extends MediaAttachMixin(CustomMediaElement('video', HlsJsAdapter)) {}
+export class HlsJsVideo extends createMediaElement(HlsJsAdapter) {}
diff --git a/packages/html/src/media/mux-audio/hls-js.ts b/packages/html/src/media/mux-audio/hls-js.ts
index 6c437a5b7d..fb1b7333a6 100644
--- a/packages/html/src/media/mux-audio/hls-js.ts
+++ b/packages/html/src/media/mux-audio/hls-js.ts
@@ -1,9 +1,8 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { MuxAudioAdapter } from '@videojs/mux-audio';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 import { MuxAudioMixin } from './mixin';
 
-const MuxAudioBase = MuxAudioMixin(MediaAttachMixin(CustomMediaElement('audio', MuxAudioAdapter)));
+const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter, { tag: 'audio' }));
 
 export class MuxAudio extends MuxAudioBase {}
diff --git a/packages/html/src/media/mux-audio/spf.ts b/packages/html/src/media/mux-audio/spf.ts
index a6c6e94dbf..c4b15d0a3f 100644
--- a/packages/html/src/media/mux-audio/spf.ts
+++ b/packages/html/src/media/mux-audio/spf.ts
@@ -1,10 +1,9 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { MuxAudioAdapter } from '@videojs/mux-audio/spf';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 import { MuxAudioMixin } from './mixin';
 
-const MuxAudioBase = MuxAudioMixin(MediaAttachMixin(CustomMediaElement('audio', MuxAudioAdapter)));
+const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter, { tag: 'audio' }));
 
 /**
  * `<mux-audio>` over the SPF audio-only Mux Media instead of the hls.js-backed one.
diff --git a/packages/html/src/media/mux-video/hls-js.ts b/packages/html/src/media/mux-video/hls-js.ts
index 94b916d48b..4fd7a11018 100644
--- a/packages/html/src/media/mux-video/hls-js.ts
+++ b/packages/html/src/media/mux-video/hls-js.ts
@@ -1,9 +1,8 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { MuxVideoAdapter } from '@videojs/mux-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 import { MuxVideoMixin } from './mixin';
 
-const MuxVideoBase = MuxVideoMixin(MediaAttachMixin(CustomMediaElement('video', MuxVideoAdapter)));
+const MuxVideoBase = MuxVideoMixin(createMediaElement(MuxVideoAdapter));
 
 export class MuxVideo extends MuxVideoBase {}
diff --git a/packages/html/src/media/mux-video/spf.ts b/packages/html/src/media/mux-video/spf.ts
index 8e5d6c21a6..6c584e8eb8 100644
--- a/packages/html/src/media/mux-video/spf.ts
+++ b/packages/html/src/media/mux-video/spf.ts
@@ -1,10 +1,9 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { MuxVideoAdapter } from '@videojs/mux-video/spf';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 import { MuxVideoMixin } from './mixin';
 
-const MuxVideoBase = MuxVideoMixin(MediaAttachMixin(CustomMediaElement('video', MuxVideoAdapter)));
+const MuxVideoBase = MuxVideoMixin(createMediaElement(MuxVideoAdapter));
 
 /**
  * `<mux-video>` over the SPF-backed Mux Media instead of the hls.js-backed one.
diff --git a/packages/html/src/media/native-hls-video/adapter.ts b/packages/html/src/media/native-hls-video/adapter.ts
index c45b6b7a63..5d09ccbe65 100644
--- a/packages/html/src/media/native-hls-video/adapter.ts
+++ b/packages/html/src/media/native-hls-video/adapter.ts
@@ -1,6 +1,5 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { NativeHlsAdapter } from '@videojs/native-hls-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class NativeHlsVideo extends MediaAttachMixin(CustomMediaElement('video', NativeHlsAdapter)) {}
+export class NativeHlsVideo extends createMediaElement(NativeHlsAdapter) {}
diff --git a/packages/html/src/media/shaka-video/adapter.ts b/packages/html/src/media/shaka-video/adapter.ts
index 9f19d7372f..4aa2d74c17 100644
--- a/packages/html/src/media/shaka-video/adapter.ts
+++ b/packages/html/src/media/shaka-video/adapter.ts
@@ -1,6 +1,5 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { ShakaAdapter } from '@videojs/shaka-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-export class ShakaVideo extends MediaAttachMixin(CustomMediaElement('video', ShakaAdapter)) {}
+export class ShakaVideo extends createMediaElement(ShakaAdapter) {}
diff --git a/packages/html/src/media/spotify-audio/adapter.ts b/packages/html/src/media/spotify-audio/adapter.ts
index 18f031f56f..27b81f3f6d 100644
--- a/packages/html/src/media/spotify-audio/adapter.ts
+++ b/packages/html/src/media/spotify-audio/adapter.ts
@@ -1,52 +1,49 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { buildSpotifyIframeSrc, SpotifyAdapter } from '@videojs/spotify-audio';
 import { escapeHtml } from '@videojs/utils/string';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class SpotifyCustomMediaElement extends CustomMediaElement('iframe', SpotifyAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildSpotifyIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildSpotifyIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: block;
-          min-width: 160px;
-          min-height: 80px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        /*
-         * Without Spotify's own chrome the embed is a transport and nothing else:
-         * its player UI would otherwise show through whatever skin is drawn over
-         * it. Hidden rather than merely inert, and important so a consumer's own
-         * display rule cannot put it back on screen. An iframe in a hidden subtree
-         * still loads and plays its src.
-         */
-        :host(:not([controls])) {
-          display: none !important;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        ${srcAttr}
-        allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: block;
+        min-width: 160px;
+        min-height: 80px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      /*
+       * Without Spotify's own chrome the embed is a transport and nothing else:
+       * its player UI would otherwise show through whatever skin is drawn over
+       * it. Hidden rather than merely inert, and important so a consumer's own
+       * display rule cannot put it back on screen. An iframe in a hidden subtree
+       * still loads and plays its src.
+       */
+      :host(:not([controls])) {
+        display: none !important;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      ${srcAttr}
+      allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   return {
@@ -58,4 +55,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class SpotifyAudio extends MediaAttachMixin(SpotifyCustomMediaElement) {}
+export class SpotifyAudio extends createMediaElement(SpotifyAdapter, { tag: 'iframe', template }) {}
diff --git a/packages/html/src/media/tests/create-media-element.test.ts b/packages/html/src/media/tests/create-media-element.test.ts
new file mode 100644
index 0000000000..3d3a160e34
--- /dev/null
+++ b/packages/html/src/media/tests/create-media-element.test.ts
@@ -0,0 +1,85 @@
+import { backgroundFeatures } from '@videojs/core/dom';
+import { HTMLVideoAdapter } from '@videojs/media/dom';
+import { afterEach, describe, expect, it, vi } from 'vite-plus/test';
+
+import { createPlayer } from '../../player/create-player';
+import { createMediaElement } from '../create-media-element';
+
+class FakeAdapter extends HTMLVideoAdapter {
+  static defaultProps = { src: '' };
+
+  #src = '';
+
+  get src() {
+    return this.#src;
+  }
+
+  set src(value: string) {
+    this.#src = value;
+  }
+}
+
+let tagCounter = 0;
+
+function defineTestElement<Element extends CustomElementConstructor>(Base: Element): string {
+  const tagName = `test-create-media-element-${tagCounter++}`;
+
+  customElements.define(tagName, Base);
+  return tagName;
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('createMediaElement', () => {
+  it('renders the native tag in the shadow root and attaches the adapter to it', () => {
+    const el = document.createElement(defineTestElement(createMediaElement(FakeAdapter)));
+
+    document.body.append(el);
+
+    const video = el.shadowRoot?.querySelector('video');
+
+    expect(video).toBeInstanceOf(HTMLVideoElement);
+    expect((el as unknown as { adapter: FakeAdapter }).adapter).toBeInstanceOf(FakeAdapter);
+  });
+
+  it('mirrors attributes onto the adapter', () => {
+    const el = document.createElement(defineTestElement(createMediaElement(FakeAdapter, { tag: 'audio' })));
+
+    document.body.append(el);
+    el.setAttribute('src', 'https://example.com/audio.m3u8');
+
+    expect((el as unknown as { adapter: FakeAdapter }).adapter.src).toBe('https://example.com/audio.m3u8');
+    expect(el.shadowRoot?.querySelector('audio')).toBeInstanceOf(HTMLAudioElement);
+  });
+
+  it('renders a custom template around an iframe target', () => {
+    const Element = createMediaElement(FakeAdapter, {
+      tag: 'iframe',
+      template: () => '<iframe part="iframe" title="Embedded player"></iframe>',
+    });
+    const el = document.createElement(defineTestElement(Element));
+
+    document.body.append(el);
+
+    const iframe = el.shadowRoot?.querySelector('iframe');
+
+    expect(iframe?.getAttribute('title')).toBe('Embedded player');
+    expect(el.shadowRoot?.querySelector('video')).toBeNull();
+  });
+
+  it('registers with the surrounding player and releases on disconnect', async () => {
+    const { PlayerElement } = createPlayer({ features: backgroundFeatures });
+    const player = document.createElement(defineTestElement(PlayerElement)) as InstanceType<typeof PlayerElement>;
+    const el = document.createElement(defineTestElement(createMediaElement(FakeAdapter)));
+
+    player.append(el);
+    document.body.append(player);
+
+    await vi.waitFor(() => expect(player.store.target?.media).toBe(el));
+
+    el.remove();
+    await vi.waitFor(() => expect(player.store.target).toBeNull());
+  });
+});
diff --git a/packages/html/src/media/tiktok-video/adapter.ts b/packages/html/src/media/tiktok-video/adapter.ts
index 6f5b5c4c40..3c9f7804ae 100644
--- a/packages/html/src/media/tiktok-video/adapter.ts
+++ b/packages/html/src/media/tiktok-video/adapter.ts
@@ -1,55 +1,52 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { buildTikTokIframeSrc, TikTokAdapter, type TikTokAdapterProps } from '@videojs/tiktok-video';
 import { escapeHtml } from '@videojs/utils/string';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class TikTokCustomMediaElement extends CustomMediaElement('iframe', TikTokAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildTikTokIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildTikTokIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-block;
-          /* TikTok videos are portrait, and the player refuses to draw its chrome
-             below 325x578, so that is where this host starts rather than the
-             300x150 the landscape embeds use. */
-          min-width: 325px;
-          min-height: 578px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        /* A cross-origin frame swallows every pointer event, so the skin above it
-           never sees the hover that reveals the controls. Kept out of hit-testing
-           except where the host leaves TikTok's player dormant, which is the same
-           pair of cases shouldBootstrapTikTokEmbed opts out of: then the frame's
-           own controls are the only thing that can still start it. */
-        :host(:not([controls]):not([preload="none"])) {
-          pointer-events: none;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        title="TikTok video player"
-        ${srcAttr}
-        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-        allowfullscreen
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: inline-block;
+        /* TikTok videos are portrait, and the player refuses to draw its chrome
+           below 325x578, so that is where this host starts rather than the
+           300x150 the landscape embeds use. */
+        min-width: 325px;
+        min-height: 578px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      /* A cross-origin frame swallows every pointer event, so the skin above it
+         never sees the hover that reveals the controls. Kept out of hit-testing
+         except where the host leaves TikTok's player dormant, which is the same
+         pair of cases shouldBootstrapTikTokEmbed opts out of: then the frame's
+         own controls are the only thing that can still start it. */
+      :host(:not([controls]):not([preload="none"])) {
+        pointer-events: none;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      title="TikTok video player"
+      ${srcAttr}
+      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 // Only the props the embed URL is built from. `preload` is not a TikTok parameter, but it decides whether the URL
 // carries a bootstrap autoplay, and a URL differing from the host's would have it rebuild the frame on mount.
@@ -63,4 +60,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>): Partial<TikTo
   };
 }
 
-export class TikTokVideo extends MediaAttachMixin(TikTokCustomMediaElement) {}
+export class TikTokVideo extends createMediaElement(TikTokAdapter, { tag: 'iframe', template }) {}
diff --git a/packages/html/src/media/twitch-video/adapter.ts b/packages/html/src/media/twitch-video/adapter.ts
index 51463ee195..c9289ab41d 100644
--- a/packages/html/src/media/twitch-video/adapter.ts
+++ b/packages/html/src/media/twitch-video/adapter.ts
@@ -1,47 +1,44 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { buildTwitchIframeSrc, TwitchAdapter } from '@videojs/twitch-video';
 import { escapeHtml } from '@videojs/utils/string';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class TwitchCustomMediaElement extends CustomMediaElement('iframe', TwitchAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildTwitchIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildTwitchIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-block;
-          min-width: 300px;
-          min-height: 150px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        :host(:not([controls])) {
-          pointer-events: none;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        ${srcAttr}
-        allow="accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;"
-        sandbox="allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
-        scrolling="no"
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: inline-block;
+        min-width: 300px;
+        min-height: 150px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      :host(:not([controls])) {
+        pointer-events: none;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      ${srcAttr}
+      allow="accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;"
+      sandbox="allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
+      scrolling="no"
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   return {
@@ -54,4 +51,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class TwitchVideo extends MediaAttachMixin(TwitchCustomMediaElement) {}
+export class TwitchVideo extends createMediaElement(TwitchAdapter, { tag: 'iframe', template }) {}
diff --git a/packages/html/src/media/vimeo-video/adapter.ts b/packages/html/src/media/vimeo-video/adapter.ts
index e1eadec2fc..16f70a54c2 100644
--- a/packages/html/src/media/vimeo-video/adapter.ts
+++ b/packages/html/src/media/vimeo-video/adapter.ts
@@ -1,46 +1,43 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { escapeHtml } from '@videojs/utils/string';
 import { buildVimeoIframeSrc, VimeoAdapter } from '@videojs/vimeo-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class VimeoCustomMediaElement extends CustomMediaElement('iframe', VimeoAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildVimeoIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildVimeoIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-block;
-          min-width: 300px;
-          min-height: 150px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        :host(:not([controls])) {
-          pointer-events: none;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        ${srcAttr}
-        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-        allowfullscreen
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: inline-block;
+        min-width: 300px;
+        min-height: 150px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      :host(:not([controls])) {
+        pointer-events: none;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      ${srcAttr}
+      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   return {
@@ -53,4 +50,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class VimeoVideo extends MediaAttachMixin(VimeoCustomMediaElement) {}
+export class VimeoVideo extends createMediaElement(VimeoAdapter, { tag: 'iframe', template }) {}
diff --git a/packages/html/src/media/youtube-video/adapter.ts b/packages/html/src/media/youtube-video/adapter.ts
index 84961c42ce..23974b1e5c 100644
--- a/packages/html/src/media/youtube-video/adapter.ts
+++ b/packages/html/src/media/youtube-video/adapter.ts
@@ -1,46 +1,43 @@
-import { CustomMediaElement } from '@videojs/media/dom';
 import { escapeHtml } from '@videojs/utils/string';
 import { buildYouTubeIframeSrc, YouTubeAdapter } from '@videojs/youtube-video';
 
-import { MediaAttachMixin } from '../../store/media-attach-mixin';
+import { createMediaElement } from '../create-media-element';
 
-class YouTubeCustomMediaElement extends CustomMediaElement('iframe', YouTubeAdapter) {
-  static override getTemplateHTML = (attrs: Record<string, string>): string => {
-    const initialSrc = buildYouTubeIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-    const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+const template = (attrs: Record<string, string>): string => {
+  const initialSrc = buildYouTubeIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
+  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
 
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-block;
-          min-width: 300px;
-          min-height: 150px;
-          position: relative;
-        }
-        iframe {
-          position: absolute;
-          inset: 0;
-          width: 100%;
-          height: 100%;
-          border: 0;
-        }
-        :host(:not([controls])) {
-          pointer-events: none;
-        }
-      </style>
-      <iframe
-        part="iframe"
-        ${srcAttr}
-        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-        allowfullscreen
-        frameborder="0"
-        width="100%"
-        height="100%"
-        referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-      ></iframe>
-    `;
-  };
-}
+  return /*html*/ `
+    <style>
+      :host {
+        display: inline-block;
+        min-width: 300px;
+        min-height: 150px;
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      :host(:not([controls])) {
+        pointer-events: none;
+      }
+    </style>
+    <iframe
+      part="iframe"
+      ${srcAttr}
+      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+      frameborder="0"
+      width="100%"
+      height="100%"
+      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
+    ></iframe>
+  `;
+};
 
 function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   return {
@@ -53,4 +50,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class YouTubeVideo extends MediaAttachMixin(YouTubeCustomMediaElement) {}
+export class YouTubeVideo extends createMediaElement(YouTubeAdapter, { tag: 'iframe', template }) {}
diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
new file mode 100644
index 0000000000..c595d3f386
--- /dev/null
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -0,0 +1,46 @@
+---
+title: createMediaElement
+description: Build a custom media element around a playback adapter that registers with the player
+---
+
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import DocsLink from "@/components/docs/DocsLink.astro";
+
+## Import
+
+```ts
+import { createMediaElement } from "@videojs/html";
+```
+
+## Usage
+
+Pass an adapter class. The returned element renders a `<video>` in its shadow root, drives it through the adapter, and registers itself with the surrounding <DocsLink slug="reference/player">player</DocsLink> on connect.
+
+```ts
+import { createMediaElement } from '@videojs/html';
+import { HlsJsAdapter } from '@videojs/hlsjs-video';
+
+export class MyHlsVideo extends createMediaElement(HlsJsAdapter) {}
+
+customElements.define('my-hls-video', MyHlsVideo);
+```
+
+Pass `tag: 'audio'` for an audio adapter. Embeds pass `tag: 'iframe'` and a `template` that renders the provider's iframe from the element's initial attributes:
+
+```ts
+import { createMediaElement } from '@videojs/html';
+import { VimeoAdapter } from '@videojs/vimeo-video';
+
+export class MyVimeoVideo extends createMediaElement(VimeoAdapter, {
+  tag: 'iframe',
+  template: (attrs) => `<iframe part="iframe" src="${attrs.src ?? ''}" allowfullscreen></iframe>`,
+}) {}
+```
+
+Every built-in media element except `<wistia-video>` and `<background-video>` is created this way. Subclass the result to add element behavior, such as extra observed attributes.
+
+## Who needs this
+
+Use `createMediaElement` to expose an adapter as a custom element, for example a third-party engine that implements the `@videojs/media` contract. For an element that already renders its own media, or whose media is not a native `<video>` or `<audio>`, apply <DocsLink slug="reference/media-attach-mixin">MediaAttachMixin</DocsLink> to it directly.
+
+<UtilReference util="createMediaElement" />
diff --git a/site/src/content/docs/reference/media-attach-mixin.mdx b/site/src/content/docs/reference/media-attach-mixin.mdx
index 926dfdb96c..0049f08557 100644
--- a/site/src/content/docs/reference/media-attach-mixin.mdx
+++ b/site/src/content/docs/reference/media-attach-mixin.mdx
@@ -14,7 +14,7 @@ import { MediaAttachMixin } from "@videojs/html";
 
 `MediaAttachMixin` creates a class that registers itself with the <DocsLink slug="reference/player">player</DocsLink> on connect. Apply it to custom media elements so they automatically wire to the store.
 
-Built-in elements, like `<hlsjs-video>`, `<dash-video>`, `<hls-video>`, and `<background-video>`, all use this mixin internally.
+Built-in elements, like `<hlsjs-video>`, `<dash-video>`, `<hls-video>`, and `<background-video>`, all use this mixin internally, most of them through <DocsLink slug="reference/create-media-element">createMediaElement</DocsLink>.
 
 ```ts
 import { MediaAttachMixin } from '@videojs/html';
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index 2c6f4dc788..529c505a71 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -303,6 +303,7 @@ export const sidebar: Sidebar = [
               { slug: 'reference/use-tap-gesture', frameworks: ['react'] },
               { slug: 'reference/use-tooltip-context', frameworks: ['react'] },
               { slug: 'reference/aria-key-shortcuts-controller', frameworks: ['html'] },
+              { slug: 'reference/create-media-element', frameworks: ['html'] },
               { slug: 'reference/media-attach-mixin', frameworks: ['html'] },
               { slug: 'reference/player-context', frameworks: ['html'] },
               { slug: 'reference/snapshot-controller', frameworks: ['html'] },

From a8a536c7bfc041f8b50685676467be102fe8a0bf Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Wed, 2 Sep 2026 16:54:32 -0700
Subject: [PATCH 02/25] docs(site): discover media elements built with
 createMediaElement

The media reference builder found an element's host by walking its class
chain for a `CustomMediaElement(tag, Host)` call. Elements now compose through
`createMediaElement(tag, Adapter)`, which declares the same two arguments, so
the builder accepts either factory name.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media-element-handler.ts              | 28 ++++++++++++++++---
 .../api-docs-builder/src/tests/e2e.test.ts    |  8 ++++++
 .../html/src/media/mixin-video/adapter.ts     | 10 +++----
 .../html/src/media/simple-video/adapter.ts    | 13 ++++-----
 4 files changed, 43 insertions(+), 16 deletions(-)

diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index 26191d7125..5d05c08fe4 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -326,6 +326,8 @@ function publicImplementationFiles(entryPath: string, project: OxcProject, visit
   return [absolute, ...reexports];
 }
 
+const MEDIA_ELEMENT_FACTORIES = new Set(['CustomMediaElement', 'createMediaElement']);
+
 function findCustomMediaComposition(
   file: SourceFile,
   declaration: Class,
@@ -347,10 +349,28 @@ function findCustomMediaComposition(
     walkAst(expression, (node) => {
       if (found || node.type !== 'CallExpression' || node.callee.type !== 'Identifier') return;
 
-      if (node.callee.name !== 'CustomMediaElement' || node.arguments.length < 2) return;
-
-      const target = node.arguments[0];
-      const host = node.arguments[1];
+      if (!MEDIA_ELEMENT_FACTORIES.has(node.callee.name) || node.arguments.length < 1) return;
+
+      // `CustomMediaElement(tag, Host)` names the target first; `createMediaElement(Host, { tag })` from
+      // `@videojs/html` names the host first and defaults the target to `video`.
+      const fromFactory = node.callee.name === 'createMediaElement';
+      const host = fromFactory ? node.arguments[0] : node.arguments[1];
+      let target: Expression | undefined;
+
+      if (fromFactory) {
+        const options = node.arguments[1];
+        const tagProperty =
+          options?.type === 'ObjectExpression'
+            ? options.properties.find((entry) => entry.type === 'Property' && staticName(entry.key) === 'tag')
+            : undefined;
+
+        target =
+          tagProperty?.type === 'Property'
+            ? tagProperty.value
+            : ({ type: 'Literal', value: 'video', raw: "'video'", start: node.start, end: node.end } as Expression);
+      } else {
+        target = node.arguments[0]?.type === 'SpreadElement' ? undefined : node.arguments[0];
+      }
 
       if (
         !target ||
diff --git a/site/scripts/api-docs-builder/src/tests/e2e.test.ts b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
index dc8c893740..7730d6f803 100644
--- a/site/scripts/api-docs-builder/src/tests/e2e.test.ts
+++ b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
@@ -1508,6 +1508,14 @@ describe('Media element pipeline (end-to-end)', () => {
       ]);
     });
 
+    it('discovers elements built with createMediaElement as well as CustomMediaElement', () => {
+      // SimpleVideo composes through the factory (default target), MixinVideo names its target in the options object,
+      // and ComplexVideo composes through CustomMediaElement directly.
+      expect(findElement('SimpleVideo')!.reference.platforms.html.target).toBe('video');
+      expect(findElement('MixinVideo')!.reference.platforms.html.target).toBe('video');
+      expect(findElement('ComplexVideo')!.reference.platforms.html.target).toBe('video');
+    });
+
     it('does not treat the UI container as a media element', () => {
       expect(findElement('ContainerElement')).toBeUndefined();
     });
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
index 58848bc318..b85b273760 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
@@ -1,14 +1,14 @@
 /**
  * Mock mixin-chain media element — mirrors MuxVideo / NativeHlsVideo.
  *
- * Exercises: standard composition where the host is a mixin chain.
+ * Exercises: the `createMediaElement` factory with an options object naming the target, where the host is a mixin
+ * chain.
  */
-import { CustomMediaElement } from '../../../../media/src/dom/custom-media-element';
 import { MixinHost } from '../../../../media/src/dom/mixin';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function MediaAttachMixin(base: any) {
-  return base;
+function createMediaElement(host: any, options?: { tag?: string }) {
+  return host;
 }
 
-export class MixinVideo extends MediaAttachMixin(CustomMediaElement('video', MixinHost)) {}
+export class MixinVideo extends createMediaElement(MixinHost, { tag: 'video' }) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
index f726b0f2fc..afa8dba720 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
@@ -1,16 +1,15 @@
 /**
  * Mock simple media element — mirrors DashVideo.
  *
- * Exercises: standard composition with CustomMediaElement factory.
- * The builder follows this import chain to discover the host class
- * and resolve its properties.
+ * Exercises: composition through the `createMediaElement` factory, which wraps
+ * `CustomMediaElement` in `MediaAttachMixin`. The builder follows the factory
+ * call to discover the host class and resolve its properties.
  */
-import { CustomMediaElement } from '../../../../media/src/dom/custom-media-element';
 import { SimpleHost } from '../../../../media/src/dom/simple';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function MediaAttachMixin(base: any) {
-  return base;
+function createMediaElement(host: any, options?: { tag?: string }) {
+  return host;
 }
 
-export class SimpleVideo extends MediaAttachMixin(CustomMediaElement('video', SimpleHost)) {}
+export class SimpleVideo extends createMediaElement(SimpleHost) {}

From 877f7c8b63e086e8be5e8cf3f2a6a67c8c97dbf4 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 20:56:40 -0700
Subject: [PATCH 03/25] refactor(media)!: adapters declare their host element

`CustomMediaElement(Adapter)` reads the element it renders and attaches to
from the adapter's static `host` ('video' | 'audio' | 'iframe') instead of a
tag argument. `HTMLVideoAdapter` and `HTMLAudioAdapter` declare theirs, the
iframe embed adapters declare 'iframe', and the hls.js-backed
`MuxAudioAdapter` overrides the video base it extends.

`createMediaElement` drops its `tag` option, leaving `template` as the only
knob, and the element's static `getTemplateHTML` is renamed `template`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../adapters/cloudflare-video/src/adapter.ts  |  4 +-
 .../hlsjs-video/src/tests/adapter.test.ts     |  2 +-
 packages/adapters/mux-audio/src/index.ts      |  4 +-
 .../adapters/spotify-audio/src/adapter.ts     |  4 +-
 packages/adapters/tiktok-video/src/adapter.ts |  4 +-
 packages/adapters/twitch-video/src/adapter.ts |  4 +-
 packages/adapters/vimeo-video/src/adapter.ts  |  4 +-
 .../adapters/youtube-video/src/adapter.ts     |  4 +-
 .../src/media/background-video/adapter.ts     |  6 +--
 .../src/media/background-video/template.ts    |  2 +-
 .../tests/background-video.test.ts            |  2 +-
 .../src/media/cloudflare-video/adapter.ts     |  2 +-
 .../html/src/media/create-media-element.ts    | 26 +++++------
 packages/html/src/media/hls-audio/adapter.ts  |  2 +-
 .../src/media/hls-background-video/adapter.ts |  6 +--
 packages/html/src/media/mux-audio/hls-js.ts   |  2 +-
 packages/html/src/media/mux-audio/spf.ts      |  2 +-
 .../html/src/media/spotify-audio/adapter.ts   |  2 +-
 .../media/tests/create-media-element.test.ts  | 46 +++++++++++++++----
 .../src/media/tests/spotify-audio.test.ts     |  2 +-
 .../html/src/media/tests/tiktok-video.test.ts | 10 ++--
 .../html/src/media/tiktok-video/adapter.ts    |  2 +-
 .../html/src/media/twitch-video/adapter.ts    |  2 +-
 .../html/src/media/vimeo-video/adapter.ts     |  2 +-
 .../html/src/media/youtube-video/adapter.ts   |  2 +-
 .../custom-media-element.ts                   | 33 ++++++++-----
 .../tests/custom-media-element.test.ts        | 26 ++++++-----
 .../html-audio-adapter/html-audio-adapter.ts  |  6 ++-
 .../html-media-adapter/html-media-adapter.ts  |  8 ++++
 .../html-video-adapter/html-video-adapter.ts  | 10 +++-
 30 files changed, 151 insertions(+), 80 deletions(-)

diff --git a/packages/adapters/cloudflare-video/src/adapter.ts b/packages/adapters/cloudflare-video/src/adapter.ts
index 698d14adf9..7a1a27f8a5 100644
--- a/packages/adapters/cloudflare-video/src/adapter.ts
+++ b/packages/adapters/cloudflare-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type TextTrackListLike, type Video } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 
@@ -16,6 +16,8 @@ import { type CloudflareStreamApi, type CloudflareStreamPlayerApi, loadCloudflar
  *   new value.
  */
 export class CloudflareAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: CloudflareAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/adapters/hlsjs-video/src/tests/adapter.test.ts b/packages/adapters/hlsjs-video/src/tests/adapter.test.ts
index 3bb9e79fc6..21f5882816 100644
--- a/packages/adapters/hlsjs-video/src/tests/adapter.test.ts
+++ b/packages/adapters/hlsjs-video/src/tests/adapter.test.ts
@@ -7,7 +7,7 @@ import { ContentTypes, Hls, HlsJsAdapter, type HlsSource } from '../index';
 
 // Stands in for `<hlsjs-video>`, so markup reaches the media adapter the same way
 // the HTML binding delivers it.
-customElements.define('test-airplay-video', CustomMediaElement('video', HlsJsAdapter as never));
+customElements.define('test-airplay-video', CustomMediaElement(HlsJsAdapter));
 
 afterEach(() => {
   document.body.innerHTML = '';
diff --git a/packages/adapters/mux-audio/src/index.ts b/packages/adapters/mux-audio/src/index.ts
index 3acae18dc6..d9bcc86b21 100644
--- a/packages/adapters/mux-audio/src/index.ts
+++ b/packages/adapters/mux-audio/src/index.ts
@@ -5,4 +5,6 @@ export type { MuxSource, MuxVideoAdapterProps as MuxAudioAdapterProps } from '@v
 // TODO(mux): audio extending video is upside down. The hls.js-backed Mux behavior should move to a shared base that a
 // video and an audio adapter both extend; until then this class exists so audio installs by the media it plays and has
 // a home for audio-only behavior.
-export class MuxAudioAdapter extends MuxVideoAdapter {}
+export class MuxAudioAdapter extends MuxVideoAdapter {
+  static override readonly host = 'audio';
+}
diff --git a/packages/adapters/spotify-audio/src/adapter.ts b/packages/adapters/spotify-audio/src/adapter.ts
index 71b18203c6..3a877e76e9 100644
--- a/packages/adapters/spotify-audio/src/adapter.ts
+++ b/packages/adapters/spotify-audio/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements — License: MIT
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber } from '@videojs/utils/predicate';
@@ -22,6 +22,8 @@ import { buildSpotifyIframeSrc, parseSpotifySource, type SpotifySource } from '.
  *   new value.
  */
 export class SpotifyAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: SpotifyAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/adapters/tiktok-video/src/adapter.ts b/packages/adapters/tiktok-video/src/adapter.ts
index b4e56ae9c6..76208d44d4 100644
--- a/packages/adapters/tiktok-video/src/adapter.ts
+++ b/packages/adapters/tiktok-video/src/adapter.ts
@@ -2,7 +2,7 @@
 // ported to TypeScript and reshaped as a media adapter (mirrors `dom/youtube`).
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -33,6 +33,8 @@ import { buildTikTokIframeSrc, shouldBootstrapTikTokEmbed, type TikTokSource } f
  *   new value.
  */
 export class TikTokAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: TikTokAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/adapters/twitch-video/src/adapter.ts b/packages/adapters/twitch-video/src/adapter.ts
index a4a048f29b..d724b126cb 100644
--- a/packages/adapters/twitch-video/src/adapter.ts
+++ b/packages/adapters/twitch-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // License: MIT
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -35,6 +35,8 @@ import { buildTwitchIframeSrc, parseTwitchSource, type TwitchSource } from './so
  *   new value.
  */
 export class TwitchAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: TwitchAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/adapters/vimeo-video/src/adapter.ts b/packages/adapters/vimeo-video/src/adapter.ts
index 6d6c430947..596a70def9 100644
--- a/packages/adapters/vimeo-video/src/adapter.ts
+++ b/packages/adapters/vimeo-video/src/adapter.ts
@@ -8,7 +8,7 @@ import {
   type TextTrackListLike,
   type Video,
 } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin, serializeEmbedParams } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin, serializeEmbedParams } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNull, isString, isUndefined } from '@videojs/utils/predicate';
@@ -65,6 +65,8 @@ export interface VimeoAdapterProps {
  *   for the new value.
  */
 export class VimeoAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: VimeoAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/adapters/youtube-video/src/adapter.ts b/packages/adapters/youtube-video/src/adapter.ts
index 3f1b532998..08b9da83d8 100644
--- a/packages/adapters/youtube-video/src/adapter.ts
+++ b/packages/adapters/youtube-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type TextTrackListLike, type Video } from '@videojs/media';
-import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, noop, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -24,6 +24,8 @@ import type { YouTubeAdapterProps } from './props';
 import { buildYouTubeIframeSrc, parseYouTubeSource, type YouTubeSource } from './source';
 
 export class YouTubeAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
+  static readonly host: AdapterHost = 'iframe';
+
   static readonly defaultProps: YouTubeAdapterProps = {
     src: '',
     autoplay: false,
diff --git a/packages/html/src/media/background-video/adapter.ts b/packages/html/src/media/background-video/adapter.ts
index b94d9ac5b8..d9d800a603 100644
--- a/packages/html/src/media/background-video/adapter.ts
+++ b/packages/html/src/media/background-video/adapter.ts
@@ -2,14 +2,14 @@ import type { Media } from '@videojs/media/dom';
 import { namedNodeMapToObject } from '@videojs/utils/dom';
 
 import { MediaAttachMixin } from '../../store/media-attach-mixin';
-import { getTemplateHTML } from './template';
+import { backgroundVideoTemplate } from './template';
 
 const HTMLElementBase = globalThis.HTMLElement ?? class {};
 
 // Don't extend CustomMediaMixin to save some bytes, background videos don't need the full Media API.
 export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
-  static getTemplateHTML = getTemplateHTML;
+  static template = backgroundVideoTemplate;
   static get observedAttributes() {
     return ['src'];
   }
@@ -30,7 +30,7 @@ export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
         disablepictureinpicture: '',
       };
 
-      this.shadowRoot!.innerHTML = getTemplateHTML(attrs);
+      this.shadowRoot!.innerHTML = backgroundVideoTemplate(attrs);
     }
 
     // Neither Chrome or Firefox support setting the muted attribute
diff --git a/packages/html/src/media/background-video/template.ts b/packages/html/src/media/background-video/template.ts
index d49b84630b..0b66b7d7ff 100644
--- a/packages/html/src/media/background-video/template.ts
+++ b/packages/html/src/media/background-video/template.ts
@@ -26,7 +26,7 @@ export const VideoAttributes = [
  * Shared so the two can't drift in presentation. `object-fit` and `object-position` are the only styling hooks — a
  * background video has no controls to theme.
  */
-export function getTemplateHTML(attrs: Record<string, string>) {
+export function backgroundVideoTemplate(attrs: Record<string, string>) {
   return /*html*/ `
     <style>
       :host {
diff --git a/packages/html/src/media/background-video/tests/background-video.test.ts b/packages/html/src/media/background-video/tests/background-video.test.ts
index a9ceadf13c..104a5de765 100644
--- a/packages/html/src/media/background-video/tests/background-video.test.ts
+++ b/packages/html/src/media/background-video/tests/background-video.test.ts
@@ -87,7 +87,7 @@ describe('BackgroundVideo', () => {
       };
       const container = document.createElement('div');
 
-      container.innerHTML = (Ctor as any).getTemplateHTML(attrs);
+      container.innerHTML = (Ctor as any).template(attrs);
 
       const video = container.querySelector('video')!;
 
diff --git a/packages/html/src/media/cloudflare-video/adapter.ts b/packages/html/src/media/cloudflare-video/adapter.ts
index 4d6cbbd0d8..607233d511 100644
--- a/packages/html/src/media/cloudflare-video/adapter.ts
+++ b/packages/html/src/media/cloudflare-video/adapter.ts
@@ -51,4 +51,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class CloudflareVideo extends createMediaElement(CloudflareAdapter, { tag: 'iframe', template }) {}
+export class CloudflareVideo extends createMediaElement(CloudflareAdapter, { template }) {}
diff --git a/packages/html/src/media/create-media-element.ts b/packages/html/src/media/create-media-element.ts
index ba1ad3d2cf..363e9d6121 100644
--- a/packages/html/src/media/create-media-element.ts
+++ b/packages/html/src/media/create-media-element.ts
@@ -1,14 +1,11 @@
-import { CustomMediaElement, type PlaybackAdapter } from '@videojs/media/dom';
-import type { Constructor } from '@videojs/utils/types';
+import { CustomMediaElement, type PlaybackAdapterConstructor } from '@videojs/media/dom';
 
 import { MediaAttachMixin } from '../store/media-attach-mixin';
 
 export interface CreateMediaElementOptions {
-  /** Native element the adapter attaches to, rendered in the shadow root. Defaults to `'video'`. */
-  tag?: 'video' | 'audio' | 'iframe';
   /**
-   * Shadow template for the element, given its initial attributes. Defaults to the bare native tag; embeds pass one
-   * that renders their `<iframe>` with the provider's attributes and initial URL.
+   * Shadow template for the element, given its initial attributes. Defaults to the adapter's bare `host` element;
+   * embeds pass one that renders their `<iframe>` with the provider's attributes and initial URL.
    */
   template?: (attrs: Record<string, string>) => string;
 }
@@ -16,22 +13,21 @@ export interface CreateMediaElementOptions {
 /**
  * Build a custom element that plays through an adapter and registers itself with the surrounding player.
  *
- * The element renders its target (`<video>` by default) in its shadow root, attaches the adapter to it, and mirrors its
- * attributes onto the adapter's properties. Connecting it inside a player registers it as the player's media, the same
- * way the built-in `<hlsjs-video>`, `<dash-video>`, and `<vimeo-video>` elements do. Subclass the result to add element
- * behavior, then register it with `customElements.define()`.
+ * The element renders the adapter's `host` element (`<video>`, `<audio>`, or `<iframe>`) in its shadow root, attaches
+ * the adapter to it, and mirrors its attributes onto the adapter's properties. Connecting it inside a player registers
+ * it as the player's media, the same way the built-in `<hlsjs-video>`, `<dash-video>`, and `<vimeo-video>` elements do.
+ * Subclass the result to add element behavior, then register it with `customElements.define()`.
  *
  * @param Adapter - Adapter class that drives playback, for example `HlsJsAdapter` from `@videojs/hlsjs-video`.
- * @param options - The target tag and, for embeds, the shadow template that renders it.
+ * @param options - For embeds, the shadow template that renders the `<iframe>`.
  */
-export function createMediaElement<Adapter extends Constructor<PlaybackAdapter>>(
+export function createMediaElement<Adapter extends PlaybackAdapterConstructor>(
   Adapter: Adapter,
   options: CreateMediaElementOptions = {}
 ): ReturnType<typeof CustomMediaElement<Adapter>> {
-  const { tag = 'video', template } = options;
-  const Element = CustomMediaElement(tag, Adapter);
+  const Element = CustomMediaElement(Adapter);
 
-  if (template) Element.getTemplateHTML = template;
+  if (options.template) Element.template = options.template;
 
   return MediaAttachMixin(Element);
 }
diff --git a/packages/html/src/media/hls-audio/adapter.ts b/packages/html/src/media/hls-audio/adapter.ts
index 8665ea0fa8..4730ef7f3d 100644
--- a/packages/html/src/media/hls-audio/adapter.ts
+++ b/packages/html/src/media/hls-audio/adapter.ts
@@ -2,4 +2,4 @@ import { HlsAudioAdapter } from '@videojs/spf/hls-audio';
 
 import { createMediaElement } from '../create-media-element';
 
-export class HlsAudio extends createMediaElement(HlsAudioAdapter, { tag: 'audio' }) {}
+export class HlsAudio extends createMediaElement(HlsAudioAdapter) {}
diff --git a/packages/html/src/media/hls-background-video/adapter.ts b/packages/html/src/media/hls-background-video/adapter.ts
index bfc9fff3e6..cd6ad456ea 100644
--- a/packages/html/src/media/hls-background-video/adapter.ts
+++ b/packages/html/src/media/hls-background-video/adapter.ts
@@ -4,7 +4,7 @@ import { type CustomElement, namedNodeMapToObject } from '@videojs/utils/dom';
 import type { Constructor } from '@videojs/utils/types';
 
 import { MediaAttachMixin } from '../../store/media-attach-mixin';
-import { getTemplateHTML } from '../background-video/template';
+import { backgroundVideoTemplate } from '../background-video/template';
 
 const HTMLElementBase = globalThis.HTMLElement ?? class {};
 
@@ -51,7 +51,7 @@ const HlsBackgroundVideoBase = MediaAttachMixin(HTMLElementBase) as unknown as C
 // background video needs one property, not the full WHATWG media API.
 export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
-  static getTemplateHTML = getTemplateHTML;
+  static template = backgroundVideoTemplate;
 
   static get observedAttributes(): string[] {
     return ['src'];
@@ -75,7 +75,7 @@ export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
         disablepictureinpicture: '',
       };
 
-      this.shadowRoot!.innerHTML = getTemplateHTML(attrs);
+      this.shadowRoot!.innerHTML = backgroundVideoTemplate(attrs);
     }
 
     // Neither Chrome nor Firefox honor a `muted` attribute set after
diff --git a/packages/html/src/media/mux-audio/hls-js.ts b/packages/html/src/media/mux-audio/hls-js.ts
index fb1b7333a6..22b6550162 100644
--- a/packages/html/src/media/mux-audio/hls-js.ts
+++ b/packages/html/src/media/mux-audio/hls-js.ts
@@ -3,6 +3,6 @@ import { MuxAudioAdapter } from '@videojs/mux-audio';
 import { createMediaElement } from '../create-media-element';
 import { MuxAudioMixin } from './mixin';
 
-const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter, { tag: 'audio' }));
+const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter));
 
 export class MuxAudio extends MuxAudioBase {}
diff --git a/packages/html/src/media/mux-audio/spf.ts b/packages/html/src/media/mux-audio/spf.ts
index c4b15d0a3f..f8efd601f0 100644
--- a/packages/html/src/media/mux-audio/spf.ts
+++ b/packages/html/src/media/mux-audio/spf.ts
@@ -3,7 +3,7 @@ import { MuxAudioAdapter } from '@videojs/mux-audio/spf';
 import { createMediaElement } from '../create-media-element';
 import { MuxAudioMixin } from './mixin';
 
-const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter, { tag: 'audio' }));
+const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter));
 
 /**
  * `<mux-audio>` over the SPF audio-only Mux Media instead of the hls.js-backed one.
diff --git a/packages/html/src/media/spotify-audio/adapter.ts b/packages/html/src/media/spotify-audio/adapter.ts
index 27b81f3f6d..69e8a3ebc6 100644
--- a/packages/html/src/media/spotify-audio/adapter.ts
+++ b/packages/html/src/media/spotify-audio/adapter.ts
@@ -55,4 +55,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class SpotifyAudio extends createMediaElement(SpotifyAdapter, { tag: 'iframe', template }) {}
+export class SpotifyAudio extends createMediaElement(SpotifyAdapter, { template }) {}
diff --git a/packages/html/src/media/tests/create-media-element.test.ts b/packages/html/src/media/tests/create-media-element.test.ts
index 3d3a160e34..ee11a4b536 100644
--- a/packages/html/src/media/tests/create-media-element.test.ts
+++ b/packages/html/src/media/tests/create-media-element.test.ts
@@ -1,5 +1,5 @@
 import { backgroundFeatures } from '@videojs/core/dom';
-import { HTMLVideoAdapter } from '@videojs/media/dom';
+import { HTMLAudioAdapter, HTMLVideoAdapter } from '@videojs/media/dom';
 import { afterEach, describe, expect, it, vi } from 'vite-plus/test';
 
 import { createPlayer } from '../../player/create-player';
@@ -19,6 +19,36 @@ class FakeAdapter extends HTMLVideoAdapter {
   }
 }
 
+class FakeAudioAdapter extends HTMLAudioAdapter {
+  static defaultProps = { src: '' };
+
+  #src = '';
+
+  get src() {
+    return this.#src;
+  }
+
+  set src(value: string) {
+    this.#src = value;
+  }
+}
+
+class FakeEmbedAdapter extends EventTarget {
+  static readonly host = 'iframe' as const;
+
+  target: EventTarget | null = null;
+
+  attach(target: EventTarget | null) {
+    this.target = target;
+  }
+
+  detach() {
+    this.target = null;
+  }
+
+  destroy() {}
+}
+
 let tagCounter = 0;
 
 function defineTestElement<Element extends CustomElementConstructor>(Base: Element): string {
@@ -33,7 +63,7 @@ afterEach(() => {
 });
 
 describe('createMediaElement', () => {
-  it('renders the native tag in the shadow root and attaches the adapter to it', () => {
+  it("renders the adapter's host element in the shadow root and attaches the adapter to it", () => {
     const el = document.createElement(defineTestElement(createMediaElement(FakeAdapter)));
 
     document.body.append(el);
@@ -44,19 +74,18 @@ describe('createMediaElement', () => {
     expect((el as unknown as { adapter: FakeAdapter }).adapter).toBeInstanceOf(FakeAdapter);
   });
 
-  it('mirrors attributes onto the adapter', () => {
-    const el = document.createElement(defineTestElement(createMediaElement(FakeAdapter, { tag: 'audio' })));
+  it('renders an <audio> for an audio adapter and mirrors attributes onto the adapter', () => {
+    const el = document.createElement(defineTestElement(createMediaElement(FakeAudioAdapter)));
 
     document.body.append(el);
     el.setAttribute('src', 'https://example.com/audio.m3u8');
 
-    expect((el as unknown as { adapter: FakeAdapter }).adapter.src).toBe('https://example.com/audio.m3u8');
+    expect((el as unknown as { adapter: FakeAudioAdapter }).adapter.src).toBe('https://example.com/audio.m3u8');
     expect(el.shadowRoot?.querySelector('audio')).toBeInstanceOf(HTMLAudioElement);
   });
 
-  it('renders a custom template around an iframe target', () => {
-    const Element = createMediaElement(FakeAdapter, {
-      tag: 'iframe',
+  it('renders the template around an embed adapter and attaches to its iframe', () => {
+    const Element = createMediaElement(FakeEmbedAdapter, {
       template: () => '<iframe part="iframe" title="Embedded player"></iframe>',
     });
     const el = document.createElement(defineTestElement(Element));
@@ -67,6 +96,7 @@ describe('createMediaElement', () => {
 
     expect(iframe?.getAttribute('title')).toBe('Embedded player');
     expect(el.shadowRoot?.querySelector('video')).toBeNull();
+    expect((el as unknown as { adapter: FakeEmbedAdapter }).adapter.target).toBe(iframe);
   });
 
   it('registers with the surrounding player and releases on disconnect', async () => {
diff --git a/packages/html/src/media/tests/spotify-audio.test.ts b/packages/html/src/media/tests/spotify-audio.test.ts
index fadc2590a8..8ca94ed4aa 100644
--- a/packages/html/src/media/tests/spotify-audio.test.ts
+++ b/packages/html/src/media/tests/spotify-audio.test.ts
@@ -4,7 +4,7 @@ import { SpotifyAudio } from '../spotify-audio/adapter';
 
 describe('SpotifyAudio', () => {
   it('hides the embed unless it is showing Spotify’s own chrome', () => {
-    const template = SpotifyAudio.getTemplateHTML({ src: 'https://open.spotify.com/track/1301WleyT98MSxVHPZCA6M' });
+    const template = SpotifyAudio.template({ src: 'https://open.spotify.com/track/1301WleyT98MSxVHPZCA6M' });
 
     // Left visible, Spotify's own player UI shows through the skin drawn over it.
     // Asserted against the template because no DOM implementation the tests run
diff --git a/packages/html/src/media/tests/tiktok-video.test.ts b/packages/html/src/media/tests/tiktok-video.test.ts
index d17e7435b8..07b2feed36 100644
--- a/packages/html/src/media/tests/tiktok-video.test.ts
+++ b/packages/html/src/media/tests/tiktok-video.test.ts
@@ -10,7 +10,7 @@ describe('TikTokVideo', () => {
   it('keeps the embed out of hit-testing so the skin above it sees hover', () => {
     // A cross-origin frame swallows every pointer event it is given, and the skin never sees the hover that
     // reveals the controls.
-    expect(TikTokVideo.getTemplateHTML({ src: SRC })).toMatch(
+    expect(TikTokVideo.template({ src: SRC })).toMatch(
       /:host\(:not\(\[controls\]\):not\(\[preload="none"\]\)\)\s*\{\s*pointer-events:\s*none/
     );
   });
@@ -18,17 +18,17 @@ describe('TikTokVideo', () => {
   it('leaves a dormant embed clickable', () => {
     // `preload="none"` opts out of the bootstrap, so TikTok's own controls are the only thing left that can start
     // the player. The rule stops applying rather than the frame stopping taking pointer events.
-    const template = TikTokVideo.getTemplateHTML({ src: SRC, preload: 'none' });
+    const template = TikTokVideo.template({ src: SRC, preload: 'none' });
 
     expect(template).toContain(':not([preload="none"])');
   });
 
   it('builds the embed with a bootstrap autoplay unless the player is left dormant', () => {
     // `autoplay=1` is the embed parameter; the `allow` attribute names the feature policy and carries it either way.
-    expect(TikTokVideo.getTemplateHTML({ src: SRC })).toContain('autoplay=1');
-    expect(TikTokVideo.getTemplateHTML({ src: SRC, preload: 'none' })).not.toContain('autoplay=1');
+    expect(TikTokVideo.template({ src: SRC })).toContain('autoplay=1');
+    expect(TikTokVideo.template({ src: SRC, preload: 'none' })).not.toContain('autoplay=1');
     // The two cases the hit-testing rule above excludes are the two that skip the bootstrap, so the frame stays
     // clickable exactly where its own controls are the only way to start it.
-    expect(TikTokVideo.getTemplateHTML({ src: SRC, controls: '' })).not.toContain('autoplay=1');
+    expect(TikTokVideo.template({ src: SRC, controls: '' })).not.toContain('autoplay=1');
   });
 });
diff --git a/packages/html/src/media/tiktok-video/adapter.ts b/packages/html/src/media/tiktok-video/adapter.ts
index 3c9f7804ae..618273b68f 100644
--- a/packages/html/src/media/tiktok-video/adapter.ts
+++ b/packages/html/src/media/tiktok-video/adapter.ts
@@ -60,4 +60,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>): Partial<TikTo
   };
 }
 
-export class TikTokVideo extends createMediaElement(TikTokAdapter, { tag: 'iframe', template }) {}
+export class TikTokVideo extends createMediaElement(TikTokAdapter, { template }) {}
diff --git a/packages/html/src/media/twitch-video/adapter.ts b/packages/html/src/media/twitch-video/adapter.ts
index c9289ab41d..90fab3e4a7 100644
--- a/packages/html/src/media/twitch-video/adapter.ts
+++ b/packages/html/src/media/twitch-video/adapter.ts
@@ -51,4 +51,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class TwitchVideo extends createMediaElement(TwitchAdapter, { tag: 'iframe', template }) {}
+export class TwitchVideo extends createMediaElement(TwitchAdapter, { template }) {}
diff --git a/packages/html/src/media/vimeo-video/adapter.ts b/packages/html/src/media/vimeo-video/adapter.ts
index 16f70a54c2..21945f130f 100644
--- a/packages/html/src/media/vimeo-video/adapter.ts
+++ b/packages/html/src/media/vimeo-video/adapter.ts
@@ -50,4 +50,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class VimeoVideo extends createMediaElement(VimeoAdapter, { tag: 'iframe', template }) {}
+export class VimeoVideo extends createMediaElement(VimeoAdapter, { template }) {}
diff --git a/packages/html/src/media/youtube-video/adapter.ts b/packages/html/src/media/youtube-video/adapter.ts
index 23974b1e5c..498a973036 100644
--- a/packages/html/src/media/youtube-video/adapter.ts
+++ b/packages/html/src/media/youtube-video/adapter.ts
@@ -50,4 +50,4 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class YouTubeVideo extends createMediaElement(YouTubeAdapter, { tag: 'iframe', template }) {}
+export class YouTubeVideo extends createMediaElement(YouTubeAdapter, { template }) {}
diff --git a/packages/media/src/dom/custom-media-element/custom-media-element.ts b/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 7e1fbd3c3b..09a7d5707e 100644
--- a/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -3,6 +3,8 @@ import { omit, pick } from '@videojs/utils/object';
 import { kebabCase } from '@videojs/utils/string';
 import type { Constructor } from '@videojs/utils/types';
 
+import type { AdapterHost } from '../html-media-adapter';
+
 /** CSS custom property names for video elements. */
 export const VideoCSSVars = {
   /** Border radius of the video element. */
@@ -22,8 +24,8 @@ export const VideoCSSVars = {
 /** CSS custom property names for audio elements. */
 export const AudioCSSVars = {} as const;
 
-/** Helper function to generate the HTML template for video elements. */
-function getVideoTemplateHTML(attrs: Record<string, string>): string {
+/** The default shadow template for a `<video>` host. */
+function videoTemplate(attrs: Record<string, string>): string {
   return /*html*/ `
     <style>
       :host {
@@ -55,8 +57,8 @@ function getVideoTemplateHTML(attrs: Record<string, string>): string {
   `;
 }
 
-/** Helper function to generate the HTML template for other elements. */
-function getCommonTemplateHTML(tag: string) {
+/** The default shadow template for any other host. */
+function commonTemplate(tag: string) {
   return (attrs: Record<string, string>) => {
     return /*html*/ `
       <style>
@@ -127,7 +129,12 @@ export interface PlaybackAdapter extends EventTarget {
   [key: string]: any;
 }
 
-type CustomMediaConstructor<T extends Constructor<PlaybackAdapter>> = Constructor<
+/** An adapter class: constructible without arguments and declaring the native element it drives. */
+export interface PlaybackAdapterConstructor<T extends PlaybackAdapter = PlaybackAdapter> extends Constructor<T> {
+  readonly host: AdapterHost;
+}
+
+type CustomMediaConstructor<T extends PlaybackAdapterConstructor> = Constructor<
   HTMLElement &
     InstanceType<T> & {
       readonly adapter: InstanceType<T>;
@@ -135,15 +142,19 @@ type CustomMediaConstructor<T extends Constructor<PlaybackAdapter>> = Constructo
     }
 > & {
   properties: Record<string, { type: any; attribute?: string; empty?: unknown }>;
-  getTemplateHTML: (attrs: Record<string, string>) => string;
+  template: (attrs: Record<string, string>) => string;
   shadowRootOptions: ShadowRootInit;
   readonly observedAttributes: string[];
 };
 
-export function CustomMediaElement<T extends Constructor<PlaybackAdapter>>(
-  tag: string,
+/**
+ * Build a custom element around an adapter. The element renders the adapter's `host` element in its shadow root,
+ * attaches the adapter to it, and forwards the adapter's properties, events, and content attributes.
+ */
+export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
   PlaybackAdapter: T
 ): CustomMediaConstructor<T> {
+  const tag = PlaybackAdapter.host;
   // Embed hosts (iframe) drive an external player rather than a native media
   // element, so attribute changes are not mirrored onto the iframe target and
   // there is no `<track>` / `<source>` syncing.
@@ -152,7 +163,7 @@ export function CustomMediaElement<T extends Constructor<PlaybackAdapter>>(
   let isDefined = false;
 
   class CustomMedia extends (globalThis.HTMLElement ?? class {}) {
-    static getTemplateHTML = tag.endsWith('video') ? getVideoTemplateHTML : getCommonTemplateHTML(tag);
+    static template = tag === 'video' ? videoTemplate : commonTemplate(tag);
     static shadowRootOptions: ShadowRootInit = { mode: 'open' };
     static properties = {
       autoPictureInPicture: { type: Boolean },
@@ -283,9 +294,9 @@ export function CustomMediaElement<T extends Constructor<PlaybackAdapter>>(
         // Embed templates (iframe) need adapter-bound attrs (e.g. `src`) to build the initial URL.
         const attrs: Record<string, string> = syncTargetAttributes ? omit(pickedAttrs, disallowedKeys) : pickedAttrs;
 
-        if (tag && !attrs.part) attrs.part = tag;
+        if (!attrs.part) attrs.part = tag;
 
-        this.shadowRoot!.innerHTML = ctor.getTemplateHTML(attrs);
+        this.shadowRoot!.innerHTML = ctor.template(attrs);
       }
 
       this.#mediaHost = new PlaybackAdapter();
diff --git a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
index 41684fe65f..92e588a2da 100644
--- a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
+++ b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
@@ -75,6 +75,8 @@ class TestAudioHost extends HTMLAudioAdapter {
 }
 
 class TestIframeHost extends EventTarget {
+  static readonly host = 'iframe' as const;
+
   target: EventTarget | null = null;
   attach(target: EventTarget | null) {
     this.target = target;
@@ -89,7 +91,7 @@ let tagCounter = 0;
 
 function defineVideoElement() {
   const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement('video', TestVideoHost);
+  const Ctor = CustomMediaElement(TestVideoHost);
 
   customElements.define(tag, Ctor);
   return { Ctor, tag };
@@ -97,7 +99,7 @@ function defineVideoElement() {
 
 function defineVideoElementWithObjects() {
   const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement('video', TestVideoHostWithObjects);
+  const Ctor = CustomMediaElement(TestVideoHostWithObjects);
 
   customElements.define(tag, Ctor);
   return { Ctor, tag };
@@ -105,7 +107,7 @@ function defineVideoElementWithObjects() {
 
 function defineAudioElement() {
   const tag = `test-audio-${++tagCounter}`;
-  const Ctor = CustomMediaElement('audio', TestAudioHost);
+  const Ctor = CustomMediaElement(TestAudioHost);
 
   customElements.define(tag, Ctor);
   return { Ctor, tag };
@@ -113,7 +115,7 @@ function defineAudioElement() {
 
 function defineIframeElement() {
   const tag = `test-iframe-${++tagCounter}`;
-  const Ctor = CustomMediaElement('iframe', TestIframeHost as never);
+  const Ctor = CustomMediaElement(TestIframeHost as never);
 
   customElements.define(tag, Ctor);
   return { Ctor, tag };
@@ -200,7 +202,7 @@ class TrackingVideoHost extends HTMLVideoAdapter {
 
 function defineTrackingVideoElement() {
   const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement('video', TrackingVideoHost);
+  const Ctor = CustomMediaElement(TrackingVideoHost);
 
   customElements.define(tag, Ctor);
   return { Ctor, tag };
@@ -1074,7 +1076,7 @@ describe('CustomMediaElement', () => {
 
   describe('subclass properties override', () => {
     it('includes subclass-added properties in observedAttributes', () => {
-      const Base = CustomMediaElement('video', TestVideoHost);
+      const Base = CustomMediaElement(TestVideoHost);
 
       class Extended extends Base {
         static properties = {
@@ -1091,7 +1093,7 @@ describe('CustomMediaElement', () => {
     });
 
     it('defines property accessors for subclass-added properties', () => {
-      const Base = CustomMediaElement('video', TestVideoHost);
+      const Base = CustomMediaElement(TestVideoHost);
 
       class Extended extends Base {
         static properties = {
@@ -1113,7 +1115,7 @@ describe('CustomMediaElement', () => {
     });
 
     it('subclass property setter sets the attribute', () => {
-      const Base = CustomMediaElement('video', TestVideoHost);
+      const Base = CustomMediaElement(TestVideoHost);
 
       class Extended extends Base {
         static properties = {
@@ -1155,10 +1157,10 @@ describe('CustomMediaElement', () => {
       const { Ctor } = defineVideoElement();
       const maliciousValue = '"><script>window.__xss=1</script><video x="';
 
-      // JSDOM shadow DOM has parsing quirks; test getTemplateHTML directly in a plain container.
+      // JSDOM shadow DOM has parsing quirks; test template directly in a plain container.
       const container = document.createElement('div');
 
-      container.innerHTML = (Ctor as any).getTemplateHTML({ crossorigin: maliciousValue });
+      container.innerHTML = (Ctor as any).template({ crossorigin: maliciousValue });
 
       expect(container.querySelectorAll('script')).toHaveLength(0);
       expect(container.querySelectorAll('img[onerror]')).toHaveLength(0);
@@ -1169,10 +1171,10 @@ describe('CustomMediaElement', () => {
       const { Ctor } = defineVideoElement();
       const maliciousValue = '"><img src=x onerror="window.__xss=1">';
 
-      // JSDOM shadow DOM has parsing quirks; test getTemplateHTML directly in a plain container.
+      // JSDOM shadow DOM has parsing quirks; test template directly in a plain container.
       const container = document.createElement('div');
 
-      container.innerHTML = (Ctor as any).getTemplateHTML({ poster: maliciousValue });
+      container.innerHTML = (Ctor as any).template({ poster: maliciousValue });
 
       expect(container.querySelectorAll('img')).toHaveLength(0);
       expect((globalThis as any).__xss).toBeUndefined();
diff --git a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
index 4b0e5489c9..a8cce06323 100644
--- a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
+++ b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
@@ -1,4 +1,6 @@
 import type { Audio, AudioEvents } from '../../core/types';
-import { HTMLMediaAdapter, type HTMLMediaTargetLike } from '../html-media-adapter';
+import { type AdapterHost, HTMLMediaAdapter, type HTMLMediaTargetLike } from '../html-media-adapter';
 
-export class HTMLAudioAdapter extends HTMLMediaAdapter<HTMLMediaTargetLike, AudioEvents> implements Audio {}
+export class HTMLAudioAdapter extends HTMLMediaAdapter<HTMLMediaTargetLike, AudioEvents> implements Audio {
+  static readonly host: AdapterHost = 'audio';
+}
diff --git a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
index d0bb01d057..e50e0376ae 100644
--- a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
+++ b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
@@ -19,6 +19,14 @@ export interface HTMLMediaTargetLike extends MediaTargetLike, EventTarget {
   querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E> | never[];
 }
 
+/**
+ * The native element an adapter drives, declared as its static `host`.
+ *
+ * Element façades read it to know what to render and attach to: `<video>` and `<audio>` for media adapters, `<iframe>`
+ * for embeds that drive an external player.
+ */
+export type AdapterHost = 'video' | 'audio' | 'iframe';
+
 /** An {@link HTMLMediaAdapter} over any target and event map: the shape extensions and element façades share. */
 export type AnyHTMLMediaAdapter<Target extends HTMLMediaTargetLike = any> = HTMLMediaAdapter<Target, any>;
 
diff --git a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index 056e4d35aa..5d165b9db5 100644
--- a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -2,11 +2,19 @@ import type { WebKitDocument, WebKitPresentationMode, WebKitVideoElement } from
 import { isFunction } from '@videojs/utils/predicate';
 
 import type { Video, VideoEvents, VideoTargetLike } from '../../core/types';
-import { getMediaProp, HTMLMediaAdapter, type HTMLMediaTargetLike, setMediaProp } from '../html-media-adapter';
+import {
+  type AdapterHost,
+  getMediaProp,
+  HTMLMediaAdapter,
+  type HTMLMediaTargetLike,
+  setMediaProp,
+} from '../html-media-adapter';
 
 export interface HTMLVideoTargetLike extends VideoTargetLike, HTMLMediaTargetLike {}
 
 export class HTMLVideoAdapter extends HTMLMediaAdapter<HTMLVideoTargetLike, VideoEvents> implements Video {
+  static readonly host: AdapterHost = 'video';
+
   get poster() {
     return getMediaProp(this, 'poster') ?? '';
   }

From b034e907ea50142a5dda6dac0adb5dac9a638a45 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 20:56:47 -0700
Subject: [PATCH 04/25] docs(site): resolve media element targets from the
 adapter host

The API-docs builder follows the host class chain, through mixin calls and
hoisted bases, to its static `host` or the `HTMLVideoAdapter` /
`HTMLAudioAdapter` root, now that neither factory names the target.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../spf/use-cases/audio-only-mode-override.md |   2 +-
 .../src/media-element-handler.ts              | 106 ++++++++++--------
 .../api-docs-builder/src/tests/e2e.test.ts    |   4 +-
 .../html/src/media/complex-video/adapter.ts   |   2 +-
 .../html/src/media/embed-video/adapter.ts     |   2 +-
 .../html/src/media/extending-video/adapter.ts |   2 +-
 .../html/src/media/mixin-video/adapter.ts     |   8 +-
 .../html/src/media/simple-video/adapter.ts    |   2 +-
 .../html/src/media/spf-audio/adapter.ts       |   6 +-
 .../custom-media-element.ts                   |   8 +-
 .../packages/media/src/dom/embed/adapter.ts   |   2 +
 .../html-audio-adapter/html-audio-adapter.ts  |   4 +-
 .../html-video-adapter/html-video-adapter.ts  |   2 +
 .../docs/reference/create-media-element.mdx   |   7 +-
 14 files changed, 91 insertions(+), 66 deletions(-)

diff --git a/internal/design/spf/use-cases/audio-only-mode-override.md b/internal/design/spf/use-cases/audio-only-mode-override.md
index 4045696aa1..770d6e4ee8 100644
--- a/internal/design/spf/use-cases/audio-only-mode-override.md
+++ b/internal/design/spf/use-cases/audio-only-mode-override.md
@@ -311,7 +311,7 @@ Public re-export: `@videojs/spf/hls-audio`.
 
 | Export | File | Purpose |
 |---|---|---|
-| `HlsAudio` | `media/hls-audio/adapter.ts` | Applies `MediaAttachMixin` + `CustomMediaElement('audio', HlsAudioAdapter)` |
+| `HlsAudio` | `media/hls-audio/adapter.ts` | Applies `MediaAttachMixin` + `CustomMediaElement(HlsAudioAdapter)`; the `<audio>` target comes from the adapter's static `host` |
 | `HlsAudioElement` (tag `hls-audio`) | `media/hls-audio/element.ts` | Custom-element implementation; `define/media/hls-audio.ts` registers it via `safeDefine` |
 
 CDN entry: `packages/html/src/define/media/hls-audio.ts` →
diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index 5d05c08fe4..51faf93fd0 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -288,6 +288,8 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
 
         // The composition may name the host through an import alias; property extraction needs the declared name.
         const hostClassName = host.declaration.id?.name ?? composition.hostClassName;
+        const targetTag = resolveHostTag(host.file, host.declaration, project, new Set());
+        if (!targetTag) continue;
 
         sources.push({
           defineFilePath: filePath,
@@ -296,8 +298,8 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
           mediaFilePath: mediaDeclaration.file.filePath,
           hostFilePath: host.file.filePath,
           hostClassName,
-          mediaType: composition.mediaType,
-          targetTag: composition.targetTag,
+          mediaType: targetTag === 'audio' || (targetTag === 'iframe' && name.endsWith('Audio')) ? 'audio' : 'video',
+          targetTag,
         });
       }
     }
@@ -327,12 +329,16 @@ function publicImplementationFiles(entryPath: string, project: OxcProject, visit
 }
 
 const MEDIA_ELEMENT_FACTORIES = new Set(['CustomMediaElement', 'createMediaElement']);
+const HOST_BASE_TAGS: Readonly<Record<string, MediaTargetTag>> = {
+  HTMLVideoAdapter: 'video',
+  HTMLAudioAdapter: 'audio',
+};
 
 function findCustomMediaComposition(
   file: SourceFile,
   declaration: Class,
   project: OxcProject
-): { hostClassName: string; mediaType: 'video' | 'audio'; targetTag: MediaTargetTag } | undefined {
+): { hostClassName: string } | undefined {
   const expressions: Expression[] = [];
 
   if (declaration.superClass) expressions.push(resolveLocalExpression(file, declaration.superClass, project));
@@ -344,55 +350,19 @@ function findCustomMediaComposition(
   }
 
   for (const expression of expressions) {
-    let found: { hostClassName: string; mediaType: 'video' | 'audio'; targetTag: MediaTargetTag } | undefined;
+    let found: { hostClassName: string } | undefined;
 
     walkAst(expression, (node) => {
       if (found || node.type !== 'CallExpression' || node.callee.type !== 'Identifier') return;
 
       if (!MEDIA_ELEMENT_FACTORIES.has(node.callee.name) || node.arguments.length < 1) return;
 
-      // `CustomMediaElement(tag, Host)` names the target first; `createMediaElement(Host, { tag })` from
-      // `@videojs/html` names the host first and defaults the target to `video`.
-      const fromFactory = node.callee.name === 'createMediaElement';
-      const host = fromFactory ? node.arguments[0] : node.arguments[1];
-      let target: Expression | undefined;
-
-      if (fromFactory) {
-        const options = node.arguments[1];
-        const tagProperty =
-          options?.type === 'ObjectExpression'
-            ? options.properties.find((entry) => entry.type === 'Property' && staticName(entry.key) === 'tag')
-            : undefined;
-
-        target =
-          tagProperty?.type === 'Property'
-            ? tagProperty.value
-            : ({ type: 'Literal', value: 'video', raw: "'video'", start: node.start, end: node.end } as Expression);
-      } else {
-        target = node.arguments[0]?.type === 'SpreadElement' ? undefined : node.arguments[0];
-      }
+      // `CustomMediaElement(Host)` from `@videojs/media/dom` and `createMediaElement(Host, options?)` from
+      // `@videojs/html` both name the host first; the target comes from the host's static `host`.
+      const host = node.arguments[0];
+      if (!host || host.type !== 'Identifier') return;
 
-      if (
-        !target ||
-        target.type !== 'Literal' ||
-        typeof target.value !== 'string' ||
-        !['video', 'audio', 'iframe'].includes(target.value) ||
-        !host ||
-        host.type !== 'Identifier'
-      ) {
-        return;
-      }
-
-      const targetTag = target.value as MediaTargetTag;
-
-      found = {
-        hostClassName: host.name,
-        targetTag,
-        mediaType:
-          targetTag === 'audio' || (targetTag === 'iframe' && declaration.id?.name.endsWith('Audio'))
-            ? 'audio'
-            : 'video',
-      };
+      found = { hostClassName: host.name };
     });
 
     if (found) return found;
@@ -401,6 +371,52 @@ function findCustomMediaComposition(
   return undefined;
 }
 
+/**
+ * The element a host attaches to, read from its static `host` or inherited from the base adapter it extends.
+ *
+ * Follows the extends chain through mixin calls (`MuxMixin(HlsAudioAdapter)`) and hoisted bases, stopping at the
+ * `HTMLVideoAdapter` / `HTMLAudioAdapter` roots or the first class that declares the static itself.
+ */
+function resolveHostTag(
+  file: SourceFile,
+  declaration: Class,
+  project: OxcProject,
+  visited: Set<string>
+): MediaTargetTag | undefined {
+  const declared = staticStringClassProperty(declaration, 'host');
+  if (declared === 'video' || declared === 'audio' || declared === 'iframe') return declared;
+
+  if (!declaration.superClass) return undefined;
+
+  return resolveHostTagFromBase(resolveLocalExpression(file, declaration.superClass, project), file, project, visited);
+}
+
+function resolveHostTagFromBase(
+  expression: Expression,
+  file: SourceFile,
+  project: OxcProject,
+  visited: Set<string>
+): MediaTargetTag | undefined {
+  const value = resolveLocalExpression(file, expression, project);
+
+  if (value.type === 'CallExpression') {
+    return resolveHostTagFromBase(unwindMixinChain(value).base, file, project, visited);
+  }
+
+  if (value.type !== 'Identifier') return undefined;
+
+  const known = HOST_BASE_TAGS[value.name];
+  const resolved = project.resolveName(file.filePath, value.name);
+  if (!resolved || resolved.declaration.type !== 'ClassDeclaration') return known;
+
+  const key = `${resolved.file.filePath}#${value.name}`;
+  if (visited.has(key)) return known;
+
+  visited.add(key);
+
+  return resolveHostTag(resolved.file, resolved.declaration, project, visited) ?? known;
+}
+
 function extractHostProperties(
   filePath: string,
   className: string,
diff --git a/site/scripts/api-docs-builder/src/tests/e2e.test.ts b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
index 7730d6f803..9af41c6ce4 100644
--- a/site/scripts/api-docs-builder/src/tests/e2e.test.ts
+++ b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
@@ -1509,8 +1509,8 @@ describe('Media element pipeline (end-to-end)', () => {
     });
 
     it('discovers elements built with createMediaElement as well as CustomMediaElement', () => {
-      // SimpleVideo composes through the factory (default target), MixinVideo names its target in the options object,
-      // and ComplexVideo composes through CustomMediaElement directly.
+      // SimpleVideo composes through the factory, MixinVideo through the factory with an options object, and
+      // ComplexVideo through CustomMediaElement directly; each target comes from the host's static `host`.
       expect(findElement('SimpleVideo')!.reference.platforms.html.target).toBe('video');
       expect(findElement('MixinVideo')!.reference.platforms.html.target).toBe('video');
       expect(findElement('ComplexVideo')!.reference.platforms.html.target).toBe('video');
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts
index 524bd5dec4..c11bfb7862 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts
@@ -13,4 +13,4 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class ComplexVideo extends MediaAttachMixin(CustomMediaElement('video', ComplexHost)) {}
+export class ComplexVideo extends MediaAttachMixin(CustomMediaElement(ComplexHost)) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts
index 9c0a39956e..e664c669ac 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts
@@ -5,6 +5,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-class EmbedCustomMediaElement extends CustomMediaElement('iframe', EmbedHost) {}
+class EmbedCustomMediaElement extends CustomMediaElement(EmbedHost) {}
 
 export class EmbedVideo extends MediaAttachMixin(EmbedCustomMediaElement) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts
index c2bd6b106c..0c33138342 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts
@@ -11,6 +11,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-const ExtendingVideoBase = MediaAttachMixin(CustomMediaElement('video', ExtendingHost));
+const ExtendingVideoBase = MediaAttachMixin(CustomMediaElement(ExtendingHost));
 
 export class ExtendingVideo extends (ExtendingVideoBase as typeof ExtendingVideoBase) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
index b85b273760..7de9fe8fe6 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
@@ -1,14 +1,14 @@
 /**
  * Mock mixin-chain media element — mirrors MuxVideo / NativeHlsVideo.
  *
- * Exercises: the `createMediaElement` factory with an options object naming the target, where the host is a mixin
- * chain.
+ * Exercises: the `createMediaElement` factory with an options object, where the host is a mixin chain whose target
+ * is inherited from the base host.
  */
 import { MixinHost } from '../../../../media/src/dom/mixin';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function createMediaElement(host: any, options?: { tag?: string }) {
+function createMediaElement(host: any, options?: { template?: (attrs: Record<string, string>) => string }) {
   return host;
 }
 
-export class MixinVideo extends createMediaElement(MixinHost, { tag: 'video' }) {}
+export class MixinVideo extends createMediaElement(MixinHost, { template: () => '<video></video>' }) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
index afa8dba720..25f39b43dc 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
@@ -8,7 +8,7 @@
 import { SimpleHost } from '../../../../media/src/dom/simple';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function createMediaElement(host: any, options?: { tag?: string }) {
+function createMediaElement(host: any, options?: { template?: (attrs: Record<string, string>) => string }) {
   return host;
 }
 
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts
index 90fcb819cf..e59832fdff 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts
@@ -1,8 +1,8 @@
 /**
  * Mock audio-only media element — mirrors HlsAudio.
  *
- * Exercises: audio media type ('audio' tag argument) with a cross-package
- * mixin host.
+ * Exercises: audio media type, inherited from the `HTMLAudioAdapter` root of a
+ * cross-package mixin host.
  */
 import { CustomMediaElement } from '../../../../media/src/dom/custom-media-element';
 import { SpfAudioHost } from '../../../../media/src/dom/spf-audio';
@@ -12,4 +12,4 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class SpfAudio extends MediaAttachMixin(CustomMediaElement('audio', SpfAudioHost)) {}
+export class SpfAudio extends MediaAttachMixin(CustomMediaElement(SpfAudioHost)) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 0e99fd8ef5..6b46a74aca 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -60,10 +60,12 @@ function getCommonTemplateHTML(tag: string) {
 }
 
 // Stub — the builder parses the AST, it doesn't run the code.
-// Mirrors the real CustomMediaElement factory signature.
-export function CustomMediaElement(tag: string, Host: any) {
+// Mirrors the real CustomMediaElement factory signature: the target is the host's static `host`.
+export function CustomMediaElement(Host: any) {
+  const tag: string = Host.host;
+
   class CustomMedia {
-    static getTemplateHTML = tag === 'video' ? getVideoTemplateHTML : getCommonTemplateHTML(tag);
+    static template = tag === 'video' ? getVideoTemplateHTML : getCommonTemplateHTML(tag);
     static shadowRootOptions = { mode: 'open' };
 
     static properties = {
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/embed/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/embed/adapter.ts
index 47d94613e5..c155a13995 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/embed/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/embed/adapter.ts
@@ -2,6 +2,8 @@
 import type { EmbedSource } from './source';
 
 export class EmbedHost extends EventTarget {
+  static readonly host = 'iframe';
+
   static readonly defaultProps = {
     src: '',
     autoplay: false,
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
index cbe918a764..d31fccbe26 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
@@ -6,4 +6,6 @@
  */
 import { HTMLMediaAdapter } from '../html-media-adapter';
 
-export class HTMLAudioAdapter extends HTMLMediaAdapter {}
+export class HTMLAudioAdapter extends HTMLMediaAdapter {
+  static readonly host = 'audio';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index d860172645..b50a4dd3f3 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -9,6 +9,8 @@
 import { HTMLMediaAdapter } from '../html-media-adapter';
 
 export class HTMLVideoAdapter extends HTMLMediaAdapter {
+  static readonly host = 'video';
+
   requestFullscreen(): Promise<void> {
     return Promise.resolve();
   }
diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index c595d3f386..014f4d3053 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -14,7 +14,7 @@ import { createMediaElement } from "@videojs/html";
 
 ## Usage
 
-Pass an adapter class. The returned element renders a `<video>` in its shadow root, drives it through the adapter, and registers itself with the surrounding <DocsLink slug="reference/player">player</DocsLink> on connect.
+Pass an adapter class. The returned element renders the adapter's host element in its shadow root, drives it through the adapter, and registers itself with the surrounding <DocsLink slug="reference/player">player</DocsLink> on connect. Every adapter declares its host as a static: `'video'` for `HlsJsAdapter`, `'audio'` for `HlsAudioAdapter`, `'iframe'` for the embed adapters.
 
 ```ts
 import { createMediaElement } from '@videojs/html';
@@ -25,18 +25,19 @@ export class MyHlsVideo extends createMediaElement(HlsJsAdapter) {}
 customElements.define('my-hls-video', MyHlsVideo);
 ```
 
-Pass `tag: 'audio'` for an audio adapter. Embeds pass `tag: 'iframe'` and a `template` that renders the provider's iframe from the element's initial attributes:
+Embeds pass a `template` that renders the provider's `<iframe>` from the element's initial attributes:
 
 ```ts
 import { createMediaElement } from '@videojs/html';
 import { VimeoAdapter } from '@videojs/vimeo-video';
 
 export class MyVimeoVideo extends createMediaElement(VimeoAdapter, {
-  tag: 'iframe',
   template: (attrs) => `<iframe part="iframe" src="${attrs.src ?? ''}" allowfullscreen></iframe>`,
 }) {}
 ```
 
+The template is also the element's static `template`, so a subclass can override it the same way.
+
 Every built-in media element except `<wistia-video>` and `<background-video>` is created this way. Subclass the result to add element behavior, such as extra observed attributes.
 
 ## Who needs this

From cf2a80bda7c9331cdc23b8a48169179f101814de Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 21:26:16 -0700
Subject: [PATCH 05/25] docs(site): escape the interpolated src in the embed
 template example

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 site/src/content/docs/reference/create-media-element.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index 014f4d3053..f18d2295fe 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -29,13 +29,16 @@ Embeds pass a `template` that renders the provider's `<iframe>` from the element
 
 ```ts
 import { createMediaElement } from '@videojs/html';
+import { escapeHtml } from '@videojs/utils/string';
 import { VimeoAdapter } from '@videojs/vimeo-video';
 
 export class MyVimeoVideo extends createMediaElement(VimeoAdapter, {
-  template: (attrs) => `<iframe part="iframe" src="${attrs.src ?? ''}" allowfullscreen></iframe>`,
+  template: (attrs) => `<iframe part="iframe" src="${escapeHtml(attrs.src ?? '')}" allowfullscreen></iframe>`,
 }) {}
 ```
 
+The template is written to the shadow root with `innerHTML`, so escape any attribute value you interpolate.
+
 The template is also the element's static `template`, so a subclass can override it the same way.
 
 Every built-in media element except `<wistia-video>` and `<background-video>` is created this way. Subclass the result to add element behavior, such as extra observed attributes.

From 0b927189c63a650ce350908739e39f236df1821d Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 21:26:21 -0700
Subject: [PATCH 06/25] fix(site): classify iframe audio elements from the
 media class name

The define file exports `SpotifyAudioElement`, so the `endsWith('Audio')`
check has to run on the suffix-stripped name. Adds an `EmbedAudio` fixture
so the iframe-audio path stays covered.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../api-docs-builder/src/media-element-handler.ts  |  9 +++++++--
 .../scripts/api-docs-builder/src/tests/e2e.test.ts | 12 +++++++++++-
 .../packages/html/src/define/media/embed-audio.ts  |  5 +++++
 .../packages/html/src/media/embed-audio/adapter.ts | 14 ++++++++++++++
 .../packages/html/src/media/embed-audio/index.ts   |  1 +
 5 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
 create mode 100644 site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts
 create mode 100644 site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts

diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index 51faf93fd0..94e6defa58 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -291,14 +291,19 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
         const targetTag = resolveHostTag(host.file, host.declaration, project, new Set());
         if (!targetTag) continue;
 
+        // An iframe says nothing about what it plays, so an embed's media type comes from its class name
+        // (`SpotifyAudio` against `VimeoVideo`); the `*Element` export in the define file carries a suffix.
+        const className = stripElementSuffix(name);
+        const isAudio = targetTag === 'audio' || (targetTag === 'iframe' && className.endsWith('Audio'));
+
         sources.push({
           defineFilePath: filePath,
-          className: stripElementSuffix(name),
+          className,
           tagName,
           mediaFilePath: mediaDeclaration.file.filePath,
           hostFilePath: host.file.filePath,
           hostClassName,
-          mediaType: targetTag === 'audio' || (targetTag === 'iframe' && name.endsWith('Audio')) ? 'audio' : 'video',
+          mediaType: isAudio ? 'audio' : 'video',
           targetTag,
         });
       }
diff --git a/site/scripts/api-docs-builder/src/tests/e2e.test.ts b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
index 9af41c6ce4..f4401c4ffe 100644
--- a/site/scripts/api-docs-builder/src/tests/e2e.test.ts
+++ b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
@@ -1500,6 +1500,7 @@ describe('Media element pipeline (end-to-end)', () => {
       expect(names).toEqual([
         'BarrelVideo',
         'ComplexVideo',
+        'EmbedAudio',
         'EmbedVideo',
         'ExtendingVideo',
         'MixinVideo',
@@ -1526,7 +1527,7 @@ describe('Media element pipeline (end-to-end)', () => {
     });
 
     it('produces one result per media element', () => {
-      expect(results.length).toBe(7);
+      expect(results.length).toBe(8);
     });
 
     it('follows nested public index barrels without including sibling implementations', () => {
@@ -1864,6 +1865,15 @@ describe('Media element pipeline (end-to-end)', () => {
       expect(Object.keys(react!.props).sort()).toEqual(['autoplay', 'source', 'src']);
     });
 
+    it('classifies an iframe-backed element as audio from its media class name', () => {
+      const audio = findElement('EmbedAudio')!.reference;
+      const video = findElement('EmbedVideo')!.reference;
+
+      expect(audio.platforms.html.target).toBe('iframe');
+      expect(audio.mediaType).toBe('audio');
+      expect(video.mediaType).toBe('video');
+    });
+
     it('extracts engine options by following the source property type', () => {
       const ref = findElement('EmbedVideo')!.reference;
 
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
new file mode 100644
index 0000000000..433f639256
--- /dev/null
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
@@ -0,0 +1,5 @@
+import { EmbedAudio } from '../../media/embed-audio';
+
+export class EmbedAudioElement extends EmbedAudio {
+  static readonly tagName = 'embed-audio';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts
new file mode 100644
index 0000000000..3e036844fc
--- /dev/null
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts
@@ -0,0 +1,14 @@
+/**
+ * Mock iframe-backed audio element — mirrors SpotifyAudio.
+ *
+ * Exercises: an `iframe` host classified as audio from the media class name, which the define file exports with an
+ * `Element` suffix.
+ */
+import { CustomMediaElement } from '../../../../media/src/dom/custom-media-element';
+import { EmbedHost } from '../../../../media/src/dom/embed';
+
+function MediaAttachMixin(base: any) {
+  return base;
+}
+
+export class EmbedAudio extends MediaAttachMixin(CustomMediaElement(EmbedHost)) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts
new file mode 100644
index 0000000000..7e77e9fc24
--- /dev/null
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts
@@ -0,0 +1 @@
+export * from './adapter';

From de7f4133b589c06119b679fcdd02ad0bc75c8dbb Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 21:26:24 -0700
Subject: [PATCH 07/25] refactor(media): narrow adapter host types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`HTMLVideoAdapter.host` is `'video' | 'audio'` so the hls.js
`MuxAudioAdapter` override still fits, and every other adapter keeps the
literal, so façades can read the host off the type as well as the value.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/adapters/cloudflare-video/src/adapter.ts    |  4 ++--
 packages/adapters/spotify-audio/src/adapter.ts       |  4 ++--
 packages/adapters/tiktok-video/src/adapter.ts        |  4 ++--
 packages/adapters/twitch-video/src/adapter.ts        |  4 ++--
 packages/adapters/vimeo-video/src/adapter.ts         |  4 ++--
 packages/adapters/youtube-video/src/adapter.ts       |  4 ++--
 .../src/dom/html-audio-adapter/html-audio-adapter.ts |  4 ++--
 .../src/dom/html-video-adapter/html-video-adapter.ts | 12 ++++--------
 8 files changed, 18 insertions(+), 22 deletions(-)

diff --git a/packages/adapters/cloudflare-video/src/adapter.ts b/packages/adapters/cloudflare-video/src/adapter.ts
index 7a1a27f8a5..15ca991749 100644
--- a/packages/adapters/cloudflare-video/src/adapter.ts
+++ b/packages/adapters/cloudflare-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type TextTrackListLike, type Video } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 
@@ -16,7 +16,7 @@ import { type CloudflareStreamApi, type CloudflareStreamPlayerApi, loadCloudflar
  *   new value.
  */
 export class CloudflareAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: CloudflareAdapterProps = {
     src: '',
diff --git a/packages/adapters/spotify-audio/src/adapter.ts b/packages/adapters/spotify-audio/src/adapter.ts
index 3a877e76e9..05daf0658b 100644
--- a/packages/adapters/spotify-audio/src/adapter.ts
+++ b/packages/adapters/spotify-audio/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements — License: MIT
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber } from '@videojs/utils/predicate';
@@ -22,7 +22,7 @@ import { buildSpotifyIframeSrc, parseSpotifySource, type SpotifySource } from '.
  *   new value.
  */
 export class SpotifyAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: SpotifyAdapterProps = {
     src: '',
diff --git a/packages/adapters/tiktok-video/src/adapter.ts b/packages/adapters/tiktok-video/src/adapter.ts
index 76208d44d4..8ebb714977 100644
--- a/packages/adapters/tiktok-video/src/adapter.ts
+++ b/packages/adapters/tiktok-video/src/adapter.ts
@@ -2,7 +2,7 @@
 // ported to TypeScript and reshaped as a media adapter (mirrors `dom/youtube`).
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -33,7 +33,7 @@ import { buildTikTokIframeSrc, shouldBootstrapTikTokEmbed, type TikTokSource } f
  *   new value.
  */
 export class TikTokAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: TikTokAdapterProps = {
     src: '',
diff --git a/packages/adapters/twitch-video/src/adapter.ts b/packages/adapters/twitch-video/src/adapter.ts
index d724b126cb..3a0b50c2e3 100644
--- a/packages/adapters/twitch-video/src/adapter.ts
+++ b/packages/adapters/twitch-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // License: MIT
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type Video } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -35,7 +35,7 @@ import { buildTwitchIframeSrc, parseTwitchSource, type TwitchSource } from './so
  *   new value.
  */
 export class TwitchAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: TwitchAdapterProps = {
     src: '',
diff --git a/packages/adapters/vimeo-video/src/adapter.ts b/packages/adapters/vimeo-video/src/adapter.ts
index 596a70def9..20f2a126fc 100644
--- a/packages/adapters/vimeo-video/src/adapter.ts
+++ b/packages/adapters/vimeo-video/src/adapter.ts
@@ -8,7 +8,7 @@ import {
   type TextTrackListLike,
   type Video,
 } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin, serializeEmbedParams } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin, serializeEmbedParams } from '@videojs/media/dom';
 import { createPublicPromise, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNull, isString, isUndefined } from '@videojs/utils/predicate';
@@ -65,7 +65,7 @@ export interface VimeoAdapterProps {
  *   for the new value.
  */
 export class VimeoAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: VimeoAdapterProps = {
     src: '',
diff --git a/packages/adapters/youtube-video/src/adapter.ts b/packages/adapters/youtube-video/src/adapter.ts
index 08b9da83d8..3d6127b724 100644
--- a/packages/adapters/youtube-video/src/adapter.ts
+++ b/packages/adapters/youtube-video/src/adapter.ts
@@ -3,7 +3,7 @@
 // Source: https://github.com/muxinc/media-elements
 
 import { EMPTY_TEXT_TRACKS, EMPTY_TIME_RANGES, MediaError, type TextTrackListLike, type Video } from '@videojs/media';
-import { type AdapterHost, createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
+import { createTimeRange, MediaPlayedRangesMixin } from '@videojs/media/dom';
 import { createPublicPromise, noop, type PublicPromise, tryCall } from '@videojs/utils/function';
 import { deepEqual } from '@videojs/utils/object';
 import { isNumber, isUndefined } from '@videojs/utils/predicate';
@@ -24,7 +24,7 @@ import type { YouTubeAdapterProps } from './props';
 import { buildYouTubeIframeSrc, parseYouTubeSource, type YouTubeSource } from './source';
 
 export class YouTubeAdapter extends MediaPlayedRangesMixin(EventTarget) implements Partial<Video> {
-  static readonly host: AdapterHost = 'iframe';
+  static readonly host = 'iframe';
 
   static readonly defaultProps: YouTubeAdapterProps = {
     src: '',
diff --git a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
index a8cce06323..5eb255d927 100644
--- a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
+++ b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
@@ -1,6 +1,6 @@
 import type { Audio, AudioEvents } from '../../core/types';
-import { type AdapterHost, HTMLMediaAdapter, type HTMLMediaTargetLike } from '../html-media-adapter';
+import { HTMLMediaAdapter, type HTMLMediaTargetLike } from '../html-media-adapter';
 
 export class HTMLAudioAdapter extends HTMLMediaAdapter<HTMLMediaTargetLike, AudioEvents> implements Audio {
-  static readonly host: AdapterHost = 'audio';
+  static readonly host = 'audio';
 }
diff --git a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index 5d165b9db5..9a2945cd5d 100644
--- a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -2,18 +2,14 @@ import type { WebKitDocument, WebKitPresentationMode, WebKitVideoElement } from
 import { isFunction } from '@videojs/utils/predicate';
 
 import type { Video, VideoEvents, VideoTargetLike } from '../../core/types';
-import {
-  type AdapterHost,
-  getMediaProp,
-  HTMLMediaAdapter,
-  type HTMLMediaTargetLike,
-  setMediaProp,
-} from '../html-media-adapter';
+import { getMediaProp, HTMLMediaAdapter, type HTMLMediaTargetLike, setMediaProp } from '../html-media-adapter';
 
 export interface HTMLVideoTargetLike extends VideoTargetLike, HTMLMediaTargetLike {}
 
 export class HTMLVideoAdapter extends HTMLMediaAdapter<HTMLVideoTargetLike, VideoEvents> implements Video {
-  static readonly host: AdapterHost = 'video';
+  // Typed to admit `'audio'` so an adapter built on the video base can override it and play in an `<audio>`, as the
+  // hls.js-backed `MuxAudioAdapter` does. Element façades treat anything not narrowed to `'audio'` as a video.
+  static readonly host: 'video' | 'audio' = 'video';
 
   get poster() {
     return getMediaProp(this, 'poster') ?? '';

From 8aa7df537553f4c521f56dd8060d2e4db058a77e Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 21:46:04 -0700
Subject: [PATCH 08/25] refactor(media): name the CustomMediaElement parameter
 Adapter

It shadowed the `PlaybackAdapter` interface; the builder fixture stub
mirrors the name and types the static `host` it reads.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../custom-media-element/custom-media-element.ts | 16 +++++-----------
 .../html/src/media/mixin-video/adapter.ts        |  4 ++--
 .../html/src/media/simple-video/adapter.ts       |  4 ++--
 .../custom-media-element/custom-media-element.ts |  6 +++---
 4 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/packages/media/src/dom/custom-media-element/custom-media-element.ts b/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 09a7d5707e..87c1528d2e 100644
--- a/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -151,10 +151,8 @@ type CustomMediaConstructor<T extends PlaybackAdapterConstructor> = Constructor<
  * Build a custom element around an adapter. The element renders the adapter's `host` element in its shadow root,
  * attaches the adapter to it, and forwards the adapter's properties, events, and content attributes.
  */
-export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
-  PlaybackAdapter: T
-): CustomMediaConstructor<T> {
-  const tag = PlaybackAdapter.host;
+export function CustomMediaElement<T extends PlaybackAdapterConstructor>(Adapter: T): CustomMediaConstructor<T> {
+  const tag = Adapter.host;
   // Embed hosts (iframe) drive an external player rather than a native media
   // element, so attribute changes are not mirrored onto the iframe target and
   // there is no `<track>` / `<source>` syncing.
@@ -199,17 +197,13 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
 
       const properties = ctor.properties as PropertyConfigs;
 
-      for (
-        let proto = PlaybackAdapter.prototype;
-        proto && proto !== Object.prototype;
-        proto = Object.getPrototypeOf(proto)
-      ) {
+      for (let proto = Adapter.prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
         for (const prop of Object.getOwnPropertyNames(proto)) {
           if (prop in CustomMedia.prototype || excludedProperties.includes(prop)) continue;
 
           // An alias keeps reflecting its attribute through the `properties`
           // loop below rather than reaching the adapter.
-          if (isAttributeAlias(prop, properties, PlaybackAdapter.prototype)) continue;
+          if (isAttributeAlias(prop, properties, Adapter.prototype)) continue;
 
           const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
           if (!descriptor) continue;
@@ -299,7 +293,7 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
         this.shadowRoot!.innerHTML = ctor.template(attrs);
       }
 
-      this.#mediaHost = new PlaybackAdapter();
+      this.#mediaHost = new Adapter();
       this.#attachToTarget();
 
       this.#childObserver = new MutationObserver(this.#syncMediaChildAttribute.bind(this));
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
index 7de9fe8fe6..3761649924 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
@@ -7,8 +7,8 @@
 import { MixinHost } from '../../../../media/src/dom/mixin';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function createMediaElement(host: any, options?: { template?: (attrs: Record<string, string>) => string }) {
-  return host;
+function createMediaElement(adapter: any, options?: { template?: (attrs: Record<string, string>) => string }) {
+  return adapter;
 }
 
 export class MixinVideo extends createMediaElement(MixinHost, { template: () => '<video></video>' }) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
index 25f39b43dc..5e0bf14dcd 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
@@ -8,8 +8,8 @@
 import { SimpleHost } from '../../../../media/src/dom/simple';
 
 // Stub — the builder parses the AST, it doesn't run the code.
-function createMediaElement(host: any, options?: { template?: (attrs: Record<string, string>) => string }) {
-  return host;
+function createMediaElement(adapter: any, options?: { template?: (attrs: Record<string, string>) => string }) {
+  return adapter;
 }
 
 export class SimpleVideo extends createMediaElement(SimpleHost) {}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 6b46a74aca..0107ef2b73 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -60,9 +60,9 @@ function getCommonTemplateHTML(tag: string) {
 }
 
 // Stub — the builder parses the AST, it doesn't run the code.
-// Mirrors the real CustomMediaElement factory signature: the target is the host's static `host`.
-export function CustomMediaElement(Host: any) {
-  const tag: string = Host.host;
+// Mirrors the real CustomMediaElement factory signature: the target is the adapter's static `host`.
+export function CustomMediaElement(Adapter: { readonly host: 'video' | 'audio' | 'iframe' }) {
+  const tag = Adapter.host;
 
   class CustomMedia {
     static template = tag === 'video' ? getVideoTemplateHTML : getCommonTemplateHTML(tag);

From 872202e82bc73768d8fb9433097799eb09336c91 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:46:31 -0700
Subject: [PATCH 09/25] feat(adapters): declare streamType where it was
 configurable but undeclared

`streamType` is settable on every media adapter, but the DASH and SPF audio
adapters left it out of `defaultProps`, so neither `<dash-video stream-type>`
nor the React `streamType` prop reached them by contract.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/adapters/dash-video/src/adapter.ts           | 4 +++-
 packages/adapters/dash-video/src/server.ts            | 2 ++
 packages/spf/src/playback/adapters/hls-audio/mixin.ts | 3 +++
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/adapters/dash-video/src/adapter.ts b/packages/adapters/dash-video/src/adapter.ts
index a932064465..a5ed297554 100644
--- a/packages/adapters/dash-video/src/adapter.ts
+++ b/packages/adapters/dash-video/src/adapter.ts
@@ -1,4 +1,4 @@
-import type { EngineAdapter } from '@videojs/media';
+import { type EngineAdapter, type MediaStreamType, MediaStreamTypes } from '@videojs/media';
 import { HTMLVideoAdapter } from '@videojs/media/dom';
 import { MediaTracksMixin } from '@videojs/media/media-tracks';
 import { deepEqual } from '@videojs/utils/object';
@@ -23,6 +23,7 @@ export interface DashEngineConfig {
 export interface DashAdapterProps {
   src: string;
   source: DashSource | null;
+  streamType: MediaStreamType;
 }
 
 class DashAdapterCore
@@ -32,6 +33,7 @@ class DashAdapterCore
   static readonly defaultProps: DashAdapterProps = {
     src: '',
     source: null,
+    streamType: MediaStreamTypes.UNKNOWN,
   };
 
   #engine: dashjs.MediaPlayerClass;
diff --git a/packages/adapters/dash-video/src/server.ts b/packages/adapters/dash-video/src/server.ts
index 11880f8050..64f7089a2c 100644
--- a/packages/adapters/dash-video/src/server.ts
+++ b/packages/adapters/dash-video/src/server.ts
@@ -1,3 +1,4 @@
+import { MediaStreamTypes } from '@videojs/media';
 import { HTMLVideoAdapter } from '@videojs/media/dom';
 import { MediaTracksMixin } from '@videojs/media/media-tracks';
 
@@ -10,6 +11,7 @@ export class DashAdapter extends MediaTracksMixin(HTMLVideoAdapter) implements D
   static readonly defaultProps: DashAdapterProps = {
     src: '',
     source: null,
+    streamType: MediaStreamTypes.UNKNOWN,
   };
 
   readonly engine = null;
diff --git a/packages/spf/src/playback/adapters/hls-audio/mixin.ts b/packages/spf/src/playback/adapters/hls-audio/mixin.ts
index e841dfa1a7..0e3514822c 100644
--- a/packages/spf/src/playback/adapters/hls-audio/mixin.ts
+++ b/packages/spf/src/playback/adapters/hls-audio/mixin.ts
@@ -1,3 +1,4 @@
+import { type MediaStreamType, MediaStreamTypes } from '@videojs/media';
 import type { Constructor, MixinReturn } from '@videojs/utils/types';
 
 import type { Composition } from '../../../core/composition/create-composition';
@@ -26,6 +27,7 @@ export interface HlsAudioAdapterProps {
   src: string;
   preload: '' | 'none' | 'metadata' | 'auto';
   disableRemotePlayback: boolean;
+  streamType: MediaStreamType;
 }
 
 export interface HlsAudioAdapterAPI extends HlsAudioAdapterProps {
@@ -69,6 +71,7 @@ export function HlsAudioMixin<Base extends Constructor<any>>(BaseClass: Base) {
       src: '',
       preload: '',
       disableRemotePlayback: false,
+      streamType: MediaStreamTypes.UNKNOWN,
     };
 
     /**

From 9e1f13db9ad382599cce5ebf0715c954e4c8707c Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:46:34 -0700
Subject: [PATCH 10/25] refactor(media)!: build media elements from the adapter
 contract

An adapter declares two statics, `host` and `defaultProps`, and the element
derives everything else from them. Each primitive default becomes a content
attribute of that type, named by its WHATWG spelling or kebab-case, and reset
to the default when removed; objects stay property-only. The base adapters
declare the attributes their native element accepts (`videoContentAttributes`,
`audioContentAttributes`), which pass through to the inner element; an iframe
passes nothing. `static properties` is gone.

`CustomMediaElement(Adapter, { template? })` is now a thin composition of
pieces that stand on their own: `renderHost`, `AdapterAttachment`,
`forwardAdapter` / `reflectAttributes` / `bridgeEvent`, and `MediaChildren`.
Definition state is per class and the light-DOM target lookup only adopts
direct children.

BREAKING CHANGE: `CustomMediaElement` no longer takes a tag or exposes
`static properties`; adapters must declare `static host` and
`static defaultProps`. Audio elements drop the video-only attributes and
embeds reflect only the attributes their adapter declares.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../html/src/media/create-media-element.ts    |   27 +-
 .../media/tests/create-media-element.test.ts  |    5 +-
 .../custom-media-element/attach-adapter.ts    |   44 +
 .../dom/custom-media-element/attributes.ts    |  113 ++
 .../custom-media-element.ts                   |  478 ++-----
 .../custom-media-element/element-surface.ts   |  103 ++
 .../src/dom/custom-media-element/index.ts     |    6 +
 .../custom-media-element/media-children.ts    |   80 ++
 .../dom/custom-media-element/render-host.ts   |   41 +
 .../src/dom/custom-media-element/templates.ts |   83 ++
 .../tests/custom-media-element.test.ts        | 1189 +++++------------
 .../tests/media-children.test.ts              |   70 +
 .../html-audio-adapter/html-audio-adapter.ts  |   10 +-
 .../html-media-adapter/html-media-adapter.ts  |   30 +
 .../html-video-adapter/html-video-adapter.ts  |   18 +-
 15 files changed, 1008 insertions(+), 1289 deletions(-)
 create mode 100644 packages/media/src/dom/custom-media-element/attach-adapter.ts
 create mode 100644 packages/media/src/dom/custom-media-element/attributes.ts
 create mode 100644 packages/media/src/dom/custom-media-element/element-surface.ts
 create mode 100644 packages/media/src/dom/custom-media-element/media-children.ts
 create mode 100644 packages/media/src/dom/custom-media-element/render-host.ts
 create mode 100644 packages/media/src/dom/custom-media-element/templates.ts
 create mode 100644 packages/media/src/dom/custom-media-element/tests/media-children.test.ts

diff --git a/packages/html/src/media/create-media-element.ts b/packages/html/src/media/create-media-element.ts
index 363e9d6121..72e31bf9db 100644
--- a/packages/html/src/media/create-media-element.ts
+++ b/packages/html/src/media/create-media-element.ts
@@ -1,22 +1,21 @@
-import { CustomMediaElement, type PlaybackAdapterConstructor } from '@videojs/media/dom';
+import {
+  CustomMediaElement,
+  type CustomMediaElementOptions,
+  type PlaybackAdapterConstructor,
+} from '@videojs/media/dom';
 
 import { MediaAttachMixin } from '../store/media-attach-mixin';
 
-export interface CreateMediaElementOptions {
-  /**
-   * Shadow template for the element, given its initial attributes. Defaults to the adapter's bare `host` element;
-   * embeds pass one that renders their `<iframe>` with the provider's attributes and initial URL.
-   */
-  template?: (attrs: Record<string, string>) => string;
-}
+export type CreateMediaElementOptions = CustomMediaElementOptions;
 
 /**
  * Build a custom element that plays through an adapter and registers itself with the surrounding player.
  *
  * The element renders the adapter's `host` element (`<video>`, `<audio>`, or `<iframe>`) in its shadow root, attaches
- * the adapter to it, and mirrors its attributes onto the adapter's properties. Connecting it inside a player registers
- * it as the player's media, the same way the built-in `<hlsjs-video>`, `<dash-video>`, and `<vimeo-video>` elements do.
- * Subclass the result to add element behavior, then register it with `customElements.define()`.
+ * the adapter to it, and reflects the adapter's `defaultProps` as content attributes alongside the ones the host
+ * accepts natively. Connecting it inside a player registers it as the player's media, the same way the built-in
+ * `<hlsjs-video>`, `<dash-video>`, and `<vimeo-video>` elements do. Subclass the result to add element behavior, then
+ * register it with `customElements.define()`.
  *
  * @param Adapter - Adapter class that drives playback, for example `HlsJsAdapter` from `@videojs/hlsjs-video`.
  * @param options - For embeds, the shadow template that renders the `<iframe>`.
@@ -25,9 +24,5 @@ export function createMediaElement<Adapter extends PlaybackAdapterConstructor>(
   Adapter: Adapter,
   options: CreateMediaElementOptions = {}
 ): ReturnType<typeof CustomMediaElement<Adapter>> {
-  const Element = CustomMediaElement(Adapter);
-
-  if (options.template) Element.template = options.template;
-
-  return MediaAttachMixin(Element);
+  return MediaAttachMixin(CustomMediaElement(Adapter, options));
 }
diff --git a/packages/html/src/media/tests/create-media-element.test.ts b/packages/html/src/media/tests/create-media-element.test.ts
index ee11a4b536..99978fbfe7 100644
--- a/packages/html/src/media/tests/create-media-element.test.ts
+++ b/packages/html/src/media/tests/create-media-element.test.ts
@@ -6,7 +6,7 @@ import { createPlayer } from '../../player/create-player';
 import { createMediaElement } from '../create-media-element';
 
 class FakeAdapter extends HTMLVideoAdapter {
-  static defaultProps = { src: '' };
+  static readonly defaultProps = { src: '' };
 
   #src = '';
 
@@ -20,7 +20,7 @@ class FakeAdapter extends HTMLVideoAdapter {
 }
 
 class FakeAudioAdapter extends HTMLAudioAdapter {
-  static defaultProps = { src: '' };
+  static readonly defaultProps = { src: '' };
 
   #src = '';
 
@@ -35,6 +35,7 @@ class FakeAudioAdapter extends HTMLAudioAdapter {
 
 class FakeEmbedAdapter extends EventTarget {
   static readonly host = 'iframe' as const;
+  static readonly defaultProps = {};
 
   target: EventTarget | null = null;
 
diff --git a/packages/media/src/dom/custom-media-element/attach-adapter.ts b/packages/media/src/dom/custom-media-element/attach-adapter.ts
new file mode 100644
index 0000000000..2a46472e8b
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/attach-adapter.ts
@@ -0,0 +1,44 @@
+import type { PlaybackAdapter } from './custom-media-element';
+
+/**
+ * Keeps an adapter attached to whichever element `target()` currently resolves to, and destroys it once the host has
+ * left the document for good.
+ */
+export class AdapterAttachment {
+  #host: HTMLElement;
+  #adapter: PlaybackAdapter;
+  #target: () => Element | null;
+
+  /**
+   * @param host - The custom element that owns the adapter.
+   * @param adapter - The adapter to keep attached.
+   * @param target - Resolves the element to attach to; re-run on every `attach()`.
+   */
+  constructor(host: HTMLElement, adapter: PlaybackAdapter, target: () => Element | null) {
+    this.#host = host;
+    this.#adapter = adapter;
+    this.#target = target;
+  }
+
+  /** Attach to the current target if it changed. Call after construction and whenever the target may have moved. */
+  attach(): void {
+    const target = this.#target();
+    if (target === this.#adapter.target) return;
+
+    if (this.#adapter.target) this.#adapter.detach();
+
+    this.#adapter.attach(target);
+  }
+
+  /**
+   * Call from `disconnectedCallback`. Destroys the adapter a microtask later, so a synchronous move to a new parent
+   * keeps it; a `keep-alive` attribute on the host opts out entirely.
+   */
+  release(): void {
+    if (this.#host.hasAttribute('keep-alive')) return;
+
+    queueMicrotask(() => {
+      if (!this.#host.isConnected) this.#adapter.destroy();
+    });
+  }
+}
diff --git a/packages/media/src/dom/custom-media-element/attributes.ts b/packages/media/src/dom/custom-media-element/attributes.ts
new file mode 100644
index 0000000000..0daf05d4ab
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/attributes.ts
@@ -0,0 +1,113 @@
+import { isBoolean, isFunction, isNumber, isString } from '@videojs/utils/predicate';
+import { kebabCase } from '@videojs/utils/string';
+import type { Constructor } from '@videojs/utils/types';
+
+import type { AttributeConfig, AttributeConfigs } from '../html-media-adapter';
+
+/** The WHATWG spellings for the media properties whose attribute is not their kebab-cased name. */
+export const mediaAttributeNames: Readonly<Record<string, string>> = {
+  autoPictureInPicture: 'autopictureinpicture',
+  controlsList: 'controlslist',
+  crossOrigin: 'crossorigin',
+  defaultMuted: 'muted',
+  disablePictureInPicture: 'disablepictureinpicture',
+  disableRemotePlayback: 'disableremoteplayback',
+  playsInline: 'playsinline',
+};
+
+/** Live playback state has no content attribute, even when an adapter lists a default for it. */
+export const stateProps: ReadonlySet<string> = new Set(['muted', 'volume', 'currentTime', 'playbackRate']);
+
+/** The content attribute a property is driven by: its WHATWG spelling if it has one, else kebab-case. */
+export function attributeName(prop: string, config?: AttributeConfig): string {
+  return config?.attribute ?? mediaAttributeNames[prop] ?? kebabCase(prop);
+}
+
+/**
+ * The content attributes an adapter's `defaultProps` declare: one per primitive default, typed by that default and
+ * reset to it when the attribute is removed. Object defaults such as `source` stay property-only.
+ */
+export function derivedAttributes(defaultProps: object): AttributeConfigs {
+  const configs: AttributeConfigs = {};
+
+  for (const [prop, value] of Object.entries(defaultProps)) {
+    if (stateProps.has(prop)) continue;
+
+    const type = isBoolean(value) ? Boolean : isNumber(value) ? Number : isString(value) ? String : undefined;
+    if (!type) continue;
+
+    configs[prop] = { type, attribute: attributeName(prop), empty: value };
+  }
+
+  return configs;
+}
+
+/** Coerce an attribute string to the type its config declares. */
+export function coerceAttribute(value: string | null, config: AttributeConfig): unknown {
+  if (config.type === Boolean) return value !== null;
+
+  if (value === null) return 'empty' in config ? config.empty : config.type === Number ? 0 : '';
+
+  return config.type === Number ? Number(value) : value;
+}
+
+/**
+ * How an element routes its content attributes.
+ *
+ * An attribute whose property the adapter can set is owned by that property: the attribute writes the adapter, and the
+ * property writes the attribute. `defaultMuted` declares `attribute: 'muted'`, but `muted` is a settable property in
+ * its own right and owns that attribute, so the alias only reflects it.
+ */
+export interface AttributeRoutes {
+  /** Attribute names to observe, in declaration order. */
+  observed: string[];
+  /** Adapter property by attribute name, for the attributes an adapter property owns. */
+  ownerOf: Map<string, string>;
+  /** Attribute name by adapter property, for the properties that reflect through one. */
+  attributeOf: Map<string, string>;
+  /** Config by attribute name, for coercion. */
+  configOf: Map<string, AttributeConfig>;
+  /** Properties that only reflect their attribute: aliases and attributes the adapter has no setter for. */
+  reflected: Map<string, { attribute: string; config: AttributeConfig }>;
+}
+
+export function buildRoutes(configs: AttributeConfigs, Adapter: Constructor<object>): AttributeRoutes {
+  const routes: AttributeRoutes = {
+    observed: [],
+    ownerOf: new Map(),
+    attributeOf: new Map(),
+    configOf: new Map(),
+    reflected: new Map(),
+  };
+
+  for (const [prop, config] of Object.entries(configs)) {
+    const attribute = attributeName(prop, config);
+    const alias =
+      config.attribute !== prop && hasSetter(Adapter.prototype, config.attribute) ? config.attribute : undefined;
+    const owner = alias ?? (hasSetter(Adapter.prototype, prop) ? prop : undefined);
+
+    if (!routes.configOf.has(attribute)) routes.observed.push(attribute);
+
+    routes.configOf.set(attribute, config);
+
+    if (owner) {
+      routes.ownerOf.set(attribute, owner);
+      routes.attributeOf.set(owner, attribute);
+    }
+
+    if (owner !== prop) routes.reflected.set(prop, { attribute, config });
+  }
+
+  return routes;
+}
+
+function hasSetter(prototype: object, prop: string | undefined): boolean {
+  if (!prop) return false;
+
+  for (let proto = prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
+    if (descriptor) return isFunction(descriptor.set);
+  }
+
+  return false;
+}
diff --git a/packages/media/src/dom/custom-media-element/custom-media-element.ts b/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 87c1528d2e..cc83e5ed97 100644
--- a/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -1,125 +1,14 @@
-import { namedNodeMapToObject, serializeAttributes } from '@videojs/utils/dom';
-import { omit, pick } from '@videojs/utils/object';
-import { kebabCase } from '@videojs/utils/string';
 import type { Constructor } from '@videojs/utils/types';
 
-import type { AdapterHost } from '../html-media-adapter';
-
-/** CSS custom property names for video elements. */
-export const VideoCSSVars = {
-  /** Border radius of the video element. */
-  borderRadius: '--media-video-border-radius',
-  /** Object fit for the video. */
-  objectFit: '--media-object-fit',
-  /** Object position for the video. */
-  objectPosition: '--media-object-position',
-  /** Duration of the caption track transition. */
-  captionTrackDuration: '--media-caption-track-duration',
-  /** Delay before the caption track transition. */
-  captionTrackDelay: '--media-caption-track-delay',
-  /** Vertical offset of the caption track. */
-  captionTrackY: '--media-caption-track-y',
-} as const;
-
-/** CSS custom property names for audio elements. */
-export const AudioCSSVars = {} as const;
-
-/** The default shadow template for a `<video>` host. */
-function videoTemplate(attrs: Record<string, string>): string {
-  return /*html*/ `
-    <style>
-      :host {
-        display: contents;
-      }
-
-      video {
-        display: block;
-        width: 100%;
-        height: 100%;
-        border-radius: var(${VideoCSSVars.borderRadius});
-        object-fit: var(${VideoCSSVars.objectFit}, contain);
-        object-position: var(${VideoCSSVars.objectPosition}, center);
-      }
-
-      video::-webkit-media-text-track-container {
-        transition: translate var(${VideoCSSVars.captionTrackDuration}, 0) ease-out;
-        transition-delay: var(${VideoCSSVars.captionTrackDelay}, 0);
-        translate: 0 var(${VideoCSSVars.captionTrackY}, 0);
-        scale: 0.98;
-        z-index: 1;
-        font-family: inherit;
-      }
-    </style>
-    <slot name="media">
-      <video${serializeAttributes(attrs)}></video>
-    </slot>
-    <slot></slot>
-  `;
-}
-
-/** The default shadow template for any other host. */
-function commonTemplate(tag: string) {
-  return (attrs: Record<string, string>) => {
-    return /*html*/ `
-      <style>
-        :host {
-          display: inline-flex;
-          line-height: 0;
-          flex-direction: column;
-          justify-content: end;
-        }
-
-        ${tag} {
-          width: 100%;
-        }
-      </style>
-      <slot name="media">
-        <${tag}${serializeAttributes(attrs)}></${tag}>
-      </slot>
-      <slot></slot>
-    `;
-  };
-}
-
-const excludedProperties = ['attach', 'detach', 'destroy'];
-
-/** How a property declares the content attribute that drives it. */
-type PropertyConfig = { type: any; attribute?: string; empty?: unknown };
-type PropertyConfigs = Record<string, PropertyConfig>;
-
-/**
- * The content attribute a property is driven by.
- *
- * Attributes HTML already defines are squashed lowercase (`playsInline` -> `playsinline`), while the custom ones are
- * kebab-case (`streamType` -> `stream-type`) and name themselves through `attribute`. Undeclared properties are this
- * library's own, so they take kebab-case too.
- */
-function attributeName(prop: string, properties: PropertyConfigs): string {
-  const config = properties[prop];
-
-  return config ? (config.attribute ?? prop.toLowerCase()) : kebabCase(prop);
-}
-
-/**
- * Whether a property's declared attribute is really another property's.
- *
- * For example: `defaultMuted` declares `attribute: 'muted'`, but `muted` is a property in its own right and owns that
- * attribute, so the alias defers to it.
- */
-function isAttributeAlias(prop: string, properties: PropertyConfigs, hostPrototype: object): boolean {
-  const { attribute } = properties[prop] ?? {};
-
-  return !!attribute && attribute in hostPrototype;
-}
-
-/** Coerce an attribute string to the type the adapter property already holds. */
-function propertyValueFor(attrValue: string | null, current: unknown, config?: PropertyConfig): unknown {
-  if (typeof current === 'boolean') return attrValue !== null;
-
-  if (typeof current === 'number') return Number(attrValue);
-
-  return attrValue ?? (config && 'empty' in config ? config.empty : '');
-}
+import { audioContentAttributes } from '../html-audio-adapter';
+import { type AdapterHost, type AttributeConfigs } from '../html-media-adapter';
+import { videoContentAttributes } from '../html-video-adapter';
+import { AdapterAttachment } from './attach-adapter';
+import { attributeName, buildRoutes, coerceAttribute, derivedAttributes } from './attributes';
+import { bridgeEvent, forwardAdapter, reflectAttributes } from './element-surface';
+import { MediaChildren } from './media-children';
+import { initialAttributes, renderHost } from './render-host';
+import { defaultTemplate, type MediaTemplate } from './templates';
 
 export interface PlaybackAdapter extends EventTarget {
   attach(target: EventTarget | null): void;
@@ -129,9 +18,18 @@ export interface PlaybackAdapter extends EventTarget {
   [key: string]: any;
 }
 
-/** An adapter class: constructible without arguments and declaring the native element it drives. */
+/**
+ * An adapter class as an element sees it: constructible without arguments, naming the element it drives, and declaring
+ * its configurable properties with their defaults.
+ */
 export interface PlaybackAdapterConstructor<T extends PlaybackAdapter = PlaybackAdapter> extends Constructor<T> {
   readonly host: AdapterHost;
+  readonly defaultProps: object;
+}
+
+export interface CustomMediaElementOptions {
+  /** Shadow template, given the element's initial attributes. Defaults to the bare host element in a `media` slot. */
+  template?: MediaTemplate;
 }
 
 type CustomMediaConstructor<T extends PlaybackAdapterConstructor> = Constructor<
@@ -141,209 +39,99 @@ type CustomMediaConstructor<T extends PlaybackAdapterConstructor> = Constructor<
       attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     }
 > & {
-  properties: Record<string, { type: any; attribute?: string; empty?: unknown }>;
-  template: (attrs: Record<string, string>) => string;
+  template: MediaTemplate;
   shadowRootOptions: ShadowRootInit;
   readonly observedAttributes: string[];
 };
 
+/** The content attributes each native host accepts and passes through to its element. An iframe passes nothing. */
+const nativeAttributes: Record<AdapterHost, AttributeConfigs> = {
+  video: videoContentAttributes,
+  audio: audioContentAttributes,
+  iframe: {},
+};
+
 /**
- * Build a custom element around an adapter. The element renders the adapter's `host` element in its shadow root,
- * attaches the adapter to it, and forwards the adapter's properties, events, and content attributes.
+ * Build a custom element around an adapter.
+ *
+ * The element renders the adapter's `host` in its shadow root, attaches the adapter to it, and is the adapter to its
+ * callers: every method, accessor, and event comes through. Its content attributes are the host's native ones plus one
+ * for each primitive in the adapter's `defaultProps`; an attribute the adapter can set writes the adapter, and any
+ * other native attribute is copied onto the inner element. `<track>` and `<source>` children reach a native host too.
+ *
+ * @param Adapter - Adapter class with static `host` and `defaultProps`.
+ * @param options - The shadow template, for elements that render more than the bare host.
  */
-export function CustomMediaElement<T extends PlaybackAdapterConstructor>(Adapter: T): CustomMediaConstructor<T> {
+export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
+  Adapter: T,
+  options: CustomMediaElementOptions = {}
+): CustomMediaConstructor<T> {
   const tag = Adapter.host;
-  // Embed hosts (iframe) drive an external player rather than a native media
-  // element, so attribute changes are not mirrored onto the iframe target and
-  // there is no `<track>` / `<source>` syncing.
-  const syncTargetAttributes = tag !== 'iframe';
-  const mediaHostAttrToProp = new Map<string, string>();
-  let isDefined = false;
+  const native = nativeAttributes[tag];
+  const passthrough = tag !== 'iframe';
+  const nativeNames = new Set(Object.entries(native).map(([prop, config]) => attributeName(prop, config)));
+  const routes = buildRoutes({ ...native, ...derivedAttributes(Adapter.defaultProps) }, Adapter);
 
   class CustomMedia extends (globalThis.HTMLElement ?? class {}) {
-    static template = tag === 'video' ? videoTemplate : commonTemplate(tag);
+    static template = options.template ?? defaultTemplate(tag);
     static shadowRootOptions: ShadowRootInit = { mode: 'open' };
-    static properties = {
-      autoPictureInPicture: { type: Boolean },
-      autoplay: { type: Boolean },
-      controls: { type: Boolean },
-      controlsList: { type: String },
-      crossOrigin: { type: String, empty: null },
-      defaultMuted: { type: Boolean, attribute: 'muted' },
-      disablePictureInPicture: { type: Boolean },
-      disableRemotePlayback: { type: Boolean },
-      loading: { type: String },
-      loop: { type: Boolean },
-      playsInline: { type: Boolean },
-      poster: { type: String, empty: '' },
-      preload: { type: String, empty: null },
-      src: { type: String, empty: '' },
-      streamType: { type: String, attribute: 'stream-type', empty: 'unknown' },
-    };
 
-    static get observedAttributes() {
-      // `this` resolves to the subclass, which may override `properties`.
-      CustomMedia.#define(this);
-      return [
-        // Intentionally use `this` so subclasses can override the constructor.
-        ...getAttrsFromProps(this.properties),
-      ];
+    static get observedAttributes(): string[] {
+      return [...routes.observed];
     }
 
-    static #define(ctor: typeof CustomMedia) {
-      if (isDefined) return;
-
-      isDefined = true;
-
-      const properties = ctor.properties as PropertyConfigs;
-
-      for (let proto = Adapter.prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
-        for (const prop of Object.getOwnPropertyNames(proto)) {
-          if (prop in CustomMedia.prototype || excludedProperties.includes(prop)) continue;
-
-          // An alias keeps reflecting its attribute through the `properties`
-          // loop below rather than reaching the adapter.
-          if (isAttributeAlias(prop, properties, Adapter.prototype)) continue;
-
-          const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
-          if (!descriptor) continue;
-
-          const config: PropertyDescriptor = {
-            enumerable: true,
-            configurable: true,
-          };
-
-          if (typeof descriptor.value === 'function') {
-            config.value = function (this: CustomMedia, ...args: any[]) {
-              return this.#mediaHost[prop](...args);
-            };
-          } else if (descriptor.get) {
-            config.get = function (this: CustomMedia) {
-              return this.#mediaHost[prop];
-            };
-
-            if (descriptor.set) {
-              const attr = attributeName(prop, properties);
-
-              if (ctor.observedAttributes.includes(attr)) {
-                mediaHostAttrToProp.set(attr, prop);
-
-                config.set = function (this: CustomMedia, val: any) {
-                  if (val === true || val === false || val == null) {
-                    this.toggleAttribute(attr, Boolean(val));
-                  } else {
-                    this.setAttribute(attr, String(val));
-                  }
-                };
-              } else {
-                config.set = function (this: CustomMedia, val: any) {
-                  this.#mediaHost[prop] = val;
-                };
-              }
-            }
-          }
-
-          Object.defineProperty(CustomMedia.prototype, prop, config);
-        }
-      }
-
-      for (const [prop, { type, attribute }] of Object.entries(properties)) {
-        if (prop in CustomMedia.prototype) continue;
-
-        const attr = attribute ?? prop.toLowerCase();
-
-        Object.defineProperty(CustomMedia.prototype, prop, {
-          get: function (this: CustomMedia) {
-            return type === Boolean ? this.hasAttribute(attr) : this.getAttribute(attr);
-          },
-          set: function (this: CustomMedia, val: any) {
-            if (type === Boolean) {
-              this.toggleAttribute(attr, Boolean(val));
-            } else {
-              this.setAttribute(attr, val);
-            }
-          },
-          enumerable: true,
-          configurable: true,
-        });
-      }
-    }
-
-    #mediaHost: PlaybackAdapter;
-    #bridgedEventTypes = new Set<string>();
-    #childMap = new Map<HTMLTrackElement | HTMLSourceElement, HTMLTrackElement | HTMLSourceElement>();
-    #childObserver?: MutationObserver;
+    #adapter = new Adapter();
+    #attachment = new AdapterAttachment(this, this.#adapter, () => this.target);
+    #children = passthrough ? new MediaChildren(this, () => this.target) : null;
 
     constructor() {
       super();
 
-      if (!this.shadowRoot) {
-        const ctor = this.constructor as typeof CustomMedia;
-
-        this.attachShadow(ctor.shadowRootOptions);
-
-        const allowedKeys = getAttrsFromProps(ctor.properties);
-        const disallowedKeys = [...mediaHostAttrToProp.keys()];
-        const pickedAttrs = pick(namedNodeMapToObject(this.attributes), allowedKeys);
-        // Embed templates (iframe) need adapter-bound attrs (e.g. `src`) to build the initial URL.
-        const attrs: Record<string, string> = syncTargetAttributes ? omit(pickedAttrs, disallowedKeys) : pickedAttrs;
+      const ctor = this.constructor as typeof CustomMedia;
 
-        if (!attrs.part) attrs.part = tag;
-
-        this.shadowRoot!.innerHTML = ctor.template(attrs);
-      }
-
-      this.#mediaHost = new Adapter();
-      this.#attachToTarget();
+      renderHost(
+        this,
+        ctor.template,
+        { part: tag, ...initialAttributes(this, routes, { passthrough }) },
+        ctor.shadowRootOptions
+      );
 
-      this.#childObserver = new MutationObserver(this.#syncMediaChildAttribute.bind(this));
+      this.#attachment.attach();
       this.shadowRoot!.addEventListener('slotchange', () => {
-        this.#attachToTarget();
-        this.#syncMediaChildren();
+        this.#attachment.attach();
+        this.#children?.sync();
       });
 
-      this.#syncMediaChildren();
-    }
-
-    #attachToTarget(): void {
-      const target = this.target;
-      if (target === this.#mediaHost.target) return;
-
-      if (this.#mediaHost.target) this.#mediaHost.detach();
-
-      this.#mediaHost.attach(target);
+      this.#children?.sync();
     }
 
     get adapter(): PlaybackAdapter {
-      return this.#mediaHost;
+      return this.#adapter;
     }
 
+    /**
+     * The element the adapter plays through: a child slotted as `media`, else a child of the host's tag, else the one
+     * rendered in the shadow root. Only direct children count, so a `<video>` nested in slotted content is not
+     * adopted.
+     */
     get target(): HTMLElement | null {
       return (
-        this.querySelector(':scope > [slot=media]') ??
-        this.querySelector(tag) ??
+        this.querySelector(`:scope > [slot=media]`) ??
+        this.querySelector(`:scope > ${tag}`) ??
         this.shadowRoot?.querySelector(tag) ??
         null
       );
     }
 
     connectedCallback() {
-      if (tag !== 'iframe') return;
+      if (passthrough) return;
 
-      // Add data attribute for styling and avoiding cross-origin issues. e.g. backdrop-filter
-      if (!this.hasAttribute('data-cross-origin-frame')) {
-        this.setAttribute('data-cross-origin-frame', '');
-      }
+      // Styling reads this to skip effects such as `backdrop-filter` that break over a cross-origin frame.
+      if (!this.hasAttribute('data-cross-origin-frame')) this.setAttribute('data-cross-origin-frame', '');
     }
 
     disconnectedCallback() {
-      if (this.hasAttribute('keep-alive')) return;
-
-      // Defer so a synchronous reparent (remove + insert) doesn't tear down
-      // the adapter and its registered components.
-      queueMicrotask(() => {
-        if (!this.isConnected) this.#mediaHost.destroy();
-      });
+      this.#attachment.release();
     }
 
     addEventListener(
@@ -352,125 +140,31 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(Adapter
       options?: boolean | AddEventListenerOptions
     ) {
       super.addEventListener(type, listener as EventListener, options);
-
-      if (!this.#bridgedEventTypes.has(type)) {
-        this.#bridgedEventTypes.add(type);
-        this.#mediaHost.addEventListener(type, this.#bridgeEvent);
-      }
-    }
-
-    removeEventListener(
-      type: string,
-      listener: EventListenerOrEventListenerObject | ((event: never) => void) | null,
-      options?: boolean | EventListenerOptions
-    ): void {
-      super.removeEventListener(type, listener as EventListener, options);
+      bridgeEvent(this, type);
     }
 
-    #bridgeEvent = (event: Event) => {
-      if (!event.composed) {
-        this.dispatchEvent(new (event.constructor as typeof Event)(event.type, event));
-      }
-    };
-
-    attributeChangedCallback(attrName: string, oldValue: string | null, newValue: string | null): void {
-      const prop = mediaHostAttrToProp.get(attrName);
-
-      if (prop) {
-        if (oldValue !== newValue) {
-          const propConfig = (this.constructor as CustomMediaConstructor<T>).properties[prop];
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
+      const owner = routes.ownerOf.get(name);
 
-          this.#mediaHost[prop] = propertyValueFor(newValue, this.#mediaHost[prop], propConfig);
-        }
+      if (owner) {
+        if (oldValue !== newValue) this.#adapter[owner] = coerceAttribute(newValue, routes.configOf.get(name)!);
 
         return;
       }
 
-      if (
-        !CustomMedia.observedAttributes.includes(attrName) &&
-        (this.constructor as typeof CustomMedia).observedAttributes.includes(attrName)
-      ) {
-        return;
-      }
-
-      if (!syncTargetAttributes) return;
+      // Anything else the host understands is the inner element's business; a subclass's own attributes are not.
+      if (!passthrough || !nativeNames.has(name)) return;
 
       if (newValue === null) {
-        this.target?.removeAttribute(attrName);
-      } else if (this.target?.getAttribute(attrName) !== newValue) {
-        this.target?.setAttribute(attrName, newValue);
-      }
-    }
-
-    #syncMediaChildren(): void {
-      if (tag === 'iframe') return;
-
-      const defaultSlot = this.shadowRoot?.querySelector('slot:not([name])') as HTMLSlotElement;
-      const mediaChildren = new Set(
-        defaultSlot
-          ?.assignedElements({ flatten: true })
-          .filter((el) => el.localName === 'track' || el.localName === 'source') as (
-          | HTMLTrackElement
-          | HTMLSourceElement
-        )[]
-      );
-
-      for (const [el, clone] of this.#childMap) {
-        if (!mediaChildren.has(el)) {
-          clone.remove();
-          this.#childMap.delete(el);
-        }
-      }
-
-      for (const el of mediaChildren) {
-        let clone = this.#childMap.get(el);
-
-        if (!clone) {
-          clone = el.cloneNode() as HTMLTrackElement | HTMLSourceElement;
-          this.#childMap.set(el, clone);
-          this.#childObserver?.observe(el, { attributes: true });
-        }
-
-        this.target?.append(clone);
-        this.#enableDefaultTrack(clone as HTMLTrackElement);
-      }
-    }
-
-    #syncMediaChildAttribute(mutations: MutationRecord[]): void {
-      for (const mutation of mutations) {
-        if (mutation.type === 'attributes') {
-          const { target, attributeName } = mutation;
-          const clone = this.#childMap.get(target as HTMLTrackElement | HTMLSourceElement);
-
-          if (clone && attributeName) {
-            clone.setAttribute(
-              attributeName,
-              (target as HTMLTrackElement | HTMLSourceElement).getAttribute(attributeName) ?? ''
-            );
-            this.#enableDefaultTrack(clone as HTMLTrackElement);
-          }
-        }
-      }
-    }
-
-    #enableDefaultTrack(trackEl: HTMLTrackElement): void {
-      // Browsers don't honor the `default` attribute if a track is added via JS.
-      // Enable default tracks for chapters or metadata.
-      if (
-        trackEl &&
-        trackEl.localName === 'track' &&
-        trackEl.default &&
-        (trackEl.kind === 'chapters' || trackEl.kind === 'metadata') &&
-        trackEl.track.mode === 'disabled'
-      ) {
-        trackEl.track.mode = 'hidden';
+        this.target?.removeAttribute(name);
+      } else if (this.target?.getAttribute(name) !== newValue) {
+        this.target?.setAttribute(name, newValue);
       }
     }
   }
 
-  return CustomMedia as any;
-}
+  reflectAttributes(CustomMedia.prototype, routes);
+  forwardAdapter(CustomMedia.prototype, Adapter, routes);
 
-function getAttrsFromProps(props: PropertyConfigs): string[] {
-  return Object.keys(props).map((prop) => attributeName(prop, props));
+  return CustomMedia as any;
 }
diff --git a/packages/media/src/dom/custom-media-element/element-surface.ts b/packages/media/src/dom/custom-media-element/element-surface.ts
new file mode 100644
index 0000000000..ebb36b150c
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/element-surface.ts
@@ -0,0 +1,103 @@
+import { isFunction } from '@videojs/utils/predicate';
+import type { Constructor } from '@videojs/utils/types';
+
+import type { AttributeRoutes } from './attributes';
+import type { PlaybackAdapter } from './custom-media-element';
+
+/** An element that owns an adapter. */
+export interface AdapterElement extends HTMLElement {
+  readonly adapter: PlaybackAdapter;
+}
+
+const excludedProperties = new Set(['constructor', 'attach', 'detach', 'destroy']);
+
+/**
+ * Put the adapter's methods and accessors on the element prototype, so the element is the adapter to its callers.
+ *
+ * A setter whose property reflects through an attribute writes the attribute instead, and the attribute change reaches
+ * the adapter; the property then holds one value whichever way it was set. Properties the routes mark as reflected are
+ * left to `reflectAttributes`.
+ */
+export function forwardAdapter(prototype: object, Adapter: Constructor<object>, routes: AttributeRoutes): void {
+  for (let proto = Adapter.prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const prop of Object.getOwnPropertyNames(proto)) {
+      if (prop in prototype || excludedProperties.has(prop) || routes.reflected.has(prop)) continue;
+
+      const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
+      if (!descriptor) continue;
+
+      const config: PropertyDescriptor = { enumerable: true, configurable: true };
+
+      if (isFunction(descriptor.value)) {
+        config.value = function (this: AdapterElement, ...args: unknown[]) {
+          return this.adapter[prop](...args);
+        };
+      } else if (descriptor.get) {
+        const attribute = routes.attributeOf.get(prop);
+
+        config.get = function (this: AdapterElement) {
+          return this.adapter[prop];
+        };
+
+        if (descriptor.set) {
+          config.set = function (this: AdapterElement, value: unknown) {
+            if (!attribute) {
+              this.adapter[prop] = value;
+            } else if (value === true || value === false || value == null) {
+              this.toggleAttribute(attribute, Boolean(value));
+            } else {
+              this.setAttribute(attribute, String(value));
+            }
+          };
+        }
+      }
+
+      Object.defineProperty(prototype, prop, config);
+    }
+  }
+}
+
+/** Give the element an accessor for each property that only reflects its attribute. */
+export function reflectAttributes(prototype: object, routes: AttributeRoutes): void {
+  for (const [prop, { attribute, config }] of routes.reflected) {
+    if (Object.hasOwn(prototype, prop)) continue;
+
+    Object.defineProperty(prototype, prop, {
+      get(this: HTMLElement) {
+        return config.type === Boolean ? this.hasAttribute(attribute) : this.getAttribute(attribute);
+      },
+      set(this: HTMLElement, value: unknown) {
+        if (config.type === Boolean) {
+          this.toggleAttribute(attribute, Boolean(value));
+        } else {
+          this.setAttribute(attribute, String(value));
+        }
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+}
+
+const bridgedTypes = new WeakMap<AdapterElement, Set<string>>();
+
+/**
+ * Re-dispatch the adapter's events of one type on the element. Call it from `addEventListener`: the adapter is only
+ * subscribed the first time someone listens for a type, and composed events are left alone since they already reach the
+ * element through the shadow boundary.
+ */
+export function bridgeEvent(element: AdapterElement, type: string): void {
+  let types = bridgedTypes.get(element);
+
+  if (!types) {
+    types = new Set();
+    bridgedTypes.set(element, types);
+  }
+
+  if (types.has(type)) return;
+
+  types.add(type);
+  element.adapter.addEventListener(type, (event: Event) => {
+    if (!event.composed) element.dispatchEvent(new (event.constructor as typeof Event)(event.type, event));
+  });
+}
diff --git a/packages/media/src/dom/custom-media-element/index.ts b/packages/media/src/dom/custom-media-element/index.ts
index df08577f10..03cc80c24c 100644
--- a/packages/media/src/dom/custom-media-element/index.ts
+++ b/packages/media/src/dom/custom-media-element/index.ts
@@ -1 +1,7 @@
+export * from './attach-adapter';
+export * from './attributes';
 export * from './custom-media-element';
+export * from './element-surface';
+export * from './media-children';
+export * from './render-host';
+export * from './templates';
diff --git a/packages/media/src/dom/custom-media-element/media-children.ts b/packages/media/src/dom/custom-media-element/media-children.ts
new file mode 100644
index 0000000000..c624c6971c
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/media-children.ts
@@ -0,0 +1,80 @@
+type MediaChild = HTMLTrackElement | HTMLSourceElement;
+
+/**
+ * Mirrors an element's light-DOM `<track>` and `<source>` children into the media element it renders, so markup written
+ * against the custom element reaches the native element that plays it.
+ *
+ * Each child is cloned once and its clone follows the original's attribute changes; a child that leaves the default
+ * slot takes its clone with it. Default `chapters` and `metadata` tracks are enabled by hand, because browsers ignore
+ * the `default` attribute on a track added from script.
+ */
+export class MediaChildren {
+  #host: HTMLElement;
+  #target: () => Element | null;
+  #clones = new Map<MediaChild, MediaChild>();
+  #observer = new MutationObserver((mutations) => this.#syncAttributes(mutations));
+
+  /**
+   * @param host - The custom element whose default slot holds the children.
+   * @param target - Resolves the media element the clones are appended to.
+   */
+  constructor(host: HTMLElement, target: () => Element | null) {
+    this.#host = host;
+    this.#target = target;
+  }
+
+  /** Bring the clones in step with the default slot's assigned children. Call it after construction and on `slotchange`. */
+  sync(): void {
+    const slot = this.#host.shadowRoot?.querySelector<HTMLSlotElement>('slot:not([name])');
+    const children = new Set(slot?.assignedElements({ flatten: true }).filter(isMediaChild) ?? []);
+
+    for (const [child, clone] of this.#clones) {
+      if (children.has(child)) continue;
+
+      clone.remove();
+      this.#clones.delete(child);
+    }
+
+    const target = this.#target();
+
+    for (const child of children) {
+      let clone = this.#clones.get(child);
+
+      if (!clone) {
+        clone = child.cloneNode() as MediaChild;
+        this.#clones.set(child, clone);
+        this.#observer.observe(child, { attributes: true });
+      }
+
+      target?.append(clone);
+      enableDefaultTrack(clone);
+    }
+  }
+
+  #syncAttributes(mutations: MutationRecord[]): void {
+    for (const { type, target, attributeName } of mutations) {
+      if (type !== 'attributes' || !attributeName) continue;
+
+      const child = target as MediaChild;
+      const clone = this.#clones.get(child);
+      if (!clone) continue;
+
+      clone.setAttribute(attributeName, child.getAttribute(attributeName) ?? '');
+      enableDefaultTrack(clone);
+    }
+  }
+}
+
+function isMediaChild(element: Element): element is MediaChild {
+  return element.localName === 'track' || element.localName === 'source';
+}
+
+function enableDefaultTrack(element: MediaChild): void {
+  if (element.localName !== 'track') return;
+
+  const track = element as HTMLTrackElement;
+
+  if (track.default && (track.kind === 'chapters' || track.kind === 'metadata') && track.track?.mode === 'disabled') {
+    track.track.mode = 'hidden';
+  }
+}
diff --git a/packages/media/src/dom/custom-media-element/render-host.ts b/packages/media/src/dom/custom-media-element/render-host.ts
new file mode 100644
index 0000000000..d8de2a5183
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/render-host.ts
@@ -0,0 +1,41 @@
+import { namedNodeMapToObject } from '@videojs/utils/dom';
+import { omit, pick } from '@videojs/utils/object';
+
+import type { AttributeRoutes } from './attributes';
+import type { MediaTemplate } from './templates';
+
+/**
+ * Render the template into the element's shadow root. An existing root, such as a declarative one, is left as it is.
+ *
+ * @param element - The custom element to render into.
+ * @param template - Produces the shadow HTML from the attributes it may render.
+ * @param attrs - The attributes handed to the template, typically from `initialAttributes`.
+ */
+export function renderHost(
+  element: HTMLElement,
+  template: MediaTemplate,
+  attrs: Record<string, string>,
+  init: ShadowRootInit = { mode: 'open' }
+): ShadowRoot {
+  if (element.shadowRoot) return element.shadowRoot;
+
+  const root = element.attachShadow(init);
+
+  root.innerHTML = template(attrs);
+
+  return root;
+}
+
+/**
+ * The attributes present on the element that its template may render: the observed ones, minus those an adapter
+ * property owns when they would otherwise land on a native element and start a load of their own.
+ */
+export function initialAttributes(
+  element: HTMLElement,
+  routes: AttributeRoutes,
+  { passthrough }: { passthrough: boolean }
+): Record<string, string> {
+  const attrs = pick(namedNodeMapToObject(element.attributes), routes.observed);
+
+  return passthrough ? omit(attrs, [...routes.ownerOf.keys()]) : attrs;
+}
diff --git a/packages/media/src/dom/custom-media-element/templates.ts b/packages/media/src/dom/custom-media-element/templates.ts
new file mode 100644
index 0000000000..9c6b9780fe
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/templates.ts
@@ -0,0 +1,83 @@
+import { serializeAttributes } from '@videojs/utils/dom';
+
+import type { AdapterHost } from '../html-media-adapter';
+
+/** CSS custom property names for video elements. */
+export const VideoCSSVars = {
+  /** Border radius of the video element. */
+  borderRadius: '--media-video-border-radius',
+  /** Object fit for the video. */
+  objectFit: '--media-object-fit',
+  /** Object position for the video. */
+  objectPosition: '--media-object-position',
+  /** Duration of the caption track transition. */
+  captionTrackDuration: '--media-caption-track-duration',
+  /** Delay before the caption track transition. */
+  captionTrackDelay: '--media-caption-track-delay',
+  /** Vertical offset of the caption track. */
+  captionTrackY: '--media-caption-track-y',
+} as const;
+
+/** CSS custom property names for audio elements. */
+export const AudioCSSVars = {} as const;
+
+/** Renders an element's shadow template from its initial attributes. */
+export type MediaTemplate = (attrs: Record<string, string>) => string;
+
+function videoTemplate(attrs: Record<string, string>): string {
+  return /*html*/ `
+    <style>
+      :host {
+        display: contents;
+      }
+
+      video {
+        display: block;
+        width: 100%;
+        height: 100%;
+        border-radius: var(${VideoCSSVars.borderRadius});
+        object-fit: var(${VideoCSSVars.objectFit}, contain);
+        object-position: var(${VideoCSSVars.objectPosition}, center);
+      }
+
+      video::-webkit-media-text-track-container {
+        transition: translate var(${VideoCSSVars.captionTrackDuration}, 0) ease-out;
+        transition-delay: var(${VideoCSSVars.captionTrackDelay}, 0);
+        translate: 0 var(${VideoCSSVars.captionTrackY}, 0);
+        scale: 0.98;
+        z-index: 1;
+        font-family: inherit;
+      }
+    </style>
+    <slot name="media">
+      <video${serializeAttributes(attrs)}></video>
+    </slot>
+    <slot></slot>
+  `;
+}
+
+function commonTemplate(tag: string): MediaTemplate {
+  return (attrs) => /*html*/ `
+    <style>
+      :host {
+        display: inline-flex;
+        line-height: 0;
+        flex-direction: column;
+        justify-content: end;
+      }
+
+      ${tag} {
+        width: 100%;
+      }
+    </style>
+    <slot name="media">
+      <${tag}${serializeAttributes(attrs)}></${tag}>
+    </slot>
+    <slot></slot>
+  `;
+}
+
+/** The bare template for a host: a `<slot name="media">` wrapping the host element, and a default slot after it. */
+export function defaultTemplate(host: AdapterHost): MediaTemplate {
+  return host === 'video' ? videoTemplate : commonTemplate(host);
+}
diff --git a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
index 92e588a2da..bde833256e 100644
--- a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
+++ b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
@@ -8,7 +8,10 @@ afterEach(() => {
   document.body.innerHTML = '';
 });
 
-class TestVideoHost extends HTMLVideoAdapter {
+/** A video adapter that owns `src` and `streamType`, like an engine-backed one does. */
+class TestVideoAdapter extends HTMLVideoAdapter {
+  static readonly defaultProps = { src: '', streamType: 'unknown' };
+
   #src = '';
   #destroyed = false;
 
@@ -29,11 +32,16 @@ class TestVideoHost extends HTMLVideoAdapter {
   }
 }
 
-class TestVideoHostWithObjects extends HTMLVideoAdapter {
+/** A video adapter with its own primitive and object props, like `MuxVideoAdapter`. */
+class TestVideoAdapterWithOptions extends HTMLVideoAdapter {
+  static readonly defaultProps = { src: '', source: null, debug: false, latencyMode: 'normal', bufferSeconds: 30 };
+
   #src = '';
-  #source: Record<string, any> | null = null;
-  #metadata: Record<string, any> | undefined;
+  #source: Record<string, unknown> | null = null;
+  #metadata: Record<string, unknown> | undefined;
   #debug = false;
+  #latencyMode = 'normal';
+  #bufferSeconds = 30;
 
   get src() {
     return this.#src;
@@ -47,15 +55,16 @@ class TestVideoHostWithObjects extends HTMLVideoAdapter {
     return this.#source;
   }
 
-  set source(value: Record<string, any> | null) {
+  set source(value: Record<string, unknown> | null) {
     this.#source = value;
   }
 
+  /** Property-only: not in `defaultProps`. */
   get metadata() {
     return this.#metadata;
   }
 
-  set metadata(value: Record<string, any> | undefined) {
+  set metadata(value: Record<string, unknown> | undefined) {
     this.#metadata = value;
   }
 
@@ -67,177 +76,150 @@ class TestVideoHostWithObjects extends HTMLVideoAdapter {
     this.#debug = value;
   }
 
-  destroy() {}
-}
-
-class TestAudioHost extends HTMLAudioAdapter {
-  destroy() {}
-}
-
-class TestIframeHost extends EventTarget {
-  static readonly host = 'iframe' as const;
-
-  target: EventTarget | null = null;
-  attach(target: EventTarget | null) {
-    this.target = target;
-  }
-  detach() {
-    this.target = null;
+  get latencyMode() {
+    return this.#latencyMode;
   }
-  destroy() {}
-}
-
-let tagCounter = 0;
-
-function defineVideoElement() {
-  const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement(TestVideoHost);
-
-  customElements.define(tag, Ctor);
-  return { Ctor, tag };
-}
 
-function defineVideoElementWithObjects() {
-  const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement(TestVideoHostWithObjects);
+  set latencyMode(value: string) {
+    this.#latencyMode = value;
+  }
 
-  customElements.define(tag, Ctor);
-  return { Ctor, tag };
-}
+  get bufferSeconds() {
+    return this.#bufferSeconds;
+  }
 
-function defineAudioElement() {
-  const tag = `test-audio-${++tagCounter}`;
-  const Ctor = CustomMediaElement(TestAudioHost);
+  set bufferSeconds(value: number) {
+    this.#bufferSeconds = value;
+  }
 
-  customElements.define(tag, Ctor);
-  return { Ctor, tag };
+  destroy() {}
 }
 
-function defineIframeElement() {
-  const tag = `test-iframe-${++tagCounter}`;
-  const Ctor = CustomMediaElement(TestIframeHost as never);
+class TestAudioAdapter extends HTMLAudioAdapter {
+  static readonly defaultProps = { src: '' };
 
-  customElements.define(tag, Ctor);
-  return { Ctor, tag };
+  destroy() {}
 }
 
-function create(def: { Ctor: new () => any; tag: string }) {
-  const el = new def.Ctor();
+/** An embed adapter: no native element, so only its `defaultProps` become attributes. */
+class TestEmbedAdapter extends EventTarget {
+  static readonly host = 'iframe' as const;
+  static readonly defaultProps = { src: '', autoplay: false, defaultMuted: false, muted: false, source: null };
 
-  document.body.appendChild(el);
-  return el;
-}
+  target: EventTarget | null = null;
 
-class TrackingVideoHost extends HTMLVideoAdapter {
-  #calls: string[] = [];
   #src = '';
-  #volume = 1;
+  #autoplay = false;
   #muted = false;
-  #currentTime = 0;
-  #playbackRate = 1;
-  #preload: '' | 'none' | 'metadata' | 'auto' | null = 'metadata';
-
-  get calls() {
-    return this.#calls;
-  }
 
   get src() {
     return this.#src;
   }
 
   set src(value: string) {
-    this.calls.push(`set:src:${value}`);
     this.#src = value;
   }
 
-  override get volume() {
-    return this.#volume;
+  get autoplay() {
+    return this.#autoplay;
   }
 
-  override set volume(value: number) {
-    this.calls.push(`set:volume:${value}`);
-    this.#volume = value;
+  set autoplay(value: boolean) {
+    this.#autoplay = value;
   }
 
-  override get muted() {
+  get muted() {
     return this.#muted;
   }
 
-  override set muted(value: boolean) {
-    this.calls.push(`set:muted:${value}`);
+  set muted(value: boolean) {
     this.#muted = value;
   }
 
-  override get currentTime() {
-    return this.#currentTime;
-  }
-
-  override set currentTime(value: number) {
-    this.calls.push(`set:currentTime:${value}`);
-    this.#currentTime = value;
+  attach(target: EventTarget | null) {
+    this.target = target;
   }
 
-  override get playbackRate() {
-    return this.#playbackRate;
+  detach() {
+    this.target = null;
   }
 
-  override set playbackRate(value: number) {
-    this.calls.push(`set:playbackRate:${value}`);
-    this.#playbackRate = value;
-  }
+  destroy() {}
+}
 
-  override get preload() {
-    return this.#preload ?? 'metadata';
-  }
+let tagCounter = 0;
 
-  override set preload(value: '' | 'none' | 'metadata' | 'auto') {
-    const preload = value as '' | 'none' | 'metadata' | 'auto' | null;
+function define<T extends CustomElementConstructor>(prefix: string, Ctor: T) {
+  const tag = `${prefix}-${++tagCounter}`;
 
-    this.calls.push(`set:preload:${preload}`);
-    this.#preload = preload;
-  }
+  customElements.define(tag, Ctor);
 
-  destroy() {}
+  return { Ctor, tag };
 }
 
-function defineTrackingVideoElement() {
-  const tag = `test-video-${++tagCounter}`;
-  const Ctor = CustomMediaElement(TrackingVideoHost);
+const defineVideoElement = () => define('test-video', CustomMediaElement(TestVideoAdapter));
+const defineVideoElementWithOptions = () => define('test-video', CustomMediaElement(TestVideoAdapterWithOptions));
+const defineAudioElement = () => define('test-audio', CustomMediaElement(TestAudioAdapter));
+const defineEmbedElement = () => define('test-embed', CustomMediaElement(TestEmbedAdapter));
 
-  customElements.define(tag, Ctor);
-  return { Ctor, tag };
+function create(def: { Ctor: new () => any; tag: string }) {
+  const el = new def.Ctor();
+
+  document.body.appendChild(el);
+
+  return el;
 }
 
 describe('CustomMediaElement', () => {
-  describe('shadow DOM setup', () => {
-    it('creates a shadow root with a video element for video tag', () => {
+  describe('shadow DOM', () => {
+    it('renders the host element for the adapter', () => {
+      const video = create(defineVideoElement());
+      const audio = create(defineAudioElement());
+      const embed = create(defineEmbedElement());
+
+      expect(video.shadowRoot!.querySelector('video')).not.toBeNull();
+      expect(audio.shadowRoot!.querySelector('audio')).not.toBeNull();
+      expect(embed.shadowRoot!.querySelector('iframe')).not.toBeNull();
+    });
+
+    it('marks the inner element with a part named after the host', () => {
       const el = create(defineVideoElement());
 
-      expect(el.shadowRoot).toBeTruthy();
-      expect(el.shadowRoot!.querySelector('video')).toBeTruthy();
+      expect(el.shadowRoot!.querySelector('video')!.getAttribute('part')).toBe('video');
     });
 
-    it('creates a shadow root with an audio element for audio tag', () => {
-      const el = create(defineAudioElement());
+    it('renders a custom template', () => {
+      const Ctor = CustomMediaElement(TestEmbedAdapter, {
+        template: (attrs) => `<iframe title="Embedded player" data-src="${attrs.src ?? ''}"></iframe>`,
+      });
+      const { tag } = define('test-embed', Ctor);
+      const container = document.createElement('div');
+
+      document.body.append(container);
+      container.innerHTML = `<${tag} src="https://example.com/embed"></${tag}>`;
 
-      expect(el.shadowRoot).toBeTruthy();
-      expect(el.shadowRoot!.querySelector('audio')).toBeTruthy();
+      const iframe = container.querySelector(tag)!.shadowRoot!.querySelector('iframe')!;
+
+      expect(iframe.getAttribute('title')).toBe('Embedded player');
+      expect(iframe.getAttribute('data-src')).toBe('https://example.com/embed');
     });
 
-    it('sets part attribute on the inner element', () => {
-      const el = create(defineVideoElement());
-      const video = el.shadowRoot!.querySelector('video')!;
+    it('lets a subclass replace the template through the static', () => {
+      class Custom extends CustomMediaElement(TestVideoAdapter) {
+        static template = () => '<video part="custom"></video>';
+      }
+
+      const el = create(define('test-video', Custom));
 
-      expect(video.getAttribute('part')).toBe('video');
+      expect(el.shadowRoot!.querySelector('video')!.getAttribute('part')).toBe('custom');
     });
   });
 
   describe('target', () => {
     it('returns the shadow DOM media element by default', () => {
       const el = create(defineVideoElement());
-      const video = el.shadowRoot!.querySelector('video');
 
-      expect(el.target).toBe(video);
+      expect(el.target).toBe(el.shadowRoot!.querySelector('video'));
     });
 
     it('prefers a slotted element with slot=media', () => {
@@ -249,21 +231,29 @@ describe('CustomMediaElement', () => {
       expect(el.target).toBe(slotted);
     });
 
-    it('re-attaches media adapter when slotted media element appears after construction', () => {
+    it('adopts a direct child of the host tag but not one nested in slotted content', () => {
       const el = create(defineVideoElement());
-      const shadowVideo = el.shadowRoot!.querySelector('video')!;
+      const wrapper = document.createElement('div');
+
+      wrapper.append(document.createElement('video'));
+      el.append(wrapper);
+      expect(el.target).toBe(el.shadowRoot!.querySelector('video'));
 
+      const child = document.createElement('video');
+
+      el.append(child);
+      expect(el.target).toBe(child);
+    });
+
+    it('re-attaches the adapter when a slotted media element appears after construction', () => {
+      const el = create(defineVideoElement());
+      const shadowVideo = el.shadowRoot!.querySelector('video')!;
       const slottedVideo = document.createElement('video');
 
       slottedVideo.slot = 'media';
       el.appendChild(slottedVideo);
+      el.shadowRoot!.querySelector('slot[name="media"]')!.dispatchEvent(new Event('slotchange', { bubbles: true }));
 
-      // Simulate slotchange with bubbles (matches real browser behavior)
-      const mediaSlot = el.shadowRoot!.querySelector('slot[name="media"]')!;
-
-      mediaSlot.dispatchEvent(new Event('slotchange', { bubbles: true }));
-
-      // After re-attach, property writes should go to the slotted element
       el.volume = 0.5;
       expect(slottedVideo.volume).toBe(0.5);
       expect(shadowVideo.volume).toBe(1);
@@ -273,446 +263,282 @@ describe('CustomMediaElement', () => {
       const el = create(defineVideoElement());
       const shadowVideo = el.shadowRoot!.querySelector('video')!;
 
-      // Dispatch slotchange without adding a slotted element
-      const mediaSlot = el.shadowRoot!.querySelector('slot[name="media"]')!;
-
-      mediaSlot.dispatchEvent(new Event('slotchange', { bubbles: true }));
+      el.shadowRoot!.querySelector('slot[name="media"]')!.dispatchEvent(new Event('slotchange', { bubbles: true }));
 
       el.volume = 0.5;
       expect(shadowVideo.volume).toBe(0.5);
     });
   });
 
-  describe('observedAttributes includes standard media attributes', () => {
-    it('includes standard attributes for video elements', () => {
-      const { Ctor } = defineVideoElement();
-      const observed = Ctor.observedAttributes;
+  describe('observedAttributes', () => {
+    it('observes the native attributes of a video host plus the adapter defaults', () => {
+      const observed = defineVideoElement().Ctor.observedAttributes;
 
-      expect(observed).toContain('autoplay');
-      expect(observed).toContain('controls');
-      expect(observed).toContain('crossorigin');
-      expect(observed).toContain('loop');
-      expect(observed).toContain('muted');
-      expect(observed).toContain('playsinline');
-      expect(observed).toContain('preload');
-      expect(observed).toContain('src');
-      expect(observed).toContain('poster');
-      expect(observed).toContain('autopictureinpicture');
-      expect(observed).toContain('disablepictureinpicture');
-      expect(observed).toContain('stream-type');
-    });
+      for (const attr of ['autoplay', 'controls', 'crossorigin', 'loop', 'muted', 'preload', 'src', 'loading']) {
+        expect(observed).toContain(attr);
+      }
 
-    it('includes standard attributes for audio elements', () => {
-      const { Ctor } = defineAudioElement();
-      const observed = Ctor.observedAttributes;
+      for (const attr of ['poster', 'playsinline', 'autopictureinpicture', 'disablepictureinpicture']) {
+        expect(observed).toContain(attr);
+      }
 
-      expect(observed).toContain('autoplay');
-      expect(observed).toContain('controls');
-      expect(observed).toContain('crossorigin');
-      expect(observed).toContain('loop');
-      expect(observed).toContain('muted');
-      expect(observed).toContain('preload');
-      expect(observed).toContain('src');
       expect(observed).toContain('stream-type');
     });
-  });
 
-  describe('observedAttributes', () => {
-    it('includes PlaybackAdapter properties that overlap with standard Attributes', () => {
-      const { Ctor } = defineVideoElement();
-      const observed = Ctor.observedAttributes;
+    it('does not give an audio host video-only attributes', () => {
+      const observed = defineAudioElement().Ctor.observedAttributes;
 
+      expect(observed).toContain('controls');
       expect(observed).toContain('src');
-      expect(observed).toContain('muted');
-    });
-
-    it('excludes PlaybackAdapter properties not in standard Attributes', () => {
-      const { Ctor } = defineVideoElement();
-      const observed = Ctor.observedAttributes;
-
-      expect(observed).not.toContain('current-time');
-      expect(observed).not.toContain('volume');
-      expect(observed).not.toContain('playback-rate');
-    });
-  });
-
-  describe('stream-type reflection', () => {
-    it('sets the host streamType from the stream-type attribute', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('stream-type', 'live');
-      expect(el.streamType).toBe('live');
+      expect(observed).not.toContain('poster');
+      expect(observed).not.toContain('playsinline');
+      expect(observed).not.toContain('disablepictureinpicture');
+      expect(observed).not.toContain('stream-type');
     });
 
-    it('reflects the streamType property to the stream-type attribute', () => {
-      const el = create(defineVideoElement());
+    it('gives an embed exactly the primitive defaults of its adapter', () => {
+      const observed = defineEmbedElement().Ctor.observedAttributes;
 
-      el.streamType = 'live';
-      expect(el.getAttribute('stream-type')).toBe('live');
-      expect(el.streamType).toBe('live');
+      expect(observed.sort()).toEqual(['autoplay', 'muted', 'src']);
     });
 
-    it('does not forward stream-type to the inner media element', () => {
-      const el = create(defineVideoElement());
+    it('derives one attribute per primitive default and none for objects or playback state', () => {
+      const observed = defineVideoElementWithOptions().Ctor.observedAttributes;
 
-      el.setAttribute('stream-type', 'live');
-      expect(el.target!.hasAttribute('stream-type')).toBe(false);
+      expect(observed).toContain('debug');
+      expect(observed).toContain('latency-mode');
+      expect(observed).toContain('buffer-seconds');
+      expect(observed).not.toContain('source');
+      expect(observed).not.toContain('metadata');
+      expect(observed).not.toContain('volume');
+      expect(observed).not.toContain('current-time');
     });
   });
 
-  describe('video attribute forwarding', () => {
-    it('forwards autoplay to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('autoplay', '');
-      expect(el.target!.hasAttribute('autoplay')).toBe(true);
-    });
-
-    it('forwards controls to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('controls', '');
-      expect(el.target!.hasAttribute('controls')).toBe(true);
-    });
-
-    it('forwards crossorigin to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('crossorigin', 'anonymous');
-      expect(el.target!.getAttribute('crossorigin')).toBe('anonymous');
-    });
-
-    it('forwards loop to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('loop', '');
-      expect(el.target!.hasAttribute('loop')).toBe(true);
-    });
-
-    it('forwards playsinline to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('playsinline', '');
-      expect(el.target!.hasAttribute('playsinline')).toBe(true);
-    });
-
-    it('forwards preload to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('preload', 'none');
-      expect(el.target!.getAttribute('preload')).toBe('none');
-    });
-
-    it('forwards poster to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('poster', 'https://example.com/poster.jpg');
-      expect(el.target!.getAttribute('poster')).toBe('https://example.com/poster.jpg');
-    });
-
-    it('forwards controlslist to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('controlslist', 'nodownload');
-      expect(el.target!.getAttribute('controlslist')).toBe('nodownload');
-    });
-
-    // These two reach the target through the media adapter, which assigns the IDL
-    // property; browsers reflect that back to the attribute, but jsdom
-    // implements neither property, so only the assignment is observable here.
-    it('forwards disableremoteplayback to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('disableremoteplayback', '');
-      expect(el.adapter.disableRemotePlayback).toBe(true);
-      expect((el.target as HTMLVideoElement).disableRemotePlayback).toBe(true);
-    });
+  describe('attributes owned by the adapter', () => {
+    it('write the adapter property, coerced by the type of its default', () => {
+      const el = create(defineVideoElementWithOptions());
 
-    it('forwards disablepictureinpicture to the target video element', () => {
-      const el = create(defineVideoElement());
+      el.setAttribute('src', 'https://example.com/video.m3u8');
+      el.setAttribute('debug', '');
+      el.setAttribute('latency-mode', 'low');
+      el.setAttribute('buffer-seconds', '60');
 
-      el.setAttribute('disablepictureinpicture', '');
-      expect(el.adapter.disablePictureInPicture).toBe(true);
-      expect((el.target as HTMLVideoElement).disablePictureInPicture).toBe(true);
+      expect(el.adapter.src).toBe('https://example.com/video.m3u8');
+      expect(el.adapter.debug).toBe(true);
+      expect(el.adapter.latencyMode).toBe('low');
+      expect(el.adapter.bufferSeconds).toBe(60);
     });
 
-    it('forwards autopictureinpicture to the target video element', () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('autopictureinpicture', '');
-      expect(el.target!.hasAttribute('autopictureinpicture')).toBe(true);
-    });
+    it('reset the adapter property to its default when removed', () => {
+      const el = create(defineVideoElementWithOptions());
 
-    it('forwards loading to the target video element', () => {
-      const el = create(defineVideoElement());
+      el.setAttribute('debug', '');
+      el.setAttribute('latency-mode', 'low');
+      el.setAttribute('buffer-seconds', '60');
+      el.removeAttribute('debug');
+      el.removeAttribute('latency-mode');
+      el.removeAttribute('buffer-seconds');
 
-      el.setAttribute('loading', 'lazy');
-      expect(el.target!.getAttribute('loading')).toBe('lazy');
+      expect(el.adapter.debug).toBe(false);
+      expect(el.adapter.latencyMode).toBe('normal');
+      expect(el.adapter.bufferSeconds).toBe(30);
     });
 
-    it('forwards all non-setter VideoAttributes to the target', () => {
-      const el = create(defineVideoElement());
-      const target = el.target!;
-
-      const booleanAttrs = ['autoplay', 'controls', 'loop', 'playsinline', 'autopictureinpicture'] as const;
-
-      // Host-routed properties jsdom does not implement, so the browser's
-      // reflection back to the attribute is not observable here.
-      const propertyOnlyAttrs = {
-        disableremoteplayback: 'disableRemotePlayback',
-        disablepictureinpicture: 'disablePictureInPicture',
-      } as const;
-
-      const valueAttrs = {
-        controlslist: 'nodownload',
-        crossorigin: 'anonymous',
-        loading: 'lazy',
-        preload: 'auto',
-        poster: 'https://example.com/poster.jpg',
-      } as const;
-
-      for (const attr of [...booleanAttrs, ...Object.keys(propertyOnlyAttrs)]) {
-        el.setAttribute(attr, '');
-      }
-
-      for (const [attr, value] of Object.entries(valueAttrs)) {
-        el.setAttribute(attr, value);
-      }
-
-      for (const attr of booleanAttrs) {
-        expect(target.hasAttribute(attr), `expected ${attr} to be present on target`).toBe(true);
-      }
+    it('are written back by the property setter', () => {
+      const el = create(defineVideoElementWithOptions());
 
-      for (const [attr, prop] of Object.entries(propertyOnlyAttrs)) {
-        expect((target as any)[prop], `expected ${attr} to set ${prop} on target`).toBe(true);
-      }
+      el.debug = true;
+      el.latencyMode = 'low';
+      el.src = 'https://example.com/video.m3u8';
 
-      for (const [attr, value] of Object.entries(valueAttrs)) {
-        expect(target.getAttribute(attr), `expected ${attr}="${value}" on target`).toBe(value);
-      }
+      expect(el.hasAttribute('debug')).toBe(true);
+      expect(el.getAttribute('latency-mode')).toBe('low');
+      expect(el.getAttribute('src')).toBe('https://example.com/video.m3u8');
+      expect(el.adapter.src).toBe('https://example.com/video.m3u8');
     });
 
-    it('removes forwarded attributes when removed from host', () => {
+    it('do not reach the inner element', () => {
       const el = create(defineVideoElement());
-      const target = el.target!;
 
-      el.setAttribute('crossorigin', 'anonymous');
-      expect(target.getAttribute('crossorigin')).toBe('anonymous');
+      el.setAttribute('stream-type', 'live');
+      el.setAttribute('src', 'https://example.com/video.m3u8');
 
-      el.removeAttribute('crossorigin');
-      expect(target.hasAttribute('crossorigin')).toBe(false);
+      expect(el.streamType).toBe('live');
+      expect(el.target!.hasAttribute('stream-type')).toBe(false);
+      expect(el.target!.hasAttribute('src')).toBe(false);
     });
 
-    it('updates forwarded attribute value when changed', () => {
+    it('take the same value whether set through the attribute or the property', () => {
       const el = create(defineVideoElement());
-      const target = el.target!;
+      const set = vi.spyOn(TestVideoAdapter.prototype, 'src', 'set');
 
-      el.setAttribute('crossorigin', 'anonymous');
-      expect(target.getAttribute('crossorigin')).toBe('anonymous');
+      el.src = 'a.m3u8';
+      el.src = 'a.m3u8';
+      el.setAttribute('src', 'b.m3u8');
 
-      el.setAttribute('crossorigin', 'use-credentials');
-      expect(target.getAttribute('crossorigin')).toBe('use-credentials');
+      expect(set.mock.calls.map(([value]) => value)).toEqual(['a.m3u8', 'b.m3u8']);
+      set.mockRestore();
     });
   });
 
-  describe('non-PlaybackAdapter attribute property accessors', () => {
-    it('boolean property getter returns false when attribute is absent', () => {
-      const el = create(defineVideoElement());
-
-      expect(el.autoplay).toBe(false);
-      expect(el.controls).toBe(false);
-      expect(el.loop).toBe(false);
-    });
-
-    it('boolean property getter returns true when attribute is present', () => {
+  describe('native attributes of the host', () => {
+    it('reach the adapter when it can set the property, so an engine can intercept them', () => {
       const el = create(defineVideoElement());
 
-      el.setAttribute('autoplay', '');
+      el.setAttribute('muted', '');
+      el.setAttribute('preload', 'none');
       el.setAttribute('controls', '');
-      el.setAttribute('loop', '');
-
-      expect(el.autoplay).toBe(true);
-      expect(el.controls).toBe(true);
-      expect(el.loop).toBe(true);
-    });
-
-    it('boolean property setter adds the attribute', () => {
-      const el = create(defineVideoElement());
-
-      el.autoplay = true;
-      expect(el.hasAttribute('autoplay')).toBe(true);
-      expect(el.target!.hasAttribute('autoplay')).toBe(true);
-    });
 
-    it('boolean property setter removes the attribute when set to false', () => {
-      const el = create(defineVideoElement());
-
-      el.autoplay = true;
-      el.autoplay = false;
-      expect(el.hasAttribute('autoplay')).toBe(false);
-      expect(el.target!.hasAttribute('autoplay')).toBe(false);
+      expect(el.muted).toBe(true);
+      expect(el.target!.preload).toBe('none');
+      expect(el.target!.hasAttribute('controls')).toBe(true);
     });
 
-    it('string property getter returns the attribute value', () => {
+    it('are copied onto the inner element when the adapter has no property for them', () => {
       const el = create(defineVideoElement());
 
       el.setAttribute('controlslist', 'nodownload');
-      expect(el.controlsList).toBe('nodownload');
-    });
-
-    it('string property getter returns null when attribute is absent', () => {
-      const el = create(defineVideoElement());
-
-      expect(el.controlsList).toBeNull();
-    });
-
-    it('string property setter sets the attribute and forwards to target', () => {
-      const el = create(defineVideoElement());
+      el.setAttribute('loading', 'lazy');
+      el.setAttribute('autopictureinpicture', '');
 
-      el.controlsList = 'nodownload';
-      expect(el.getAttribute('controlslist')).toBe('nodownload');
       expect(el.target!.getAttribute('controlslist')).toBe('nodownload');
-    });
-
-    it('removing attribute resets string property getter to null', () => {
-      const el = create(defineVideoElement());
+      expect(el.target!.getAttribute('loading')).toBe('lazy');
+      expect(el.target!.hasAttribute('autopictureinpicture')).toBe(true);
 
-      el.controlsList = 'nodownload';
       el.removeAttribute('controlslist');
-      expect(el.controlsList).toBeNull();
+      expect(el.target!.hasAttribute('controlslist')).toBe(false);
     });
 
-    it('property accessors work for all non-PlaybackAdapter video attributes', () => {
+    it('reflect through a property either way', () => {
       const el = create(defineVideoElement());
 
       el.controls = true;
-      expect(el.controls).toBe(true);
-      expect(el.hasAttribute('controls')).toBe(true);
-
-      el.loop = true;
-      expect(el.loop).toBe(true);
-      expect(el.hasAttribute('loop')).toBe(true);
-
-      el.playsInline = true;
-      expect(el.playsInline).toBe(true);
-      expect(el.hasAttribute('playsinline')).toBe(true);
-
       el.controlsList = 'nodownload';
-      expect(el.controlsList).toBe('nodownload');
-      expect(el.getAttribute('controlslist')).toBe('nodownload');
-
       el.crossOrigin = 'anonymous';
-      expect(el.crossOrigin).toBe('anonymous');
-      expect(el.getAttribute('crossorigin')).toBe('anonymous');
-
-      el.loading = 'lazy';
-      expect(el.loading).toBe('lazy');
-      expect(el.getAttribute('loading')).toBe('lazy');
-    });
-
-    it('property accessors are defined on the prototype, not the constructor', () => {
-      const { Ctor } = defineVideoElement();
-      const proto = Ctor.prototype;
 
-      expect(Object.getOwnPropertyDescriptor(proto, 'autoplay')).toBeDefined();
-      expect(Object.getOwnPropertyDescriptor(proto, 'controls')).toBeDefined();
-      expect(Object.getOwnPropertyDescriptor(proto, 'loop')).toBeDefined();
-      expect(Object.getOwnPropertyDescriptor(proto, 'poster')).toBeDefined();
-      expect(Object.getOwnPropertyDescriptor(proto, 'preload')).toBeDefined();
+      expect(el.hasAttribute('controls')).toBe(true);
+      expect(el.controls).toBe(true);
+      expect(el.getAttribute('controlslist')).toBe('nodownload');
+      expect(el.controlsList).toBe('nodownload');
+      expect(el.getAttribute('crossorigin')).toBe('anonymous');
+      expect(el.target!.getAttribute('crossorigin')).toBe('anonymous');
 
-      expect(Object.getOwnPropertyDescriptor(Ctor, 'autoplay')).toBeUndefined();
-      expect(Object.getOwnPropertyDescriptor(Ctor, 'poster')).toBeUndefined();
+      el.crossOrigin = null;
+      expect(el.hasAttribute('crossorigin')).toBe(false);
+      expect(el.target!.hasAttribute('crossorigin')).toBe(false);
     });
-  });
 
-  describe('PlaybackAdapter-backed string properties', () => {
-    it('poster property reads through to the target', () => {
+    it('share the muted attribute between muted and defaultMuted', () => {
       const el = create(defineVideoElement());
 
-      expect(el.poster).toBe('');
+      el.defaultMuted = true;
+      expect(el.hasAttribute('muted')).toBe(true);
+      expect(el.muted).toBe(true);
 
-      el.setAttribute('poster', 'https://example.com/poster.jpg');
-      expect(el.poster).toBe('https://example.com/poster.jpg');
-      expect(el.target!.getAttribute('poster')).toBe('https://example.com/poster.jpg');
+      el.muted = false;
+      expect(el.hasAttribute('muted')).toBe(false);
+      expect(el.defaultMuted).toBe(false);
     });
 
-    it('poster setter forwards through PlaybackAdapter to the target', () => {
-      const el = create(defineVideoElement());
+    it('are rendered into the template at construction, minus the ones the adapter owns', () => {
+      const { tag } = defineVideoElement();
+      const container = document.createElement('div');
 
-      el.poster = 'https://example.com/poster.jpg';
-      expect(el.getAttribute('poster')).toBe('https://example.com/poster.jpg');
-      expect(el.target!.getAttribute('poster')).toBe('https://example.com/poster.jpg');
-    });
-  });
+      document.body.appendChild(container);
+      container.innerHTML = `<${tag} src="video.m3u8" muted poster="poster.jpg" crossorigin="anonymous" class="player" volume="0.5"></${tag}>`;
 
-  describe('setter attributes route through PlaybackAdapter property', () => {
-    it('sets muted property via attribute', () => {
-      const el = create(defineVideoElement());
+      const video = container.querySelector(tag)!.shadowRoot!.querySelector('video')!;
 
-      el.setAttribute('muted', '');
-      expect(el.muted).toBe(true);
+      expect(video.getAttribute('poster')).toBe('poster.jpg');
+      expect(video.getAttribute('crossorigin')).toBe('anonymous');
+      expect(video.hasAttribute('src')).toBe(false);
+      expect(video.hasAttribute('muted')).toBe(false);
+      expect(video.hasAttribute('class')).toBe(false);
+      expect(video.hasAttribute('volume')).toBe(false);
     });
 
-    it('unsets muted property when attribute removed', () => {
-      const el = create(defineVideoElement());
+    it('are not mirrored by an embed, whose template gets them all instead', () => {
+      const Ctor = CustomMediaElement(TestEmbedAdapter, {
+        template: (attrs) => `<iframe data-src="${attrs.src ?? ''}" data-muted="${'muted' in attrs}"></iframe>`,
+      });
+      const { tag } = define('test-embed', Ctor);
+      const container = document.createElement('div');
 
-      el.setAttribute('muted', '');
-      expect(el.muted).toBe(true);
+      document.body.appendChild(container);
+      container.innerHTML = `<${tag} src="https://example.com/embed" muted></${tag}>`;
 
-      el.removeAttribute('muted');
-      expect(el.muted).toBe(false);
-    });
+      const el = container.querySelector(tag)! as any;
+      const iframe = el.shadowRoot!.querySelector('iframe')!;
 
-    it('sets src property via attribute', () => {
-      const el = create(defineVideoElement());
+      expect(iframe.getAttribute('data-src')).toBe('https://example.com/embed');
+      expect(iframe.getAttribute('data-muted')).toBe('true');
+      expect(el.adapter.muted).toBe(true);
 
-      el.setAttribute('src', 'https://example.com/video.mp4');
-      expect(el.src).toBe('https://example.com/video.mp4');
+      el.setAttribute('autoplay', '');
+      expect(el.adapter.autoplay).toBe(true);
+      expect(iframe.hasAttribute('autoplay')).toBe(false);
     });
 
-    it('sets volume directly on PlaybackAdapter', () => {
-      const el = create(defineVideoElement());
+    it('do not include attributes a subclass observes for itself', () => {
+      class Extended extends CustomMediaElement(TestVideoAdapter) {
+        static get observedAttributes() {
+          return [...super.observedAttributes, 'playback-id'];
+        }
+      }
 
-      el.volume = 0.5;
-      expect(el.volume).toBe(0.5);
+      const el = create(define('test-video', Extended));
+
+      el.setAttribute('playback-id', 'abc');
+      expect(el.target!.hasAttribute('playback-id')).toBe(false);
     });
   });
 
-  describe('PlaybackAdapter property delegation', () => {
-    it('delegates getter properties to the PlaybackAdapter', () => {
+  describe('adapter surface', () => {
+    it('forwards getters, setters, and methods', () => {
       const el = create(defineVideoElement());
 
       expect(el.paused).toBe(true);
-      expect(el.duration).toBeNaN();
       expect(el.currentTime).toBe(0);
-    });
-
-    it('delegates setter properties to the PlaybackAdapter', () => {
-      const el = create(defineVideoElement());
+      expect(typeof el.play).toBe('function');
+      expect(typeof el.load).toBe('function');
 
       el.volume = 0.5;
       expect(el.target!.volume).toBe(0.5);
     });
 
-    it('delegates methods to the PlaybackAdapter', () => {
-      const el = create(defineVideoElement());
+    it('forwards object properties without an attribute', () => {
+      const el = create(defineVideoElementWithOptions());
+      const source = { src: 'https://example.com/video.m3u8' };
 
-      expect(typeof el.play).toBe('function');
-      expect(typeof el.pause).toBe('function');
-      expect(typeof el.load).toBe('function');
+      el.source = source;
+      el.metadata = { title: 'x' };
+
+      expect(el.source).toBe(source);
+      expect(el.hasAttribute('source')).toBe(false);
+      expect(el.adapter.metadata).toEqual({ title: 'x' });
+    });
+
+    it('leaves attach, detach, and destroy to the element', () => {
+      const { Ctor } = defineVideoElement();
+
+      for (const name of ['attach', 'detach', 'destroy']) {
+        expect(Object.getOwnPropertyDescriptor(Ctor.prototype, name)).toBeUndefined();
+      }
     });
 
-    it('excludes attach, detach, and destroy from delegation', () => {
+    it('defines the surface on the prototype', () => {
       const { Ctor } = defineVideoElement();
 
-      expect(Object.getOwnPropertyDescriptor(Ctor.prototype, 'attach')).toBeUndefined();
-      expect(Object.getOwnPropertyDescriptor(Ctor.prototype, 'detach')).toBeUndefined();
-      expect(Object.getOwnPropertyDescriptor(Ctor.prototype, 'destroy')).toBeUndefined();
+      for (const name of ['autoplay', 'controls', 'controlsList', 'poster', 'src', 'streamType', 'play']) {
+        expect(Object.getOwnPropertyDescriptor(Ctor.prototype, name), name).toBeDefined();
+        expect(Object.getOwnPropertyDescriptor(Ctor, name), name).toBeUndefined();
+      }
     });
   });
 
-  describe('event delegation', () => {
-    it('forwards non-composed media events from the target to the host', () => {
+  describe('events', () => {
+    it('forwards non-composed adapter events to the element', () => {
       const el = create(defineVideoElement());
       const handler = vi.fn();
 
@@ -722,7 +548,7 @@ describe('CustomMediaElement', () => {
       expect(handler).toHaveBeenCalledOnce();
     });
 
-    it('removes forwarded listener via removeEventListener', () => {
+    it('stops forwarding to a removed listener', () => {
       const el = create(defineVideoElement());
       const handler = vi.fn();
 
@@ -733,464 +559,73 @@ describe('CustomMediaElement', () => {
       expect(handler).not.toHaveBeenCalled();
     });
 
-    it('delivers DOM events dispatched directly on the host element', () => {
+    it('delivers events dispatched on the element itself once', () => {
       const el = create(defineVideoElement());
       const handler = vi.fn();
 
       el.addEventListener('click', handler);
       el.dispatchEvent(new MouseEvent('click', { bubbles: true }));
-
-      expect(handler).toHaveBeenCalledOnce();
-    });
-
-    it('delivers custom events dispatched on the host element', () => {
-      const el = create(defineVideoElement());
-      const handler = vi.fn();
-
-      el.addEventListener('my-custom-event', handler);
-      el.dispatchEvent(new CustomEvent('my-custom-event'));
-
-      expect(handler).toHaveBeenCalledOnce();
-    });
-
-    it('does not double-fire composed events that originate on the target', () => {
-      const el = create(defineVideoElement());
-      const handler = vi.fn();
-
-      el.addEventListener('click', handler);
       el.target!.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
 
-      expect(handler).toHaveBeenCalledOnce();
+      expect(handler).toHaveBeenCalledTimes(2);
     });
   });
 
-  describe('connectedCallback', () => {
-    it('marks iframe embeds with data-cross-origin-frame for cross-origin-safe styling', () => {
-      const el = create(defineIframeElement());
-
-      expect(el.hasAttribute('data-cross-origin-frame')).toBe(true);
-    });
-
-    it('does not add data-cross-origin-frame to native media elements', () => {
-      const el = create(defineVideoElement());
-
-      expect(el.hasAttribute('data-cross-origin-frame')).toBe(false);
+  describe('lifecycle', () => {
+    it('marks an embed with data-cross-origin-frame and leaves native hosts alone', () => {
+      expect(create(defineEmbedElement()).hasAttribute('data-cross-origin-frame')).toBe(true);
+      expect(create(defineVideoElement()).hasAttribute('data-cross-origin-frame')).toBe(false);
     });
-  });
 
-  describe('disconnectedCallback', () => {
-    it('calls destroy on the PlaybackAdapter when disconnected', async () => {
+    it('destroys the adapter a microtask after disconnecting', async () => {
       const el = create(defineVideoElement());
 
+      el.remove();
       expect(el.destroyed).toBe(false);
 
-      el.remove();
-      // Destroy is deferred a microtask to allow synchronous reparenting.
       await Promise.resolve();
       expect(el.destroyed).toBe(true);
     });
 
-    it('does not destroy when keep-alive attribute is set', async () => {
-      const el = create(defineVideoElement());
-
-      el.setAttribute('keep-alive', '');
-
-      el.remove();
-      await Promise.resolve();
-      expect(el.destroyed).toBe(false);
-    });
-
-    it('does not destroy when synchronously moved to a new parent', async () => {
-      const el = create(defineVideoElement());
+    it('keeps the adapter alive across a synchronous move or with keep-alive', async () => {
+      const moved = create(defineVideoElement());
+      const kept = create(defineVideoElement());
       const container = document.createElement('div');
 
       document.body.appendChild(container);
-
-      // Moving fires disconnectedCallback + connectedCallback synchronously.
-      container.appendChild(el);
+      container.appendChild(moved);
+      kept.setAttribute('keep-alive', '');
+      kept.remove();
       await Promise.resolve();
 
-      expect(el.destroyed).toBe(false);
-    });
-  });
-
-  describe('non-Attributes properties are directly delegated', () => {
-    it('excludes non-Attributes properties from observedAttributes', () => {
-      const { Ctor } = defineVideoElementWithObjects();
-      const observed = Ctor.observedAttributes;
-
-      expect(observed).not.toContain('source');
-      expect(observed).not.toContain('debug');
-      expect(observed).toContain('src');
-    });
-
-    it('allows object properties to be set via JS', () => {
-      const el = create(defineVideoElementWithObjects());
-      const newSource = { src: 'https://example.com/video.m3u8', engine: { maxBufferLength: 60 } };
-
-      el.source = newSource;
-      expect(el.source).toBe(newSource);
-    });
-
-    it('directly delegates primitive properties not in Attributes', () => {
-      const el = create(defineVideoElementWithObjects());
-
-      el.debug = true;
-      expect(el.debug).toBe(true);
-      expect(el.hasAttribute('debug')).toBe(false);
-    });
-  });
-
-  describe('property setters set attribute and delegate to PlaybackAdapter', () => {
-    it('string setter sets attribute on the custom element', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.src = 'https://example.com/video.mp4';
-      expect(el.getAttribute('src')).toBe('https://example.com/video.mp4');
-    });
-
-    it('string setter delegates value to the PlaybackAdapter via attributeChangedCallback', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.src = 'https://example.com/video.mp4';
-      expect(el.src).toBe('https://example.com/video.mp4');
-    });
-
-    it('preload setter delegates through the PlaybackAdapter', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.preload = 'metadata';
-
-      expect(el.getAttribute('preload')).toBe('metadata');
-      expect(el.preload).toBe('metadata');
-      expect(el.calls).toContain('set:preload:metadata');
-    });
-
-    it('number setter delegates directly to the PlaybackAdapter', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.volume = 0.5;
-      expect(el.volume).toBe(0.5);
-    });
-
-    it('number setter does not set attribute for non-Attributes properties', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.volume = 0.5;
-      expect(el.hasAttribute('volume')).toBe(false);
-    });
-
-    it('boolean setter toggles attribute on the custom element', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.muted = true;
-      expect(el.hasAttribute('muted')).toBe(true);
-    });
-
-    it('boolean setter removes attribute when set to false', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.muted = true;
-      el.muted = false;
-      expect(el.hasAttribute('muted')).toBe(false);
-    });
-
-    it('boolean setter delegates value to the PlaybackAdapter via attributeChangedCallback', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.muted = true;
-      expect(el.muted).toBe(true);
-
-      el.muted = false;
-      expect(el.muted).toBe(false);
-    });
-
-    it('currentTime setter delegates directly to PlaybackAdapter', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.currentTime = 42;
-      expect(el.currentTime).toBe(42);
-      expect(el.hasAttribute('current-time')).toBe(false);
-    });
-
-    it('playbackRate setter delegates directly to PlaybackAdapter', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.playbackRate = 2;
-      expect(el.playbackRate).toBe(2);
-      expect(el.hasAttribute('playback-rate')).toBe(false);
-    });
-
-    it('attribute is set before PlaybackAdapter setter is called', () => {
-      const el = create(defineTrackingVideoElement());
-      const spy = vi.spyOn(el, 'setAttribute');
-
-      el.src = 'video.mp4';
-
-      expect(spy).toHaveBeenCalledWith('src', 'video.mp4');
-      expect(spy.mock.invocationCallOrder[0]).toBeLessThan(Number.POSITIVE_INFINITY);
-    });
-
-    it('PlaybackAdapter setter receives the coerced value for each type', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.src = 'video.mp4';
-      el.volume = 0.75;
-      el.muted = true;
-      el.currentTime = 10;
-      el.playbackRate = 1.5;
-
-      expect(el.src).toBe('video.mp4');
-      expect(el.volume).toBe(0.75);
-      expect(el.muted).toBe(true);
-      expect(el.currentTime).toBe(10);
-      expect(el.playbackRate).toBe(1.5);
-    });
-
-    it('setting the same attribute value does not re-trigger the PlaybackAdapter setter', () => {
-      const el = create(defineTrackingVideoElement());
-      const spy = vi.fn();
-      const origSetAttribute = el.setAttribute.bind(el);
-
-      el.setAttribute = (...args: [string, string]) => {
-        origSetAttribute(...args);
-        spy(...args);
-      };
-
-      el.src = 'video.mp4';
-      expect(spy).toHaveBeenCalledOnce();
-      expect(el.src).toBe('video.mp4');
-    });
-
-    it('defaultMuted getter reflects the muted attribute', () => {
-      const el = create(defineTrackingVideoElement());
-
-      expect(el.defaultMuted).toBe(false);
-
-      el.setAttribute('muted', '');
-      expect(el.defaultMuted).toBe(true);
-
-      el.removeAttribute('muted');
-      expect(el.defaultMuted).toBe(false);
-    });
-
-    it('defaultMuted setter toggles the muted attribute', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.defaultMuted = true;
-      expect(el.hasAttribute('muted')).toBe(true);
-
-      el.defaultMuted = false;
-      expect(el.hasAttribute('muted')).toBe(false);
-    });
-
-    it('defaultMuted setter triggers the PlaybackAdapter muted setter via attributeChangedCallback', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.defaultMuted = true;
-      expect(el.muted).toBe(true);
-
-      el.defaultMuted = false;
-      expect(el.muted).toBe(false);
-    });
-
-    it('muted property setter and defaultMuted share the same attribute', () => {
-      const el = create(defineTrackingVideoElement());
-
-      el.muted = true;
-      expect(el.defaultMuted).toBe(true);
-
-      el.defaultMuted = false;
-      expect(el.muted).toBe(false);
-    });
-
-    it('object-typed properties bypass attribute and delegate directly to PlaybackAdapter', () => {
-      const el = create(defineVideoElementWithObjects());
-      const source = { engine: { startLevel: 2 } };
-
-      el.source = source;
-
-      expect(el.hasAttribute('source')).toBe(false);
-      expect(el.source).toBe(source);
-    });
-  });
-
-  describe('initial attribute forwarding', () => {
-    it('applies attributes present at construction time to the template', () => {
-      const { tag } = defineVideoElement();
-
-      const container = document.createElement('div');
-
-      document.body.appendChild(container);
-      container.innerHTML = `<${tag} poster="https://example.com/poster.jpg" crossorigin="anonymous"></${tag}>`;
-
-      const el = container.querySelector(tag)!;
-      const video = el.shadowRoot!.querySelector('video')!;
-
-      expect(video.getAttribute('poster')).toBe('https://example.com/poster.jpg');
-      expect(video.getAttribute('crossorigin')).toBe('anonymous');
-    });
-
-    it('excludes attribute-reflected PlaybackAdapter props from the inner element template', () => {
-      const { tag } = defineVideoElement();
-
-      const container = document.createElement('div');
-
-      document.body.appendChild(container);
-      container.innerHTML = `<${tag} src="video.mp4" volume="0.5" current-time="10" playback-rate="2" muted poster="poster.jpg"></${tag}>`;
-
-      const el = container.querySelector(tag)!;
-      const video = el.shadowRoot!.querySelector('video')!;
-
-      // src and muted are in Attributes AND have PlaybackAdapter setters, excluded from template
-      expect(video.hasAttribute('src')).toBe(false);
-      expect(video.hasAttribute('muted')).toBe(false);
-
-      // volume, current-time, playback-rate are not in Attributes at all, so not in template
-      expect(video.hasAttribute('volume')).toBe(false);
-      expect(video.hasAttribute('current-time')).toBe(false);
-      expect(video.hasAttribute('playback-rate')).toBe(false);
-
-      // poster is in Attributes but has no PlaybackAdapter setter, forwarded to template
-      expect(video.getAttribute('poster')).toBe('poster.jpg');
-    });
-
-    it('excludes non-allowed attributes from the inner element template', () => {
-      const { tag } = defineVideoElement();
-
-      const container = document.createElement('div');
-
-      document.body.appendChild(container);
-      container.innerHTML = `<${tag} class="player" data-id="123" poster="poster.jpg" autoplay></${tag}>`;
-
-      const el = container.querySelector(tag)!;
-      const video = el.shadowRoot!.querySelector('video')!;
-
-      expect(video.hasAttribute('class')).toBe(false);
-      expect(video.hasAttribute('data-id')).toBe(false);
-
-      expect(video.getAttribute('poster')).toBe('poster.jpg');
-      expect(video.hasAttribute('autoplay')).toBe(true);
-    });
-  });
-
-  describe('subclass properties override', () => {
-    it('includes subclass-added properties in observedAttributes', () => {
-      const Base = CustomMediaElement(TestVideoHost);
-
-      class Extended extends Base {
-        static properties = {
-          ...Base.properties,
-          playbackId: { type: String, attribute: 'playback-id' },
-        };
-      }
-
-      const tag = `test-video-${++tagCounter}`;
-
-      customElements.define(tag, Extended);
-
-      expect(Extended.observedAttributes).toContain('playback-id');
-    });
-
-    it('defines property accessors for subclass-added properties', () => {
-      const Base = CustomMediaElement(TestVideoHost);
-
-      class Extended extends Base {
-        static properties = {
-          ...Base.properties,
-          playbackId: { type: String, attribute: 'playback-id' },
-        };
-      }
-
-      const tag = `test-video-${++tagCounter}`;
-
-      customElements.define(tag, Extended);
-
-      const el = new Extended();
-
-      document.body.appendChild(el);
-
-      el.setAttribute('playback-id', 'abc123');
-      expect((el as any).playbackId).toBe('abc123');
-    });
-
-    it('subclass property setter sets the attribute', () => {
-      const Base = CustomMediaElement(TestVideoHost);
-
-      class Extended extends Base {
-        static properties = {
-          ...Base.properties,
-          playbackId: { type: String, attribute: 'playback-id' },
-        };
-      }
-
-      const tag = `test-video-${++tagCounter}`;
-
-      customElements.define(tag, Extended);
-
-      const el = new Extended();
-
-      document.body.appendChild(el);
-
-      (el as any).playbackId = 'xyz789';
-      expect(el.getAttribute('playback-id')).toBe('xyz789');
+      expect(moved.destroyed).toBe(false);
+      expect(kept.destroyed).toBe(false);
     });
   });
 
   describe('XSS prevention', () => {
-    it('does not inject nodes when poster contains a quote breakout attempt', () => {
-      const { tag } = defineVideoElement();
-      const container = document.createElement('div');
-
-      document.body.appendChild(container);
-      container.innerHTML = `<${tag} poster='" onerror="window.__xss=1'></${tag}>`;
-
-      const el = container.querySelector(tag)!;
-      const shadow = el.shadowRoot!;
-
-      expect(shadow.querySelectorAll('[onerror]')).toHaveLength(0);
-      expect(shadow.querySelectorAll('[onload]')).toHaveLength(0);
-      expect((globalThis as any).__xss).toBeUndefined();
-    });
-
-    it('does not inject script elements when an attribute value contains angle brackets', () => {
+    // jsdom's shadow DOM parsing has quirks, so the template is rendered into a plain container.
+    function renderTemplate(attrs: Record<string, string>) {
       const { Ctor } = defineVideoElement();
-      const maliciousValue = '"><script>window.__xss=1</script><video x="';
-
-      // JSDOM shadow DOM has parsing quirks; test template directly in a plain container.
       const container = document.createElement('div');
 
-      container.innerHTML = (Ctor as any).template({ crossorigin: maliciousValue });
+      container.innerHTML = Ctor.template(attrs);
 
-      expect(container.querySelectorAll('script')).toHaveLength(0);
-      expect(container.querySelectorAll('img[onerror]')).toHaveLength(0);
-      expect((globalThis as any).__xss).toBeUndefined();
-    });
-
-    it('does not inject img elements when poster contains an angle-bracket payload', () => {
-      const { Ctor } = defineVideoElement();
-      const maliciousValue = '"><img src=x onerror="window.__xss=1">';
+      return container;
+    }
 
-      // JSDOM shadow DOM has parsing quirks; test template directly in a plain container.
-      const container = document.createElement('div');
-
-      container.innerHTML = (Ctor as any).template({ poster: maliciousValue });
+    it('does not inject nodes when poster contains a quote breakout attempt', () => {
+      const container = renderTemplate({ poster: '"><script>alert(1)</script>' });
 
-      expect(container.querySelectorAll('img')).toHaveLength(0);
-      expect((globalThis as any).__xss).toBeUndefined();
+      expect(container.querySelector('script')).toBeNull();
+      expect(container.querySelector('video')!.getAttribute('poster')).toBe('"><script>alert(1)</script>');
     });
 
-    it('preserves the attribute value correctly after escaping', () => {
-      const { tag } = defineVideoElement();
-      const container = document.createElement('div');
-
-      document.body.appendChild(container);
-      container.innerHTML = `<${tag} poster="https://example.com/poster.jpg"></${tag}>`;
-
-      const el = container.querySelector(tag)!;
-      const video = el.shadowRoot!.querySelector('video')!;
+    it('does not inject elements when an attribute value contains angle brackets', () => {
+      const container = renderTemplate({ crossorigin: '<img src=x onerror=alert(1)>' });
 
-      expect(video.getAttribute('poster')).toBe('https://example.com/poster.jpg');
+      expect(container.querySelector('img')).toBeNull();
+      expect(container.querySelector('video')!.getAttribute('crossorigin')).toBe('<img src=x onerror=alert(1)>');
     });
   });
 });
diff --git a/packages/media/src/dom/custom-media-element/tests/media-children.test.ts b/packages/media/src/dom/custom-media-element/tests/media-children.test.ts
new file mode 100644
index 0000000000..0ccac37350
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/tests/media-children.test.ts
@@ -0,0 +1,70 @@
+import { beforeEach, describe, expect, it } from 'vite-plus/test';
+
+import { MediaChildren } from '../media-children';
+
+function createHost() {
+  const host = document.createElement('div');
+
+  host.attachShadow({ mode: 'open' });
+  host.shadowRoot!.innerHTML = '<video></video><slot></slot>';
+  document.body.append(host);
+
+  const video = host.shadowRoot!.querySelector('video')!;
+  const children = new MediaChildren(host, () => video);
+
+  return { host, video, children };
+}
+
+describe('MediaChildren', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('clones track and source children into the target and leaves other children alone', () => {
+    const { host, video, children } = createHost();
+
+    host.innerHTML = '<track kind="captions" src="en.vtt" /><source src="a.mp4" /><span>label</span>';
+    children.sync();
+
+    expect(video.querySelector('track')?.getAttribute('src')).toBe('en.vtt');
+    expect(video.querySelector('source')?.getAttribute('src')).toBe('a.mp4');
+    expect(video.querySelector('span')).toBeNull();
+    expect(host.querySelector('track')).not.toBe(video.querySelector('track'));
+  });
+
+  it('removes a clone when its child leaves', () => {
+    const { host, video, children } = createHost();
+
+    host.innerHTML = '<source src="a.mp4" /><source src="b.mp4" />';
+    children.sync();
+    host.querySelector('source')!.remove();
+    children.sync();
+
+    expect([...video.querySelectorAll('source')].map((el) => el.getAttribute('src'))).toEqual(['b.mp4']);
+  });
+
+  it('mirrors attribute changes from a child to its clone', async () => {
+    const { host, video, children } = createHost();
+
+    host.innerHTML = '<source src="a.mp4" />';
+    children.sync();
+    host.querySelector('source')!.setAttribute('src', 'c.mp4');
+    await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));
+
+    expect(video.querySelector('source')?.getAttribute('src')).toBe('c.mp4');
+  });
+
+  it('enables a default chapters track that the browser left disabled', () => {
+    const { host, video, children } = createHost();
+    const textTrack = { mode: 'disabled' };
+
+    // jsdom has no `TextTrack`; the clone inherits the stub through the prototype.
+    Object.defineProperty(HTMLTrackElement.prototype, 'track', { configurable: true, get: () => textTrack });
+    host.innerHTML = '<track kind="chapters" default src="chapters.vtt" />';
+    children.sync();
+    delete (HTMLTrackElement.prototype as { track?: unknown }).track;
+
+    expect(video.querySelector('track')!.hasAttribute('default')).toBe(true);
+    expect(textTrack.mode).toBe('hidden');
+  });
+});
diff --git a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
index 5eb255d927..6977fef927 100644
--- a/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
+++ b/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
@@ -1,5 +1,13 @@
 import type { Audio, AudioEvents } from '../../core/types';
-import { HTMLMediaAdapter, type HTMLMediaTargetLike } from '../html-media-adapter';
+import {
+  type AttributeConfigs,
+  HTMLMediaAdapter,
+  type HTMLMediaTargetLike,
+  mediaContentAttributes,
+} from '../html-media-adapter';
+
+/** The content attributes an `<audio>` accepts: the media ones and nothing more. */
+export const audioContentAttributes: AttributeConfigs = mediaContentAttributes;
 
 export class HTMLAudioAdapter extends HTMLMediaAdapter<HTMLMediaTargetLike, AudioEvents> implements Audio {
   static readonly host = 'audio';
diff --git a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
index e50e0376ae..4fae6b968b 100644
--- a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
+++ b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
@@ -27,6 +27,36 @@ export interface HTMLMediaTargetLike extends MediaTargetLike, EventTarget {
  */
 export type AdapterHost = 'video' | 'audio' | 'iframe';
 
+/** How a property maps to the content attribute that drives it. */
+export interface AttributeConfig {
+  type: BooleanConstructor | NumberConstructor | StringConstructor;
+  /** The attribute name when it is not the lowercased property name. */
+  attribute?: string;
+  /** The value the property takes when the attribute is removed, when that is not the empty string. */
+  empty?: unknown;
+}
+
+export type AttributeConfigs = Record<string, AttributeConfig>;
+
+/**
+ * The content attributes every native media element accepts, keyed by the property that reflects each one.
+ *
+ * `defaultMuted` shares the `muted` attribute with the `muted` property, which owns it: a `<video muted>` starts muted,
+ * and toggling the attribute later toggles playback muting the way the property does.
+ */
+export const mediaContentAttributes: AttributeConfigs = {
+  autoplay: { type: Boolean },
+  controls: { type: Boolean },
+  controlsList: { type: String },
+  crossOrigin: { type: String, empty: null },
+  defaultMuted: { type: Boolean, attribute: 'muted' },
+  disableRemotePlayback: { type: Boolean },
+  loading: { type: String },
+  loop: { type: Boolean },
+  preload: { type: String, empty: null },
+  src: { type: String, empty: '' },
+};
+
 /** An {@link HTMLMediaAdapter} over any target and event map: the shape extensions and element façades share. */
 export type AnyHTMLMediaAdapter<Target extends HTMLMediaTargetLike = any> = HTMLMediaAdapter<Target, any>;
 
diff --git a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index 9a2945cd5d..a642e4ce7a 100644
--- a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -2,10 +2,26 @@ import type { WebKitDocument, WebKitPresentationMode, WebKitVideoElement } from
 import { isFunction } from '@videojs/utils/predicate';
 
 import type { Video, VideoEvents, VideoTargetLike } from '../../core/types';
-import { getMediaProp, HTMLMediaAdapter, type HTMLMediaTargetLike, setMediaProp } from '../html-media-adapter';
+import {
+  type AttributeConfigs,
+  getMediaProp,
+  HTMLMediaAdapter,
+  type HTMLMediaTargetLike,
+  mediaContentAttributes,
+  setMediaProp,
+} from '../html-media-adapter';
 
 export interface HTMLVideoTargetLike extends VideoTargetLike, HTMLMediaTargetLike {}
 
+/** The content attributes a `<video>` accepts: the media ones plus its own. */
+export const videoContentAttributes: AttributeConfigs = {
+  ...mediaContentAttributes,
+  autoPictureInPicture: { type: Boolean },
+  disablePictureInPicture: { type: Boolean },
+  playsInline: { type: Boolean },
+  poster: { type: String, empty: '' },
+};
+
 export class HTMLVideoAdapter extends HTMLMediaAdapter<HTMLVideoTargetLike, VideoEvents> implements Video {
   // Typed to admit `'audio'` so an adapter built on the video base can override it and play in an `<audio>`, as the
   // hls.js-backed `MuxAudioAdapter` does. Element façades treat anything not narrowed to `'audio'` as a video.

From 0d92d24f6834f5653b992ae0b3e0a3ebb293e64c Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:46:37 -0700
Subject: [PATCH 11/25] docs(site): derive media element attributes from the
 adapter contract

The builder reads the native attribute lists beside the base adapters and
derives custom attributes from each adapter's `defaultProps`, the same rule
the element applies, instead of parsing `static properties`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media-element-handler.ts              | 124 ++++++++++++------
 .../api-docs-builder/src/tests/e2e.test.ts    |  11 ++
 .../custom-media-element.ts                   |  85 +-----------
 .../src/dom/custom-media-element/index.ts     |   1 +
 .../src/dom/custom-media-element/templates.ts |  56 ++++++++
 .../html-audio-adapter/html-audio-adapter.ts  |   5 +-
 .../html-media-adapter/html-media-adapter.ts  |  14 ++
 .../html-video-adapter/html-video-adapter.ts  |  11 +-
 .../packages/media/src/dom/simple/adapter.ts  |   6 +
 9 files changed, 191 insertions(+), 122 deletions(-)
 create mode 100644 site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/templates.ts

diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index 94e6defa58..dd15e4a5f1 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -131,13 +131,9 @@ export function generateMediaElementReferences(monorepoRoot: string): MediaEleme
   const sources = discoverMediaElements(monorepoRoot, project);
   if (sources.length === 0) return [];
 
-  const customMediaPath = path.join(
-    monorepoRoot,
-    'packages/media/src/dom/custom-media-element/custom-media-element.ts'
-  );
-  if (!fs.existsSync(customMediaPath)) return [];
+  const templatesPath = path.join(monorepoRoot, 'packages/media/src/dom/custom-media-element/templates.ts');
+  if (!fs.existsSync(templatesPath)) return [];
 
-  const staticProperties = extractStaticProperties(customMediaPath, project);
   const mediaTypesPath = path.join(monorepoRoot, 'packages/media/src/core/types.ts');
   const videoEvents = extractEventsFromTypes(mediaTypesPath, 'VideoEvents', project);
   const audioEvents = extractEventsFromTypes(mediaTypesPath, 'AudioEvents', project);
@@ -157,8 +153,14 @@ export function generateMediaElementReferences(monorepoRoot: string): MediaEleme
   const audioHost = extractHostProperties(audioHostPath, 'HTMLAudioAdapter', project, nativeNames);
   const videoBaseSurface = { ...baseHost.properties, ...videoHost.properties };
   const audioBaseSurface = { ...baseHost.properties, ...audioHost.properties };
-  const videoCSSVars = cssVarsRecord(extractCSSVars(customMediaPath, project, 'Video'));
-  const audioCSSVars = cssVarsRecord(extractCSSVars(customMediaPath, project, 'Audio'));
+  const videoCSSVars = cssVarsRecord(extractCSSVars(templatesPath, project, 'Video'));
+  const audioCSSVars = cssVarsRecord(extractCSSVars(templatesPath, project, 'Audio'));
+  // The content attributes each native host accepts, declared beside the base adapter that knows what it is.
+  const nativeAttributes = {
+    video: extractAttributeConfigs(videoHostPath, 'videoContentAttributes', project),
+    audio: extractAttributeConfigs(audioHostPath, 'audioContentAttributes', project),
+    iframe: [],
+  };
   const results: MediaElementResult[] = [];
 
   for (const source of sources) {
@@ -174,19 +176,24 @@ export function generateMediaElementReferences(monorepoRoot: string): MediaEleme
 
     Object.assign(propertyDefinitions, host.properties);
 
-    const standardAttributes: string[] = [];
+    // Standard attributes are the host's native ones. Custom attributes derive from the adapter's `defaultProps`, one
+    // per primitive default, the same rule the element applies at runtime.
+    const native = nativeAttributes[source.targetTag];
+    const standardAttributes = native.map(({ attribute }) => attribute);
+    const nativeAttributeOf = new Map(native.map(({ property, attribute }) => [property, attribute]));
     const customAttributes: Record<string, HostPropertyDef> = {};
 
-    for (const { property, attribute } of staticProperties) {
+    for (const [property, value] of collectFileDefaults(source.hostFilePath, project)) {
+      if (STATE_PROPS.has(property) || !isPrimitiveDefault(value)) continue;
+
+      const attribute = nativeAttributeOf.get(property) ?? attributeNameFor(property, nativeAttributes.video);
+      if (standardAttributes.includes(attribute)) continue;
+
       const definition = publicProperties[property];
 
-      if (source.targetTag === 'iframe') {
-        if (definition) customAttributes[attribute] = { ...definition, readonly: false };
-      } else if (definition && !definition.overridesNative) {
-        customAttributes[attribute] = { ...definition, readonly: false };
-      } else {
-        standardAttributes.push(attribute);
-      }
+      customAttributes[attribute] = definition
+        ? { ...definition, readonly: false, default: value }
+        : { type: primitiveTypeOf(value), readonly: false, default: value };
     }
 
     const files = [...new Set(host.files)];
@@ -1045,38 +1052,73 @@ function serializeDefault(expression: Expression, file: SourceFile, project: Oxc
   return undefined;
 }
 
-function extractStaticProperties(filePath: string, project: OxcProject): StaticMediaProperty[] {
-  const file = project.source(filePath);
-  if (!file) return [];
+/** Live playback state has no content attribute, even when an adapter lists a default for it. */
+const STATE_PROPS = new Set(['muted', 'volume', 'currentTime', 'playbackRate']);
 
-  const properties: StaticMediaProperty[] = [];
+/** Whether a serialized default is a boolean, number, or string, and so becomes an attribute. */
+function isPrimitiveDefault(value: string): boolean {
+  return value === 'true' || value === 'false' || /^-?\d/.test(value) || /^['"`]/.test(value);
+}
 
-  walkAst(file.program, (node) => {
-    if (node.type !== 'PropertyDefinition' || !node.static || staticName(node.key) !== 'properties' || !node.value) {
-      return;
-    }
+function primitiveTypeOf(value: string): string {
+  if (value === 'true' || value === 'false') return 'boolean';
 
-    const object = unwrapObjectExpression(node.value);
-    if (!object) return;
+  return /^-?\d/.test(value) ? 'number' : 'string';
+}
 
-    for (const property of object.properties) {
-      if (property.type !== 'Property' || property.kind !== 'init') continue;
+/** The attribute a derived property reflects through: its WHATWG spelling if the video host names it, else kebab-case. */
+function attributeNameFor(property: string, video: StaticMediaProperty[]): string {
+  return (
+    video.find((entry) => entry.property === property)?.attribute ??
+    property.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+  );
+}
 
-      const name = staticName(property.key);
-      if (!name) continue;
+/**
+ * The `{ property: { type, attribute? } }` entries of an exported attribute-config const, following spreads of other
+ * consts such as `videoContentAttributes` spreading `mediaContentAttributes`.
+ */
+function extractAttributeConfigs(filePath: string, constName: string, project: OxcProject): StaticMediaProperty[] {
+  const declaration = project.resolveName(filePath, constName);
+  if (declaration?.declaration.type !== 'VariableDeclarator' || !declaration.declaration.init) return [];
 
-      const config = unwrapObjectExpression(property.value);
-      const attributeProperty = config?.properties.find(
-        (entry) => entry.type === 'Property' && staticName(entry.key) === 'attribute'
-      );
-      const attribute =
-        attributeProperty?.type === 'Property' && attributeProperty.value.type === 'Literal'
-          ? attributeProperty.value.value
-          : undefined;
+  // `audioContentAttributes = mediaContentAttributes` names another const rather than spelling its own literal.
+  const initializer = unwrapExpression(declaration.declaration.init);
+
+  if (initializer.type === 'Identifier') {
+    return extractAttributeConfigs(declaration.file.filePath, initializer.name, project);
+  }
+
+  const resolved = resolveConstObject(filePath, constName, project);
+  if (!resolved) return [];
+
+  const properties: StaticMediaProperty[] = [];
+
+  for (const property of resolved.object.properties) {
+    if (property.type === 'SpreadElement') {
+      if (property.argument.type === 'Identifier') {
+        properties.push(...extractAttributeConfigs(resolved.file.filePath, property.argument.name, project));
+      }
 
-      properties.push({ property: name, attribute: typeof attribute === 'string' ? attribute : name.toLowerCase() });
+      continue;
     }
-  });
+
+    if (property.type !== 'Property' || property.kind !== 'init') continue;
+
+    const name = staticName(property.key);
+    if (!name) continue;
+
+    const config = unwrapObjectExpression(property.value);
+    const attributeProperty = config?.properties.find(
+      (entry) => entry.type === 'Property' && staticName(entry.key) === 'attribute'
+    );
+    const attribute =
+      attributeProperty?.type === 'Property' && attributeProperty.value.type === 'Literal'
+        ? attributeProperty.value.value
+        : undefined;
+
+    properties.push({ property: name, attribute: typeof attribute === 'string' ? attribute : name.toLowerCase() });
+  }
 
   return properties;
 }
diff --git a/site/scripts/api-docs-builder/src/tests/e2e.test.ts b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
index f4401c4ffe..658ec9f06c 100644
--- a/site/scripts/api-docs-builder/src/tests/e2e.test.ts
+++ b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
@@ -2180,6 +2180,17 @@ describe('Media element pipeline (end-to-end)', () => {
       expect(ref.mediaType).toBe('audio');
     });
 
+    it('takes the media attributes of the audio host as standard and none of the video ones', () => {
+      const attributes = findElement('SpfAudio')!.reference.platforms.html.attributes;
+
+      expect(attributes.standard).toContain('src');
+      expect(attributes.standard).toContain('controls');
+      expect(attributes.standard).toContain('muted');
+      expect(attributes.standard).not.toContain('poster');
+      expect(attributes.standard).not.toContain('playsinline');
+      expect(attributes.custom['preload']).toBeUndefined();
+    });
+
     it('resolves the mixin through another package barrel', () => {
       const props = findElement('SpfAudio')!.reference.platforms.html.properties.definitions;
 
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 0107ef2b73..d0e748412f 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -1,90 +1,17 @@
 /**
- * Mock custom media element infrastructure.
+ * Mock custom media element factory.
  *
- * Exercises: shared native attributes (via static properties), CSS vars,
- * and slots that the builder reads to populate media element references.
- * Slots are parsed from getVideoTemplateHTML / getCommonTemplateHTML.
- *
- * VideoCSSVars/AudioCSSVars follow the `{ camelKey: '--var-name' }` pattern
- * with JSDoc descriptions, matching UI component css-vars files.
+ * Exercises: composition through the factory. The builder reads nothing from this file; native attributes come from the
+ * base adapters and CSS vars from templates.ts.
  */
-
-/** CSS custom property names for video elements. */
-export const VideoCSSVars = {
-  /** Border radius of the video element. */
-  borderRadius: '--media-video-border-radius',
-  /** Object fit for the video. */
-  objectFit: '--media-object-fit',
-  /** Object position for the video. */
-  objectPosition: '--media-object-position',
-  /** Duration of the caption track transition. */
-  captionTrackDuration: '--media-caption-track-duration',
-  /** Delay before the caption track transition. */
-  captionTrackDelay: '--media-caption-track-delay',
-  /** Vertical offset of the caption track. */
-  captionTrackY: '--media-caption-track-y',
-} as const;
-
-/** CSS custom property names for audio elements. */
-export const AudioCSSVars = {} as const;
-
-// Minimal template stubs — the builder parses <slot> elements from these.
-function getVideoTemplateHTML(attrs: Record<string, string>): string {
-  return /*html*/ `
-    <style>
-      video {
-        border-radius: var(${VideoCSSVars.borderRadius});
-        object-fit: var(${VideoCSSVars.objectFit}, contain);
-        object-position: var(${VideoCSSVars.objectPosition}, center);
-      }
-    </style>
-    <slot name="media">
-      <video></video>
-    </slot>
-    <slot></slot>
-  `;
-}
-
-function getCommonTemplateHTML(tag: string) {
-  return (attrs: Record<string, string>) => {
-    return /*html*/ `
-      <style>
-        ${tag} { width: 100%; }
-      </style>
-      <slot name="media">
-        <${tag}></${tag}>
-      </slot>
-      <slot></slot>
-    `;
-  };
-}
+import { commonTemplate, videoTemplate } from './templates';
 
 // Stub — the builder parses the AST, it doesn't run the code.
 // Mirrors the real CustomMediaElement factory signature: the target is the adapter's static `host`.
-export function CustomMediaElement(Adapter: { readonly host: 'video' | 'audio' | 'iframe' }) {
-  const tag = Adapter.host;
-
+export function CustomMediaElement(Adapter: { readonly host: 'video' | 'audio' | 'iframe'; readonly defaultProps: object }) {
   class CustomMedia {
-    static template = tag === 'video' ? getVideoTemplateHTML : getCommonTemplateHTML(tag);
+    static template = Adapter.host === 'video' ? videoTemplate : commonTemplate(Adapter.host);
     static shadowRootOptions = { mode: 'open' };
-
-    static properties = {
-      autoPictureInPicture: { type: Boolean },
-      autoplay: { type: Boolean },
-      controls: { type: Boolean },
-      controlsList: { type: String },
-      crossOrigin: { type: String },
-      defaultMuted: { type: Boolean, attribute: 'muted' },
-      disablePictureInPicture: { type: Boolean },
-      disableRemotePlayback: { type: Boolean },
-      loading: { type: String },
-      loop: { type: Boolean },
-      playsInline: { type: Boolean },
-      poster: { type: String },
-      preload: { type: String },
-      src: { type: String },
-      streamType: { type: String, attribute: 'stream-type' },
-    };
   }
 
   return CustomMedia;
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/index.ts
index df08577f10..a2337100b9 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/index.ts
@@ -1 +1,2 @@
 export * from './custom-media-element';
+export * from './templates';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/templates.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/templates.ts
new file mode 100644
index 0000000000..f629844a7d
--- /dev/null
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/templates.ts
@@ -0,0 +1,56 @@
+/**
+ * Mock media templates — mirrors the real templates.ts.
+ *
+ * Exercises: the CSS vars and the slots the builder reads from the templates. VideoCSSVars/AudioCSSVars follow the
+ * `{ camelKey: '--var-name' }` pattern with JSDoc descriptions, matching UI component css-vars files.
+ */
+
+/** CSS custom property names for video elements. */
+export const VideoCSSVars = {
+  /** Border radius of the video element. */
+  borderRadius: '--media-video-border-radius',
+  /** Object fit for the video. */
+  objectFit: '--media-object-fit',
+  /** Object position for the video. */
+  objectPosition: '--media-object-position',
+  /** Duration of the caption track transition. */
+  captionTrackDuration: '--media-caption-track-duration',
+  /** Delay before the caption track transition. */
+  captionTrackDelay: '--media-caption-track-delay',
+  /** Vertical offset of the caption track. */
+  captionTrackY: '--media-caption-track-y',
+} as const;
+
+/** CSS custom property names for audio elements. */
+export const AudioCSSVars = {} as const;
+
+// Minimal template stubs — the builder parses <slot> elements from these.
+export function videoTemplate(attrs: Record<string, string>): string {
+  return /*html*/ `
+    <style>
+      video {
+        border-radius: var(${VideoCSSVars.borderRadius});
+        object-fit: var(${VideoCSSVars.objectFit}, contain);
+        object-position: var(${VideoCSSVars.objectPosition}, center);
+      }
+    </style>
+    <slot name="media">
+      <video></video>
+    </slot>
+    <slot></slot>
+  `;
+}
+
+export function commonTemplate(tag: string) {
+  return (attrs: Record<string, string>) => {
+    return /*html*/ `
+      <style>
+        ${tag} { width: 100%; }
+      </style>
+      <slot name="media">
+        <${tag}></${tag}>
+      </slot>
+      <slot></slot>
+    `;
+  };
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
index d31fccbe26..d8eeb3bf88 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-audio-adapter/html-audio-adapter.ts
@@ -4,8 +4,11 @@
  * Adds no methods of its own: audio elements get only the shared html-media-adapter
  * methods.
  */
-import { HTMLMediaAdapter } from '../html-media-adapter';
+import { HTMLMediaAdapter, mediaContentAttributes } from '../html-media-adapter';
 
 export class HTMLAudioAdapter extends HTMLMediaAdapter {
   static readonly host = 'audio';
 }
+
+/** The content attributes an `<audio>` accepts: the media ones and nothing more. */
+export const audioContentAttributes = mediaContentAttributes;
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-media-adapter/html-media-adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
index 6c776416fe..10df1dcf23 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
@@ -57,3 +57,17 @@ export class HTMLMediaAdapter {
     return '';
   }
 }
+
+/** The content attributes every native media element accepts, keyed by the property that reflects each one. */
+export const mediaContentAttributes = {
+  autoplay: { type: Boolean },
+  controls: { type: Boolean },
+  controlsList: { type: String },
+  crossOrigin: { type: String },
+  defaultMuted: { type: Boolean, attribute: 'muted' },
+  disableRemotePlayback: { type: Boolean },
+  loading: { type: String },
+  loop: { type: Boolean },
+  preload: { type: String },
+  src: { type: String },
+};
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index b50a4dd3f3..24cb153103 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -6,7 +6,7 @@
  * video-only native-property extraction (videoWidth) and a non-native helper
  * (isFullscreen) that must be filtered out of nativeProperties.
  */
-import { HTMLMediaAdapter } from '../html-media-adapter';
+import { HTMLMediaAdapter, mediaContentAttributes } from '../html-media-adapter';
 
 export class HTMLVideoAdapter extends HTMLMediaAdapter {
   static readonly host = 'video';
@@ -25,3 +25,12 @@ export class HTMLVideoAdapter extends HTMLMediaAdapter {
     return false;
   }
 }
+
+/** The content attributes a `<video>` accepts: the media ones plus its own. */
+export const videoContentAttributes = {
+  ...mediaContentAttributes,
+  autoPictureInPicture: { type: Boolean },
+  disablePictureInPicture: { type: Boolean },
+  playsInline: { type: Boolean },
+  poster: { type: String },
+};
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
index 1b74d657c7..073e2d1b1b 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
@@ -22,6 +22,12 @@ export class HTMLAudioAdapter {
 }
 
 export class SimpleHost extends HTMLVideoAdapter {
+  static readonly defaultProps = {
+    src: '',
+    source: null,
+    streamType: 'unknown',
+  };
+
   #src: string = '';
   #engine: object = {};
 

From 74345a2ba44d66368b67a24bfd8ea1c9c1d70027 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:48:02 -0700
Subject: [PATCH 12/25] refactor(html): build the background elements on the
 media element pieces

`<background-video>` renders through `renderHost` and `<hls-background-video>`
keeps its engine attached and destroyed through `AdapterAttachment`, instead
of each hand-rolling the shadow root and the deferred teardown.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media/background-video/adapter.ts     | 20 ++++++------
 .../src/media/hls-background-video/adapter.ts | 31 +++++++------------
 2 files changed, 23 insertions(+), 28 deletions(-)

diff --git a/packages/html/src/media/background-video/adapter.ts b/packages/html/src/media/background-video/adapter.ts
index d9d800a603..042aa4ff22 100644
--- a/packages/html/src/media/background-video/adapter.ts
+++ b/packages/html/src/media/background-video/adapter.ts
@@ -1,4 +1,4 @@
-import type { Media } from '@videojs/media/dom';
+import { type Media, renderHost } from '@videojs/media/dom';
 import { namedNodeMapToObject } from '@videojs/utils/dom';
 
 import { MediaAttachMixin } from '../../store/media-attach-mixin';
@@ -6,7 +6,8 @@ import { backgroundVideoTemplate } from './template';
 
 const HTMLElementBase = globalThis.HTMLElement ?? class {};
 
-// Don't extend CustomMediaMixin to save some bytes, background videos don't need the full Media API.
+// Not a `CustomMediaElement`: a background video has no adapter and needs one attribute, not the full media API. It
+// renders through the same `renderHost` the media elements use.
 export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
   static template = backgroundVideoTemplate;
@@ -17,10 +18,12 @@ export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
   constructor() {
     super();
 
-    if (!this.shadowRoot) {
-      this.attachShadow((this.constructor as typeof BackgroundVideo).shadowRootOptions);
+    const ctor = this.constructor as typeof BackgroundVideo;
 
-      const attrs = {
+    renderHost(
+      this,
+      ctor.template,
+      {
         ...namedNodeMapToObject(this.attributes),
         ...(!this.hasAttribute('nomuted') && { muted: '' }),
         ...(!this.hasAttribute('noloop') && { loop: '' }),
@@ -28,10 +31,9 @@ export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
         playsinline: '',
         disableremoteplayback: '',
         disablepictureinpicture: '',
-      };
-
-      this.shadowRoot!.innerHTML = backgroundVideoTemplate(attrs);
-    }
+      },
+      ctor.shadowRootOptions
+    );
 
     // Neither Chrome or Firefox support setting the muted attribute
     // after using document.createElement.
diff --git a/packages/html/src/media/hls-background-video/adapter.ts b/packages/html/src/media/hls-background-video/adapter.ts
index cd6ad456ea..49a4a24763 100644
--- a/packages/html/src/media/hls-background-video/adapter.ts
+++ b/packages/html/src/media/hls-background-video/adapter.ts
@@ -1,4 +1,4 @@
-import type { Media } from '@videojs/media/dom';
+import { AdapterAttachment, type Media, renderHost } from '@videojs/media/dom';
 import { HlsBackgroundVideoAdapter, type HlsVideoMediaError } from '@videojs/spf/hls-background-video';
 import { type CustomElement, namedNodeMapToObject } from '@videojs/utils/dom';
 import type { Constructor } from '@videojs/utils/types';
@@ -58,14 +58,17 @@ export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
   }
 
   #media = new HlsBackgroundVideoAdapter();
+  #attachment = new AdapterAttachment(this, this.#media, () => this.video);
 
   constructor() {
     super();
 
-    if (!this.shadowRoot) {
-      this.attachShadow((this.constructor as typeof HlsBackgroundVideo).shadowRootOptions);
+    const ctor = this.constructor as typeof HlsBackgroundVideo;
 
-      const attrs = {
+    renderHost(
+      this,
+      ctor.template,
+      {
         ...namedNodeMapToObject(this.attributes),
         muted: '',
         loop: '',
@@ -73,18 +76,15 @@ export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
         playsinline: '',
         disableremoteplayback: '',
         disablepictureinpicture: '',
-      };
-
-      this.shadowRoot!.innerHTML = backgroundVideoTemplate(attrs);
-    }
+      },
+      ctor.shadowRootOptions
+    );
 
     // Neither Chrome nor Firefox honor a `muted` attribute set after
     // `document.createElement`, and autoplay is refused without it. Attaching is
     // what sets the property — along with the rest of the fixed behavior — so
     // nothing here needs to repeat it.
-    const video = this.video;
-
-    if (video) this.#media.attach(video);
+    this.#attachment.attach();
 
     // Re-fired rather than bridged on demand the way `CustomMediaElement` does
     // it: one listener for the one event this element has, on a Media it owns
@@ -99,14 +99,7 @@ export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
 
   override disconnectedCallback(): void {
     super.disconnectedCallback?.();
-
-    if (this.hasAttribute('keep-alive')) return;
-
-    // Deferred so a synchronous reparent (remove then insert) doesn't tear down
-    // the engine, matching `CustomMediaElement`.
-    queueMicrotask(() => {
-      if (!this.isConnected) this.#media.destroy();
-    });
+    this.#attachment.release();
   }
 
   attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {

From 9c53e3847083ed3a4358b8a24f3a98957c58758b Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:48:25 -0700
Subject: [PATCH 13/25] docs(site): describe how a media element derives its
 attributes

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../docs/reference/create-media-element.mdx   | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index f18d2295fe..3cc051bb88 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -14,7 +14,7 @@ import { createMediaElement } from "@videojs/html";
 
 ## Usage
 
-Pass an adapter class. The returned element renders the adapter's host element in its shadow root, drives it through the adapter, and registers itself with the surrounding <DocsLink slug="reference/player">player</DocsLink> on connect. Every adapter declares its host as a static: `'video'` for `HlsJsAdapter`, `'audio'` for `HlsAudioAdapter`, `'iframe'` for the embed adapters.
+Pass an adapter class. The returned element renders the adapter's host element in its shadow root, drives it through the adapter, and registers itself with the surrounding <DocsLink slug="reference/player">player</DocsLink> on connect. Everything the element exposes comes from two statics every adapter declares: `host`, which is `'video'` for `HlsJsAdapter`, `'audio'` for `HlsAudioAdapter`, and `'iframe'` for the embed adapters, and `defaultProps`, which names the adapter's configurable properties and their defaults.
 
 ```ts
 import { createMediaElement } from '@videojs/html';
@@ -41,6 +41,23 @@ The template is written to the shadow root with `innerHTML`, so escape any attri
 
 The template is also the element's static `template`, so a subclass can override it the same way.
 
+## Attributes
+
+Each primitive in the adapter's `defaultProps` becomes a content attribute of the same type, named by its WHATWG spelling where one exists and kebab-case otherwise: `src`, `preload`, `stream-type`. Removing the attribute resets the property to its default. Object properties such as `source` are property-only. This is the rule <DocsLink slug="reference/create-media-component">createMediaComponent</DocsLink> applies to React props, so both façades expose the same surface from one declaration.
+
+A `<video>` or `<audio>` host also accepts the attributes its native element understands, such as `controls`, `muted`, and `crossorigin`. Ones the adapter can set go through the adapter; the rest are copied onto the inner element. An `<iframe>` host accepts only what its adapter declares, since nothing is mirrored onto the frame.
+
+```ts
+class LowLatencyAdapter extends HTMLVideoAdapter {
+  static readonly host = 'video';
+  static readonly defaultProps = { src: '', debug: false, latencyMode: 'normal' };
+}
+
+customElements.define('ll-video', createMediaElement(LowLatencyAdapter));
+// <ll-video src="…" debug latency-mode="low" controls></ll-video>
+// `debug` and `latency-mode` reach the adapter; `controls` reaches the <video>.
+```
+
 Every built-in media element except `<wistia-video>` and `<background-video>` is created this way. Subclass the result to add element behavior, such as extra observed attributes.
 
 ## Who needs this

From e3ad1a6d444649adb918eb6e1080346d9aa9cff2 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 22:57:31 -0700
Subject: [PATCH 14/25] fix(site): type the media element fixtures for astro
 check

The fixture stub asked for an adapter with `host` and `defaultProps`; the
fixture base adapters only had `host` where the builder needed it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/dom/custom-media-element/custom-media-element.ts      | 2 +-
 .../monorepo/packages/media/src/dom/simple/adapter.ts         | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
index d0e748412f..e01e963627 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -8,7 +8,7 @@ import { commonTemplate, videoTemplate } from './templates';
 
 // Stub — the builder parses the AST, it doesn't run the code.
 // Mirrors the real CustomMediaElement factory signature: the target is the adapter's static `host`.
-export function CustomMediaElement(Adapter: { readonly host: 'video' | 'audio' | 'iframe'; readonly defaultProps: object }) {
+export function CustomMediaElement(Adapter: { readonly host: 'video' | 'audio' | 'iframe'; readonly defaultProps?: object }) {
   class CustomMedia {
     static template = Adapter.host === 'video' ? videoTemplate : commonTemplate(Adapter.host);
     static shadowRootOptions = { mode: 'open' };
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
index 073e2d1b1b..7e97c991d7 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/media/src/dom/simple/adapter.ts
@@ -9,6 +9,8 @@
 
 // Stub — the builder walks the prototype chain and stops here.
 export class HTMLVideoAdapter {
+  static readonly host = 'video';
+
   attach(_target: EventTarget): void {}
   detach(): void {}
   destroy(): void {}
@@ -16,6 +18,8 @@ export class HTMLVideoAdapter {
 
 // Stub — audio counterpart, also a prototype-chain stop.
 export class HTMLAudioAdapter {
+  static readonly host = 'audio';
+
   attach(_target: EventTarget): void {}
   detach(): void {}
   destroy(): void {}

From bad86dfe91bea6076a544031d3be6351894b1431 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 23:05:40 -0700
Subject: [PATCH 15/25] docs(site): do not link the React factory page before
 it exists

The `create-media-component` reference lands in #2604, so linking it here
broke the site build for this PR alone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 site/src/content/docs/reference/create-media-element.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index 3cc051bb88..7e367853cf 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -43,7 +43,7 @@ The template is also the element's static `template`, so a subclass can override
 
 ## Attributes
 
-Each primitive in the adapter's `defaultProps` becomes a content attribute of the same type, named by its WHATWG spelling where one exists and kebab-case otherwise: `src`, `preload`, `stream-type`. Removing the attribute resets the property to its default. Object properties such as `source` are property-only. This is the rule <DocsLink slug="reference/create-media-component">createMediaComponent</DocsLink> applies to React props, so both façades expose the same surface from one declaration.
+Each primitive in the adapter's `defaultProps` becomes a content attribute of the same type, named by its WHATWG spelling where one exists and kebab-case otherwise: `src`, `preload`, `stream-type`. Removing the attribute resets the property to its default. Object properties such as `source` are property-only. This is the rule the React `createMediaComponent` factory applies to props, so both façades expose the same surface from one declaration.
 
 A `<video>` or `<audio>` host also accepts the attributes its native element understands, such as `controls`, `muted`, and `crossorigin`. Ones the adapter can set go through the adapter; the rest are copied onto the inner element. An `<iframe>` host accepts only what its adapter declares, since nothing is mirrored onto the frame.
 

From 55eda8dc550aaf8f16f8bdc1b49b5ec0826febde Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 00:01:22 -0700
Subject: [PATCH 16/25] refactor(html)!: name media elements *Element in
 element.ts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The html façades follow the UI elements: `media/<name>/element.ts` exports
`<Name>Element` carrying its static `tagName`, and the define entry only
registers it. `<mux-background-video>` is a subclass of
`HlsBackgroundVideoElement` with its own tag, since one class can hold one
tag name.

BREAKING CHANGE: `HlsJsVideo`, `SpotifyAudio`, and the other html media
classes are now `HlsJsVideoElement`, `SpotifyAudioElement`, and so on, and
declare their own `tagName`. `@videojs/html/media/<name>` keeps exporting the
element class.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../references/workflow.md                    |  2 +-
 .../spf/use-cases/audio-only-mode-override.md |  4 ++--
 .../html/src/define/media/background-video.ts |  8 +++----
 .../html/src/define/media/cloudflare-video.ts |  8 +++----
 packages/html/src/define/media/dash-video.ts  |  9 +++-----
 packages/html/src/define/media/hls-audio.ts   |  8 +++----
 .../src/define/media/hls-background-video.ts  |  8 +++----
 packages/html/src/define/media/hls-video.ts   |  9 +++-----
 packages/html/src/define/media/hlsjs-video.ts |  9 +++-----
 .../html/src/define/media/mux-audio/hls-js.ts |  8 +++----
 .../html/src/define/media/mux-audio/spf.ts    |  8 +++----
 .../src/define/media/mux-background-video.ts  | 14 +++--------
 .../html/src/define/media/mux-video/hls-js.ts |  8 +++----
 .../html/src/define/media/mux-video/spf.ts    |  8 +++----
 .../html/src/define/media/native-hls-video.ts |  9 +++-----
 packages/html/src/define/media/shaka-video.ts |  8 +++----
 .../html/src/define/media/spotify-audio.ts    |  8 +++----
 .../html/src/define/media/tiktok-video.ts     |  8 +++----
 .../html/src/define/media/twitch-video.ts     |  8 +++----
 packages/html/src/define/media/vimeo-video.ts |  8 +++----
 .../html/src/define/media/wistia-video.ts     |  8 +++----
 .../html/src/define/media/youtube-video.ts    |  8 +++----
 .../src/define/tests/media-aliases.test.ts    |  8 +++----
 .../{adapter.ts => element.ts}                |  6 +++--
 .../html/src/media/background-video/index.ts  |  2 +-
 .../tests/background-video.test.ts            |  8 +++----
 .../{adapter.ts => element.ts}                |  4 +++-
 .../html/src/media/cloudflare-video/index.ts  |  2 +-
 packages/html/src/media/dash-video/adapter.ts |  5 ----
 packages/html/src/media/dash-video/element.ts |  8 +++++++
 packages/html/src/media/dash-video/index.ts   |  2 +-
 .../hls-audio/{adapter.ts => element.ts}      |  4 +++-
 packages/html/src/media/hls-audio/index.ts    |  2 +-
 .../{adapter.ts => element.ts}                |  6 +++--
 .../src/media/hls-background-video/index.ts   |  2 +-
 .../{adapter.test.ts => element.test.ts}      | 23 ++++++++++---------
 .../hls-video/{adapter.ts => element.ts}      |  4 +++-
 packages/html/src/media/hls-video/index.ts    |  2 +-
 .../html/src/media/hlsjs-video/adapter.ts     |  5 ----
 .../html/src/media/hlsjs-video/element.ts     |  7 ++++++
 packages/html/src/media/hlsjs-video/index.ts  |  2 +-
 packages/html/src/media/mux-audio/hls-js.ts   |  4 +++-
 packages/html/src/media/mux-audio/spf.ts      |  4 +++-
 .../src/media/mux-background-video/element.ts | 17 ++++++++++++++
 .../src/media/mux-background-video/index.ts   | 12 +---------
 packages/html/src/media/mux-video/hls-js.ts   |  4 +++-
 packages/html/src/media/mux-video/spf.ts      |  4 +++-
 .../src/media/native-hls-video/adapter.ts     |  5 ----
 .../src/media/native-hls-video/element.ts     |  7 ++++++
 .../html/src/media/native-hls-video/index.ts  |  2 +-
 .../html/src/media/shaka-video/adapter.ts     |  5 ----
 .../html/src/media/shaka-video/element.ts     |  7 ++++++
 packages/html/src/media/shaka-video/index.ts  |  2 +-
 .../spotify-audio/{adapter.ts => element.ts}  |  4 +++-
 .../html/src/media/spotify-audio/index.ts     |  2 +-
 .../html/src/media/tests/mux-video.test.ts    |  8 +++----
 .../src/media/tests/spotify-audio.test.ts     |  6 ++---
 .../html/src/media/tests/tiktok-video.test.ts | 14 +++++------
 .../html/src/media/tests/vimeo-video.test.ts  |  6 ++---
 .../tiktok-video/{adapter.ts => element.ts}   |  4 +++-
 packages/html/src/media/tiktok-video/index.ts |  2 +-
 .../twitch-video/{adapter.ts => element.ts}   |  4 +++-
 packages/html/src/media/twitch-video/index.ts |  2 +-
 .../vimeo-video/{adapter.ts => element.ts}    |  4 +++-
 packages/html/src/media/vimeo-video/index.ts  |  2 +-
 .../wistia-video/{adapter.ts => element.ts}   |  4 +++-
 packages/html/src/media/wistia-video/index.ts |  2 +-
 .../youtube-video/{adapter.ts => element.ts}  |  4 +++-
 .../html/src/media/youtube-video/index.ts     |  2 +-
 .../src/player/tests/create-player.test.ts    |  4 ++--
 .../docs/reference/create-media-element.mdx   |  8 ++++---
 71 files changed, 216 insertions(+), 217 deletions(-)
 rename packages/html/src/media/background-video/{adapter.ts => element.ts} (91%)
 rename packages/html/src/media/cloudflare-video/{adapter.ts => element.ts} (91%)
 delete mode 100644 packages/html/src/media/dash-video/adapter.ts
 create mode 100644 packages/html/src/media/dash-video/element.ts
 rename packages/html/src/media/hls-audio/{adapter.ts => element.ts} (50%)
 rename packages/html/src/media/hls-background-video/{adapter.ts => element.ts} (96%)
 rename packages/html/src/media/hls-background-video/tests/{adapter.test.ts => element.test.ts} (86%)
 rename packages/html/src/media/hls-video/{adapter.ts => element.ts} (50%)
 delete mode 100644 packages/html/src/media/hlsjs-video/adapter.ts
 create mode 100644 packages/html/src/media/hlsjs-video/element.ts
 create mode 100644 packages/html/src/media/mux-background-video/element.ts
 delete mode 100644 packages/html/src/media/native-hls-video/adapter.ts
 create mode 100644 packages/html/src/media/native-hls-video/element.ts
 delete mode 100644 packages/html/src/media/shaka-video/adapter.ts
 create mode 100644 packages/html/src/media/shaka-video/element.ts
 rename packages/html/src/media/spotify-audio/{adapter.ts => element.ts} (92%)
 rename packages/html/src/media/tiktok-video/{adapter.ts => element.ts} (94%)
 rename packages/html/src/media/twitch-video/{adapter.ts => element.ts} (92%)
 rename packages/html/src/media/vimeo-video/{adapter.ts => element.ts} (91%)
 rename packages/html/src/media/wistia-video/{adapter.ts => element.ts} (74%)
 rename packages/html/src/media/youtube-video/{adapter.ts => element.ts} (91%)

diff --git a/.agents/skills/implement-spf-use-case/references/workflow.md b/.agents/skills/implement-spf-use-case/references/workflow.md
index d9dda7047e..f41de7c964 100644
--- a/.agents/skills/implement-spf-use-case/references/workflow.md
+++ b/.agents/skills/implement-spf-use-case/references/workflow.md
@@ -442,7 +442,7 @@ typical for use-case implementations:
   applying the SPF mixin to `HTMLVideoAdapter` (or audio host for
   audio-only variants), exported through the adjacent `index.ts`; ~5 LOC.
 - **HTML custom element + define entry + CDN entry** —
-  `packages/html/src/media/<key>-video/adapter.ts`,
+  `packages/html/src/media/<key>-video/element.ts`,
   `packages/html/src/define/media/<key>-video.ts`,
   `packages/cdn/src/media/<key>-video.ts`. Inline implementation;
   ~5 LOC + boilerplate.
diff --git a/internal/design/spf/use-cases/audio-only-mode-override.md b/internal/design/spf/use-cases/audio-only-mode-override.md
index 770d6e4ee8..85a1f68624 100644
--- a/internal/design/spf/use-cases/audio-only-mode-override.md
+++ b/internal/design/spf/use-cases/audio-only-mode-override.md
@@ -311,7 +311,7 @@ Public re-export: `@videojs/spf/hls-audio`.
 
 | Export | File | Purpose |
 |---|---|---|
-| `HlsAudio` | `media/hls-audio/adapter.ts` | Applies `MediaAttachMixin` + `CustomMediaElement(HlsAudioAdapter)`; the `<audio>` target comes from the adapter's static `host` |
+| `HlsAudioElement` | `media/hls-audio/element.ts` | Applies `MediaAttachMixin` + `CustomMediaElement(HlsAudioAdapter)`; the `<audio>` target comes from the adapter's static `host` |
 | `HlsAudioElement` (tag `hls-audio`) | `media/hls-audio/element.ts` | Custom-element implementation; `define/media/hls-audio.ts` registers it via `safeDefine` |
 
 CDN entry: `packages/html/src/define/media/hls-audio.ts` →
@@ -416,7 +416,7 @@ configuration drives end-of-stream correctly with no per-type changes.
 - [`packages/spf/src/playback/engines/hls/tests/engine-audio-only.test.ts`](../../../../packages/spf/src/playback/engines/hls/tests/engine-audio-only.test.ts) — Phase 1 engine integration tests
 - [`packages/spf/src/playback/adapters/hls-audio/tests/mixin.test.ts`](../../../../packages/spf/src/playback/adapters/hls-audio/tests/mixin.test.ts) — Phase 1 adapter tests
 - [`packages/spf/src/playback/adapters/hls-audio/adapter.ts`](../../../../packages/spf/src/playback/adapters/hls-audio/adapter.ts) — Phase 1 media wrapper
-- [`packages/html/src/media/hls-audio/adapter.ts`](../../../../packages/html/src/media/hls-audio/adapter.ts) — Phase 1 HTML custom element
+- [`packages/html/src/media/hls-audio/element.ts`](../../../../packages/html/src/media/hls-audio/element.ts) — Phase 1 HTML custom element
 - [`packages/react/src/media/hls-audio/adapter.tsx`](../../../../packages/react/src/media/hls-audio/adapter.tsx) — Phase 1 React component
 - [`apps/sandbox/templates/html-hls-audio/`](../../../../apps/sandbox/templates/html-hls-audio/) — Phase 1 HTML sandbox demo template
 - [`apps/sandbox/templates/react-hls-audio/`](../../../../apps/sandbox/templates/react-hls-audio/) — Phase 1 React sandbox demo template
diff --git a/packages/html/src/define/media/background-video.ts b/packages/html/src/define/media/background-video.ts
index 9287765a77..4bb15d36ae 100644
--- a/packages/html/src/define/media/background-video.ts
+++ b/packages/html/src/define/media/background-video.ts
@@ -1,12 +1,10 @@
-import { BackgroundVideo } from '../../media/background-video';
+import { BackgroundVideoElement } from '../../media/background-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class BackgroundVideoElement extends BackgroundVideo {
-  static readonly tagName = 'background-video';
-}
-
 safeDefine(BackgroundVideoElement);
 
+export { BackgroundVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [BackgroundVideoElement.tagName]: BackgroundVideoElement;
diff --git a/packages/html/src/define/media/cloudflare-video.ts b/packages/html/src/define/media/cloudflare-video.ts
index 2a4841b0c6..a794fa0356 100644
--- a/packages/html/src/define/media/cloudflare-video.ts
+++ b/packages/html/src/define/media/cloudflare-video.ts
@@ -1,12 +1,10 @@
-import { CloudflareVideo } from '../../media/cloudflare-video';
+import { CloudflareVideoElement } from '../../media/cloudflare-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class CloudflareVideoElement extends CloudflareVideo {
-  static readonly tagName = 'cloudflare-video';
-}
-
 safeDefine(CloudflareVideoElement);
 
+export { CloudflareVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [CloudflareVideoElement.tagName]: CloudflareVideoElement;
diff --git a/packages/html/src/define/media/dash-video.ts b/packages/html/src/define/media/dash-video.ts
index 831cdb6a4a..ab9fdc74e0 100644
--- a/packages/html/src/define/media/dash-video.ts
+++ b/packages/html/src/define/media/dash-video.ts
@@ -1,13 +1,10 @@
-import { DashVideo } from '../../media/dash-video';
+import { DashVideoElement } from '../../media/dash-video';
 import { safeDefine } from '../../registration/safe-define';
 
-/** MPEG-DASH media element powered by dash.js and registered as `<dash-video>`. */
-export class DashVideoElement extends DashVideo {
-  static readonly tagName = 'dash-video';
-}
-
 safeDefine(DashVideoElement);
 
+export { DashVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [DashVideoElement.tagName]: DashVideoElement;
diff --git a/packages/html/src/define/media/hls-audio.ts b/packages/html/src/define/media/hls-audio.ts
index d12494efda..ed64481f4d 100644
--- a/packages/html/src/define/media/hls-audio.ts
+++ b/packages/html/src/define/media/hls-audio.ts
@@ -1,12 +1,10 @@
-import { HlsAudio } from '../../media/hls-audio';
+import { HlsAudioElement } from '../../media/hls-audio';
 import { safeDefine } from '../../registration/safe-define';
 
-export class HlsAudioElement extends HlsAudio {
-  static readonly tagName = 'hls-audio';
-}
-
 safeDefine(HlsAudioElement);
 
+export { HlsAudioElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [HlsAudioElement.tagName]: HlsAudioElement;
diff --git a/packages/html/src/define/media/hls-background-video.ts b/packages/html/src/define/media/hls-background-video.ts
index 5136844deb..ad57323475 100644
--- a/packages/html/src/define/media/hls-background-video.ts
+++ b/packages/html/src/define/media/hls-background-video.ts
@@ -1,12 +1,10 @@
-import { HlsBackgroundVideo } from '../../media/hls-background-video';
+import { HlsBackgroundVideoElement } from '../../media/hls-background-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class HlsBackgroundVideoElement extends HlsBackgroundVideo {
-  static readonly tagName = 'hls-background-video';
-}
-
 safeDefine(HlsBackgroundVideoElement);
 
+export { HlsBackgroundVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [HlsBackgroundVideoElement.tagName]: HlsBackgroundVideoElement;
diff --git a/packages/html/src/define/media/hls-video.ts b/packages/html/src/define/media/hls-video.ts
index 4d8fc35410..d52ae89613 100644
--- a/packages/html/src/define/media/hls-video.ts
+++ b/packages/html/src/define/media/hls-video.ts
@@ -1,13 +1,10 @@
-import { HlsVideo } from '../../media/hls-video';
+import { HlsVideoElement } from '../../media/hls-video';
 import { safeDefine } from '../../registration/safe-define';
 
-/** Lightweight SPF-backed HLS media element registered as `<hls-video>`. */
-export class HlsVideoElement extends HlsVideo {
-  static readonly tagName = 'hls-video';
-}
-
 safeDefine(HlsVideoElement);
 
+export { HlsVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [HlsVideoElement.tagName]: HlsVideoElement;
diff --git a/packages/html/src/define/media/hlsjs-video.ts b/packages/html/src/define/media/hlsjs-video.ts
index bf15315b68..e9e014965a 100644
--- a/packages/html/src/define/media/hlsjs-video.ts
+++ b/packages/html/src/define/media/hlsjs-video.ts
@@ -1,13 +1,10 @@
-import { HlsJsVideo } from '../../media/hlsjs-video';
+import { HlsJsVideoElement } from '../../media/hlsjs-video';
 import { safeDefine } from '../../registration/safe-define';
 
-/** Cross-browser HLS media element powered by hls.js and registered as `<hlsjs-video>`. */
-export class HlsJsVideoElement extends HlsJsVideo {
-  static readonly tagName = 'hlsjs-video';
-}
-
 safeDefine(HlsJsVideoElement);
 
+export { HlsJsVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [HlsJsVideoElement.tagName]: HlsJsVideoElement;
diff --git a/packages/html/src/define/media/mux-audio/hls-js.ts b/packages/html/src/define/media/mux-audio/hls-js.ts
index 2e78202a88..3af503461e 100644
--- a/packages/html/src/define/media/mux-audio/hls-js.ts
+++ b/packages/html/src/define/media/mux-audio/hls-js.ts
@@ -1,12 +1,10 @@
-import { MuxAudio } from '../../../media/mux-audio/hls-js';
+import { MuxAudioElement } from '../../../media/mux-audio/hls-js';
 import { safeDefine } from '../../../registration/safe-define';
 
-export class MuxAudioElement extends MuxAudio {
-  static readonly tagName = 'mux-audio';
-}
-
 safeDefine(MuxAudioElement);
 
+export { MuxAudioElement };
+
 declare global {
   /** The Mux audio flavors in the build — see `../mux-video/spf` for why. */
   interface MuxAudioFlavors {
diff --git a/packages/html/src/define/media/mux-audio/spf.ts b/packages/html/src/define/media/mux-audio/spf.ts
index 42dcf8d91f..1deee9d7df 100644
--- a/packages/html/src/define/media/mux-audio/spf.ts
+++ b/packages/html/src/define/media/mux-audio/spf.ts
@@ -1,12 +1,10 @@
-import { MuxAudio } from '../../../media/mux-audio/spf';
+import { MuxAudioElement } from '../../../media/mux-audio/spf';
 import { safeDefine } from '../../../registration/safe-define';
 
-export class MuxAudioElement extends MuxAudio {
-  static readonly tagName = 'mux-audio';
-}
-
 safeDefine(MuxAudioElement);
 
+export { MuxAudioElement };
+
 declare global {
   /** The Mux audio flavors in the build — see `../mux-video/spf` for why. */
   interface MuxAudioFlavors {
diff --git a/packages/html/src/define/media/mux-background-video.ts b/packages/html/src/define/media/mux-background-video.ts
index efe415451e..413786d6fc 100644
--- a/packages/html/src/define/media/mux-background-video.ts
+++ b/packages/html/src/define/media/mux-background-video.ts
@@ -1,18 +1,10 @@
-import { MuxBackgroundVideo } from '../../media/mux-background-video';
+import { MuxBackgroundVideoElement } from '../../media/mux-background-video';
 import { safeDefine } from '../../registration/safe-define';
 
-/**
- * `<mux-background-video>` — the Mux-flavored tag for `<hls-background-video>`.
- *
- * A distinct subclass rather than a re-export because a custom-element class can hold one tag name: registering the
- * same class twice throws. The behavior is entirely the shared base's.
- */
-export class MuxBackgroundVideoElement extends MuxBackgroundVideo {
-  static readonly tagName = 'mux-background-video';
-}
-
 safeDefine(MuxBackgroundVideoElement);
 
+export { MuxBackgroundVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [MuxBackgroundVideoElement.tagName]: MuxBackgroundVideoElement;
diff --git a/packages/html/src/define/media/mux-video/hls-js.ts b/packages/html/src/define/media/mux-video/hls-js.ts
index 326fbdfdec..5b8570e933 100644
--- a/packages/html/src/define/media/mux-video/hls-js.ts
+++ b/packages/html/src/define/media/mux-video/hls-js.ts
@@ -1,12 +1,10 @@
-import { MuxVideo } from '../../../media/mux-video/hls-js';
+import { MuxVideoElement } from '../../../media/mux-video/hls-js';
 import { safeDefine } from '../../../registration/safe-define';
 
-export class MuxVideoElement extends MuxVideo {
-  static readonly tagName = 'mux-video';
-}
-
 safeDefine(MuxVideoElement);
 
+export { MuxVideoElement };
+
 declare global {
   /** The Mux video flavors in the build — see `./spf` for why. */
   interface MuxVideoFlavors {
diff --git a/packages/html/src/define/media/mux-video/spf.ts b/packages/html/src/define/media/mux-video/spf.ts
index 0f5132425b..6f0b0b5b8e 100644
--- a/packages/html/src/define/media/mux-video/spf.ts
+++ b/packages/html/src/define/media/mux-video/spf.ts
@@ -1,12 +1,10 @@
-import { MuxVideo } from '../../../media/mux-video/spf';
+import { MuxVideoElement } from '../../../media/mux-video/spf';
 import { safeDefine } from '../../../registration/safe-define';
 
-export class MuxVideoElement extends MuxVideo {
-  static readonly tagName = 'mux-video';
-}
-
 safeDefine(MuxVideoElement);
 
+export { MuxVideoElement };
+
 declare global {
   /**
    * The Mux video flavors in the build, keyed by engine.
diff --git a/packages/html/src/define/media/native-hls-video.ts b/packages/html/src/define/media/native-hls-video.ts
index c47d0c7a0f..f4df0fb50b 100644
--- a/packages/html/src/define/media/native-hls-video.ts
+++ b/packages/html/src/define/media/native-hls-video.ts
@@ -1,13 +1,10 @@
-import { NativeHlsVideo } from '../../media/native-hls-video';
+import { NativeHlsVideoElement } from '../../media/native-hls-video';
 import { safeDefine } from '../../registration/safe-define';
 
-/** Browser-native HLS media element registered as `<native-hls-video>`. */
-export class NativeHlsVideoElement extends NativeHlsVideo {
-  static readonly tagName = 'native-hls-video';
-}
-
 safeDefine(NativeHlsVideoElement);
 
+export { NativeHlsVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [NativeHlsVideoElement.tagName]: NativeHlsVideoElement;
diff --git a/packages/html/src/define/media/shaka-video.ts b/packages/html/src/define/media/shaka-video.ts
index 69119b7696..114b872ec5 100644
--- a/packages/html/src/define/media/shaka-video.ts
+++ b/packages/html/src/define/media/shaka-video.ts
@@ -1,12 +1,10 @@
-import { ShakaVideo } from '../../media/shaka-video';
+import { ShakaVideoElement } from '../../media/shaka-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class ShakaVideoElement extends ShakaVideo {
-  static readonly tagName = 'shaka-video';
-}
-
 safeDefine(ShakaVideoElement);
 
+export { ShakaVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [ShakaVideoElement.tagName]: ShakaVideoElement;
diff --git a/packages/html/src/define/media/spotify-audio.ts b/packages/html/src/define/media/spotify-audio.ts
index ae91640856..fdcc3fe446 100644
--- a/packages/html/src/define/media/spotify-audio.ts
+++ b/packages/html/src/define/media/spotify-audio.ts
@@ -1,12 +1,10 @@
-import { SpotifyAudio } from '../../media/spotify-audio';
+import { SpotifyAudioElement } from '../../media/spotify-audio';
 import { safeDefine } from '../../registration/safe-define';
 
-export class SpotifyAudioElement extends SpotifyAudio {
-  static readonly tagName = 'spotify-audio';
-}
-
 safeDefine(SpotifyAudioElement);
 
+export { SpotifyAudioElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [SpotifyAudioElement.tagName]: SpotifyAudioElement;
diff --git a/packages/html/src/define/media/tiktok-video.ts b/packages/html/src/define/media/tiktok-video.ts
index be66d38973..92098381b1 100644
--- a/packages/html/src/define/media/tiktok-video.ts
+++ b/packages/html/src/define/media/tiktok-video.ts
@@ -1,12 +1,10 @@
-import { TikTokVideo } from '../../media/tiktok-video';
+import { TikTokVideoElement } from '../../media/tiktok-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class TikTokVideoElement extends TikTokVideo {
-  static readonly tagName = 'tiktok-video';
-}
-
 safeDefine(TikTokVideoElement);
 
+export { TikTokVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [TikTokVideoElement.tagName]: TikTokVideoElement;
diff --git a/packages/html/src/define/media/twitch-video.ts b/packages/html/src/define/media/twitch-video.ts
index caf8dc7e17..6abd454e29 100644
--- a/packages/html/src/define/media/twitch-video.ts
+++ b/packages/html/src/define/media/twitch-video.ts
@@ -1,12 +1,10 @@
-import { TwitchVideo } from '../../media/twitch-video';
+import { TwitchVideoElement } from '../../media/twitch-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class TwitchVideoElement extends TwitchVideo {
-  static readonly tagName = 'twitch-video';
-}
-
 safeDefine(TwitchVideoElement);
 
+export { TwitchVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [TwitchVideoElement.tagName]: TwitchVideoElement;
diff --git a/packages/html/src/define/media/vimeo-video.ts b/packages/html/src/define/media/vimeo-video.ts
index 87d0d77894..c4f73069c4 100644
--- a/packages/html/src/define/media/vimeo-video.ts
+++ b/packages/html/src/define/media/vimeo-video.ts
@@ -1,12 +1,10 @@
-import { VimeoVideo } from '../../media/vimeo-video';
+import { VimeoVideoElement } from '../../media/vimeo-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class VimeoVideoElement extends VimeoVideo {
-  static readonly tagName = 'vimeo-video';
-}
-
 safeDefine(VimeoVideoElement);
 
+export { VimeoVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [VimeoVideoElement.tagName]: VimeoVideoElement;
diff --git a/packages/html/src/define/media/wistia-video.ts b/packages/html/src/define/media/wistia-video.ts
index e4244415ea..840d780112 100644
--- a/packages/html/src/define/media/wistia-video.ts
+++ b/packages/html/src/define/media/wistia-video.ts
@@ -1,12 +1,10 @@
-import { WistiaVideo } from '../../media/wistia-video';
+import { WistiaVideoElement } from '../../media/wistia-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class WistiaVideoElement extends WistiaVideo {
-  static readonly tagName = 'wistia-video';
-}
-
 safeDefine(WistiaVideoElement);
 
+export { WistiaVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [WistiaVideoElement.tagName]: WistiaVideoElement;
diff --git a/packages/html/src/define/media/youtube-video.ts b/packages/html/src/define/media/youtube-video.ts
index 2a325746af..6a7a451ac7 100644
--- a/packages/html/src/define/media/youtube-video.ts
+++ b/packages/html/src/define/media/youtube-video.ts
@@ -1,12 +1,10 @@
-import { YouTubeVideo } from '../../media/youtube-video';
+import { YouTubeVideoElement } from '../../media/youtube-video';
 import { safeDefine } from '../../registration/safe-define';
 
-export class YouTubeVideoElement extends YouTubeVideo {
-  static readonly tagName = 'youtube-video';
-}
-
 safeDefine(YouTubeVideoElement);
 
+export { YouTubeVideoElement };
+
 declare global {
   interface HTMLElementTagNameMap {
     [YouTubeVideoElement.tagName]: YouTubeVideoElement;
diff --git a/packages/html/src/define/tests/media-aliases.test.ts b/packages/html/src/define/tests/media-aliases.test.ts
index a2c9bc0ae1..acb91101d6 100644
--- a/packages/html/src/define/tests/media-aliases.test.ts
+++ b/packages/html/src/define/tests/media-aliases.test.ts
@@ -7,7 +7,6 @@
  */
 import { describe, expect, it } from 'vite-plus/test';
 
-import { HlsBackgroundVideo } from '../../media/hls-background-video';
 import { HlsBackgroundVideoElement } from '../media/hls-background-video';
 import { MuxBackgroundVideoElement } from '../media/mux-background-video';
 
@@ -17,9 +16,10 @@ describe('background-video alias tags', () => {
     expect(customElements.get('mux-background-video')).toBe(MuxBackgroundVideoElement);
   });
 
-  it('registers distinct subclasses of the one shared base', () => {
+  it('registers the alias as a subclass of the shared element', () => {
     expect(MuxBackgroundVideoElement).not.toBe(HlsBackgroundVideoElement);
-    expect(Object.getPrototypeOf(HlsBackgroundVideoElement)).toBe(HlsBackgroundVideo);
-    expect(Object.getPrototypeOf(MuxBackgroundVideoElement)).toBe(HlsBackgroundVideo);
+    expect(Object.getPrototypeOf(MuxBackgroundVideoElement)).toBe(HlsBackgroundVideoElement);
+    expect(MuxBackgroundVideoElement.tagName).toBe('mux-background-video');
+    expect(HlsBackgroundVideoElement.tagName).toBe('hls-background-video');
   });
 });
diff --git a/packages/html/src/media/background-video/adapter.ts b/packages/html/src/media/background-video/element.ts
similarity index 91%
rename from packages/html/src/media/background-video/adapter.ts
rename to packages/html/src/media/background-video/element.ts
index 042aa4ff22..c016bbd612 100644
--- a/packages/html/src/media/background-video/adapter.ts
+++ b/packages/html/src/media/background-video/element.ts
@@ -8,7 +8,9 @@ const HTMLElementBase = globalThis.HTMLElement ?? class {};
 
 // Not a `CustomMediaElement`: a background video has no adapter and needs one attribute, not the full media API. It
 // renders through the same `renderHost` the media elements use.
-export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
+export class BackgroundVideoElement extends MediaAttachMixin(HTMLElementBase) {
+  static readonly tagName = 'background-video';
+
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
   static template = backgroundVideoTemplate;
   static get observedAttributes() {
@@ -18,7 +20,7 @@ export class BackgroundVideo extends MediaAttachMixin(HTMLElementBase) {
   constructor() {
     super();
 
-    const ctor = this.constructor as typeof BackgroundVideo;
+    const ctor = this.constructor as typeof BackgroundVideoElement;
 
     renderHost(
       this,
diff --git a/packages/html/src/media/background-video/index.ts b/packages/html/src/media/background-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/background-video/index.ts
+++ b/packages/html/src/media/background-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/background-video/tests/background-video.test.ts b/packages/html/src/media/background-video/tests/background-video.test.ts
index 104a5de765..686d919051 100644
--- a/packages/html/src/media/background-video/tests/background-video.test.ts
+++ b/packages/html/src/media/background-video/tests/background-video.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from 'vite-plus/test';
 
-import { BackgroundVideo } from '../index';
+import { BackgroundVideoElement } from '../index';
 
 afterEach(() => {
   document.body.innerHTML = '';
@@ -11,7 +11,7 @@ let tagCounter = 0;
 function defineElement() {
   const tag = `test-background-video-${++tagCounter}`;
 
-  customElements.define(tag, class extends BackgroundVideo {});
+  customElements.define(tag, class extends BackgroundVideoElement {});
   return tag;
 }
 
@@ -31,7 +31,7 @@ function create(tag: string, attrs: Record<string, string> = {}): Element {
   return container.querySelector(tag)!;
 }
 
-describe('BackgroundVideo', () => {
+describe('BackgroundVideoElement', () => {
   describe('XSS prevention', () => {
     it('does not inject nodes when a whitelisted attribute value contains a quote breakout', () => {
       const tag = defineElement();
@@ -74,7 +74,7 @@ describe('BackgroundVideo', () => {
     it('preserves safe whitelisted attribute values correctly', () => {
       const tag = defineElement();
       // Test template generation directly — happy-dom may return null for IDL attrs (crossorigin) on shadow DOM elements.
-      const Ctor = customElements.get(tag) as typeof BackgroundVideo;
+      const Ctor = customElements.get(tag) as typeof BackgroundVideoElement;
       const attrs = {
         crossorigin: 'anonymous',
         preload: 'metadata',
diff --git a/packages/html/src/media/cloudflare-video/adapter.ts b/packages/html/src/media/cloudflare-video/element.ts
similarity index 91%
rename from packages/html/src/media/cloudflare-video/adapter.ts
rename to packages/html/src/media/cloudflare-video/element.ts
index 607233d511..d01775b599 100644
--- a/packages/html/src/media/cloudflare-video/adapter.ts
+++ b/packages/html/src/media/cloudflare-video/element.ts
@@ -51,4 +51,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class CloudflareVideo extends createMediaElement(CloudflareAdapter, { template }) {}
+export class CloudflareVideoElement extends createMediaElement(CloudflareAdapter, { template }) {
+  static readonly tagName = 'cloudflare-video';
+}
diff --git a/packages/html/src/media/cloudflare-video/index.ts b/packages/html/src/media/cloudflare-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/cloudflare-video/index.ts
+++ b/packages/html/src/media/cloudflare-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/dash-video/adapter.ts b/packages/html/src/media/dash-video/adapter.ts
deleted file mode 100644
index 43590cc45d..0000000000
--- a/packages/html/src/media/dash-video/adapter.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { DashAdapter } from '@videojs/dash-video';
-
-import { createMediaElement } from '../create-media-element';
-
-export class DashVideo extends createMediaElement(DashAdapter) {}
diff --git a/packages/html/src/media/dash-video/element.ts b/packages/html/src/media/dash-video/element.ts
new file mode 100644
index 0000000000..16c1818364
--- /dev/null
+++ b/packages/html/src/media/dash-video/element.ts
@@ -0,0 +1,8 @@
+import { DashAdapter } from '@videojs/dash-video';
+
+import { createMediaElement } from '../create-media-element';
+
+/** MPEG-DASH media element powered by dash.js and registered as `<dash-video>`. */
+export class DashVideoElement extends createMediaElement(DashAdapter) {
+  static readonly tagName = 'dash-video';
+}
diff --git a/packages/html/src/media/dash-video/index.ts b/packages/html/src/media/dash-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/dash-video/index.ts
+++ b/packages/html/src/media/dash-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/hls-audio/adapter.ts b/packages/html/src/media/hls-audio/element.ts
similarity index 50%
rename from packages/html/src/media/hls-audio/adapter.ts
rename to packages/html/src/media/hls-audio/element.ts
index 4730ef7f3d..49cf7a63e5 100644
--- a/packages/html/src/media/hls-audio/adapter.ts
+++ b/packages/html/src/media/hls-audio/element.ts
@@ -2,4 +2,6 @@ import { HlsAudioAdapter } from '@videojs/spf/hls-audio';
 
 import { createMediaElement } from '../create-media-element';
 
-export class HlsAudio extends createMediaElement(HlsAudioAdapter) {}
+export class HlsAudioElement extends createMediaElement(HlsAudioAdapter) {
+  static readonly tagName = 'hls-audio';
+}
diff --git a/packages/html/src/media/hls-audio/index.ts b/packages/html/src/media/hls-audio/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/hls-audio/index.ts
+++ b/packages/html/src/media/hls-audio/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/hls-background-video/adapter.ts b/packages/html/src/media/hls-background-video/element.ts
similarity index 96%
rename from packages/html/src/media/hls-background-video/adapter.ts
rename to packages/html/src/media/hls-background-video/element.ts
index 49a4a24763..2e4c0dec31 100644
--- a/packages/html/src/media/hls-background-video/adapter.ts
+++ b/packages/html/src/media/hls-background-video/element.ts
@@ -49,7 +49,9 @@ const HlsBackgroundVideoBase = MediaAttachMixin(HTMLElementBase) as unknown as C
  */
 // Deliberately not `CustomMediaElement`, matching `<background-video>`: a
 // background video needs one property, not the full WHATWG media API.
-export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
+export class HlsBackgroundVideoElement extends HlsBackgroundVideoBase {
+  static readonly tagName = 'hls-background-video';
+
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
   static template = backgroundVideoTemplate;
 
@@ -63,7 +65,7 @@ export class HlsBackgroundVideo extends HlsBackgroundVideoBase {
   constructor() {
     super();
 
-    const ctor = this.constructor as typeof HlsBackgroundVideo;
+    const ctor = this.constructor as typeof HlsBackgroundVideoElement;
 
     renderHost(
       this,
diff --git a/packages/html/src/media/hls-background-video/index.ts b/packages/html/src/media/hls-background-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/hls-background-video/index.ts
+++ b/packages/html/src/media/hls-background-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/hls-background-video/tests/adapter.test.ts b/packages/html/src/media/hls-background-video/tests/element.test.ts
similarity index 86%
rename from packages/html/src/media/hls-background-video/tests/adapter.test.ts
rename to packages/html/src/media/hls-background-video/tests/element.test.ts
index 8e11cfa268..9d9c53000f 100644
--- a/packages/html/src/media/hls-background-video/tests/adapter.test.ts
+++ b/packages/html/src/media/hls-background-video/tests/element.test.ts
@@ -1,8 +1,8 @@
 import type { HlsBackgroundVideoAdapter } from '@videojs/spf/hls-background-video';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test';
 
-import { MuxBackgroundVideo } from '../../mux-background-video';
-import { HlsBackgroundVideo } from '../index';
+import { MuxBackgroundVideoElement } from '../../mux-background-video';
+import { HlsBackgroundVideoElement } from '../index';
 
 /** SVTA 2011 — no video track this environment can play. */
 const NO_SUPPORTED_VIDEO_TRACK = 2011;
@@ -27,12 +27,12 @@ let tagCounter = 0;
 function defineElement() {
   const tag = `test-hls-background-video-${++tagCounter}`;
 
-  customElements.define(tag, class extends HlsBackgroundVideo {});
+  customElements.define(tag, class extends HlsBackgroundVideoElement {});
   return tag;
 }
 
 // innerHTML on a connected container so attributes are present when the constructor runs.
-function create(tag: string, attrs: Record<string, string> = {}): HlsBackgroundVideo {
+function create(tag: string, attrs: Record<string, string> = {}): HlsBackgroundVideoElement {
   const container = document.createElement('div');
 
   document.body.appendChild(container);
@@ -41,17 +41,17 @@ function create(tag: string, attrs: Record<string, string> = {}): HlsBackgroundV
     .join('');
 
   container.innerHTML = `<${tag}${attrStr}></${tag}>`;
-  return container.querySelector(tag) as HlsBackgroundVideo;
+  return container.querySelector(tag) as HlsBackgroundVideoElement;
 }
 
 /** The Media the element registers, which is what the engine hangs off. */
-function mediaOf(element: HlsBackgroundVideo) {
+function mediaOf(element: HlsBackgroundVideoElement) {
   return element.getMediaTarget() as unknown as HlsBackgroundVideoAdapter;
 }
 
 const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
 
-describe('HlsBackgroundVideo', () => {
+describe('HlsBackgroundVideoElement', () => {
   it('renders a video into its shadow root', () => {
     const element = create(defineElement());
 
@@ -106,7 +106,7 @@ describe('HlsBackgroundVideo', () => {
     // `max-resolution` is a URL param, `preload` means nothing to an engine that
     // loads immediately, and `audio` / `debug` from the package this replaces are
     // gone for good.
-    expect(HlsBackgroundVideo.observedAttributes).toEqual(['src']);
+    expect(HlsBackgroundVideoElement.observedAttributes).toEqual(['src']);
   });
 
   // The engine's reported sequence is the only failure signal this composition
@@ -148,8 +148,9 @@ describe('HlsBackgroundVideo', () => {
     });
   });
 
-  it('is what <mux-background-video> resolves to', () => {
-    // An alias, so there is one implementation to test rather than two.
-    expect(MuxBackgroundVideo).toBe(HlsBackgroundVideo);
+  it('is what <mux-background-video> extends', () => {
+    // An alias tag over the same implementation, so there is one element to test rather than two.
+    expect(Object.getPrototypeOf(MuxBackgroundVideoElement)).toBe(HlsBackgroundVideoElement);
+    expect(MuxBackgroundVideoElement.tagName).toBe('mux-background-video');
   });
 });
diff --git a/packages/html/src/media/hls-video/adapter.ts b/packages/html/src/media/hls-video/element.ts
similarity index 50%
rename from packages/html/src/media/hls-video/adapter.ts
rename to packages/html/src/media/hls-video/element.ts
index 753be67d57..1474979b40 100644
--- a/packages/html/src/media/hls-video/adapter.ts
+++ b/packages/html/src/media/hls-video/element.ts
@@ -2,4 +2,6 @@ import { HlsVideoAdapter } from '@videojs/spf/hls-video';
 
 import { createMediaElement } from '../create-media-element';
 
-export class HlsVideo extends createMediaElement(HlsVideoAdapter) {}
+export class HlsVideoElement extends createMediaElement(HlsVideoAdapter) {
+  static readonly tagName = 'hls-video';
+}
diff --git a/packages/html/src/media/hls-video/index.ts b/packages/html/src/media/hls-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/hls-video/index.ts
+++ b/packages/html/src/media/hls-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/hlsjs-video/adapter.ts b/packages/html/src/media/hlsjs-video/adapter.ts
deleted file mode 100644
index fa508c939c..0000000000
--- a/packages/html/src/media/hlsjs-video/adapter.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { HlsJsAdapter } from '@videojs/hlsjs-video';
-
-import { createMediaElement } from '../create-media-element';
-
-export class HlsJsVideo extends createMediaElement(HlsJsAdapter) {}
diff --git a/packages/html/src/media/hlsjs-video/element.ts b/packages/html/src/media/hlsjs-video/element.ts
new file mode 100644
index 0000000000..4a34622913
--- /dev/null
+++ b/packages/html/src/media/hlsjs-video/element.ts
@@ -0,0 +1,7 @@
+import { HlsJsAdapter } from '@videojs/hlsjs-video';
+
+import { createMediaElement } from '../create-media-element';
+
+export class HlsJsVideoElement extends createMediaElement(HlsJsAdapter) {
+  static readonly tagName = 'hlsjs-video';
+}
diff --git a/packages/html/src/media/hlsjs-video/index.ts b/packages/html/src/media/hlsjs-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/hlsjs-video/index.ts
+++ b/packages/html/src/media/hlsjs-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/mux-audio/hls-js.ts b/packages/html/src/media/mux-audio/hls-js.ts
index 22b6550162..ef67ae391a 100644
--- a/packages/html/src/media/mux-audio/hls-js.ts
+++ b/packages/html/src/media/mux-audio/hls-js.ts
@@ -5,4 +5,6 @@ import { MuxAudioMixin } from './mixin';
 
 const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter));
 
-export class MuxAudio extends MuxAudioBase {}
+export class MuxAudioElement extends MuxAudioBase {
+  static readonly tagName = 'mux-audio';
+}
diff --git a/packages/html/src/media/mux-audio/spf.ts b/packages/html/src/media/mux-audio/spf.ts
index f8efd601f0..119de59931 100644
--- a/packages/html/src/media/mux-audio/spf.ts
+++ b/packages/html/src/media/mux-audio/spf.ts
@@ -15,4 +15,6 @@ const MuxAudioBase = MuxAudioMixin(createMediaElement(MuxAudioAdapter));
  * The engine underneath is the subtractive audio-only one, so only the audio renditions of the playback ID are fetched
  * — unlike the hls.js-backed flavor, which runs the full engine and downloads video renditions it never plays.
  */
-export class MuxAudio extends MuxAudioBase {}
+export class MuxAudioElement extends MuxAudioBase {
+  static readonly tagName = 'mux-audio';
+}
diff --git a/packages/html/src/media/mux-background-video/element.ts b/packages/html/src/media/mux-background-video/element.ts
new file mode 100644
index 0000000000..3461dc3152
--- /dev/null
+++ b/packages/html/src/media/mux-background-video/element.ts
@@ -0,0 +1,17 @@
+import { HlsBackgroundVideoElement } from '../hls-background-video';
+
+/**
+ * `<mux-background-video>` — the Mux-flavored name for `<hls-background-video>`. Kept because it is what the standalone
+ * package this element replaces was called.
+ *
+ * A subclass rather than a re-export because a custom-element class can hold one tag name: registering the same class
+ * twice throws. The behavior is entirely the shared base's. There is no Mux identity to add, because there is no Mux
+ * input to take: `src` is an HLS URL, and capping which rendition is fetched is a param on it rather than an
+ * attribute.
+ */
+// The base's `tagName` is a literal type, which a subclass cannot widen; the cast drops it from the static side.
+type HlsBackgroundVideoBase = Omit<typeof HlsBackgroundVideoElement, 'tagName'> & (new () => HlsBackgroundVideoElement);
+
+export class MuxBackgroundVideoElement extends (HlsBackgroundVideoElement as HlsBackgroundVideoBase) {
+  static readonly tagName = 'mux-background-video';
+}
diff --git a/packages/html/src/media/mux-background-video/index.ts b/packages/html/src/media/mux-background-video/index.ts
index ccb0c2e225..ef9f88ec65 100644
--- a/packages/html/src/media/mux-background-video/index.ts
+++ b/packages/html/src/media/mux-background-video/index.ts
@@ -1,11 +1 @@
-/**
- * The Mux-flavored name for `HlsBackgroundVideo` — the same class, not a subclass or a variant. Kept because
- * `<mux-background-video>` is what the standalone package this element replaces was called.
- *
- * There is no Mux identity to add, because there is no Mux input to take: `src` is an HLS URL, and capping which
- * rendition is fetched is a param on it rather than an attribute. `../hls-background-video` carries the whole surface.
- *
- * The two tags register from separate `define/media` entries, each subclassing this base with its own `tagName`, so
- * importing both is fine — they are two names for one element, not two elements competing for one name.
- */
-export { HlsBackgroundVideo as MuxBackgroundVideo } from '../hls-background-video';
+export * from './element';
diff --git a/packages/html/src/media/mux-video/hls-js.ts b/packages/html/src/media/mux-video/hls-js.ts
index 4fd7a11018..55b869f677 100644
--- a/packages/html/src/media/mux-video/hls-js.ts
+++ b/packages/html/src/media/mux-video/hls-js.ts
@@ -5,4 +5,6 @@ import { MuxVideoMixin } from './mixin';
 
 const MuxVideoBase = MuxVideoMixin(createMediaElement(MuxVideoAdapter));
 
-export class MuxVideo extends MuxVideoBase {}
+export class MuxVideoElement extends MuxVideoBase {
+  static readonly tagName = 'mux-video';
+}
diff --git a/packages/html/src/media/mux-video/spf.ts b/packages/html/src/media/mux-video/spf.ts
index 6c584e8eb8..7a8bacc008 100644
--- a/packages/html/src/media/mux-video/spf.ts
+++ b/packages/html/src/media/mux-video/spf.ts
@@ -12,4 +12,6 @@ const MuxVideoBase = MuxVideoMixin(createMediaElement(MuxVideoAdapter));
  * the surface moves. Deliberately not exported from this directory's barrel, so importing one flavor never pulls the
  * other's engine in with it.
  */
-export class MuxVideo extends MuxVideoBase {}
+export class MuxVideoElement extends MuxVideoBase {
+  static readonly tagName = 'mux-video';
+}
diff --git a/packages/html/src/media/native-hls-video/adapter.ts b/packages/html/src/media/native-hls-video/adapter.ts
deleted file mode 100644
index 5d09ccbe65..0000000000
--- a/packages/html/src/media/native-hls-video/adapter.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { NativeHlsAdapter } from '@videojs/native-hls-video';
-
-import { createMediaElement } from '../create-media-element';
-
-export class NativeHlsVideo extends createMediaElement(NativeHlsAdapter) {}
diff --git a/packages/html/src/media/native-hls-video/element.ts b/packages/html/src/media/native-hls-video/element.ts
new file mode 100644
index 0000000000..0af37952ec
--- /dev/null
+++ b/packages/html/src/media/native-hls-video/element.ts
@@ -0,0 +1,7 @@
+import { NativeHlsAdapter } from '@videojs/native-hls-video';
+
+import { createMediaElement } from '../create-media-element';
+
+export class NativeHlsVideoElement extends createMediaElement(NativeHlsAdapter) {
+  static readonly tagName = 'native-hls-video';
+}
diff --git a/packages/html/src/media/native-hls-video/index.ts b/packages/html/src/media/native-hls-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/native-hls-video/index.ts
+++ b/packages/html/src/media/native-hls-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/shaka-video/adapter.ts b/packages/html/src/media/shaka-video/adapter.ts
deleted file mode 100644
index 4aa2d74c17..0000000000
--- a/packages/html/src/media/shaka-video/adapter.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { ShakaAdapter } from '@videojs/shaka-video';
-
-import { createMediaElement } from '../create-media-element';
-
-export class ShakaVideo extends createMediaElement(ShakaAdapter) {}
diff --git a/packages/html/src/media/shaka-video/element.ts b/packages/html/src/media/shaka-video/element.ts
new file mode 100644
index 0000000000..ec34fabae9
--- /dev/null
+++ b/packages/html/src/media/shaka-video/element.ts
@@ -0,0 +1,7 @@
+import { ShakaAdapter } from '@videojs/shaka-video';
+
+import { createMediaElement } from '../create-media-element';
+
+export class ShakaVideoElement extends createMediaElement(ShakaAdapter) {
+  static readonly tagName = 'shaka-video';
+}
diff --git a/packages/html/src/media/shaka-video/index.ts b/packages/html/src/media/shaka-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/shaka-video/index.ts
+++ b/packages/html/src/media/shaka-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/spotify-audio/adapter.ts b/packages/html/src/media/spotify-audio/element.ts
similarity index 92%
rename from packages/html/src/media/spotify-audio/adapter.ts
rename to packages/html/src/media/spotify-audio/element.ts
index 69e8a3ebc6..5f5652b365 100644
--- a/packages/html/src/media/spotify-audio/adapter.ts
+++ b/packages/html/src/media/spotify-audio/element.ts
@@ -55,4 +55,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class SpotifyAudio extends createMediaElement(SpotifyAdapter, { template }) {}
+export class SpotifyAudioElement extends createMediaElement(SpotifyAdapter, { template }) {
+  static readonly tagName = 'spotify-audio';
+}
diff --git a/packages/html/src/media/spotify-audio/index.ts b/packages/html/src/media/spotify-audio/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/spotify-audio/index.ts
+++ b/packages/html/src/media/spotify-audio/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/tests/mux-video.test.ts b/packages/html/src/media/tests/mux-video.test.ts
index c670f8b095..d2cb9d0b17 100644
--- a/packages/html/src/media/tests/mux-video.test.ts
+++ b/packages/html/src/media/tests/mux-video.test.ts
@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, it } from 'vite-plus/test';
 
-import { MuxVideo } from '../mux-video';
+import { MuxVideoElement } from '../mux-video';
 
-customElements.define('test-mux-video', MuxVideo);
+customElements.define('test-mux-video', MuxVideoElement);
 
 function createMuxVideo() {
-  const el = new MuxVideo();
+  const el = new MuxVideoElement();
 
   document.body.appendChild(el);
   return el;
@@ -15,7 +15,7 @@ afterEach(() => {
   document.body.innerHTML = '';
 });
 
-describe('MuxVideo', () => {
+describe('MuxVideoElement', () => {
   it('exposes the element source as a property, not an attribute', () => {
     const el = createMuxVideo();
 
diff --git a/packages/html/src/media/tests/spotify-audio.test.ts b/packages/html/src/media/tests/spotify-audio.test.ts
index 8ca94ed4aa..bbb36cfb4c 100644
--- a/packages/html/src/media/tests/spotify-audio.test.ts
+++ b/packages/html/src/media/tests/spotify-audio.test.ts
@@ -1,10 +1,10 @@
 import { describe, expect, it } from 'vite-plus/test';
 
-import { SpotifyAudio } from '../spotify-audio/adapter';
+import { SpotifyAudioElement } from '../spotify-audio/element';
 
-describe('SpotifyAudio', () => {
+describe('SpotifyAudioElement', () => {
   it('hides the embed unless it is showing Spotify’s own chrome', () => {
-    const template = SpotifyAudio.template({ src: 'https://open.spotify.com/track/1301WleyT98MSxVHPZCA6M' });
+    const template = SpotifyAudioElement.template({ src: 'https://open.spotify.com/track/1301WleyT98MSxVHPZCA6M' });
 
     // Left visible, Spotify's own player UI shows through the skin drawn over it.
     // Asserted against the template because no DOM implementation the tests run
diff --git a/packages/html/src/media/tests/tiktok-video.test.ts b/packages/html/src/media/tests/tiktok-video.test.ts
index 07b2feed36..7c59b52728 100644
--- a/packages/html/src/media/tests/tiktok-video.test.ts
+++ b/packages/html/src/media/tests/tiktok-video.test.ts
@@ -1,16 +1,16 @@
 import { describe, expect, it } from 'vite-plus/test';
 
-import { TikTokVideo } from '../tiktok-video/adapter';
+import { TikTokVideoElement } from '../tiktok-video/element';
 
 const SRC = 'https://www.tiktok.com/@videojs/video/7273420104193772846';
 
-describe('TikTokVideo', () => {
+describe('TikTokVideoElement', () => {
   // Asserted against the template because no DOM implementation the tests run in resolves `:host` for a computed
   // style, which is also how the sibling embed hosts check theirs.
   it('keeps the embed out of hit-testing so the skin above it sees hover', () => {
     // A cross-origin frame swallows every pointer event it is given, and the skin never sees the hover that
     // reveals the controls.
-    expect(TikTokVideo.template({ src: SRC })).toMatch(
+    expect(TikTokVideoElement.template({ src: SRC })).toMatch(
       /:host\(:not\(\[controls\]\):not\(\[preload="none"\]\)\)\s*\{\s*pointer-events:\s*none/
     );
   });
@@ -18,17 +18,17 @@ describe('TikTokVideo', () => {
   it('leaves a dormant embed clickable', () => {
     // `preload="none"` opts out of the bootstrap, so TikTok's own controls are the only thing left that can start
     // the player. The rule stops applying rather than the frame stopping taking pointer events.
-    const template = TikTokVideo.template({ src: SRC, preload: 'none' });
+    const template = TikTokVideoElement.template({ src: SRC, preload: 'none' });
 
     expect(template).toContain(':not([preload="none"])');
   });
 
   it('builds the embed with a bootstrap autoplay unless the player is left dormant', () => {
     // `autoplay=1` is the embed parameter; the `allow` attribute names the feature policy and carries it either way.
-    expect(TikTokVideo.template({ src: SRC })).toContain('autoplay=1');
-    expect(TikTokVideo.template({ src: SRC, preload: 'none' })).not.toContain('autoplay=1');
+    expect(TikTokVideoElement.template({ src: SRC })).toContain('autoplay=1');
+    expect(TikTokVideoElement.template({ src: SRC, preload: 'none' })).not.toContain('autoplay=1');
     // The two cases the hit-testing rule above excludes are the two that skip the bootstrap, so the frame stays
     // clickable exactly where its own controls are the only way to start it.
-    expect(TikTokVideo.template({ src: SRC, controls: '' })).not.toContain('autoplay=1');
+    expect(TikTokVideoElement.template({ src: SRC, controls: '' })).not.toContain('autoplay=1');
   });
 });
diff --git a/packages/html/src/media/tests/vimeo-video.test.ts b/packages/html/src/media/tests/vimeo-video.test.ts
index c9f0cf9582..f5d2c05f8b 100644
--- a/packages/html/src/media/tests/vimeo-video.test.ts
+++ b/packages/html/src/media/tests/vimeo-video.test.ts
@@ -1,13 +1,13 @@
 import { describe, expect, it } from 'vite-plus/test';
 
-import { VimeoVideo } from '../vimeo-video/adapter';
+import { VimeoVideoElement } from '../vimeo-video/element';
 
 let tagCounter = 0;
 
 function defineVimeoVideo(): string {
   const tag = `test-vimeo-video-${tagCounter++}`;
 
-  customElements.define(tag, class extends VimeoVideo {});
+  customElements.define(tag, class extends VimeoVideoElement {});
   return tag;
 }
 
@@ -21,7 +21,7 @@ async function flushDeferredEmbed(): Promise<void> {
   await Promise.resolve();
 }
 
-describe('VimeoVideo', () => {
+describe('VimeoVideoElement', () => {
   it('builds the embed for a src set after the element is created', async () => {
     const tag = defineVimeoVideo();
 
diff --git a/packages/html/src/media/tiktok-video/adapter.ts b/packages/html/src/media/tiktok-video/element.ts
similarity index 94%
rename from packages/html/src/media/tiktok-video/adapter.ts
rename to packages/html/src/media/tiktok-video/element.ts
index 618273b68f..ab81b30e66 100644
--- a/packages/html/src/media/tiktok-video/adapter.ts
+++ b/packages/html/src/media/tiktok-video/element.ts
@@ -60,4 +60,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>): Partial<TikTo
   };
 }
 
-export class TikTokVideo extends createMediaElement(TikTokAdapter, { template }) {}
+export class TikTokVideoElement extends createMediaElement(TikTokAdapter, { template }) {
+  static readonly tagName = 'tiktok-video';
+}
diff --git a/packages/html/src/media/tiktok-video/index.ts b/packages/html/src/media/tiktok-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/tiktok-video/index.ts
+++ b/packages/html/src/media/tiktok-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/twitch-video/adapter.ts b/packages/html/src/media/twitch-video/element.ts
similarity index 92%
rename from packages/html/src/media/twitch-video/adapter.ts
rename to packages/html/src/media/twitch-video/element.ts
index 90fab3e4a7..38b7f877a9 100644
--- a/packages/html/src/media/twitch-video/adapter.ts
+++ b/packages/html/src/media/twitch-video/element.ts
@@ -51,4 +51,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class TwitchVideo extends createMediaElement(TwitchAdapter, { template }) {}
+export class TwitchVideoElement extends createMediaElement(TwitchAdapter, { template }) {
+  static readonly tagName = 'twitch-video';
+}
diff --git a/packages/html/src/media/twitch-video/index.ts b/packages/html/src/media/twitch-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/twitch-video/index.ts
+++ b/packages/html/src/media/twitch-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/vimeo-video/adapter.ts b/packages/html/src/media/vimeo-video/element.ts
similarity index 91%
rename from packages/html/src/media/vimeo-video/adapter.ts
rename to packages/html/src/media/vimeo-video/element.ts
index 21945f130f..90c3e58df9 100644
--- a/packages/html/src/media/vimeo-video/adapter.ts
+++ b/packages/html/src/media/vimeo-video/element.ts
@@ -50,4 +50,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class VimeoVideo extends createMediaElement(VimeoAdapter, { template }) {}
+export class VimeoVideoElement extends createMediaElement(VimeoAdapter, { template }) {
+  static readonly tagName = 'vimeo-video';
+}
diff --git a/packages/html/src/media/vimeo-video/index.ts b/packages/html/src/media/vimeo-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/vimeo-video/index.ts
+++ b/packages/html/src/media/vimeo-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/wistia-video/adapter.ts b/packages/html/src/media/wistia-video/element.ts
similarity index 74%
rename from packages/html/src/media/wistia-video/adapter.ts
rename to packages/html/src/media/wistia-video/element.ts
index 7c57c749f5..44bd1420b6 100644
--- a/packages/html/src/media/wistia-video/adapter.ts
+++ b/packages/html/src/media/wistia-video/element.ts
@@ -6,4 +6,6 @@ import { MediaAttachMixin } from '../../store/media-attach-mixin';
  * `<wistia-video>` is Wistia's own `<wistia-player>`, normalized into a media by `WistiaAdapter` and attached to the
  * player store here. No template and no inner player: the element written is the element that plays.
  */
-export class WistiaVideo extends MediaAttachMixin(WistiaAdapter) {}
+export class WistiaVideoElement extends MediaAttachMixin(WistiaAdapter) {
+  static readonly tagName = 'wistia-video';
+}
diff --git a/packages/html/src/media/wistia-video/index.ts b/packages/html/src/media/wistia-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/wistia-video/index.ts
+++ b/packages/html/src/media/wistia-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/media/youtube-video/adapter.ts b/packages/html/src/media/youtube-video/element.ts
similarity index 91%
rename from packages/html/src/media/youtube-video/adapter.ts
rename to packages/html/src/media/youtube-video/element.ts
index 498a973036..bf75dfde76 100644
--- a/packages/html/src/media/youtube-video/adapter.ts
+++ b/packages/html/src/media/youtube-video/element.ts
@@ -50,4 +50,6 @@ function templateAttrsToEmbedProps(attrs: Record<string, string>) {
   };
 }
 
-export class YouTubeVideo extends createMediaElement(YouTubeAdapter, { template }) {}
+export class YouTubeVideoElement extends createMediaElement(YouTubeAdapter, { template }) {
+  static readonly tagName = 'youtube-video';
+}
diff --git a/packages/html/src/media/youtube-video/index.ts b/packages/html/src/media/youtube-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/packages/html/src/media/youtube-video/index.ts
+++ b/packages/html/src/media/youtube-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/packages/html/src/player/tests/create-player.test.ts b/packages/html/src/player/tests/create-player.test.ts
index 152ac45989..09af7ae3ae 100644
--- a/packages/html/src/player/tests/create-player.test.ts
+++ b/packages/html/src/player/tests/create-player.test.ts
@@ -9,7 +9,7 @@ import {
 import { ContextConsumer } from '@videojs/element/context';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
-import { BackgroundVideo } from '../../media/background-video';
+import { BackgroundVideoElement } from '../../media/background-video';
 import { MediaAttachMixin } from '../../store/media-attach-mixin';
 import { ContainerElement } from '../../ui/container/container-element';
 import { UIElement } from '../../ui/ui-element';
@@ -186,7 +186,7 @@ describe('createPlayer', () => {
   it('does not retain disconnected context media as a native fallback', async () => {
     const { PlayerElement } = createPlayer({ features: backgroundFeatures });
     const player = document.createElement(defineTestElement(PlayerElement)) as InstanceType<typeof PlayerElement>;
-    const background = document.createElement(defineTestElement(BackgroundVideo));
+    const background = document.createElement(defineTestElement(BackgroundVideoElement));
     const video = document.createElement('video');
 
     video.slot = 'media';
diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index 7e367853cf..7f7454eb08 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -20,9 +20,11 @@ Pass an adapter class. The returned element renders the adapter's host element i
 import { createMediaElement } from '@videojs/html';
 import { HlsJsAdapter } from '@videojs/hlsjs-video';
 
-export class MyHlsVideo extends createMediaElement(HlsJsAdapter) {}
+export class MyHlsVideoElement extends createMediaElement(HlsJsAdapter) {
+  static readonly tagName = 'my-hls-video';
+}
 
-customElements.define('my-hls-video', MyHlsVideo);
+customElements.define(MyHlsVideoElement.tagName, MyHlsVideoElement);
 ```
 
 Embeds pass a `template` that renders the provider's `<iframe>` from the element's initial attributes:
@@ -32,7 +34,7 @@ import { createMediaElement } from '@videojs/html';
 import { escapeHtml } from '@videojs/utils/string';
 import { VimeoAdapter } from '@videojs/vimeo-video';
 
-export class MyVimeoVideo extends createMediaElement(VimeoAdapter, {
+export class MyVimeoVideoElement extends createMediaElement(VimeoAdapter, {
   template: (attrs) => `<iframe part="iframe" src="${escapeHtml(attrs.src ?? '')}" allowfullscreen></iframe>`,
 }) {}
 ```

From 8259bfa321de989fd0c2833c03694607b126d38e Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 00:01:26 -0700
Subject: [PATCH 17/25] docs(site): discover media elements through safeDefine

The define entries no longer declare a class, so the builder resolves what
they pass to `safeDefine()` to the element class in the media directory and
reads its `tagName` and composition there. Fixtures follow the element.ts
layout, including a flavour reached through a nested barrel.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media-element-handler.ts              | 66 ++++++++++++++++---
 .../html/src/define/media/background-video.ts | 12 ++--
 .../src/define/media/barrel-video/hls-js.ts   |  7 +-
 .../html/src/define/media/complex-video.ts    | 13 +---
 .../html/src/define/media/embed-audio.ts      |  7 +-
 .../html/src/define/media/embed-video.ts      |  7 +-
 .../html/src/define/media/extending-video.ts  | 12 +---
 .../html/src/define/media/mixin-video.ts      | 12 +---
 .../html/src/define/media/simple-video.ts     | 10 +--
 .../html/src/define/media/spf-audio.ts        |  7 +-
 .../{adapter.ts => element.ts}                |  4 +-
 .../html/src/media/background-video/index.ts  |  2 +-
 .../html/src/media/barrel-video/hls-js.ts     | 15 +++++
 .../complex-video/{adapter.ts => element.ts}  |  4 +-
 .../html/src/media/complex-video/index.ts     |  2 +-
 .../embed-audio/{adapter.ts => element.ts}    |  4 +-
 .../html/src/media/embed-audio/index.ts       |  2 +-
 .../embed-video/{adapter.ts => element.ts}    |  4 +-
 .../html/src/media/embed-video/index.ts       |  2 +-
 .../{adapter.ts => element.ts}                |  4 +-
 .../html/src/media/extending-video/index.ts   |  2 +-
 .../mixin-video/{adapter.ts => element.ts}    |  4 +-
 .../html/src/media/mixin-video/index.ts       |  2 +-
 .../simple-video/{adapter.ts => element.ts}   |  4 +-
 .../html/src/media/simple-video/index.ts      |  2 +-
 .../spf-audio/{adapter.ts => element.ts}      |  4 +-
 .../html/src/media/spf-audio/index.ts         |  2 +-
 27 files changed, 134 insertions(+), 82 deletions(-)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/{adapter.ts => element.ts} (73%)
 create mode 100644 site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/barrel-video/hls-js.ts
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/{adapter.ts => element.ts} (77%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/{adapter.ts => element.ts} (75%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/{adapter.ts => element.ts} (68%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/{adapter.ts => element.ts} (77%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/{adapter.ts => element.ts} (76%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/{adapter.ts => element.ts} (82%)
 rename site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/{adapter.ts => element.ts} (77%)

diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index dd15e4a5f1..68835cc650 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -275,19 +275,25 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
       const file = project.source(filePath);
       if (!file) continue;
 
-      for (const statement of file.program.body) {
-        if (statement.type !== 'ExportNamedDeclaration' || statement.declaration?.type !== 'ClassDeclaration') continue;
-
-        const declaration = statement.declaration;
+      for (const candidate of registeredElements(file, project)) {
+        const { file: elementFile, declaration } = candidate;
         const name = declaration.id?.name;
         const tagName = staticStringClassProperty(declaration, 'tagName');
-        const base = declaration.superClass;
-        if (!name || !tagName || base?.type !== 'Identifier') continue;
+        if (!name || !tagName) continue;
+
+        // The element class composes the factory in its own extends clause; an older shape subclassed a media class
+        // declared elsewhere, so follow one identifier up when the composition is not here.
+        let composition = findCustomMediaComposition(elementFile, declaration, project);
+        let mediaDeclaration = { file: elementFile, declaration };
+
+        if (!composition && declaration.superClass?.type === 'Identifier') {
+          const base = project.resolveName(elementFile.filePath, declaration.superClass.name);
+          if (!base || base.declaration.type !== 'ClassDeclaration') continue;
 
-        const mediaDeclaration = project.resolveName(filePath, base.name);
-        if (!mediaDeclaration || mediaDeclaration.declaration.type !== 'ClassDeclaration') continue;
+          mediaDeclaration = { file: base.file, declaration: base.declaration };
+          composition = findCustomMediaComposition(base.file, base.declaration, project);
+        }
 
-        const composition = findCustomMediaComposition(mediaDeclaration.file, mediaDeclaration.declaration, project);
         if (!composition) continue;
 
         const host = project.resolveName(mediaDeclaration.file.filePath, composition.hostClassName);
@@ -299,7 +305,7 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
         if (!targetTag) continue;
 
         // An iframe says nothing about what it plays, so an embed's media type comes from its class name
-        // (`SpotifyAudio` against `VimeoVideo`); the `*Element` export in the define file carries a suffix.
+        // (`SpotifyAudio` against `VimeoVideo`); the element class carries an `Element` suffix.
         const className = stripElementSuffix(name);
         const isAudio = targetTag === 'audio' || (targetTag === 'iframe' && className.endsWith('Audio'));
 
@@ -320,6 +326,46 @@ function discoverMediaElements(monorepoRoot: string, project: OxcProject): Media
   return sources;
 }
 
+/**
+ * The element classes a define file registers: what it passes to `safeDefine()`, resolved to the class declaration in
+ * the media directory, plus any class it declares itself with a static `tagName`.
+ */
+function registeredElements(file: SourceFile, project: OxcProject): { file: SourceFile; declaration: Class }[] {
+  const elements: { file: SourceFile; declaration: Class }[] = [];
+  const seen = new Set<string>();
+
+  for (const statement of file.program.body) {
+    if (
+      statement.type === 'ExpressionStatement' &&
+      statement.expression.type === 'CallExpression' &&
+      statement.expression.callee.type === 'Identifier' &&
+      statement.expression.callee.name === 'safeDefine' &&
+      statement.expression.arguments[0]?.type === 'Identifier'
+    ) {
+      const resolved = project.resolveName(file.filePath, statement.expression.arguments[0].name);
+      const key = resolved && `${resolved.file.filePath}#${statement.expression.arguments[0].name}`;
+
+      if (resolved?.declaration.type === 'ClassDeclaration' && key && !seen.has(key)) {
+        seen.add(key);
+        elements.push({ file: resolved.file, declaration: resolved.declaration });
+      }
+
+      continue;
+    }
+
+    if (statement.type === 'ExportNamedDeclaration' && statement.declaration?.type === 'ClassDeclaration') {
+      const key = `${file.filePath}#${statement.declaration.id?.name}`;
+
+      if (!seen.has(key)) {
+        seen.add(key);
+        elements.push({ file, declaration: statement.declaration });
+      }
+    }
+  }
+
+  return elements;
+}
+
 function publicImplementationFiles(entryPath: string, project: OxcProject, visited: Set<string>): string[] {
   const absolute = path.resolve(entryPath);
   if (visited.has(absolute)) return [];
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/background-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/background-video.ts
index 699ac0cc5e..6d5d306652 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/background-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/background-video.ts
@@ -2,12 +2,10 @@
  * Mock background video registration — mirrors define/media/background-video.ts.
  *
  * Exercises: exclusion. BackgroundVideo uses MediaAttachMixin(HTMLElement)
- * without MediaPropsMixin. The builder should discover this file (it has
- * static tagName) but skip it because parseMixinChain returns null.
- * Its API reference is manually maintained in MDX (#1243).
+ * without a media factory. The builder should discover this file (it registers an element with a static tagName) but
+ * skip it because there is no composition to follow. Its API reference is manually maintained in MDX (#1243).
  */
-import { BackgroundVideo } from '../../media/background-video';
+import { BackgroundVideoElement } from '../../media/background-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class BackgroundVideoElement extends BackgroundVideo {
-  static readonly tagName = 'background-video';
-}
+safeDefine(BackgroundVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/barrel-video/hls-js.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/barrel-video/hls-js.ts
index a2e6e4ad2b..26922e8b77 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/barrel-video/hls-js.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/barrel-video/hls-js.ts
@@ -1,5 +1,4 @@
-import { SimpleVideo } from '../../../media/simple-video';
+import { BarrelVideoElement } from '../../../media/barrel-video/hls-js';
+import { safeDefine } from '../../../registration/safe-define';
 
-export class BarrelVideoElement extends SimpleVideo {
-  static readonly tagName = 'barrel-video';
-}
+safeDefine(BarrelVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/complex-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/complex-video.ts
index e88d784047..6fbd0dbd00 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/complex-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/complex-video.ts
@@ -1,11 +1,4 @@
-/**
- * Mock complex video element registration — mirrors define/media/hls-video.ts.
- *
- * Exercises: element discovery via static tagName in define/media/*.ts,
- * with a delegate that has JSDoc and overlapping native attributes.
- */
-import { ComplexVideo } from '../../media/complex-video';
+import { ComplexVideoElement } from '../../media/complex-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class ComplexVideoElement extends ComplexVideo {
-  static readonly tagName = 'complex-video';
-}
+safeDefine(ComplexVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
index 433f639256..b0c9c5f3c7 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-audio.ts
@@ -1,5 +1,4 @@
-import { EmbedAudio } from '../../media/embed-audio';
+import { EmbedAudioElement } from '../../media/embed-audio';
+import { safeDefine } from '../../registration/safe-define';
 
-export class EmbedAudioElement extends EmbedAudio {
-  static readonly tagName = 'embed-audio';
-}
+safeDefine(EmbedAudioElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-video.ts
index dcb204f57a..646992390f 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/embed-video.ts
@@ -1,5 +1,4 @@
-import { EmbedVideo } from '../../media/embed-video';
+import { EmbedVideoElement } from '../../media/embed-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class EmbedVideoElement extends EmbedVideo {
-  static readonly tagName = 'embed-video';
-}
+safeDefine(EmbedVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/extending-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/extending-video.ts
index 2bb2318daa..1164e2420a 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/extending-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/extending-video.ts
@@ -1,10 +1,4 @@
-/**
- * Mock extending video element registration — mirrors define/media/mux-video.ts.
- *
- * Exercises: element with a delegate that extends another delegate.
- */
-import { ExtendingVideo } from '../../media/extending-video';
+import { ExtendingVideoElement } from '../../media/extending-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class ExtendingVideoElement extends ExtendingVideo {
-  static readonly tagName = 'extending-video';
-}
+safeDefine(ExtendingVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/mixin-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/mixin-video.ts
index 255c865bab..4ec321956c 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/mixin-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/mixin-video.ts
@@ -1,10 +1,4 @@
-/**
- * Mock mixin-chain element registration — mirrors define/media/mux-video.ts.
- *
- * Exercises: element whose host is a mixin chain (call-expression extends).
- */
-import { MixinVideo } from '../../media/mixin-video';
+import { MixinVideoElement } from '../../media/mixin-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class MixinVideoElement extends MixinVideo {
-  static readonly tagName = 'mixin-video';
-}
+safeDefine(MixinVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/simple-video.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/simple-video.ts
index 8eee4044c0..1ef1ce9b8c 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/simple-video.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/simple-video.ts
@@ -1,10 +1,10 @@
 /**
  * Mock simple video element registration — mirrors define/media/dash-video.ts.
  *
- * Exercises: element discovery via static tagName in define/media/*.ts.
+ * Exercises: element discovery through `safeDefine()`, resolving to the element class and its static tagName in
+ * media/simple-video/element.ts.
  */
-import { SimpleVideo } from '../../media/simple-video';
+import { SimpleVideoElement } from '../../media/simple-video';
+import { safeDefine } from '../../registration/safe-define';
 
-export class SimpleVideoElement extends SimpleVideo {
-  static readonly tagName = 'simple-video';
-}
+safeDefine(SimpleVideoElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/spf-audio.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/spf-audio.ts
index 0c4a1681d2..d862f53c41 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/spf-audio.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/define/media/spf-audio.ts
@@ -4,8 +4,7 @@
  * Exercises: discovery of an audio element whose host mixin lives in another
  * workspace package.
  */
-import { SpfAudio } from '../../media/spf-audio';
+import { SpfAudioElement } from '../../media/spf-audio';
+import { safeDefine } from '../../registration/safe-define';
 
-export class SpfAudioElement extends SpfAudio {
-  static readonly tagName = 'spf-audio';
-}
+safeDefine(SpfAudioElement);
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/element.ts
similarity index 73%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/element.ts
index 1b8cff6129..4183928bba 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/element.ts
@@ -9,4 +9,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class BackgroundVideo extends MediaAttachMixin(Object) {}
+export class BackgroundVideoElement extends MediaAttachMixin(Object) {
+  static readonly tagName = 'background-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/background-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/barrel-video/hls-js.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/barrel-video/hls-js.ts
new file mode 100644
index 0000000000..74d97533d1
--- /dev/null
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/barrel-video/hls-js.ts
@@ -0,0 +1,15 @@
+/**
+ * Mock flavour element — mirrors media/mux-video/hls-js.ts.
+ *
+ * Exercises: an element reached through a nested define barrel (`define/media/barrel-video/index.ts` → `./hls-js`).
+ */
+import { SimpleHost } from '../../../../media/src/dom/simple';
+
+// Stub — the builder parses the AST, it doesn't run the code.
+function createMediaElement(adapter: any, options?: { template?: (attrs: Record<string, string>) => string }) {
+  return adapter;
+}
+
+export class BarrelVideoElement extends createMediaElement(SimpleHost) {
+  static readonly tagName = 'barrel-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/element.ts
similarity index 77%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/element.ts
index c11bfb7862..dc7d8d9f29 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/element.ts
@@ -13,4 +13,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class ComplexVideo extends MediaAttachMixin(CustomMediaElement(ComplexHost)) {}
+export class ComplexVideoElement extends MediaAttachMixin(CustomMediaElement(ComplexHost)) {
+  static readonly tagName = 'complex-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/complex-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/element.ts
similarity index 75%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/element.ts
index 3e036844fc..8b9c1818c7 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/element.ts
@@ -11,4 +11,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class EmbedAudio extends MediaAttachMixin(CustomMediaElement(EmbedHost)) {}
+export class EmbedAudioElement extends MediaAttachMixin(CustomMediaElement(EmbedHost)) {
+  static readonly tagName = 'embed-audio';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-audio/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/element.ts
similarity index 68%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/element.ts
index e664c669ac..639e6aea86 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/element.ts
@@ -7,4 +7,6 @@ function MediaAttachMixin(base: any) {
 
 class EmbedCustomMediaElement extends CustomMediaElement(EmbedHost) {}
 
-export class EmbedVideo extends MediaAttachMixin(EmbedCustomMediaElement) {}
+export class EmbedVideoElement extends MediaAttachMixin(EmbedCustomMediaElement) {
+  static readonly tagName = 'embed-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/embed-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/element.ts
similarity index 77%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/element.ts
index 0c33138342..8f79608590 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/element.ts
@@ -13,4 +13,6 @@ function MediaAttachMixin(base: any) {
 
 const ExtendingVideoBase = MediaAttachMixin(CustomMediaElement(ExtendingHost));
 
-export class ExtendingVideo extends (ExtendingVideoBase as typeof ExtendingVideoBase) {}
+export class ExtendingVideoElement extends (ExtendingVideoBase as typeof ExtendingVideoBase) {
+  static readonly tagName = 'extending-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/extending-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/element.ts
similarity index 76%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/element.ts
index 3761649924..f693fb38e0 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/element.ts
@@ -11,4 +11,6 @@ function createMediaElement(adapter: any, options?: { template?: (attrs: Record<
   return adapter;
 }
 
-export class MixinVideo extends createMediaElement(MixinHost, { template: () => '<video></video>' }) {}
+export class MixinVideoElement extends createMediaElement(MixinHost, { template: () => '<video></video>' }) {
+  static readonly tagName = 'mixin-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/mixin-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/element.ts
similarity index 82%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/element.ts
index 5e0bf14dcd..5da31d441f 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/element.ts
@@ -12,4 +12,6 @@ function createMediaElement(adapter: any, options?: { template?: (attrs: Record<
   return adapter;
 }
 
-export class SimpleVideo extends createMediaElement(SimpleHost) {}
+export class SimpleVideoElement extends createMediaElement(SimpleHost) {
+  static readonly tagName = 'simple-video';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/simple-video/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/element.ts
similarity index 77%
rename from site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts
rename to site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/element.ts
index e59832fdff..262765a5f3 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/adapter.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/element.ts
@@ -12,4 +12,6 @@ function MediaAttachMixin(base: any) {
   return base;
 }
 
-export class SpfAudio extends MediaAttachMixin(CustomMediaElement(SpfAudioHost)) {}
+export class SpfAudioElement extends MediaAttachMixin(CustomMediaElement(SpfAudioHost)) {
+  static readonly tagName = 'spf-audio';
+}
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/index.ts b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/index.ts
index 7e77e9fc24..ef9f88ec65 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/index.ts
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/html/src/media/spf-audio/index.ts
@@ -1 +1 @@
-export * from './adapter';
+export * from './element';

From 8ae3eca7f71df686bbbec45298f24150f10cbc65 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 00:20:27 -0700
Subject: [PATCH 18/25] refactor(media): let renderHost read the element's
 statics

`renderHost(element, attrs)` takes the template and shadow root options from
the element's own constructor, so callers stop passing what the class already
declares.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media/background-video/element.ts     | 25 +++++++------------
 .../src/media/hls-background-video/element.ts | 25 +++++++------------
 .../custom-media-element.ts                   |  9 +------
 .../dom/custom-media-element/render-host.ts   | 20 ++++++++-------
 4 files changed, 30 insertions(+), 49 deletions(-)

diff --git a/packages/html/src/media/background-video/element.ts b/packages/html/src/media/background-video/element.ts
index c016bbd612..e1ff651313 100644
--- a/packages/html/src/media/background-video/element.ts
+++ b/packages/html/src/media/background-video/element.ts
@@ -20,22 +20,15 @@ export class BackgroundVideoElement extends MediaAttachMixin(HTMLElementBase) {
   constructor() {
     super();
 
-    const ctor = this.constructor as typeof BackgroundVideoElement;
-
-    renderHost(
-      this,
-      ctor.template,
-      {
-        ...namedNodeMapToObject(this.attributes),
-        ...(!this.hasAttribute('nomuted') && { muted: '' }),
-        ...(!this.hasAttribute('noloop') && { loop: '' }),
-        ...(!this.hasAttribute('noautoplay') && { autoplay: '' }),
-        playsinline: '',
-        disableremoteplayback: '',
-        disablepictureinpicture: '',
-      },
-      ctor.shadowRootOptions
-    );
+    renderHost(this, {
+      ...namedNodeMapToObject(this.attributes),
+      ...(!this.hasAttribute('nomuted') && { muted: '' }),
+      ...(!this.hasAttribute('noloop') && { loop: '' }),
+      ...(!this.hasAttribute('noautoplay') && { autoplay: '' }),
+      playsinline: '',
+      disableremoteplayback: '',
+      disablepictureinpicture: '',
+    });
 
     // Neither Chrome or Firefox support setting the muted attribute
     // after using document.createElement.
diff --git a/packages/html/src/media/hls-background-video/element.ts b/packages/html/src/media/hls-background-video/element.ts
index 2e4c0dec31..0eb03650d6 100644
--- a/packages/html/src/media/hls-background-video/element.ts
+++ b/packages/html/src/media/hls-background-video/element.ts
@@ -65,22 +65,15 @@ export class HlsBackgroundVideoElement extends HlsBackgroundVideoBase {
   constructor() {
     super();
 
-    const ctor = this.constructor as typeof HlsBackgroundVideoElement;
-
-    renderHost(
-      this,
-      ctor.template,
-      {
-        ...namedNodeMapToObject(this.attributes),
-        muted: '',
-        loop: '',
-        autoplay: '',
-        playsinline: '',
-        disableremoteplayback: '',
-        disablepictureinpicture: '',
-      },
-      ctor.shadowRootOptions
-    );
+    renderHost(this, {
+      ...namedNodeMapToObject(this.attributes),
+      muted: '',
+      loop: '',
+      autoplay: '',
+      playsinline: '',
+      disableremoteplayback: '',
+      disablepictureinpicture: '',
+    });
 
     // Neither Chrome nor Firefox honor a `muted` attribute set after
     // `document.createElement`, and autoplay is refused without it. Attaching is
diff --git a/packages/media/src/dom/custom-media-element/custom-media-element.ts b/packages/media/src/dom/custom-media-element/custom-media-element.ts
index cc83e5ed97..862c8fd9a8 100644
--- a/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -87,14 +87,7 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
     constructor() {
       super();
 
-      const ctor = this.constructor as typeof CustomMedia;
-
-      renderHost(
-        this,
-        ctor.template,
-        { part: tag, ...initialAttributes(this, routes, { passthrough }) },
-        ctor.shadowRootOptions
-      );
+      renderHost(this, { part: tag, ...initialAttributes(this, routes, { passthrough }) });
 
       this.#attachment.attach();
       this.shadowRoot!.addEventListener('slotchange', () => {
diff --git a/packages/media/src/dom/custom-media-element/render-host.ts b/packages/media/src/dom/custom-media-element/render-host.ts
index d8de2a5183..bb89801ecf 100644
--- a/packages/media/src/dom/custom-media-element/render-host.ts
+++ b/packages/media/src/dom/custom-media-element/render-host.ts
@@ -4,22 +4,24 @@ import { omit, pick } from '@videojs/utils/object';
 import type { AttributeRoutes } from './attributes';
 import type { MediaTemplate } from './templates';
 
+/** The statics an element class carries for `renderHost`: its template and, optionally, its shadow root options. */
+export interface HostElementConstructor {
+  template: MediaTemplate;
+  shadowRootOptions?: ShadowRootInit;
+}
+
 /**
- * Render the template into the element's shadow root. An existing root, such as a declarative one, is left as it is.
+ * Render the element's static `template` into its shadow root, attached with its static `shadowRootOptions`. An
+ * existing root, such as a declarative one, is left as it is.
  *
  * @param element - The custom element to render into.
- * @param template - Produces the shadow HTML from the attributes it may render.
  * @param attrs - The attributes handed to the template, typically from `initialAttributes`.
  */
-export function renderHost(
-  element: HTMLElement,
-  template: MediaTemplate,
-  attrs: Record<string, string>,
-  init: ShadowRootInit = { mode: 'open' }
-): ShadowRoot {
+export function renderHost(element: HTMLElement, attrs: Record<string, string>): ShadowRoot {
   if (element.shadowRoot) return element.shadowRoot;
 
-  const root = element.attachShadow(init);
+  const { template, shadowRootOptions = { mode: 'open' } } = element.constructor as unknown as HostElementConstructor;
+  const root = element.attachShadow(shadowRootOptions);
 
   root.innerHTML = template(attrs);
 

From 742e16306d9d65e88d021c1bcbb11b77fab70a9b Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 00:20:32 -0700
Subject: [PATCH 19/25] refactor(html): share one embed template across the
 iframe elements

Six embeds each carried the same `<style>` and `<iframe>` markup and the same
attribute-to-props mapper. `embedTemplate` renders the frame from what
differs (URL, feature policy, extra attributes, host sizing, the rule for a
host without controls), and `propsFromAttributes` in `@videojs/media/dom`
reads the initial attributes through the adapter's `defaultProps`, the same
coercion the element applies later.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media/cloudflare-video/element.ts     | 53 +++-----------
 packages/html/src/media/embed-template.ts     | 61 ++++++++++++++++
 .../html/src/media/spotify-audio/element.ts   | 61 ++++------------
 .../src/media/tests/embed-template.test.ts    | 42 +++++++++++
 .../html/src/media/tiktok-video/element.ts    | 70 ++++---------------
 .../html/src/media/twitch-video/element.ts    | 56 +++------------
 .../html/src/media/vimeo-video/element.ts     | 52 +++-----------
 .../html/src/media/youtube-video/element.ts   | 52 +++-----------
 .../dom/custom-media-element/attributes.ts    | 19 +++++
 .../tests/attributes.test.ts                  | 45 ++++++++++++
 10 files changed, 229 insertions(+), 282 deletions(-)
 create mode 100644 packages/html/src/media/embed-template.ts
 create mode 100644 packages/html/src/media/tests/embed-template.test.ts
 create mode 100644 packages/media/src/dom/custom-media-element/tests/attributes.test.ts

diff --git a/packages/html/src/media/cloudflare-video/element.ts b/packages/html/src/media/cloudflare-video/element.ts
index d01775b599..c8ec3faef0 100644
--- a/packages/html/src/media/cloudflare-video/element.ts
+++ b/packages/html/src/media/cloudflare-video/element.ts
@@ -1,56 +1,19 @@
 import { buildCloudflareIframeSrc, CloudflareAdapter } from '@videojs/cloudflare-video';
-import { escapeHtml } from '@videojs/utils/string';
+import { propsFromAttributes } from '@videojs/media/dom';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildCloudflareIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(CloudflareAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: inline-block;
-        min-width: 300px;
-        min-height: 150px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      :host(:not([controls])) {
-        pointer-events: none;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      ${srcAttr}
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowfullscreen
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildCloudflareIframeSrc(props.src, props),
+    allow: 'accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture',
+    attributes: { allowfullscreen: '' },
+  });
 };
 
-function templateAttrsToEmbedProps(attrs: Record<string, string>) {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    defaultMuted: attrs.muted !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    preload: (attrs.preload as 'none' | 'metadata' | 'auto' | undefined) ?? 'metadata',
-    // The Stream embed paints the poster itself, so it is part of the URL.
-    poster: attrs.poster ?? '',
-  };
-}
-
 export class CloudflareVideoElement extends createMediaElement(CloudflareAdapter, { template }) {
   static readonly tagName = 'cloudflare-video';
 }
diff --git a/packages/html/src/media/embed-template.ts b/packages/html/src/media/embed-template.ts
new file mode 100644
index 0000000000..36ad43aa53
--- /dev/null
+++ b/packages/html/src/media/embed-template.ts
@@ -0,0 +1,61 @@
+import { serializeAttributes } from '@videojs/utils/dom';
+import { escapeHtml } from '@videojs/utils/string';
+
+export interface EmbedTemplateOptions {
+  /** The embed URL, or an empty string to leave `src` off until the adapter builds one. */
+  src: string;
+  /** The `allow` feature policy for the frame. */
+  allow: string;
+  /** Further attributes on the frame, such as `sandbox` or `title`. An empty string renders a boolean attribute. */
+  attributes?: Record<string, string>;
+  /** How the host sizes itself. Landscape embeds start inline at 300x150. */
+  host?: { display?: 'inline-block' | 'block'; minWidth?: string; minHeight?: string };
+  /**
+   * The CSS rule for a host without `controls`. A cross-origin frame swallows every pointer event, so by default the
+   * frame leaves hit-testing and the skin above it sees the hover that reveals the controls.
+   */
+  withoutControls?: string;
+}
+
+/**
+ * The shadow template every iframe embed renders: a frame filling the host, with the provider's URL and feature policy.
+ * Embeds pass what differs and keep the rest in one place.
+ */
+export function embedTemplate({
+  src,
+  allow,
+  attributes = {},
+  host = {},
+  withoutControls,
+}: EmbedTemplateOptions): string {
+  const { display = 'inline-block', minWidth = '300px', minHeight = '150px' } = host;
+  const frame = serializeAttributes({
+    part: 'iframe',
+    ...(src && { src }),
+    allow,
+    frameborder: '0',
+    width: '100%',
+    height: '100%',
+    ...attributes,
+  });
+
+  return /*html*/ `
+    <style>
+      :host {
+        display: ${display};
+        min-width: ${escapeHtml(minWidth)};
+        min-height: ${escapeHtml(minHeight)};
+        position: relative;
+      }
+      iframe {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        border: 0;
+      }
+      ${withoutControls ?? ':host(:not([controls])) { pointer-events: none; }'}
+    </style>
+    <iframe${frame}></iframe>
+  `;
+}
diff --git a/packages/html/src/media/spotify-audio/element.ts b/packages/html/src/media/spotify-audio/element.ts
index 5f5652b365..bf988f5163 100644
--- a/packages/html/src/media/spotify-audio/element.ts
+++ b/packages/html/src/media/spotify-audio/element.ts
@@ -1,60 +1,23 @@
+import { propsFromAttributes } from '@videojs/media/dom';
 import { buildSpotifyIframeSrc, SpotifyAdapter } from '@videojs/spotify-audio';
-import { escapeHtml } from '@videojs/utils/string';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildSpotifyIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(SpotifyAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: block;
-        min-width: 160px;
-        min-height: 80px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      /*
-       * Without Spotify's own chrome the embed is a transport and nothing else:
-       * its player UI would otherwise show through whatever skin is drawn over
-       * it. Hidden rather than merely inert, and important so a consumer's own
-       * display rule cannot put it back on screen. An iframe in a hidden subtree
-       * still loads and plays its src.
-       */
-      :host(:not([controls])) {
-        display: none !important;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      ${srcAttr}
-      allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildSpotifyIframeSrc(props.src, props),
+    allow: 'autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture',
+    host: { display: 'block', minWidth: '160px', minHeight: '80px' },
+    // Without Spotify's own chrome the embed is a transport and nothing else: its player UI would otherwise show
+    // through whatever skin is drawn over it. Hidden rather than merely inert, and important so a consumer's own
+    // display rule cannot put it back on screen. An iframe in a hidden subtree still loads and plays its src.
+    withoutControls: ':host(:not([controls])) { display: none !important; }',
+  });
 };
 
-function templateAttrsToEmbedProps(attrs: Record<string, string>) {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    playsInline: attrs.playsinline !== undefined,
-    preload: (attrs.preload as 'none' | 'metadata' | 'auto' | undefined) ?? 'metadata',
-  };
-}
-
 export class SpotifyAudioElement extends createMediaElement(SpotifyAdapter, { template }) {
   static readonly tagName = 'spotify-audio';
 }
diff --git a/packages/html/src/media/tests/embed-template.test.ts b/packages/html/src/media/tests/embed-template.test.ts
new file mode 100644
index 0000000000..fc1c4af545
--- /dev/null
+++ b/packages/html/src/media/tests/embed-template.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vite-plus/test';
+
+import { embedTemplate } from '../embed-template';
+
+describe('embedTemplate', () => {
+  it('renders the frame with the URL, the feature policy, and the extra attributes', () => {
+    const html = embedTemplate({
+      src: 'https://player.example.com/embed?x="1"',
+      allow: 'autoplay; fullscreen',
+      attributes: { allowfullscreen: '', title: 'Example player' },
+    });
+    const container = document.createElement('div');
+
+    container.innerHTML = html;
+
+    const iframe = container.querySelector('iframe')!;
+
+    expect(iframe.getAttribute('part')).toBe('iframe');
+    expect(iframe.getAttribute('src')).toBe('https://player.example.com/embed?x="1"');
+    expect(iframe.getAttribute('allow')).toBe('autoplay; fullscreen');
+    expect(iframe.hasAttribute('allowfullscreen')).toBe(true);
+    expect(iframe.getAttribute('title')).toBe('Example player');
+    expect(container.querySelector('script')).toBeNull();
+  });
+
+  it('leaves src off until there is a URL', () => {
+    const container = document.createElement('div');
+
+    container.innerHTML = embedTemplate({ src: '', allow: 'autoplay' });
+
+    expect(container.querySelector('iframe')!.hasAttribute('src')).toBe(false);
+  });
+
+  it('takes the frame out of hit-testing without controls unless told otherwise', () => {
+    expect(embedTemplate({ src: '', allow: '' })).toMatch(
+      /:host\(:not\(\[controls\]\)\)\s*\{\s*pointer-events:\s*none/
+    );
+    expect(embedTemplate({ src: '', allow: '', withoutControls: ':host { color: red; }' })).not.toContain(
+      'pointer-events'
+    );
+  });
+});
diff --git a/packages/html/src/media/tiktok-video/element.ts b/packages/html/src/media/tiktok-video/element.ts
index ab81b30e66..0e534a3686 100644
--- a/packages/html/src/media/tiktok-video/element.ts
+++ b/packages/html/src/media/tiktok-video/element.ts
@@ -1,65 +1,25 @@
-import { buildTikTokIframeSrc, TikTokAdapter, type TikTokAdapterProps } from '@videojs/tiktok-video';
-import { escapeHtml } from '@videojs/utils/string';
+import { propsFromAttributes } from '@videojs/media/dom';
+import { buildTikTokIframeSrc, TikTokAdapter } from '@videojs/tiktok-video';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildTikTokIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(TikTokAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: inline-block;
-        /* TikTok videos are portrait, and the player refuses to draw its chrome
-           below 325x578, so that is where this host starts rather than the
-           300x150 the landscape embeds use. */
-        min-width: 325px;
-        min-height: 578px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      /* A cross-origin frame swallows every pointer event, so the skin above it
-         never sees the hover that reveals the controls. Kept out of hit-testing
-         except where the host leaves TikTok's player dormant, which is the same
-         pair of cases shouldBootstrapTikTokEmbed opts out of: then the frame's
-         own controls are the only thing that can still start it. */
-      :host(:not([controls]):not([preload="none"])) {
-        pointer-events: none;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      title="TikTok video player"
-      ${srcAttr}
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowfullscreen
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildTikTokIframeSrc(props.src, props),
+    allow: 'accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture',
+    attributes: { title: 'TikTok video player', allowfullscreen: '' },
+    // TikTok videos are portrait, and the player refuses to draw its chrome below 325x578, so that is where this host
+    // starts rather than the 300x150 the landscape embeds use.
+    host: { minWidth: '325px', minHeight: '578px' },
+    // Kept out of hit-testing except where the host leaves TikTok's player dormant, which is the same pair of cases
+    // shouldBootstrapTikTokEmbed opts out of: then the frame's own controls are the only thing that can still start it.
+    withoutControls: ':host(:not([controls]):not([preload="none"])) { pointer-events: none; }',
+  });
 };
 
-// Only the props the embed URL is built from. `preload` is not a TikTok parameter, but it decides whether the URL
-// carries a bootstrap autoplay, and a URL differing from the host's would have it rebuild the frame on mount.
-function templateAttrsToEmbedProps(attrs: Record<string, string>): Partial<TikTokAdapterProps> {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    defaultMuted: attrs.muted !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    preload: attrs.preload as TikTokAdapterProps['preload'],
-  };
-}
-
 export class TikTokVideoElement extends createMediaElement(TikTokAdapter, { template }) {
   static readonly tagName = 'tiktok-video';
 }
diff --git a/packages/html/src/media/twitch-video/element.ts b/packages/html/src/media/twitch-video/element.ts
index 38b7f877a9..eaab75546e 100644
--- a/packages/html/src/media/twitch-video/element.ts
+++ b/packages/html/src/media/twitch-video/element.ts
@@ -1,56 +1,22 @@
+import { propsFromAttributes } from '@videojs/media/dom';
 import { buildTwitchIframeSrc, TwitchAdapter } from '@videojs/twitch-video';
-import { escapeHtml } from '@videojs/utils/string';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildTwitchIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(TwitchAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: inline-block;
-        min-width: 300px;
-        min-height: 150px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      :host(:not([controls])) {
-        pointer-events: none;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      ${srcAttr}
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;"
-      sandbox="allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
-      scrolling="no"
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildTwitchIframeSrc(props.src, props),
+    allow: 'accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;',
+    attributes: {
+      sandbox: 'allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox',
+      scrolling: 'no',
+    },
+  });
 };
 
-function templateAttrsToEmbedProps(attrs: Record<string, string>) {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    defaultMuted: attrs.muted !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    playsInline: attrs.playsinline !== undefined,
-    preload: (attrs.preload as 'none' | 'metadata' | 'auto' | undefined) ?? 'metadata',
-  };
-}
-
 export class TwitchVideoElement extends createMediaElement(TwitchAdapter, { template }) {
   static readonly tagName = 'twitch-video';
 }
diff --git a/packages/html/src/media/vimeo-video/element.ts b/packages/html/src/media/vimeo-video/element.ts
index 90c3e58df9..45ebba0683 100644
--- a/packages/html/src/media/vimeo-video/element.ts
+++ b/packages/html/src/media/vimeo-video/element.ts
@@ -1,55 +1,19 @@
-import { escapeHtml } from '@videojs/utils/string';
+import { propsFromAttributes } from '@videojs/media/dom';
 import { buildVimeoIframeSrc, VimeoAdapter } from '@videojs/vimeo-video';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildVimeoIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(VimeoAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: inline-block;
-        min-width: 300px;
-        min-height: 150px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      :host(:not([controls])) {
-        pointer-events: none;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      ${srcAttr}
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowfullscreen
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildVimeoIframeSrc(props.src, props),
+    allow: 'accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture',
+    attributes: { allowfullscreen: '' },
+  });
 };
 
-function templateAttrsToEmbedProps(attrs: Record<string, string>) {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    defaultMuted: attrs.muted !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    playsInline: attrs.playsinline !== undefined,
-    preload: (attrs.preload as 'none' | 'metadata' | 'auto' | undefined) ?? 'metadata',
-  };
-}
-
 export class VimeoVideoElement extends createMediaElement(VimeoAdapter, { template }) {
   static readonly tagName = 'vimeo-video';
 }
diff --git a/packages/html/src/media/youtube-video/element.ts b/packages/html/src/media/youtube-video/element.ts
index bf75dfde76..1b01178338 100644
--- a/packages/html/src/media/youtube-video/element.ts
+++ b/packages/html/src/media/youtube-video/element.ts
@@ -1,55 +1,19 @@
-import { escapeHtml } from '@videojs/utils/string';
+import { propsFromAttributes } from '@videojs/media/dom';
 import { buildYouTubeIframeSrc, YouTubeAdapter } from '@videojs/youtube-video';
 
 import { createMediaElement } from '../create-media-element';
+import { embedTemplate } from '../embed-template';
 
 const template = (attrs: Record<string, string>): string => {
-  const initialSrc = buildYouTubeIframeSrc(attrs.src ?? '', templateAttrsToEmbedProps(attrs));
-  const srcAttr = initialSrc ? ` src="${escapeHtml(initialSrc)}"` : '';
+  const props = propsFromAttributes(YouTubeAdapter, attrs);
 
-  return /*html*/ `
-    <style>
-      :host {
-        display: inline-block;
-        min-width: 300px;
-        min-height: 150px;
-        position: relative;
-      }
-      iframe {
-        position: absolute;
-        inset: 0;
-        width: 100%;
-        height: 100%;
-        border: 0;
-      }
-      :host(:not([controls])) {
-        pointer-events: none;
-      }
-    </style>
-    <iframe
-      part="iframe"
-      ${srcAttr}
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowfullscreen
-      frameborder="0"
-      width="100%"
-      height="100%"
-      referrerpolicy="${escapeHtml(attrs.referrerpolicy ?? '')}"
-    ></iframe>
-  `;
+  return embedTemplate({
+    src: buildYouTubeIframeSrc(props.src, props),
+    allow: 'accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture',
+    attributes: { allowfullscreen: '' },
+  });
 };
 
-function templateAttrsToEmbedProps(attrs: Record<string, string>) {
-  return {
-    autoplay: attrs.autoplay !== undefined,
-    defaultMuted: attrs.muted !== undefined,
-    loop: attrs.loop !== undefined,
-    controls: attrs.controls !== undefined,
-    playsInline: attrs.playsinline !== undefined,
-    preload: (attrs.preload as 'none' | 'metadata' | 'auto' | undefined) ?? 'metadata',
-  };
-}
-
 export class YouTubeVideoElement extends createMediaElement(YouTubeAdapter, { template }) {
   static readonly tagName = 'youtube-video';
 }
diff --git a/packages/media/src/dom/custom-media-element/attributes.ts b/packages/media/src/dom/custom-media-element/attributes.ts
index 0daf05d4ab..005c87c9d8 100644
--- a/packages/media/src/dom/custom-media-element/attributes.ts
+++ b/packages/media/src/dom/custom-media-element/attributes.ts
@@ -42,6 +42,25 @@ export function derivedAttributes(defaultProps: object): AttributeConfigs {
   return configs;
 }
 
+/**
+ * The adapter's props as an element's initial attributes set them: `defaultProps` with each declared attribute that is
+ * present coerced over it. What a template needs to build an embed URL before the adapter has attached.
+ */
+export function propsFromAttributes<Adapter extends { readonly defaultProps: object }>(
+  Adapter: Adapter,
+  attrs: Record<string, string>
+): Adapter['defaultProps'] {
+  const props: Record<string, unknown> = { ...Adapter.defaultProps };
+
+  for (const [prop, config] of Object.entries(derivedAttributes(Adapter.defaultProps))) {
+    const attribute = config.attribute!;
+
+    if (attribute in attrs) props[prop] = coerceAttribute(attrs[attribute]!, config);
+  }
+
+  return props as Adapter['defaultProps'];
+}
+
 /** Coerce an attribute string to the type its config declares. */
 export function coerceAttribute(value: string | null, config: AttributeConfig): unknown {
   if (config.type === Boolean) return value !== null;
diff --git a/packages/media/src/dom/custom-media-element/tests/attributes.test.ts b/packages/media/src/dom/custom-media-element/tests/attributes.test.ts
new file mode 100644
index 0000000000..6665e80bc5
--- /dev/null
+++ b/packages/media/src/dom/custom-media-element/tests/attributes.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vite-plus/test';
+
+import { derivedAttributes, propsFromAttributes } from '../attributes';
+
+class EmbedAdapter {
+  static readonly defaultProps = {
+    src: '',
+    autoplay: false,
+    defaultMuted: false,
+    muted: false,
+    preload: 'metadata',
+    volume: 1,
+    source: null,
+  };
+}
+
+describe('derivedAttributes', () => {
+  it('declares one attribute per primitive default, spelled the WHATWG way, and skips objects and playback state', () => {
+    const configs = derivedAttributes(EmbedAdapter.defaultProps);
+
+    expect(Object.keys(configs).sort()).toEqual(['autoplay', 'defaultMuted', 'preload', 'src']);
+    expect(configs.defaultMuted).toEqual({ type: Boolean, attribute: 'muted', empty: false });
+    expect(configs.preload).toEqual({ type: String, attribute: 'preload', empty: 'metadata' });
+  });
+});
+
+describe('propsFromAttributes', () => {
+  it('reads the present attributes over the defaults, coerced by their default', () => {
+    const props = propsFromAttributes(EmbedAdapter, { src: 'https://example.com/x', muted: '', preload: 'none' });
+
+    expect(props).toEqual({
+      src: 'https://example.com/x',
+      autoplay: false,
+      defaultMuted: true,
+      muted: false,
+      preload: 'none',
+      volume: 1,
+      source: null,
+    });
+  });
+
+  it('returns the defaults when nothing is set', () => {
+    expect(propsFromAttributes(EmbedAdapter, {})).toEqual(EmbedAdapter.defaultProps);
+  });
+});

From 48d520f7dd0255f1be062d0a75a7a6732c3ce3bf Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 17:55:05 -0700
Subject: [PATCH 20/25] refactor(media)!: make the video adapter host a literal
 again

`HTMLVideoAdapter.host` was typed `'video' | 'audio'` only so the hls.js
`MuxAudioAdapter`, which extends the video adapter, could override it. That
made every video adapter's `host` a union in the types. The base is `'video'`
again and the Mux audio adapter casts its inverted base to drop the literal,
the same way `MuxBackgroundVideoElement` does for `tagName`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/adapters/mux-audio/src/index.ts                   | 7 +++++--
 .../media/src/dom/html-video-adapter/html-video-adapter.ts | 4 +---
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/adapters/mux-audio/src/index.ts b/packages/adapters/mux-audio/src/index.ts
index d9bcc86b21..60641a57fa 100644
--- a/packages/adapters/mux-audio/src/index.ts
+++ b/packages/adapters/mux-audio/src/index.ts
@@ -5,6 +5,9 @@ export type { MuxSource, MuxVideoAdapterProps as MuxAudioAdapterProps } from '@v
 // TODO(mux): audio extending video is upside down. The hls.js-backed Mux behavior should move to a shared base that a
 // video and an audio adapter both extend; until then this class exists so audio installs by the media it plays and has
 // a home for audio-only behavior.
-export class MuxAudioAdapter extends MuxVideoAdapter {
-  static override readonly host = 'audio';
+// The video base names `'video'` as a literal, which a subclass cannot widen; the cast drops it from the static side.
+type MuxAudioBase = Omit<typeof MuxVideoAdapter, 'host'> & (new () => MuxVideoAdapter);
+
+export class MuxAudioAdapter extends (MuxVideoAdapter as MuxAudioBase) {
+  static readonly host = 'audio';
 }
diff --git a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
index a642e4ce7a..d1ba333baf 100644
--- a/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
+++ b/packages/media/src/dom/html-video-adapter/html-video-adapter.ts
@@ -23,9 +23,7 @@ export const videoContentAttributes: AttributeConfigs = {
 };
 
 export class HTMLVideoAdapter extends HTMLMediaAdapter<HTMLVideoTargetLike, VideoEvents> implements Video {
-  // Typed to admit `'audio'` so an adapter built on the video base can override it and play in an `<audio>`, as the
-  // hls.js-backed `MuxAudioAdapter` does. Element façades treat anything not narrowed to `'audio'` as a video.
-  static readonly host: 'video' | 'audio' = 'video';
+  static readonly host = 'video';
 
   get poster() {
     return getMediaProp(this, 'poster') ?? '';

From 198b97a89200fcfd6e31bef1f69cabaf2e631ead Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 17:55:09 -0700
Subject: [PATCH 21/25] fix(media): follow the review on media element
 attributes and events

Attributes:
- A boolean that defaults to `true` stays property-only. An absent HTML
  boolean attribute cannot mean `true`, so `<x playsinline>` could never turn
  it off and `el.playsInline = false` did nothing.
- A property from `defaultProps` owns its attribute by definition, so an
  adapter written with fields rather than accessors works; one exposed
  read-only only reflects, with a development warning.
- `defaultMuted` owns the `muted` attribute, as in HTML, and seeds the `muted`
  state with it. It used to write `muted` instead, so an embed that stores the
  two apart built an unmuted URL after `el.defaultMuted = true`.
- A number that does not parse falls back to the default.
- A target that arrives later gets every attribute already on the element
  replayed, and only a direct child of the host tag is adopted as `media`.

Surface:
- Forwarding copies `enumerable`, treats underscore-prefixed members as
  private, keeps `title` for the element, and reports other collisions in
  development.
- The event bridge forwards composed events an adapter raises itself, skipping
  only the adapter's copies of events its target dispatched, keeps a stable
  handler, and is torn down with the adapter.
- `MediaChildren` removes an attribute from the clone when it leaves the
  child, and can disconnect.
- `@videojs/media/dom` exports only the deliberate extension points.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../custom-media-element/attach-adapter.ts    |  22 ++-
 .../dom/custom-media-element/attributes.ts    | 115 ++++++++----
 .../custom-media-element.ts                   |  56 ++++--
 .../custom-media-element/element-surface.ts   | 134 +++++++++++---
 .../src/dom/custom-media-element/index.ts     |   9 +-
 .../custom-media-element/media-children.ts    |  12 +-
 .../tests/attributes.test.ts                  |   8 +-
 .../tests/custom-media-element.test.ts        | 173 +++++++++++++++++-
 .../tests/media-children.test.ts              |  23 +++
 .../html-media-adapter/html-media-adapter.ts  |  26 ++-
 10 files changed, 475 insertions(+), 103 deletions(-)

diff --git a/packages/media/src/dom/custom-media-element/attach-adapter.ts b/packages/media/src/dom/custom-media-element/attach-adapter.ts
index 2a46472e8b..7407e51ef8 100644
--- a/packages/media/src/dom/custom-media-element/attach-adapter.ts
+++ b/packages/media/src/dom/custom-media-element/attach-adapter.ts
@@ -8,26 +8,35 @@ export class AdapterAttachment {
   #host: HTMLElement;
   #adapter: PlaybackAdapter;
   #target: () => Element | null;
+  #onDestroy: (() => void) | undefined;
 
   /**
    * @param host - The custom element that owns the adapter.
    * @param adapter - The adapter to keep attached.
    * @param target - Resolves the element to attach to; re-run on every `attach()`.
+   * @param onDestroy - Runs after the adapter is destroyed, for whatever else the host tied to its lifetime.
    */
-  constructor(host: HTMLElement, adapter: PlaybackAdapter, target: () => Element | null) {
+  constructor(host: HTMLElement, adapter: PlaybackAdapter, target: () => Element | null, onDestroy?: () => void) {
     this.#host = host;
     this.#adapter = adapter;
     this.#target = target;
+    this.#onDestroy = onDestroy;
   }
 
-  /** Attach to the current target if it changed. Call after construction and whenever the target may have moved. */
-  attach(): void {
+  /**
+   * Attach to the current target if it changed. Call after construction and whenever the target may have moved.
+   *
+   * @returns Whether the adapter moved to a different target.
+   */
+  attach(): boolean {
     const target = this.#target();
-    if (target === this.#adapter.target) return;
+    if (target === this.#adapter.target) return false;
 
     if (this.#adapter.target) this.#adapter.detach();
 
     this.#adapter.attach(target);
+
+    return true;
   }
 
   /**
@@ -38,7 +47,10 @@ export class AdapterAttachment {
     if (this.#host.hasAttribute('keep-alive')) return;
 
     queueMicrotask(() => {
-      if (!this.#host.isConnected) this.#adapter.destroy();
+      if (this.#host.isConnected) return;
+
+      this.#adapter.destroy();
+      this.#onDestroy?.();
     });
   }
 }
diff --git a/packages/media/src/dom/custom-media-element/attributes.ts b/packages/media/src/dom/custom-media-element/attributes.ts
index 005c87c9d8..2cdee23613 100644
--- a/packages/media/src/dom/custom-media-element/attributes.ts
+++ b/packages/media/src/dom/custom-media-element/attributes.ts
@@ -4,15 +4,18 @@ import type { Constructor } from '@videojs/utils/types';
 
 import type { AttributeConfig, AttributeConfigs } from '../html-media-adapter';
 
-/** The WHATWG spellings for the media properties whose attribute is not their kebab-cased name. */
-export const mediaAttributeNames: Readonly<Record<string, string>> = {
-  autoPictureInPicture: 'autopictureinpicture',
-  controlsList: 'controlslist',
-  crossOrigin: 'crossorigin',
-  defaultMuted: 'muted',
-  disablePictureInPicture: 'disablepictureinpicture',
-  disableRemotePlayback: 'disableremoteplayback',
-  playsInline: 'playsinline',
+/**
+ * The media properties whose content attribute is not their kebab-cased name, plus the one attribute that seeds live
+ * state: a `muted` attribute is `defaultMuted` by the HTML spec, but the page that writes it means to start muted.
+ */
+export const mediaAttributeConfigs: Readonly<Record<string, Pick<AttributeConfig, 'attribute' | 'state'>>> = {
+  autoPictureInPicture: { attribute: 'autopictureinpicture' },
+  controlsList: { attribute: 'controlslist' },
+  crossOrigin: { attribute: 'crossorigin' },
+  defaultMuted: { attribute: 'muted', state: 'muted' },
+  disablePictureInPicture: { attribute: 'disablepictureinpicture' },
+  disableRemotePlayback: { attribute: 'disableremoteplayback' },
+  playsInline: { attribute: 'playsinline' },
 };
 
 /** Live playback state has no content attribute, even when an adapter lists a default for it. */
@@ -20,23 +23,28 @@ export const stateProps: ReadonlySet<string> = new Set(['muted', 'volume', 'curr
 
 /** The content attribute a property is driven by: its WHATWG spelling if it has one, else kebab-case. */
 export function attributeName(prop: string, config?: AttributeConfig): string {
-  return config?.attribute ?? mediaAttributeNames[prop] ?? kebabCase(prop);
+  return config?.attribute ?? mediaAttributeConfigs[prop]?.attribute ?? kebabCase(prop);
 }
 
 /**
  * The content attributes an adapter's `defaultProps` declare: one per primitive default, typed by that default and
- * reset to it when the attribute is removed. Object defaults such as `source` stay property-only.
+ * reset to it when the attribute is removed.
+ *
+ * Object defaults such as `source` stay property-only, and so does a boolean that defaults to `true`: an HTML boolean
+ * attribute cannot say "absent means true", so `<x playsinline>` could never turn it off.
  */
 export function derivedAttributes(defaultProps: object): AttributeConfigs {
   const configs: AttributeConfigs = {};
 
   for (const [prop, value] of Object.entries(defaultProps)) {
-    if (stateProps.has(prop)) continue;
+    if (stateProps.has(prop) || value === true) continue;
 
     const type = isBoolean(value) ? Boolean : isNumber(value) ? Number : isString(value) ? String : undefined;
     if (!type) continue;
 
-    configs[prop] = { type, attribute: attributeName(prop), empty: value };
+    const { state } = mediaAttributeConfigs[prop] ?? {};
+
+    configs[prop] = { type, attribute: attributeName(prop), empty: value, ...(state && { state }) };
   }
 
   return configs;
@@ -54,28 +62,40 @@ export function propsFromAttributes<Adapter extends { readonly defaultProps: obj
 
   for (const [prop, config] of Object.entries(derivedAttributes(Adapter.defaultProps))) {
     const attribute = config.attribute!;
+    if (!(attribute in attrs)) continue;
+
+    props[prop] = coerceAttribute(attrs[attribute]!, config);
 
-    if (attribute in attrs) props[prop] = coerceAttribute(attrs[attribute]!, config);
+    if (config.state && config.state in props) props[config.state] = props[prop];
   }
 
   return props as Adapter['defaultProps'];
 }
 
-/** Coerce an attribute string to the type its config declares. */
+/**
+ * Coerce an attribute string to the type its config declares. A removed attribute, or a number that does not parse,
+ * falls back to the config's `empty` value.
+ */
 export function coerceAttribute(value: string | null, config: AttributeConfig): unknown {
   if (config.type === Boolean) return value !== null;
 
-  if (value === null) return 'empty' in config ? config.empty : config.type === Number ? 0 : '';
+  const empty = 'empty' in config ? config.empty : config.type === Number ? 0 : '';
+
+  if (value === null) return empty;
+
+  if (config.type !== Number) return value;
 
-  return config.type === Number ? Number(value) : value;
+  const number = Number(value);
+
+  return Number.isNaN(number) ? empty : number;
 }
 
 /**
  * How an element routes its content attributes.
  *
- * An attribute whose property the adapter can set is owned by that property: the attribute writes the adapter, and the
- * property writes the attribute. `defaultMuted` declares `attribute: 'muted'`, but `muted` is a settable property in
- * its own right and owns that attribute, so the alias only reflects it.
+ * A property from `defaultProps` owns its attribute by definition: the attribute writes the adapter, and the property
+ * writes the attribute. A native attribute is owned by the adapter property of the same name when the adapter can set
+ * it, so an engine can intercept `preload`; otherwise the element reflects it and copies it onto the inner element.
  */
 export interface AttributeRoutes {
   /** Attribute names to observe, in declaration order. */
@@ -86,11 +106,20 @@ export interface AttributeRoutes {
   attributeOf: Map<string, string>;
   /** Config by attribute name, for coercion. */
   configOf: Map<string, AttributeConfig>;
-  /** Properties that only reflect their attribute: aliases and attributes the adapter has no setter for. */
+  /** Properties with no adapter counterpart to write: they only reflect their attribute. */
   reflected: Map<string, { attribute: string; config: AttributeConfig }>;
 }
 
-export function buildRoutes(configs: AttributeConfigs, Adapter: Constructor<object>): AttributeRoutes {
+/**
+ * @param native - The host element's own attributes, owned by the adapter only where it can set the property.
+ * @param derived - The adapter's declared attributes, owned by the adapter unless it exposes the property read-only.
+ * @param Adapter - The adapter class, for its prototype.
+ */
+export function buildRoutes(
+  native: AttributeConfigs,
+  derived: AttributeConfigs,
+  Adapter: Constructor<object>
+): AttributeRoutes {
   const routes: AttributeRoutes = {
     observed: [],
     ownerOf: new Map(),
@@ -98,35 +127,49 @@ export function buildRoutes(configs: AttributeConfigs, Adapter: Constructor<obje
     configOf: new Map(),
     reflected: new Map(),
   };
+  const configs: Record<string, { config: AttributeConfig; owned: boolean }> = {};
+
+  for (const [prop, config] of Object.entries(native)) {
+    configs[prop] = { config, owned: accessorOf(Adapter.prototype, prop)?.set !== undefined };
+  }
+
+  for (const [prop, config] of Object.entries(derived)) {
+    const accessor = accessorOf(Adapter.prototype, prop);
+    const readOnly = !!accessor?.get && !accessor.set;
+
+    if (__DEV__ && readOnly) {
+      console.warn(
+        `[videojs] ${Adapter.name}.defaultProps lists \`${prop}\`, but the adapter exposes it read-only; its attribute reflects without reaching the adapter.`
+      );
+    }
+
+    configs[prop] = { config, owned: !readOnly };
+  }
 
-  for (const [prop, config] of Object.entries(configs)) {
+  for (const [prop, { config, owned }] of Object.entries(configs)) {
     const attribute = attributeName(prop, config);
-    const alias =
-      config.attribute !== prop && hasSetter(Adapter.prototype, config.attribute) ? config.attribute : undefined;
-    const owner = alias ?? (hasSetter(Adapter.prototype, prop) ? prop : undefined);
 
     if (!routes.configOf.has(attribute)) routes.observed.push(attribute);
 
     routes.configOf.set(attribute, config);
 
-    if (owner) {
-      routes.ownerOf.set(attribute, owner);
-      routes.attributeOf.set(owner, attribute);
+    if (owned) {
+      routes.ownerOf.set(attribute, prop);
+      routes.attributeOf.set(prop, attribute);
+    } else {
+      routes.reflected.set(prop, { attribute, config });
     }
-
-    if (owner !== prop) routes.reflected.set(prop, { attribute, config });
   }
 
   return routes;
 }
 
-function hasSetter(prototype: object, prop: string | undefined): boolean {
-  if (!prop) return false;
-
+/** The accessor descriptor a prototype chain declares for a property, if any. */
+export function accessorOf(prototype: object, prop: string): PropertyDescriptor | undefined {
   for (let proto = prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
     const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
-    if (descriptor) return isFunction(descriptor.set);
+    if (descriptor) return isFunction(descriptor.get) || isFunction(descriptor.set) ? descriptor : undefined;
   }
 
-  return false;
+  return undefined;
 }
diff --git a/packages/media/src/dom/custom-media-element/custom-media-element.ts b/packages/media/src/dom/custom-media-element/custom-media-element.ts
index 862c8fd9a8..9ebe7e5c5f 100644
--- a/packages/media/src/dom/custom-media-element/custom-media-element.ts
+++ b/packages/media/src/dom/custom-media-element/custom-media-element.ts
@@ -5,7 +5,7 @@ import { type AdapterHost, type AttributeConfigs } from '../html-media-adapter';
 import { videoContentAttributes } from '../html-video-adapter';
 import { AdapterAttachment } from './attach-adapter';
 import { attributeName, buildRoutes, coerceAttribute, derivedAttributes } from './attributes';
-import { bridgeEvent, forwardAdapter, reflectAttributes } from './element-surface';
+import { bridgeEvent, forwardAdapter, reflectAttributes, unbridgeEvents } from './element-surface';
 import { MediaChildren } from './media-children';
 import { initialAttributes, renderHost } from './render-host';
 import { defaultTemplate, type MediaTemplate } from './templates';
@@ -56,8 +56,8 @@ const nativeAttributes: Record<AdapterHost, AttributeConfigs> = {
  *
  * The element renders the adapter's `host` in its shadow root, attaches the adapter to it, and is the adapter to its
  * callers: every method, accessor, and event comes through. Its content attributes are the host's native ones plus one
- * for each primitive in the adapter's `defaultProps`; an attribute the adapter can set writes the adapter, and any
- * other native attribute is copied onto the inner element. `<track>` and `<source>` children reach a native host too.
+ * for each primitive in the adapter's `defaultProps`; an attribute the adapter owns writes the adapter, and any other
+ * native attribute is copied onto the inner element. `<track>` and `<source>` children reach a native host too.
  *
  * @param Adapter - Adapter class with static `host` and `defaultProps`.
  * @param options - The shadow template, for elements that render more than the bare host.
@@ -70,7 +70,7 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
   const native = nativeAttributes[tag];
   const passthrough = tag !== 'iframe';
   const nativeNames = new Set(Object.entries(native).map(([prop, config]) => attributeName(prop, config)));
-  const routes = buildRoutes({ ...native, ...derivedAttributes(Adapter.defaultProps) }, Adapter);
+  const routes = buildRoutes(native, derivedAttributes(Adapter.defaultProps), Adapter);
 
   class CustomMedia extends (globalThis.HTMLElement ?? class {}) {
     static template = options.template ?? defaultTemplate(tag);
@@ -81,8 +81,16 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
     }
 
     #adapter = new Adapter();
-    #attachment = new AdapterAttachment(this, this.#adapter, () => this.target);
     #children = passthrough ? new MediaChildren(this, () => this.target) : null;
+    #attachment = new AdapterAttachment(
+      this,
+      this.#adapter,
+      () => this.target,
+      () => {
+        unbridgeEvents(this);
+        this.#children?.disconnect();
+      }
+    );
 
     constructor() {
       super();
@@ -91,7 +99,9 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
 
       this.#attachment.attach();
       this.shadowRoot!.addEventListener('slotchange', () => {
-        this.#attachment.attach();
+        // A target that arrives later has seen none of the attributes already on the element.
+        if (this.#attachment.attach()) this.#hydrate();
+
         this.#children?.sync();
       });
 
@@ -103,13 +113,13 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
     }
 
     /**
-     * The element the adapter plays through: a child slotted as `media`, else a child of the host's tag, else the one
-     * rendered in the shadow root. Only direct children count, so a `<video>` nested in slotted content is not
-     * adopted.
+     * The element the adapter plays through: a child of the host's tag slotted as `media`, else a child of the host's
+     * tag, else the one rendered in the shadow root. Only direct children of the right tag count, so a `<video>` nested
+     * in slotted content, or a `<div slot="media">`, is not adopted.
      */
     get target(): HTMLElement | null {
       return (
-        this.querySelector(`:scope > [slot=media]`) ??
+        this.querySelector(`:scope > ${tag}[slot=media]`) ??
         this.querySelector(`:scope > ${tag}`) ??
         this.shadowRoot?.querySelector(tag) ??
         null
@@ -137,10 +147,26 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
     }
 
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
+      if (oldValue !== newValue) this.#apply(name, newValue);
+    }
+
+    /** Replay every observed attribute onto the current target, after the target changed underneath them. */
+    #hydrate(): void {
+      for (const name of routes.observed) {
+        if (this.hasAttribute(name)) this.#apply(name, this.getAttribute(name));
+      }
+    }
+
+    #apply(name: string, value: string | null): void {
       const owner = routes.ownerOf.get(name);
 
       if (owner) {
-        if (oldValue !== newValue) this.#adapter[owner] = coerceAttribute(newValue, routes.configOf.get(name)!);
+        const config = routes.configOf.get(name)!;
+        const coerced = coerceAttribute(value, config);
+
+        this.#adapter[owner] = coerced;
+
+        if (config.state && config.state in this.#adapter) this.#adapter[config.state] = coerced;
 
         return;
       }
@@ -148,16 +174,16 @@ export function CustomMediaElement<T extends PlaybackAdapterConstructor>(
       // Anything else the host understands is the inner element's business; a subclass's own attributes are not.
       if (!passthrough || !nativeNames.has(name)) return;
 
-      if (newValue === null) {
+      if (value === null) {
         this.target?.removeAttribute(name);
-      } else if (this.target?.getAttribute(name) !== newValue) {
-        this.target?.setAttribute(name, newValue);
+      } else if (this.target?.getAttribute(name) !== value) {
+        this.target?.setAttribute(name, value);
       }
     }
   }
 
-  reflectAttributes(CustomMedia.prototype, routes);
   forwardAdapter(CustomMedia.prototype, Adapter, routes);
+  reflectAttributes(CustomMedia.prototype, routes);
 
   return CustomMedia as any;
 }
diff --git a/packages/media/src/dom/custom-media-element/element-surface.ts b/packages/media/src/dom/custom-media-element/element-surface.ts
index ebb36b150c..4cd94df5b4 100644
--- a/packages/media/src/dom/custom-media-element/element-surface.ts
+++ b/packages/media/src/dom/custom-media-element/element-surface.ts
@@ -1,6 +1,7 @@
 import { isFunction } from '@videojs/utils/predicate';
 import type { Constructor } from '@videojs/utils/types';
 
+import { isForwardedEvent } from '../html-media-adapter';
 import type { AttributeRoutes } from './attributes';
 import type { PlaybackAdapter } from './custom-media-element';
 
@@ -12,21 +13,47 @@ export interface AdapterElement extends HTMLElement {
 const excludedProperties = new Set(['constructor', 'attach', 'detach', 'destroy']);
 
 /**
- * Put the adapter's methods and accessors on the element prototype, so the element is the adapter to its callers.
+ * Adapter members the element keeps for itself. `title` is the element's tooltip; the media title stays reachable as
+ * `element.adapter.title`.
+ */
+const elementOwned = new Set(['title']);
+
+function writeThroughAttribute(element: HTMLElement, attribute: string, value: unknown): void {
+  if (value === true || value === false || value == null) {
+    element.toggleAttribute(attribute, Boolean(value));
+  } else {
+    element.setAttribute(attribute, String(value));
+  }
+}
+
+/**
+ * Put the adapter's public methods and accessors on the element prototype, so the element is the adapter to its
+ * callers.
  *
  * A setter whose property reflects through an attribute writes the attribute instead, and the attribute change reaches
- * the adapter; the property then holds one value whichever way it was set. Properties the routes mark as reflected are
- * left to `reflectAttributes`.
+ * the adapter; the property then holds one value whichever way it was set. Members the element already has, such as
+ * `addEventListener` or `title`, are left alone; in development, any other collision is reported. Underscore-prefixed
+ * members are treated as private.
  */
 export function forwardAdapter(prototype: object, Adapter: Constructor<object>, routes: AttributeRoutes): void {
+  const collisions: string[] = [];
+
   for (let proto = Adapter.prototype; proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    if (proto === EventTarget.prototype) break;
+
     for (const prop of Object.getOwnPropertyNames(proto)) {
-      if (prop in prototype || excludedProperties.has(prop) || routes.reflected.has(prop)) continue;
+      if (excludedProperties.has(prop) || prop.startsWith('_') || routes.reflected.has(prop)) continue;
+
+      if (prop in prototype) {
+        if (!elementOwned.has(prop) && !(prop in EventTarget.prototype)) collisions.push(prop);
+
+        continue;
+      }
 
       const descriptor = Object.getOwnPropertyDescriptor(proto, prop);
       if (!descriptor) continue;
 
-      const config: PropertyDescriptor = { enumerable: true, configurable: true };
+      const config: PropertyDescriptor = { enumerable: descriptor.enumerable ?? true, configurable: true };
 
       if (isFunction(descriptor.value)) {
         config.value = function (this: AdapterElement, ...args: unknown[]) {
@@ -41,24 +68,49 @@ export function forwardAdapter(prototype: object, Adapter: Constructor<object>,
 
         if (descriptor.set) {
           config.set = function (this: AdapterElement, value: unknown) {
-            if (!attribute) {
-              this.adapter[prop] = value;
-            } else if (value === true || value === false || value == null) {
-              this.toggleAttribute(attribute, Boolean(value));
+            if (attribute) {
+              writeThroughAttribute(this, attribute, value);
             } else {
-              this.setAttribute(attribute, String(value));
+              this.adapter[prop] = value;
             }
           };
         }
+      } else {
+        continue;
       }
 
       Object.defineProperty(prototype, prop, config);
     }
   }
+
+  if (__DEV__ && collisions.length > 0) {
+    console.warn(
+      `[videojs] ${Adapter.name} defines ${collisions.map((name) => `\`${name}\``).join(', ')}, which HTMLElement already has; the element's own member wins.`
+    );
+  }
 }
 
-/** Give the element an accessor for each property that only reflects its attribute. */
+/**
+ * Give the element an accessor for every routed property `forwardAdapter` did not: owned properties the adapter keeps
+ * as fields rather than accessors read the adapter and write the attribute, and reflected properties read and write the
+ * attribute alone.
+ */
 export function reflectAttributes(prototype: object, routes: AttributeRoutes): void {
+  for (const [prop, attribute] of routes.attributeOf) {
+    if (Object.hasOwn(prototype, prop)) continue;
+
+    Object.defineProperty(prototype, prop, {
+      get(this: AdapterElement) {
+        return this.adapter[prop];
+      },
+      set(this: AdapterElement, value: unknown) {
+        writeThroughAttribute(this, attribute, value);
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
   for (const [prop, { attribute, config }] of routes.reflected) {
     if (Object.hasOwn(prototype, prop)) continue;
 
@@ -67,11 +119,7 @@ export function reflectAttributes(prototype: object, routes: AttributeRoutes): v
         return config.type === Boolean ? this.hasAttribute(attribute) : this.getAttribute(attribute);
       },
       set(this: HTMLElement, value: unknown) {
-        if (config.type === Boolean) {
-          this.toggleAttribute(attribute, Boolean(value));
-        } else {
-          this.setAttribute(attribute, String(value));
-        }
+        writeThroughAttribute(this, attribute, config.type === Boolean ? Boolean(value) : value);
       },
       enumerable: true,
       configurable: true,
@@ -79,25 +127,55 @@ export function reflectAttributes(prototype: object, routes: AttributeRoutes): v
   }
 }
 
-const bridgedTypes = new WeakMap<AdapterElement, Set<string>>();
+interface Bridge {
+  handler: (event: Event) => void;
+  types: Set<string>;
+}
+
+const bridges = new WeakMap<AdapterElement, Bridge>();
+
+/** A copy of an event for re-dispatch, keeping the subclass and its init dictionary where the constructor allows it. */
+function cloneEvent(event: Event): Event {
+  try {
+    return new (event.constructor as typeof Event)(event.type, event);
+  } catch {
+    return new Event(event.type, event);
+  }
+}
 
 /**
  * Re-dispatch the adapter's events of one type on the element. Call it from `addEventListener`: the adapter is only
- * subscribed the first time someone listens for a type, and composed events are left alone since they already reach the
- * element through the shadow boundary.
+ * subscribed the first time someone listens for a type. An adapter's composed copy of an event its target dispatched
+ * already reached the element through the shadow boundary, so those are left alone; anything the adapter raises itself
+ * comes through, composed or not.
  */
 export function bridgeEvent(element: AdapterElement, type: string): void {
-  let types = bridgedTypes.get(element);
+  let bridge = bridges.get(element);
 
-  if (!types) {
-    types = new Set();
-    bridgedTypes.set(element, types);
+  if (!bridge) {
+    bridge = {
+      types: new Set(),
+      handler: (event) => {
+        if (event.composed && isForwardedEvent(event)) return;
+
+        element.dispatchEvent(cloneEvent(event));
+      },
+    };
+    bridges.set(element, bridge);
   }
 
-  if (types.has(type)) return;
+  if (bridge.types.has(type)) return;
+
+  bridge.types.add(type);
+  element.adapter.addEventListener(type, bridge.handler);
+}
+
+/** Stop re-dispatching the adapter's events. Call it when the adapter is destroyed. */
+export function unbridgeEvents(element: AdapterElement): void {
+  const bridge = bridges.get(element);
+  if (!bridge) return;
+
+  for (const type of bridge.types) element.adapter.removeEventListener(type, bridge.handler);
 
-  types.add(type);
-  element.adapter.addEventListener(type, (event: Event) => {
-    if (!event.composed) element.dispatchEvent(new (event.constructor as typeof Event)(event.type, event));
-  });
+  bridges.delete(element);
 }
diff --git a/packages/media/src/dom/custom-media-element/index.ts b/packages/media/src/dom/custom-media-element/index.ts
index 03cc80c24c..c81216aaaa 100644
--- a/packages/media/src/dom/custom-media-element/index.ts
+++ b/packages/media/src/dom/custom-media-element/index.ts
@@ -1,7 +1,6 @@
-export * from './attach-adapter';
-export * from './attributes';
+export { AdapterAttachment } from './attach-adapter';
+export { propsFromAttributes } from './attributes';
 export * from './custom-media-element';
-export * from './element-surface';
-export * from './media-children';
-export * from './render-host';
+export { MediaChildren } from './media-children';
+export { type HostElementConstructor, renderHost } from './render-host';
 export * from './templates';
diff --git a/packages/media/src/dom/custom-media-element/media-children.ts b/packages/media/src/dom/custom-media-element/media-children.ts
index c624c6971c..5de582b4d7 100644
--- a/packages/media/src/dom/custom-media-element/media-children.ts
+++ b/packages/media/src/dom/custom-media-element/media-children.ts
@@ -51,6 +51,12 @@ export class MediaChildren {
     }
   }
 
+  /** Stop following the children. Call it when the host is done for good; the clones are left where they are. */
+  disconnect(): void {
+    this.#observer.disconnect();
+    this.#clones.clear();
+  }
+
   #syncAttributes(mutations: MutationRecord[]): void {
     for (const { type, target, attributeName } of mutations) {
       if (type !== 'attributes' || !attributeName) continue;
@@ -59,7 +65,11 @@ export class MediaChildren {
       const clone = this.#clones.get(child);
       if (!clone) continue;
 
-      clone.setAttribute(attributeName, child.getAttribute(attributeName) ?? '');
+      const value = child.getAttribute(attributeName);
+
+      if (value === null) clone.removeAttribute(attributeName);
+      else clone.setAttribute(attributeName, value);
+
       enableDefaultTrack(clone);
     }
   }
diff --git a/packages/media/src/dom/custom-media-element/tests/attributes.test.ts b/packages/media/src/dom/custom-media-element/tests/attributes.test.ts
index 6665e80bc5..b34f4012ec 100644
--- a/packages/media/src/dom/custom-media-element/tests/attributes.test.ts
+++ b/packages/media/src/dom/custom-media-element/tests/attributes.test.ts
@@ -9,17 +9,18 @@ class EmbedAdapter {
     defaultMuted: false,
     muted: false,
     preload: 'metadata',
+    playsInline: true,
     volume: 1,
     source: null,
   };
 }
 
 describe('derivedAttributes', () => {
-  it('declares one attribute per primitive default, spelled the WHATWG way, and skips objects and playback state', () => {
+  it('declares one attribute per primitive default, spelled the WHATWG way, and skips objects, playback state, and booleans that default to true', () => {
     const configs = derivedAttributes(EmbedAdapter.defaultProps);
 
     expect(Object.keys(configs).sort()).toEqual(['autoplay', 'defaultMuted', 'preload', 'src']);
-    expect(configs.defaultMuted).toEqual({ type: Boolean, attribute: 'muted', empty: false });
+    expect(configs.defaultMuted).toEqual({ type: Boolean, attribute: 'muted', empty: false, state: 'muted' });
     expect(configs.preload).toEqual({ type: String, attribute: 'preload', empty: 'metadata' });
   });
 });
@@ -32,8 +33,9 @@ describe('propsFromAttributes', () => {
       src: 'https://example.com/x',
       autoplay: false,
       defaultMuted: true,
-      muted: false,
+      muted: true,
       preload: 'none',
+      playsInline: true,
       volume: 1,
       source: null,
     });
diff --git a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
index bde833256e..c3baa7bf8d 100644
--- a/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
+++ b/packages/media/src/dom/custom-media-element/tests/custom-media-element.test.ts
@@ -104,13 +104,22 @@ class TestAudioAdapter extends HTMLAudioAdapter {
 /** An embed adapter: no native element, so only its `defaultProps` become attributes. */
 class TestEmbedAdapter extends EventTarget {
   static readonly host = 'iframe' as const;
-  static readonly defaultProps = { src: '', autoplay: false, defaultMuted: false, muted: false, source: null };
+  static readonly defaultProps = {
+    src: '',
+    autoplay: false,
+    defaultMuted: false,
+    muted: false,
+    playsInline: true,
+    source: null,
+  };
 
   target: EventTarget | null = null;
 
   #src = '';
   #autoplay = false;
+  #defaultMuted = false;
   #muted = false;
+  #playsInline = true;
 
   get src() {
     return this.#src;
@@ -128,6 +137,14 @@ class TestEmbedAdapter extends EventTarget {
     this.#autoplay = value;
   }
 
+  get defaultMuted() {
+    return this.#defaultMuted;
+  }
+
+  set defaultMuted(value: boolean) {
+    this.#defaultMuted = value;
+  }
+
   get muted() {
     return this.#muted;
   }
@@ -136,6 +153,14 @@ class TestEmbedAdapter extends EventTarget {
     this.#muted = value;
   }
 
+  get playsInline() {
+    return this.#playsInline;
+  }
+
+  set playsInline(value: boolean) {
+    this.#playsInline = value;
+  }
+
   attach(target: EventTarget | null) {
     this.target = target;
   }
@@ -147,6 +172,28 @@ class TestEmbedAdapter extends EventTarget {
   destroy() {}
 }
 
+/** An adapter written with public fields rather than accessors, as a third party might. */
+class TestFieldAdapter extends HTMLVideoAdapter {
+  static readonly defaultProps = { src: '', debug: false, latencyMode: 'normal', bufferSeconds: 30 };
+
+  debug = false;
+  latencyMode = 'normal';
+  bufferSeconds = 30;
+
+  destroy() {}
+}
+
+/** An adapter that lists a read-only property among its defaults. */
+class TestReadOnlyAdapter extends HTMLVideoAdapter {
+  static readonly defaultProps = { src: '', engineName: 'test' };
+
+  get engineName() {
+    return 'test';
+  }
+
+  destroy() {}
+}
+
 let tagCounter = 0;
 
 function define<T extends CustomElementConstructor>(prefix: string, Ctor: T) {
@@ -161,6 +208,7 @@ const defineVideoElement = () => define('test-video', CustomMediaElement(TestVid
 const defineVideoElementWithOptions = () => define('test-video', CustomMediaElement(TestVideoAdapterWithOptions));
 const defineAudioElement = () => define('test-audio', CustomMediaElement(TestAudioAdapter));
 const defineEmbedElement = () => define('test-embed', CustomMediaElement(TestEmbedAdapter));
+const defineFieldElement = () => define('test-video', CustomMediaElement(TestFieldAdapter));
 
 function create(def: { Ctor: new () => any; tag: string }) {
   const el = new def.Ctor();
@@ -245,6 +293,31 @@ describe('CustomMediaElement', () => {
       expect(el.target).toBe(child);
     });
 
+    it('ignores a slotted element that is not the host tag', () => {
+      const el = create(defineVideoElement());
+      const div = document.createElement('div');
+
+      div.slot = 'media';
+      el.append(div);
+      expect(el.target).toBe(el.shadowRoot!.querySelector('video'));
+    });
+
+    it('replays the attributes already set onto a target that arrives later', () => {
+      const el = create(defineVideoElement());
+      const slotted = document.createElement('video');
+
+      el.setAttribute('controlslist', 'nodownload');
+      el.setAttribute('preload', 'none');
+      el.setAttribute('muted', '');
+      slotted.slot = 'media';
+      el.append(slotted);
+      el.shadowRoot!.querySelector('slot[name="media"]')!.dispatchEvent(new Event('slotchange', { bubbles: true }));
+
+      expect(slotted.getAttribute('controlslist')).toBe('nodownload');
+      expect(slotted.preload).toBe('none');
+      expect(slotted.muted).toBe(true);
+    });
+
     it('re-attaches the adapter when a slotted media element appears after construction', () => {
       const el = create(defineVideoElement());
       const shadowVideo = el.shadowRoot!.querySelector('video')!;
@@ -302,6 +375,18 @@ describe('CustomMediaElement', () => {
       expect(observed.sort()).toEqual(['autoplay', 'muted', 'src']);
     });
 
+    it('keeps a boolean that defaults to true property-only', () => {
+      // An HTML boolean attribute cannot say "absent means true", so `<x playsinline>` could never turn it off.
+      const el = create(defineEmbedElement());
+
+      expect(el.hasAttribute('playsinline')).toBe(false);
+      expect(el.playsInline).toBe(true);
+
+      el.playsInline = false;
+      expect(el.adapter.playsInline).toBe(false);
+      expect(el.hasAttribute('playsinline')).toBe(false);
+    });
+
     it('derives one attribute per primitive default and none for objects or playback state', () => {
       const observed = defineVideoElementWithOptions().Ctor.observedAttributes;
 
@@ -358,6 +443,39 @@ describe('CustomMediaElement', () => {
       expect(el.adapter.src).toBe('https://example.com/video.m3u8');
     });
 
+    it('reach an adapter that keeps them as fields rather than accessors', () => {
+      const el = create(defineFieldElement());
+
+      el.setAttribute('debug', '');
+      el.setAttribute('latency-mode', 'low');
+      expect(el.adapter.debug).toBe(true);
+      expect(el.adapter.latencyMode).toBe('low');
+
+      el.bufferSeconds = 60;
+      expect(el.getAttribute('buffer-seconds')).toBe('60');
+      expect(el.adapter.bufferSeconds).toBe(60);
+      expect(el.bufferSeconds).toBe(60);
+    });
+
+    it('only reflect a property the adapter exposes read-only', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const el = create(define('test-video', CustomMediaElement(TestReadOnlyAdapter)));
+
+      el.setAttribute('engine-name', 'other');
+
+      expect(el.adapter.engineName).toBe('test');
+      expect(el.engineName).toBe('other');
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('engineName'));
+      warn.mockRestore();
+    });
+
+    it('fall back to the default for a number that does not parse', () => {
+      const el = create(defineVideoElementWithOptions());
+
+      el.setAttribute('buffer-seconds', 'lots');
+      expect(el.adapter.bufferSeconds).toBe(30);
+    });
+
     it('do not reach the inner element', () => {
       const el = create(defineVideoElement());
 
@@ -429,16 +547,29 @@ describe('CustomMediaElement', () => {
       expect(el.target!.hasAttribute('crossorigin')).toBe(false);
     });
 
-    it('share the muted attribute between muted and defaultMuted', () => {
+    it('give the muted attribute to defaultMuted and seed the muted state with it', () => {
       const el = create(defineVideoElement());
 
-      el.defaultMuted = true;
-      expect(el.hasAttribute('muted')).toBe(true);
+      el.setAttribute('muted', '');
+      expect(el.defaultMuted).toBe(true);
       expect(el.muted).toBe(true);
 
+      // `muted` is live state, as in HTML: changing it leaves the attribute and `defaultMuted` alone.
       el.muted = false;
+      expect(el.hasAttribute('muted')).toBe(true);
+      expect(el.defaultMuted).toBe(true);
+
+      el.defaultMuted = false;
       expect(el.hasAttribute('muted')).toBe(false);
-      expect(el.defaultMuted).toBe(false);
+    });
+
+    it('write defaultMuted on an embed that stores it apart from muted', () => {
+      const el = create(defineEmbedElement());
+
+      el.defaultMuted = true;
+      expect(el.hasAttribute('muted')).toBe(true);
+      expect(el.adapter.defaultMuted).toBe(true);
+      expect(el.adapter.muted).toBe(true);
     });
 
     it('are rendered into the template at construction, minus the ones the adapter owns', () => {
@@ -453,9 +584,11 @@ describe('CustomMediaElement', () => {
       expect(video.getAttribute('poster')).toBe('poster.jpg');
       expect(video.getAttribute('crossorigin')).toBe('anonymous');
       expect(video.hasAttribute('src')).toBe(false);
-      expect(video.hasAttribute('muted')).toBe(false);
       expect(video.hasAttribute('class')).toBe(false);
       expect(video.hasAttribute('volume')).toBe(false);
+      // `muted` went through the adapter as `defaultMuted`, which the inner element reflects itself.
+      expect(video.defaultMuted).toBe(true);
+      expect(video.muted).toBe(true);
     });
 
     it('are not mirrored by an embed, whose template gets them all instead', () => {
@@ -559,6 +692,34 @@ describe('CustomMediaElement', () => {
       expect(handler).not.toHaveBeenCalled();
     });
 
+    it('forwards a composed event the adapter raises itself, and keeps the subclass and its detail', () => {
+      const el = create(defineVideoElement());
+      const custom = vi.fn();
+      const error = vi.fn();
+
+      el.addEventListener('adapterready', custom);
+      el.addEventListener('error', error);
+      el.adapter.dispatchEvent(new CustomEvent('adapterready', { composed: true, detail: { engine: 'x' } }));
+      el.adapter.dispatchEvent(new ErrorEvent('error', { message: 'boom' }));
+
+      expect(custom).toHaveBeenCalledOnce();
+      expect((custom.mock.calls[0]![0] as CustomEvent).detail).toEqual({ engine: 'x' });
+      expect(error).toHaveBeenCalledOnce();
+      expect((error.mock.calls[0]![0] as ErrorEvent).message).toBe('boom');
+    });
+
+    it('stops forwarding once the adapter is destroyed', async () => {
+      const el = create(defineVideoElement());
+      const handler = vi.fn();
+
+      el.addEventListener('play', handler);
+      el.remove();
+      await Promise.resolve();
+      el.adapter.dispatchEvent(new Event('play'));
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+
     it('delivers events dispatched on the element itself once', () => {
       const el = create(defineVideoElement());
       const handler = vi.fn();
diff --git a/packages/media/src/dom/custom-media-element/tests/media-children.test.ts b/packages/media/src/dom/custom-media-element/tests/media-children.test.ts
index 0ccac37350..bb46e60696 100644
--- a/packages/media/src/dom/custom-media-element/tests/media-children.test.ts
+++ b/packages/media/src/dom/custom-media-element/tests/media-children.test.ts
@@ -54,6 +54,29 @@ describe('MediaChildren', () => {
     expect(video.querySelector('source')?.getAttribute('src')).toBe('c.mp4');
   });
 
+  it('removes an attribute from the clone when it leaves the child', async () => {
+    const { host, video, children } = createHost();
+
+    host.innerHTML = '<track kind="chapters" default src="chapters.vtt" />';
+    children.sync();
+    host.querySelector('track')!.removeAttribute('default');
+    await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));
+
+    expect(video.querySelector('track')!.hasAttribute('default')).toBe(false);
+  });
+
+  it('stops following the children once disconnected', async () => {
+    const { host, video, children } = createHost();
+
+    host.innerHTML = '<source src="a.mp4" />';
+    children.sync();
+    children.disconnect();
+    host.querySelector('source')!.setAttribute('src', 'c.mp4');
+    await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));
+
+    expect(video.querySelector('source')?.getAttribute('src')).toBe('a.mp4');
+  });
+
   it('enables a default chapters track that the browser left disabled', () => {
     const { host, video, children } = createHost();
     const textTrack = { mode: 'disabled' };
diff --git a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
index 4fae6b968b..a6aedbeb04 100644
--- a/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
+++ b/packages/media/src/dom/html-media-adapter/html-media-adapter.ts
@@ -34,6 +34,11 @@ export interface AttributeConfig {
   attribute?: string;
   /** The value the property takes when the attribute is removed, when that is not the empty string. */
   empty?: unknown;
+  /**
+   * A live-state property written alongside the owner. A `muted` attribute is `defaultMuted` by the HTML spec, but the
+   * page that writes it means to start muted, so it steers `muted` too.
+   */
+  state?: string;
 }
 
 export type AttributeConfigs = Record<string, AttributeConfig>;
@@ -41,15 +46,15 @@ export type AttributeConfigs = Record<string, AttributeConfig>;
 /**
  * The content attributes every native media element accepts, keyed by the property that reflects each one.
  *
- * `defaultMuted` shares the `muted` attribute with the `muted` property, which owns it: a `<video muted>` starts muted,
- * and toggling the attribute later toggles playback muting the way the property does.
+ * `defaultMuted` owns the `muted` attribute, as in HTML, and seeds the `muted` state with it: a `<video muted>` starts
+ * muted, and toggling the attribute later mutes and unmutes the way the property does.
  */
 export const mediaContentAttributes: AttributeConfigs = {
   autoplay: { type: Boolean },
   controls: { type: Boolean },
   controlsList: { type: String },
   crossOrigin: { type: String, empty: null },
-  defaultMuted: { type: Boolean, attribute: 'muted' },
+  defaultMuted: { type: Boolean, attribute: 'muted', state: 'muted' },
   disableRemotePlayback: { type: Boolean },
   loading: { type: String },
   loop: { type: Boolean },
@@ -77,6 +82,16 @@ export interface MediaExtensions extends Map<MediaExtensionConstructor, MediaExt
   set<T extends MediaExtension>(component: MediaExtensionConstructor<T>, instance: T): this;
 }
 
+const forwardedEvents = new WeakSet<Event>();
+
+/**
+ * Whether an event is an adapter's copy of one its target element dispatched. A composed copy already reached any
+ * element wrapping the target through the shadow boundary, so a bridge can leave it alone.
+ */
+export function isForwardedEvent(event: Event): boolean {
+  return forwardedEvents.has(event);
+}
+
 export class HTMLMediaAdapter<Target extends HTMLMediaTargetLike, Events extends { [K in keyof Events]: EventLike }>
   extends EventTarget
   implements CommonMedia
@@ -157,7 +172,10 @@ export class HTMLMediaAdapter<Target extends HTMLMediaTargetLike, Events extends
   }
 
   #forwardEvent = (event: Event) => {
-    this.dispatchEvent(new (event.constructor as typeof Event)(event.type, event));
+    const copy = new (event.constructor as typeof Event)(event.type, event);
+
+    forwardedEvents.add(copy);
+    this.dispatchEvent(copy);
   };
 
   /**

From ed0bb45d42ea1833e873e54279b524bbfbf2d973 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 17:55:12 -0700
Subject: [PATCH 22/25] docs(site): keep true-by-default booleans out of the
 attribute reference

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 site/scripts/api-docs-builder/src/media-element-handler.ts | 7 +++++--
 site/src/content/docs/reference/create-media-element.mdx   | 2 +-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index 68835cc650..e4863c8b1f 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -1101,9 +1101,12 @@ function serializeDefault(expression: Expression, file: SourceFile, project: Oxc
 /** Live playback state has no content attribute, even when an adapter lists a default for it. */
 const STATE_PROPS = new Set(['muted', 'volume', 'currentTime', 'playbackRate']);
 
-/** Whether a serialized default is a boolean, number, or string, and so becomes an attribute. */
+/**
+ * Whether a serialized default becomes an attribute: a `false` boolean, a number, or a string. A boolean that defaults
+ * to `true` stays property-only, since an absent attribute cannot mean `true`.
+ */
 function isPrimitiveDefault(value: string): boolean {
-  return value === 'true' || value === 'false' || /^-?\d/.test(value) || /^['"`]/.test(value);
+  return value === 'false' || /^-?\d/.test(value) || /^['"`]/.test(value);
 }
 
 function primitiveTypeOf(value: string): string {
diff --git a/site/src/content/docs/reference/create-media-element.mdx b/site/src/content/docs/reference/create-media-element.mdx
index 7f7454eb08..25d368af1f 100644
--- a/site/src/content/docs/reference/create-media-element.mdx
+++ b/site/src/content/docs/reference/create-media-element.mdx
@@ -45,7 +45,7 @@ The template is also the element's static `template`, so a subclass can override
 
 ## Attributes
 
-Each primitive in the adapter's `defaultProps` becomes a content attribute of the same type, named by its WHATWG spelling where one exists and kebab-case otherwise: `src`, `preload`, `stream-type`. Removing the attribute resets the property to its default. Object properties such as `source` are property-only. This is the rule the React `createMediaComponent` factory applies to props, so both façades expose the same surface from one declaration.
+Each primitive in the adapter's `defaultProps` becomes a content attribute of the same type, named by its WHATWG spelling where one exists and kebab-case otherwise: `src`, `preload`, `stream-type`. Removing the attribute resets the property to its default. Object properties such as `source` stay property-only, and so does a boolean that defaults to `true`, since an absent attribute cannot mean `true`. The `muted` attribute belongs to `defaultMuted`, as in HTML, and seeds the `muted` state when it changes. This is the rule the React `createMediaComponent` factory applies to props, so both façades expose the same surface from one declaration.
 
 A `<video>` or `<audio>` host also accepts the attributes its native element understands, such as `controls`, `muted`, and `crossorigin`. Ones the adapter can set go through the adapter; the rest are copied onto the inner element. An `<iframe>` host accepts only what its adapter declares, since nothing is mirrored onto the frame.
 

From d384db144a956a30ca4f45121b998584b3ad5f1d Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Wed, 2 Sep 2026 16:59:55 -0700
Subject: [PATCH 23/25] feat(react): add createMediaComponent

`createMediaComponent(tag, Adapter, options?)` builds a component that renders
a native `<video>` or `<audio>`, drives it through one adapter instance, syncs
the adapter's props from React props against `Adapter.defaultProps`, forwards
everything else (and the ref) to the element, and registers with the Player.
The six built-in components that followed that exact shape now use it.

The media reference builder reads the target and defaults straight from the
factory call, so those components keep their generated React prop tables.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/index.ts                   |  12 ++
 .../src/media/cloudflare-video/adapter.tsx    |  91 +++++-------
 .../src/media/create-media-component.tsx      | 130 ++++++++++++++++++
 .../react/src/media/dash-video/adapter.tsx    |  30 ++--
 .../react/src/media/hls-audio/adapter.tsx     |  30 ++--
 .../react/src/media/hls-video/adapter.tsx     |  30 ++--
 .../react/src/media/hlsjs-video/adapter.tsx   |  33 ++---
 packages/react/src/media/mux-audio/hls-js.tsx |  42 ++----
 packages/react/src/media/mux-audio/spf.tsx    |  42 ++----
 packages/react/src/media/mux-video/hls-js.tsx |  44 ++----
 packages/react/src/media/mux-video/spf.tsx    |  44 ++----
 .../src/media/native-hls-video/adapter.tsx    |  33 ++---
 .../react/src/media/shaka-video/adapter.tsx   |  33 ++---
 .../react/src/media/spotify-audio/adapter.tsx |  90 ++++++------
 .../tests/create-media-component.test.tsx     | 104 ++++++++++++++
 .../react/src/media/tiktok-video/adapter.tsx  |  91 +++++-------
 .../react/src/media/twitch-video/adapter.tsx  |  92 ++++++-------
 .../react/src/media/vimeo-video/adapter.tsx   |  76 +++++-----
 .../react/src/media/youtube-video/adapter.tsx |  80 +++++------
 packages/react/src/utils/use-attach-iframe.ts |  15 --
 packages/react/src/utils/use-attach-media.ts  |   2 +-
 .../src/media-element-handler.ts              |  43 ++++++
 .../api-docs-builder/src/tests/e2e.test.ts    |   2 +-
 .../src/media/extending-video/adapter.tsx     |  26 ++--
 .../docs/reference/create-media-component.mdx |  52 +++++++
 site/src/docs.config.ts                       |   1 +
 26 files changed, 697 insertions(+), 571 deletions(-)
 create mode 100644 packages/react/src/media/create-media-component.tsx
 create mode 100644 packages/react/src/media/tests/create-media-component.test.tsx
 delete mode 100644 packages/react/src/utils/use-attach-iframe.ts
 create mode 100644 site/src/content/docs/reference/create-media-component.mdx

diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 40b5c895d2..619b5b58a1 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -169,6 +169,18 @@ export type { VolumeIndicatorValueProps } from './ui/volume-indicator/volume-ind
 export { VolumePopover } from './ui/volume-popover';
 export { VolumeSlider } from './ui/volume-slider';
 // Utilities
+export {
+  createMediaComponent,
+  type MediaAdapterConstructor,
+  type MediaAdapterProps,
+  type MediaAdapterTarget,
+  type MediaComponent,
+  type MediaComponentOptions,
+  type MediaComponentProps,
+  type MediaRenderArgs,
+  type MediaRenderFunction,
+  type MediaTargetAttributes,
+} from './media/create-media-component';
 export { mergeProps } from './utils/merge-props';
 export type { HTMLProps, RenderFunction, RenderProp, UIComponentProps } from './utils/types';
 export { useAttachMedia } from './utils/use-attach-media';
diff --git a/packages/react/src/media/cloudflare-video/adapter.tsx b/packages/react/src/media/cloudflare-video/adapter.tsx
index 729c6745d1..282096933d 100644
--- a/packages/react/src/media/cloudflare-video/adapter.tsx
+++ b/packages/react/src/media/cloudflare-video/adapter.tsx
@@ -1,62 +1,47 @@
 'use client';
 
-import { buildCloudflareIframeSrc, CloudflareAdapter, type CloudflareAdapterProps } from '@videojs/cloudflare-video';
-import { forwardRef, type ReactNode, useState } from 'react';
+import { buildCloudflareIframeSrc, CloudflareAdapter } from '@videojs/cloudflare-video';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface CloudflareVideoProps extends Partial<CloudflareAdapterProps> {
-  children?: ReactNode;
-}
+export type CloudflareVideoProps = MediaComponentProps<typeof CloudflareAdapter>;
 
-export const CloudflareVideo = forwardRef<HTMLIFrameElement, CloudflareVideoProps>(function CloudflareVideo(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(CloudflareAdapter);
-  const props: Partial<CloudflareAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // `source.src` is the only other way to name a video, so honor it when `src` is absent.
-    buildCloudflareIframeSrc(props.src || props.source?.src || '', {
-      ...CloudflareAdapter.defaultProps,
-      ...props,
-      // The embed reads mute once, out of the URL it is rendered with, and either
-      // prop says to start muted. Leaving `muted` out of the URL would leave a
-      // muted autoplay blocked by the browser, since the embed comes up audible.
-      defaultMuted: !!(props.defaultMuted || props.muted),
-    })
-  );
-  const iframeProps = useSyncProps<CloudflareAdapterProps, Record<string, unknown>>(
-    media,
-    props,
-    CloudflareAdapter.defaultProps
-  );
+export const CloudflareVideo = createMediaComponent(
+  CloudflareAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // `source.src` is the only other way to name a video, so honor it when `src` is absent.
+      buildCloudflareIframeSrc(initialProps.src || initialProps.source?.src || '', {
+        ...CloudflareAdapter.defaultProps,
+        ...initialProps,
+        // The embed reads mute once, out of the URL it is rendered with, and either
+        // prop says to start muted. Leaving `muted` out of the URL would leave a
+        // muted autoplay blocked by the browser, since the embed comes up audible.
+        defaultMuted: !!(initialProps.defaultMuted || initialProps.muted),
+      });
 
-  return (
-    <iframe
-      title="Cloudflare Stream video player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowFullScreen
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.cloudflare?.referrerPolicy}
-      {...iframeProps}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="Cloudflare Stream video player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+        allowFullScreen
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.cloudflare?.referrerPolicy}
+        {...props}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'CloudflareVideo' }
+);
 
 export namespace CloudflareVideo {
   export type Props = CloudflareVideoProps;
diff --git a/packages/react/src/media/create-media-component.tsx b/packages/react/src/media/create-media-component.tsx
new file mode 100644
index 0000000000..a305158bf2
--- /dev/null
+++ b/packages/react/src/media/create-media-component.tsx
@@ -0,0 +1,130 @@
+'use client';
+
+import type { EngineAdapter, Media } from '@videojs/media';
+import type {
+  AudioHTMLAttributes,
+  ForwardRefExoticComponent,
+  HTMLAttributes,
+  IframeHTMLAttributes,
+  PropsWithoutRef,
+  ReactNode,
+  RefAttributes,
+  RefCallback,
+  VideoHTMLAttributes,
+} from 'react';
+import { forwardRef, useState } from 'react';
+
+import { useAttachMedia } from '../utils/use-attach-media';
+import { useComposedRefs } from '../utils/use-composed-refs';
+import { useMediaInstance } from '../utils/use-media-instance';
+import { useSyncProps } from '../utils/use-sync-props';
+
+/** An adapter class: constructible without arguments, attachable to a target, with its defaults as a static. */
+export interface MediaAdapterConstructor {
+  new (): Media & EngineAdapter;
+  readonly defaultProps: object;
+}
+
+/** The element an adapter attaches to, read off its `attach()` signature. */
+export type MediaAdapterTarget<Adapter extends MediaAdapterConstructor> =
+  InstanceType<Adapter> extends { attach(target: infer Target): unknown } ? NonNullable<Target> : never;
+
+/** The adapter's props: the keys of its static `defaultProps`. */
+export type MediaAdapterProps<Adapter extends MediaAdapterConstructor> = Adapter['defaultProps'];
+
+/** The native attributes of the element an adapter attaches to. */
+export type MediaTargetAttributes<Target> = Target extends HTMLIFrameElement
+  ? IframeHTMLAttributes<HTMLIFrameElement>
+  : Target extends { readonly videoWidth: number }
+    ? VideoHTMLAttributes<HTMLVideoElement>
+    : Target extends { readonly volume: number }
+      ? AudioHTMLAttributes<HTMLAudioElement>
+      : HTMLAttributes<HTMLElement>;
+
+/** Props of a component built by `createMediaComponent`: the target's attributes plus the adapter's props. */
+export type MediaComponentProps<Adapter extends MediaAdapterConstructor> = Omit<
+  MediaTargetAttributes<MediaAdapterTarget<Adapter>>,
+  keyof MediaAdapterProps<Adapter>
+> &
+  Partial<MediaAdapterProps<Adapter>> & {
+    children?: ReactNode;
+  };
+
+/** What the render callback receives on every render. */
+export interface MediaRenderArgs<Adapter extends MediaAdapterConstructor> {
+  /** The adapter instance, already synced with this render's props. */
+  adapter: InstanceType<Adapter>;
+  /** Props left after the adapter's were synced onto it: the native attributes to spread on the target. */
+  props: Omit<MediaTargetAttributes<MediaAdapterTarget<Adapter>>, keyof MediaAdapterProps<Adapter>> &
+    Record<string, unknown>;
+  children: ReactNode;
+  /** Attaches the adapter to the rendered target and forwards the consumer's ref. Put it on the target. */
+  ref: RefCallback<MediaAdapterTarget<Adapter>>;
+  /**
+   * The adapter props from the first render, frozen. For values that must not change once rendered, such as an embed's
+   * initial `src`, derive them from these rather than from `adapter`.
+   */
+  initialProps: Readonly<Partial<MediaAdapterProps<Adapter>>>;
+}
+
+export type MediaRenderFunction<Adapter extends MediaAdapterConstructor> = (
+  args: MediaRenderArgs<Adapter>
+) => ReactNode;
+
+/** A component built by `createMediaComponent`, forwarding its ref to the rendered target. */
+export type MediaComponent<Adapter extends MediaAdapterConstructor> = ForwardRefExoticComponent<
+  PropsWithoutRef<MediaComponentProps<Adapter>> & RefAttributes<MediaAdapterTarget<Adapter>>
+>;
+
+export interface MediaComponentOptions {
+  /** Name shown in React DevTools. Defaults to the adapter's class name. */
+  displayName?: string;
+}
+
+/**
+ * Build a React component that drives a rendered target through an adapter and registers with the surrounding Player.
+ *
+ * The component creates one adapter instance, syncs the adapter's props from the React props of the same name (falling
+ * back to `Adapter.defaultProps` when a prop is omitted), and calls `render` with the adapter, the remaining native
+ * props, and a ref that attaches the adapter to whatever element it lands on. The target element is whatever `render`
+ * returns: a `<video>`, an `<audio>`, or an embed's `<iframe>`. It is what the built-in `HlsJsVideo`, `MuxVideo`, and
+ * `VimeoVideo` components are made of.
+ *
+ * @param Adapter - Adapter class with a static `defaultProps`, for example `HlsJsAdapter` from `@videojs/hlsjs-video`.
+ * @param render - Renders the target element from the adapter, the native props, the children, and the attach ref.
+ * @param options - `displayName` for React DevTools. Defaults to the adapter's class name.
+ */
+export function createMediaComponent<Adapter extends MediaAdapterConstructor>(
+  Adapter: Adapter,
+  render: MediaRenderFunction<Adapter>,
+  options: MediaComponentOptions = {}
+): MediaComponent<Adapter> {
+  type Props = MediaAdapterProps<Adapter>;
+  type Target = MediaAdapterTarget<Adapter>;
+
+  const Component = forwardRef<Target, MediaComponentProps<Adapter>>(function MediaComponent(allProps, ref) {
+    // The conditional attribute type keeps TypeScript from destructuring `children` off the generic props directly.
+    const { children, ...props } = allProps as { children?: ReactNode } & Record<string, unknown>;
+    const media = useMediaInstance(Adapter) as InstanceType<Adapter>;
+    const attachRef = useAttachMedia<Target>(media);
+    const composedRef = useComposedRefs(attachRef, ref);
+    const [initialProps] = useState(() => Object.freeze({ ...props }) as Readonly<Partial<Props>>);
+    const htmlProps = useSyncProps<Props, Record<string, unknown>>(
+      media as Props,
+      props as Partial<Props> & Record<string, unknown>,
+      Adapter.defaultProps as Props
+    );
+
+    return render({
+      adapter: media,
+      props: htmlProps as MediaRenderArgs<Adapter>['props'],
+      children,
+      ref: composedRef,
+      initialProps,
+    });
+  });
+
+  if (__DEV__) Component.displayName = options.displayName ?? Adapter.name;
+
+  return Component;
+}
diff --git a/packages/react/src/media/dash-video/adapter.tsx b/packages/react/src/media/dash-video/adapter.tsx
index bfbbdb7c4f..cb2fe5b1d1 100644
--- a/packages/react/src/media/dash-video/adapter.tsx
+++ b/packages/react/src/media/dash-video/adapter.tsx
@@ -1,30 +1,20 @@
 'use client';
 
-import { DashAdapter, type DashAdapterProps } from '@videojs/dash-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { DashAdapter } from '@videojs/dash-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface DashVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof DashAdapterProps>, Partial<DashAdapterProps> {
-  children?: ReactNode;
-}
-
-export const DashVideo = forwardRef<HTMLVideoElement, DashVideoProps>(function DashVideo({ children, ...props }, ref) {
-  const media = useMediaInstance(DashAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, DashAdapter.defaultProps);
+export type DashVideoProps = MediaComponentProps<typeof DashAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
+export const DashVideo = createMediaComponent(
+  DashAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
       {children}
     </video>
-  );
-});
+  ),
+  { displayName: 'DashVideo' }
+);
 
 export namespace DashVideo {
   export type Props = DashVideoProps;
diff --git a/packages/react/src/media/hls-audio/adapter.tsx b/packages/react/src/media/hls-audio/adapter.tsx
index e62498d6b2..4c8d935755 100644
--- a/packages/react/src/media/hls-audio/adapter.tsx
+++ b/packages/react/src/media/hls-audio/adapter.tsx
@@ -1,30 +1,20 @@
 'use client';
 
-import { HlsAudioAdapter, type HlsAudioAdapterProps } from '@videojs/spf/hls-audio';
-import { type AudioHTMLAttributes, forwardRef, type ReactNode } from 'react';
+import { HlsAudioAdapter } from '@videojs/spf/hls-audio';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface HlsAudioProps
-  extends Omit<AudioHTMLAttributes<HTMLAudioElement>, keyof HlsAudioAdapterProps>, Partial<HlsAudioAdapterProps> {
-  children?: ReactNode;
-}
-
-export const HlsAudio = forwardRef<HTMLAudioElement, HlsAudioProps>(function HlsAudio({ children, ...props }, ref) {
-  const media = useMediaInstance(HlsAudioAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, HlsAudioAdapter.defaultProps);
+export type HlsAudioProps = MediaComponentProps<typeof HlsAudioAdapter>;
 
-  return (
-    <audio ref={composedRef} {...htmlProps}>
+export const HlsAudio = createMediaComponent(
+  HlsAudioAdapter,
+  ({ props, children, ref }) => (
+    <audio {...props} ref={ref}>
       {children}
     </audio>
-  );
-});
+  ),
+  { displayName: 'HlsAudio' }
+);
 
 export namespace HlsAudio {
   export type Props = HlsAudioProps;
diff --git a/packages/react/src/media/hls-video/adapter.tsx b/packages/react/src/media/hls-video/adapter.tsx
index 088870c007..eb709a4626 100644
--- a/packages/react/src/media/hls-video/adapter.tsx
+++ b/packages/react/src/media/hls-video/adapter.tsx
@@ -1,30 +1,20 @@
 'use client';
 
-import { HlsVideoAdapter, type HlsVideoAdapterProps } from '@videojs/spf/hls-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { HlsVideoAdapter } from '@videojs/spf/hls-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface HlsVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof HlsVideoAdapterProps>, Partial<HlsVideoAdapterProps> {
-  children?: ReactNode;
-}
-
-export const HlsVideo = forwardRef<HTMLVideoElement, HlsVideoProps>(function HlsVideo({ children, ...props }, ref) {
-  const media = useMediaInstance(HlsVideoAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, HlsVideoAdapter.defaultProps);
+export type HlsVideoProps = MediaComponentProps<typeof HlsVideoAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
+export const HlsVideo = createMediaComponent(
+  HlsVideoAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
       {children}
     </video>
-  );
-});
+  ),
+  { displayName: 'HlsVideo' }
+);
 
 export namespace HlsVideo {
   export type Props = HlsVideoProps;
diff --git a/packages/react/src/media/hlsjs-video/adapter.tsx b/packages/react/src/media/hlsjs-video/adapter.tsx
index ef768ddae1..381e327062 100644
--- a/packages/react/src/media/hlsjs-video/adapter.tsx
+++ b/packages/react/src/media/hlsjs-video/adapter.tsx
@@ -1,33 +1,20 @@
 'use client';
 
-import { HlsJsAdapter, type HlsJsAdapterProps } from '@videojs/hlsjs-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { HlsJsAdapter } from '@videojs/hlsjs-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface HlsJsVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof HlsJsAdapterProps>, Partial<HlsJsAdapterProps> {
-  children?: ReactNode;
-}
-
-export const HlsJsVideo = forwardRef<HTMLVideoElement, HlsJsVideoProps>(function HlsJsVideo(
-  { children, ...props },
-  ref
-) {
-  const media = useMediaInstance(HlsJsAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, HlsJsAdapter.defaultProps);
+export type HlsJsVideoProps = MediaComponentProps<typeof HlsJsAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
+export const HlsJsVideo = createMediaComponent(
+  HlsJsAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
       {children}
     </video>
-  );
-});
+  ),
+  { displayName: 'HlsJsVideo' }
+);
 
 export namespace HlsJsVideo {
   export type Props = HlsJsVideoProps;
diff --git a/packages/react/src/media/mux-audio/hls-js.tsx b/packages/react/src/media/mux-audio/hls-js.tsx
index 61b55c6969..000d96f0cc 100644
--- a/packages/react/src/media/mux-audio/hls-js.tsx
+++ b/packages/react/src/media/mux-audio/hls-js.tsx
@@ -1,36 +1,22 @@
 'use client';
 
-import type { HlsJsAdapterProps } from '@videojs/hlsjs-video';
-import { MuxAudioAdapter, type MuxAudioAdapterProps } from '@videojs/mux-audio';
-import { type AudioHTMLAttributes, forwardRef, type ReactNode } from 'react';
+import { MuxAudioAdapter } from '@videojs/mux-audio';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-// `source` comes from `MuxAudioAdapterProps` only: `MuxSource` extends `HlsSource` with
-// Mux identity fields, so the narrower type has to win.
-export interface MuxAudioProps
-  extends
-    Omit<AudioHTMLAttributes<HTMLAudioElement>, keyof HlsJsAdapterProps | keyof MuxAudioAdapterProps>,
-    Partial<Omit<HlsJsAdapterProps, 'source'>>,
-    Partial<MuxAudioAdapterProps> {
-  children?: ReactNode;
-}
-
-export const MuxAudio = forwardRef<HTMLAudioElement, MuxAudioProps>(function MuxAudio({ children, ...props }, ref) {
-  const media = useMediaInstance(MuxAudioAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, MuxAudioAdapter.defaultProps);
+export type MuxAudioProps = MediaComponentProps<typeof MuxAudioAdapter>;
 
-  return (
-    <audio ref={composedRef} {...htmlProps}>
-      {children}
-    </audio>
-  );
-});
+export const MuxAudio = createMediaComponent(
+  MuxAudioAdapter,
+  ({ props, children, ref }) => {
+    return (
+      <audio ref={ref} {...props}>
+        {children}
+      </audio>
+    );
+  },
+  { displayName: 'MuxAudio' }
+);
 
 export namespace MuxAudio {
   export type Props = MuxAudioProps;
diff --git a/packages/react/src/media/mux-audio/spf.tsx b/packages/react/src/media/mux-audio/spf.tsx
index 6d15a2442e..d2b32f1efc 100644
--- a/packages/react/src/media/mux-audio/spf.tsx
+++ b/packages/react/src/media/mux-audio/spf.tsx
@@ -1,36 +1,22 @@
 'use client';
 
-import { type MuxAdapterProps, MuxAudioAdapter } from '@videojs/mux-audio/spf';
-import type { HlsAudioAdapterProps } from '@videojs/spf/hls-audio';
-import { type AudioHTMLAttributes, forwardRef, type ReactNode } from 'react';
+import { MuxAudioAdapter } from '@videojs/mux-audio/spf';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-// `src` and `source` come from `MuxAdapterProps`: the Mux Media owns both, and its
-// `source` is the structured Mux one rather than the generic engine's.
-export interface MuxAudioProps
-  extends
-    Omit<AudioHTMLAttributes<HTMLAudioElement>, keyof HlsAudioAdapterProps | keyof MuxAdapterProps>,
-    Partial<Omit<HlsAudioAdapterProps, 'src'>>,
-    Partial<MuxAdapterProps> {
-  children?: ReactNode;
-}
-
-export const MuxAudio = forwardRef<HTMLAudioElement, MuxAudioProps>(function MuxAudio({ children, ...props }, ref) {
-  const media = useMediaInstance(MuxAudioAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, MuxAudioAdapter.defaultProps);
+export type MuxAudioProps = MediaComponentProps<typeof MuxAudioAdapter>;
 
-  return (
-    <audio ref={composedRef} {...htmlProps}>
-      {children}
-    </audio>
-  );
-});
+export const MuxAudio = createMediaComponent(
+  MuxAudioAdapter,
+  ({ props, children, ref }) => {
+    return (
+      <audio ref={ref} {...props}>
+        {children}
+      </audio>
+    );
+  },
+  { displayName: 'MuxAudio' }
+);
 
 export namespace MuxAudio {
   export type Props = MuxAudioProps;
diff --git a/packages/react/src/media/mux-video/hls-js.tsx b/packages/react/src/media/mux-video/hls-js.tsx
index 95a94c4458..7c971aa49b 100644
--- a/packages/react/src/media/mux-video/hls-js.tsx
+++ b/packages/react/src/media/mux-video/hls-js.tsx
@@ -1,38 +1,24 @@
 'use client';
 
-import type { HlsJsAdapterProps } from '@videojs/hlsjs-video';
-import { MuxVideoAdapter, type MuxVideoAdapterProps } from '@videojs/mux-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { MuxVideoAdapter } from '@videojs/mux-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 import { MuxStoryboard } from './storyboard';
 
-// `source` comes from `MuxVideoAdapterProps` only: `MuxSource` extends `HlsSource` with
-// Mux identity fields, so the narrower type has to win.
-export interface MuxVideoProps
-  extends
-    Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof HlsJsAdapterProps | keyof MuxVideoAdapterProps>,
-    Partial<Omit<HlsJsAdapterProps, 'source'>>,
-    Partial<MuxVideoAdapterProps> {
-  children?: ReactNode;
-}
-
-export const MuxVideo = forwardRef<HTMLVideoElement, MuxVideoProps>(function MuxVideo({ children, ...props }, ref) {
-  const media = useMediaInstance(MuxVideoAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, MuxVideoAdapter.defaultProps);
+export type MuxVideoProps = MediaComponentProps<typeof MuxVideoAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
-      <MuxStoryboard media={media} />
-      {children}
-    </video>
-  );
-});
+export const MuxVideo = createMediaComponent(
+  MuxVideoAdapter,
+  ({ adapter, props, children, ref }) => {
+    return (
+      <video ref={ref} {...props}>
+        <MuxStoryboard media={adapter} />
+        {children}
+      </video>
+    );
+  },
+  { displayName: 'MuxVideo' }
+);
 
 export namespace MuxVideo {
   export type Props = MuxVideoProps;
diff --git a/packages/react/src/media/mux-video/spf.tsx b/packages/react/src/media/mux-video/spf.tsx
index eebb5894a2..580c70979e 100644
--- a/packages/react/src/media/mux-video/spf.tsx
+++ b/packages/react/src/media/mux-video/spf.tsx
@@ -1,38 +1,24 @@
 'use client';
 
-import { type MuxAdapterProps, MuxVideoAdapter } from '@videojs/mux-video/spf';
-import type { HlsVideoAdapterProps } from '@videojs/spf/hls-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { MuxVideoAdapter } from '@videojs/mux-video/spf';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 import { MuxStoryboard } from './storyboard';
 
-// `src` and `source` come from `MuxAdapterProps`: the Mux Media owns both, and its
-// `source` is the structured Mux one rather than the generic engine's.
-export interface MuxVideoProps
-  extends
-    Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof HlsVideoAdapterProps | keyof MuxAdapterProps>,
-    Partial<Omit<HlsVideoAdapterProps, 'src'>>,
-    Partial<MuxAdapterProps> {
-  children?: ReactNode;
-}
-
-export const MuxVideo = forwardRef<HTMLVideoElement, MuxVideoProps>(function MuxVideo({ children, ...props }, ref) {
-  const media = useMediaInstance(MuxVideoAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, MuxVideoAdapter.defaultProps);
+export type MuxVideoProps = MediaComponentProps<typeof MuxVideoAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
-      <MuxStoryboard media={media} />
-      {children}
-    </video>
-  );
-});
+export const MuxVideo = createMediaComponent(
+  MuxVideoAdapter,
+  ({ adapter, props, children, ref }) => {
+    return (
+      <video ref={ref} {...props}>
+        <MuxStoryboard media={adapter} />
+        {children}
+      </video>
+    );
+  },
+  { displayName: 'MuxVideo' }
+);
 
 export namespace MuxVideo {
   export type Props = MuxVideoProps;
diff --git a/packages/react/src/media/native-hls-video/adapter.tsx b/packages/react/src/media/native-hls-video/adapter.tsx
index b1abefa9ac..3daa886cdd 100644
--- a/packages/react/src/media/native-hls-video/adapter.tsx
+++ b/packages/react/src/media/native-hls-video/adapter.tsx
@@ -1,33 +1,20 @@
 'use client';
 
-import { NativeHlsAdapter, type NativeHlsAdapterProps } from '@videojs/native-hls-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { NativeHlsAdapter } from '@videojs/native-hls-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface NativeHlsVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof NativeHlsAdapterProps>, Partial<NativeHlsAdapterProps> {
-  children?: ReactNode;
-}
-
-export const NativeHlsVideo = forwardRef<HTMLVideoElement, NativeHlsVideoProps>(function NativeHlsVideo(
-  { children, ...props },
-  ref
-) {
-  const media = useMediaInstance(NativeHlsAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, NativeHlsAdapter.defaultProps);
+export type NativeHlsVideoProps = MediaComponentProps<typeof NativeHlsAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
+export const NativeHlsVideo = createMediaComponent(
+  NativeHlsAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
       {children}
     </video>
-  );
-});
+  ),
+  { displayName: 'NativeHlsVideo' }
+);
 
 export namespace NativeHlsVideo {
   export type Props = NativeHlsVideoProps;
diff --git a/packages/react/src/media/shaka-video/adapter.tsx b/packages/react/src/media/shaka-video/adapter.tsx
index cc8b21e558..7feac53756 100644
--- a/packages/react/src/media/shaka-video/adapter.tsx
+++ b/packages/react/src/media/shaka-video/adapter.tsx
@@ -1,33 +1,20 @@
 'use client';
 
-import { ShakaAdapter, type ShakaAdapterProps } from '@videojs/shaka-video';
-import { forwardRef, type ReactNode, type VideoHTMLAttributes } from 'react';
+import { ShakaAdapter } from '@videojs/shaka-video';
 
-import { useAttachMedia } from '../../utils/use-attach-media';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface ShakaVideoProps
-  extends Omit<VideoHTMLAttributes<HTMLVideoElement>, keyof ShakaAdapterProps>, Partial<ShakaAdapterProps> {
-  children?: ReactNode;
-}
-
-export const ShakaVideo = forwardRef<HTMLVideoElement, ShakaVideoProps>(function ShakaVideo(
-  { children, ...props },
-  ref
-) {
-  const media = useMediaInstance(ShakaAdapter);
-  const attachRef = useAttachMedia(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const htmlProps = useSyncProps(media, props, ShakaAdapter.defaultProps);
+export type ShakaVideoProps = MediaComponentProps<typeof ShakaAdapter>;
 
-  return (
-    <video ref={composedRef} {...htmlProps}>
+export const ShakaVideo = createMediaComponent(
+  ShakaAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
       {children}
     </video>
-  );
-});
+  ),
+  { displayName: 'ShakaVideo' }
+);
 
 export namespace ShakaVideo {
   export type Props = ShakaVideoProps;
diff --git a/packages/react/src/media/spotify-audio/adapter.tsx b/packages/react/src/media/spotify-audio/adapter.tsx
index b713821c56..6caf613402 100644
--- a/packages/react/src/media/spotify-audio/adapter.tsx
+++ b/packages/react/src/media/spotify-audio/adapter.tsx
@@ -1,59 +1,49 @@
 'use client';
 
-import { buildSpotifyIframeSrc, SpotifyAdapter, type SpotifyAdapterProps } from '@videojs/spotify-audio';
-import { type CSSProperties, forwardRef, type ReactNode, useState } from 'react';
+import { buildSpotifyIframeSrc, SpotifyAdapter } from '@videojs/spotify-audio';
+import type { CSSProperties } from 'react';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface SpotifyAudioProps extends Partial<SpotifyAdapterProps> {
-  children?: ReactNode;
-}
+export type SpotifyAudioProps = MediaComponentProps<typeof SpotifyAdapter>;
 
-export const SpotifyAudio = forwardRef<HTMLIFrameElement, SpotifyAudioProps>(function SpotifyAudio(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(SpotifyAdapter);
-  const props: Partial<SpotifyAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // `source.src` is the only other way to name an entity, so honor it when `src` is absent.
-    buildSpotifyIframeSrc(props.src || props.source?.src || '', { ...SpotifyAdapter.defaultProps, ...props })
-  );
-  const { style, ...iframeProps } = useSyncProps<SpotifyAdapterProps, Record<string, unknown>>(
-    media,
-    props,
-    SpotifyAdapter.defaultProps
-  ) as Record<string, unknown> & { style?: CSSProperties };
+export const SpotifyAudio = createMediaComponent(
+  SpotifyAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // `source.src` is the only other way to name an entity, so honor it when `src` is absent.
+      buildSpotifyIframeSrc(initialProps.src || initialProps.source?.src || '', {
+        ...SpotifyAdapter.defaultProps,
+        ...initialProps,
+      });
+    const { style, ...iframeProps } = props as Record<string, unknown> & { style?: CSSProperties };
 
-  return (
-    <iframe
-      title="Spotify audio player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.spotify?.referrerPolicy}
-      {...iframeProps}
-      // Without Spotify's own chrome the embed is a transport and nothing else:
-      // its player UI would otherwise show through whatever skin is drawn over it.
-      // Inline so a `className` cannot put it back on screen, merged so a
-      // consumer's own styles survive. A hidden iframe still loads and plays.
-      style={props.controls ? style : { ...style, display: 'none' }}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="Spotify audio player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.spotify?.referrerPolicy}
+        {...iframeProps}
+        // Without Spotify's own chrome the embed is a transport and nothing else:
+        // its player UI would otherwise show through whatever skin is drawn over it.
+        // Inline so a `className` cannot put it back on screen, merged so a
+        // consumer's own styles survive. A hidden iframe still loads and plays.
+        style={adapter.controls ? style : { ...style, display: 'none' }}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'SpotifyAudio' }
+);
 
 export namespace SpotifyAudio {
   export type Props = SpotifyAudioProps;
diff --git a/packages/react/src/media/tests/create-media-component.test.tsx b/packages/react/src/media/tests/create-media-component.test.tsx
new file mode 100644
index 0000000000..c26f771623
--- /dev/null
+++ b/packages/react/src/media/tests/create-media-component.test.tsx
@@ -0,0 +1,104 @@
+import { render } from '@testing-library/react';
+import { HTMLAudioAdapter, HTMLMediaAdapter, HTMLVideoAdapter } from '@videojs/media/dom';
+import { createRef } from 'react';
+import { describe, expect, it, vi } from 'vite-plus/test';
+
+import { createMediaComponent } from '../create-media-component';
+
+class FakeAdapter extends HTMLVideoAdapter {
+  static readonly defaultProps = { src: '', debug: false };
+
+  readonly engine = null;
+
+  #src = '';
+  debug = false;
+
+  get src() {
+    return this.#src;
+  }
+
+  set src(value: string) {
+    this.#src = value;
+  }
+}
+
+class FakeAudioAdapter extends HTMLAudioAdapter {
+  static readonly defaultProps = { src: '' };
+
+  readonly engine = null;
+}
+
+const Video = createMediaComponent(
+  FakeAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
+      {children}
+    </video>
+  ),
+  { displayName: 'FakeVideo' }
+);
+
+describe('createMediaComponent', () => {
+  it('renders what the callback returns and attaches the adapter to it', () => {
+    const attach = vi.spyOn(HTMLMediaAdapter.prototype, 'attach');
+    const Audio = createMediaComponent(FakeAudioAdapter, ({ props, ref }) => <audio {...props} ref={ref} />);
+
+    const { container } = render(
+      <>
+        <Video data-testid="video">
+          <track kind="captions" />
+        </Video>
+        <Audio data-testid="audio" />
+      </>
+    );
+
+    expect(container.querySelector('video')?.getAttribute('data-testid')).toBe('video');
+    expect(container.querySelector('video track')).not.toBeNull();
+    expect(container.querySelector('audio')?.getAttribute('data-testid')).toBe('audio');
+    expect(attach).toHaveBeenCalledWith(container.querySelector('video'));
+    expect(attach).toHaveBeenCalledWith(container.querySelector('audio'));
+
+    attach.mockRestore();
+  });
+
+  it('syncs adapter props onto the adapter and forwards the rest to the element', () => {
+    const src = vi.spyOn(FakeAdapter.prototype, 'src', 'set');
+
+    const { container } = render(<Video src="https://example.com/video.m3u8" debug controls />);
+
+    expect(src).toHaveBeenCalledWith('https://example.com/video.m3u8');
+    expect((src.mock.contexts[0] as FakeAdapter).debug).toBe(true);
+    expect(container.querySelector('video')?.hasAttribute('src')).toBe(false);
+    expect(container.querySelector('video')?.hasAttribute('controls')).toBe(true);
+
+    src.mockRestore();
+  });
+
+  it('hands the callback the adapter and the frozen first-render props', () => {
+    const seen: Array<{ initialSrc: string | undefined; adapterSrc: string }> = [];
+    const Component = createMediaComponent(FakeAdapter, ({ adapter, initialProps, props, ref }) => {
+      seen.push({ initialSrc: initialProps.src, adapterSrc: adapter.src });
+
+      return <video {...props} ref={ref} />;
+    });
+
+    const { rerender } = render(<Component src="first.m3u8" />);
+
+    rerender(<Component src="second.m3u8" />);
+
+    expect(seen.map((entry) => entry.initialSrc)).toEqual(['first.m3u8', 'first.m3u8']);
+    expect(seen.map((entry) => entry.adapterSrc)).toEqual(['first.m3u8', 'second.m3u8']);
+  });
+
+  it('forwards the ref to the rendered element and names the component', () => {
+    const ref = createRef<HTMLVideoElement>();
+
+    render(<Video ref={ref} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLVideoElement);
+    expect(Video.displayName).toBe('FakeVideo');
+    expect(createMediaComponent(FakeAdapter, ({ props, ref }) => <video {...props} ref={ref} />).displayName).toBe(
+      'FakeAdapter'
+    );
+  });
+});
diff --git a/packages/react/src/media/tiktok-video/adapter.tsx b/packages/react/src/media/tiktok-video/adapter.tsx
index dde6ac17c2..76952d8e55 100644
--- a/packages/react/src/media/tiktok-video/adapter.tsx
+++ b/packages/react/src/media/tiktok-video/adapter.tsx
@@ -1,62 +1,47 @@
 'use client';
 
-import { buildTikTokIframeSrc, TikTokAdapter, type TikTokAdapterProps } from '@videojs/tiktok-video';
-import { forwardRef, type ReactNode, useState } from 'react';
+import { buildTikTokIframeSrc, TikTokAdapter } from '@videojs/tiktok-video';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface TikTokVideoProps extends Partial<TikTokAdapterProps> {
-  children?: ReactNode;
-}
+export type TikTokVideoProps = MediaComponentProps<typeof TikTokAdapter>;
 
-export const TikTokVideo = forwardRef<HTMLIFrameElement, TikTokVideoProps>(function TikTokVideo(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(TikTokAdapter);
-  const props: Partial<TikTokAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // `source.src` is the only other way to name a video, so honor it when `src` is absent.
-    buildTikTokIframeSrc(props.src || props.source?.src || '', {
-      ...TikTokAdapter.defaultProps,
-      ...props,
-      // The frame reads mute once, out of the URL it is rendered with, and either
-      // prop says to start muted. Rendering it any other way than the media
-      // builds it would have the media rebuild the frame on mount.
-      defaultMuted: !!(props.defaultMuted || props.muted),
-    })
-  );
-  const iframeProps = useSyncProps<TikTokAdapterProps, Record<string, unknown>>(
-    media,
-    props,
-    TikTokAdapter.defaultProps
-  );
+export const TikTokVideo = createMediaComponent(
+  TikTokAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // `source.src` is the only other way to name a video, so honor it when `src` is absent.
+      buildTikTokIframeSrc(initialProps.src || initialProps.source?.src || '', {
+        ...TikTokAdapter.defaultProps,
+        ...initialProps,
+        // The frame reads mute once, out of the URL it is rendered with, and either
+        // prop says to start muted. Rendering it any other way than the media
+        // builds it would have the media rebuild the frame on mount.
+        defaultMuted: !!(initialProps.defaultMuted || initialProps.muted),
+      });
 
-  return (
-    <iframe
-      title="TikTok video player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowFullScreen
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.tiktok?.referrerPolicy}
-      {...iframeProps}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="TikTok video player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+        allowFullScreen
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.tiktok?.referrerPolicy}
+        {...props}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'TikTokVideo' }
+);
 
 export namespace TikTokVideo {
   export type Props = TikTokVideoProps;
diff --git a/packages/react/src/media/twitch-video/adapter.tsx b/packages/react/src/media/twitch-video/adapter.tsx
index ee98f83ba5..37bb389173 100644
--- a/packages/react/src/media/twitch-video/adapter.tsx
+++ b/packages/react/src/media/twitch-video/adapter.tsx
@@ -1,61 +1,49 @@
 'use client';
 
-import { buildTwitchIframeSrc, TwitchAdapter, type TwitchAdapterProps } from '@videojs/twitch-video';
-import { forwardRef, type ReactNode, useState } from 'react';
+import { buildTwitchIframeSrc, TwitchAdapter } from '@videojs/twitch-video';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface TwitchVideoProps extends Partial<TwitchAdapterProps> {
-  children?: ReactNode;
-}
+export type TwitchVideoProps = MediaComponentProps<typeof TwitchAdapter>;
 
-export const TwitchVideo = forwardRef<HTMLIFrameElement, TwitchVideoProps>(function TwitchVideo(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(TwitchAdapter);
-  const props: Partial<TwitchAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // Server rendering has no `location` to name as the embed's parent, and Twitch
-    // refuses to play in a page its URL never named. Rendering no `src` leaves the
-    // URL to `attach()`, which builds it where there is a hostname to name.
-    globalThis.location
-      ? // `source.src` is the only other way to name a video, so honor it when `src` is absent.
-        buildTwitchIframeSrc(props.src || props.source?.src || '', { ...TwitchAdapter.defaultProps, ...props })
-      : ''
-  );
-  const iframeProps = useSyncProps<TwitchAdapterProps, Record<string, unknown>>(
-    media,
-    props,
-    TwitchAdapter.defaultProps
-  );
+export const TwitchVideo = createMediaComponent(
+  TwitchAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // Server rendering has no `location` to name as the embed's parent, and Twitch
+      // refuses to play in a page its URL never named. Rendering no `src` leaves the
+      // URL to `attach()`, which builds it where there is a hostname to name.
+      globalThis.location
+        ? // `source.src` is the only other way to name a video, so honor it when `src` is absent.
+          buildTwitchIframeSrc(initialProps.src || initialProps.source?.src || '', {
+            ...TwitchAdapter.defaultProps,
+            ...initialProps,
+          })
+        : '';
 
-  return (
-    <iframe
-      title="Twitch video player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;"
-      sandbox="allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
-      scrolling="no"
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.twitch?.referrerPolicy}
-      {...iframeProps}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="Twitch video player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="accelerometer; fullscreen; autoplay; encrypted-media; picture-in-picture;"
+        sandbox="allow-modals allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
+        scrolling="no"
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.twitch?.referrerPolicy}
+        {...props}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'TwitchVideo' }
+);
 
 export namespace TwitchVideo {
   export type Props = TwitchVideoProps;
diff --git a/packages/react/src/media/vimeo-video/adapter.tsx b/packages/react/src/media/vimeo-video/adapter.tsx
index cfdef6e84c..7e61171e6e 100644
--- a/packages/react/src/media/vimeo-video/adapter.tsx
+++ b/packages/react/src/media/vimeo-video/adapter.tsx
@@ -1,51 +1,43 @@
 'use client';
 
-import { buildVimeoIframeSrc, VimeoAdapter, type VimeoAdapterProps } from '@videojs/vimeo-video';
-import { forwardRef, type ReactNode, useState } from 'react';
+import { buildVimeoIframeSrc, VimeoAdapter } from '@videojs/vimeo-video';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface VimeoVideoProps extends Partial<VimeoAdapterProps> {
-  children?: ReactNode;
-}
+export type VimeoVideoProps = MediaComponentProps<typeof VimeoAdapter>;
 
-export const VimeoVideo = forwardRef<HTMLIFrameElement, VimeoVideoProps>(function VimeoVideo(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(VimeoAdapter);
-  const props: Partial<VimeoAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // `source.src` is the only other way to name a video, so honor it when `src` is absent.
-    buildVimeoIframeSrc(props.src || props.source?.src || '', { ...VimeoAdapter.defaultProps, ...props })
-  );
-  const iframeProps = useSyncProps<VimeoAdapterProps, Record<string, unknown>>(media, props, VimeoAdapter.defaultProps);
+export const VimeoVideo = createMediaComponent(
+  VimeoAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // `source.src` is the only other way to name a video, so honor it when `src` is absent.
+      buildVimeoIframeSrc(initialProps.src || initialProps.source?.src || '', {
+        ...VimeoAdapter.defaultProps,
+        ...initialProps,
+      });
 
-  return (
-    <iframe
-      title="Vimeo video player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowFullScreen
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.vimeo?.referrerPolicy}
-      {...iframeProps}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="Vimeo video player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+        allowFullScreen
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.vimeo?.referrerPolicy}
+        {...props}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'VimeoVideo' }
+);
 
 export namespace VimeoVideo {
   export type Props = VimeoVideoProps;
diff --git a/packages/react/src/media/youtube-video/adapter.tsx b/packages/react/src/media/youtube-video/adapter.tsx
index cd30416e93..0d9cfff121 100644
--- a/packages/react/src/media/youtube-video/adapter.tsx
+++ b/packages/react/src/media/youtube-video/adapter.tsx
@@ -1,55 +1,43 @@
 'use client';
 
-import { buildYouTubeIframeSrc, YouTubeAdapter, type YouTubeAdapterProps } from '@videojs/youtube-video';
-import { forwardRef, type ReactNode, useState } from 'react';
+import { buildYouTubeIframeSrc, YouTubeAdapter } from '@videojs/youtube-video';
 
-import { useAttachIframe } from '../../utils/use-attach-iframe';
-import { useComposedRefs } from '../../utils/use-composed-refs';
-import { useMediaInstance } from '../../utils/use-media-instance';
-import { useSyncProps } from '../../utils/use-sync-props';
+import { createMediaComponent, type MediaComponentProps } from '../create-media-component';
 
-export interface YouTubeVideoProps extends Partial<YouTubeAdapterProps> {
-  children?: ReactNode;
-}
+export type YouTubeVideoProps = MediaComponentProps<typeof YouTubeAdapter>;
 
-export const YouTubeVideo = forwardRef<HTMLIFrameElement, YouTubeVideoProps>(function YouTubeVideo(
-  { children, ...rawProps },
-  ref
-) {
-  const media = useMediaInstance(YouTubeAdapter);
-  const props: Partial<YouTubeAdapterProps> & Record<string, unknown> = { ...rawProps };
-  const attachRef = useAttachIframe(media);
-  const composedRef = useComposedRefs(attachRef, ref);
-  const [initialSrc] = useState(() =>
-    // `source.src` is the only other way to name a video, so honor it when `src` is absent.
-    buildYouTubeIframeSrc(props.src || props.source?.src || '', { ...YouTubeAdapter.defaultProps, ...props })
-  );
-  const iframeProps = useSyncProps<YouTubeAdapterProps, Record<string, unknown>>(
-    media,
-    props,
-    YouTubeAdapter.defaultProps
-  );
+export const YouTubeVideo = createMediaComponent(
+  YouTubeAdapter,
+  ({ adapter, props, children, ref, initialProps }) => {
+    const initialSrc =
+      // `source.src` is the only other way to name a video, so honor it when `src` is absent.
+      buildYouTubeIframeSrc(initialProps.src || initialProps.source?.src || '', {
+        ...YouTubeAdapter.defaultProps,
+        ...initialProps,
+      });
 
-  return (
-    <iframe
-      title="YouTube video player"
-      // Empty means there is no embed to point at yet; React warns about `src=""`,
-      // and the media builds the URL itself once a source resolves.
-      src={initialSrc || undefined}
-      data-cross-origin-frame
-      allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
-      allowFullScreen
-      frameBorder={0}
-      width="100%"
-      height="100%"
-      referrerPolicy={props.source?.engine?.youtube?.referrerPolicy}
-      {...iframeProps}
-      ref={composedRef}
-    >
-      {children}
-    </iframe>
-  );
-});
+    return (
+      <iframe
+        title="YouTube video player"
+        // Empty means there is no embed to point at yet; React warns about `src=""`,
+        // and the media builds the URL itself once a source resolves.
+        src={initialSrc || undefined}
+        data-cross-origin-frame
+        allow="accelerometer; fullscreen; autoplay; encrypted-media; gyroscope; picture-in-picture"
+        allowFullScreen
+        frameBorder={0}
+        width="100%"
+        height="100%"
+        referrerPolicy={adapter.source?.engine?.youtube?.referrerPolicy}
+        {...props}
+        ref={ref}
+      >
+        {children}
+      </iframe>
+    );
+  },
+  { displayName: 'YouTubeVideo' }
+);
 
 export namespace YouTubeVideo {
   export type Props = YouTubeVideoProps;
diff --git a/packages/react/src/utils/use-attach-iframe.ts b/packages/react/src/utils/use-attach-iframe.ts
deleted file mode 100644
index a00e98c2e4..0000000000
--- a/packages/react/src/utils/use-attach-iframe.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import type { EngineAdapter } from '@videojs/media';
-import type { RefCallback } from 'react';
-import { useCallback } from 'react';
-
-export function useAttachIframe<T extends HTMLIFrameElement>(media: EngineAdapter): RefCallback<T> {
-  return useCallback(
-    (element: T | null) => {
-      if (element) media.attach?.(element);
-      else media.detach?.();
-
-      return () => media.detach?.();
-    },
-    [media]
-  );
-}
diff --git a/packages/react/src/utils/use-attach-media.ts b/packages/react/src/utils/use-attach-media.ts
index 9a8fa5a61d..ceca4f2da5 100644
--- a/packages/react/src/utils/use-attach-media.ts
+++ b/packages/react/src/utils/use-attach-media.ts
@@ -7,7 +7,7 @@ import { useCallback } from 'react';
  *
  * @param media - Playback adapter to attach and detach.
  */
-export function useAttachMedia<T extends HTMLMediaElement>(media: EngineAdapter): RefCallback<T> {
+export function useAttachMedia<T = HTMLMediaElement>(media: EngineAdapter): RefCallback<T> {
   return useCallback(
     (element: T | null) => {
       if (element) media.attach?.(element);
diff --git a/site/scripts/api-docs-builder/src/media-element-handler.ts b/site/scripts/api-docs-builder/src/media-element-handler.ts
index e4863c8b1f..a10930c951 100644
--- a/site/scripts/api-docs-builder/src/media-element-handler.ts
+++ b/site/scripts/api-docs-builder/src/media-element-handler.ts
@@ -1172,6 +1172,21 @@ function extractAttributeConfigs(filePath: string, constName: string, project: O
   return properties;
 }
 
+/** The tag name of the first JSX element a render callback returns, or undefined when it renders none. */
+function renderedRootTag(render: Expression): string | undefined {
+  let tag: string | undefined;
+
+  walkAst(render, (node) => {
+    if (tag || node.type !== 'JSXElement') return;
+
+    const name = node.openingElement.name;
+
+    if (name.type === 'JSXIdentifier') tag = name.name;
+  });
+
+  return tag;
+}
+
 function extractReactReference(
   monorepoRoot: string,
   source: MediaElementSource,
@@ -1226,6 +1241,34 @@ function extractReactReference(
 
         if (name === 'HTMLIFrameElement') target = 'iframe';
       }
+
+      // `createMediaComponent(Adapter, render)` from `@videojs/react`: the target is whatever element `render` returns,
+      // native video/audio props are spread onto it, and props sync against the adapter's static `defaultProps`.
+      if (
+        initializer.type === 'CallExpression' &&
+        initializer.callee.type === 'Identifier' &&
+        initializer.callee.name === 'createMediaComponent'
+      ) {
+        const [adapter, renderer] = initializer.arguments;
+        const rootTag = renderer && renderer.type !== 'SpreadElement' ? renderedRootTag(renderer) : undefined;
+
+        if (rootTag === 'video' || rootTag === 'audio' || rootTag === 'iframe') {
+          target = rootTag;
+          acceptsNativeProps = rootTag !== 'iframe';
+        }
+
+        if (adapter?.type === 'Identifier') {
+          defaultsExpression = {
+            type: 'MemberExpression',
+            object: adapter,
+            property: { type: 'Identifier', name: 'defaultProps', start: adapter.start, end: adapter.end },
+            computed: false,
+            optional: false,
+            start: adapter.start,
+            end: adapter.end,
+          } as Expression;
+        }
+      }
     }
 
     if (node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'useSyncProps') {
diff --git a/site/scripts/api-docs-builder/src/tests/e2e.test.ts b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
index 658ec9f06c..3ca0901451 100644
--- a/site/scripts/api-docs-builder/src/tests/e2e.test.ts
+++ b/site/scripts/api-docs-builder/src/tests/e2e.test.ts
@@ -1976,7 +1976,7 @@ describe('Media element pipeline (end-to-end)', () => {
       expect(props.streamType.default).toBe("'unknown'");
     });
 
-    it('extracts the React surface from a static defaultProps that spreads the parent host', () => {
+    it('extracts the React surface of a createMediaComponent component from the adapter static defaultProps', () => {
       const react = findElement('ExtendingVideo')!.reference.platforms.react;
 
       expect(react).toMatchObject({ target: 'video', acceptsNativeProps: true });
diff --git a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/media/extending-video/adapter.tsx b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/media/extending-video/adapter.tsx
index d83be33cfb..42076a1f50 100644
--- a/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/media/extending-video/adapter.tsx
+++ b/site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/media/extending-video/adapter.tsx
@@ -1,21 +1,17 @@
 /**
- * Mock React media component over an inheriting host.
+ * Mock React media component built with the `createMediaComponent` factory.
  *
- * Exercises: defaults read off a `static defaultProps` that spreads the parent
- * host's static (mirrors MuxVideo over MuxVideoAdapter extends HlsJsAdapter).
+ * Exercises: the factory takes the adapter and a render callback, so the
+ * builder reads the target from the element the callback returns and the
+ * defaults from the adapter's `static defaultProps` — which here spreads the
+ * parent host's static (mirrors HlsJsVideo over HlsJsAdapter, and MuxVideo's inheritance).
  */
 import { ExtendingHost } from '../../../../media/src/dom/extending';
 
-interface VideoHTMLAttributes<Element> {
-  element?: Element;
-}
+declare function createMediaComponent(adapter: object, render: (args: any) => unknown): unknown;
 
-interface ExtendingVideoProps extends VideoHTMLAttributes<HTMLVideoElement>, Partial<typeof ExtendingHost.defaultProps> {}
-
-declare function forwardRef<Ref, Props>(render: (props: Props, ref: Ref) => unknown): unknown;
-declare function useSyncProps(target: object, props: object, defaults: object): object;
-
-export const ExtendingVideo = forwardRef<HTMLVideoElement, ExtendingVideoProps>(function ExtendingVideo(props, ref) {
-  useSyncProps({}, props, ExtendingHost.defaultProps);
-  return { ref };
-});
+export const ExtendingVideo = createMediaComponent(ExtendingHost, ({ props, children, ref }) => (
+  <video {...props} ref={ref}>
+    {children}
+  </video>
+));
diff --git a/site/src/content/docs/reference/create-media-component.mdx b/site/src/content/docs/reference/create-media-component.mdx
new file mode 100644
index 0000000000..efaed02e07
--- /dev/null
+++ b/site/src/content/docs/reference/create-media-component.mdx
@@ -0,0 +1,52 @@
+---
+title: createMediaComponent
+description: Build a React media component around a playback adapter that registers with the Player
+---
+
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import DocsLink from "@/components/docs/DocsLink.astro";
+
+## Import
+
+```tsx
+import { createMediaComponent } from "@videojs/react";
+```
+
+## Usage
+
+Pass an adapter class and a render callback. The component drives one adapter instance, syncs the adapter's props from the React props of the same name, and calls your callback with everything needed to render the target: the adapter, the remaining native props, the children, and a ref that attaches the adapter to the element it lands on. It registers with the surrounding <DocsLink slug="reference/player">Player</DocsLink>.
+
+```tsx
+import { HlsJsAdapter } from '@videojs/hlsjs-video';
+import { createMediaComponent, type MediaComponentProps } from '@videojs/react';
+
+export type MyHlsVideoProps = MediaComponentProps<typeof HlsJsAdapter>;
+
+export const MyHlsVideo = createMediaComponent(
+  HlsJsAdapter,
+  ({ props, children, ref }) => (
+    <video {...props} ref={ref}>
+      {children}
+    </video>
+  ),
+  { displayName: 'MyHlsVideo' }
+);
+```
+
+The target can be any element the adapter attaches to. Embeds render an `<iframe>`, and read values that must not change after the first render from `initialProps`:
+
+```tsx
+export const MyVimeoVideo = createMediaComponent(VimeoAdapter, ({ adapter, props, children, ref, initialProps }) => (
+  <iframe src={buildVimeoIframeSrc(initialProps.src ?? '', { ...VimeoAdapter.defaultProps, ...initialProps })} {...props} ref={ref}>
+    {children}
+  </iframe>
+));
+```
+
+Props matching the adapter's `defaultProps` are synced onto the adapter and reset to their defaults when omitted. Every other prop and the forwarded ref go to the rendered element, whose attribute type follows from the adapter's `attach()` target. Every built-in media component except `WistiaVideo` and `HlsBackgroundVideo` is created this way.
+
+## Who needs this
+
+Use `createMediaComponent` to expose an adapter as a React component, for example a third-party engine that implements the `@videojs/media` contract. For a component that needs its own effects or state beyond rendering, compose <DocsLink slug="reference/use-media-instance">useMediaInstance</DocsLink> and <DocsLink slug="reference/use-attach-media">useAttachMedia</DocsLink> directly.
+
+<UtilReference util="createMediaComponent" />
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index 529c505a71..5a6b6822d3 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -273,6 +273,7 @@ export const sidebar: Sidebar = [
               { slug: 'reference/i-18-n-controller', sidebarLabel: 'I18nController', frameworks: ['html'] },
               { slug: 'reference/merge-props', frameworks: ['react'] },
               { slug: 'reference/render-element', frameworks: ['react'] },
+              { slug: 'reference/create-media-component', frameworks: ['react'] },
               { slug: 'reference/use-attach-media', frameworks: ['react'] },
               { slug: 'reference/use-audio-track-options', frameworks: ['react'] },
               { slug: 'reference/use-button', frameworks: ['react'] },

From d10d9724f71ecac66e5cf11669293a98ef24cda4 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Sun, 6 Sep 2026 21:28:29 -0700
Subject: [PATCH 24/25] fix(react): type media component targets from the
 adapter host

Inferring the element from `attach()` mistyped the SPF adapters, whose
mixins take an `HTMLMediaElement`, as audio, and the hls.js
`MuxAudioAdapter` as video. The adapter's static `host` names the element
directly.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/media/create-media-component.tsx      | 31 ++++++++++++-------
 .../docs/reference/create-media-component.mdx |  2 +-
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/packages/react/src/media/create-media-component.tsx b/packages/react/src/media/create-media-component.tsx
index a305158bf2..3ac2376365 100644
--- a/packages/react/src/media/create-media-component.tsx
+++ b/packages/react/src/media/create-media-component.tsx
@@ -1,10 +1,10 @@
 'use client';
 
 import type { EngineAdapter, Media } from '@videojs/media';
+import type { AdapterHost } from '@videojs/media/dom';
 import type {
   AudioHTMLAttributes,
   ForwardRefExoticComponent,
-  HTMLAttributes,
   IframeHTMLAttributes,
   PropsWithoutRef,
   ReactNode,
@@ -19,27 +19,35 @@ import { useComposedRefs } from '../utils/use-composed-refs';
 import { useMediaInstance } from '../utils/use-media-instance';
 import { useSyncProps } from '../utils/use-sync-props';
 
-/** An adapter class: constructible without arguments, attachable to a target, with its defaults as a static. */
+/** An adapter class: constructible without arguments, declaring the element it drives, with its defaults as a static. */
 export interface MediaAdapterConstructor {
   new (): Media & EngineAdapter;
+  readonly host: AdapterHost;
   readonly defaultProps: object;
 }
 
-/** The element an adapter attaches to, read off its `attach()` signature. */
-export type MediaAdapterTarget<Adapter extends MediaAdapterConstructor> =
-  InstanceType<Adapter> extends { attach(target: infer Target): unknown } ? NonNullable<Target> : never;
+/**
+ * The element an adapter renders into, read off its static `host`.
+ *
+ * `HTMLVideoAdapter` types its host as `'video' | 'audio'` so an adapter built on it can re-host in an `<audio>`;
+ * anything not narrowed to `'audio'` or `'iframe'` is therefore a video. Checked non-distributively so the union
+ * resolves to one element rather than to a union of elements.
+ */
+export type MediaAdapterTarget<Adapter extends MediaAdapterConstructor> = [Adapter['host']] extends ['iframe']
+  ? HTMLIFrameElement
+  : [Adapter['host']] extends ['audio']
+    ? HTMLAudioElement
+    : HTMLVideoElement;
 
 /** The adapter's props: the keys of its static `defaultProps`. */
 export type MediaAdapterProps<Adapter extends MediaAdapterConstructor> = Adapter['defaultProps'];
 
-/** The native attributes of the element an adapter attaches to. */
+/** The native attributes of the element an adapter renders into. */
 export type MediaTargetAttributes<Target> = Target extends HTMLIFrameElement
   ? IframeHTMLAttributes<HTMLIFrameElement>
-  : Target extends { readonly videoWidth: number }
+  : Target extends HTMLVideoElement
     ? VideoHTMLAttributes<HTMLVideoElement>
-    : Target extends { readonly volume: number }
-      ? AudioHTMLAttributes<HTMLAudioElement>
-      : HTMLAttributes<HTMLElement>;
+    : AudioHTMLAttributes<HTMLAudioElement>;
 
 /** Props of a component built by `createMediaComponent`: the target's attributes plus the adapter's props. */
 export type MediaComponentProps<Adapter extends MediaAdapterConstructor> = Omit<
@@ -90,7 +98,8 @@ export interface MediaComponentOptions {
  * returns: a `<video>`, an `<audio>`, or an embed's `<iframe>`. It is what the built-in `HlsJsVideo`, `MuxVideo`, and
  * `VimeoVideo` components are made of.
  *
- * @param Adapter - Adapter class with a static `defaultProps`, for example `HlsJsAdapter` from `@videojs/hlsjs-video`.
+ * @param Adapter - Adapter class with static `host` and `defaultProps`, for example `HlsJsAdapter` from
+ *   `@videojs/hlsjs-video`.
  * @param render - Renders the target element from the adapter, the native props, the children, and the attach ref.
  * @param options - `displayName` for React DevTools. Defaults to the adapter's class name.
  */
diff --git a/site/src/content/docs/reference/create-media-component.mdx b/site/src/content/docs/reference/create-media-component.mdx
index efaed02e07..636cb1f57a 100644
--- a/site/src/content/docs/reference/create-media-component.mdx
+++ b/site/src/content/docs/reference/create-media-component.mdx
@@ -43,7 +43,7 @@ export const MyVimeoVideo = createMediaComponent(VimeoAdapter, ({ adapter, props
 ));
 ```
 
-Props matching the adapter's `defaultProps` are synced onto the adapter and reset to their defaults when omitted. Every other prop and the forwarded ref go to the rendered element, whose attribute type follows from the adapter's `attach()` target. Every built-in media component except `WistiaVideo` and `HlsBackgroundVideo` is created this way.
+Props matching the adapter's `defaultProps` are synced onto the adapter and reset to their defaults when omitted. Every other prop and the forwarded ref go to the rendered element, whose attribute and ref types follow from the adapter's static `host`: `'video'`, `'audio'`, or `'iframe'`. Every built-in media component except `WistiaVideo` and `HlsBackgroundVideo` is created this way.
 
 ## Who needs this
 

From 009cc1120d3c99a19d71ab87c9279e77d275b809 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Mon, 7 Sep 2026 17:56:01 -0700
Subject: [PATCH 25/25] refactor(react): read the media target off a literal
 host

Every adapter's `host` is a literal now, so the non-distributive check for
the video union is gone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/media/create-media-component.tsx | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/react/src/media/create-media-component.tsx b/packages/react/src/media/create-media-component.tsx
index 3ac2376365..e7a90b6fca 100644
--- a/packages/react/src/media/create-media-component.tsx
+++ b/packages/react/src/media/create-media-component.tsx
@@ -26,16 +26,10 @@ export interface MediaAdapterConstructor {
   readonly defaultProps: object;
 }
 
-/**
- * The element an adapter renders into, read off its static `host`.
- *
- * `HTMLVideoAdapter` types its host as `'video' | 'audio'` so an adapter built on it can re-host in an `<audio>`;
- * anything not narrowed to `'audio'` or `'iframe'` is therefore a video. Checked non-distributively so the union
- * resolves to one element rather than to a union of elements.
- */
-export type MediaAdapterTarget<Adapter extends MediaAdapterConstructor> = [Adapter['host']] extends ['iframe']
+/** The element an adapter renders into, read off its static `host`. */
+export type MediaAdapterTarget<Adapter extends MediaAdapterConstructor> = Adapter['host'] extends 'iframe'
   ? HTMLIFrameElement
-  : [Adapter['host']] extends ['audio']
+  : Adapter['host'] extends 'audio'
     ? HTMLAudioElement
     : HTMLVideoElement;