@videojs/html 10.2.0 → 10.3.0

package/docs/reference/api/feature-playback-rate.md

@@ -2,7 +2,7 @@
 
 Playback speed state and actions for the player store
 
-Controls speed of playback.
+Controls speed of playback. `playbackRateAvailability` is `unsupported` when the media has no playback rate, such as an embed whose provider takes no speed command.
 
 ## Import
 
@@ -14,23 +14,74 @@ The `audioFeatures` and `videoFeatures` [feature bundles](../../guides/presets.m
 
 ## API Reference
 
+### Configuration
+
+Attributes and matching properties the player element accepts. They exist only while this feature is selected.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultPlaybackRates` (attribute `default-playback-rates`) | `undefined \| null \| readonly number[] \| string` | `[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Rates the player's controls offer, in the order they cycle through them, unless a control sets its own `rates`. HTML takes a space-separated list, such as `default-playback-rates="0.5 1 1.5 2"`. Missing or empty input restores the defaults. Rates outside the media's range are left out, so YouTube, which plays up to `2`, may offer fewer. |
+
 ### State
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `playbackRates` | `readonly number[]` | Available playback rates. |
 | `playbackRate` | `number` | Current playback rate. |
+| `playbackRateAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can change its playback rate. `unsupported` when the attached media has no `playbackRate` at all, such as an embed whose provider takes no speed command. |
+| `playbackRates` | `readonly number[]` | The default rates that fit the media's range. Set them through the player, not through the store. They are listed even when the media cannot change its rate, so check `playbackRateAvailability` before offering them. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `setPlaybackRate` | `(rate: number) => void` | Set the playback rate. |
+| `setPlaybackRate` | `(rate: number) => void` | Set the playback rate, clamped to the rates the media accepts. |
+
+### Playback rates
+
+The player offers `0.5` through `2` in steps of `0.25` unless you set your own list. The [playback rate button](../components/playback-rate-button.md), the [playback rate radio group](../components/playback-rate-radio-group.md), and the `speedUp` and `speedDown` [hotkeys](../../guides/keyboard-shortcuts.md) use this list unless you give one of them its own.
+
+Set the `default-playback-rates` attribute on [`<video-player>`](../components/player.md) to a space-separated list:
+
+```html
+<video-player default-playback-rates="0.5 1 1.25 1.5 2">
+  <media-container>
+    <video src="/video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+The `defaultPlaybackRates` property also takes an array, such as `player.defaultPlaybackRates = [1, 2]`. Removing the attribute restores the defaults.
+
+The button cycles through the rates in the order you list them, and the menu shows them in that order. `speedUp` and `speedDown` move to the next faster or slower rate whatever the order, and do nothing at the fastest or slowest rate. The player ignores values that aren’t positive numbers, and repeated rates. If nothing usable is left, it falls back to the defaults.
+
+### Rates for one control
+
+To give one control a different list, set `rates` on it. The rest of the player keeps the default list. The control offers these rates as given, even ones outside the media’s range, which play at the nearest end of the range.
+
+```html
+<media-playback-rate-button rates="1 1.5 2"></media-playback-rate-button>
+```
+
+To make the speed hotkeys change speed in fixed steps instead, give `speedUp` and `speedDown` a `value`. A `value` of `0.1` moves from `1` to `1.1`, then `1.2`, and so on.
+
+### Rates outside the list
+
+The media owns the current rate, so it can be one the menu doesn’t offer, such as `1.1` set through the media API or a stepped hotkey. The menu then shows that rate as an extra item, slotted before the next faster rate. Skins set it in italics, and its accessible name is “Custom, 1.1×”. The item goes away once the rate is back on the list. Normal speed (`1`) is added the same way when your list leaves it out, but isn’t marked custom.
+
+### Media range
+
+Each media accepts rates within a range. Browsers play `0.0625` through `16`, YouTube `0.25` through `2`, and Vimeo up to `2`. The player leaves out any `defaultPlaybackRates` outside that range and keeps the rest in your order. If none are left, it offers the defaults within the range and warns in development. `setPlaybackRate` clamps a rate outside the range to the nearest end, and warns in development. That includes `0`, which would stop the picture while the player still reports playback; call `pause()` instead.
+
+`playbackRates` lists rates even for a media that can’t change its rate, so check `playbackRateAvailability` before offering them.
+
+YouTube rounds rates down to a step of `0.05`, so asking for `1.13` plays at `1.1`.
 
 ### Selector
 
 Pass `selectPlaybackRate` to [`PlayerController`](./player-controller.md) to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
 
+Check `playbackRateAvailability` before showing a playback rate control.
+
 **rate-display.ts**
 
 ```ts

package/docs/reference/api/feature-playback.md

@@ -4,6 +4,8 @@ Play/pause state and actions for the player store
 
 Controls play/pause state and tracks whether playback has started or is stalled.
 
+When the media has `autoplay`, `autoplaying` is true from the moment a source loads until playback starts. It also turns false when the autoplay is refused: browsers don’t announce that, so it shows as the media being able to play through but staying paused, and embeds report it with a `pause` or `error` event. Treat it as playback about to begin: the play button shows pause and the buffering indicator shows while it’s true, and `pause()` cancels it.
+
 ## Import
 
 ```ts
@@ -22,13 +24,15 @@ The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeature
 | `ended` | `boolean` | Whether playback has reached the end. |
 | `started` | `boolean` | Whether playback has started (played or seeked). |
 | `waiting` | `boolean` | Whether playback is stalled waiting for data. |
+| `autoplay` | `boolean` | Whether the media starts playing on its own once it can. |
+| `autoplaying` | `boolean` | Whether the media is trying to autoplay: `autoplay` is set, and playback hasn't started yet. Clears when playback starts, when `pause()` cancels it, and when the autoplay is refused. Browsers don't announce a refusal, so it shows as the media being able to play through but staying paused; embeds report one with a `pause` or `error` event. Controls treat it as playback that's about to begin. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
 | `play` | `() => Promise<void>` | Start playback. Updates `paused` immediately when the media starts. |
-| `pause` | `() => void` | Pause playback. Updates `paused` immediately. |
+| `pause` | `() => void` | Pause playback. Updates `paused` immediately, and cancels a pending autoplay. |
 
 ### Selector
 

package/docs/reference/api/html-create-player.md

@@ -175,7 +175,7 @@ Creates a typed HTML player class and bound controller.
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, typeof playbackRateFeature, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
 
 #### Return Value
 
@@ -195,7 +195,7 @@ Creates a typed HTML audio player class and bound controller.
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, typeof playbackRateFeature, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
 
 #### Return Value
 

package/docs/reference/api/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML API
 
-> API reference for the player factory, presets, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.2.0. Links are relative paths to files in this directory.
+> API reference for the player factory, presets, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.3.0. Links are relative paths to files in this directory.
 
 ## Player
 

package/docs/reference/api/media-capabilities.md

@@ -38,7 +38,7 @@ Each `isMedia*Capable` guard accepts any value and returns `false` for `null`, `
 
 A guard checks that a few members of a capability are present, then narrows to every member of that capability’s contract. The table lists both.
 
-Some media, such as embeds, can’t provide buffered ranges, text tracks, or remote playback, and report a shared empty placeholder in their place. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for that placeholder.
+Some media can’t provide buffered ranges, text tracks, or remote playback, and report a shared empty placeholder in their place. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for that placeholder. Media that can provide buffered ranges but has none yet, such as an embed before it loads, reports an empty range that is not the placeholder, so `isMediaBufferCapable` returns `true`.
 
 A guard describes what the media object supports, not its current state. `isMediaErrorCapable` returns `true` while `error` is `null`, and `isMediaVolumeCapable` returns `true` on platforms that ignore volume changes. For current state and availability, such as `volumeAvailability` from the [volume feature](./feature-volume.md), read the player’s [features](../../guides/features.md) instead.
 

package/docs/reference/api/player-store.md

@@ -31,8 +31,10 @@ Each feature links to the same entry on its reference page.
 | `ended` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-ended) | Whether playback has reached the end. |
 | `started` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-started) | Whether playback has started (played or seeked). |
 | `waiting` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-waiting) | Whether playback is stalled waiting for data. |
+| `autoplay` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-autoplay) | Whether the media starts playing on its own once it can. |
+| `autoplaying` | `boolean` | [`playbackFeature`](./feature-playback.md#playback-state-autoplaying) | Whether the media is trying to autoplay: `autoplay` is set, and playback hasn't started yet. Clears when playback starts, when `pause()` cancels it, and when the autoplay is refused. Browsers don't announce a refusal, so it shows as the media being able to play through but staying paused; embeds report one with a `pause` or `error` event. Controls treat it as playback that's about to begin. |
 | `play` | `() => Promise<void>` | [`playbackFeature`](./feature-playback.md#playback-action-play) | Start playback. Updates `paused` immediately when the media starts. |
-| `pause` | `() => void` | [`playbackFeature`](./feature-playback.md#playback-action-pause) | Pause playback. Updates `paused` immediately. |
+| `pause` | `() => void` | [`playbackFeature`](./feature-playback.md#playback-action-pause) | Pause playback. Updates `paused` immediately, and cancels a pending autoplay. |
 | `currentTime` | `number` | [`timeFeature`](./feature-time.md#time-state-currentTime) | Current playback position in seconds. |
 | `duration` | `number` | [`timeFeature`](./feature-time.md#time-state-duration) | Total duration in seconds (0 if unknown). |
 | `seeking` | `boolean` | [`timeFeature`](./feature-time.md#time-state-seeking) | Whether a seek operation is in progress. |
@@ -59,9 +61,10 @@ Each feature links to the same entry on its reference page.
 | `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-thumbnailsTrack) | The first thumbnails track, or `null` when there is none. |
 | `toggleSubtitles` | `(forceShow?: boolean) => boolean` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-toggleSubtitles) | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
 | `selectSubtitlesTrack` | `(id: string \| null) => void` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-selectSubtitlesTrack) | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
