@videojs/html 10.0.0-rc.4 → 10.0.0

package/docs/guides/migrate-from-media-chrome.md

@@ -1,16 +1,63 @@
 # Migrate from Media Chrome
 
-Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
+Move a Media Chrome player to Video.js v10, mapping its controller, controls, styles, and imperative calls
 
-Video.js v10’s HTML player uses the same `media-*` custom-element convention as Media Chrome, so most of the work is **renaming and reshaping**, not rewriting.
+Replace Media Chrome’s controller with a Video.js player and container, then migrate your controls. The libraries share `media-*` tag names, but their attributes, child markup, icons, and styles differ.
 
 > **Note**
 >
-> Scoped to apps that compose their own player from Media Chrome elements. If you use `<mux-player>`, follow the Mux Player migration guide instead.
+> This guide is for apps that build their own player from Media Chrome elements. If you use Mux Player, follow [Migrate from Mux Player](./migrate-from-mux-player.md) instead.
+
+## AI Quickstart
+
+Paste this prompt into your coding agent:
+
+```
+Migrate this project's Media Chrome player to Video.js v10 for HTML. Use @videojs/html or its CDN bundles for a page without a build step.
+
+Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.
+
+Read the migration guide at https://videojs.org/docs/framework/html/guides/migrate-from-media-chrome, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.
+
+For installation guidance, read https://videojs.org/docs/framework/html/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.
+
+From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.
+
+Choose values for these options:
+- --media and --source-url: the existing content and playback requirements.
+- --method: the installation method.
+- --preset, --skin, and --extensions: the player UI and integrations.
+
+Add those options to `npx @videojs/cli agents init --framework html --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.
+
+After installing a package, switch to node_modules/@videojs/html/docs/llms.txt for documentation matching its version.
+
+Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
+```
 
 ## Before you begin
 
-Install Video.js and choose a [preset](./presets.md) (see [Installation](./installation.md)). Start with its ready-made skin if those controls fit your player. If you need to keep a custom control bar, build it from the individual Video.js UI components instead.
+Check [Known gaps](#known-gaps) for controller options and preferences your app relies on. List your media sources, custom controls, event handlers, and theme rules.
+
+Install Video.js and choose a [preset](./presets.md) (see [Installation](./installation.md)). If the preset’s ready-made skin has the controls you need, start with it. To keep a custom control bar, build it from the individual Video.js UI components instead.
+
+Before loading Video.js HTML, remove every Media Chrome import and CDN script from the page, including any that another component loads. Then reload the page. Both libraries register custom elements with names such as `media-play-button`. A document can hold only one definition per name, and Video.js keeps any definition that already exists. If you need both libraries during migration, load them in separate documents, such as an iframe.
+
+For a page without a bundler, load the CDN video preset. It registers the player, the UI elements and icons used in the controller example below, and the `<media-i18n>` element:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/video.js"></script>
+```
+
+Some elements in the mapping table below need separate bundles. If you use any of these elements, also load its bundle:
+
+- `media-seek-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/ui/seek-button.js`
+- `media-playback-rate-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/ui/playback-rate-button.js`
+- `media-thumbnail`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0/ui/thumbnail.js`
+
+Load each with `<script type="module" src="…"></script>`. See [CDN](./cdn.md) for individual component bundles.
+
+For a bundler installation:
 
 ```bash
 npm install @videojs/html
@@ -18,18 +65,22 @@ npm install @videojs/html
 
 ## Map the controller
 
-Media Chrome wraps a slotted `<video slot="media">` in a single `<media-controller>`. Video.js splits that into two elements. The player owns state and draws nothing. The `<media-container>` is the box everything lives in, with the media as a plain child.
+The examples use the same MP4 source before and after migration. For HLS, DASH, or an embed, keep your existing source and choose its [media component](./media-sources.md).
+
+Media Chrome wraps a slotted `<video slot="media">` in a single `<media-controller>`. Video.js splits that into two elements. The player owns state and renders no UI. The `<media-container>` holds the media and controls. Put the media directly inside the container.
 
 ```html
 <!-- Media Chrome -->
 <media-controller>
-  <video slot="media" src="video.m3u8"></video>
+  <video slot="media" src="video.mp4"></video>
   <media-control-bar>
     <media-play-button></media-play-button>
   </media-control-bar>
 </media-controller>
 ```
 
