@videojs/html 10.0.0-rc.4 → 10.0.0-rc.5

package/docs/guides/ui-components.md

@@ -24,7 +24,7 @@ For components you add yourself, select them by their custom element name. Use t
 
 ### Add icons
 
-Import `@videojs/html/icons/element` once in your `app.ts` to register `<media-icon>`. Choose an icon with `name`. Set `family="minimal"` to use the Minimal skin’s icon designs. You can also use your own text or SVG.
+Import `@videojs/html/icons/element` once in your `app.ts` to register `<media-icon>`. Choose an icon with `name`. Set `family="neutral"` or `family="compat"` to use the Neutral or Compat skin’s icon designs. You can also use your own text or SVG.
 
 ```ts
 import '@videojs/html/icons/element';

package/docs/guides/user-preferences.md

@@ -1,8 +1,8 @@
 # Remember user preferences
 
-Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.
 
-The player doesn’t persist preferences itself today. Player state gives you everything needed to wire persistence to the storage you choose — local storage, your backend, or per-profile settings.
+Save preferences from player state to local storage or your backend. Video.js leaves storage and per-profile settings to your application.
 
 ## Recommended approach
 
@@ -16,16 +16,18 @@ Subscribe to the state you want to remember, write it to storage when it changes
 </video-player>
 <script type="module">
   import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
   import { selectVolume } from '@videojs/html';
 
   const STORAGE_KEY = 'player:volume';
   const player = document.querySelector('video-player');
   const store = player.store;
 
-  // Local storage can be unavailable (private modes), so guard reads and writes.
+  // Guard storage access so playback still works when storage is blocked.
   function readSaved() {
     try {
-      return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
+      const value = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
+      return Number.isFinite(value?.volume) && typeof value?.muted === 'boolean' ? value : null;
     } catch {
       return null;
     }
@@ -46,9 +48,8 @@ Subscribe to the state you want to remember, write it to storage when it changes
       if (!store.target) return false;
       const v = selectVolume(store.state);
       v?.setVolume(saved.volume);
-      // setVolume above zero unmutes, so mute again if that's the saved preference.
-      // At volume zero the player already counts as muted, and toggling would unmute.
-      if (v && saved.muted && saved.volume > 0) v.toggleMuted();
+      // Apply saved mute after setVolume, which unmutes above zero.
+      if (saved.muted) v?.setMuted(true);
       return true;
     };
     if (!restore()) {
@@ -72,26 +73,48 @@ Subscribe to the state you want to remember, write it to storage when it changes
 ## How it works
 
 - Player state is the single source of truth: it already reflects every change, whatever caused it — your UI, keyboard shortcuts, native controls, or scripts.
-- `store.subscribe(callback)` fires on any state change. Notifications are batched per microtask, so rapid changes (a volume drag) produce one callback per tick, which keeps storage writes cheap. There is no per-key subscription on the store: read the state and diff the slice you care about.
+- `store.subscribe(callback)` fires on any state change. The store batches notifications per microtask, so changes made in the same tick produce one callback. There is no per-key subscription on the store: read the state and diff the slice you care about.
 - Feature selectors exported by `@videojs/html` (`selectVolume`, `selectTextTrack`, `selectQuality`, and the rest) read a feature’s slice from any store, returning `undefined` when the feature isn’t present.
-- Restore through the feature actions (`setVolume`, `toggleMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
+- Restore through the feature actions (`setVolume`, `setMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
 - Actions need an attached media target: calling one before the store attaches throws. Check `store.target` and defer the restore until it is set, as the examples do.
 
 ## Availability and constraints
 
-- Nothing persists by default: volume resets to the media element’s value, captions to the track markup, quality to automatic, on every load.
-- `setVolume` clamps to 0–1 and unmutes when setting a value above zero; restore volume first, then toggle `muted` back on when the saved preference is muted, as the examples do. Skip the toggle when the saved volume is zero: the player treats volume zero as muted, so toggling would unmute and raise the volume. Don’t compare against store state right after calling an action: notifications batch per microtask, so that state is still stale.
-- Restore track and quality selections after the media exposes them: track and rendition lists arrive when the media loads, not at player creation. Subscribe and apply when the saved entry appears in the list.
-- Programmatic volume control is unavailable on some platforms (after attach, iOS Safari reports `volumeAvailability: 'unsupported'`); volume persistence quietly does nothing there.
+- Video.js does not write preferences to storage. Initial values come from the media element, track markup, and playback engine.
+- `setVolume` clamps to 0–1 and unmutes above zero. Restore volume first, then call `setMuted(true)` if the saved preference is muted. Calling `setMuted(false)` at zero raises the volume to 0.25.
+- The volume examples leave autoplay off. For muted autoplay, defer volume restoration until a user action: restoring a positive volume unmutes the media and can interrupt autoplay, even if you immediately mute it again.
+- `setVolume` and `setMuted` update `store.state` immediately. A React hook’s selected value updates on the next render.
+- Track and rendition lists arrive when the media loads, not when the player is created. Subscribe and restore a saved selection when its entry appears in the list.
+- On iOS Safari, `volumeAvailability` is `'unsupported'` after attachment. Restoring the volume level has no effect there; mute can still be restored.
 - Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
 
 ## Common variations
 
 ### Persist caption preference
 
-Save the showing track’s `language` (not its generated id, which can change between sources), or `'off'` when the user turns captions off. Restoring is two phases: while the media loads, assert the saved preference whenever the track modes drift from it, because browsers can auto-enable a track of their own during loading. Once the media can play (`canPlay`), treat every change as the user’s choice and save it. A restore that re-runs forever would keep overriding the user; one that runs only once can get overridden by the browser.
+Save the showing track’s `language` because track ids can change between sources. Save `'off'` when captions are off. Restore once when the first caption or subtitle list arrives, then save later selection changes. Do not wait for `canPlay`. With limited preloading, `canPlay` can stay `false` until playback starts. Repeated restoration would override a selection the user already made.
 
-Apply the same pattern with `selectTextTrack(store.state)` inside `store.subscribe`: until `canPlay` is true, re-apply the saved preference by passing the matching track’s `id` (or `'off'`) to `selectSubtitlesTrack` whenever the modes drift; afterward, save the showing track’s `language`, or `'off'` when none is showing, on every change.
+If the saved language is absent from that first list, leave the stored preference intact until the selection changes. This example does not retry restoration when more tracks arrive; adapt the initial loading step if your engine exposes languages in several batches. Browser selection changes after restoration are saved just like user changes.
+
+Apply the same pattern in a store subscription:
+
+1. Inside `store.subscribe`, read the track state with `selectTextTrack(store.state)`.
+2. When the first caption or subtitle list arrives, record the current selection and mark restoration complete. If the saved language is present, call `selectSubtitlesTrack` with that track’s `id`. If the saved value is `'off'`, pass `null`. Do not save during this first pass.
+3. After that, save selection changes. If the saved language was absent from the first list, keep the stored preference until the selection changes.
+4. Guard `localStorage` reads and writes, and restart restoration for each new source.
+
+Omit `default` from the tracks when persisting caption preferences. A default track can turn on after restoration, causing the subscription to save its language over a stored `'off'` preference.
+
+### Remember a quality selection
+
+Adapt the same restore-then-save pattern to the [quality feature](../reference/api/feature-quality.md):
+
+1. Save `'auto'` or the resolution of the selected entry in `videoRenditionList`. Read `selected`; `activeVideoRendition` can change during automatic playback and does not identify a manual preference.
+2. Wait for the next source’s rendition list, then match the saved resolution to an entry. Rendition ids belong to that source, so do not reuse a saved id across sources.
+3. Call `selectVideoRendition` with the matching entry’s id, or `'auto'` if no match exists. Every entry in `videoRenditionList` has an id; use it directly.
+4. Do not save until restoration finishes; otherwise the source’s default selection overwrites the saved choice. After that, save each change the user makes.
+
+To remember a data-saving limit while preserving automatic switching, persist `maxAutoResolution` and pass it on the next source. It needs the hls.js engine; native HLS playback ignores it. See [Options Video.js normalizes](./media-sources.md#options-videojs-normalizes).
 
 ### Persist to your backend
 

package/docs/guides/v10-roadmap.md

@@ -51,7 +51,7 @@ Feature-complete release ahead of GA.
 
 - Core feature parity with v8 in terms of fundamentals
 - Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
-- Community encouraged to begin full reintegration projects, following the migration guides for [Video.js 8](./migrate-from-video-js-8.md), [Mux Player](./migrate-from-mux-player.md), [Plyr](./migrate-from-plyr.md), and [Media Chrome](./migrate-from-media-chrome.md)
+- Community encouraged to begin full reintegration projects, following the migration guides for [Video.js 8](./migrate-from-video-js-8.md), [Mux Player](./migrate-from-mux-player.md), [Plyr](./migrate-from-plyr.md), [Media Chrome](./migrate-from-media-chrome.md), and [Vidstack](./migrate-from-vidstack.md)
 - Plugin ecosystem migration begins in earnest
 
 ### Engine development focus

package/docs/llms.txt

@@ -1,11 +1,13 @@
 # Video.js v10 — HTML Documentation
 
-> Bundled with `@videojs/html` v10.0.0-rc.4. Links are relative paths to files in this directory.
+> Bundled with `@videojs/html` v10.0.0-rc.5. Links are relative paths to files in this directory.
 
 > Install the [Video.js skill](https://github.com/videojs/skills) to help AI coding agents find version-matched pages from this index.
 
 > The `video.js` package on npm is still Video.js 8. Video.js 10 ships as `@videojs/html`; to move existing Video.js 8 code, read https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8.md
 
+> Vidstack Player is in security-only maintenance. To move existing `vidstack` code, read https://videojs.org/docs/framework/html/guides/migrate-from-vidstack.md
+
 > Print version-matched installation options without changing files: `npx @videojs/cli agents init`, then pass `--framework html` with the other choices. Installation guide index: https://videojs.org/docs/guides/installation.md
 
 ## Guides
@@ -27,7 +29,7 @@ Install Video.js, customize a skin, understand its main pieces, check browser an
 - [Architecture](./guides/architecture.md): How Video.js players are structured — state, UI, media, and extensions
 - [Customize skins](./guides/customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
 - [Why Video.js?](./guides/why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
-- [Browser support](./guides/browser-support.md): Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
+- [Browser support](./guides/browser-support.md): Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them
 - [Build with AI](./guides/build-with-ai.md): Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
 - [v10 Roadmap](./guides/v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
 - [Contribute to Video.js](https://github.com/videojs/v10/blob/main/CONTRIBUTING.md)
@@ -76,7 +78,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Show timeline thumbnail previews](./guides/thumbnails.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
 - [Cast to AirPlay and Chromecast](./guides/casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
 - [Handle playback errors](./guides/playback-errors.md): Display playback failures, report them, and choose a useful recovery action.
-- [Remember user preferences](./guides/user-preferences.md): Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+- [Remember user preferences](./guides/user-preferences.md): Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.
 - [Add a background video](./guides/background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
 - [Internationalize the player](./guides/internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
 - [Monitor playback with Mux Data](./guides/mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
@@ -86,9 +88,10 @@ Guides for one player capability each: the recommended setup, how it works, brow
 Guides for moving an existing player integration to Video.js v10, one per player you might be coming from.
 
 - [Migrate from Video.js 8](./guides/migrate-from-video-js-8.md): Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
-- [Migrate from Mux Player](./guides/migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
+- [Migrate from Mux Player](./guides/migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10 using a player, media component, skin, and analytics extension
 - [Migrate from Plyr](./guides/migrate-from-plyr.md): Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
-- [Migrate from Media Chrome](./guides/migrate-from-media-chrome.md): Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
+- [Migrate from Media Chrome](./guides/migrate-from-media-chrome.md): Move a Media Chrome player to Video.js v10, mapping its controller, controls, styles, and imperative calls
+- [Migrate from Vidstack](./guides/migrate-from-vidstack.md): Move a Vidstack Player integration to Video.js 10, mapping the player, providers, layouts, and media store onto composed components
 
 ## Components
 
@@ -109,13 +112,17 @@ API reference for the components that establish a player and lay out its interfa
 API reference for the packaged skins each preset ships.
 
 - [video-skin](./reference/components/video-skin.md): The video preset's default skin with the modern, frosted look
-- [video-minimal-skin](./reference/components/video-minimal-skin.md): The video preset's visually lighter skin, closer to a classic control bar
+- [video-neutral-skin](./reference/components/video-neutral-skin.md): The video preset's visually lighter skin, closer to a classic control bar
+- [video-compat-skin](./reference/components/video-compat-skin.md): A video skin designed for broader browser compatibility
 - [audio-skin](./reference/components/audio-skin.md): The audio preset's default skin with the modern, frosted look
-- [audio-minimal-skin](./reference/components/audio-minimal-skin.md): The audio preset's visually lighter skin, closer to a classic control bar
+- [audio-neutral-skin](./reference/components/audio-neutral-skin.md): The audio preset's visually lighter skin, closer to a classic control bar
+- [audio-compat-skin](./reference/components/audio-compat-skin.md): An audio skin designed for broader browser compatibility
 - [live-video-skin](./reference/components/live-video-skin.md): The live video preset's default skin, which swaps time controls for a Live button
-- [live-video-minimal-skin](./reference/components/live-video-minimal-skin.md): The live video preset's visually lighter skin, closer to a classic control bar
+- [live-video-neutral-skin](./reference/components/live-video-neutral-skin.md): The live video preset's visually lighter skin, closer to a classic control bar
+- [live-video-compat-skin](./reference/components/live-video-compat-skin.md): A live video skin designed for broader browser compatibility
 - [live-audio-skin](./reference/components/live-audio-skin.md): The live audio preset's default skin, which swaps time controls for a Live button
-- [live-audio-minimal-skin](./reference/components/live-audio-minimal-skin.md): The live audio preset's visually lighter skin, closer to a classic control bar
+- [live-audio-neutral-skin](./reference/components/live-audio-neutral-skin.md): The live audio preset's visually lighter skin, closer to a classic control bar
+- [live-audio-compat-skin](./reference/components/live-audio-compat-skin.md): A live audio skin designed for broader browser compatibility
 - [background-video-skin](./reference/components/background-video-skin.md): The background preset's chrome-less skin for ambient video
 
 ### Media
@@ -215,9 +222,15 @@ API reference for the non-visual components that add gestures, hotkeys, and anno
 - [media-hotkey](./reference/components/hotkey.md): Register a keyboard shortcut that invokes a player action
 - [media-status-announcer](./reference/components/status-announcer.md): Announce player state changes through a persistent status live region
 
+### Icons
+
+API reference for the icon sets the skins use, available for your own controls.
+
+- [Icons](./reference/components/icons.md): The SVG icon sets used by the packaged skins, as React components, SVG strings, and the media-icon element
+
 ## API
 
-API reference for the player factory, store controllers, features, translation tools, and utilities.
+API reference for the player factory, presets, store controllers, features, translation tools, and utilities.
 
 Section index: [reference/api/llms.txt](./reference/api/llms.txt).
 
@@ -227,11 +240,24 @@ API reference for creating a player and reaching it and its container from your
 
 - [createPlayer](./reference/api/html-create-player.md): Factory function that creates a typed player element and controller for HTML custom elements
 - [PlayerController](./reference/api/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [UIElement](./reference/api/ui-element.md): Base class for custom elements that read player state through reactive controllers
+- [Media capability guards](./reference/api/media-capabilities.md): Type guards that narrow a Media object to the capabilities it supports
+
+### Presets
+
+API reference for the presets: each bundles a player, feature bundle, skins, and media for one use case.
+
+- [Video preset](./reference/api/preset-video.md): The general-purpose video preset — a player, feature bundle, skins, and media for on-demand video
+- [Audio preset](./reference/api/preset-audio.md): The audio-only preset — a player, feature bundle, skins, and media for on-demand audio
+- [Live video preset](./reference/api/preset-live-video.md): The live video preset — a player, feature bundle, skins, and media for live video streams
+- [Live audio preset](./reference/api/preset-live-audio.md): The live audio preset — a player, feature bundle, skins, and media for live audio streams
+- [Background preset](./reference/api/preset-background.md): The background video preset — a player, feature bundle, skin, and media for ambient video with no controls
 
 ### Store
 
 API reference for reading and subscribing to player state: selectors and the store controllers.
 
+- [Player store](./reference/api/player-store.md): Every state field and action on the player store, grouped by the feature that adds it
 - [createSelector](./reference/api/create-selector.md): Create a type-safe selector for a store slice's state
 - [StoreController](./reference/api/store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
 - [SnapshotController](./reference/api/snapshot-controller.md): Reactive controller for subscribing to a State container in HTML custom elements
@@ -273,12 +299,20 @@ API reference for translating the player: the i18n elements, controller, and the
 - [hasRegisteredLocale](./reference/api/has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
 - [onI18nRegistryChange](./reference/api/on-i18n-registry-change.md): Subscribe to global i18n registry mutations
 - [createTranslator](./reference/api/create-translator.md): Build a typed translator from a resolved translation map
+- [translateText](./reference/api/translate-text.md): Translate a text descriptor, or fall back to its English default
+- [resolveTranslation](./reference/api/resolve-translation.md): Translate a key with the params its English default requires
+- [isText](./reference/api/is-text.md): Check whether a value is a text descriptor
+- [loadLocale](./reference/api/load-locale.md): Lazy-load the built-in translation pack for a locale
+- [getLocaleKey](./reference/api/get-locale-key.md): Normalize a locale tag to the key the i18n registry stores it under
+- [findLocaleKeys](./reference/api/find-locale-keys.md): List the locale tags a lookup falls back through, most specific first
 - [I18nController](./reference/api/i18n-controller.md): Reactive controller for consuming translator and locale values from an HTML i18n context
 
 ### Utils
 
-Lower-level building blocks for custom components: the keyboard shortcut controller.
+Lower-level building blocks: adapter and MIME type resolution, and the keyboard shortcut controller for custom components.
 
+- [resolveAdapterType](./reference/api/resolve-adapter-type.md): Resolve which type of adapter plays a source URL, from its host, MIME type, or file extension
+- [resolveMimeType](./reference/api/resolve-mime-type.md): Resolve a source's MIME type from its file extension
 - [AriaKeyShortcutsController](./reference/api/aria-key-shortcuts-controller.md): Reactive controller that exposes registered hotkey shortcut metadata
 
 ### Error codes

package/docs/reference/api/create-i18n.md

@@ -11,13 +11,13 @@ import { createI18n } from "@videojs/html/i18n";
 `createI18n` returns a context-bound `ProviderMixin`, `TextMixin`, and `I18nController` for custom elements. Use it when you need a custom locale loader or custom i18n elements. Most apps use `<media-i18n>` and `<media-text>` from `@videojs/html/i18n`.
 
 ```ts
-import { ReactiveElement } from '@videojs/element';
+import { UIElement } from '@videojs/html';
 import { createI18n } from '@videojs/html/i18n';
 
 const { ProviderMixin, TextMixin } = createI18n();
 
-class LocalizedRoot extends ProviderMixin(ReactiveElement) {}
-class LocalizedText extends TextMixin(ReactiveElement) {}
+class LocalizedRoot extends ProviderMixin(UIElement) {}
+class LocalizedText extends TextMixin(UIElement) {}
 ```
 
 ## API Reference

package/docs/reference/api/create-translator.md

@@ -8,7 +8,7 @@ Build a typed translator from a resolved translation map
 import { createTranslator } from "@videojs/html/i18n";
 ```
 
-`createTranslator` wraps the flat map returned by `getI18nTranslations` and returns a typed translator. Providers call this internally after merging registry, lazy-loaded built-in packs, browser-translated fallback copy, and provider layers. Use it directly for custom UI outside built-in controls.
+`createTranslator` wraps the flat map returned by `getI18nTranslations` and returns a typed `Translator` function. Providers call this internally after merging registry, lazy-loaded built-in packs, browser-translated fallback copy, and provider layers. Use it directly for custom UI outside built-in controls.
 
 ```ts
 import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';

package/docs/reference/api/feature-audio-track.md

@@ -24,7 +24,7 @@ The `videoFeatures` [feature bundle](../../guides/presets.md) includes this feat
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `selectAudioTrack` | `(value: string) => void` | Select an audio track by menu value. |
+| `selectAudioTrack` | `(id: string) => void` | Select an audio track by `id`. |
 
 ### Selector
 

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

@@ -2,7 +2,7 @@
 
 User activity and controls visibility state for the player store
 
-Read-only — tracks user activity for showing and hiding controls.
+Tracks user activity for showing and hiding controls, with actions to toggle visibility and keep controls shown.
 
 ## Import
 
@@ -26,7 +26,7 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 | Action | Type | Description |
 | --- | --- | --- |
 | `requestControlsLock` | `() => (() => void)` | Keep controls visible during a sustained interaction. The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent. |
-| `toggleControls` | `() => boolean` | Toggle controls visibility. Returns the new `controlsVisible` value. |
+| `toggleControls` | `(forceShow?: boolean) => boolean` | Toggle controls visibility, or force it with `forceShow`. Returns the new `controlsVisible` value. |
 
 ### Selector
 

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

@@ -18,7 +18,7 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `fullscreen` | `boolean` | Whether fullscreen mode is currently active. |
+| `isFullscreen` | `boolean` | Whether fullscreen mode is currently active. |
 | `fullscreenAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether fullscreen can be requested on this platform. |
 
 ### Actions
@@ -27,7 +27,6 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 | --- | --- | --- |
 | `requestFullscreen` | `() => Promise<void>` | Enter fullscreen mode. Tries container first, falls back to media element. |
 | `exitFullscreen` | `() => Promise<void>` | Exit fullscreen mode. |
-| `toggleFullscreen` | `() => Promise<void>` | Toggle fullscreen mode. |
 
 ### Selector
 

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

@@ -18,16 +18,15 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `pip` | `boolean` | Whether picture-in-picture mode is currently active. |
-| `pipAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether picture-in-picture can be requested on this platform. |
+| `isPictureInPicture` | `boolean` | Whether picture-in-picture mode is currently active. |
+| `pictureInPictureAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether picture-in-picture can be requested on this platform. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `requestPictureInPicture` | `() => Promise<void>` | Enter picture-in-picture mode. |
+| `requestPictureInPicture` | `() => Promise<void>` | Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. |
 | `exitPictureInPicture` | `() => Promise<void>` | Exit picture-in-picture mode. |
-| `togglePictureInPicture` | `() => Promise<void>` | Toggle picture-in-picture mode. |
 
 ### Selector
 

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

@@ -27,9 +27,8 @@ The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeature
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `play` | `() => Promise<void>` | Start playback. |
-| `pause` | `() => void` | Pause playback. |
-| `togglePaused` | `() => boolean` | Toggle play/pause. Returns `true` if playback started. |
+| `play` | `() => Promise<void>` | Start playback. Updates `paused` immediately when the media starts. |
+| `pause` | `() => void` | Pause playback. Updates `paused` immediately. |
 
 ### Selector
 

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

@@ -19,13 +19,13 @@ The `videoFeatures` [feature bundle](../../guides/presets.md) includes this feat
 | Property | Type | Description |
 | --- | --- | --- |
 | `videoRenditionList` | `MediaVideoRendition[]` | Video renditions available for manual quality selection. |
-| `activeVideoRendition` | `{ id?: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } \| null` | Video rendition currently playing, including when automatic ABR is selected. |
+| `activeVideoRendition` | `{ id: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } \| null` | Video rendition currently playing, including when automatic ABR is selected. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `selectVideoRendition` | `(value: string) => void` | Select a video rendition by menu value, or automatic ABR with `"auto"`. |
+| `selectVideoRendition` | `(id: string) => void` | Select a video rendition by `id`, or automatic ABR with `"auto"`. |
 
 ### Selector
 

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

@@ -27,7 +27,7 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `toggleRemotePlayback` | `() => Promise<void>` | Toggle the remote playback connection. |
+| `promptRemotePlayback` | `() => Promise<void>` | Prompt the user to pick a remote playback device. Exits fullscreen first when connecting. |
 
 ### Selector
 

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

@@ -2,7 +2,7 @@
 
 Media source state and actions for the player store
 
-Tracks the current media source and readiness.
+Tracks the loaded media resource and how much of it is ready. To change the source, set `src` or `source` on the media element, which also carries type and engine configuration.
 
 ## Import
 
@@ -18,15 +18,9 @@ The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeature
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `source` | `string \| null` | Current media source URL (null if none). |
+| `currentSrc` | `string` | Current media source URL (empty string if none). |
 | `canPlay` | `boolean` | Whether enough data is loaded to begin playback. |
 
-### Actions
-
-| Action | Type | Description |
-| --- | --- | --- |
-| `loadSource` | `(src: string) => string` | Load a new media source. Returns the new source URL. |
-
 ### Selector
 
 Pass `selectSource` to [`PlayerController`](./player-controller.md) to subscribe to source state. Returns `undefined` if the source feature is not configured.

package/docs/reference/api/feature-text-tracks.md

@@ -6,7 +6,7 @@ Manages subtitles, captions, chapters, and thumbnail tracks.
 
 A default `kind="chapters"` track can also divide the [time slider](../components/time-slider.md) into chapter ranges and label the chapter at the current interaction position.
 
-When a thumbnail track is present, `thumbnailTrackCrossOrigin` reports the media element’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](../components/thumbnail.md) reads it to fetch sprite sheets the same way the browser fetched the track.
+`thumbnailsTrack` is the first `kind="metadata"` track labeled `thumbnails`, or `null` when there is none. Its `crossOrigin` reports the media element’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](../components/thumbnail.md) reads it to fetch sprite sheets the same way the browser fetched the track.
 
 ## Import
 
