@videojs/html 10.0.0-rc.2 → 10.0.0-rc.3

package/docs/{how-to/use-picture-in-picture.md → guides/picture-in-picture.md}

@@ -2,25 +2,17 @@
 
 Pop the video into a floating window, with availability detection and state that tracks every entry path.
 
-Pop the video into a floating always-on-top window so it keeps playing while the user does something else.
-
-Note
-
-Using a pre-built [skin](../concepts/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](../concepts/ui-components.md).
+> **Note**
+>
+> 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).
 
 ## Recommended approach
 
-Add a [PiPButton](../reference/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
-
-Exit PiP Enter PiP
-
-index.html
+Add a [`<media-pip-button>`](../reference/components/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
 
-index.css
+**index.html**
 
-index.ts
-
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -31,7 +23,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -68,7 +63,10 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/pip-button';
@@ -76,7 +74,7 @@ import '@videojs/html/ui/pip-button';
 
 ## How it works
 
-The [picture-in-picture feature](../reference/feature-pip.md) puts three things in player state.
+The [picture-in-picture feature](../reference/api/feature-pip.md) puts three things in player state.
 
 `pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
 
@@ -88,12 +86,12 @@ Picture-in-picture and fullscreen are exclusive: requesting one exits the other
 
 ## Availability and constraints
 
-*   Show picture-in-picture controls only when `pipAvailability` is `'available'`. PiPButton handles this for you.
-*   Requests must come from a user gesture; browsers reject requests outside one.
-*   Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
-*   On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
-*   The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
-*   The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
+- Show picture-in-picture controls only when `pipAvailability` is `'available'`. `<media-pip-button>` handles this for you.
+- Requests must come from a user gesture; browsers reject requests outside one.
+- Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
+- On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
+- The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
+- The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
 
 ## Common variations
 
@@ -101,9 +99,7 @@ Picture-in-picture and fullscreen are exclusive: requesting one exits the other
 
 Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
 
-html
-
-```
+```html
 <video-player>
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
@@ -137,15 +133,17 @@ The video has no data yet (wait for it to be ready), the call wasn’t tied to a
 
 Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
 
-## Related components
+## Related pages
+
+### Components
 
-*   [PiP button](../reference/pip-button.md)
+- [media-pip-button](../reference/components/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
 
-## Related API
+### API
 
-*   [Picture-in-picture feature](../reference/feature-pip.md)
+- [Picture-in-picture](../reference/api/feature-pip.md): Picture-in-picture state and actions for the player store
 
-## Related guides
+### Guides
 
-*   [Go fullscreen and lock orientation](./go-fullscreen-and-lock-orientation.md)
-*   [Cast to AirPlay and Chromecast](./cast-to-airplay-and-chromecast.md)
+- [Go fullscreen and lock orientation](./fullscreen.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

package/docs/guides/playback-errors.md

@@ -0,0 +1,129 @@
+# Handle playback errors
+
+Display playback failures, report them, and choose a useful recovery action.
+
+Display playback failures instead of leaving a dead player, report the failure when you need diagnostics, and give users a useful next step.
+
+> **Note**
+>
+> 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).
+
+## Recommended approach
+
+Render a [`<media-error-dialog>`](../reference/components/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+    <media-error-dialog>
+      <media-dialog-popup>
+        <media-dialog-title></media-dialog-title>
+        <media-dialog-description></media-dialog-description>
+        <media-dialog-close></media-dialog-close>
+      </media-dialog-popup>
+    </media-error-dialog>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/ui/error-dialog';
+  import '@videojs/html/ui/dialog-popup';
+  import '@videojs/html/ui/dialog-title';
+  import '@videojs/html/ui/dialog-description';
+  import '@videojs/html/ui/dialog-close';
+</script>
+```
+
+The dialog renders its text into the child parts — a title, the error description, and a dismiss button — and fills each empty part with default copy. Write your own text inside a part to replace the default. Without the child parts, the dialog opens with nothing to show.
+
+## How it works
+
+The [error feature](../reference/api/feature-error.md) mirrors the media element’s error into player state:
+
+- `error` holds the media’s error — `code`, `message` — or `null` when there is none.
+- `dismissError()` clears the error from player state (the media element keeps its own error until a new load).
+- Loading a new source resets `error` to `null` automatically.
+
+The dialog owns presentation, not recovery. Decide the next step in your application: let the user dismiss the message, choose another item, refresh an expired URL, or contact support.
+
+## Availability and constraints
+
+- For a terminal failure, load a new or refreshed source to recover. An aborted load or an adapter-specific error may have different behavior.
+- Standard media error codes distinguish broad classes — aborted, network, decode, and source-not-supported — rather than root causes. A media adapter can report its own numeric code too.
+- Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
+- Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
+
+## Common variations
+
+### Offer an application-specific next step
+
+Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `<media-error-dialog>`; the dialog can close after your application has handled it.
+
+### Report errors to monitoring
+
+Subscribe to error state and forward new errors to your monitoring service with the source URL and `error.code`. A media error does not automatically appear in JavaScript exception monitoring.
+
+Subscribe after the player element has registered. Compare the current error with the previous one because the store also notifies for unrelated state changes:
+
+```ts
+import '@videojs/html/video/player';
+import { selectError } from '@videojs/html';
+
+const player = document.querySelector('video-player');
+if (!player) throw new Error('Missing video-player');
+
+let previousError: { code: number; message: string } | null = null;
+
+function reportNewError() {
+  const error = selectError(player.store.state)?.error ?? null;
+  if (error === previousError) return;
+
+  previousError = error;
+  if (error) console.error('Playback failed', error.code, error.message);
+}
+
+const unsubscribe = player.store.subscribe(reportNewError);
+reportNewError();
+// Call unsubscribe() when this player is removed.
+```
+
+Replace the `console.error` call with your monitoring service and include the current source URL.
+
+### Diagnose a reported failure
+
+Start with `error.code` and the affected source URL. Check the browser’s network panel for failed media requests, response status, redirects, CORS headers, and expired credentials. If requests succeed, check the file’s container and codecs against the chosen media component. For HLS or DASH, inspect the streaming engine’s diagnostics for segment and manifest failures; the player error often names only the final outcome.
+
+## Troubleshooting
+
+### The player is black and silent with no error
+
+Not every dead player is a media error — autoplay blocking and an unset source produce no error. Check `error`, `source`, and `paused` in player state to tell them apart. If `play()` rejects with `NotAllowedError`, see [Autoplay](./autoplay.md).
+
+### A `VJS8_LEGACY_*` exception appears
+
+These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](../reference/api/error-codes.md) for its trigger and v10 equivalent. The player `error` state covered in this guide receives media playback errors after setup.
+
+### Error code says the source isn’t supported
+
+The browser can’t play the format through this media element. HLS in a plain video element outside Safari is the classic case; use the matching streaming media element. See [Media sources](./media-sources.md).
+
+### Reopening the source produces the same error
+
+The failure is probably permanent for that source, such as a 404, revoked token, unsupported codec, or CORS response. Fix or replace the source instead of repeatedly loading the same URL.
+
+## Related pages
+
+### Components
+
+- [media-buffering-indicator](../reference/components/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+
+### API
+
+- [Error](../reference/api/feature-error.md): Media error state and actions for the player store
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Autoplay](./autoplay.md): Start playback automatically and handle browser autoplay restrictions.

package/docs/{how-to/add-a-poster-and-loading-placeholder.md → guides/poster.md}

@@ -4,26 +4,22 @@ Set the image shown before playback, then add a lightweight placeholder while it
 
 A poster is the image shown before your video plays. There are several places to set one, so work down this list and stop at the first step that fits:
 
-1.  **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
-2.  **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
-3.  **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
-4.  **Keep it working in an [ejected skin](./customize-skins.md#eject-and-edit-a-skin).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
+1. **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
+2. **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
+3. **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
+4. **Keep it working after [adding the skin source to your project](./customize-skins.md#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
 
 ## Let the media provide a poster
 
-Some media components choose a poster for you. For example, `MuxVideo` creates one from its playback ID:
+Some media components choose a poster for you. For example, `<mux-video>` creates one from its playback ID:
 
 Install the HTML façade and the Mux playback adapter:
 
-bash
-
-```
+```bash
 pnpm add @videojs/html @videojs/mux-video
 ```
 
-html
-
-```
+```html
 <video-player>
   <video-skin>
     <mux-video
@@ -44,9 +40,7 @@ html
 
 When the media has no poster of its own, set the player’s `poster` to an image URL:
 
-html
-
-```
+```html
 <video-player poster="/poster.jpg">
   <video-skin>
     <video src="/video.mp4" playsinline></video>
@@ -54,9 +48,9 @@ html
 </video-player>
 ```
 
-If you use a ready-made skin, it includes [Poster](../reference/poster.md) and shows the image automatically. If you build your own UI, add Poster yourself. It hides after the user plays or seeks.
+If you use a ready-made skin, it includes [`<media-poster>`](../reference/components/poster.md) and shows the image automatically. If you build your own UI, add `<media-poster>` yourself. It hides after the user plays or seeks.
 
-When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/feature-metadata.md) for how the player combines those values.
+When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/api/feature-metadata.md) for how the player combines those values.
 
 Posters are decorative by default, with an empty `alt`. If the image communicates something that is not available elsewhere, add `alt` text when you customize the poster image.
 
@@ -66,9 +60,7 @@ The packaged skins also accept an image of your own, for when a plain `<img>` is
 
 Add your image to the skin’s `poster` slot. Leave off `src` and Video.js fills in the player’s poster. Provide a `src`, a `srcset`, or `<picture>` sources and Video.js leaves the image alone:
 
-html
-
-```
+```html
 <video-player>
   <video-skin>
     <video src="/video.mp4" playsinline></video>
@@ -88,9 +80,7 @@ A placeholder is a tiny preview that appears while the poster downloads, so a sl
 
 Add an image to the skin’s `poster` slot with the placeholder as its background. Leave off `src`: Video.js adds the poster URL, while the background appears immediately.
 
-html
-
-```
+```html
 <video-player poster="/poster.jpg">
   <video-skin>
     <video src="/video.mp4" playsinline></video>
@@ -105,17 +95,15 @@ html
 
 The examples use `contain` for both images. Use `cover` for both when the poster should fill the player. Keeping the same size and position prevents the image from jumping when the poster appears.
 
-## Set the poster in an ejected skin
+## Set the poster after adding skin source
 
-Ejecting a skin changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [Poster](../reference/poster.md) component your skin renders.
+Adding the skin source to your project changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [`<media-poster>`](../reference/components/poster.md) element your skin renders.
 
 `<media-poster>` fills the `src` of the image inside it. Give that image a `src`, a `srcset`, or `<picture>` sources instead and Video.js leaves it untouched — set the source at this level when the poster should bypass player state entirely.
 
 For a placeholder, put the background on the image inside `<media-poster>`:
 
-html
-
-```
+```html
 <media-poster>
   <img
     alt=""
@@ -142,15 +130,17 @@ Use the same fit for both images: pair `background-size: contain` with `object-f
 
 Use fewer pixels and stronger compression. The placeholder only needs to suggest the poster’s color and shape until the full image appears.
 
-## Related components
+## Related pages
+
+### Components
 
-*   [Poster](../reference/poster.md)
+- [media-poster](../reference/components/poster.md): Poster image component that displays a thumbnail until video playback starts
 
-## Related API
+### API
 
-*   [Metadata](../reference/feature-metadata.md)
+- [Metadata](../reference/api/feature-metadata.md): Resolved title and poster values for the player store
 
-## Related guides
+### Guides
 
-*   [Customize skins](./customize-skins.md#style-a-packaged-skin)
-*   [Build your own UI component](./build-your-own-component.md)
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.

package/docs/{concepts → guides}/presets.md

@@ -6,9 +6,9 @@ A **preset** packages what you need for a specific player use case. It can inclu
 
 For example, the `@videojs/html/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
 
-index.html
+**index.html**
 
-```
+```html
 <script type="module">
   import '@videojs/html/background/player';
   import '@videojs/html/background/video';
@@ -26,121 +26,13 @@ index.html
 
 The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
 
-Import
-
-Description
-
-Details
-
-`@videojs/html/video`
-
-General-purpose video player preset with full playback controls.
-
-▸
-
-Feature bundle
-
-`videoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [quality](../reference/feature-quality.md), [audioTrack](../reference/feature-audio-track.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<video-minimal-skin>`, `<video-skin>`
-
-Default media element
-
-`<video>`
-
-`@videojs/html/audio`
-
-Audio-only player preset with playback and volume controls.
-
-▸
-
-Feature bundle
-
-`audioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<audio-minimal-skin>`, `<audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/background`
-
-Ambient background video preset with no user controls.
-
-▸
-
-Feature bundle
-
-`backgroundFeatures`
-
-Features
-
-–
-
-Skins
-
-`<background-video-skin>`
-
-Default media element
-
-`<background-video>`
-
-`@videojs/html/live-audio`
-
-Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveAudioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-audio-minimal-skin>`, `<live-audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/live-video`
-
-Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveVideoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-video-minimal-skin>`, `<live-video-skin>`
-
-Default media element
-
-`<video>`
+| Import | Description | Details |
+| --- | --- | --- |
+| `@videojs/html/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<video-minimal-skin>`, `<video-skin>`; **Default media element:** `<video>` |
+| `@videojs/html/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<audio-minimal-skin>`, `<audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<background-video-skin>`; **Default media element:** `<background-video>` |
+| `@videojs/html/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-audio-minimal-skin>`, `<live-audio-skin>`; **Default media element:** `<audio>` |
+| `@videojs/html/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<live-video-minimal-skin>`, `<live-video-skin>`; **Default media element:** `<video>` |
 
 ## What’s in a preset
 
@@ -150,9 +42,7 @@ These parts aren’t equally tied together. Skins depend tightly on their featur
 
 HTML preset roots are side-effect-free modules for importing the configured classes, typed controller, and feature bundle:
 
-ts
-
-```
+```ts
 import {
   PlayerController,
   VideoPlayerElement,
@@ -163,9 +53,7 @@ import {
 
 Registration is explicit, so importing a value never changes the custom element registry. Registration entry points are side-effect-only; import classes, controllers, and types from the preset root:
 
-ts
-
-```
+```ts
 import '@videojs/html/video/player'; // <video-player> only
 import '@videojs/html/video/skin';   // <video-skin> + container + video UI
 // Import '@videojs/html/video/minimal-skin' instead for the minimal skin.
@@ -175,15 +63,15 @@ A complete player imports `video/player` and one skin. Each skin registration in
 
 ## Customizing a preset
 
-You can customize a preset in three ways: extend its feature bundle, eject its skin, or swap its media element.
+You can customize a preset in three ways: extend its feature bundle, add its skin source to your project, or swap its media element.
 
 ### Extend the feature bundle
 
 Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
 
-index.html
+**index.html**
 
-```
+```html
 <script type="module">
   import { createPlayer, playbackFeature } from '@videojs/html';
   import { backgroundFeatures } from '@videojs/html/background';
@@ -206,17 +94,15 @@ index.html
 </my-player>
 ```
 
-### Eject the skin
+### Skin source
 
-If a preset’s skin is close but not quite right, [eject it](../how-to/customize-skins.md#eject-and-edit-a-skin) and customize its components and styles.
+If a preset’s skin is close but not quite right, [add its source to your project](./customize-skins.md#style-skin-source) and customize its components and styles.
 
 ### Swap the media element
 
 A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
 
-html
-
-```
+```html
 <video-player>
   <video-skin>
     <hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>