+Use the HTML and CSS tabs for both installation methods. With a bundler, also add the JavaScript imports. With the CDN video preset, skip those imports because the preset already registers these elements.
+
 **JavaScript**
 
 ```js
@@ -46,13 +97,13 @@ import '@videojs/html/icons/element';
 ```html
 <!-- Video.js -->
 <video-player>
-  <media-container>
-    <video src="video.mp4"></video>
+  <media-container class="app-player-container">
+    <video class="app-player-media" src="video.mp4" playsinline></video>
     <media-controls>
-      <media-controls-content>
+      <media-controls-content class="app-player-controls">
         <media-play-button class="player-play-button">
-          <media-icon class="player-play-icon" name="play"></media-icon>
-          <media-icon class="player-pause-icon" name="pause"></media-icon>
+          <media-icon class="player-play-icon" name="play" aria-hidden="true"></media-icon>
+          <media-icon class="player-pause-icon" name="pause" aria-hidden="true"></media-icon>
         </media-play-button>
       </media-controls-content>
     </media-controls>
@@ -63,7 +114,55 @@ import '@videojs/html/icons/element';
 **CSS**
 
 ```css
-.player-pause-icon {
+.app-player-container {
+  position: relative;
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.app-player-media {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+.app-player-controls {
+  position: absolute;
+  inset-inline: 0;
+  bottom: 0;
+  display: flex;
+  padding: 0.75rem;
+  background: rgb(0 0 0 / 70%);
+}
+
+.app-player-controls:not([data-visible]) {
+  visibility: hidden;
+  pointer-events: none;
+}
+
+.player-play-button {
+  padding: 0.5rem;
+  color: white;
+  cursor: pointer;
+  background: #222;
+  border: 1px solid white;
+  border-radius: 0.25rem;
+}
+
+.player-play-button:focus-visible {
+  outline: 2px solid white;
+  outline-offset: 2px;
+}
+
+.player-play-button media-icon {
+  display: inline-flex;
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+.player-play-button .player-pause-icon {
   display: none;
 }
 
@@ -78,25 +177,25 @@ import '@videojs/html/icons/element';
 
 ## Map controller attributes
 
-Media Chrome configures behavior through `<media-controller>` attributes. Video.js v10 has no single controller element, so these settle into three places:
+Media Chrome configures behavior through `<media-controller>` attributes. Video.js v10 has no single controller element, so these settings move to three places:
 
-- **Player features** — playback behavior that comes from the player’s feature set. A preset picks one for you; `createPlayer` lets you name your own.
+- **Player features** — playback behavior that comes from the player’s feature set. A preset includes a fixed feature set. With `createPlayer`, you choose the feature set.
 - **`<media-container>` and `<media-controls>`** — layout, focus, and autohide.
-- **Dedicated elements** — `<media-hotkey>`, `<media-gesture>`, and friends, declared in markup.
+- **Dedicated elements** — `<media-hotkey>`, `<media-gesture>`, and similar elements, declared in markup.
 
 | Media Chrome attribute | Video.js v10 | How |
 | --- | --- | --- |
 | `audio` | the audio preset | Choose an audio player and audio skin rather than toggling at runtime. |
-| `autohide` | `media-controls` (built in) | Controls auto-hide after inactivity automatically. `autohide="-1"` becomes `visibility="always"` on `media-controls`; the delay is currently fixed, see [Known gaps](#known-gaps). |
+| `autohide` | `media-controls` (built in) | Controls hide after inactivity by default. For `autohide="-1"`, set `visibility="always"` on `media-controls`. The delay is not configurable yet; see [Known gaps](#known-gaps). |
 | `fullscreenelement` | `media-container` | Fullscreen targets the container element. |
-| `gesturesdisabled` | `media-gesture disabled`, or omit | Disable per gesture element, or leave the gestures out. |
-| `nohotkeys` | `media-hotkey disabled`, or omit | Disable per hotkey element, or leave them out. |
+| `gesturesdisabled` | `disabled` on each `media-gesture`, or omit it | Media Chrome disables all gestures at once. In Video.js, set `disabled` on each `media-gesture` or omit it. |
+| `nohotkeys` | `disabled` on each `media-hotkey`, or omit it | Media Chrome disables all hotkeys at once. In Video.js, set `disabled` on each `media-hotkey` or omit it. |
 | `hotkeys="noarrowleft …"` | individual `media-hotkey` | Each shortcut is its own element, so remove the ones you don’t want. |
 | `keyboardforwardseekoffset`, `keyboardbackwardseekoffset` | `value` on `media-hotkey` | Set the signed seek amount per element. |
-| `defaultsubtitles` | `<track default>` for authored tracks | Add `default` to an authored captions or subtitles track. Tracks discovered from a provider or manifest don’t have one generic player-level default flag. |
-| `defaultstreamtype` | `streamType` feature | Partial: derived from the media, with no pre-load default. |
+| `defaultsubtitles` | `<track default>` for authored tracks | Add `default` to an authored captions or subtitles track. For tracks supplied by a provider or manifest, Video.js has no player-level setting that picks the default. |
+| `defaultstreamtype` | `streamType` feature | Partial support. Video.js reads the stream type from the media. You cannot set a default stream type for use before the media loads. |
 | `liveedgeoffset`, `seektoliveoffset` | live media engine | Live-edge behavior lives in the playback engine, not a UI attribute. |
-| `lang` | i18n translator | Localization is configured through the [translator and locale registry](./internationalization.md). |
+| `lang` | `<media-i18n>` | Wrap the player in `<media-i18n lang="…">`. CDN presets register it; with a bundler, import `@videojs/html/i18n`. See [Internationalize the player](./internationalization.md). |
 
 ### Hotkeys
 
@@ -109,11 +208,13 @@ Media Chrome toggles keyboard shortcuts with `nohotkeys` and `hotkeys`. Video.js
 <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
 ```
 
