@munsonlabs/video-player 0.1.6 → 0.2.1

package/README.md

@@ -27,6 +27,19 @@ import '@munsonlabs/video-player/style'
 </template>
 ```
 
+### 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.
+
+```vue
+<VideoItem video-url="https://cdn.jwplayer.com/videos/O5chtspP-4VHSaSK0.mp4" pin-position="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).
+- 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.
+- `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.
@@ -45,27 +58,19 @@ import '@munsonlabs/video-player/style'
 
 ### 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 `VideoItem`'s props) to let the stage track the currently-playing video's position within it. Position updates automatically when a user clicks a `VideoItem` 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
@@ -88,37 +93,43 @@ 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: `--mvp-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
 
-| 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))                     |
-| `title`             | `string`       | `''`     | Video title                                                                                                                                                  |
-| `poster`            | `string`       | `''`     | Poster image URL                                                                                                                                             |
-| `aspectRatio`       | `string`       | `'16:9'` | e.g. `'16:9'`, `'9:16'`, `'4:3'`                                                                                                                             |
-| `autoplay`          | `boolean`      | `false`  | Autoplay on mount (mutes automatically)                                                                                                                      |
-| `muted`             | `boolean`      | `false`  | Start muted                                                                                                                                                  |
-| `lazy`              | `boolean`      | `true`\* | Show placeholder until clicked                                                                                                                               |
-| `nativeUi`          | `boolean`      | `false`  | Use the platform's native controls (YouTube, Vimeo, Dailymotion only)                                                                                        |
-| `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)                                                               |
-| `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. Implies `muted` unless `muted` is set explicitly |
+| 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))                           |
+| `title`             | `string`       | `''`     | Video title                                                                                                                                                        |
+| `poster`            | `string`       | `''`     | Poster image URL                                                                                                                                                   |
+| `aspectRatio`       | `string`       | `'16:9'` | e.g. `'16:9'`, `'9:16'`, `'4:3'`                                                                                                                                   |
+| `autoplay`          | `boolean`      | `false`  | Autoplay on mount, see [Autoplay, mute & volume](#autoplay-mute--volume)                                                                                           |
+| `muted`             | `boolean`      | -        | Force a starting mute state - if unset, follows the shared audio preference, see [Autoplay, mute & volume](#autoplay-mute--volume)                                 |
+| `volume`            | `number`       | -        | Force a starting volume (0-1) - if unset, follows the shared audio preference, see [Autoplay, mute & volume](#autoplay-mute--volume)                               |
+| `lazy`              | `boolean`      | `true`\* | Show placeholder until clicked                                                                                                                                     |
+| `nativeUi`          | `boolean`      | `false`  | Use the platform's native controls (YouTube, Vimeo, Dailymotion only)                                                                                              |
+| `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)                                                                     |
+| `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) |
 
 \* `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`.
 
+### Autoplay, mute & volume
+
+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.
@@ -134,6 +145,28 @@ The platform is detected automatically from the shape of `videoUrl`; there's no
 
 \* `PLAYER_ID_EMBED` is one path segment: `{PLAYER_ID}_{EMBED_NAME}` (e.g. `abc123_default` for the account's default player), which is exactly the URL Brightcove Studio's "Publish" panel gives you for an embed.
 
+### Adding a custom platform
+
+`registerPlatform` teaches the player about a platform beyond the six above, without forking the package:
+
+```ts
+import { registerPlatform } from '@munsonlabs/video-player'
+
+registerPlatform({
+  key: 'acme',
+  test: (url) => url.includes('acme.tv'),
+  embed: true, // true: the platform has its own SDK/iframe; false: it resolves to a plain playable file
+  createAdapter: (videoEl, options) => createAcmeAdapter(videoEl, options),
+})
+```
+
+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: 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.
+
+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
@@ -156,6 +189,7 @@ import {
   Scrubber,
   VolumeSlider,
   TimeDisplay,
+  Transcript,
 } from '@munsonlabs/video-player'
 ```
 
@@ -185,6 +219,27 @@ Or, `<label for>`-style, skip the ref and point at an element id instead:
 
 `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.
 
+### 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:
+
+```vue
+<VideoPlayer id="my-player" video-url="..." />
+<Transcript
+  for="my-player"
+  :cues="[
+    { time: 0, text: 'Welcome back to the show.' },
+    { time: 12, text: 'Today we look at the new release.' },
+    { time: 47, end: 60, text: 'Here is the demo.' },
+  ]"
+/>
+```
+
+- 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 (`<muns-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:
@@ -202,90 +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'
-    | '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.
-
-`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).
+`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.
 
-`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.
+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.
 
-`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.
+### Exposing a plain Vue player to independent, non-Vue code
 
-`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>`/`<VideoItem>`/`<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 `<muns-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" video-url="..." />
+  </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>
+<muns-controls-transcript for="my-player" cues='[{"time":0,"text":"..."}]'></muns-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 `VideoItem`, `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
@@ -304,26 +344,10 @@ The `action` prop adds a button to the player HUD. Pass a built-in string or a c
 
 ### 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>
+<VideoItem :action="{ icon: '<svg .../>', label: 'Save', onClick: () => console.log('saved') }" ... />
 ```
 
 ---
@@ -343,35 +367,24 @@ const saveAction = {
 
 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. `adTagParams` 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',
-  }"
-/>
+<VideoItem video-url="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`/`adTagParams` 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
@@ -388,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`/`adTagParams` would have resolved to.
 
 ### Ad overlay UI
 
@@ -396,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.
 
 ---
 
@@ -419,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.
 
@@ -439,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.
+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.
 
-**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.
-
-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.
 
@@ -461,8 +462,6 @@ 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
@@ -474,66 +473,37 @@ Set the variables on any ancestor of the player (e.g. a wrapper `<div>` or `:roo
 
 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.
 
-### 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:
-
-```css
-.my-video-wrapper {
-  --mvp-popup-align: flex-end;
-}
-```
+| Variable               | Default                         | Description                                                                              |
+| ---------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `--mvp-controls-width` | `min(450px, calc(100% - 32px))` | Controls popup width                                                                     |
+| `--mvp-popup-align`    | `center`                        | Horizontal alignment of the popup (`center` or `flex-end` to dock at the bottom)         |
+| `--mvp-btn-bg`         | (frosted glass)                 | Background of action, play/pause, and show-controls buttons                              |
+| `--mvp-btn-color`      | (frosted glass)                 | Icon/text colour of the same buttons                                                     |
+| `--mvp-stage-tuck`     | `32px`                          | Width of the sliver left visible when `HideMarker` tucks the pinned stage off-screen     |
+| `--mvp-radius`         | `12px`                          | Border-radius of the pinned corner box                                                   |
+| `--mvp-accent`         | —                               | Active-state highlight colour for the loop/autoplay toggle buttons in the controls popup |
 
-Real fullscreen always docks the popup to the bottom regardless of this variable.
+Real fullscreen always docks the popup to the bottom regardless of `--mvp-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 `<muns-video-player>`/`<muns-video-stage>`/`<muns-video-item>`/`<muns-video-placeholder>`. Import `@munsonlabs/video-player/style/core` yourself.
+- `@munsonlabs/video-player/element/controls`: just the `<muns-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` 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">
@@ -594,10 +564,11 @@ Controls (in `/element` and `/element/controls`), see [Headless Controls](#headl
 | `<muns-controls-scrubber>`             | `<Scrubber>`           |
 | `<muns-controls-volume-slider>`        | `<VolumeSlider>`       |
 | `<muns-controls-time-display>`         | `<TimeDisplay>`        |
+| `<muns-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>
@@ -629,6 +600,37 @@ player.togglePlay()
 console.log(player.isPlaying)
 ```
 
+### Registering a platform from a web component
+
+[`registerPlatform`](#adding-a-custom-platform) is exported from `/element` and `/element/core` too:
+
+```html
+<script type="module">
+  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')
+  document.body.append(player)
+</script>
+```
+
+**Timing note:** importing `/element`/`/element/core` calls `customElements.define()`, which synchronously upgrades any matching tag already in the DOM. A statically-declared `<muns-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, 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">
+  import { registerPlatform, defineElements } from 'https://esm.sh/@munsonlabs/video-player/element/core?defer'
+  registerPlatform({ key: 'acme', test: (url) => url.includes('acme.tv'), embed: true, createAdapter: createAcmeAdapter })
+  defineElements()
+</script>
+
+<muns-video-player video-url="https://acme.tv/watch/123"></muns-video-player>
+```
+
+`?defer` is read from the `/element/core` module's own URL. `defineElements()` is idempotent: it only defines whichever tags aren't already registered.
+
 ---
 
 ## Peer Dependencies