@munsonlabs/video-player 0.2.0 → 0.2.2

package/README.md

@@ -14,14 +14,14 @@ npm install @munsonlabs/video-player
 
 ```vue
 <script setup>
-import { VideoItem } from '@munsonlabs/video-player'
+import { VideoCard } from '@munsonlabs/video-player'
 import '@munsonlabs/video-player/style'
 </script>
 
 <template>
-  <VideoItem
+  <VideoCard
     title="Big Buck Bunny"
-    video-url="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4"
+    src="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4"
     poster="https://storage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
   />
 </template>
@@ -29,61 +29,53 @@ import '@munsonlabs/video-player/style'
 
 ### Pinning a single player
 
-Set `pin-position` on a standalone `VideoItem`/`VideoPlayer` (no `VideoStage` involved) to get the same corner-pinning mini-player behaviour `VideoStage` has, scoped to just that one player: once it scrolls out of view while playing, it pins to the given corner instead of auto-pausing, and shrinks back to its inline size once scrolled back into view.
+Set `pin` on a standalone `VideoCard`/`VideoPlayer` (no `VideoStage` involved) to get the same corner-pinning mini-player behaviour `VideoStage` has, scoped to just that one player: once it scrolls out of view while playing, it pins to the given corner instead of auto-pausing, and shrinks back to its inline size once scrolled back into view.
 
 ```vue
-<VideoItem video-url="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4" pin-position="bottom-right" />
+<VideoCard src="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4" pin="bottom-right" />
 ```
 
-- Only `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` are supported here (unlike `VideoStage`'s `pinPosition`, there's no `'full-width'` option for a single player).
+- Only `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` are supported here (unlike `VideoStage`'s `pin`, there's no `'full-width'` option for a single player).
 - Pausing while pinned does **not** unpin it - like a mini-player, it stays put, paused, in the corner until scrolled back into view. A dismiss button and a scroll-to-player button are shown on the pinned box.
-- Omit `pin-position` to disable pinning entirely - the player then just auto-pauses offscreen as usual.
+- Omit `pin` to disable pinning entirely - the player then just auto-pauses offscreen as usual.
 - `HideMarker` (see [Hiding the pinned stage over content](#hiding-the-pinned-stage-over-content)) works the same way here too, since there's only ever one pinned/tucked element on a page at a time.
 
 ### Stage player
 
-`VideoStage` is a sticky full-width player that receives videos from `VideoItem` components anywhere on the page via window events. When the stage scrolls out of view it minifies to a pip in the bottom-right corner.
+`VideoStage` is a sticky full-width player that receives videos from `VideoCard` components anywhere on the page via window events. When the stage scrolls out of view it minifies to a pip in the bottom-right corner.
 
 ```vue
 <script setup>
-import { VideoStage, VideoItem } from '@munsonlabs/video-player'
+import { VideoStage, VideoCard } from '@munsonlabs/video-player'
 import '@munsonlabs/video-player/style'
 </script>
 
 <template>
   <VideoStage @state-change="onStateChange" />
-  <VideoItem v-for="video in videos" :key="video.videoUrl" v-bind="video" />
+  <VideoCard v-for="video in videos" :key="video.src" v-bind="video" />
 </template>
 ```
 
 ### Playlists
 
-Pass `playlist` (a `VideoEntry[]`, the same shape as a `VideoItem`'s props) to let the stage track the currently-playing video's position within it. This works alongside the existing `video-select`/`video-toggle` window events, not instead of them: position is derived by matching the current video's URL against the playlist on every read, so an external selection (e.g. clicking a `VideoItem` elsewhere on the page) naturally updates "where we are in the playlist" too, with nothing extra to keep in sync.
+Pass `playlist` (a `VideoEntry[]`, the same shape as a `VideoCard`'s props) to let the stage track the currently-playing video's position within it. Position updates automatically when a user clicks a `VideoCard` elsewhere on the page, with nothing extra to keep in sync.
 
 ```vue
 <VideoStage :playlist="videos" @state-change="onStateChange" />
 ```
 
-- Auto-advance (playing the next playlist entry automatically once the current one fires `ended`, with no wraparound, so playback simply stops after the last entry) is fully owned by `VideoStage`: it's remembered in `localStorage` and toggled only via the controls popup's built-in "Auto" button (and, if enabled, the `action="autoplay"` HUD button, see [Actions](#actions)). There's no prop for it: every consumer gets the same persisted, in-player toggle with zero wiring.
-- Whenever `playlist` is set, the controls popup automatically shows a skip-to-next button (only while there's a next entry) and the "Auto" toggle described above, with no extra markup needed.
-- A template ref on `VideoStage` exposes `playNext()`, `playPrevious()`, `hasNext`, and `hasPrevious` too, for building your own next/previous buttons outside the player's own controls:
+- Auto-advance (playing the next entry on `ended`, no wraparound) is toggled via the controls popup's "Auto" button and remembered in `localStorage` - there's no prop for it.
+- A template ref on `VideoStage` exposes `playNext()`, `playPrevious()`, `hasNext`, and `hasPrevious`:
 
 ```vue
-<script setup>
-import { ref } from 'vue'
-const stage = ref(null)
-</script>
-
-<template>
-  <VideoStage ref="stage" :playlist="videos" />
-  <button :disabled="!stage?.hasPrevious" @click="stage.playPrevious()">Previous</button>
-  <button :disabled="!stage?.hasNext" @click="stage.playNext()">Next</button>
-</template>
+<VideoStage ref="stage" :playlist="videos" />
+<button :disabled="!stage?.hasPrevious" @click="stage.playPrevious()">Previous</button>
+<button :disabled="!stage?.hasNext" @click="stage.playNext()">Next</button>
 ```
 
 ### Hiding the pinned stage over content
 
-When `VideoStage` is pinned to a corner (any `pinPosition` other than `'full-width'`), it can sit over content you'd rather it not cover - a footer, a signup form, a comments section. `HideMarker` is a plain sentinel element: place it just before that content, and the stage slides mostly off-screen (leaving a small sliver) for as long as the marker is in the viewport, sliding back once it isn't.
+When `VideoStage` is pinned to a corner (any `pin` other than `'full-width'`), it can sit over content you'd rather it not cover - a footer, a signup form, a comments section. `HideMarker` is a plain sentinel element: place it just before that content, and the stage slides mostly off-screen (leaving a small sliver) for as long as the marker is in the viewport, sliding back once it isn't.
 
 ```vue
 <script setup>
@@ -91,7 +83,7 @@ import { VideoStage, HideMarker } from '@munsonlabs/video-player'
 </script>
 
 <template>
-  <VideoStage pin-position="bottom-right" :playlist="videos" />
+  <VideoStage pin="bottom-right" :playlist="videos" />
 
   <!-- ...page content... -->
 