+In a custom layout, put these elements inside the player’s `<media-container>`. With installed skin source, edit its existing hotkey declarations.
+
 To drop a shortcut, remove its element or add `disabled`. There’s no global “all hotkeys off” switch; omit the elements you don’t need.
 
 ### Gestures
 
-`gesturesdisabled` becomes per-element `<media-gesture>` controls. Tap and double-tap behavior — click to toggle play, double-tap to seek or go fullscreen — is declared explicitly:
+Declare each tap or double-tap behavior with a `<media-gesture>` element. For example, declare a tap that toggles playback, or a double-tap that seeks or enters fullscreen:
 
 ```html
 <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
@@ -121,11 +222,13 @@ To drop a shortcut, remove its element or add `disabled`. There’s no global
 <media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>
 ```
 
+In a custom layout, put these elements inside the player’s `<media-container>`. With installed skin source, edit its existing gesture declarations. A packaged skin already declares its own gestures, so do not add duplicates.
+
 Remove an element or set `disabled` to turn a gesture off.
 
 ## Map the elements
 
-Most names match. These are the renames that bite:
+Most names match. Start with these name changes:
 
 | Media Chrome | Video.js v10 | Note |
 | --- | --- | --- |
@@ -133,7 +236,7 @@ Most names match. These are the renames that bite:
 | `media-control-bar` | `media-controls`, `media-controls-group` | grouping |
 | `media-time-range` | `media-time-slider` | “range” becomes “slider” |
 | `media-volume-range` | `media-volume-slider` | “range” becomes “slider” |
-| `media-time-display`, `media-duration-display` | `media-time` | one element, set via attribute |
+| `media-time-display`, `media-duration-display` | `media-time` | one element; set its `type` attribute to choose the value |
 | `media-loading-indicator` | `media-buffering-indicator` | rename |
 | `media-poster-image` | `media-poster` | rename, and the image source moves — see below |
 | `media-seek-backward-button`, `media-seek-forward-button` | `media-seek-button` | one element, direction via signed `seconds` |