-| `playbackRates` | `readonly number[]` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRates) | Available playback rates. |
 | `playbackRate` | `number` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRate) | Current playback rate. |
-| `setPlaybackRate` | `(rate: number) => void` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-action-setPlaybackRate) | Set the playback rate. |
+| `playbackRateAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRateAvailability) | Whether the media can change its playback rate. `unsupported` when the attached media has no `playbackRate` at all, such as an embed whose provider takes no speed command. |
+| `playbackRates` | `readonly number[]` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRates) | The default rates that fit the media's range. Set them through the player, not through the store. They are listed even when the media cannot change its rate, so check `playbackRateAvailability` before offering them. |
+| `setPlaybackRate` | `(rate: number) => void` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-action-setPlaybackRate) | Set the playback rate, clamped to the rates the media accepts. |
 | `isPictureInPicture` | `boolean` | [`pipFeature`](./feature-pip.md#pip-state-isPictureInPicture) | Whether picture-in-picture mode is currently active. |
 | `pictureInPictureAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`pipFeature`](./feature-pip.md#pip-state-pictureInPictureAvailability) | Whether picture-in-picture can be requested on this platform. |
 | `requestPictureInPicture` | `() => Promise<void>` | [`pipFeature`](./feature-pip.md#pip-action-requestPictureInPicture) | Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. |

package/docs/reference/api/preset-audio.md

@@ -2,7 +2,7 @@
 
 The audio-only preset — a player, feature bundle, skins, and media for on-demand audio
 
-`@videojs/html/audio` is the preset for on-demand audio. It bundles the `<audio-player>` element, the `audioFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
+`@videojs/html/audio` is the preset for on-demand audio. It bundles the `<audio-player>` element, the `audioFeatures` bundle it is configured with, and four skins, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
 
 ## Import
 
@@ -11,13 +11,13 @@ import '@videojs/html/audio/player';
 import '@videojs/html/audio/skin';
 ```
 
-Import `@videojs/html/audio/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+Import `@videojs/html/audio/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio.js"></script>
 ```
 
-`audio-neutral.js` registers the neutral skin instead, and `audio-player.js` registers `<audio-player>` alone.
+`audio-neutral.js`, `audio-compat.js`, and `audio-scaffold.js` register the other skins instead, and `audio-player.js` registers `<audio-player>` alone.
 
 ## Usage
 
@@ -44,7 +44,7 @@ Import `@videojs/html/audio/neutral-skin` instead for the neutral skin. Or load
 | --- | --- | --- |
 | `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
 | `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
-| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+| `keep-alive` | — | Keeps the player, its store, and the UI elements inside it alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
 
 `content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
 
@@ -88,6 +88,10 @@ customElements.define('my-audio-player', PlayerElement);
 
 - [AudioSkin](../components/audio-skin.md) — the default skin, with the modern, frosted look.
 - [NeutralAudioSkin](../components/audio-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+- [CompatAudioSkin](../components/audio-compat-skin.md) — the plain, unbranded variant that avoids newer visual effects, so it looks consistent across browsers.
+- [ScaffoldAudioSkin](../components/audio-scaffold-skin.md) — the minimally styled variant of Compat, a foundation for your own design.
+
+See [Choose a skin](../../guides/skins.md#choose-a-skin) to compare them.
 
 ## Media
 
@@ -104,6 +108,8 @@ The preset root, `@videojs/html/audio`, has no side effects. Importing it never
 | `audioFeatures` | The [feature bundle](#feature-bundle). |
 | `AudioSkinElement` | The default [skin](#skins) element class. |
 | `NeutralAudioSkinElement` | The neutral [skin](#skins) element class. |
+| `CompatAudioSkinElement` | The compat [skin](#skins) element class. |
+| `ScaffoldAudioSkinElement` | The scaffold [skin](#skins) element class. |
 
 Registration entry points are side-effect-only:
 
@@ -112,5 +118,7 @@ Registration entry points are side-effect-only:
 | `@videojs/html/audio/player` | `<audio-player>` |
 | `@videojs/html/audio/skin` | `<audio-skin>`, `<media-container>`, and the UI elements the skin composes |
 | `@videojs/html/audio/neutral-skin` | `<audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/audio/compat-skin` | `<audio-compat-skin>`, `<media-container>`, and the UI elements the compat skin composes |
+| `@videojs/html/audio/scaffold-skin` | `<audio-scaffold-skin>`, `<media-container>`, and the UI elements the scaffold skin composes |
 | `@videojs/html/audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
 | `@videojs/html/audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/preset-background.md

@@ -15,7 +15,7 @@ import '@videojs/html/background/video';
 Or load the [CDN](../../guides/cdn.md) bundle that registers all three:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/background.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/background.js"></script>
 ```
 
 Unlike the other presets, the background preset has one bundle and no player-only bundle.
@@ -44,7 +44,7 @@ Unlike the other presets, the background preset has one bundle and no player-onl
 
 | Attribute | Property | Description |
 | --- | --- | --- |
-| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+| `keep-alive` | — | Keeps the player, its store, and the UI elements inside it alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
 
 The bundle has no feature that takes player inputs, so the element has no player-input attributes such as `content-title` or `poster`; `keep-alive` is the only attribute it reads. Its read-only `store` property returns its player store.
 

package/docs/reference/api/preset-live-audio.md

@@ -2,7 +2,7 @@
 
 The live audio preset — a player, feature bundle, skins, and media for live audio streams
 
-`@videojs/html/live-audio` is the preset for live audio streams. It bundles the `<live-audio-player>` element, the `liveAudioFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
+`@videojs/html/live-audio` is the preset for live audio streams. It bundles the `<live-audio-player>` element, the `liveAudioFeatures` bundle it is configured with, and four skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<audio>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
 
 ## Import
 
@@ -11,13 +11,13 @@ import '@videojs/html/live-audio/player';
 import '@videojs/html/live-audio/skin';
 ```
 
-Import `@videojs/html/live-audio/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+Import `@videojs/html/live-audio/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/live-audio.js"></script>
 ```
 
-`live-audio-neutral.js` registers the neutral skin instead, and `live-audio-player.js` registers `<live-audio-player>` alone.
+`live-audio-neutral.js`, `live-audio-compat.js`, and `live-audio-scaffold.js` register the other skins instead, and `live-audio-player.js` registers `<live-audio-player>` alone.
 
 ## Usage
 
@@ -47,7 +47,7 @@ Live streams are usually HLS, so this example plays through an HLS media compone
 | --- | --- | --- |
 | `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
 | `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
-| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+| `keep-alive` | — | Keeps the player, its store, and the UI elements inside it alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
 
 `content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
 
@@ -91,6 +91,10 @@ customElements.define('my-live-audio-player', PlayerElement);
 
 - [LiveAudioSkin](../components/live-audio-skin.md) — the default skin, which swaps the time controls for a Live button.
 - [NeutralLiveAudioSkin](../components/live-audio-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+- [CompatLiveAudioSkin](../components/live-audio-compat-skin.md) — the plain, unbranded variant that avoids newer visual effects, so it looks consistent across browsers.
+- [ScaffoldLiveAudioSkin](../components/live-audio-scaffold-skin.md) — the minimally styled variant of Compat, a foundation for your own design.
+
+See [Choose a skin](../../guides/skins.md#choose-a-skin) to compare them.
 
 ## Media
 
@@ -107,6 +111,8 @@ The preset root, `@videojs/html/live-audio`, has no side effects. Importing it n
 | `liveAudioFeatures` | The [feature bundle](#feature-bundle). |
 | `LiveAudioSkinElement` | The default [skin](#skins) element class. |
 | `NeutralLiveAudioSkinElement` | The neutral [skin](#skins) element class. |
+| `CompatLiveAudioSkinElement` | The compat [skin](#skins) element class. |
+| `ScaffoldLiveAudioSkinElement` | The scaffold [skin](#skins) element class. |
 
 Registration entry points are side-effect-only:
 
@@ -115,5 +121,7 @@ Registration entry points are side-effect-only:
 | `@videojs/html/live-audio/player` | `<live-audio-player>` |
 | `@videojs/html/live-audio/skin` | `<live-audio-skin>`, `<media-container>`, and the UI elements the skin composes |
 | `@videojs/html/live-audio/neutral-skin` | `<live-audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/live-audio/compat-skin` | `<live-audio-compat-skin>`, `<media-container>`, and the UI elements the compat skin composes |
+| `@videojs/html/live-audio/scaffold-skin` | `<live-audio-scaffold-skin>`, `<media-container>`, and the UI elements the scaffold skin composes |
 | `@videojs/html/live-audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
 | `@videojs/html/live-audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/preset-live-video.md

@@ -2,7 +2,7 @@
 
 The live video preset — a player, feature bundle, skins, and media for live video streams
 
-`@videojs/html/live-video` is the preset for live video streams. It bundles the `<live-video-player>` element, the `liveVideoFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
+`@videojs/html/live-video` is the preset for live video streams. It bundles the `<live-video-player>` element, the `liveVideoFeatures` bundle it is configured with, and four skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and [Live streams](../../guides/live-streams.md) for playing a live source.
 
 ## Import
 
@@ -11,13 +11,13 @@ import '@videojs/html/live-video/player';
 import '@videojs/html/live-video/skin';
 ```
 
-Import `@videojs/html/live-video/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+Import `@videojs/html/live-video/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/live-video.js"></script>
 ```
 
-`live-video-neutral.js` registers the neutral skin instead, and `live-video-player.js` registers `<live-video-player>` alone.
+`live-video-neutral.js`, `live-video-compat.js`, and `live-video-scaffold.js` register the other skins instead, and `live-video-player.js` registers `<live-video-player>` alone.
 
 ## Usage
 
@@ -47,7 +47,7 @@ Live streams are usually HLS, so this example plays through an HLS media compone
 | --- | --- | --- |
 | `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
 | `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
-| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+| `keep-alive` | — | Keeps the player, its store, and the UI elements inside it alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
 
 `content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
 
@@ -96,6 +96,10 @@ customElements.define('my-live-video-player', PlayerElement);
 
 - [LiveVideoSkin](../components/live-video-skin.md) — the default skin, which swaps the time controls for a Live button.
 - [NeutralLiveVideoSkin](../components/live-video-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+- [CompatLiveVideoSkin](../components/live-video-compat-skin.md) — the plain, unbranded variant that avoids newer visual effects, so it looks consistent across browsers.
+- [ScaffoldLiveVideoSkin](../components/live-video-scaffold-skin.md) — the minimally styled variant of Compat, a foundation for your own design.
+
+See [Choose a skin](../../guides/skins.md#choose-a-skin) to compare them.
 
 ## Media
 
@@ -112,6 +116,8 @@ The preset root, `@videojs/html/live-video`, has no side effects. Importing it n
 | `liveVideoFeatures` | The [feature bundle](#feature-bundle). |
 | `LiveVideoSkinElement` | The default [skin](#skins) element class. |
 | `NeutralLiveVideoSkinElement` | The neutral [skin](#skins) element class. |
+| `CompatLiveVideoSkinElement` | The compat [skin](#skins) element class. |
+| `ScaffoldLiveVideoSkinElement` | The scaffold [skin](#skins) element class. |
 
 Registration entry points are side-effect-only:
 
@@ -120,5 +126,7 @@ Registration entry points are side-effect-only:
 | `@videojs/html/live-video/player` | `<live-video-player>` |
 | `@videojs/html/live-video/skin` | `<live-video-skin>`, `<media-container>`, and the UI elements the skin composes |
 | `@videojs/html/live-video/neutral-skin` | `<live-video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/live-video/compat-skin` | `<live-video-compat-skin>`, `<media-container>`, and the UI elements the compat skin composes |
+| `@videojs/html/live-video/scaffold-skin` | `<live-video-scaffold-skin>`, `<media-container>`, and the UI elements the scaffold skin composes |
 | `@videojs/html/live-video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
 | `@videojs/html/live-video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/preset-video.md

@@ -2,7 +2,7 @@
 
 The general-purpose video preset — a player, feature bundle, skins, and media for on-demand video
 
-`@videojs/html/video` is the general-purpose preset for on-demand video. It bundles the `<video-player>` element, the `videoFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
+`@videojs/html/video` is the general-purpose preset for on-demand video. It bundles the `<video-player>` element, the `videoFeatures` bundle it is configured with, and four skins, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
 
 ## Import
 
@@ -11,13 +11,13 @@ import '@videojs/html/video/player';
 import '@videojs/html/video/skin';
 ```
 
-Import `@videojs/html/video/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+Import `@videojs/html/video/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
 ```
 
-`video-neutral.js` registers the neutral skin instead, and `video-player.js` registers `<video-player>` alone.
+`video-neutral.js`, `video-compat.js`, and `video-scaffold.js` register the other skins instead, and `video-player.js` registers `<video-player>` alone.
 
 ## Usage
 
@@ -44,7 +44,7 @@ Import `@videojs/html/video/neutral-skin` instead for the neutral skin. Or load
 | --- | --- | --- |
 | `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
 | `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
-| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+| `keep-alive` | — | Keeps the player, its store, and the UI elements inside it alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
 
 `content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
 
@@ -95,6 +95,10 @@ customElements.define('my-video-player', PlayerElement);
 
 - [VideoSkin](../components/video-skin.md) — the default skin, with the modern, frosted look.
 - [NeutralVideoSkin](../components/video-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+- [CompatVideoSkin](../components/video-compat-skin.md) — the plain, unbranded variant that avoids newer visual effects, so it looks consistent across browsers.
+- [ScaffoldVideoSkin](../components/video-scaffold-skin.md) — the minimally styled variant of Compat, a foundation for your own design.
+
+See [Choose a skin](../../guides/skins.md#choose-a-skin) to compare them.
 
 ## Media
 
@@ -111,6 +115,8 @@ The preset root, `@videojs/html/video`, has no side effects. Importing it never
 | `videoFeatures` | The [feature bundle](#feature-bundle). |
 | `VideoSkinElement` | The default [skin](#skins) element class. |
 | `NeutralVideoSkinElement` | The neutral [skin](#skins) element class. |
+| `CompatVideoSkinElement` | The compat [skin](#skins) element class. |
+| `ScaffoldVideoSkinElement` | The scaffold [skin](#skins) element class. |
 
 Registration entry points are side-effect-only:
 
@@ -119,5 +125,7 @@ Registration entry points are side-effect-only:
 | `@videojs/html/video/player` | `<video-player>` |
 | `@videojs/html/video/skin` | `<video-skin>`, `<media-container>`, and the UI elements the skin composes |
 | `@videojs/html/video/neutral-skin` | `<video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/video/compat-skin` | `<video-compat-skin>`, `<media-container>`, and the UI elements the compat skin composes |
+| `@videojs/html/video/scaffold-skin` | `<video-scaffold-skin>`, `<media-container>`, and the UI elements the scaffold skin composes |
 | `@videojs/html/video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
 | `@videojs/html/video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/resolve-adapter-type.md

@@ -47,8 +47,11 @@ Each media module you import adds its engine to your bundle, so import the rarel
 | `mux` | `stream.mux.com` stream URLs, with or without `.m3u8` | `<mux-video>` or `<mux-audio>` |
 | `cloudflare` | `cloudflarestream.com` and `videodelivery.net` URLs | `<cloudflare-video>` |
 | `spotify` | `open.spotify.com` URLs and `spotify:` URIs | `<spotify-audio>` |
+| `soundcloud` | `soundcloud.com` track and set URLs, `api.soundcloud.com` tracks and playlists, and `w.soundcloud.com/player/` embed URLs | `<soundcloud-audio>` |
+| `mixcloud` | `mixcloud.com` show URLs and Mixcloud widget embed URLs | `<mixcloud-audio>` |
 | `tiktok` | `tiktok.com` video URLs | `<tiktok-video>` |
 | `twitch` | `twitch.tv` video and channel URLs | `<twitch-video>` |
+| `dailymotion` | `dailymotion.com` video and embed URLs, `dai.ly` short links, and `geo.dailymotion.com` player embed URLs | `<dailymotion-video>` |
 | `hls` | `.m3u8` files and HLS MIME types | `<hls-video>`, `<hlsjs-video>`, or `<native-hls-video>` |
 | `dash` | `.mpd` files and `application/dash+xml` | `<dash-video>` or `<shaka-video>` |
 | `video` | `.mp4`, `.webm`, `.mov`, and `.ogv` files, and `video/*` MIME types | `<video>` |
@@ -95,4 +98,4 @@ A bare id returns `null`. An 11-character YouTube id and a 10-character Wistia i
 
 | Type |
 | --- |
-| `'youtube' \| 'vimeo' \| 'wistia' \| 'mux' \| 'cloudflare' \| 'spotify' \| 'tiktok' \| 'twitch' \| 'hls' \| 'dash' \| 'video' \| 'audio' \| null` |
+| `'youtube' \| 'vimeo' \| 'wistia' \| 'mux' \| 'cloudflare' \| 'spotify' \| 'soundcloud' \| 'mixcloud' \| 'tiktok' \| 'twitch' \| 'dailymotion' \| 'hls' \| 'dash' \| 'video' \| 'audio' \| null` |

package/docs/reference/api/ui-element.md

@@ -165,7 +165,7 @@ class ClockController implements ReactiveController {
 
 ## Destruction
 
-When the element disconnects, it waits two animation frames and then destroys itself if it is still disconnected. Moving the element within the document, or a framework reordering it, therefore keeps it alive. Destruction calls `hostDestroyed()` on every controller. A destroyed element stops updating and ignores later connections.
+When the element disconnects, it waits two animation frames and then destroys itself if it is still disconnected. Moving the element within the document, or a framework reordering it, therefore keeps it alive. Destruction first destroys the UI elements inside the element, including those in its shadow root, then calls `hostDestroyed()` on every controller. A destroyed element stops updating and ignores later connections.
 
 | Member | Description |
 | --- | --- |
@@ -173,7 +173,7 @@ When the element disconnects, it waits two animation frames and then destroys it
 | `destroyed` | `true` after destruction. |
 | `destroyCallback()` | Runs once on destruction. Override it, calling `super.destroyCallback()`, to release resources the element owns. |
 
-Add the `keep-alive` attribute to skip automatic destruction, for example when you detach an element and insert it again later. Call `destroy()` yourself when you are done with it.
+Add the `keep-alive` attribute to the element or one of its ancestors to skip automatic destruction, for example when you detach an element and insert it again later. Destroying an ancestor still destroys it. Call `destroy()` yourself when you are done with it.
 
 Release listeners and observers that the element starts on connection in `disconnectedCallback()`, calling `super.disconnectedCallback()`, because an element can connect and disconnect many times before it is destroyed.
 

package/docs/reference/components/alert-dialog.md

@@ -45,6 +45,7 @@ Use the open and transition data attributes to style visibility and animations:
 | `data-open` | Present while the dialog is open, including its closing transition |
 | `data-starting-style` | Present at the start of the opening transition |
 | `data-ending-style` | Present during the closing transition |
+| `data-scope` | `player` inside a player, `document` outside one |
 
 ```css
 media-dialog-backdrop:not([data-open]),
@@ -62,7 +63,7 @@ media-dialog-popup[data-ending-style] {
 
 ## Accessibility
 
-The dialog uses `role="alertdialog"` and `aria-modal="true"`. The title and description receive generated IDs that are connected with `aria-labelledby` and `aria-describedby`. Focus moves into the dialog when it opens, stays within it while open, and returns to the previously focused element when it closes. Content outside the dialog is inert while it is open. Pressing Escape closes the dialog.
+The dialog uses `role="alertdialog"`, plus `aria-modal="true"` outside a player. Like [Dialog](./dialog.md), it is confined to its player when rendered inside one and modal for the whole page otherwise. The title and description receive generated IDs that are connected with `aria-labelledby` and `aria-describedby`. Focus moves into the dialog when it opens, stays within it while open, and returns to the previously focused element when it closes. Content outside the dialog, within its player or the page, is inert while it is open. Pressing Escape closes the dialog.
 
 ## Examples
 
@@ -217,6 +218,7 @@ State is reflected as data attributes for CSS styling.
 | `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
 | `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
 | `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |
+| `scope` | `'player' \| 'document'` | `player` when the dialog is rendered inside a player and confined to it, otherwise `document`. |
 
 #### Events
 
@@ -231,11 +233,12 @@ Presentational backdrop that reflects its owning dialog's state.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-close
 
@@ -243,11 +246,12 @@ Button that closes its owning dialog; the element itself takes `role="button"` a
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-description
 
@@ -259,11 +263,12 @@ Semantic popup that owns focus management and dialog transition completion.
 
 #### Data attributes
 
-| Attribute | Description |
-| --- | --- |
-| `data-open` | Present when the dialog is open. |
-| `data-starting-style` | Present during the open transition. |
-| `data-ending-style` | Present during the close transition. |
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the dialog is open. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-scope` | `'player' \| 'document'` | `player` when the dialog is confined to its player, otherwise `document`. |
 
 ### media-dialog-title
 

package/docs/reference/components/audio-compat-skin.md

@@ -1,8 +1,8 @@
 # audio-compat-skin
 
-An audio skin designed for broader browser compatibility
+The audio preset's plain, unbranded skin, a polished step above native controls
 
-The Compat skin of the audio preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. Its time slider supports chapter segments and thumbnail previews. See [Customize skins](../../guides/customize-skins.md) to install and edit its source.
+The Compat skin of the audio preset: the same core controls with plain, unbranded surfaces that avoid newer visual effects such as backdrop blur. Its time slider supports chapter segments and thumbnail previews, and it adds captions and AirPlay buttons that the default audio skin leaves out. The preset also provides [AudioSkin](./audio-skin.md), [NeutralAudioSkin](./audio-neutral-skin.md), and [ScaffoldAudioSkin](./audio-scaffold-skin.md). See [Skins](../../guides/skins.md#choose-a-skin) to choose between them and [Customize skins](../../guides/customize-skins.md) to install and edit its source.
 
 ## Import
 
@@ -10,6 +10,12 @@ The Compat skin of the audio preset provides basic controls and plain surfaces,
 import '@videojs/html/audio/compat-skin';
 ```
 
+The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio-compat.js"></script>
+```
+
 ## Anatomy
 
 The skin goes between the player and the media component. It renders its controls around the media.