@@ -101,16 +93,16 @@ import { VideoStage, HideMarker } from '@munsonlabs/video-player'
 ```
 
 - There's no prop linking `HideMarker` to a specific `VideoStage` - there's only ever one stage on a page, so it always applies to whichever one is mounted.
-- The sliver width is a CSS custom property: `--mvp-stage-tuck` (default `32px`).
-- `HideMarker` renders a single, unstyled, full-width `div` with `min-height: 1px` - it has no visible chrome of its own, and no slot for content. Because it's only 1px tall, it triggers briefly as the page scrolls past that exact line rather than staying "hidden" for as long as some section below it remains on screen; place it precisely where you want the stage to tuck away.
+- The sliver width is a CSS custom property: `--mlv-stage-tuck` (default `32px`), see [theming variables](#theming-the-hud-buttons).
+- Place it precisely where you want the stage to tuck away - it renders a 1px-tall invisible `div`, so it triggers briefly as the page scrolls past that exact line.
 
 ---
 
-## VideoItem / VideoPlayer Props
+## VideoCard / VideoPlayer Props
 
 | Prop                | Type           | Default  | Description                                                                                                                                                        |
 | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `videoUrl`          | `string`       | -        | **Required.** The video URL or platform-specific URI (the platform is auto-detected from its shape, see [Platform URLs](#platform-urls))                           |
+| `src`               | `string`       | -        | **Required.** The video URL or platform-specific URI (the platform is auto-detected from its shape, see [Platform URLs](#platform-urls))                           |
 | `title`             | `string`       | `''`     | Video title                                                                                                                                                        |
 | `poster`            | `string`       | `''`     | Poster image URL                                                                                                                                                   |
 | `aspectRatio`       | `string`       | `'16:9'` | e.g. `'16:9'`, `'9:16'`, `'4:3'`                                                                                                                                   |
@@ -122,41 +114,25 @@ import { VideoStage, HideMarker } from '@munsonlabs/video-player'
 | `autoStage`         | `boolean`      | `false`  | Immediately send this video to the stage on mount                                                                                                                  |
 | `playbackRate`      | `number`       | `1`      | Initial playback rate                                                                                                                                              |
 | `adTagUrl`          | `string`       | `''`     | VAST or VMAP ad tag URL                                                                                                                                            |
-| `adTagParams`       | `object`       | -        | Fills `{macro}` tokens on whichever ad tag URL ends up in use, see [Ads](#ads-ima--vast--vmap)                                                                     |
+| `adMacroParams`     | `object`       | -        | Fills `{macro}` tokens on whichever ad tag URL ends up in use, see [Ads](#ads-ima--vast--vmap)                                                                     |
 | `headerBidding`     | `object`       | -        | Runs a Prebid.js auction before the ad plays, see [Header bidding](#header-bidding-prebidjs)                                                                       |
 | `tracks`            | `array`        | -        | WebVTT caption/subtitle tracks, see [Captions](#captions-webvtt)                                                                                                   |
 | `payload`           | `object`       | `{}`     | Arbitrary data attached to every `state-change` event                                                                                                              |
 | `action`            | `PlayerAction` | `null`   | Button shown in the player HUD, see [Actions](#actions)                                                                                                            |
 | `disableTapCapture` | `boolean`      | `false`  | Disables the full-video tap-to-reveal-controls overlay (tap/click still reaches embed platform UI underneath, e.g. YouTube's own)                                  |
 | `controls`          | `boolean`      | `true`   | Set `false` to render a bare `<video>` with no built-in HUD - drive playback with your own UI instead, see [Headless Controls](#headless-controls)                 |
-| `playWhenInView`    | `boolean`      | `false`  | Auto-play once at least half the player is visible, auto-pause once it isn't - e.g. for a scroll-snap feed, see [Autoplay, mute & volume](#autoplay-mute--volume)  |
-| `pinPosition`       | `PinCorner`    | -        | Pins the player to this screen corner once it scrolls out of view while playing, instead of auto-pausing - see [Pinning a single player](#pinning-a-single-player) |
+| `playInView`        | `boolean`      | `false`  | Auto-play once at least half the player is visible, auto-pause once it isn't - e.g. for a scroll-snap feed, see [Autoplay, mute & volume](#autoplay-mute--volume)  |
+| `pin`               | `PinCorner`    | -        | Pins the player to this screen corner once it scrolls out of view while playing, instead of auto-pausing - see [Pinning a single player](#pinning-a-single-player) |
 
-\* `lazy` only has an effect on `VideoItem` (default `true`), which is what actually implements the placeholder-until-clicked behaviour. `VideoPlayer` accepts the prop for type compatibility but defaults to `false` and never reads it: using `<VideoPlayer>` directly always mounts the real player immediately, regardless of `lazy`.
+\* `lazy` only has an effect on `VideoCard` (default `true`), which is what actually implements the placeholder-until-clicked behaviour. `VideoPlayer` accepts the prop for type compatibility but defaults to `false` and never reads it: using `<VideoPlayer>` directly always mounts the real player immediately, regardless of `lazy`.
 
 ### Autoplay, mute & volume
 
-Unless a video sets `muted`/`volume` explicitly, every player on the page shares one persisted audio preference (`localStorage`, updated whenever a viewer actually presses a mute button or drags a volume slider) - a newly-mounted or completely independent player starts at whatever level the viewer last chose anywhere else, instead of always resetting to full volume/unmuted.
-
-Volume is never restricted - it always follows the shared preference. Mute has one hard exception layered on top: **autoplay-ish playback with no user gesture behind it must start muted**, full stop, regardless of the stored preference. This isn't a library choice, it's the browser enforcing its autoplay-with-sound policy - unmuted `autoplay`/`playWhenInView` without a gesture is blocked or force-muted by the browser itself. This applies to:
-
-- `autoplay="true"` set directly on `VideoItem`/`VideoPlayer`.
-- A `playWhenInView` video actually starting once scrolled into view - re-checked at that exact moment (not just once at mount, since a `playWhenInView` player can sit mounted-but-paused for a long time before it actually plays), so if you unmute something else in the meantime, it plays unmuted once it becomes visible instead of forcing itself muted again.
-
-That policy is scoped to the current page load, though, not to `localStorage`: once a real gesture has resulted in unmuted playback during this session - a click that happens to land unmuted (see below), or an explicit press of a mute button/volume slider - browsers generally allow further unmuted JS-triggered playback for the rest of it, so the forced-mute rule above stops applying from that point on (a fresh reload resets it - browsers don't know or care what a past session did).
-
-A **real user gesture** is exempt from the policy entirely, and always follows the shared preference immediately, even before any gesture-less autoplay would've been allowed to (the gesture itself is what a browser needs, and it's happening right here) - and if that preference happens to be unmuted, this is itself one of the triggers above that lifts the forced-mute rule for the rest of the session, no explicit mute-button press required:
-
-- Clicking a lazy `VideoItem`'s placeholder for the first time.
-- `VideoStage`'s idle-click-to-resume and `video-toggle` window event.
-
-**`VideoStage`'s playlist skip/auto-advance is the one exception to "follow the shared preference"**: `playNext`/`playPrevious` carry the _outgoing_ video's own live mute/volume state forward to the next one, rather than the shared preference. This is the feed convention (TikTok/Reels-style), not the single-video-click convention: within one continuous playlist, audio should stick to whatever's already playing - skipping past a video you never unmuted shouldn't spontaneously turn sound on just because nothing's ever been saved globally, and skipping past one you did unmute shouldn't silently mute the next one either.
-
-An explicit `muted`/`volume` set on a specific `VideoItem`/`VideoPlayer` (or a specific playlist `VideoEntry`) always wins over all of the above, in every case.
+Unless a video sets `muted`/`volume` explicitly, every player on the page shares one persisted audio preference (`localStorage`) - a newly-mounted player starts at whatever level the viewer last chose anywhere else. **Autoplay without a user gesture always starts muted** (browser policy, not a library choice). A real user gesture (clicking a lazy placeholder, `video-toggle`) follows the shared preference immediately. `VideoStage`'s playlist skip/auto-advance carries the outgoing video's own mute/volume state forward, not the shared preference. An explicit `muted`/`volume` always wins.
 
 ### Platform URLs
 
-The platform is detected automatically from the shape of `videoUrl`; there's no separate prop to set it.
+The platform is detected automatically from the shape of `src`; there's no separate prop to set it.
 
 | Platform      | URL format                                                                                               |
 | ------------- | -------------------------------------------------------------------------------------------------------- |
@@ -186,33 +162,16 @@ registerPlatform({
 
 Call it once, before mounting any player that might see the new URL - resolution reads the registry fresh every time, so ordering (not caching) is the only thing that matters.
 
-**Embed** (`embed: true`) - the platform owns its own player (YouTube, Twitch, Vimeo). `createAdapter` is a factory returning a full `PlaybackAdapter`: every method the player needs (`play`/`pause`/`currentTime`/captions/quality/PiP/fullscreen/`on`/`off`/`dispose`), translating your SDK's own events into the ones the player listens for (`play`, `pause`, `ended`, `timeupdate`, `durationchange`, etc.).
-
-**Source** (`embed: false`) - the platform just hosts a file/manifest behind an opaque URL or ID (JW Player, Brightcove). `resolveSource` (optional - skip it if the URL is already a direct, playable link) is a function returning `{ src, type?, poster?, adTagUrl? }`; the library's own native `<video>`/hls.js/dash.js path handles playback for you, nothing else to implement.
-
-`registerPlatform` is `registerMatcher` + `registerEmbedAdapter`/`registerSourceResolver` in one call - each is exported separately too, for the rare case you only need one (e.g. adding a resolver to a platform something else already registered a matcher for).
-
-This works identically from the [web component bundles](#web-component-usage) - see [Registering a platform from a web component](#registering-a-platform-from-a-web-component) for the two extra things worth knowing there (a timing subtlety around `customElements.define()`, and the `?defer` import mode that sidesteps it for statically-declared tags).
-
-### How a URL becomes a playing embed
+- **`embed: true`** - the platform owns its own player (YouTube, Twitch, Vimeo). `createAdapter` returns a full `PlaybackAdapter`: `play`/`pause`/`currentTime`/captions/quality/PiP/fullscreen/`on`/`off`/`dispose`, translating SDK events into the common set.
+- **`embed: false`** - the platform hosts a file/manifest behind an opaque URL. `resolveSource` (optional) returns `{ src, type?, poster?, adTagUrl? }`; the native path handles playback.
 
-What happens between setting `video-url` and an embed (YouTube/Vimeo/Dailymotion/a custom platform) actually appearing on screen, end to end:
-
-1. **Platform detection.** On mount, `usePlayer` calls `resolvePlatform(videoUrl)`, which checks the URL against every registered matcher (the six built-ins plus anything added via `registerPlatform`) and returns a platform key plus whether it's `embed` or a plain source.
-2. **Adapter construction.** That result goes to `mountAdapter`, which either resolves a source URL and builds a native `<video>`/hls.js/dash.js adapter, or - for embeds - looks up the platform's registered factory (e.g. `createYoutubeAdapter`) and calls it.
-3. **Hidden mount.** The embed factory calls `createEmbedMount`, which inserts a wrapper `<div>` next to the `<video>` element and starts it at `opacity: 0; pointer-events: none`. The `<video>` (showing its `poster`) stays the visible thing for now - this is what masks the embed SDK's own iframe loading chrome (spinners, its own poster flash) until the SDK is actually ready. The adapter's `el` is this wrapper, not the `<video>` itself (unlike the native path, where `el` _is_ the `<video>`).
-4. **SDK boot + event translation.** The factory loads the platform's SDK (or reuses it if another instance already has), builds the player inside the wrapper, and translates the SDK's own events into the common set every adapter emits (`play`, `pause`, `timeupdate`, `durationchange`, etc.).
-5. **Wiring.** Back in `usePlayer`, `finalizeAdapter` stores the adapter and calls `attachPlayerEvents`, which subscribes all the reactive player state (`isPlaying`, `current`, `supportsCaptions`, ...) to those translated events.
-6. **Reveal.** Once the adapter actually starts playing for the first time (`hasStarted` flips true), a `watch` swaps visibility: the `<video>` is hidden and the wrapper fades to `opacity: 1` with pointer events restored - this is the moment the embed becomes the visible thing.
-7. **Teardown.** On unmount, the adapter's `dispose()` removes the wrapper, restores the `<video>` element's normal display, and detaches the platform's own event listeners.
-
-The native (non-embed) path skips steps 3 and 6 entirely - the `<video>` element is the adapter's `el` from the start, so there's nothing separate to reveal.
+This works identically from the [web component bundles](#web-component-usage) - see [Registering a platform from a web component](#registering-a-platform-from-a-web-component) for the `?defer` import mode that sidesteps a timing subtlety with statically-declared tags.
 
 ---
 
 ## Headless Controls
 
-Unstyled control primitives for building your own HUD instead of the built-in one (set `:controls="false"` on the player) - each is published both as a Vue component and as a `muns-controls-*` custom element from the exact same source:
+Unstyled control primitives for building your own HUD instead of the built-in one (set `:controls="false"` on the player) - each is published both as a Vue component and as a `ml-controls-*` custom element from the exact same source:
 
 Building a custom HUD out of these and never rendering `VideoPlayer`'s own built-in controls? Import `@munsonlabs/video-player/style/controls` instead of the full `/style` bundle to skip the built-in HUD/popup CSS - see [Web Component Usage](#web-component-usage) for the full breakdown of the three style bundles.
 
@@ -234,7 +193,7 @@ import {
 } from '@munsonlabs/video-player'
 ```
 