@@ -22,19 +22,17 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `chaptersCues` | `MediaTextCue[]` | Cues from the first `kind="chapters"` track. |
-| `thumbnailCues` | `MediaTextCue[]` | Cues from the first `kind="metadata" label="thumbnails"` track. |
-| `thumbnailTrackSrc` | `string \| null` | The `<track>` element's `src` for resolving relative cue text URLs. |
-| `thumbnailTrackCrossOrigin` | `'anonymous' \| 'use-credentials' \| null` | The media element's CORS mode, mapped through the CORS-settings-attribute rules, or `null` when it is not in CORS mode. Thumbnail UI fetches the sprite sheets the cues point at with this mode, since a cross-origin `<track>` only loads at all when the media element is CORS-enabled. |
 | `textTrackList` | `MediaTextTrack[]` | All text tracks available on the media element. |
-| `subtitlesShowing` | `boolean` | Whether captions/subtitles are currently enabled. |
+| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
+| `chaptersCues` | `MediaTextCue[]` | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
+| `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | The first thumbnails track, or `null` when there is none. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | Toggle captions/subtitles visibility. Showing restores the track that was last showing, or the first caption/subtitle track when there is none. Returns the new enabled value. |
-| `selectSubtitlesTrack` | `(value: string) => void` | Select a captions/subtitles track by menu value, or disable with `"off"`. |
+| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
+| `selectSubtitlesTrack` | `(id: string \| null) => void` | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
 
 ### Selector
 

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

@@ -28,7 +28,7 @@ The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeature
 | Action | Type | Description |
 | --- | --- | --- |
 | `setVolume` | `(volume: number) => number` | Set volume (clamped 0-1). Returns the clamped value. |
-| `toggleMuted` | `() => boolean` | Toggle mute state. Returns the new muted value. |
+| `setMuted` | `(muted: boolean) => boolean` | Set the muted state, updating the store immediately. Unmuting at volume 0 restores volume to 0.25. Returns the new muted value. |
 
 ### Selector
 

package/docs/reference/api/find-locale-keys.md

@@ -0,0 +1,32 @@
+# findLocaleKeys
+
+List the locale tags a lookup falls back through, most specific first
+
+## Import
+
+```ts
+import { findLocaleKeys } from "@videojs/html/i18n";
+```
+
+`findLocaleKeys` returns the fallback chain the player resolves a locale through: the normalized tag from [`getLocaleKey`](./get-locale-key.md), then each shorter prefix, ending with `en`. A Chinese tag with a script, such as `zh-Hant-HK`, also falls back through `zh-tw` or `zh-cn` before `zh`. A translation missing from one locale is looked up in the next.
+
+```ts
+import { findLocaleKeys } from '@videojs/html/i18n';
+
+findLocaleKeys('es-419-u-nu-latn'); // ['es-419', 'es', 'en']
+findLocaleKeys('fr'); // ['fr', 'en']
+```
+
+## API Reference
+
+`findLocaleKeys(locale): Locale[]`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to resolve. |
+
+### Return Value
+
+`Locale[]`

package/docs/reference/api/get-locale-key.md

@@ -0,0 +1,32 @@
+# getLocaleKey
+
+Normalize a locale tag to the key the i18n registry stores it under
+
+## Import
+
+```ts
+import { getLocaleKey } from "@videojs/html/i18n";
+```
+
+`getLocaleKey` lowercases a BCP 47 tag, replaces underscores with hyphens, and removes Unicode extensions such as `-u-nu-latn`. The registry stores [`registerI18n`](./register-i18n.md) layers under this key, so use it to compare a tag with one you have registered or to key your own per-locale data the same way.
+
+```ts
+import { getLocaleKey } from '@videojs/html/i18n';
+
+getLocaleKey('en_US-u-nu-latn'); // 'en-us'
+getLocaleKey('zh-Hant'); // 'zh-hant'
+```
+
+## API Reference
+
+`getLocaleKey(locale): Locale`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to normalize. |
+
+### Return Value
+
+`(typeof LOCALES)[number] | string & {}`