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

package/docs/guides/build-with-ai.md

@@ -0,0 +1,167 @@
+# Build with AI
+
+Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
+
+The [Video.js skill](https://github.com/videojs/skills) gives coding agents the context they need to build, customize, debug, and migrate Video.js players. It teaches the agent how Video.js 10 is composed, then points it to documentation that matches the version installed in your project.
+
+## AI Quickstart
+
+Paste this prompt into your coding agent:
+
+```
+Install the Video.js skill: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --framework html` to print the version-matched choices and instructions without changing files.
+```
+
+## Video.js Skill
+
+The skill contains guidance and Markdown references. It does not install Video.js, run background services, or connect to an account.
+
+### Install the skill
+
+Follow the steps for your coding agent. To print the same steps in a terminal, run:
+
+**Terminal**
+
+```sh
+npx @videojs/cli agents skills
+```
+
+Add `--agent claude-code,cursor` to print only those agents. `--scope project` or `--scope local` changes the Claude Code installation scope from its `user` default, and `--global` adds `-g` to the `skills` installer command. Like `agents init`, the command only prints instructions.
+
+#### Codex
+
+Add the Video.js plugin marketplace, then install the plugin:
+
+**Terminal**
+
+```sh
+codex plugin marketplace add videojs/skills
+codex plugin add videojs@videojs
+```
+
+Start a new Codex session after installation.
+
+#### Claude Code
+
+Add the Video.js plugin marketplace, then install the plugin:
+
+**Terminal**
+
+```sh
+claude plugin marketplace add videojs/skills
+claude plugin install videojs@videojs
+```
+
+Start a new Claude Code session, or run `/reload-plugins` in the current session.
+
+You can invoke the skill directly with `/videojs:videojs`.
+
+#### VS Code
+
+Enable `chat.plugins.enabled`, run **Chat: Install Plugin From Source** from the Command Palette, and enter:
+
+```text
+https://github.com/videojs/skills
+```
+
+Start a new VS Code session after installation, or reload the window.
+
+#### Cursor
+
+Open **Customize**, select **Plugins**, choose **From GitHub Repository**, and enter:
+
+```text
+https://github.com/videojs/skills
+```
+
+Start a new Cursor session after installation, or reload the window.
+
+#### Other coding agents
+
+Use the open `skills` installer and select your agent when prompted:
+
+**Terminal**
+
+```sh
+npx skills add https://github.com/videojs/skills
+```
+
+Start a new session in your coding agent after installation.
+
+Project-local installation is the default. Add `-g` if you want the skill available in every project.
+
+To skip the prompts, name the agent and confirm up front, for example `npx skills add https://github.com/videojs/skills --agent <agent> --yes`.
+
+### Use the skill
+
+Ask for the player you want to build or the problem you want to solve. For example:
+
+> Add an HLS player with captions and a quality menu to the product page using Video.js.
+
+> Play this Mux playback ID in our Next.js app with Video.js, with Mux Data turned on.
+
+> Migrate this Video.js 8 embed to Video.js 10 in React.
+
+The skill checks your framework and installation method before choosing player, skin, and media code. It also checks imports and playback setup against current documentation before handing the work back.
+
+### How skills find docs
+
+The skill uses documentation in this order:
+
+1. **Version-matched installation instructions.** `npx @videojs/cli agents init` lists valid choices for every framework. Adding flags prints one complete installation plan. When the project already has a different `@videojs/react` or `@videojs/html` version, the plan names the pinned command for that release. The command only returns instructions; it does not prompt, install packages, or write files.
+2. **Installed package docs.** `node_modules/@videojs/react/docs/llms.txt` and `node_modules/@videojs/html/docs/llms.txt` index the docs shipped with each package version. These files work offline and match the code in your project.
+3. **Live docs.** If commands cannot run, the skill reads the relevant [React](https://videojs.org/docs/framework/react/llms.txt) or [HTML](../llms.txt) documentation index, then follows it to the matching installation guide.
+4. **Installed types.** If the docs are unavailable, the skill checks package exports and TypeScript declarations instead of guessing version-specific APIs.
+
+This order matters because most model training data describes Video.js 8. Video.js 10 has a different component model, package structure, and installation flow.
+
+The old `npx @videojs/cli docs` workflow was removed. `@videojs/cli` now contains only `agents init` and `agents skills`, in a single file with no dependencies, so running it does not download the player packages.
+
+### Troubleshoot
+
+If your agent does not use the skill, start a new session or reload plugins, then ask it to use the Video.js skill explicitly. If it writes `videojs()`, `data-setup`, `registerPlugin`, or other Video.js 8 APIs, ask it to read the installed `llms.txt` before changing code.
+
+Report problems with the skill in the [videojs/skills repository](https://github.com/videojs/skills/issues). Report package and documentation problems in [videojs/v10](https://github.com/videojs/v10/issues).
+
+## Use the docs
+
+You can still provide documentation directly when a tool cannot install skills.
+
+### Copy one page
+
+Each docs page has a **Copy page** menu. Copy the Markdown, open the `.md` version, or send the page to ChatGPT or Claude.
+
+### Open a Markdown URL
+
+Add `.md` to any docs URL. For this page, use:
+
+```text
+https://videojs.org/docs/framework/html/guides/build-with-ai.md
+```
+
+Each docs page also advertises its Markdown URL as an alternate format so compatible tools can discover it.
+
+### Request Markdown
+
+Request the normal docs URL with an `Accept: text/markdown` header:
+
+**Terminal**
+
+```sh
+curl -H "Accept: text/markdown" \
+  https://videojs.org/docs/framework/html/guides/build-with-ai
+```
+
+### Start from llms.txt
+
+[`videojs.org/docs/framework/html/llms.txt`](../llms.txt) lists every HTML guide and reference page with a short description. Give the index to your tool, then load only the pages the task needs.
+
+The `llms-full.txt` files contain the complete documentation corpus. Use them only when your tool requires one file because they are larger than most useful task contexts.
+
+## 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
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.

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

@@ -0,0 +1,245 @@
+# Build your own UI component
+
+Create custom player controls that read state, dispatch actions, and stay accessible.
+
+Custom components subscribe to player state and dispatch actions, like built-in controls.
+
+## You might not need a custom component
+
+Before building from scratch, check if an existing approach covers your use case:
+
+- **Restyle a control**: use CSS custom properties and data attributes. See [UI components](./ui-components.md).
+- **Rearrange or remove controls**: add the skin source to your project, then modify it. See [Customize skins](./customize-skins.md#style-skin-source).
+
+Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+## Place your component in the player
+
+Your element needs to be inside [`<video-player>`](../reference/components/player.md) to access state. Place it inside [`<media-container>`](../reference/components/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
+
+```html
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+    <skip-intro-button>Skip intro</skip-intro-button>
+  </video-skin>
+</video-player>
+```
+
+Extend `UIElement` from `@videojs/html` so `PlayerController` can schedule DOM updates when state changes:
+
+```ts
+import { UIElement, PlayerController, playerContext, selectTime, type PropertyValues } from '@videojs/html';
+
+class SkipIntroButtonElement extends UIElement {
+  #player = new PlayerController(this, playerContext, selectTime);
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#player.value;
+  }
+}
+```
+
+If your element starts listeners, observers, or other work, stop it in `disconnectedCallback()` and call the superclass lifecycle methods so inherited cleanup runs too. The browser can connect and disconnect the same element many times.
+
+## Full example
+
+A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
+
+**skip-intro-button.ts**
+
+```ts
+import {
+  UIElement,
+  PlayerController,
+  playerContext,
+  selectTime,
+  selectPlayback,
+  type PropertyValues,
+} from '@videojs/html';
+
+class SkipIntroButtonElement extends UIElement {
+  #time = new PlayerController(this, playerContext, selectTime);
+  #playback = new PlayerController(this, playerContext, selectPlayback);
+  #disconnect: AbortController | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = new AbortController();
+    const { signal } = this.#disconnect;
+
+    this.setAttribute('role', 'button');
+    this.setAttribute('aria-label', 'Skip intro');
+    this.setAttribute('tabindex', '0');
+    this.addEventListener('click', this.#handleActivate, { signal });
+    this.addEventListener('keydown', this.#handleKeydown, { signal });
+    this.addEventListener('keyup', this.#handleKeyup, { signal });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // Removes all listeners registered with this signal
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  update(changed: PropertyValues) {
+    super.update(changed);
+    const time = this.#time.value;
+    const playback = this.#playback.value;
+
+    // Features are configured per-player, so a feature may not be available
+    if (!time || !playback) return;
+
+    const visible = time.currentTime < 30 && !playback.paused;
+    this.toggleAttribute('data-visible', visible);
+    this.setAttribute('tabindex', visible ? '0' : '-1');
+  }
+
+  #handleActivate = () => {
+    this.#time.value?.seek(30);
+  };
+
+  #handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      this.#handleActivate();
+    } else if (event.key === ' ') {
+      // Prevent Space from scrolling the page
+      event.preventDefault();
+    }
+  };
+
+  // ARIA button pattern: Space activates on keyup, not keydown
+  #handleKeyup = (event: KeyboardEvent) => {
+    if (event.key === ' ') {
+      this.#handleActivate();
+    }
+  };
+}
+
+customElements.define('skip-intro-button', SkipIntroButtonElement);
+```
+
+**skip-intro-button.css**
+
+```css
+skip-intro-button {
+  position: absolute;
+  bottom: 5rem;
+  right: 1rem;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 200ms;
+}
+
+skip-intro-button[data-visible] {
+  opacity: 1;
+  pointer-events: auto;
+}
+```
+
+Your element needs to be inside [`<video-player>`](../reference/components/player.md) to access state. Place it inside [`<media-container>`](../reference/components/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4"></video>
+    <skip-intro-button>Skip intro</skip-intro-button>
+  </video-skin>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/skin';
+  import './skip-intro-button.js';
+</script>
+```
+
+## How it works
+
+Custom components read player state and dispatch actions through [features](./features.md). Each feature exposes a set. Here are some features you might reach for first:
+
+| State | Actions | Feature |
+| --- | --- | --- |
+| `paused`, `ended` | `play()`, `pause()` | [Playback](../reference/api/feature-playback.md) |
+| `currentTime`, `duration` | `seek()` | [Time](../reference/api/feature-time.md) |
+| `volume`, `muted` | `setVolume()`, `toggleMuted()` | [Volume](../reference/api/feature-volume.md) |
+| `fullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](../reference/api/feature-fullscreen.md) |
+
+The API reference lists every feature with the state and actions it adds.
+
+Extend `UIElement` from `@videojs/html` so [`PlayerController`](../reference/api/player-controller.md) can schedule DOM updates when state changes, and access state and actions with a feature selector:
+
+```ts
+import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
+
+// Subscribe to a feature — triggers update() when its state changes
+#playback = new PlayerController(this, playerContext, selectPlayback);
+
+// In update():
+const playback = this.#playback.value;
+if (playback?.paused) {
+  playback.play();
+}
+```
+
+Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
+
+Without a selector, `PlayerController` returns the full store without subscribing to changes. Create the controller with the typed context that [`createPlayer`](../reference/api/html-create-player.md) returns — the shared `playerContext` types the store’s members as `unknown` — and guard the value, which stays `undefined` until a player provides the store:
+
+```ts
+import { createPlayer, PlayerController } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { context } = createPlayer({ features: videoFeatures });
+
+#store = new PlayerController(this, context);
+
+// Call any action
+this.#store.value?.play();
+this.#store.value?.setVolume(0.5);
+```
+
+Custom controls also need real button semantics — the examples above set the accessible name, keyboard focus, and (because a custom element is not a native `<button>`) the ARIA button pattern by hand.
+
+- [Learn more about accessibility in video players](./accessibility.md)
+
+## Availability and constraints
+
+- Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
+- Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](./features.md) for details.
+
+## Common variations
+
+Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+### Restyle a control
+
+Use CSS custom properties and data attributes. See [UI components](./ui-components.md).
+
+### Rearrange or remove controls
+
+Add the skin source to your project and modify it. See [Customize skins](./customize-skins.md#style-skin-source).
+
+## Troubleshooting
+
+### State and actions are typed as `unknown`
+
+You’re using the shared `playerContext`, which doesn’t know which features your player has. Use the typed `context` returned by `createPlayer`.
+
+### The component renders but never updates
+
+The element sits outside `<video-player>`, or the class doesn’t extend `UIElement`, so `PlayerController` has nothing to schedule updates on.
+
+## Related pages
+
+### API
+
+- [PlayerController](../reference/api/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [createPlayer](../reference/api/html-create-player.md): Factory function that creates a typed player element and controller for HTML custom elements
+- [media-container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+### Guides
+
+- [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}/bundlers.md

@@ -6,13 +6,13 @@ Before the browser runs your application, a bundler such as Vite combines its im
 
 ## Package exports
 
-Each Video.js package has an `exports` field in its `package.json`. This field lists the import paths that applications and libraries can use, such as `@videojs/html/video/player` and `@videojs/react/live-video`.
+Each Video.js package has an `exports` field in its `package.json`. This field lists the import paths that applications and libraries can use, such as `@videojs/html/video/player` and `@videojs/html/video/skin`.
 
 If an older bundler reports that one of these paths is missing or not exported, upgrade the bundler before adding an alias that bypasses the package’s public API.
 
 ## Vite compatibility
 
-Use a current Vite release. Testing confirmed that Vite 5.4.19 can load Video.js JavaScript and CSS package exports. Vite 3.2.8 can load the JavaScript, but it cannot load an exported stylesheet such as `@videojs/html/video/skin.css`.
+Use Vite 4.1 or later; Video.js has been tested through Vite 8. Earlier versions can’t resolve exported stylesheets such as `@videojs/html/video/skin.css`.
 
 Packaged HTML skins import their own styles, so an HTML application using `@videojs/html/video/skin` doesn’t need to import `skin.css` separately. The CSS limitation matters only when your application imports that stylesheet directly.
 
@@ -26,9 +26,9 @@ Rollup’s array form matches only the exact package name, so `external: ['@vide
 
 Match the package name and everything below it instead:
 
-rollup.config.js
+**rollup.config.js**
 
-```
+```js
 const videojsPeers = ['@videojs/html'];
 
 export default {
@@ -40,4 +40,12 @@ export default {
 };
 ```
 
-Add every `@videojs/*` package your library imports directly to `videojsPeers` and list it in `peerDependencies`.
+Add every `@videojs/*` package your library imports directly to `videojsPeers` and list it in `peerDependencies`.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [TypeScript](./typescript.md): TypeScript version and module resolution requirements for Video.js packages
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments

package/docs/guides/captions.md

@@ -0,0 +1,140 @@
+# Show captions and subtitles
+
+Show captions and subtitles, and let users turn them on and pick a language.
+
+> **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 WebVTT tracks as `<track>` children of the media element, and give users a [`<media-captions-button>`](../reference/components/captions-button.md) to toggle them.
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop>
+      <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srclang="en" label="English" default />
+    </video>
+    <media-captions-button class="media-captions-button">
+      <span class="active">Captions Off</span>
+      <span class="inactive">Captions On</span>
+    </media-captions-button>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.media-captions-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.media-captions-button .active {
+  display: none;
+}
+.media-captions-button .inactive {
+  display: none;
+}
+.media-captions-button[data-active] .active {
+  display: inline;
+}
+.media-captions-button:not([data-active]) .inactive {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/captions-button';
+```
+
+## How it works
+
+The [text track feature](../reference/api/feature-text-tracks.md) mirrors the media element’s `textTracks` into player state:
+
+- `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
+- `subtitlesShowing` is `true` when any caption or subtitle track is showing.
+- `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
+- `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
+
+Tracks don’t have to come from `<track>` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
+
+The browser renders the cues. Style them with the `::cue` pseudo-element.
+
+## Availability and constraints
+
+- Captions availability is `'unavailable'` until the media has at least one caption or subtitle track; caption controls render nothing in that case.
+- Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
+- Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossorigin` on the media element.
+- Track selection UIs identify tracks by `label` and `language`; give every track both.
+- `default` on a `<track>` makes the browser show it initially.
+
+## Common variations
+
+### Language selection menu
+
+For multiple languages, render a menu instead of a toggle.
+
+Use [`<media-captions-radio-group>`](../reference/components/captions-radio-group.md) inside a menu or popover for explicit track selection.
+
+## Troubleshooting
+
+### Captions don’t appear
+
+Confirm that:
+
+- The track `kind` is `captions` or `subtitles`.
+- The VTT file loads (check the network panel for the track request).
+- The track is enabled: `default` on the track element, a `<media-captions-button>` toggle, or `toggleSubtitles(true)`.
+
+### Captions work locally but not in production
+
+The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossorigin` on the media element.
+
+### The selection menu is empty
+
+The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
+
+## Related pages
+
+### Components
+
+- [media-captions-button](../reference/components/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [media-captions-radio-group](../reference/components/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [media-menu](../reference/components/menu.md): A composable menu component for settings, option selection, and actions
+
+### API
+
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+
+### Guides
+
+- [Show timeline thumbnail previews](./thumbnails.md): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player