-Every control takes a `player` prop pointing at the same object `VideoPlayer`/`VideoItem`/`VideoStage` expose via a template ref:
+Every control takes a `player` prop pointing at the same object `VideoPlayer`/`VideoCard`/`VideoStage` expose via a template ref:
 
 ```vue
 <script setup>
@@ -244,7 +203,7 @@ const player = ref(null)
 </script>
 
 <template>
-  <VideoPlayer ref="player" video-url="..." :controls="false" />
+  <VideoPlayer ref="player" src="..." :controls="false" />
   <PlayButton :player="player" />
   <MuteButton :player="player" />
   <Scrubber :player="player" />
@@ -254,18 +213,18 @@ const player = ref(null)
 Or, `<label for>`-style, skip the ref and point at an element id instead:
 
 ```vue
-<VideoPlayer id="my-player" video-url="..." :controls="false" />
+<VideoPlayer id="my-player" src="..." :controls="false" />
 <PlayButton for="my-player" />
 ```
 
-`player` and `for` are both optional - if both are given, `player` wins. Each button's own CSS uses `:where()` (zero specificity), so a single class you add always wins, and most expose their state via a scoped slot for full custom markup (e.g. `PlayButton`'s `#default="{ isPlaying }"`). See [Web Component Usage](#web-component-usage) for using these as raw custom elements (`<muns-controls-play-button>` etc.) outside Vue.
+`player` and `for` are both optional - if both are given, `player` wins. Each button's own CSS uses `:where()` (zero specificity), so a single class you add always wins, and most expose their state via a scoped slot for full custom markup (e.g. `PlayButton`'s `#default="{ isPlaying }"`). See [Web Component Usage](#web-component-usage) for using these as raw custom elements (`<ml-controls-play-button>` etc.) outside Vue.
 
 ### Transcript
 
-`Transcript` renders a clickable transcript for the linked player: pass `cues` as `{ time, end?, text }[]` (times in seconds), clicking a cue seeks to its timestamp (starting playback first if paused), and the cue at the playhead is highlighted and kept scrolled into view as playback progresses:
+`Transcript` renders a clickable transcript for the linked player: pass `cues` as `{ time, end?, text }[]` (times in seconds), clicking a cue seeks to its timestamp (starting playback first if paused), and the cue at the playhead is highlighted and kept scrolled into view:
 
 ```vue
-<VideoPlayer id="my-player" video-url="..." />
+<VideoPlayer id="my-player" src="..." />
 <Transcript
   for="my-player"
   :cues="[
@@ -276,16 +235,14 @@ Or, `<label for>`-style, skip the ref and point at an element id instead:
 />
 ```
 
-- Unlike captions/quality, this works on **every** platform (YouTube/Vimeo/Dailymotion included) - it only needs the current time and `seek`, which every adapter has.
-- `end` is optional: when set, nothing is highlighted between that cue's `end` and the next cue's start (a silence/music gap); when omitted, a cue stays highlighted until the next one starts.
-- Auto-scroll pauses while the pointer is over the list, so it never fights the user's own scrolling.
-- A scoped slot customises each cue's markup: `#default="{ cue, index, isActive, formatTime }"`.
-- As a custom element (`<muns-controls-transcript>`), pass cues as an inline JSON string attribute: `cues='[{"time":0,"text":"..."}]'`.
-- Clicking a cue before the video has loaded (a lazy `VideoItem`, an unstarted player) starts playback instead - jumping needs the duration, which isn't known yet at that point.
+- Works on **every** platform (YouTube/Vimeo/Dailymotion included) - only needs current time and `seek`.
+- `end` is optional: when set, nothing is highlighted between that cue's `end` and the next cue's start.
+- Auto-scroll pauses while the pointer is over the list. A scoped slot customises each cue's markup: `#default="{ cue, index, isActive, formatTime }"`.
+- As a custom element (`<ml-controls-transcript>`), pass cues as an inline JSON string attribute: `cues='[{"time":0,"text":"..."}]'`.
 
 ### Building your own wrapper component
 
-`useForwardedPlayer` is what `VideoItem`/`VideoStage` themselves use to forward a template-ref'd `VideoPlayer`'s controls/state onto their own `defineExpose` - the same mechanism is available for building a custom wrapper component of your own:
+`useForwardedPlayer` is what `VideoCard`/`VideoStage` themselves use to forward a template-ref'd `VideoPlayer`'s controls/state onto their own `defineExpose` - the same mechanism is available for building a custom wrapper component of your own:
 
 ```vue
 <script setup>
@@ -300,94 +257,75 @@ defineExpose(forwarded)
 </template>
 ```
 
-`useForwardedPlayer` owns the ref itself - bind `playerRef` on the wrapped `VideoPlayer`, and spread (or pass) `forwarded` into your own `defineExpose`, so callers holding a ref to your wrapper get the same imperative API `VideoPlayer` exposes. Pass a `guard` callback to intercept a method call before it reaches the underlying player - return `false` to swallow it, or run a side effect (e.g. mounting a lazy placeholder first) before returning `true`.
-
-Because it's wired up via `defineExpose`, this works the same way whether your wrapper is used as a Vue component (a template ref) or as a custom element ([Web Component Usage](#web-component-usage)) - Vue copies `defineExpose`d properties onto the element itself, so `document.querySelector('muns-video-item').togglePlay()` calls the same forwarded method a Vue template ref would.
-
----
-
-## Events
-
-### `state-change`
-
-Emitted by `VideoItem`, `VideoPlayer`, and `VideoStage`.
-
-```ts
-interface StateChangeEvent {
-  type:
-    | 'play'
-    | 'pause'
-    | 'ended'
-    | 'seeked'
-    | 'error'
-    | 'adstart'
-    | 'adend'
-    | 'volumechange'
-    | 'ratechange'
-    | 'captionchange'
-    | 'qualitychange'
-    | 'pipchange'
-    | 'loopchange'
-    | 'firstQuartile'
-    | 'midpoint'
-    | 'thirdQuartile'
-    | 'controlsopen'
-    | 'controlsclose'
-    | 'stageopen'
-    | 'stageclose'
-    | 'bufferstart'
-    | 'bufferend'
-    | 'timeupdate'
-    | 'tap'
-  currentTime: number
-  duration: number
-  src: string
-  error?: { code: number; message: string } | null
-  isMuted?: boolean // volumechange only
-  playbackRate?: number // ratechange only
-  captionIndex?: number | null // captionchange only; null means captions are off
-  qualityIndex?: number | null // qualitychange only; null means Auto
-  isPipActive?: boolean // pipchange only
-  isLooping?: boolean // loopchange only
-  element?: HTMLElement | null // controlsopen/controlsclose only
-  payload?: Record<string, unknown>
-}
-```
-
-`firstQuartile` / `midpoint` / `thirdQuartile` fire once each as playback crosses 25%, 50%, and 75% of the video's duration. This is useful for analytics integrations that expect IAB-style progress milestones. They reset and can fire again on loop restart.
-
-`controlsopen` / `controlsclose` fire when the expanded controls popup mounts/unmounts (e.g. via the "show controls" button), with `element` set to the popup's root DOM node: handy for positioning your own UI relative to it, or measuring it. On `controlsclose`, `element` is a snapshot of the closing node; it's detached from the DOM immediately after.
+`useForwardedPlayer` owns the ref itself - bind `playerRef` on the wrapped `VideoPlayer`, and spread (or pass) `forwarded` into your own `defineExpose`, so callers holding a ref to your wrapper get the same imperative API `VideoPlayer` exposes. Pass a `guard` callback to intercept method calls before they reach the underlying player.
 
-`stageopen` / `stageclose` fire from `VideoStage` only, when the stage mounts its inner player (the first video arrives) and when it tears it down again. Like `controlsopen`/`controlsclose`, they arrive on the same `state-change` stream rather than as a separate event.
+Because it's wired up via `defineExpose`, this works the same way whether your wrapper is used as a Vue component (a template ref) or as a custom element ([Web Component Usage](#web-component-usage)) - Vue copies `defineExpose`d properties onto the element itself.
 
-`captionchange` / `qualitychange` fire on every `setCaptionTrack()`/`setQuality()` call (whichever menu triggered it) and whenever the adapter detects the active track/level changed on its own (e.g. hls.js's/dash.js's own ABR switching), but never before playback has started (so the initial caption/quality detection at mount doesn't get reported as a "change"). See [Captions](#captions-webvtt) and [Video Quality](#video-quality-hls--dash).
+### Exposing a plain Vue player to independent, non-Vue code
 
-`tap` fires whenever the full-video tap-to-reveal-controls overlay is tapped/clicked (see `disableTapCapture`), regardless of `controls`. With the built-in HUD (`controls: true`) this is the same gesture that reveals it; with `controls: false` it's the only signal a headless consumer gets for "the user tapped the video", useful for showing/hiding your own custom HUD in response.
-
-`pipchange` fires whenever Picture-in-Picture is entered or exited, whether that came from the player's own PiP button or the user closing the browser's floating PiP window directly.
-
-`loopchange` fires whenever `toggleLoop()` is called (e.g. from the "Loop" row in the controls menu), never before playback has started.
-
-`bufferstart` fires when the player has been stalled on `waiting` for longer than the buffering-spinner delay; `bufferend` fires once `playing`/`canplay` resolves it (or on `ended`). Useful for tracking rebuffer count/ratio.
-
-On `error`, the player shows a "Retry" button that re-attempts loading the current source. You can also trigger this yourself via a template ref on `VideoPlayer`, which exposes a `retry()` method along with `togglePlay()`, `seek()`, `toggleMute()`, `setVolume()`, `toggleFullscreen()`, `toggleLoop()`, `setPlaybackRate()`, `setCaptionTrack()`, `setQuality()`, and `togglePip()`. Note this is on `VideoPlayer` specifically: `VideoItem` doesn't forward a ref to it, since it may be showing a lazy placeholder instead:
+A plain `<VideoPlayer>`/`<VideoCard>`/`<VideoStage>` used the normal Vue way doesn't expose its API onto the DOM - its state lives on the Vue component instance, reachable only via a template ref inside your own app. `exposePlayerOnElement` bridges that gap for code with no access to your Vue app (a third party's own script, a `<ml-controls-*>` custom element from a separate bundle):
 
 ```vue
 <script setup>
-import { ref } from 'vue'
-const player = ref(null)
+import { ref, onMounted } from 'vue'
+import { VideoPlayer, exposePlayerOnElement } from '@munsonlabs/video-player'
+
+const playerRef = ref(null)
+const wrapperEl = ref(null)
+onMounted(() => exposePlayerOnElement(wrapperEl.value, playerRef.value))
 </script>
 
 <template>
-  <VideoPlayer ref="player" video-url="..." />
-  <button @click="player.retry()">Retry</button>
+  <div id="my-player" ref="wrapperEl">
+    <VideoPlayer ref="playerRef" src="..." />
+  </div>
 </template>
 ```
 
-```vue
-<VideoItem video-url="..." @state-change="onStateChange" />
+```html
+<!-- a completely separate script/bundle, e.g. a third party's own -->
+<script type="module">
+  import '@munsonlabs/video-player/element/controls'
+</script>
+<ml-controls-transcript for="my-player" cues='[{"time":0,"text":"..."}]'></ml-controls-transcript>
 ```
 
+State fields are copied as live getters (not a one-time snapshot) and methods directly. `el` doesn't need to be the player's own root element - a wrapper `<div>` works the same.
+
+---
+
+## Events
+
+### `state-change`
+
+Emitted by `VideoCard`, `VideoPlayer`, and `VideoStage`. Every event includes `currentTime`, `duration`, `src`, and `payload` (arbitrary user data).
+
+| Event                            | When it fires                                                                                        | Extra fields                                               |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `play`                           | Playback starts or resumes                                                                           | —                                                          |
+| `pause`                          | Playback pauses                                                                                      | —                                                          |
+| `ended`                          | Playback reaches the end                                                                             | —                                                          |
+| `seeked`                         | Seek completes                                                                                       | —                                                          |
+| `error`                          | Source fails to load/play; player shows a "Retry" button                                             | `error: { code, message }`                                 |
+| `adstart`                        | Ad begins playing                                                                                    | —                                                          |
+| `adend`                          | Ad finishes                                                                                          | —                                                          |
+| `volumechange`                   | Volume or mute state changes                                                                         | `isMuted`                                                  |
+| `ratechange`                     | Playback rate changes                                                                                | `playbackRate`                                             |
+| `captionchange`                  | Active caption track changes (fires on `setCaptionTrack()` and ABR-driven changes, but not at mount) | `captionIndex` (null = off)                                |
+| `qualitychange`                  | Active quality level changes (fires on `setQuality()` and ABR-driven changes, but not at mount)      | `qualityIndex` (null = Auto)                               |
+| `pipchange`                      | PiP entered or exited (from player button or browser floating window)                                | `isPipActive`                                              |
+| `loopchange`                     | Loop toggled (not before playback starts)                                                            | `isLooping`                                                |
+| `firstQuartile`                  | Playback crosses 25% of duration                                                                     | —                                                          |
+| `midpoint`                       | Playback crosses 50% of duration                                                                     | —                                                          |
+| `thirdQuartile`                  | Playback crosses 75% of duration                                                                     | —                                                          |
+| `controlsopen` / `controlsclose` | Expanded controls popup mounts/unmounts                                                              | `element` (popup root node; on close, a detached snapshot) |
+| `stageopen` / `stageclose`       | Stage mounts its inner player / tears it down (stage only)                                           | —                                                          |
+| `bufferstart` / `bufferend`      | Buffering begins (after stall delay) / resolves                                                      | —                                                          |
+| `timeupdate`                     | Regular time update during playback                                                                  | —                                                          |
+| `tap`                            | Full-video tap-to-reveal overlay is tapped; only signal for `controls: false` consumers              | —                                                          |
+
+`firstQuartile`/`midpoint`/`thirdQuartile` reset and fire again on loop restart. `captionchange`/`qualitychange` never fire before playback starts.
+
 ---
 
 ## Actions
@@ -397,35 +335,19 @@ The `action` prop adds a button to the player HUD. Pass a built-in string or a c
 ### Built-in actions
 
 ```vue
-<VideoItem action="mute" ... />
-<VideoItem action="loop" ... />
-<VideoItem action="autoplay" ... />
+<VideoCard action="mute" ... />
+<VideoCard action="loop" ... />
+<VideoCard action="autoplay" ... />
 ```
 
 `action="autoplay"` toggles [auto-advance](#playlists) and only makes sense when rendered inside a `VideoStage` with a `playlist` set: it reads and flips the same `autoAdvance` state as the controls popup's built-in "Auto" button, just as a HUD button instead.
 
 ### Custom action
 
-```ts
-interface CustomAction {
-  icon: string // SVG string
-  label: string
-  onClick: () => void
-}
-```
+Pass an object with `icon` (SVG string), `label`, and `onClick`:
 
 ```vue
-<script setup>
-const saveAction = {
-  icon: `<svg .../>`,
-  label: 'Save',
-  onClick: () => console.log('saved'),
-}
-</script>
-
-<template>
-  <VideoItem :action="saveAction" ... />
-</template>
+<VideoCard :action="{ icon: '<svg .../>', label: 'Save', onClick: () => console.log('saved') }" ... />
 ```
 
 ---
@@ -435,49 +357,38 @@ const saveAction = {
 **Step by step:**
 
 1. Get a VAST or VMAP ad tag URL. For testing, use [Google's public IMA sample tags](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags); for production, this comes from your ad server (Google Ad Manager): ask whoever manages ad ops for the tag, or build it yourself if you already know the ad unit path.
-2. Pass it as `adTagUrl` on `VideoItem`/`VideoPlayer`. That's it for a basic pre-roll/VMAP schedule: the Google IMA SDK is loaded automatically on demand, nothing else to configure.
+2. Pass it as `adTagUrl` on `VideoCard`/`VideoPlayer`. That's it for a basic pre-roll/VMAP schedule: the Google IMA SDK is loaded automatically on demand, nothing else to configure.
 3. Confirm it's working: watch for `adstart`/`adend` on the `state-change` event, or check the Network tab for a request to `pubads.g.doubleclick.net` (or wherever your ad server lives) when the video plays.
-4. Only if your ad tag is a **macro template** (contains literal `{tokenName}` placeholders, as Brightcove's auto-discovered ad tags usually do, see below) do you need `adTagParams` too. Otherwise skip it entirely.
+4. Only if your ad tag is a **macro template** (contains literal `{tokenName}` placeholders, as Brightcove's auto-discovered ad tags usually do, see below) do you need `adMacroParams` too. Otherwise skip it entirely.
 
 ```vue
-<VideoItem video-url="https://..." ad-tag-url="https://pubads.g.doubleclick.net/..." />
+<VideoCard src="https://..." ad-tag-url="https://pubads.g.doubleclick.net/..." />
 ```
 
 Ads are not supported on YouTube, Vimeo, or Dailymotion.
 
-Some platforms (currently Brightcove) auto-discover their own ad tag URL: the platform's own wins if you don't pass `adTagUrl` yourself. Brightcove's ad tag URLs are typically macro templates (e.g. `...&iu={adUnit}&vid={referenceId}&rdid={rdid}&cust_params={customParameters}`), not ready-to-use URLs. `adTagParams` fills these in on **whichever** ad tag URL ends up in use, prop-supplied or auto-discovered, without needing to know or duplicate where the base URL came from:
+Some platforms (currently Brightcove) auto-discover their own ad tag URL: the platform's own wins if you don't pass `adTagUrl` yourself. Brightcove's ad tag URLs are typically macro templates (e.g. `...&iu={adUnit}&vid={referenceId}&cust_params={customParameters}`), not ready-to-use URLs. `adMacroParams` fills these in on **whichever** ad tag URL ends up in use, prop-supplied or auto-discovered:
 
 ```vue
-<VideoItem
-  video-url="https://players.brightcove.net/..."
-  :ad-tag-params="{
-    adUnit: 'network/section',
-    referenceId: videoId,
-    rdid: deviceId,
-    idtype: 'idfa',
-    is_lat: 0,
-    customParameters: 'pageType=article&contentId=123',
-  }"
-/>
+<VideoCard src="https://players.brightcove.net/..." :ad-tag-params="{ adUnit: 'network/section', referenceId: videoId, rdid: deviceId }" />
 ```
 
-Name each key exactly after the macro it fills, not the query param it happens to sit inside (`vid={referenceId}` means the key is `referenceId`, not `vid`). A key with no matching `{macro}` in the URL is a no-op: this only fills in existing macros, it doesn't add new query params, so it has no effect on a non-templated ad tag URL (JW, or one you built by hand).
+Name each key exactly after the macro it fills (`vid={referenceId}` means the key is `referenceId`, not `vid`). A key with no matching `{macro}` is a no-op.
 
 ### Header bidding (Prebid.js)
 
 **Step by step:**
 
-1. Confirm your organisation already runs Prebid.js somewhere on the page: check for `window.pbjs` in the console. If it's not there, this isn't something to set up from this package; talk to whoever manages ad ops or your header-bidding wrapper vendor, since Prebid deployments are custom builds specific to which bidders you use (see below for why this player doesn't load Prebid itself).
-2. Get a Prebid **video ad unit** config from ad ops/your bidder: an object with `code`, `mediaTypes.video` (player size, mime types, etc.), and a `bids` array with your bidder's specific params (e.g. AppNexus's `placementId`). This is the same object your org's existing Prebid setup already uses elsewhere for video slots, if one exists.
-3. Get the GAM ad unit path (`iu`) to target: same source as step 1 in [Ads](#ads-ima--vast--vmap) above.
-4. Pass both as `headerBidding: { adUnit, params: { iu: '...' } }`, on the same `VideoItem`/`VideoPlayer` that already has a plain `adTagUrl`/`adTagParams` set as the fallback (step 2 of the Ads section). Never rely on `headerBidding` alone with nothing to fall back to.
-5. Verify: after playing, run `pbjs.getBidResponsesForAdUnitCode('your-ad-unit-code')` in the console to confirm a bid came back, and check the Network tab for `hb_bidder`/`hb_pb`/etc. in the actual ad request's `cust_params` to confirm the winning bid's targeting made it into the request IMA sent.
+1. Confirm your organisation already runs Prebid.js somewhere on the page (`window.pbjs` in the console). If not, this isn't something to set up from this package.
+2. Get a Prebid **video ad unit** config from ad ops (with `code`, `mediaTypes.video`, and `bids`) and the GAM ad unit path (`iu`).
+3. Pass both as `headerBidding: { adUnit, params: { iu: '...' } }`, alongside a plain `adTagUrl`/`adMacroParams` as fallback. Never rely on `headerBidding` alone.
+4. Verify: run `pbjs.getBidResponsesForAdUnitCode('your-ad-unit-code')` in the console after playing.
 
-The auction runs **in the background** and is never awaited: it can't block mounting, playback, or controls. Its result is only used if it's ready by the time the ad is actually requested (on the viewer's first play); otherwise the ad request goes out with whatever `adTagUrl`/`adTagParams` already resolved to, same as if `headerBidding` weren't set at all:
+The auction runs **in the background** and is never awaited: it can't block mounting, playback, or controls. Its result is only used if ready by the time the ad is requested (first play); otherwise the plain ad tag is used. Every failure mode (no `pbjs`, timeout, no bid, `buildVideoUrl()` throwing) fails open:
 
 ```vue