@@ -150,9 +253,9 @@ Unchanged names: `media-play-button`, `media-mute-button`, `media-fullscreen-but
 
 Video.js sliders use `media-slider-track`, `media-slider-fill`, and `media-slider-thumb`. See [`media-time-slider`](../reference/components/time-slider.md) and [`media-volume-slider`](../reference/components/volume-slider.md) for copy-paste markup and CSS.
 
-Media Chrome’s named icon slots do not carry over. Remove attributes such as `slot="play"` and put the icon directly inside the Video.js button. Import `@videojs/html/icons/element` to use `<media-icon>`, as shown in [Map the controller](#map-the-controller). Set `family="minimal"` to use the Minimal skin’s icon designs. You can also use your own text or SVG.
+Media Chrome’s named icon slots do not carry over. Remove attributes such as `slot="play"` and put the icon directly inside the Video.js button. With a bundler, import `@videojs/html/icons/element` to use `<media-icon>`; the CDN video preset already registers it. See the example in [Map the controller](#map-the-controller). 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.
 
-`media-poster` is the one rename that changes shape. Where `media-poster-image` took its own `src`, `media-poster` wraps the image you bring:
+`media-poster` also works differently. Where `media-poster-image` took its own `src`, `media-poster` wraps the image you bring:
 
 ```html
 <media-poster>
@@ -162,7 +265,7 @@ Media Chrome’s named icon slots do not carry over. Remove attributes such as `
 
 ## Rewrite your styles
 
-Media Chrome reflects state as `media*` attributes such as `mediapaused`; Video.js uses `data-*`.
+Media Chrome reflects state in attributes such as `mediapaused`. Video.js uses `data-*` attributes such as `data-paused`.
 
 ```css
 /* Media Chrome */
