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

package/docs/guides/thumbnails.md

@@ -0,0 +1,183 @@
+# Show timeline thumbnail previews
+
+Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+
+Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
+
+> **Tip: Using Mux?**
+>
+> With [`<mux-video>`](../reference/components/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
+
+> **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 `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [`<media-time-slider>`](../reference/components/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same attributes as the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md).
+
+`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child; set `crossorigin`, `loading`, or `fetchpriority` on the element itself, or on the image you supply. Inside a packaged skin, an `<img slot="thumbnail">` replaces the image the skin carries, so those attributes go on it:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4" crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="storyboard.vtt" default />
+    </video>
+    <img slot="thumbnail" alt="" loading="lazy" fetchpriority="low" />
+  </video-skin>
+</video-player>
+```
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+    </video>
+    <media-time-slider class="media-time-slider">
+      <media-slider-track class="media-slider-track">
+        <media-slider-fill class="media-slider-fill"></media-slider-fill>
+      </media-slider-track>
+      <media-slider-thumbnail class="media-slider-thumbnail"></media-slider-thumbnail>
+    </media-time-slider>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 6px;
+  left: 10px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+/* Reveal the preview over the pointer while it is on the slider. */
+.media-slider-thumbnail {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  max-width: 160px;
+  margin-bottom: 8px;
+  pointer-events: none;
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-thumbnail {
+  opacity: 1;
+}
+
+.media-slider-thumbnail[data-hidden] {
+  display: none;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumbnail';
+```
+
+## How it works
+
+- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/api/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+- The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the example’s CSS uses them to reveal the preview and position it over the pointer.
+- To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md) element with an explicit `time`.
+
+Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
+
+**storyboard.vtt**
+
+```txt
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+storyboard.jpg#xywh=0,0,256,160
+
+00:00:05.000 --> 00:00:10.000
+storyboard.jpg#xywh=256,0,256,160
+```
+
+## Availability and constraints
+
+- Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
+- Cross-origin storyboards need CORS headers, and `crossorigin` on the media element for the track to load.
+- Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
+- Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
+
+## Troubleshooting
+
+### Thumbnails don’t appear while scrubbing
+
+Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossorigin` set on the media element.
+
+### Thumbnails are blurry or slow
+
+Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
+
+## Related pages
+
+### Components
+
+- [media-thumbnail](../reference/components/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [media-slider](../reference/components/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [media-time-slider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+
+### API
+
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+
+### Guides
+
+- [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.

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

@@ -12,9 +12,9 @@ Video.js type files use syntax introduced in TypeScript 5.0. Older versions cann
 
 Video.js packages define their supported import paths using [package exports](./bundlers.md). Most web applications should use the following configuration. It makes TypeScript follow the same package rules as the bundler that builds the application:
 
-tsconfig.json
+**tsconfig.json**
 
-```
+```json
 {
   "compilerOptions": {
     "module": "ESNext",
@@ -31,4 +31,11 @@ Do not use the older `node` setting, now called `node10`. It does not understand
 
 The older `node` setting allowed applications to import almost any file inside a dependency. Modern settings allow only the paths that dependency publishes. Changing the setting can therefore reveal an existing import into another package’s private files.
 
-If the error names a package outside `@videojs/*`, update that dependency or use one of its supported import paths. A TypeScript `paths` override can be a temporary bridge when no supported replacement exists. Do not switch back to the older resolver because that also breaks Video.js type resolution.
+If the error names a package outside `@videojs/*`, update that dependency or use one of its supported import paths. A TypeScript `paths` override can be a temporary bridge when no supported replacement exists. Do not switch back to the older resolver because that also breaks Video.js type resolution.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

package/docs/{concepts → guides}/ui-components.md

@@ -10,11 +10,13 @@ Individual controls provide interaction, accessible names, and state. You add th
 
 ## Where to put your components
 
-UI components can go anywhere inside a [`<video-player>`](../reference/player.md).
+Each `@videojs/html/ui/*` import registers exactly one custom element. Compound components such as controls, sliders, menus, and dialogs need an import for the root and for every part you render, so a `<media-controls-content>` inside `<media-controls>` needs both `ui/controls` and `ui/controls-content`. Without its import, a part stays a plain element and never receives its state attributes. Each reference page lists the imports for its anatomy, and the skin entry points register everything their layout uses.
+
+UI components can go anywhere inside a [`<video-player>`](../reference/components/player.md).
 
 However, you should consider placing your components in `<media-container>`. Components in `<media-container>` will go fullscreen with the player, respond to user activity, and more.
 
-- [Read more about <media-container>](../reference/player-container.md)
+- [Read more about `<media-container>`](../reference/components/player-container.md)
 
 ## Styling and customization
 
@@ -24,15 +26,11 @@ For components you add yourself, select them by their custom element name. Use t
 
 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.
 
-ts
-
-```
+```ts
 import '@videojs/html/icons/element';
 ```
 
-html
-
-```
+```html
 <media-play-button class="my-play-button">
   <media-icon class="play-icon" name="play"></media-icon>
   <media-icon class="pause-icon" name="pause"></media-icon>
@@ -43,9 +41,7 @@ html
 
 Components add `data-*` attributes to describe their current state. For example, a play button adds `data-paused` while the media is paused. Use those attributes in CSS:
 
-css
-
-```
+```css
 .my-play-button .pause-icon {
   display: none;
 }
@@ -69,9 +65,7 @@ Some components also expose **CSS custom properties** for continuous values like
 
 Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each visible part owns at most one element.
 
-html
-
-```
+```html
 <media-volume-slider orientation="vertical">
   <media-slider-track>
     <media-slider-fill></media-slider-fill>

package/docs/{how-to/remember-user-preferences.md → guides/user-preferences.md}

@@ -2,17 +2,13 @@
 
 Persist volume, caption, and quality preferences across sessions by subscribing to player state.
 
-Persist player preferences — volume, muted, captions, quality — so returning users get the setup they left with.
-
 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.
 
 ## Recommended approach
 
 Subscribe to the state you want to remember, write it to storage when it changes, and restore it once the store attaches to the media.
 
-html
-
-```
+```html
 <video-player>
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
@@ -75,20 +71,19 @@ html
 
 ## 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.
-*   In React, `usePlayer(selector)` re-renders only when the selected value changes; pairing it with an effect is the idiomatic save path.
-*   Feature selectors exported by `@videojs/html` and `@videojs/react` (`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.
-*   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.
+- 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.
+- 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.
+- 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.
-*   Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
+- 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.
+- Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
 
 ## Common variations
 
@@ -116,20 +111,22 @@ The track list wasn’t loaded yet when you restored, or you saved a generated t
 
 Notifications batch per microtask, but a drag still produces many ticks. Debounce the write if the churn matters for your storage target.
 
-## Related components
+## Related pages
+
+### Components
 
-*   [Volume slider](../reference/volume-slider.md)
-*   [Captions radio group](../reference/captions-radio-group.md)
-*   [Quality radio group](../reference/quality-radio-group.md)
+- [media-volume-slider](../reference/components/volume-slider.md): A slider component for controlling media playback volume
+- [media-captions-radio-group](../reference/components/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [media-quality-radio-group](../reference/components/quality-radio-group.md): A menu radio group for selecting video quality
 
-## Related API
+### API
 
-*   [usePlayer](/docs/framework/react/reference/use-player)
-*   [useStore](/docs/framework/react/reference/use-store)
-*   [Volume feature](../reference/feature-volume.md)
-*   [Text track feature](../reference/feature-text-tracks.md)
+- [PlayerController](../reference/api/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [StoreController](../reference/api/store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
+- [Volume](../reference/api/feature-volume.md): Volume level and mute state for the player store
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
 
-## Related guides
+### Guides
 
-*   [Show captions and subtitles](./show-captions-and-subtitles.md)
-*   [Add a quality selector](./add-quality-selector.md)
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Add a quality selector](./quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.

package/docs/guides/v10-roadmap.md

@@ -0,0 +1,92 @@
+# v10 Roadmap
+
+Timeline and milestones for Video.js v10 rebuild and the future of v8
+
+Video.js v10 is a complete rebuild from the ground up, designed to be more modular, framework-flexible, and aligned with modern web development practices.
+
+## Current versions
+
+### Version 8
+
+- Maintained with bug fixes and critical security patches only
+- No new features will be planned
+- Community contributions still welcome
+- Documentation available at [legacy.videojs.org](https://legacy.videojs.org)
+
+### Version 9
+
+- Reserved only for urgent API-breaking changes that cannot be avoided
+
+## March 2026: v10 Beta Release
+
+Wider testing release to the community.
+
+### Core feature parity target
+
+- Basic control set (play, pause, seek, volume, fullscreen)
+- Adaptive streaming support via existing community engines
+- No plugin migrations yet, without plugin author contribution
+
+### What to expect
+
+- Close to stable, but API changes are still possible
+- Intended for experimental adoption in real-world projects
+- Developers encouraged to follow the [installation guide](./installation.md), try it out, and report issues
+
+## September 2026: v10 Release Candidate
+
+Feature-complete release ahead of GA.
+
+### What to expect
+
+- Close to stable. Remaining API changes are driven by feedback on the release candidate
+- Intended for adoption in real-world projects
+- Migration guides and reference documentation ready for review
+
+## Fall 2026: v10 GA Release
+
+**Stable release** of Video.js v10
+
+### Feature targets
+
+- 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)
+- Plugin ecosystem migration begins in earnest
+
+### Engine development focus
+
+- Lightweight adaptive streaming
+- MoQ (Media over QUIC) support
+
+## Late-2026: Feature parity with v8 Contrib
+
+**Extended feature parity** with Video.js “contrib” plugins:
+
+- Ads integration
+- Analytics support
+- Further community plugin migration dependent on contributions
+
+## End-of-life plan for Video.js v8
+
+### Mid-2026
+
+- v8/v9 moved to “video.js-legacy” repository and package
+- Documentation preserved at [legacy.videojs.org](https://legacy.videojs.org)
+- Hosted CDN copies will remain available
+
+### 2027 and beyond
+
+- Security patches only
+- Community contributions de-prioritized
+
+---
+
+**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved in the rebuild
+
+## Related pages
+
+### Guides
+
+- [Why Video.js?](./why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls

package/docs/{how-to/use-videojs-with-vue.md → guides/vue.md}

@@ -1,4 +1,4 @@
-# Use Video.js with Vue and Nuxt
+# Vue
 
 Add Video.js to a Vue or Nuxt app
 
@@ -10,9 +10,9 @@ If Vue warns that it cannot resolve a Video.js tag, the compiler is treating tha
 
 For a Vue app built with Vite:
 
-vite.config.ts
+**vite.config.ts**
 
-```
+```ts
 import vue from '@vitejs/plugin-vue';
 import { defineConfig } from 'vite';
 
@@ -33,9 +33,9 @@ export default defineConfig({
 
 For Nuxt:
 
-nuxt.config.ts
+**nuxt.config.ts**
 
-```
+```ts
 const videoJsElements = new Set(['video-player', 'video-skin', 'mux-video']);
 
 export default defineNuxtConfig({
@@ -53,9 +53,7 @@ List only the tags that appear in your templates. Avoid broad rules such as allo
 
 If your Vue component needs to react to player state or call a player action, wait until Vue has mounted `<video-player>`. The React API’s `usePlayer` hook is not part of `@videojs/html`, so use a template ref and subscribe to the element’s store:
 
-vue
-
-```
+```vue
 <script setup lang="ts">
 import type { VideoPlayerElement } from '@videojs/html/video';
 import { onMounted, onUnmounted, ref } from 'vue';
@@ -84,9 +82,7 @@ Use the store for player state and actions. Unsubscribe in `onUnmounted`.
 
 When you need the native event itself, attach a listener to the `<video>`, `<audio>`, or media custom element:
 
-vue
-
-```
+```vue
 <script setup lang="ts">
 function handleLoadedMetadata(event: Event) {
   const media = event.currentTarget as HTMLVideoElement;
@@ -103,9 +99,7 @@ function handleLoadedMetadata(event: Event) {
 
 If you want to hide an element until the browser loads it, use `:defined` in your component’s scoped styles:
 
-vue
-
-```
+```vue
 <style scoped>
 video-skin:not(:defined) {
   visibility: hidden;
@@ -113,7 +107,7 @@ video-skin:not(:defined) {
 </style>
 ```
 
-Scoped styles cannot reach controls inside a packaged skin. Use its CSS custom properties, or [eject the skin](./customize-skins.md#eject-and-edit-a-skin) to change its markup and CSS.
+Scoped styles cannot reach controls inside a packaged skin. Use its CSS custom properties, or [add the skin source to your project](./customize-skins.md#style-skin-source) to change its markup and CSS.
 
 ## Pass objects as properties
 
@@ -121,15 +115,11 @@ If you need to pass structured data, such as a Mux source, an HTML attribute wil
 
 The Mux media ships as its own adapter package, so add it to the HTML installation used by this example:
 
-bash
-
-```
+```bash
 pnpm add @videojs/html @videojs/mux-video
 ```
 
-vue
-
-```
+```vue
 <script setup lang="ts">
 import '@videojs/html/video/player';
 import '@videojs/html/video/skin';
@@ -156,4 +146,11 @@ Use `.prop` explicitly. An ordinary binding or render-function prop can become a
 
 If you use server rendering, keep the element imports from the installation guide static. Nuxt renders the custom-element markup on the server, and the browser upgrades it when the page loads.
 
-If you intentionally keep registration client-only, import the elements from a `.client.ts` plugin and wait for `customElements.whenDefined('video-player')` before reading its store or calling its methods. For custom tag or event types, follow Vue’s [TypeScript guidance for non-Vue custom elements](https://vuejs.org/guide/extras/web-components.html#non-vue-web-components-and-typescript).
+If you intentionally keep registration client-only, import the elements from a `.client.ts` plugin and wait for `customElements.whenDefined('video-player')` before reading its store or calling its methods. For custom tag or event types, follow Vue’s [TypeScript guidance for non-Vue custom elements](https://vuejs.org/guide/extras/web-components.html#non-vue-web-components-and-typescript).
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation-vue.md): Install Video.js with Vue in Vite, Astro, or Nuxt and build a player with HTML custom elements
+- [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions

package/docs/{concepts → guides}/why-videojs.md

@@ -8,24 +8,38 @@ Let’s dig into when you’d want to use Video.js, starting with the question w
 
 ## Why not `<video>`?
 
-The native `<video>` tag is great if you can describe your video as an image with a play button. Past that, the gaps show up quickly.
+The native `<video>` tag is enough for a short clip that plays without controls. Once viewers control playback, the gaps show up quickly.
 
 ### Cross-browser inconsistency
 
 Chrome, Safari, and Firefox each render the default `<video>` controls differently. You can hide them, but you can’t deeply style or rearrange them. Building UI that matches your product means starting from scratch.
 
-![Chrome's default video controls](/_astro/chrome-default-controls.D2ybhMTL.png)
+![Chrome's default video controls](https://videojs.org/_astro/chrome-default-controls.D2ybhMTL.png)
 
 Chrome
 
-![Safari's default video controls](/_astro/safari-default-controls.CPUt6ekS.png)
+![Safari's default video controls](https://videojs.org/_astro/safari-default-controls.CPUt6ekS.png)
 
 Safari
 
-![Firefox's default video controls](/_astro/firefox-default-controls.CYiJeU98.png)
+![Firefox's default video controls](https://videojs.org/_astro/firefox-default-controls.CYiJeU98.png)
 
 Firefox
 
+### Accessibility
+
+The browser’s controls bring their own accessibility behavior, and it differs by browser. Once you replace them, accessibility is your job: ARIA roles and labels that follow player state, keyboard controls and shortcuts, focus management, screen reader announcements when playback changes, controls that work with touch, tooltips and menus that stay on screen, and respect for reduced-motion and contrast preferences. Video.js components and skins handle these by default, following the WAI-ARIA Authoring Practices.
+
+- [Learn more about accessibility](./accessibility.md)
+
+### Player state
+
+Custom controls need to know what the media is doing. Even something as simple as “playing” or “buffering” comes from several events, behaves differently across browsers, streaming engines, and services like YouTube, and has to reset when the source changes. Wiring that by hand is fragile, and in React it quickly leads to tangled effects and extra renders.
+
+Video.js keeps playback state in one player store that every component reads. Components reflect state as data attributes such as `data-paused`, so your CSS follows the player without extra code, and controls a browser can’t support, such as picture-in-picture, hide themselves. In React, `usePlayer` with a selector re-renders a component only when the state it selects changes.
+
+- [Learn more about the architecture](./architecture.md)
+
 ### Video interactions
 
 Video often involves more than an MP4 in `src`. Features like thumbnail previews, adaptive bitrate, quality selection, chapters, audio track switching, localized controls, error UI, live-streaming UI, AirPlay, and DRM are *possible* with the video element, but require complex wiring and careful work on maintainability and [accessibility](./accessibility.md).
@@ -50,9 +64,7 @@ Let’s dig into some of the design principles that help explain why we built Vi
 
 Most player libraries ship every feature in one bundle, so you carry code you don’t run. If your video doesn’t need a feature like DRM, why ship that code? Video.js turns features into independent, *composable* modules. You hand `createPlayer` the array you actually want, and what you don’t import doesn’t ship.
 
-ts
-
-```
+```ts
 import { createPlayer, playbackFeature, timeFeature } from '@videojs/html';
 
 const { PlayerElement, PlayerController } = createPlayer({
@@ -72,11 +84,9 @@ Many player libraries wrap a single web component for every framework. That work
 
 The player feels like the rest of your app.
 
-React
-
-HTML
+**React**
 
-```
+```tsx
 import { VideoPlayer, Video, VideoSkin } from '@videojs/react/video';
 import '@videojs/react/video/skin.css';
 
@@ -91,7 +101,9 @@ function MyPlayer() {
 }
 ```
 
-```
+**HTML**
+
+```html
 <script type="module">
   import '@videojs/html/video/player';
   import '@videojs/html/video/skin';
@@ -104,16 +116,23 @@ function MyPlayer() {
 </video-player>
 ```
 
-### Eject and own
+### Source you can change
 
-Most player libraries draw a line between “configurable through props” and “fork the source.” Cross the line and you’re on your own. Video.js lets you eject any skin and walk away with the source: components in your framework’s language that you can read and change. The skin you ship is yours; the rest of the player keeps working underneath it.
+Most player libraries draw a line between “configurable through props” and “fork the source.” Cross the line and you’re on your own. Video.js lets you add the files for any skin to your project: components in your framework’s language that you can read and change. The rest of the player keeps working underneath it.
 
-We don’t want to cram every possible player into one configuration API. Packaged skins cover common visual changes. For everything else, eject early and compose the UI you need.
+We don’t want to cram every possible player into one configuration API. Packaged skins cover common visual changes. For everything else, add the skin source to your project and compose the UI you need.
 
-- [Customize skins](../how-to/customize-skins.md#eject-and-edit-a-skin)
+- [Customize skins](./customize-skins.md#style-skin-source)
 
 ### AI-native DX
 
 Documentation aimed at human readers usually doesn’t help an agent. Video.js publishes an `llms.txt` index, ships every docs page as both HTML and Markdown, and has a dedicated guide for building with AI assistants. Drop the player into a Claude or Cursor session and the docs come along for the ride.
 
-- [Build with AI](../how-to/build-with-ai.md)
+- [Build with AI](./build-with-ai.md)
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Architecture](./architecture.md): How Video.js players are structured — state, UI, media, and extensions