-<VideoItem
-  video-url="https://players.brightcove.net/..."
+<VideoCard
+  src="https://players.brightcove.net/..."
   :header-bidding="{
     adUnit: {
       code: 'video-preroll',
@@ -490,7 +401,7 @@ The auction runs **in the background** and is never awaited: it can't block moun
 />
 ```
 
-`adUnit` is a standard Prebid video ad unit, the same object you'd otherwise hand to `pbjs.addAdUnits()`. `params` is passed through to `buildVideoUrl()` (GAM ad tag params, e.g. `iu`). `timeoutMs` (default `1000`) bounds the Prebid auction itself. Every failure mode (no `window.pbjs`, the auction timing out, no bid won, `buildVideoUrl()` throwing) fails open to whatever `adTagUrl`/`adTagParams` would have resolved to; combined with never being awaited, a header-bidding hiccup can't block or break anything else in the player, ever.
+`adUnit` is a standard Prebid video ad unit. `params` is passed through to `buildVideoUrl()` (GAM ad tag params). `timeoutMs` (default `1000`) bounds the auction. Every failure mode fails open to whatever `adTagUrl`/`adMacroParams` would have resolved to.
 
 ### Ad overlay UI
 
@@ -498,7 +409,7 @@ While an ad is playing, a small overlay shows an "Ad" badge with a countdown to
 
 ### Ad visibility behaviour
 
-An ad pauses itself whenever the tab is hidden or the window loses focus (checked on `visibilitychange`/`blur`, and once up front when the ad starts, so a mid-roll beginning on an already-backgrounded tab is caught too): no manual setup needed, and it doesn't auto-resume, since the point is to stop burning an impression on nobody watching. If Picture-in-Picture is active when an ad starts, it's exited too (skipped on iOS, where the ad creative renders directly into the same `<video>` element PiP is already mirroring, so there's nothing to lose by staying in PiP there).
+An ad pauses itself whenever the tab is hidden or the window loses focus, and exits Picture-in-Picture if active (skipped on iOS, where the ad renders into the same `<video>` element PiP mirrors). The player ignores `timeupdate`/`durationchange`/`progress` events while an ad is active, so `current`/`total`/`bufferedDisplay` stay on the content's values throughout. On iOS, after a post-roll ad finishes the player restores the original content source and seeks to the end, since the IMA SDK may not restore it.
 
 ---
 
@@ -512,8 +423,8 @@ There are two ways a caption track ends up available, and you don't have to pick
 - **Everything else** (a plain MP4, or an HLS stream with no subtitle rendition of its own) needs WebVTT tracks supplied explicitly via `tracks`:
 
 ```vue
-<VideoItem
-  video-url="https://.../video.mp4"
+<VideoCard
+  src="https://.../video.mp4"
   :tracks="[
     { src: '/captions/en.vtt', kind: 'captions', srclang: 'en', label: 'English', default: true },
     { src: '/captions/fr.vtt', kind: 'captions', srclang: 'fr', label: 'Français' },
@@ -521,17 +432,7 @@ There are two ways a caption track ends up available, and you don't have to pick
 />
 ```
 
-```ts
-interface CaptionTrackDef {
-  src: string // a WebVTT file URL: <track> only understands VTT, not SRT or other subtitle formats
-  kind?: 'captions' | 'subtitles'
-  srclang?: string
-  label?: string
-  default?: boolean
-}
-```
-
-Each entry renders as a native `<track>` element: the browser fetches and parses the file itself, nothing is loaded or parsed by this package. `default: true` has the browser show that track immediately with no extra wiring; the player detects and reports this the same way as a track picked manually via the controls menu.
+`src` must be a WebVTT file URL (`<track>` only understands VTT, not SRT). Each entry renders as a native `<track>` element: the browser fetches and parses the file itself. `default: true` has the browser show that track immediately with no extra wiring.
 
 Clicking "Captions" in the controls menu cycles Off → first track → next track → ... → Off. Programmatically, a template ref on `VideoPlayer` exposes `setCaptionTrack(index)` (`null` turns captions off); see [Events](#state-change) for the `captionchange` event this fires.
 
@@ -541,11 +442,9 @@ Clicking "Captions" in the controls menu cycles Off → first track → next tra
 
 Adaptive HLS and DASH streams automatically expose a "Quality" option in the controls menu once hls.js/dash.js (or Safari's native HLS) has parsed the manifest's resolution variants: there's no prop to set and nothing to configure. Clicking it cycles Auto → highest → ... → lowest → Auto; Auto leaves the streaming engine's adaptive bitrate algorithm in control.
 
-This only applies to HLS and DASH: plain MP4/HTML5 sources have no variant levels at all, and it's unsupported on YouTube, Vimeo, and Dailymotion. Brightcove and JW Player get it for free, same reasoning as captions above.
-
-**Safari plays HLS natively instead of through hls.js** (see [Peer Dependencies](#peer-dependencies)), and native HLS has no manual quality-override hook at all: the Quality option simply won't appear there, since Safari's own adaptive bitrate algorithm is always in control on that path.
+This only applies to HLS and DASH: plain MP4/HTML5 sources have no variant levels, and it's unsupported on YouTube, Vimeo, and Dailymotion. Brightcove and JW Player get it for free, same reasoning as captions above.
 
-A manual DASH quality switch takes effect immediately, even mid-playback: dash.js is told to discard whatever it's already buffered ahead at the old quality and refetch at the new one, rather than only affecting segments requested after the switch (which could otherwise be a long way ahead of the playhead on a fast connection).
+**Safari plays HLS natively** (see [Peer Dependencies](#peer-dependencies)), and native HLS has no manual quality-override hook: the Quality option simply won't appear there.
 
 Programmatically, a template ref on `VideoPlayer` exposes `setQuality(index)` (`null` re-enables Auto); see [Events](#state-change) for the `qualitychange` event this fires.
 
@@ -563,81 +462,48 @@ Programmatically, a template ref on `VideoPlayer` exposes `togglePip()`; see [Ev
 
 ## Theming the HUD buttons
 
-Three buttons read their background and icon colour from two CSS custom properties, falling back to the default frosted-glass look when unset: the action button (mute/loop/custom/save), the central play/pause button, and the "show controls" button. The expanded controls popup (opened via the "show controls" button) is unaffected and keeps its own fixed styling.
-
 Set the variables on any ancestor of the player (e.g. a wrapper `<div>` or `:root`) to restyle all three buttons at once:
 
 ```css
 .my-video-wrapper {
-  --mvp-btn-bg: #e11d48;
-  --mvp-btn-color: #fff;
+  --mlv-btn-bg: #e11d48;
+  --mlv-btn-color: #fff;
 }
 ```
 
-Icons use `fill="currentColor"`, so `--mvp-btn-color` recolours the icon along with `--mvp-btn-bg` for the background. Hover state is a `filter: brightness()` lift on top of `--mvp-btn-bg`, so it works for both the default translucent look and a solid theme colour.
+Icons use `fill="currentColor"`, so `--mlv-btn-color` recolours the icon along with `--mlv-btn-bg` for the background. Hover state is a `filter: brightness()` lift on top of `--mlv-btn-bg`, so it works for both the default translucent look and a solid theme colour.
 
-### Controls popup position
+### Full controls popup
 
-The expanded controls popup is centred over the video by default. Set `--mvp-popup-align: flex-end` to anchor it to the bottom edge instead:
+| Variable               | Default                         | Description                                                                              |
+| ---------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `--mlv-controls-width` | `min(450px, calc(100% - 32px))` | Controls popup width                                                                     |
+| `--mlv-popup-align`    | `center`                        | Horizontal alignment of the popup (`center` or `flex-end` to dock at the bottom)         |
+| `--mlv-btn-bg`         | (frosted glass)                 | Background of action, play/pause, and show-controls buttons                              |
+| `--mlv-btn-color`      | (frosted glass)                 | Icon/text colour of the same buttons                                                     |
+| `--mlv-stage-tuck`     | `32px`                          | Width of the sliver left visible when `HideMarker` tucks the pinned stage off-screen     |
+| `--mlv-radius`         | `12px`                          | Border-radius of the pinned corner box                                                   |
+| `--mlv-accent`         | —                               | Active-state highlight colour for the loop/autoplay toggle buttons in the controls popup |
 
-```css
-.my-video-wrapper {
-  --mvp-popup-align: flex-end;
-}
-```
-
-Real fullscreen always docks the popup to the bottom regardless of this variable.
+Real fullscreen always docks the popup to the bottom regardless of `--mlv-popup-align`.
 
 ### Fullscreen controls
 
-Outside fullscreen, the full controls bar only appears after clicking "show controls" and stays open until dismissed. In real fullscreen it behaves like a standard native/YouTube-style player instead: it auto-shows on activity (mouse move, tap) and auto-hides after a short period of inactivity, with no explicit open/close step needed.
-
----
-
-## Window Events
-
-`VideoItem` and `VideoStage` communicate via window custom events. You can dispatch these yourself to control the stage from outside Vue.
-
-| Event          | Detail                                                    | Description                                    |
-| -------------- | --------------------------------------------------------- | ---------------------------------------------- |
-| `video-select` | `VideoSelectDetail`                                       | Load a video into the stage                    |
-| `video-toggle` | `{ videoUrl: string }`                                    | Play/pause a specific video in the stage       |
-| `video-state`  | `{ currentVideoUrl: string \| null, isPlaying: boolean }` | Dispatched by the stage when its state changes |
-
-```js
-// Load a video into the stage
-window.dispatchEvent(
-  new CustomEvent('video-select', {
-    detail: {
-      videoUrl: 'https://...',
-      title: 'My Video',
-      poster: 'https://...',
-      autoplay: true,
-    },
-  }),
-)
-
-// Listen for stage state changes
-window.addEventListener('video-state', (e) => {
-  console.log(e.detail.currentVideoUrl, e.detail.isPlaying)
-})
-```
+Outside fullscreen, the full controls bar only appears after clicking "show controls" and stays open until dismissed. In real fullscreen it auto-shows on activity and auto-hides after inactivity, like a standard native player.
 
 ---
 
 ## Web Component Usage
 
-Import an element bundle to register components as native custom elements. These elements render into the light DOM, not a shadow root (`shadowRoot: false`: YouTube/Vimeo/Dailymotion's SDKs mount by resolving a plain element ID, which can't see into a shadow root), so styling has nowhere encapsulated to live. Vue is an external dependency: use an import map to provide it:
+Import an element bundle to register components as native custom elements. These render into the light DOM (not shadow roots), so styling has nowhere encapsulated to live. Vue is an external dependency: use an import map to provide it.
 
 Three bundles are available: pick exactly one, since importing more than one double-registers any tag they share and throws:
 
-- `@munsonlabs/video-player/element`: everything (the built-in player plus all headless controls). Links its own styles onto the page automatically the moment it's imported, nothing else to remember there, whether you load it via a bundler, unpkg, jsdelivr, or esm.sh.
-- `@munsonlabs/video-player/element/core`: just `<muns-video-player>`/`<muns-video-stage>`/`<muns-video-item>`/`<muns-video-placeholder>`, for pages that only ever use the built-in controls. Doesn't inject any CSS itself, so also import `@munsonlabs/video-player/style/core` (or your own equivalent styles).
-- `@munsonlabs/video-player/element/controls`: just the `<muns-controls-*>` primitives, for building a custom HUD without the built-in player shell. Also doesn't inject any CSS, so import `@munsonlabs/video-player/style/controls` alongside it (or your own equivalent styles).
+- `@munsonlabs/video-player/element`: everything (player + all headless controls). Auto-injects its own CSS.
+- `@munsonlabs/video-player/element/core`: just `<ml-video-player>`/`<ml-video-stage>`/`<ml-video-card>`/`<ml-video-placeholder>`. Import `@munsonlabs/video-player/style/core` yourself.
+- `@munsonlabs/video-player/element/controls`: just the `<ml-controls-*>` primitives. Import `@munsonlabs/video-player/style/controls` alongside it.
 
-The `core`/`controls` bundles leave styling entirely up to you: defer the import, swap in your own stylesheet, or skip it if you're providing your own styles. Only the combined `element` bundle is zero-config.
-
-`/element` and `/element/core` (not `/element/controls`, which never touches platform code) each dynamically `import()` a platform's own adapter code the first time a URL for that platform actually mounts, landing in a sibling `chunks/` directory rather than the main file - a page that only ever plays plain MP4/HLS/DASH downloads none of it. Loading from a directory-serving CDN (unpkg, jsdelivr, esm.sh) needs no special handling; self-hosting either bundle means deploying its `chunks/` directory alongside it.
+`/element` and `/element/core` dynamically `import()` platform adapter code only when a URL for that platform mounts (from a sibling `chunks/` directory); self-hosting either bundle means deploying `chunks/` alongside it.
 
 ```html
 <script type="importmap">
@@ -649,11 +515,11 @@ The `core`/`controls` bundles leave styling entirely up to you: defer the import
 </script>
 <script type="module" src="@munsonlabs/video-player/element"></script>
 
-<muns-video-item
-  video-url="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4"
+<ml-video-card
+  src="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4"
   title="Big Buck Bunny"
   poster="https://storage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
-></muns-video-item>
+></ml-video-card>
 ```
 
 If you'll be playing HLS (`.m3u8`) or DASH (`.mpd`) sources, also add an import map entry for `hls.js`/`dashjs`. Each is loaded on demand via a dynamic `import(...)`, which (unlike the Vue usage, where your own bundler resolves it) has no resolution path in a plain browser without one:
@@ -674,51 +540,51 @@ If you'll be playing HLS (`.m3u8`) or DASH (`.mpd`) sources, also add an import
 
 Core (in `/element` and `/element/core`):
 
-| Element                    | Vue equivalent       |
-| -------------------------- | -------------------- |
-| `<muns-video-item>`        | `<VideoItem>`        |
-| `<muns-video-stage>`       | `<VideoStage>`       |
-| `<muns-video-player>`      | `<VideoPlayer>`      |
-| `<muns-video-placeholder>` | `<VideoPlaceholder>` |
-| `<muns-hide-marker>`       | `<HideMarker>`       |
+| Element                  | Vue equivalent       |
+| ------------------------ | -------------------- |
+| `<ml-video-card>`        | `<VideoCard>`        |
+| `<ml-video-stage>`       | `<VideoStage>`       |
+| `<ml-video-player>`      | `<VideoPlayer>`      |
+| `<ml-video-placeholder>` | `<VideoPlaceholder>` |
+| `<ml-hide-marker>`       | `<HideMarker>`       |
 
 Controls (in `/element` and `/element/controls`), see [Headless Controls](#headless-controls) for what each does:
 
-| Element                                | Vue equivalent         |
-| -------------------------------------- | ---------------------- |
-| `<muns-controls-play-button>`          | `<PlayButton>`         |
-| `<muns-controls-mute-button>`          | `<MuteButton>`         |
-| `<muns-controls-fullscreen-button>`    | `<FullscreenButton>`   |
-| `<muns-controls-loop-button>`          | `<LoopButton>`         |
-| `<muns-controls-pip-button>`           | `<PipButton>`          |
-| `<muns-controls-captions-button>`      | `<CaptionsButton>`     |
-| `<muns-controls-quality-button>`       | `<QualityButton>`      |
-| `<muns-controls-playback-rate-button>` | `<PlaybackRateButton>` |
-| `<muns-controls-buffering>`            | `<Buffering>`          |
-| `<muns-controls-scrubber>`             | `<Scrubber>`           |
-| `<muns-controls-volume-slider>`        | `<VolumeSlider>`       |
-| `<muns-controls-time-display>`         | `<TimeDisplay>`        |
-| `<muns-controls-transcript>`           | `<Transcript>`         |
+| Element                              | Vue equivalent         |
+| ------------------------------------ | ---------------------- |
+| `<ml-controls-play-button>`          | `<PlayButton>`         |
+| `<ml-controls-mute-button>`          | `<MuteButton>`         |
+| `<ml-controls-fullscreen-button>`    | `<FullscreenButton>`   |
+| `<ml-controls-loop-button>`          | `<LoopButton>`         |
+| `<ml-controls-pip-button>`           | `<PipButton>`          |
+| `<ml-controls-captions-button>`      | `<CaptionsButton>`     |
+| `<ml-controls-quality-button>`       | `<QualityButton>`      |
+| `<ml-controls-playback-rate-button>` | `<PlaybackRateButton>` |
+| `<ml-controls-buffering>`            | `<Buffering>`          |
+| `<ml-controls-scrubber>`             | `<Scrubber>`           |
+| `<ml-controls-volume-slider>`        | `<VolumeSlider>`       |
+| `<ml-controls-time-display>`         | `<TimeDisplay>`        |
+| `<ml-controls-transcript>`           | `<Transcript>`         |
 
 ### Passing objects as web component attributes
 
-Boolean and string props map directly to HTML attributes. Object props (`payload`) can be passed as inline JSON strings: Vue's custom element runtime parses them automatically:
+Boolean and string props map directly to HTML attributes. Object props (`payload`) can be passed as inline JSON strings:
 
 ```html
-<muns-video-item video-url="https://..." ad-tag-url="https://..." payload='{"articleId":"123"}'></muns-video-item>
+<ml-video-card src="https://..." ad-tag-url="https://..." payload='{"articleId":"123"}'></ml-video-card>
 ```
 
 For `action` (which contains a function), set it via JavaScript:
 
 ```js
-const player = document.querySelector('muns-video-item')
+const player = document.querySelector('ml-video-card')
 player.action = { icon: '<svg.../>', label: 'Save', onClick: () => {} }
 ```
 
 ### Listening to events
 
 ```js
-const player = document.querySelector('muns-video-item')
+const player = document.querySelector('ml-video-card')
 player.addEventListener('state-change', (e) => {
   console.log(e.detail)
 })
@@ -726,10 +592,10 @@ player.addEventListener('state-change', (e) => {
 
 ### Calling player methods
 
-`<muns-video-item>`/`<muns-video-stage>` expose the same forwarded API a Vue template ref would (see [Building your own wrapper component](#building-your-own-wrapper-component)) - methods and state land directly on the element itself:
+`<ml-video-card>`/`<ml-video-stage>` expose the same forwarded API a Vue template ref would (see [Building your own wrapper component](#building-your-own-wrapper-component)) - methods and state land directly on the element itself:
 
 ```js
-const player = document.querySelector('muns-video-item')
+const player = document.querySelector('ml-video-card')
 player.togglePlay()
 console.log(player.isPlaying)
 ```
@@ -743,15 +609,15 @@ console.log(player.isPlaying)
   import { registerPlatform } from 'https://esm.sh/@munsonlabs/video-player/element/core'
   registerPlatform({ key: 'acme', test: (url) => url.includes('acme.tv'), embed: true, createAdapter: createAcmeAdapter })
 
-  const player = document.createElement('muns-video-player')
-  player.setAttribute('video-url', 'https://acme.tv/watch/123')
+  const player = document.createElement('ml-video-player')
+  player.setAttribute('src', 'https://acme.tv/watch/123')
   document.body.append(player)
 </script>
 ```
 
-One thing worth knowing that doesn't come up in the Vue case - **timing**: importing `/element`/`/element/core` calls `customElements.define()`, which synchronously upgrades any matching tag already sitting in the DOM as part of that same call - and a `<script type="module">` defers until after the whole document has been parsed, so a _statically-declared_ `<muns-video-player>` tag is already sitting in the DOM by the time your script runs, and gets upgraded (running `usePlayer`'s adapter resolution) as soon as the import above evaluates, before your own `registerPlatform` call on the next line has a chance to run. Creating the tag from script, after registering, as above sidesteps this entirely.
+**Timing note:** importing `/element`/`/element/core` calls `customElements.define()`, which synchronously upgrades any matching tag already in the DOM. A statically-declared `<ml-video-player>` gets upgraded before your `registerPlatform` call on the next line. Creating the tag from script, after registering, as above sidesteps this.
 
-If your tags are statically declared in the markup (so you can't create them after registering), load `/element/core` with a **`?defer`** query instead: it skips the automatic `customElements.define()` on import, so you register your platform first and then call the exported `defineElements()` yourself - the static tags upgrade at that point, with your platform already in the registry:
+If your tags are statically declared, load `/element/core` with a **`?defer`** query instead: it skips the automatic `customElements.define()`, so you register your platform first and then call the exported `defineElements()` yourself:
 
 ```html
 <script type="module">
@@ -760,13 +626,10 @@ If your tags are statically declared in the markup (so you can't create them aft
   defineElements()
 </script>
 
-<muns-video-player video-url="https://acme.tv/watch/123"></muns-video-player>
+<ml-video-player src="https://acme.tv/watch/123"></ml-video-player>
 ```
 
-- `?defer` is read from the `/element/core` module's own URL, so import `/element/core` directly with the query (or point an import-map entry at a URL that includes it). The combined `/element` bundle always registers immediately - it imports the core module internally without the query.
-- `defineElements()` is idempotent: it only defines whichever tags aren't already registered, so calling it when the elements were already defined is a no-op rather than a double-registration error.
-
-Note this requires an `import` from wherever `/element`/`/element/core` is loaded - there's no way to reach the registry from a script that doesn't (or can't) import the package itself.
+`?defer` is read from the `/element/core` module's own URL. `defineElements()` is idempotent: it only defines whichever tags aren't already registered.
 
 ---