@@ -174,26 +277,34 @@ media-play-button[mediapaused] .play-icon { display: inline; }
 media-play-button[data-paused] .play-icon { display: inline; }
 ```
 
-Continuous values use CSS custom properties: sliders expose `--media-slider-fill` and `--media-slider-pointer`.
+Values that change continuously, such as slider position, use CSS custom properties: sliders expose `--media-slider-fill` and `--media-slider-pointer`.
 
 ### Map theme variables by meaning
 
-Media Chrome and Video.js both use names beginning with `--media-`, but that shared prefix is a naming convention, not a compatibility layer. Keep a variable only when its documented meaning matches.
+Media Chrome and Video.js both use names beginning with `--media-`, but the shared prefix does not make their variables compatible. Keep a variable only when its documented meaning matches.
 
 | Media Chrome theme variable | Packaged Video.js skin | Migration |
 | --- | --- | --- |
 | `--media-accent-color` or `--media-range-bar-color` | `--media-accent-color` | Closest match for slider fills and accented controls. |
-| `--media-primary-color` | no direct equivalent | Often colors every control icon in Media Chrome; Video.js’s accent variable has narrower semantics. |
-| `--media-secondary-color` | no direct equivalent | Add the skin source and author this palette role in your CSS. |
+| `--media-primary-color` | no direct equivalent | Often colors every control icon in Media Chrome; Video.js’s accent variable colors fewer parts of the skin. |
+| `--media-secondary-color` | no direct equivalent | Add the skin source and write CSS for this color. |
 | `--media-control-background` | no direct equivalent | Add the skin source and author the CSS. |
 | `--media-control-hover-background` | no direct equivalent | Add the skin source and author the CSS. |
 | `--media-range-track-height` | no direct equivalent | Add the skin source and author the slider CSS. |
 
-The packaged Video.js skins expose `--media-accent-color`, `--media-accent-text-color`, `--media-border-radius`, and `--media-scale-unit` for broad customization. Do not assume another Media Chrome variable will work because its name starts with `--media-`.
+The packaged Video.js skins expose eight custom properties:
+
+- Colors: `--media-accent-color`, `--media-accent-text-color`, and `--media-border-color`.
+- Corners: `--media-border-radius`.
+- Interface font: `--media-font-family`.
+- Media and poster fit and position: `--media-object-fit` and `--media-object-position`.
+- Control sizing: `--media-scale-unit`.
+
+See [Customize skins](./customize-skins.md#style-a-packaged-skin) for their meanings and defaults. Do not assume another Media Chrome variable will work because its name starts with `--media-`.
 
 ## Themes become skins
 
-Media Chrome’s `<template>`-based themes (`media-theme`) become Video.js [skins](./skins.md) and [presets](./presets.md). Start from a preset, then [add its skin source to your project](./customize-skins.md#style-skin-source), rather than authoring a template.
+Media Chrome’s `<template>`-based themes (`media-theme`) become Video.js [skins](./skins.md) and [presets](./presets.md). Start from a preset, then [add its skin source to your project](./customize-skins.md#style-skin-source).
 
 Ready-made HTML skins keep their controls inside Shadow DOM. Code outside the skin sees a click as coming from the skin, not the button inside it. Some control events also stay inside the skin. Do not use an outside listener to identify which built-in button was clicked.
 
@@ -203,61 +314,81 @@ Keep the skin when its CSS variables and content slots cover your changes. Build
 
 ## Control the player imperatively
 
-Control everything through the player’s store. Media Chrome had no player object; Video.js gives you one, with an action for every operation — `play`, `togglePaused`, `seek`, `setVolume`, `toggleFullscreen` — so one mental model covers playback and the state the browser doesn’t own, such as fullscreen, captions, and quality.
+Use [store actions](../reference/api/player-store.md) such as `play`, `pause`, `seek`, `setVolume`, `requestFullscreen`, and `exitFullscreen` to control playback and UI state.
 
-Hold a reference to the player element and call actions on its store:
+Call actions on the player element’s store only after `player.store.target` is set, which means the media has attached. Fullscreen requests must run from a user interaction:
 
-```js
-const player = document.querySelector('video-player');
-
-player.store.state.toggleFullscreen();
+```html
+<button id="toggle-fullscreen" type="button">Toggle fullscreen</button>
+
+<script type="module">
+  await customElements.whenDefined('video-player');
+  const player = document.querySelector('video-player');
+
+  document.querySelector('#toggle-fullscreen').addEventListener('click', () => {
+    if (!player.store.target) return;
+
+    if (player.store.isFullscreen) {
+      player.store.exitFullscreen();
+    } else {
+      player.store.requestFullscreen();
+    }
+  });
+</script>
 ```
 
