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

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

@@ -4,17 +4,13 @@ The state and actions each feature adds to the player
 
 Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
 
-## Using features
-
-### Feature bundles and presets
+## Feature bundles and presets
 
 You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
 
 For example, if you import `<video-player>` from the `/video` path, you will have playback, volume, time, fullscreen, and more already enabled.
 
-html
-
-```
+```html
 <script type="module">
   import '@videojs/html/video/player';
   import '@videojs/html/video/skin';
@@ -30,13 +26,11 @@ Feature bundles are usually paired with specific skins and media elements in a *
 
 - [Learn more about presets](./presets.md)
 
-### Create a player with individual features
+## Individual features
 
 If you’re not using presets, you can create a player that has individual features.
 
-ts
-
-```
+```ts
 import { controlsFeature, createPlayer, playbackFeature, timeFeature, volumeFeature } from '@videojs/html';
 
 const { PlayerElement: MyPlayer } = createPlayer({
@@ -46,13 +40,11 @@ const { PlayerElement: MyPlayer } = createPlayer({
 customElements.define('my-player', MyPlayer);
 ```
 
-### Extending a feature bundle
+## Extended feature bundles
 
 Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
 
-ts
-
-```
+```ts
 import { createPlayer, playbackFeature } from '@videojs/html';
 import { backgroundFeatures } from '@videojs/html/background';
 
@@ -63,13 +55,11 @@ const { PlayerElement: MyPlayer } = createPlayer({
 customElements.define('my-player', MyPlayer);
 ```
 
-### Access features in components
-
-You can access feature state and actions through [`PlayerController`](../reference/player-controller.md) and pre-built feature selectors (e.g. [`selectPlayback`](../reference/feature-playback.md), [`selectVolume`](../reference/feature-volume.md)):
+## Features inside components
 
-ts
+You can access feature state and actions through [`PlayerController`](../reference/api/player-controller.md) and pre-built feature selectors (e.g. [`selectPlayback`](../reference/api/feature-playback.md), [`selectVolume`](../reference/api/feature-volume.md)):
 
-```
+```ts
 import { selectPlayback } from '@videojs/html';
 
 // Subscribe to feature state (triggers element updates on change)
@@ -80,38 +70,26 @@ const media = this.#playback.value;
 if (media?.paused) media.play();
 ```
 
-### Checking for feature support
+## Feature availability
 
 Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
 
-Value
-
-Meaning
+| Value | Meaning |
+| --- | --- |
+| `'available'` | Ready to use |
+| `'unavailable'` | Could work, not ready yet |
+| `'unsupported'` | Platform can never do this |
 
-`'available'`
+Components that depend on availability (like [`<media-mute-button>`](../reference/components/mute-button.md), [`<media-pip-button>`](../reference/components/pip-button.md), and [`<media-fullscreen-button>`](../reference/components/fullscreen-button.md)) handle the three states for you:
 
-Ready to use
-
-`'unavailable'`
-
-Could work, not ready yet
-
-`'unsupported'`
-
-Platform can never do this
-
-Components that depend on availability (like [`MuteButton`](../reference/mute-button.md), [`PiPButton`](../reference/pip-button.md), and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
-
-*   **`unsupported`** — the HTML custom element receives the native `hidden` attribute (and `data-hidden`); React buttons return `null`. No CSS needed.
-*   **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
-*   **`disabled` prop** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
-*   **`available`** — fully interactive.
+- **`unsupported`** — the element receives the native `hidden` attribute (and `data-hidden`). No CSS needed.
+- **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
+- **`disabled` attribute** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
+- **`available`** — fully interactive.
 
 Use `data-disabled` to style the non-interactive state:
 
-css
-
-```
+```css
 media-pip-button[data-disabled] {
   opacity: 0.5;
   cursor: not-allowed;
@@ -120,9 +98,7 @@ media-pip-button[data-disabled] {
 
 You can also check availability in JS:
 
-ts
-
-```
+```ts
 const media = this.#pip.value;
 
 if (media?.pipAvailability !== 'available') {

package/docs/guides/fullscreen.md

@@ -0,0 +1,145 @@
+# Go fullscreen and lock orientation
+
+Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+
+> **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 [`<media-fullscreen-button>`](../reference/components/fullscreen-button.md) inside the player container. It requests fullscreen on the container, so everything inside it — controls, captions, overlays — stays visible in the fullscreen presentation.
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <media-fullscreen-button class="media-fullscreen-button">
+      <span class="fullscreen">Exit Fullscreen</span>
+      <span class="not-fullscreen">Fullscreen</span>
+    </media-fullscreen-button>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player media-container video {
+  width: 100%;
+}
+
+.media-fullscreen-button {
+  position: absolute;
+  right: 10px;
+  bottom: 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-fullscreen-button .fullscreen {
+  display: none;
+}
+.media-fullscreen-button .not-fullscreen {
+  display: none;
+}
+.media-fullscreen-button[data-fullscreen] .fullscreen {
+  display: inline;
+}
+.media-fullscreen-button:not([data-fullscreen]) .not-fullscreen {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/fullscreen-button';
+```
+
+## How it works
+
+The [fullscreen feature](../reference/api/feature-fullscreen.md) tracks fullscreen state and provides the actions:
+
+- `fullscreen` is `true` while the player is fullscreen, from any path — your button, native controls, or the platform presentation.
+- `fullscreenAvailability` is `'available'`, `'unavailable'`, or `'unsupported'`. It starts as `'unavailable'`, then settles to `'available'` or `'unsupported'` when the feature attaches to a media element.
+- `requestFullscreen()`, `exitFullscreen()`, and `toggleFullscreen()` change the presentation. Requests target the player container when the Fullscreen API is available, falling back to the media element’s native presentation otherwise.
+
+Fullscreen and picture-in-picture are exclusive: requesting fullscreen exits an active picture-in-picture presentation first.
+
+Style fullscreen state through the container’s `:fullscreen` pseudo-class, or through the `fullscreen` state in components.
+
+## Availability and constraints
+
+- Fullscreen requests must come from a user gesture; browsers reject requests outside one.
+- iPhone Safari has no element Fullscreen API. The player falls back to the video’s native fullscreen presentation, which shows the system player UI instead of your custom controls. iPads support element fullscreen.
+- Orientation locking requires the Screen Orientation API with lock support — in practice, Android browsers in fullscreen. iOS doesn’t support programmatic orientation lock.
+- Inside iframes, fullscreen needs `allow="fullscreen"` on the embedding iframe.
+
+## Common variations
+
+### Lock orientation while fullscreen
+
+Add `orientationLockFeature` to lock screen orientation while the player is fullscreen. It isn’t part of `videoFeatures`, so the preset `<video-player>` doesn’t include it. It locks to `landscape` by default and unlocks on exit.
+
+Compose a player with `orientationLockFeature` in its feature list through [`createPlayer`](../reference/api/html-create-player.md); the prebuilt `<video-player>` element doesn’t include it.
+
+To lock to something other than `landscape`, set the `orientation-lock-type` attribute on the player. See the [orientation lock feature](../reference/api/feature-orientation-lock.md) reference for details.
+
+### Double-click to toggle
+
+Use the `<media-gesture>` element — the default skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.
+
+```html
+<media-gesture type="doubletap" action="toggleFullscreen" region="center"></media-gesture>
+<script type="module">
+  import '@videojs/html/ui/gesture';
+</script>
+```
+
+`region="center"` keeps the gesture off the left and right thirds, which the default skins reserve for double-tap seeking. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md) for the full gesture surface.
+
+## Troubleshooting
+
+### The fullscreen request is rejected
+
+The request didn’t come from a user gesture, fullscreen is unsupported, or an embedding iframe lacks `allow="fullscreen"`.
+
+### Custom controls disappear in fullscreen on iPhone
+
+Expected: iPhone Safari uses the native video presentation, which replaces custom UI with system controls. Design mobile controls assuming this fallback.
+
+### Orientation doesn’t lock
+
+Orientation lock works in fullscreen on Android browsers; iOS doesn’t support it. Confirm `orientationLockFeature` is in your feature list.
+
+## Related pages
+
+### Components
+
+- [media-fullscreen-button](../reference/components/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [media-container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+### API
+
+- [Fullscreen](../reference/api/feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Orientation lock](../reference/api/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
+
+### Guides
+
+- [Use picture-in-picture](./picture-in-picture.md): Pop the video into a floating window, with availability detection and state that tracks every entry path.

package/docs/guides/installation-cdn.md

@@ -0,0 +1,164 @@
+# CDN Installation Guide
+
+Load Video.js from jsDelivr and build an HTML video player without installing Video.js packages
+
+Video.js can run directly from browser-ready files on jsDelivr. This HTML-only path does not install Video.js packages: choose a player, load its scripts, and add the generated custom-element markup to your page.
+
+> **Note: Release Candidate**
+>
+> Video.js v10 is a *release candidate*. We feel the API is stable and ready to build with. With your [feedback](https://github.com/videojs/v10/issues), a few documentation updates, and any final fixes, we look forward to shipping 10.0.0 soon. [Read the Release Candidate blog post](https://videojs.org/blog/videojs-v10-release-candidate).
+
+> **Tip: Coming from another player?**
+>
+> Follow the migration guide for [Video.js 8](./migrate-from-video-js-8.md), [Mux Player](./migrate-from-mux-player.md), [Plyr](./migrate-from-plyr.md), or [Media Chrome](./migrate-from-media-chrome.md). Each maps your existing setup onto Video.js v10 instead of starting from scratch.
+
+## 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 for this project. When installation details are needed, run `npx @videojs/cli agents init --method cdn --framework html` to print the version-matched choices and instructions without changing files.
+```
+
+## Installation options for coding agents
+
+The web Markdown page contains the default installation. Add the query parameters below to its `.md` URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.
+
+This page fixes the installation method to `cdn` and the framework to `html`.
+
+```sh
+npx @videojs/cli agents init
+```
+
+### Query parameters
+
+- `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
+- `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
+- `skin`: The visual skin. Minimal has cleaner surfaces and the same controls as Default. Values: `default`, `minimal`, `none`. Default: default. Applies when preset is not background-video.
+- `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
+- `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
+- `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
+- `package-manager`: The command runner used for app setup, packages, Shadcn, and the development server. Values: `npm`, `pnpm`, `yarn`, `bun`. Default: pnpm. Applies when method is not cdn with template none.
+- `template`: The app setup and file layout. CDN defaults to `none` for an existing page and `vite` for a new app. Values: `vite`, `none`. Default: none.
+
+Run the command above without flags to see the corresponding CLI flags for every framework.
+
+### Decide in this order
+
+1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
+2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
+3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses minimal; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
+6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
+7. **Choose how to install.** This guide uses CDN scripts for plain HTML. Use an existing page when one is available, and scaffold a minimal Vite app only when no app exists.
+8. **Return one explicit plan.** Confirm the choices once, then pass every applicable query parameter, including `extensions=none` when no extension is needed and `source-url=demo` when there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.
+
+### Compatible media sources by preset
+
+- `video`: `html5-video`, `hls`, `dash`, `mux-video`, `vimeo`, `youtube`, `cloudflare`, `tiktok`, `twitch`
+- `audio`: `html5-audio`, `mux-audio`, `spotify`
+- `live-video`: `hls`, `mux-video`
+- `live-audio`: `mux-audio`
+- `background-video`: `background-video`, `hls-background-video`, `mux-background-video`
+
+### App setup by framework
+
+- `html`: templates `vite`, `none`
+
+### Installation pages
+
+- [Packaged modules: React](https://videojs.org/docs/guides/installation/react.md)
+- [Packaged modules: HTML](./installation.md)
+- [Packaged modules: Vue](./installation-vue.md)
+- [Packaged modules: Svelte](./installation-svelte.md)
+- [Editable Shadcn source: React source](https://videojs.org/docs/guides/installation/shadcn.md?framework=react)
+- [Editable Shadcn source: HTML source](./installation-shadcn.md)
+- [CDN: HTML from jsDelivr](./installation-cdn.md)
+
+## Selected options
+
+- `method`: `cdn`
+- `framework`: `html`
+- `project`: `existing`
+- `preset`: `video`
+- `skin`: `default`
+- `media`: `html5-video`
+- `extensions`: `none`
+- `source-url`: `https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4`
+- `template`: `none`
+
+Defaulted options: project, preset, skin, source-url, media, extensions, template.
+
+## Reproduce or change these instructions
+
+```sh
+npx @videojs/cli@10.0.0-rc.3 agents init --method cdn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --template none
+```
+
+## Load Video.js
+
+Add these module scripts to the page head. Module scripts are deferred, so they wait for the page.
+
+### `index.html` (head)
+
+_Merge this into the page `<head>`._
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+```
+
+## Add your player
+
+Add this markup inside the page body where the player should appear.
+
+### `index.html` (body)
+
+_Merge this into the page `<body>` where the player should appear._
+
+```html
+<!--
+  The player element owns and shares state between the UI
+  components and Media. Put layout on the skin or container.
+ -->
+<video-player>
+  <!--
+    Skins contain the entire player UI and are easily swappable.
+    Add the skin source to your project for full control over its
+    UI components.
+   -->
+  <video-skin style="display: block; width: 100%; aspect-ratio: 16 / 9;">
+    <!--
+        Media are players without UIs, handling networking
+        and display of the media. They are easily swappable
+        to handle different sources.
+      -->
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
+  </video-skin>
+</video-player>
+```
+
+> These are instructions only. Review and run the commands in your project; no files were modified.
+
+That’s it! You now have a working Video.js player without installing Video.js packages.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](./installation-shadcn.md): Add editable skin source and build a working React or HTML player
+
+## Choose what to do next
+
+### Customize
+
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Change colors, typography, sizing, and poster presentation
+- [Install with Shadcn](./installation-shadcn.md): Add editable skin source and build a working React or HTML player
+- [Internationalize the player](./internationalization.md): Load another locale or add your own translations
+
+### Deploy
+
+- [CDN files and URLs](./cdn.md): Understand CDN URLs, bundles, stylesheets, locales, and shared chunks
+- [Browser support](./browser-support.md): Check supported browsers and rendering environments
+- [Content Security Policy](./content-security-policy.md): Configure Content Security Policy for your player
+- [Self-host the player](./self-hosting.md): Serve the player from your own origin for offline or restricted-network deployments