@videojs/html 10.0.0-rc.4 → 10.0.0

package/docs/guides/mux-data.md

@@ -2,7 +2,7 @@
 
 Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
 
-[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](./architecture.md) to a player and it monitors whichever media that player is playing:
+[Mux Data](https://www.mux.com/data?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](./architecture.md) to a player and it monitors whichever media that player is playing:
 
 Install the extension alongside the framework façade. The `<mux-video>` example also installs the Mux playback adapter:
 
@@ -19,11 +19,15 @@ pnpm add @videojs/html @videojs/mux-video @videojs/mux-data
     <mux-data></mux-data>
   </media-container>
 </video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/media/mux-video';
+  import '@videojs/html/extensions/mux-data';
+</script>
 ```
 
-Register the `<mux-data>` element by importing `@videojs/html/extensions/mux-data`.
-
-That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it inside the player, as a sibling of the media element.
+That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it anywhere inside the player.
 
 > **Note**
 >
@@ -31,28 +35,38 @@ That’s the whole setup for Mux-hosted playback — no environment key required
 
 ## Set the environment key
 
-Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.
+Mux Data needs to know which environment a view belongs to. For Mux-hosted playback, you do not need to set an environment key. The extension reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.
+
+Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content):
+
+For the hls.js example, also install `@videojs/hlsjs-video`. Replace `<mux-video>` in the primary example with `<hlsjs-video>` and keep `<hlsjs-video>` and `<mux-data>` inside the container:
 
-Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
+```bash
+pnpm add @videojs/hlsjs-video
+```
 
 ```html
 <hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
 <mux-data env-key="YOUR_ENV_KEY"></mux-data>
+<script type="module">
+  import '@videojs/html/media/hlsjs-video';
+  import '@videojs/html/extensions/mux-data';
+</script>
 ```
 
-An explicit key always wins, so set one to send Mux-hosted views to a specific environment.
+An explicit `envKey` overrides the environment Mux infers from the playback ID. Set one to send Mux-hosted views to a specific environment.
 
 ## How it works
 
 The extension attaches to the media the player is using, not to a specific element type, so it monitors [`<mux-video>`](../reference/components/mux-video.md), [`<hlsjs-video>`](../reference/components/hlsjs-video.md), [`<dash-video>`](../reference/components/dash-video.md), and the rest alike.
 
-How much it reports depends on the engine playing the stream. Every media gets the playback metrics the media element itself can tell us. On top of that, the component recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media with no JavaScript engine, like native HLS or a plain `<video>`, report the element-level metrics alone.
+How much the extension reports depends on the engine playing the stream. All media report the playback metrics available from the media element. The extension also recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media without a JavaScript engine, like native HLS or a plain `<video>`, report only the element-level metrics.
 
 The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.
 
 ## Describe the view
 
-Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:
+Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) to label views with your own titles, viewer IDs, and custom dimensions. `metadata` takes an object. In HTML, set it as a JavaScript property:
 
 ```ts
 const muxData = document.querySelector('mux-data');

package/docs/guides/picture-in-picture.md

@@ -8,7 +8,7 @@ Pop the video into a floating window, with availability detection and state that
 
 ## Recommended approach
 
-Add a [`<media-pip-button>`](../reference/components/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
+Add a [`<media-pip-button>`](../reference/components/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and stays hidden until picture-in-picture is available.
 
 **index.html**
 
@@ -76,28 +76,30 @@ import '@videojs/html/ui/pip-button';
 
 The [picture-in-picture feature](../reference/api/feature-pip.md) puts three things in player state.
 
-`pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
+`isPictureInPicture` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
 
-`pipAvailability` answers “can I offer this?” It starts as `'unavailable'`. Once the feature attaches to a media element, it settles to `'available'` or `'unsupported'`.
+`pictureInPictureAvailability` starts as `'unavailable'`. It becomes `'available'` when the media supports picture-in-picture and has loaded metadata, or `'unsupported'` when the browser or media has no supported route. Loading a new source returns it to `'unavailable'` until metadata loads.
 
-`requestPictureInPicture()`, `exitPictureInPicture()`, and `togglePictureInPicture()` change the presentation. If the browser blocks a request, the returned promise rejects. In a browser with no picture-in-picture API, the actions resolve without changing anything.
+`requestPictureInPicture()` and `exitPictureInPicture()` change the presentation. Handle rejected promises when the browser blocks a request. An entry request before metadata loads rejects with `InvalidStateError`. Without a supported API, the request resolves without opening a window.
 
 Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.
 
 ## Availability and constraints
 
-- Show picture-in-picture controls only when `pipAvailability` is `'available'`. `<media-pip-button>` handles this for you.
+If a Safari standalone web app exposes the standard Picture-in-Picture API, Video.js still reports picture-in-picture as `'unsupported'`. The built-in button hides in that case. Check `pictureInPictureAvailability` in installed web apps as well as browser tabs.
+
+- Show picture-in-picture controls only when `pictureInPictureAvailability` is `'available'`. `<media-pip-button>` handles this for you.
 - Requests must come from a user gesture; browsers reject requests outside one.
-- Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
+- [Firefox 153](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/153) (July 2026) added the programmatic picture-in-picture API on desktop. On earlier desktop versions, including Firefox ESR 140, `pictureInPictureAvailability` is `'unsupported'`, even though Firefox shows users its own picture-in-picture toggle. Check `pictureInPictureAvailability` rather than inferring support from the browser version.
 - On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
 - The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
-- The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
+- The user can close the window or return the video at any time. React to `isPictureInPicture` instead of assuming your button is the only entry and exit.
 
 ## Common variations
 
-### Request picture-in-picture from app logic
+### Open picture-in-picture from your own button
 
-Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
+Call `requestPictureInPicture()` directly in your button’s click handler so the browser treats the request as a user gesture. The action exits fullscreen first, then uses the standard Picture-in-Picture API or Safari’s presentation mode:
 
 ```html
 <video-player>
@@ -108,12 +110,16 @@ Enter picture-in-picture when the user scrolls the player out of view or navigat
 <button type="button" id="watch-elsewhere">Keep watching while you browse</button>
 <script type="module">
   import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import { selectPiP } from '@videojs/html';
 
   document.querySelector('#watch-elsewhere').addEventListener('click', () => {
-    const video = document.querySelector('video');
-    if (typeof video.requestPictureInPicture !== 'function') return; // Unsupported.
-    video.requestPictureInPicture().catch(() => {
-      // Rejected: no video data yet, or blocked by the browser.
+    const store = document.querySelector('video-player').store;
+    const pip = selectPiP(store.state);
+    if (pip?.pictureInPictureAvailability !== 'available') return;
+
+    pip.requestPictureInPicture().catch(() => {
+      // Show your app's request-failed message.
     });
   });
 </script>
@@ -123,15 +129,15 @@ Enter picture-in-picture when the user scrolls the player out of view or navigat
 
 ### The picture-in-picture button doesn’t render
 
-`pipAvailability` is `'unsupported'` — the browser has no programmatic picture-in-picture API (Firefox before 153), or the media isn’t a video.
+Check `pictureInPictureAvailability`. It is `'unavailable'` before metadata loads, and `'unsupported'` when the browser or media has no supported picture-in-picture route. Some embeds cannot enter picture-in-picture even in a browser that supports it.
 
 ### The request rejects
 
-The video has no data yet (wait for it to be ready), the call wasn’t tied to a user gesture, or the browser blocked it. Handle the rejection rather than assuming entry succeeded.
+The request ran outside a user gesture, or the browser refused it. Handle the rejection. A request before metadata loads rejects with `InvalidStateError`; check `pictureInPictureAvailability` before offering your button.
 
 ### State is wrong after the user closes the floating window
 
-Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
+Read `isPictureInPicture` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
 
 ## Related pages
 

package/docs/guides/playback-errors.md

@@ -10,7 +10,7 @@ Display playback failures instead of leaving a dead player, report the failure w
 
 ## Recommended approach
 
-Render a [`<media-error-dialog>`](../reference/components/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
+Render a [`<media-error-dialog>`](../reference/components/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The packaged skins include one.
 
 ```html
 <video-player>
@@ -36,7 +36,7 @@ Render a [`<media-error-dialog>`](../reference/components/error-dialog.md) insid
 </script>
 ```
 
-The dialog renders its text into the child parts — a title, the error description, and a dismiss button — and fills each empty part with default copy. Write your own text inside a part to replace the default. Without the child parts, the dialog opens with nothing to show.
+The dialog shows its text through child parts: a title, the error description, and a dismiss button. Each empty part gets default copy. Write your own text inside a part to replace it. Without the child parts, the dialog opens empty.
 
 ## How it works
 
@@ -53,13 +53,15 @@ The dialog owns presentation, not recovery. Decide the next step in your applica
 - For a terminal failure, load a new or refreshed source to recover. An aborted load or an adapter-specific error may have different behavior.
 - Standard media error codes distinguish broad classes — aborted, network, decode, and source-not-supported — rather than root causes. A media adapter can report its own numeric code too.
 - Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
-- Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
+- The feature records `error` events after attachment. An error already present on the media is not copied into state. Keep the error surface mounted regardless of playback state.
+
+A `src` in page markup can start loading before the player script runs. To capture startup failures, omit `src` from the markup and assign it after you import the player and it attaches to the media. Check `player.store.target` to confirm attachment; if it is absent, wait for a store notification. When adopting an already loaded element, check `video.error` once and show an application message if an error is present.
 
 ## Common variations
 
 ### Offer an application-specific next step
 
-Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `<media-error-dialog>`; the dialog can close after your application has handled it.
+Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `<media-error-dialog>`; the dialog can close after your application has handled the error.
 
 ### Report errors to monitoring
 
@@ -74,17 +76,18 @@ import { selectError } from '@videojs/html';
 const player = document.querySelector('video-player');
 if (!player) throw new Error('Missing video-player');
 
+const store = player.store;
 let previousError: { code: number; message: string } | null = null;
 
 function reportNewError() {
-  const error = selectError(player.store.state)?.error ?? null;
+  const error = selectError(store.state)?.error ?? null;
   if (error === previousError) return;
 
   previousError = error;
   if (error) console.error('Playback failed', error.code, error.message);
 }
 
-const unsubscribe = player.store.subscribe(reportNewError);
+const unsubscribe = store.subscribe(reportNewError);
 reportNewError();
 // Call unsubscribe() when this player is removed.
 ```
@@ -103,7 +106,7 @@ Not every dead player is a media error — autoplay blocking and an unset source
 
 ### A `VJS8_LEGACY_*` exception appears
 
-These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](../reference/api/error-codes.md) for its trigger and v10 equivalent. The player `error` state covered in this guide receives media playback errors after setup.
+These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](../reference/api/error-codes.md) for its trigger and v10 equivalent. These exceptions are separate from the player’s `error` state, which receives media playback errors after setup.
 
 ### Error code says the source isn’t supported
 

package/docs/guides/poster.md

@@ -7,7 +7,7 @@ A poster is the image shown before your video plays. There are several places to
 1. **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
 2. **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
 3. **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
-4. **Keep it working after [adding the skin source to your project](./customize-skins.md#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
+4. **Keep it working after [adding the skin source to your project](./customize-skins.md#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders. You can also set the image’s source yourself.
 
 ## Let the media provide a poster
 
@@ -46,19 +46,25 @@ When the media has no poster of its own, set the player’s `poster` to an image
     <video src="/video.mp4" playsinline></video>
   </video-skin>
 </video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+</script>
 ```
 
-If you use a ready-made skin, it includes [`<media-poster>`](../reference/components/poster.md) and shows the image automatically. If you build your own UI, add `<media-poster>` yourself. It hides after the user plays or seeks.
+A packaged skin includes [`<media-poster>`](../reference/components/poster.md) and shows the image automatically. If you build your own UI, add `<media-poster>` yourself. The poster hides after the user plays or seeks.
 
 When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/api/feature-metadata.md) for how the player combines those values.
 
+Set `poster` on the player to supply the skin’s image. A `poster` on the native `<video>` or React `Video` sets only the browser’s poster; it does not populate the player’s Poster component, `renderPoster`, or the HTML poster slot.
+
 Posters are decorative by default, with an empty `alt`. If the image communicates something that is not available elsewhere, add `alt` text when you customize the poster image.
 
 ## Take control of the poster image
 
-The packaged skins also accept an image of your own, for when a plain `<img>` is not enough:
+When a plain `<img>` is not enough, give the packaged skin an image of your own:
 
-Add your image to the skin’s `poster` slot. Leave off `src` and Video.js fills in the player’s poster. Provide a `src`, a `srcset`, or `<picture>` sources and Video.js leaves the image alone:
+Add your image to the skin’s `poster` slot. If you leave off `src`, Video.js fills in the player’s poster. If you provide a `src`, a `srcset`, or `<picture>` sources, Video.js leaves the image alone. Keep the player and skin imports from the previous section:
 
 ```html
 <video-player>
@@ -70,15 +76,27 @@ Add your image to the skin’s `poster` slot. Leave off `src` and Video.js fills
     </picture>
   </video-skin>
 </video-player>
+<style>
+  video-skin > picture[slot="poster"] > img {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: var(--media-object-fit, contain);
+    object-position: var(--media-object-position, center);
+  }
+</style>
 ```
 
 ## Add a loading placeholder
 
-A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include with the page, such as a short data URL. Add it to the customized image from the previous section.
+A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include directly in the page, for example as a short data URL. Add it to the customized image from the previous section.
+
+Replace `data:image/webp;base64,…` in the examples below with a complete data URL generated from your poster.
 
 ### Add an image to the poster slot
 
-Add an image to the skin’s `poster` slot with the placeholder as its background. Leave off `src`: Video.js adds the poster URL, while the background appears immediately.
+Add an image to the skin’s `poster` slot with the placeholder as its background. Leave off `src` so Video.js can add the poster URL. The background appears immediately, before the poster loads.
 
 ```html
 <video-player poster="/poster.jpg">
@@ -97,15 +115,16 @@ The examples use `contain` for both images. Use `cover` for both when the poster
 
 ## Set the poster after adding skin source
 
-Adding the skin source to your project changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [`<media-poster>`](../reference/components/poster.md) element your skin renders.
+After you add the skin source to your project, the first two approaches still work. The player’s `poster`, or the poster the media provides, reaches the [`<media-poster>`](../reference/components/poster.md) element your skin renders.
 
-`<media-poster>` fills the `src` of the image inside it. Give that image a `src`, a `srcset`, or `<picture>` sources instead and Video.js leaves it untouched — set the source at this level when the poster should bypass player state entirely.
+`<media-poster>` fills the `src` of the image inside it. If you give that image a `src`, a `srcset`, or `<picture>` sources, Video.js leaves it untouched. Set the source here when the poster should bypass player state entirely.
 
-For a placeholder, put the background on the image inside `<media-poster>`:
+Keep your skin’s existing classes and put the background on the image inside `<media-poster>`:
 
 ```html
-<media-poster>
+<media-poster class="media-poster">
   <img
+    class="media-poster-image"
     alt=""
     style="background: url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat"
   >
@@ -118,9 +137,11 @@ For a placeholder, put the background on the image inside `<media-poster>`:
 
 Check that the player has a `poster` or that the media component can create one from its source.
 
+A `poster` set only on the native media element does not reach the skin’s Poster. Move that URL to the player’s `poster`.
+
 ### The final poster never appears
 
-Leave off `src`, `srcset`, and any parent `<picture>` sources when you want Video.js to add the poster URL. If you provide one of those values, Video.js leaves it unchanged.
+To let Video.js add the poster URL, leave off `src`, `srcset`, and any parent `<picture>` sources. If you provide any of them, Video.js leaves the image unchanged.
 
 ### The placeholder and poster use different crops
 

package/docs/guides/presets.md

@@ -26,13 +26,23 @@ For example, the `@videojs/html/background` preset includes a media element with
 
 The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
 
+The video, audio, live video, and live audio presets also export Compat skins. For example, React exports `CompatVideoSkin` with `@videojs/react/video/compat-skin.css`; HTML registers `<video-compat-skin>` through `@videojs/html/video/compat-skin`.
+
 | Import | Description | Details |
 | --- | --- | --- |
-| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-minimal-skin>`, `<video-skin>`; **Default media element:** `<video>` |
-| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-minimal-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-compat-skin>`, `<video-neutral-skin>`, `<video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-compat-skin>`, `<audio-neutral-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
 | `@videojs/html/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<background-video-skin>`; **Default media element:** `<background-video>` |
-| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-minimal-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
-| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-minimal-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-compat-skin>`, `<live-audio-neutral-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-compat-skin>`, `<live-video-neutral-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
+
+Each preset has a reference page that lists its player, feature bundle, skins, media, and exports:
+
+- [Video preset](../reference/api/preset-video.md)
+- [Audio preset](../reference/api/preset-audio.md)
+- [Live video preset](../reference/api/preset-live-video.md)
+- [Live audio preset](../reference/api/preset-live-audio.md)
+- [Background preset](../reference/api/preset-background.md)
 
 ## What’s in a preset
 
@@ -56,7 +66,7 @@ Registration is explicit, so importing a value never changes the custom element
 ```ts
 import '@videojs/html/video/player'; // <video-player> only
 import '@videojs/html/video/skin';   // <video-skin> + container + video UI
-// Import '@videojs/html/video/minimal-skin' instead for the minimal skin.
+// Import '@videojs/html/video/neutral-skin' instead for the neutral skin.
 ```
 
 A complete player imports `video/player` and one skin. Each skin registration includes its container and UI dependencies but does not register the player.

package/docs/guides/quality.md

@@ -167,7 +167,7 @@ The [quality feature](../reference/api/feature-quality.md) mirrors the media ele
 
 - `videoRenditionList` holds each rendition’s `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and whether it’s `selected`.
 - `activeVideoRendition` is the rendition currently playing. When the engine doesn’t report one directly, the player matches it from the video’s current dimensions.
-- `selectVideoRendition(value)` pins one rendition; pass `'auto'` to return control to the engine’s adaptive selection.
+- `selectVideoRendition(id)` pins one rendition by its `id` from `videoRenditionList`; pass `'auto'` to return control to the engine’s adaptive selection.
 
 [`<media-quality-radio-group>`](../reference/components/quality-radio-group.md) turns this state into a ready-made radio menu with resolution labels and an “Auto” entry, as the example above shows.
 
@@ -175,10 +175,11 @@ Selecting “Auto” keeps adaptive bitrate switching active: the engine picks t
 
 ## Availability and constraints
 
+- The live preset omits `qualityFeature` and cannot accept extra features. To add a quality menu to a live player, use `createPlayer` with `[...liveVideoFeatures, qualityFeature]`. See [Play live streams](./live-streams.md) for custom player setup.
 - Quality availability is `'unavailable'` for media that doesn’t offer a choice — progressive files, streams before the manifest loads, and single-rendition streams. Render quality UI conditionally on that value.
-- Renditions come from the streaming engine, so the list depends on what the manifest declares. A single-rendition stream offers no meaningful selection, so availability stays `'unavailable'`.
+- Renditions come from the streaming engine, so the list depends on what the manifest declares.
 - Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
-- Rendition lists change on source change; selection resets with them.
+- Loading a new source replaces the rendition list and resets the selection.
 
 ## Common variations
 
@@ -186,14 +187,52 @@ Selecting “Auto” keeps adaptive bitrate switching active: the engine picks t
 
 If you don’t want to expose manual selection, do nothing: adaptive selection is on by default and needs no UI.
 
-### Cap or pin quality programmatically
+### Pin quality programmatically
 
-Access the player store through the [player controller](../reference/api/player-controller.md) and call `selectVideoRendition` with a rendition `id` from `videoRenditionList`, or `'auto'` to restore adaptive selection.
+Call `selectVideoRendition` to hold one rendition until the user selects “Auto”. To limit resolution while keeping automatic switching, set `maxAutoResolution` on the source. It needs the hls.js engine; native HLS playback ignores it. See [Options Video.js normalizes](./media-sources.md#options-videojs-normalizes).
+
+Add a button inside the primary example’s container:
+
+```html
+<button type="button" id="lowest-quality" disabled>Use lowest quality</button>
+```
+
+Read the current list from the player store and use the rendition’s `id`. Pass `'auto'` to restore adaptive selection:
+
+```ts
+import '@videojs/html/video/player';
+import { selectQuality } from '@videojs/html';
+
+const player = document.querySelector('video-player');
+if (!player) throw new Error('Missing video-player');
+
+const store = player.store;
+const button = document.querySelector<HTMLButtonElement>('#lowest-quality')!;
+let lowestValue: string | undefined;
+
+function updateButton() {
+  const renditions = selectQuality(store.state)?.videoRenditionList ?? [];
+  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];
+
+  lowestValue = lowest?.id;
+  button.disabled = renditions.length < 2;
+}
+
+button.addEventListener('click', () => {
+  if (lowestValue !== undefined) selectQuality(store.state)?.selectVideoRendition(lowestValue);
+});
+
+const unsubscribe = store.subscribe(updateButton);
+updateButton();
+// Call unsubscribe() when this player is removed.
+```
 
 ## Troubleshooting
 
 ### The quality menu doesn’t render
 
+Confirm that the player includes `qualityFeature`. The live preset omits it; compose a custom player as described above.
+
 Quality availability is `'unavailable'`. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media element doesn’t support renditions. Use a streaming media element such as [`<hls-video>`](../reference/components/hls-video.md) or [`<hlsjs-video>`](../reference/components/hlsjs-video.md).
 
 ### The menu doesn’t render for a single-rendition stream

package/docs/guides/self-hosting.md

@@ -43,7 +43,7 @@ Bundle a single file when you already build your front end. Download the release
 Unpack it into whatever your server treats as static files:
 
 ```bash
-VIDEOJS_VERSION=10.0.0-rc.4
+VIDEOJS_VERSION=10.0.0
 curl -fLO "https://github.com/videojs/v10/releases/download/@videojs/cdn@${VIDEOJS_VERSION}/videojs-cdn-${VIDEOJS_VERSION}.zip"
 unzip "videojs-cdn-${VIDEOJS_VERSION}.zip" -d public/
 ```
@@ -51,7 +51,7 @@ unzip "videojs-cdn-${VIDEOJS_VERSION}.zip" -d public/
 Then point a script tag at the player you want:
 
 ```html
-<script type="module" src="/videojs-cdn-10.0.0-rc.4/video.js"></script>
+<script type="module" src="/videojs-cdn-10.0.0/video.js"></script>
 ```
 
 The archive holds the same production bundles the CDN serves, minus sourcemaps and development builds. Every path inside it is relative, so it runs from any origin with no outbound requests. `SHA256SUMS` on the release verifies the download.
@@ -67,17 +67,17 @@ For Composer-based projects such as Drupal, declare the archive as a package:
       "type": "package",
       "package": {
         "name": "videojs/cdn",
-        "version": "10.0.0-rc.4",
+        "version": "10.0.0",
         "type": "drupal-library",
         "dist": {
           "type": "zip",
-          "url": "https://github.com/videojs/v10/releases/download/@videojs/cdn@10.0.0-rc.4/videojs-cdn-10.0.0-rc.4.zip"
+          "url": "https://github.com/videojs/v10/releases/download/@videojs/cdn@10.0.0/videojs-cdn-10.0.0.zip"
         }
       }
     }
   ],
   "require": {
-    "videojs/cdn": "10.0.0-rc.4"
+    "videojs/cdn": "10.0.0"
   }
 }
 ```

package/docs/guides/skins.md

@@ -8,6 +8,8 @@ Packaged player designs that include both UI components and their styles.
 
 A skin wraps the media component and provides the player’s complete interface. It combines a specific set of UI components with the styles that arrange and present them.
 
+The video, audio, live video, and live audio presets each provide Default, Neutral, and Compat skins. Compat uses plain surfaces and basic controls, with broader browser compatibility as its design goal.
+
 ## Packaged skins and skin source
 
 When you choose a skin, you can import the packaged version or add its source to your project. It’s usually easiest to start with a packaged skin and add its source when you need more customization.
@@ -59,10 +61,10 @@ You’ll find a preconfigured player, its typed controller, a skin, and the matc
 
 | Import | Description | Details |
 | --- | --- | --- |
-| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-minimal-skin>`, `<video-skin>`; **Default media element:** `<video>` |
-| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-minimal-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-compat-skin>`, `<video-neutral-skin>`, `<video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-compat-skin>`, `<audio-neutral-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
 | `@videojs/html/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<background-video-skin>`; **Default media element:** `<background-video>` |
-| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-minimal-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
-| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-minimal-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-compat-skin>`, `<live-audio-neutral-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-compat-skin>`, `<live-video-neutral-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
 
 - [Read about presets](./presets.md)

package/docs/guides/thumbnails.md

@@ -14,20 +14,9 @@ Show preview frames along the timeline while the user scrubs, like YouTube’s s
 
 ## Recommended approach
 
-Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [`<media-time-slider>`](../reference/components/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same attributes as the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md).
+Add a `<track kind="metadata" label="thumbnails" default>` whose cues reference storyboard images. Then put a slider thumbnail inside the [`<media-time-slider>`](../reference/components/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same attributes as the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md).
 
-`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child; set `crossorigin`, `loading`, or `fetchpriority` on the element itself, or on the image you supply. Inside a packaged skin, an `<img slot="thumbnail">` replaces the image the skin carries, so those attributes go on it:
-
-```html
-<video-player>
-  <video-skin>
-    <video src="video.mp4" crossorigin="anonymous">
-      <track kind="metadata" label="thumbnails" src="storyboard.vtt" default />
-    </video>
-    <img slot="thumbnail" alt="" loading="lazy" fetchpriority="low" />
-  </video-skin>
-</video-player>
-```
+`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child. Set `crossorigin`, `loading`, or `fetchpriority` on the element itself or on that image.
 
 **index.html**
 
@@ -130,7 +119,7 @@ import '@videojs/html/ui/slider-thumbnail';
 
 ## How it works
 
-- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/api/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/api/feature-text-tracks.md) exposes this track as `thumbnailsTrack`, with its `cues` and `src`.
 - The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the example’s CSS uses them to reveal the preview and position it over the pointer.
 - To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md) element with an explicit `time`.
 
@@ -155,6 +144,27 @@ storyboard.jpg#xywh=256,0,256,160
 - Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
 - Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
 
+## Common variations
+
+### Customize the skin’s thumbnail image
+
+Inside a packaged skin, an `<img slot="thumbnail">` replaces the image the skin carries, so image attributes go on it:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4" crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="storyboard.vtt" default />
+    </video>
+    <img slot="thumbnail" alt="" loading="lazy" fetchpriority="low" />
+  </video-skin>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+</script>
+```
+
 ## Troubleshooting
 
 ### Thumbnails don’t appear while scrubbing