@videojs/html 10.0.0-rc.4 → 10.0.0

package/docs/guides/browser-support.md

@@ -1,70 +1,84 @@
 # Browser support
 
-Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
+Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them
 
-Video.js 10 supports the **latest two stable versions** of Chrome, Edge, Firefox, Safari, and Safari on iOS. This page shows the versions that means today, what the packaged skins need from a browser, and how to reach older ones.
-
-## Browser baseline
-
-The build reads the policy from a [browserslist](https://browsersl.ist) query in the repository, and this page resolves the same query when the docs are built:
-
-*Supported browsers and the versions the support policy resolves to today*
+*Supported browsers and the versions of each that Video.js supports*
 
 | Browser | Versions |
 | --- | --- |
-| Chrome | 150 and 151 |
-| Edge | 150 and 151 |
-| Firefox | 153 and 154 |
-| Safari | 26.5 and 26.6 |
-| Safari on iOS | 26.5 and 26.6 |
+| Chrome | 111 and later |
+| Edge | 111 and later |
+| Firefox | 121 and later |
+| Safari | 16.4 and later |
+| Safari on iOS | 16.4 and later |
 
-These are the versions we test in and fix bugs for. We build directly on the web platform, with [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope), [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries), and [anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning), and we do not hold a feature back to keep older versions working. Older versions often work anyway:
+These versions account for 91.5% of global web usage according to [caniuse-lite](https://github.com/browserslist/caniuse-lite) 1.0.30001810, and this figure updates when we update that data.
 
-In practice the packaged skins render in Chrome 120, Edge 120, Firefox 146, Safari 17.4, and Safari on iOS 17.4 and later. Those versions account for 89.2% of global web usage according to [caniuse-lite](https://github.com/browserslist/caniuse-lite) 1.0.30001810, and this figure updates when we update that data.
+We test in and fix bugs for these versions. Each minimum comes from a feature with no fallback: `:has()` sets Firefox, [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix) and [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) set Chrome and Edge (Chrome 111, Firefox 113, Safari 16.2), and the JavaScript sets Safari, because it uses ES2022 syntax and [`adoptedStyleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets). Newer JavaScript APIs are feature-detected.
 
 ## CSS requirements
 
-The packaged skins are generated CSS, and a handful of newer features hold a skin together. **Required** features have no fallback: without them the player shows no component styling, and `@scope` alone sets the floor. **Degrades** features lose one visual detail. **Has a fallback** features sit inside [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports); anchor positioning falls back to positions computed in JavaScript.
+The packaged skins are generated CSS, and the build lowers them for the browsers above. It flattens CSS nesting, adds vendor prefixes such as `-webkit-backdrop-filter`, and writes each skin’s scope as a [`:where()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where) selector, which adds no specificity, rather than [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope).
+
+Skins you add as source through the [Shadcn registry](./installation-shadcn.md) keep `@scope`, which reads more clearly in files you edit. Their plain CSS versions need Chrome and Edge 118, Firefox 146, and Safari and iOS 17.4 unless you [flatten `@scope` in your build](#flatten-scope-in-registry-skins); the Tailwind versions style elements with utility classes and follow the versions above.
+
+Newer color functions get a fallback, and the original declaration moves inside [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports), so browsers that have the function still use it:
+
+- [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) uses its light color. The audio skins render their light theme, and the video skins keep the light hairline border.
+- [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/contrast-color) uses each theme’s default text color on primary buttons and the inherited text color elsewhere. The fallback cannot read a custom accent, so set `--media-accent-text-color` whenever you set `--media-accent-color`; see [Customize skins](./customize-skins.md).
+- [Relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors) that keep their origin’s channels, which build the scrims behind the controls, become `color-mix()`. Subtle shadows derived from `currentColor` have no equivalent and are left out.
+
+Tooltips, menus, and popovers use the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) where it exists (Chrome 114, Firefox 125, Safari 17). In older supported versions they stay inside the player instead of the top layer: the skins hide them while closed and position them against the player while open, so on the video skins a menu taller than the player is cut off.
 
-The table reads the first fully supporting version of each feature from [caniuse-lite](https://github.com/browserslist/caniuse-lite) when the docs build, and feature names link to [caniuse.com](https://caniuse.com/). The **effective floor** is the newest required version in each column.
+The table reads the first fully supporting version of each feature from [caniuse-lite](https://github.com/browserslist/caniuse-lite) when the docs build, and feature names link to [caniuse.com](https://caniuse.com/). **Required** features have no fallback. **Degrades** features lose one visual detail. **Has a fallback** features keep working another way: anchor positioning falls back to positions computed in JavaScript, `:dir()` sits beside `[dir="rtl"]` selectors, and the packaged skins flatten `@scope` into `:where()` selectors.
 
-*First browser version that fully supports each CSS feature the packaged skins use, with the share of global web usage on supporting browsers. Feature names link to their caniuse.com support data. "Not supported" means the browser has no full support. Paired browsers share a column and show two values only when they differ. The effective floor row is the newest required version in each column.*
+*First browser version that fully supports each CSS feature the packaged skins use, with the share of global web usage on supporting browsers. Feature names link to their caniuse.com support data. "Not supported" means the browser has no full support. Paired browsers share a column and show two values only when they differ.*
 
 | Feature | Chrome and Edge | Firefox | Safari and iOS | Global support |
 | --- | --- | --- | --- | --- |
-| [`@scope`](https://caniuse.com/css-cascade-scope) Required. No component styling. | 118 | 146 | 17.4 | 90.0% |
-| [`CSS nesting`](https://caniuse.com/css-nesting) Required. No component styling. | 120 | 117 | 17.2 | 90.7% |
+| [`@scope`](https://caniuse.com/css-cascade-scope) Has a fallback. Packaged skins use :where() selectors instead; registry CSS skins need it. | 118 | 146 | 17.4 | 90.0% |
 | [`@layer`](https://caniuse.com/css-cascade-layers) Required. No component styling. | 99 | 97 | 15.4 | 95.3% |
 | [`:has()`](https://caniuse.com/css-has) Required. Menu and slider focus states are lost. | 105 | 121 | 15.4 | 94.1% |
 | [`@container`](https://caniuse.com/css-container-queries) Required. Controls do not adapt to player width. | 106 | 110 | 16 | 94.0% |
 | [`Media query range syntax`](https://caniuse.com/css-media-range-syntax) Required. Large-screen sizing is lost. | 104 | 63 | 16.4 | 94.0% |
-| [`:dir()`](https://caniuse.com/css-dir-pseudo) Required. Right-to-left layout is lost. | 120 | 17 | 16.4 | 91.4% |
-| [`Relative color syntax`](https://caniuse.com/css-relative-colors) Degrades. Adaptive shadows are lost. | 131 | 133 | 18 | 85.7% |
+| [`:dir()`](https://caniuse.com/css-dir-pseudo) Has a fallback. Right-to-left layout follows the dir attribute instead. | 120 | 17 | 16.4 | 91.4% |
+| [`Relative color syntax`](https://caniuse.com/css-relative-colors) Degrades. Control scrims fall back to color-mix(), and subtle shadows are lost. | 131 | 133 | 18 | 85.7% |
 | [`scrollbar-color and scrollbar-width`](https://caniuse.com/css-scrollbar) Degrades. Menus show default scrollbars. | 121 | 64 | 26.2 | 85.6% |
 | [`backdrop-filter`](https://caniuse.com/css-backdrop-filter) Degrades. Surfaces lose their blur. | 76 / 17 | 103 | 9 | 95.7% |
 | [`Anchor positioning`](https://caniuse.com/css-anchor-positioning) Has a fallback. Popups are positioned by JavaScript. | 125 | 147 | 26 | 84.1% |
-| Effective floor | 120 | 146 | 17.4 | 89.2% |
 
-A few features have no caniuse entry. [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) is required but older than the floor (Chrome 111, Firefox 113, Safari 15.4). [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark), [relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors), [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property), and [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/contrast-color) each degrade on their own; set `--media-accent-text-color` from [Customize skins](./customize-skins.md) if you support browsers without `contrast-color()`. [Firefox ESR](https://www.mozilla.org/en-US/firefox/enterprise/) releases older than 146 lack `@scope`, so the skins render unstyled there.
+Older browsers than the baseline are not tested. Without `:has()`, `@container`, `@layer`, `color-mix()`, or `oklch()`, the skins lose focus states, layout, or colors.
 
-The JavaScript has a lower floor: ES2022 syntax, with newer APIs feature-detected, so it runs in Chrome 102, Firefox 112, and Safari 16.4 or later. The stylesheet decides whether an older browser shows a working player.
+## Build the skin CSS yourself
 
-### Support older browsers
+Packaged HTML skins inline their CSS into JavaScript, so [add the skin source to your project](./customize-skins.md#style-skin-source) first. The added `skin.css` can pass through your CSS pipeline. CDN bundles inline their CSS too; to recompile it, move to a [self-hosted build](./self-hosting.md) and use the skin source instead of the prebuilt CDN skin.
 
-To reach browsers below the floor, recompile the skin stylesheet with fallbacks. Only a stylesheet your build processes can be recompiled.
+[Lightning CSS](https://lightningcss.dev/transpilation.html), which Vite uses to minify CSS, rewrites `light-dark()` and `:dir()` for every browser when its targets include older ones, not only for those older browsers. Its `light-dark()` output depends on a `color-scheme` declaration the skins do not make, so the skin colors break. The skins keep `light-dark()` inside `@supports` checks, which Lightning CSS 1.32 and earlier leave alone but 1.33 and later rewrite anyway. The skins already handle both features, so exclude them:
 
-Packaged HTML skins inline their CSS into JavaScript, so [add the skin source to your project](./customize-skins.md#style-skin-source) first. The added `skin.css` can pass through your CSS pipeline. CDN bundles inline their CSS too; to recompile it, move to a [self-hosted build](./self-hosting.md) and use the skin source instead of the prebuilt CDN skin.
+**vite.config.ts**
+
+```ts
+import { Features } from 'lightningcss';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  css: {
+    lightningcss: { exclude: Features.LightDark | Features.DirSelector },
+  },
+});
+```
+
+### Flatten `@scope` in registry skins
 
-[lightningcss](https://lightningcss.dev/transpilation.html) and [postcss-preset-env](https://preset-env.cssdb.org/) both read a browserslist query and add what those browsers lack: they flatten nesting and rewrite `:dir()`, range media queries, `light-dark()`, and `oklch()` in ordinary declarations, and add vendor prefixes. Neither rewrites `@scope` or `:scope`, so a small plugin flattens each block into descendant selectors prefixed with [`:where(root)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which adds no specificity. The PostCSS version, picked up by Vite, Next.js, and most bundlers from `postcss.config.mjs`:
+Registry skins in plain CSS keep `@scope`, and Lightning CSS passes it through unchanged. To reach browsers without `@scope`, add a PostCSS plugin that rewrites each block into descendant selectors prefixed with [`:where(root)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which adds no specificity. Vite, Next.js, and most bundlers pick it up from `postcss.config.mjs` and run it before Lightning CSS:
 
 ```bash
-npm install --save-dev postcss postcss-preset-env postcss-selector-parser
+npm install --save-dev postcss postcss-selector-parser
 ```
 
 **postcss.config.mjs**
 
 ```js
-import presetEnv from 'postcss-preset-env';
 import selectorParser from 'postcss-selector-parser';
 
 /** Rewrite `@scope (<root>) { … }` into descendant selectors that older browsers understand. */
@@ -76,7 +90,7 @@ function flattenScope() {
 
         sel.walk((node) => {
           if (node.type === 'nesting' || (node.type === 'pseudo' && node.value === ':scope')) {
-            node.replaceWith(selectorParser.string({ value: root }));
+            node.replaceWith(selectorParser.string({ value: `:where(${root})` }));
             referencesRoot = true;
           }
         });
@@ -109,12 +123,10 @@ function flattenScope() {
 }
 flattenScope.postcss = true;
 
-export default {
-  plugins: [flattenScope(), presetEnv({ browsers: 'baseline widely available', stage: 2 })],
-};
+export default { plugins: [flattenScope()] };
 ```
 
-The result renders in Chrome 111, Firefox 121, and Safari 16.4 or later, the floor [Tailwind CSS 4 documents](https://tailwindcss.com/docs/compatibility#browser-support), because `:has()`, `@container`, `@layer`, and `color-mix()` have no fallback. Flattening `@scope` trades scope proximity for source order; the packaged skins never nest a component inside itself, so the output matches. Run `npx browserslist "baseline widely available"` to see what the query resolves to today, or pick another query for your audience.
+Flattening trades scope proximity for source order, the same way the packaged skins do. Keep the Lightning CSS `exclude` setting above so the colors still work.
 
 ## Rendering contexts
 

package/docs/guides/build-your-own-component.md

@@ -164,8 +164,8 @@ Custom components read player state and dispatch actions through [features](./fe
 | --- | --- | --- |
 | `paused`, `ended` | `play()`, `pause()` | [Playback](../reference/api/feature-playback.md) |
 | `currentTime`, `duration` | `seek()` | [Time](../reference/api/feature-time.md) |
-| `volume`, `muted` | `setVolume()`, `toggleMuted()` | [Volume](../reference/api/feature-volume.md) |
-| `fullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](../reference/api/feature-fullscreen.md) |
+| `volume`, `muted` | `setVolume()`, `setMuted()` | [Volume](../reference/api/feature-volume.md) |
+| `isFullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](../reference/api/feature-fullscreen.md) |
 
 The API reference lists every feature with the state and actions it adds.
 
@@ -192,9 +192,9 @@ Without a selector, `PlayerController` returns the full store without subscribin
 import { createPlayer, PlayerController } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
-const { context } = createPlayer({ features: videoFeatures });
+const { playerContext: videoPlayerContext } = createPlayer({ features: videoFeatures });
 
-#store = new PlayerController(this, context);
+#store = new PlayerController(this, videoPlayerContext);
 
 // Call any action
 this.#store.value?.play();
@@ -226,7 +226,7 @@ Add the skin source to your project and modify it. See [Customize skins](./custo
 
 ### State and actions are typed as `unknown`
 
-You’re using the shared `playerContext`, which doesn’t know which features your player has. Use the typed `context` returned by `createPlayer`.
+You’re passing the `playerContext` exported from `@videojs/html`, which doesn’t know which features your player has. Pass the context `createPlayer` returns instead, as `videoPlayerContext` does in [How it works](#how-it-works), or use the `PlayerController` that `createPlayer` returns, which is already bound to it and takes no context argument.
 
 ### The component renders but never updates
 

package/docs/guides/captions.md

@@ -10,6 +10,8 @@ Show captions and subtitles, and let users turn them on and pick a language.
 
 Add WebVTT tracks as `<track>` children of the media element, and give users a [`<media-captions-button>`](../reference/components/captions-button.md) to toggle them.
 
+The `<track>` loads `/docs/demos/text-tracks/captions.vtt`, shown in the `captions.vtt` tab. Host a WebVTT file for your video and point `src` at its URL.
+
 **index.html**
 
 ```html
@@ -74,14 +76,29 @@ import '@videojs/html/ui/container';
 import '@videojs/html/ui/captions-button';
 ```
 
+**captions.vtt**
+
+```text
+WEBVTT
+
+00:00.000 --> 00:03.000
+This is a demo of the captions button.
+
+00:03.000 --> 00:06.000
+Captions help make video accessible to everyone.
+
+00:06.000 --> 00:09.000
+Toggle captions on and off with a single click.
+```
+
 ## How it works
 
 The [text track feature](../reference/api/feature-text-tracks.md) mirrors the media element’s `textTracks` into player state:
 
 - `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
 - `subtitlesShowing` is `true` when any caption or subtitle track is showing.
-- `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
-- `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
+- `toggleSubtitles(forceShow?)` hides captions if a caption or subtitle track is showing. Otherwise it shows one track, chosen in this order: the last track shown, a track matching the browser language, then the first available track. Pass `true` or `false` to force captions on or off.
+- `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `null` to disable all.
 
 Tracks don’t have to come from `<track>` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
 
@@ -93,7 +110,7 @@ The browser renders the cues. Style them with the `::cue` pseudo-element.
 - Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
 - Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossorigin` on the media element.
 - Track selection UIs identify tracks by `label` and `language`; give every track both.
-- `default` on a `<track>` makes the browser show it initially.
+- `default` on a `<track>` marks it as the preferred initial track. The browser’s caption preferences can select another track.
 
 ## Common variations
 
@@ -101,7 +118,30 @@ The browser renders the cues. Style them with the `::cue` pseudo-element.
 
 For multiple languages, render a menu instead of a toggle.
 
-Use [`<media-captions-radio-group>`](../reference/components/captions-radio-group.md) inside a menu or popover for explicit track selection.
+Replace the Captions button in the primary example with a menu containing [`<media-captions-radio-group>`](../reference/components/captions-radio-group.md). Keep the player, container, and track setup, and add these imports:
+
+```html
+<button type="button" commandfor="captions-menu">Captions</button>
+<media-menu id="captions-menu" side="top" align="end">
+  <media-menu-content>
+    <media-captions-radio-group label="Captions">
+      <template>
+        <media-menu-radio-item>
+          <span data-part="label"></span>
+          <media-menu-item-indicator>✓</media-menu-item-indicator>
+        </media-menu-radio-item>
+      </template>
+    </media-captions-radio-group>
+  </media-menu-content>
+</media-menu>
+<script type="module">
+  import '@videojs/html/ui/menu';
+  import '@videojs/html/ui/menu-content';
+  import '@videojs/html/ui/menu-radio-item';
+  import '@videojs/html/ui/menu-item-indicator';
+  import '@videojs/html/ui/captions-radio-group';
+</script>
+```
 
 ## Troubleshooting
 
@@ -117,9 +157,9 @@ Confirm that:
 
 The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossorigin` on the media element.
 
-### The selection menu is empty
+### The captions menu is empty
 
-The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
+The radio group hides when there are no caption or subtitle tracks, but the example’s plain Captions button still renders. Hide or disable that trigger while `textTrackList` contains no caption or subtitle entries. For streaming sources, confirm the manifest actually declares text tracks.
 
 ## Related pages
 

package/docs/guides/casting.md

@@ -8,9 +8,17 @@ Send playback to an Apple TV over AirPlay or a Chromecast over Google Cast while
 >
 > Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
 
+## Installation
+
+Install the Google Cast extension and the hls.js adapter used in the example below. AirPlay needs no extra package:
+
+```bash
+pnpm add @videojs/html @videojs/google-cast @videojs/hlsjs-video
+```
+
 ## Recommended approach
 
-Use the [`<google-cast>` extension](../reference/components/google-cast.md) with a [`<media-cast-button>`](../reference/components/cast-button.md), and add an [`<media-airplay-button>`](../reference/components/airplay-button.md) for Safari. The prebuilt skins already include both buttons; add `<google-cast>` next to a streaming media component to enable the configurable Cast route.
+Use the [`<google-cast>` extension](../reference/components/google-cast.md) with a [`<media-cast-button>`](../reference/components/cast-button.md), and add an [`<media-airplay-button>`](../reference/components/airplay-button.md) for Safari. The packaged skins already include both buttons; add `<google-cast>` anywhere inside the player to enable the configurable Cast route. It works with any media the player attaches, including a plain `<video>`.
 
 **index.html**
 
@@ -108,28 +116,32 @@ import '@videojs/html/ui/airplay-button';
 import '@videojs/html/ui/cast-button';
 ```
 
-The demo pairs the streaming media element with the `<google-cast>` extension. Without that extension, `<media-cast-button>` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
+The demo pairs the media element with the `<google-cast>` extension. Without that extension, `<media-cast-button>` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
 
 ## How it works
 
 The [remote playback feature](../reference/api/feature-remote-playback.md) gives AirPlay and Google Cast one state shape:
 
 - `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
-- `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
-- `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
+- `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`. The AirPlay route reports only `'disconnected'` and `'connected'`; Google Cast also reports `'connecting'`.
+- `promptRemotePlayback()` opens the browser’s device picker, including during an active session. Use the picker to connect to a device or return to local playback.
 
 AirPlay uses WebKit’s presentation APIs. Google Cast uses a sender and receiver: the browser sends the receiver a media URL and then controls playback. Your UI reads the same Video.js state for either route.
 
 While connected, playback actions — play, pause, seek, volume — proxy to the remote device, and player state keeps reflecting the remote session. Local playback is suspended.
 
-The Google Cast SDK loads only when the `<google-cast>` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
+Control playback and read its state through the player while casting: use the built-in controls or the [store actions and state](../reference/api/player-store.md) on the player element’s `store`. Don’t call methods on the media element or listen for its events to drive or track a session.
+
+For a custom control, call `promptRemotePlayback()` directly from the click handler and catch its promise. It rejects when no remote route exists or the browser refuses the request. A canceled Google Cast picker can also resolve without connecting, so show success only when `remotePlaybackState` is `'connected'`. The built-in buttons handle the request for you.
+
+The Google Cast SDK loads only when the player includes the `<google-cast>` extension and runs in a Chromium browser that can cast.
 
 ## Availability and constraints
 
 - Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
 - Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
 - AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
-- The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
+- The remote device fetches the source and its text tracks on its own. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
 - Set the `disableremoteplayback` attribute on the media element to opt out entirely.
 
 ## Common variations
@@ -142,7 +154,7 @@ By default, Video.js sends the current source to Google’s Default Media Receiv
 <google-cast receiver="YOUR_APP_ID"></google-cast>
 ```
 
-Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [`<google-cast>` reference](../reference/components/google-cast.md) for the exact option types and attribute-to-property mapping.
+Use `src` and `contentType` when the receiver should load a different source than the browser. A YouTube or Vimeo embed needs `src`: the receiver can’t play the embed itself, so without it nothing is sent to the receiver. `streamType` and `customData` let you describe that source and attach application-specific data. See the [`<google-cast>` reference](../reference/components/google-cast.md) for the exact option types and attribute-to-property mapping.
 
 ### Read connection state
 
@@ -158,9 +170,13 @@ The Cast button hides when the route is unsupported. In Chromium with no Cast de
 
 The receiver cannot fetch the media. Confirm the source URL is reachable from the device and served with CORS headers, including caption tracks.
 
+### Custom UI shows local playback while casting
+
+The code reads or controls the media element directly. Read playback state from the player store and call its actions instead; only the player reflects the remote session.
+
 ### The UI freezes on “connecting”
 
-The user dismissed the picker or the device disconnected. `remotePlaybackState` returns to `'disconnected'`; drive your UI from that state.
+For Google Cast, track the `promptRemotePlayback()` promise separately from `remotePlaybackState`. Clear your loading indicator when the promise settles. A canceled picker can resolve without connecting. AirPlay does not expose a `'connecting'` phase; show its connected or disconnected state instead.
 
 ## Related pages
 

package/docs/guides/cdn.md

@@ -23,7 +23,8 @@ Each installation [preset](./presets.md) ships its bundles at the package root:
 | File | Registers |
 | --- | --- |
 | `video.js` | `<video-player>`, `<video-skin>`, and the UI elements the skin composes |
-| `video-minimal.js` | `<video-player>`, `<video-minimal-skin>`, and the UI elements the minimal skin composes |
+| `video-neutral.js` | `<video-player>`, `<video-neutral-skin>`, and the UI elements the neutral skin composes |
+| `video-compat.js` | `<video-player>`, `<video-compat-skin>`, and the UI elements the compat skin composes |
 | `video-player.js` | `<video-player>` alone, for markup without a packaged skin |
 
 The other presets follow the same pattern. Background video is the exception: one bundle, `background.js`, registers the player, the skin, and the `<background-video>` media element.
@@ -35,8 +36,8 @@ A skin bundle registers every UI element its skin is built from. Any element the
 Each [UI element](./ui-components.md) is its own bundle under `ui/`, for markup that a skin bundle does not already cover: a player-only bundle, [skin source](./customize-skins.md#style-skin-source) that adds a component the packaged skin lacks, or a [dialog](../reference/components/dialog.md) your page opens beside a packaged skin.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video-player.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/ui/play-button.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/video-player.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/ui/play-button.js"></script>
 ```
 
 Each path mirrors its npm subpath: `ui/play-button.js` registers the element that `@videojs/html/ui/play-button` does. Compound components list one bundle per part in their reference page’s Import section, and all of the bundles share chunks with the player.
@@ -46,8 +47,8 @@ Each path mirrors its npm subpath: `ui/play-button.js` registers the element tha
 The default presets play through the browser’s own `<video>` and `<audio>`. Every other [media element](./media-sources.md) is its own bundle under `media/`, loaded beside the player bundle:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/hlsjs-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/media/hlsjs-video.js"></script>
 ```
 
 Each path mirrors its npm subpath. Elements with more than one playback engine keep the extra flavors in a directory named for the element, such as `media/mux-video/spf.js`. Load one flavor per page: every flavor claims the same tag name, and the first registration wins.
@@ -57,9 +58,9 @@ Each path mirrors its npm subpath. Elements with more than one playback engine k
 Each [extension](./architecture.md) is its own bundle under `extensions/`, loaded beside the player and media bundles:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/mux-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/extensions/mux-data.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/extensions/mux-data.js"></script>
 ```
 
 As with media, each path mirrors its npm subpath: `extensions/mux-data.js` registers the element that `@videojs/html/extensions/mux-data` does.
@@ -69,8 +70,8 @@ As with media, each path mirrors its npm subpath: `extensions/mux-data.js` regis
 English ships inside the skin bundles. Each other locale is a bundle under `locales/` that registers its translations on import. Load it before the player script to avoid a flash of English:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/locales/es.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/video.js"></script>
 ```
 
 One bundle exists per locale pack, plus bare-language aliases such as `pt`. For custom strings, see [Internationalize the player](./internationalization.md).

package/docs/guides/content-security-policy.md

@@ -8,13 +8,15 @@ Content Security Policy (CSP) limits which resources a page can load. Video.js u
 
 - `media-src` must allow your media URLs.
 - `img-src` must allow any poster or thumbnail image URLs.
-- `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
-- `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
-- `worker-src blob:` is required when using the `hls.js` player variants.
+- `connect-src` must allow manifests, playlists, captions, and segment requests when using HLS or DASH playback.
+- `media-src blob:` is required when your engine uses Media Source Extensions (MSE), including HLS and DASH engines.
+- `worker-src blob:` is required for hls.js workers, which are enabled by default.
 - `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
 
 ## Recommended policy
 
+Start with this policy for native, HLS, and DASH playback. For embeds and Google Cast, add the provider origins below.
+
 ```http
 Content-Security-Policy:
   script-src 'self';
@@ -23,11 +25,33 @@ Content-Security-Policy:
   media-src 'self' https: blob:;
   connect-src 'self' https:;
   worker-src 'self' blob:;
+  frame-src 'none';
 ```
 
-This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`. Add it to `style-src` too if you load stylesheets from that CDN.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need. Keep `media-src blob:` for engines that use MSE. Keep `worker-src blob:` for engines that create blob workers, as hls.js does by default.
+
+## Allow embeds and Google Cast
+
+Add only the origins for the providers you use. Extend `script-src` with their script origins. If a provider lists iframe origins, replace `frame-src 'none'` with those origins. A dash means the Video.js integration does not directly load that resource.
+
+| Provider | `script-src` origins | `frame-src` origins |
+| --- | --- | --- |
+| YouTube | `https://www.youtube.com` | `https://www.youtube.com` or `https://www.youtube-nocookie.com`, depending on your source URL |
+| Vimeo | — | `https://player.vimeo.com`; `https://vimeo.com` for live events |
+| Spotify | `https://open.spotify.com` | `https://open.spotify.com` |
+| TikTok | — | `https://www.tiktok.com` |
+| Twitch | — | `https://player.twitch.tv` |
+| Cloudflare | `https://embed.videodelivery.net` | `https://iframe.videodelivery.net` or your `https://customer-<code>.cloudflarestream.com` origin |
+| Google Cast | `https://www.gstatic.com` | — |
+| Wistia | `https://fast.wistia.com` and `https://fast.wistia.net` | `https://fast.wistia.com` and `https://fast.wistia.net` if the SDK falls back to an iframe |
+
+For Cloudflare, use `https://iframe.videodelivery.net` unless your source URL names a customer origin. In that case, replace `<code>` with your customer code.
+
+The Wistia SDK bundled with Video.js normally renders its player in the page and can fall back to an iframe. It loads scripts and media data from `fast.wistia.com` and `fast.wistia.net`. If you narrow `connect-src`, keep both origins.
 
-Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.
+The table covers entry scripts and embed frames. Provider SDKs can request additional resources. Test your selected media under your policy, check the browser’s CSP violations, and allow the exact origins those requests need.
 
 ## Related pages
 

package/docs/guides/controls.md

@@ -65,7 +65,7 @@ Wrap your control UI in [`<media-controls>`](../reference/components/controls.md
 }
 
 .controls-backdrop:not([data-visible]),
-.media-controls:not([data-visible]) {
+.media-controls:not([data-visible]):not(:has(:focus-visible)) {
   opacity: 0;
 }
 
@@ -134,18 +134,18 @@ import '@videojs/html/ui/time';
 
 The [controls feature](../reference/api/feature-controls.md) tracks activity on the player container:
 
-- `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
+- `userActive` becomes `true` on pointer movement, keyboard input, or focus entry. It becomes `false` after two seconds without another activity event, or when the mouse leaves the container.
 - `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
-- `toggleControls()` flips visibility, for wiring to custom triggers.
+- `toggleControls(forceShow?)` marks the user inactive when controls are visible, and shows them otherwise. Pass `true` to show controls or `false` to mark the user inactive. Paused playback, a remote session, or an open menu can keep controls visible even when the user is inactive.
 
-On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
+On touch devices, pointer movement does not show controls. A tap on the media toggles them, and movement during a gesture does not make them flicker.
 
-The feature needs the player container for activity tracking; without a container it stays inactive and warns in development.
+The feature needs the player container for activity tracking. Without one, it keeps its initial active and visible state and warns in development.
 
 ## Availability and constraints
 
 - Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
-- Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
+- Focus entry restarts the idle timer; holding focus alone does not keep controls visible. The example uses `:has(:focus-visible)` to keep controls visible while they contain keyboard focus. Focus from a mouse click does not hold them open.
 - Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
 - The idle delay is fixed at two seconds.
 
@@ -153,7 +153,7 @@ The feature needs the player container for activity tracking; without a containe
 
 ### Always-visible controls
 
-Set `visibility="always"` on [`<media-controls>`](../reference/components/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
+Set `visibility="always"` on [`<media-controls>`](../reference/components/controls.md). This keeps the UI visible. When the controls feature is present, `userActive` still follows its activity tracking. The packaged audio skins use this mode.
 
 ```html
 <media-controls visibility="always">
@@ -163,13 +163,28 @@ Set `visibility="always"` on [`<media-controls>`](../reference/components/contro
 
 ### Custom show/hide styling
 
-Controls hide by state, so you own the transition. Style the visible and hidden states in CSS — fade, slide, or scale — driven by the component’s rendered state rather than re-implementing the idle timer.
+Style the visible and hidden states in CSS with a fade, slide, or scale, using the component’s `data-visible` attribute. The controls feature handles the idle timer.
+
+Keep controls with keyboard focus visible in your hiding rule:
+
+```css
+.media-controls:not([data-visible]):not(:has(:focus-visible)) {
+  opacity: 0;
+}
+```
 
 ## Troubleshooting
 
 ### Controls never hide
 
-The media is paused (controls intentionally stay visible), a remote playback session is active, an open menu or popover holds a controls lock, or something keeps triggering activity — for example a focused element inside the container receiving repeated events.
+Check for these causes:
+
+- The media is paused. Controls stay visible by design.
+- A remote playback session is active.
+- An open menu or popover holds a controls lock.
+- Something keeps triggering activity, such as a focused element inside the container that receives repeated events.
+
+With the `:has(:focus-visible)` CSS rule above, keyboard focus keeps the controls visible even after activity becomes idle. Move focus out of the controls to let them hide.
 
 ### Controls don’t come back on touch
 
@@ -177,7 +192,7 @@ A tap on the media toggles controls. If a custom overlay covers the media and sw
 
 ### Controls flicker on Android while tapping
 
-Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
+Use the skin gestures (`tap` with the `toggleControls` action). When two handlers both toggle controls, one shows them and the other hides them again. Remove extra tap handlers that duplicate the built-in behavior. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
 
 ## Related pages
 

package/docs/guides/customize-skins.md

@@ -34,7 +34,7 @@ Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-U
 | `--media-object-position` | Where the media and poster sit when they do not fill the player | A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position) | `top` |
 | `--media-scale-unit` | The base size for skin spacing, icons, and text | [`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | `1rem` |
 
-If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Set it only when you want a different result.
+If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Browsers before Chrome 147, Firefox 146, and Safari 26 lack `contrast-color()` and use the theme’s default text color instead, which suits only the default accent, so set both properties together if you support those browsers.
 
 The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
 
@@ -106,7 +106,7 @@ Start with the file that owns the change you want:
 | --- | --- |
 | Add, remove, or rearrange controls | `skin.html` |
 | Change default colors, surfaces, shadows, sizes, or motion across skins | `components/videojs/styles/themes/theme.css` |
-| Change only the Minimal theme or one media preset | `components/videojs/styles/themes/minimal.css`, `components/videojs/styles/video/theme.css`, or `components/videojs/styles/audio/theme.css` |
+| Change only Neutral, Compat, or one media preset | `components/videojs/styles/themes/neutral.css`, `components/videojs/styles/themes/compat.css`, `components/videojs/styles/video/theme.css`, or `components/videojs/styles/audio/theme.css` |
 | Change one control’s appearance | That control’s classes or stylesheet |
 | Change one control’s interaction | That control’s module |
 

package/docs/guides/features.md

@@ -4,6 +4,8 @@ The state and actions each feature adds to the player
 
 Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
 
+- [See every feature’s state and actions](../reference/api/player-store.md)
+
 ## Feature bundles and presets
 
 You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
@@ -101,7 +103,7 @@ You can also check availability in JS:
 ```ts
 const media = this.#pip.value;
 
-if (media?.pipAvailability !== 'available') {
+if (media?.pictureInPictureAvailability !== 'available') {
   this.hidden = true;
 }
 ```