From e09ea334bd92430c6243b8f02718ed23c0ee3443 Mon Sep 17 00:00:00 2001
From: rahim <rahim.alwer@gmail.com>
Date: Wed, 18 Mar 2026 22:21:30 -0700
Subject: [PATCH] refactor(html): context-based media discovery, remove
 slot="media" (#997)

---
 internal/decisions/context-media-discovery.md | 60 +++++++++++++++++++
 packages/element/src/context.ts               |  8 ++-
 .../src/define/audio/minimal-skin.tailwind.ts |  2 +-
 .../html/src/define/audio/minimal-skin.ts     |  2 +-
 .../html/src/define/audio/skin.tailwind.ts    |  2 +-
 packages/html/src/define/audio/skin.ts        |  2 +-
 packages/html/src/define/background/skin.css  |  2 +-
 packages/html/src/define/background/skin.ts   |  2 +-
 .../src/define/video/minimal-skin.tailwind.ts |  2 +-
 .../html/src/define/video/minimal-skin.ts     |  2 +-
 .../html/src/define/video/skin.tailwind.ts    |  2 +-
 packages/html/src/define/video/skin.ts        |  2 +-
 packages/html/src/index.ts                    |  1 +
 .../html/src/media/background-video/index.ts  |  9 ++-
 packages/html/src/media/dash-video/index.ts   |  3 +-
 packages/html/src/media/hls-video/index.ts    |  3 +-
 .../html/src/media/simple-hls-video/index.ts  |  3 +-
 packages/html/src/store/media-attach-mixin.ts | 60 +++++++++++++++++++
 packages/sandbox/templates/html-audio/main.ts |  2 +-
 .../templates/html-background-video/main.ts   |  2 +-
 .../sandbox/templates/html-dash-video/main.ts |  2 +-
 .../sandbox/templates/html-hls-video/main.ts  |  2 +-
 .../templates/html-simple-hls-video/main.ts   |  2 +-
 packages/sandbox/templates/html-video/main.ts |  2 +-
 24 files changed, 158 insertions(+), 21 deletions(-)
 create mode 100644 internal/decisions/context-media-discovery.md
 create mode 100644 packages/html/src/store/media-attach-mixin.ts

diff --git a/internal/decisions/context-media-discovery.md b/internal/decisions/context-media-discovery.md
new file mode 100644
index 00000000..38735e2d
--- /dev/null
+++ b/internal/decisions/context-media-discovery.md
@@ -0,0 +1,60 @@
+---
+status: decided
+date: 2026-03-17
+---
+
+# Context-Based Media Discovery
+
+## Decision
+
+Media elements are discovered via context, not named slots. Skins use a default `<slot>` instead of `<slot name="media">`. Users no longer need `slot="media"` on their `<video>` or `<audio>` elements.
+
+The provider's `mediaAttachContext` is the primary discovery mechanism. Custom elements that consume context register themselves directly. Plain `<video>`/`<audio>` elements that can't consume context are found via the provider's fallback `querySelector('video, audio')`.
+
+The `<slot name="media">` inside `CustomMediaElement` is a separate concern — it's for overriding the internal native element and stays unchanged.
+
+## Context
+
+Skins previously used `<slot name="media">` inside `<media-container>` for two purposes:
+
+1. **DOM projection** — visually placing the media element inside the container's layout.
+2. **Media discovery** — the container's `slotchange` listener and `MutationObserver` watched the slot to detect when a media element appeared.
+
+With [provider-attach](provider-attach.md), the provider now owns media discovery and `store.attach()`. The container no longer watches for media elements. Discovery purpose (2) is gone. Only DOM projection (1) remains — and a default slot serves that purpose without requiring users to mark their elements with `slot="media"`.
+
+The named slot created user-facing friction:
+
+- Forgetting `slot="media"` meant the player silently didn't attach — no error, just a broken player.
+- The slot pattern confused users who expected shadow DOM semantics under the hood.
+- Frameworks that hijack slot assignment could conflict with the sentinel usage.
+- React already used context-based registration, making the HTML behavior inconsistent.
+
+## Alternatives Considered
+
+- **Keep named slots alongside context** — Skins keep `<slot name="media">`, users keep writing `slot="media"`. Rejected because the named slot no longer serves a discovery purpose and creates unnecessary friction.
+
+- **Remove all slots from skins** — Skins render media via a different mechanism (e.g., `<template>` insertion). Rejected because default slots still provide clean DOM projection without any user-facing attributes.
+
+## Rationale
+
+**One less thing to remember.** Users drop a `<video>` inside a skin and it works. No attribute ceremony.
+
+**Consistent with React.** React uses `<Video>` with a callback ref — no slot concept. HTML now matches: elements register via context, the provider discovers them.
+
+**Default slot is invisible.** A `<slot>` (default) projects all light DOM children. The media element, controls, and other children all project naturally. No named targeting needed.
+
+**Fallback covers plain elements.** The provider's `querySelector('video, audio')` microtask fallback handles native elements that can't consume context. This path is simple and predictable.
+
+## Previous Behavior
+
+Skins defined `<slot name="media"></slot>` inside `<media-container>`. Users wrote:
+
+```html
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+The container discovered media via `querySelector`, `MutationObserver`, duck-type checks (`localName.endsWith('-video')`), and `slotchange` listeners. Forgetting `slot="media"` meant the video rendered but never attached to the store.
diff --git a/packages/element/src/context.ts b/packages/element/src/context.ts
index bd83d1bb..ff0f3341 100644
--- a/packages/element/src/context.ts
+++ b/packages/element/src/context.ts
@@ -1 +1,7 @@
-export { type Context, ContextConsumer, ContextProvider, createContext } from '@lit/context';
+export {
+  type Context,
+  ContextConsumer,
+  ContextEvent,
+  ContextProvider,
+  createContext,
+} from '@lit/context';
diff --git a/packages/html/src/define/audio/minimal-skin.tailwind.ts b/packages/html/src/define/audio/minimal-skin.tailwind.ts
index be818d03..d182f9b4 100644
--- a/packages/html/src/define/audio/minimal-skin.tailwind.ts
+++ b/packages/html/src/define/audio/minimal-skin.tailwind.ts
@@ -37,7 +37,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="${root}">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <div class="${controls}">
         <media-tooltip-group>
diff --git a/packages/html/src/define/audio/minimal-skin.ts b/packages/html/src/define/audio/minimal-skin.ts
index f012c255..f3abd9c1 100644
--- a/packages/html/src/define/audio/minimal-skin.ts
+++ b/packages/html/src/define/audio/minimal-skin.ts
@@ -21,7 +21,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="media-minimal-skin media-minimal-skin--audio">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <div class="media-controls">
         <media-tooltip-group>
diff --git a/packages/html/src/define/audio/skin.tailwind.ts b/packages/html/src/define/audio/skin.tailwind.ts
index 57cb9778..5ed52af3 100644
--- a/packages/html/src/define/audio/skin.tailwind.ts
+++ b/packages/html/src/define/audio/skin.tailwind.ts
@@ -36,7 +36,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="${root}">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <div class="${controls}">
         <media-tooltip-group>
diff --git a/packages/html/src/define/audio/skin.ts b/packages/html/src/define/audio/skin.ts
index ce87c479..bb58262c 100644
--- a/packages/html/src/define/audio/skin.ts
+++ b/packages/html/src/define/audio/skin.ts
@@ -21,7 +21,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="media-default-skin media-default-skin--audio">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <div class="media-surface media-controls">
         <media-tooltip-group>
diff --git a/packages/html/src/define/background/skin.css b/packages/html/src/define/background/skin.css
index 025f827a..daf9d07e 100644
--- a/packages/html/src/define/background/skin.css
+++ b/packages/html/src/define/background/skin.css
@@ -11,7 +11,7 @@ background-video-skin {
   object-fit: var(--media-object-fit);
 }
 
-background-video-skin > [slot="media"] {
+background-video-skin > background-video {
   position: absolute;
   inset: 0;
   width: 100%;
diff --git a/packages/html/src/define/background/skin.ts b/packages/html/src/define/background/skin.ts
index 4f51e0e4..a2f46402 100644
--- a/packages/html/src/define/background/skin.ts
+++ b/packages/html/src/define/background/skin.ts
@@ -5,7 +5,7 @@ import { safeDefine } from '../safe-define';
 function getTemplateHTML(_attrs: Record<string, string>) {
   return /*html*/ `
     <media-container>
-      <slot name="media" slot="media"></slot>
+      <slot></slot>
     </media-container>
   `;
 }
diff --git a/packages/html/src/define/video/minimal-skin.tailwind.ts b/packages/html/src/define/video/minimal-skin.tailwind.ts
index 86279b83..0214be7b 100644
--- a/packages/html/src/define/video/minimal-skin.tailwind.ts
+++ b/packages/html/src/define/video/minimal-skin.tailwind.ts
@@ -47,7 +47,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="${root(true)}">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <media-poster class="${poster(true)}">
         <slot name="poster"></slot>
diff --git a/packages/html/src/define/video/minimal-skin.ts b/packages/html/src/define/video/minimal-skin.ts
index 8c1822ba..aad00d3d 100644
--- a/packages/html/src/define/video/minimal-skin.ts
+++ b/packages/html/src/define/video/minimal-skin.ts
@@ -26,7 +26,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="media-minimal-skin media-minimal-skin--video">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <media-poster>
         <slot name="poster"></slot>
diff --git a/packages/html/src/define/video/skin.tailwind.ts b/packages/html/src/define/video/skin.tailwind.ts
index 3d44590f..2eeac146 100644
--- a/packages/html/src/define/video/skin.tailwind.ts
+++ b/packages/html/src/define/video/skin.tailwind.ts
@@ -46,7 +46,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="${root(true)}">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <media-poster class="${poster(true)}">
         <slot name="poster"></slot>
diff --git a/packages/html/src/define/video/skin.ts b/packages/html/src/define/video/skin.ts
index 05ceb7a8..3b56a96d 100644
--- a/packages/html/src/define/video/skin.ts
+++ b/packages/html/src/define/video/skin.ts
@@ -27,7 +27,7 @@ const SEEK_TIME = 10;
 function getTemplateHTML() {
   return /*html*/ `
     <media-container class="media-default-skin media-default-skin--video">
-      <slot name="media"></slot>
+      <slot></slot>
 
       <media-poster>
         <slot name="poster"></slot>
diff --git a/packages/html/src/index.ts b/packages/html/src/index.ts
index cd2dec5d..6b7d1850 100644
--- a/packages/html/src/index.ts
+++ b/packages/html/src/index.ts
@@ -11,6 +11,7 @@ export * from './player/context';
 export * from './player/create-player';
 export * from './player/player-controller';
 export * from './store/container-mixin';
+export * from './store/media-attach-mixin';
 export * from './store/provider-mixin';
 export * from './store/types';
 // UI Components
diff --git a/packages/html/src/media/background-video/index.ts b/packages/html/src/media/background-video/index.ts
index 8e969623..dde9058d 100644
--- a/packages/html/src/media/background-video/index.ts
+++ b/packages/html/src/media/background-video/index.ts
@@ -1,4 +1,6 @@
+import type { Media } from '@videojs/core/dom';
 import { namedNodeMapToObject } from '@videojs/utils/dom';
+import { MediaAttachMixin } from '../../store/media-attach-mixin';
 
 function getTemplateHTML(attrs: Record<string, string>) {
   return /*html*/ `
@@ -22,7 +24,7 @@ function getTemplateHTML(attrs: Record<string, string>) {
 }
 
 // Don't extend CustomMediaMixin to save some bytes, background videos don't need the full Media API.
-export class BackgroundVideo extends HTMLElement {
+export class BackgroundVideo extends MediaAttachMixin(HTMLElement) {
   static shadowRootOptions = { mode: 'open' as ShadowRootMode };
   static getTemplateHTML = getTemplateHTML;
   static get observedAttributes() {
@@ -54,6 +56,11 @@ export class BackgroundVideo extends HTMLElement {
     this.target!.muted = !this.hasAttribute('nomuted');
   }
 
+  // Register the inner <video> (not `this`) with the provider.
+  getMediaTarget(): Media | null {
+    return this.target;
+  }
+
   attributeChangedCallback(attrName: string, oldValue: string | null, newValue: string | null): void {
     if (attrName === 'src' && oldValue !== newValue) {
       this.target!.src = newValue ?? '';
diff --git a/packages/html/src/media/dash-video/index.ts b/packages/html/src/media/dash-video/index.ts
index e7365d4a..4f2971cf 100644
--- a/packages/html/src/media/dash-video/index.ts
+++ b/packages/html/src/media/dash-video/index.ts
@@ -1,6 +1,7 @@
 import { DashCustomMedia } from '@videojs/core/dom/media/dash';
+import { MediaAttachMixin } from '../../store/media-attach-mixin';
 
-export class DashVideo extends DashCustomMedia {
+export class DashVideo extends MediaAttachMixin(DashCustomMedia) {
   static getTemplateHTML(attrs: Record<string, string>): string {
     const { src, ...rest } = attrs;
     // biome-ignore lint/complexity/noThisInStatic: intentional use of super
diff --git a/packages/html/src/media/hls-video/index.ts b/packages/html/src/media/hls-video/index.ts
index e4c06d77..c943232f 100644
--- a/packages/html/src/media/hls-video/index.ts
+++ b/packages/html/src/media/hls-video/index.ts
@@ -1,6 +1,7 @@
 import { HlsCustomMedia } from '@videojs/core/dom/media/hls';
+import { MediaAttachMixin } from '../../store/media-attach-mixin';
 
-export class HlsVideo extends HlsCustomMedia {
+export class HlsVideo extends MediaAttachMixin(HlsCustomMedia) {
   static getTemplateHTML(attrs: Record<string, string>): string {
     const { src, ...rest } = attrs;
     // biome-ignore lint/complexity/noThisInStatic: intentional use of super
diff --git a/packages/html/src/media/simple-hls-video/index.ts b/packages/html/src/media/simple-hls-video/index.ts
index 7fe83239..6fbb498d 100644
--- a/packages/html/src/media/simple-hls-video/index.ts
+++ b/packages/html/src/media/simple-hls-video/index.ts
@@ -1,6 +1,7 @@
 import { SimpleHlsCustomMedia } from '@videojs/core/dom/media/simple-hls';
+import { MediaAttachMixin } from '../../store/media-attach-mixin';
 
-export class SimpleHlsVideo extends SimpleHlsCustomMedia {
+export class SimpleHlsVideo extends MediaAttachMixin(SimpleHlsCustomMedia) {
   static getTemplateHTML(attrs: Record<string, string>): string {
     const { src, ...rest } = attrs;
     // biome-ignore lint/complexity/noThisInStatic: intentional use of super
diff --git a/packages/html/src/store/media-attach-mixin.ts b/packages/html/src/store/media-attach-mixin.ts
new file mode 100644
index 00000000..86bb657b
--- /dev/null
+++ b/packages/html/src/store/media-attach-mixin.ts
@@ -0,0 +1,60 @@
+import type { Media } from '@videojs/core/dom';
+import { ContextEvent } from '@videojs/element/context';
+import type { CustomElement } from '@videojs/utils/dom';
+import type { AnyConstructor, Constructor } from '@videojs/utils/types';
+import { type MediaAttachContext, mediaAttachContext } from '../player/context';
+
+export type MediaAttachMixin = <Class extends AnyConstructor<HTMLElement>>(BaseClass: Class) => Class;
+
+/**
+ * Create a mixin that consumes `mediaAttachContext` and registers the
+ * element as the media with the provider.
+ *
+ * Uses the raw context-request protocol so it works with any
+ * `HTMLElement` subclass — no `ReactiveControllerHost` required.
+ *
+ * @param context - The media attach context to consume.
+ */
+export function createMediaAttachMixin(context: MediaAttachContext): MediaAttachMixin {
+  return <Class extends AnyConstructor<HTMLElement>>(BaseClass: Class) => {
+    class MediaAttachElement extends (BaseClass as unknown as Constructor<CustomElement>) {
+      #setMedia: ((media: Media | null) => void) | null = null;
+      #unsubscribe: (() => void) | null = null;
+
+      getMediaTarget(): Media | null {
+        return this as unknown as Media;
+      }
+
+      override connectedCallback() {
+        super.connectedCallback?.();
+
+        this.dispatchEvent(
+          new ContextEvent(
+            context,
+            this,
+            (value, unsubscribe) => {
+              if (unsubscribe) this.#unsubscribe = unsubscribe;
+              this.#setMedia = value ?? null;
+              if (this.isConnected) {
+                this.#setMedia?.(this.getMediaTarget());
+              }
+            },
+            true
+          )
+        );
+      }
+
+      override disconnectedCallback() {
+        super.disconnectedCallback?.();
+        this.#setMedia?.(null);
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        this.#setMedia = null;
+      }
+    }
+
+    return MediaAttachElement as unknown as Class;
+  };
+}
+
+export const MediaAttachMixin = createMediaAttachMixin(mediaAttachContext);
diff --git a/packages/sandbox/templates/html-audio/main.ts b/packages/sandbox/templates/html-audio/main.ts
index ed5dc664..6054ba31 100644
--- a/packages/sandbox/templates/html-audio/main.ts
+++ b/packages/sandbox/templates/html-audio/main.ts
@@ -18,7 +18,7 @@ async function render() {
     <div class="w-full max-w-xl mx-auto">
       <audio-player>
         <${tag}>
-          <audio slot="media" src="${SOURCES[state.source].url}"></audio>
+          <audio src="${SOURCES[state.source].url}"></audio>
         </${tag}>
       </audio-player>
     </div>
diff --git a/packages/sandbox/templates/html-background-video/main.ts b/packages/sandbox/templates/html-background-video/main.ts
index f049d579..11d1063c 100644
--- a/packages/sandbox/templates/html-background-video/main.ts
+++ b/packages/sandbox/templates/html-background-video/main.ts
@@ -10,7 +10,7 @@ const html = String.raw;
 document.getElementById('root')!.innerHTML = html`
   <background-video-player>
     <background-video-skin>
-      <background-video slot="media" src="${BACKGROUND_VIDEO_SRC}"></background-video>
+      <background-video src="${BACKGROUND_VIDEO_SRC}"></background-video>
     </background-video-skin>
   </background-video-player>
 `;
diff --git a/packages/sandbox/templates/html-dash-video/main.ts b/packages/sandbox/templates/html-dash-video/main.ts
index 24bf7ed1..a74b616d 100644
--- a/packages/sandbox/templates/html-dash-video/main.ts
+++ b/packages/sandbox/templates/html-dash-video/main.ts
@@ -22,7 +22,7 @@ async function render() {
   document.getElementById('root')!.innerHTML = html`
     <video-player>
       <${tag} class="w-full aspect-video max-w-4xl mx-auto">
-        <dash-video slot="media" src="${SOURCES[state.source].url}" playsinline>
+        <dash-video src="${SOURCES[state.source].url}" playsinline>
           ${renderStoryboard(storyboard)}
         </dash-video>
         ${poster ? html`<img slot="poster" src="${poster}" alt="Video poster" />` : ''}
diff --git a/packages/sandbox/templates/html-hls-video/main.ts b/packages/sandbox/templates/html-hls-video/main.ts
index db5c4cb7..69ff1dcb 100644
--- a/packages/sandbox/templates/html-hls-video/main.ts
+++ b/packages/sandbox/templates/html-hls-video/main.ts
@@ -22,7 +22,7 @@ async function render() {
   document.getElementById('root')!.innerHTML = html`
     <video-player>
       <${tag} class="w-full aspect-video max-w-4xl mx-auto">
-        <hls-video slot="media" src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
+        <hls-video src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
           ${renderStoryboard(storyboard)}
         </hls-video>
         ${poster ? html`<img slot="poster" src="${poster}" alt="Video poster" />` : ''}
diff --git a/packages/sandbox/templates/html-simple-hls-video/main.ts b/packages/sandbox/templates/html-simple-hls-video/main.ts
index ed3687aa..f49e92a9 100644
--- a/packages/sandbox/templates/html-simple-hls-video/main.ts
+++ b/packages/sandbox/templates/html-simple-hls-video/main.ts
@@ -22,7 +22,7 @@ async function render() {
   document.getElementById('root')!.innerHTML = html`
     <video-player>
       <${tag} class="w-full aspect-video max-w-4xl mx-auto">
-        <simple-hls-video slot="media" src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
+        <simple-hls-video src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
           ${renderStoryboard(storyboard)}
         </simple-hls-video>
         ${poster ? html`<img slot="poster" src="${poster}" alt="Video poster" />` : ''}
diff --git a/packages/sandbox/templates/html-video/main.ts b/packages/sandbox/templates/html-video/main.ts
index 95b01ecf..0c537ecc 100644
--- a/packages/sandbox/templates/html-video/main.ts
+++ b/packages/sandbox/templates/html-video/main.ts
@@ -22,7 +22,7 @@ async function render() {
   document.getElementById('root')!.innerHTML = html`
     <video-player>
       <${tag} class="w-full aspect-video max-w-4xl mx-auto">
-        <video slot="media" src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
+        <video src="${SOURCES[state.source].url}" playsinline crossorigin="anonymous">
           ${renderStoryboard(storyboard)}
         </video>
         ${poster ? html`<img slot="poster" src="${poster}" alt="Video poster" />` : ''}