-The Media Chrome habit of scripting the media element directly still works, unchanged. The media is a plain child of the player, and Video.js derives player state from the native media events, so `video.play()` or `video.currentTime = 30` never leaves the controls out of sync. The media element also stays the way to swap `src`, replace the media component, and listen for native events.
+Keep native media calls such as `video.play()` and assignments such as `video.currentTime = 30`. Video.js updates player state from media events. Set `src` on the media component to change content, and replace the component when the source needs a different playback engine.
 
 ## Known gaps
 
 These Media Chrome features have no direct equivalent yet. Several can be approximated; see [Workarounds](#workarounds).
 
-- No configurable `autohide` delay and no `autohideovercontrols` ([#1728](https://github.com/videojs/v10/issues/1728)). Disabling autohide (`autohide="-1"`) is covered by `visibility="always"` on the controls component; see [Workarounds](#workarounds).
+- No configurable `autohide` delay and no `autohideovercontrols` ([#1728](https://github.com/videojs/v10/issues/1728)). To disable autohide (`autohide="-1"`), set `visibility="always"` on the controls component; see [Workarounds](#workarounds).
 - No `defaultduration` placeholder before the media loads ([#1729](https://github.com/videojs/v10/issues/1729))
 - Volume and muted preferences are not persisted across sessions, so Media Chrome’s `novolumepref` and `nomutedpref` opt-outs have nothing to opt out of ([#944](https://github.com/videojs/v10/issues/944)). Video.js can choose an initial subtitle track from the locale, but it does not yet remember the viewer’s later language choice ([#1786](https://github.com/videojs/v10/issues/1786)).
 - No `breakpoints` or container-breakpoint attributes; use CSS container queries instead
 - No `seektoliveoffset` or `noautoseektolive` controls, and live-edge offset and tolerance aren’t configurable ([#1730](https://github.com/videojs/v10/issues/1730))
-- Chapters render and each time-slider segment reflects `data-active`, but there’s no player-level active chapter value, `chapterchange` event, or menu to jump between them ([#1873](https://github.com/videojs/v10/issues/1873))
+- Chapters render and each time-slider segment reflects `data-active`, but there’s no player-level active chapter value, `chapterchange` event, or menu for jumping between chapters ([#1873](https://github.com/videojs/v10/issues/1873))
 - Cue points are not supported ([#1442](https://github.com/videojs/v10/issues/1442))
 
-Chapters themselves do work. Add a default `<track kind="chapters">` and the packaged skins segment the time slider and show the chapter title on hover, via `media-time-slider-chapters` and `media-time-slider-chapter-title`.
+Chapters still work. Add a `<track kind="chapters">` with the `default` attribute. The packaged skins then split the time slider into chapter segments and show the chapter title on hover, via `media-time-slider-chapters` and `media-time-slider-chapter-title`.
 
 ## Workarounds
 
 ### Disable autohide (`autohide="-1"`)
 
-Set `visibility="always"` on `media-controls` and the controls stay visible regardless of activity. Packaged skins don’t expose that attribute; to keep a preset skin’s look, [add the skin source to your project](./customize-skins.md#style-skin-source) and set it on the skin’s controls element rather than overriding private selectors.
+Set `visibility="always"` on `media-controls` to keep the controls visible regardless of activity. Packaged skins do not expose this attribute. To keep a packaged skin’s look, [add its source to your project](./customize-skins.md#style-skin-source) and set `visibility="always"` on its controls element.
 
 ### Breakpoints
 
-The skin root is an inline-size container named `media-root`, so write responsive styles with container queries instead of `breakpoints` attributes. This is exactly how the built-in skins adapt:
+For custom UI, add a class to your container and another to the controls you want to change. Define and query your own CSS container:
 
 ```css
-@container media-root (width > 40rem) {
-  .media-controls { /* wide layout */ }
+.app-player-container {
+  container-type: inline-size;
+  container-name: app-player;
+}
+
+@container app-player (width > 40rem) {
+  .app-player-controls { /* your wide layout */ }
 }
 ```
 
+Packaged HTML skin controls are inside Shadow DOM; external selectors cannot reach them. React skin selectors are private. To change a packaged skin’s responsive layout, [add its source to your project](./customize-skins.md#style-skin-source) and edit the container queries in its local styles.
+
 ### Default duration
 
-There’s no player input for a pre-load duration. Use `preload="metadata"`, the default, so the real duration is known almost immediately; only `preload="none"` defers it. If you must defer loading, render your own static placeholder in markup.
+There is no player input for a duration placeholder. Set `preload="metadata"` to request the duration before playback. The duration is available only after the network request and engine loading finish. If you defer loading, render a static placeholder in your own UI.
 
 ### Preference persistence
 
-Media Chrome remembers volume, muted state, and language across sessions. Video.js v10 persists nothing, so restore and save the values yourself.
+Media Chrome remembers volume, muted state, and language across sessions. Video.js does not persist these preferences. Follow [Remember user preferences](./user-preferences.md) to restore and save them in your app.
 
-Work against the store directly: `selectVolume(store.state).setVolume(…)` on init, and `store.subscribe(…)` to save on change.
+Actions throw before the media attaches. Wait until `store.target` is set, restore the saved values, and then start saving changes. For captions or quality, also wait for the relevant track or rendition list before restoring a selection.
 
 ### Live edge offsets
 
-`seektoliveoffset` and `noautoseektolive` are governed by the playback engine rather than the UI layer, so there’s no attribute to tune them today. The escape hatch is a custom live control built against the `selectLive` and `selectTime` player state.
+`seektoliveoffset` and `noautoseektolive` are governed by the playback engine rather than the UI layer, so there’s no attribute to tune them today. As a workaround, build a custom live control that reads player state through `selectLive` and `selectTime`.
 
 ## See also