@videojs/react 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/concepts/presets.md

@@ -0,0 +1,230 @@
+# Presets
+
+Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+
+A **preset** packages what you need for a specific player use case. It can include special [state management](./features.md), one or more [skins](./skins.md) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
+
+For example, the `@videojs/react/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:
+
+App.tsx
+
+```
+import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';
+import '@videojs/react/background/skin.css';
+
+function Hero() {
+  return (
+    <BackgroundVideoPlayer>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </BackgroundVideoPlayer>
+  );
+}
+```
+
+## Available presets
+
+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/react/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
+
+`<MinimalVideoSkin>`
+
+`import '@videojs/react/video/minimal-skin.css';`
+
+`<VideoSkin>`
+
+`import '@videojs/react/video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+`@videojs/react/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
+
+`<MinimalAudioSkin>`
+
+`import '@videojs/react/audio/minimal-skin.css';`
+
+`<AudioSkin>`
+
+`import '@videojs/react/audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/background`
+
+Ambient background video preset with no user controls.
+
+▸
+
+Feature bundle
+
+`backgroundFeatures`
+
+Features
+
+–
+
+Skins
+
+`<BackgroundVideoSkin>`
+
+`import '@videojs/react/background/skin.css';`
+
+Default media element
+
+`<BackgroundVideo>`
+
+`@videojs/react/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
+
+`<MinimalLiveAudioSkin>`
+
+`import '@videojs/react/live-audio/minimal-skin.css';`
+
+`<LiveAudioSkin>`
+
+`import '@videojs/react/live-audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/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
+
+`<MinimalLiveVideoSkin>`
+
+`import '@videojs/react/live-video/minimal-skin.css';`
+
+`<LiveVideoSkin>`
+
+`import '@videojs/react/live-video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+## What’s in a preset
+
+Each React preset exports a named, preconfigured player component and typed `usePlayer` hook, plus the building blocks needed to customize or eject from it:
+
+*   **Player** — A player component named for the preset, such as `VideoPlayer`, already configured with the preset’s feature bundle.
+*   **Typed hook** — A `usePlayer` hook whose state and actions match the preset.
+*   **Feature bundle** — An array of [features](./features.md) that define the player’s state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
+*   **Skins** — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn’t.
+*   **Media element** — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.
+
+These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
+
+## Customizing a preset
+
+You can customize a preset in three ways: extend its feature bundle, eject its skin, 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:
+
+App.tsx
+
+```
+import { Container, createPlayer, playbackFeature, PlayButton } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
+
+const { Player } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+function Hero() {
+  return (
+    <Player>
+      <Container>
+        <BackgroundVideo src="hero.mp4" />
+        <PlayButton />
+      </Container>
+    </Player>
+  );
+}
+```
+
+### Eject the skin
+
+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.
+
+### 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:
+
+tsx
+
+```
+<VideoPlayer>
+  <VideoSkin>
+    <HlsJsVideo src="https://example.com/stream.m3u8" />
+  </VideoSkin>
+</VideoPlayer>
+```

package/docs/concepts/security.md

@@ -0,0 +1,32 @@
+# Security
+
+How to configure Content Security Policy for your video player
+
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+
+## Allow player resources
+
+*   `media-src` must allow your media URLs.
+*   `img-src` must allow any poster or thumbnail image URLs.
+*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+*   `worker-src blob:` is required when using the `hls.js` player variants.
+*   `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
+
+## Example
+
+http
+
+```
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.

package/docs/concepts/skins.md

@@ -0,0 +1,216 @@
+# Skins
+
+Packaged player designs that include both UI components and their styles.
+
+New in version 10
+
+In prior versions of Video.js, skins were CSS-only themes applied to the same set of default controls. In version 10 the concept of skins has been expanded to include the UI components, so each skin can be completely unique and only include the UI components it needs.
+
+A skin wraps the media component and provides the player’s complete interface. It combines a specific set of UI components with the styles that arrange and present them.
+
+## Packaged and ejected skins
+
+When you choose a skin you have two options for how you use it: **packaged** or **ejected**. It’s usually easiest to start with a packaged skin and later eject its internal components into your project when you need more customization.
+
+Packaged skins cover common visual changes through documented CSS custom properties. Packaged video skins also let you replace the poster. When you need more than that, eject the skin and change the components and styles directly.
+
+Packaged skin
+
+Ejected skin
+
+Single component
+
+Many UI components
+
+Documented CSS custom properties
+
+Components and styles you own
+
+Future design updates auto-applied by bumping the version
+
+Future design updates manually applied, or intentionally ignored
+
+### Packaged skin
+
+Player.tsx
+
+```
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/skin.css';
+
+export function Player() {
+  return (
+    <VideoPlayer>
+      <VideoSkin>
+        <Video src="video.mp4" />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+Don’t depend on elements, class names, or undocumented custom properties inside a packaged skin. They may change between releases.
+
+- [Style a packaged skin](../how-to/customize-skins.md#style-a-packaged-skin)
+
+### Ejected skin
+
+An ejected skin is the same skin as app code that you own. Its UI components and styles become files in your project, so you can add, remove, rearrange, or restyle any part of it.
+
+- [Eject and edit a skin](../how-to/customize-skins.md#eject-and-edit-a-skin)
+
+### Custom interface
+
+You can also build an interface without starting from a skin. In that model, you choose and arrange individual [UI components](./ui-components.md) around the media. This takes more work, but it avoids inheriting a skin’s layout and interactions.
+
+- [Build your own component](../how-to/build-your-own-component.md)
+
+## Skins, features, and presets
+
+Each skin is built with specific [features](./features.md) in mind. For example, a video skin renders fullscreen and picture-in-picture controls. An audio skin doesn’t.
+
+You’ll find a preconfigured player, its typed hook, a skin, and the matching feature bundle exported from the same path. We call these paths **presets**.
+
+Import
+
+Description
+
+Details
+
+`@videojs/react/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
+
+`<MinimalVideoSkin>`
+
+`import '@videojs/react/video/minimal-skin.css';`
+
+`<VideoSkin>`
+
+`import '@videojs/react/video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+`@videojs/react/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
+
+`<MinimalAudioSkin>`
+
+`import '@videojs/react/audio/minimal-skin.css';`
+
+`<AudioSkin>`
+
+`import '@videojs/react/audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/background`
+
+Ambient background video preset with no user controls.
+
+▸
+
+Feature bundle
+
+`backgroundFeatures`
+
+Features
+
+–
+
+Skins
+
+`<BackgroundVideoSkin>`
+
+`import '@videojs/react/background/skin.css';`
+
+Default media element
+
+`<BackgroundVideo>`
+
+`@videojs/react/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
+
+`<MinimalLiveAudioSkin>`
+
+`import '@videojs/react/live-audio/minimal-skin.css';`
+
+`<LiveAudioSkin>`
+
+`import '@videojs/react/live-audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/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
+
+`<MinimalLiveVideoSkin>`
+
+`import '@videojs/react/live-video/minimal-skin.css';`
+
+`<LiveVideoSkin>`
+
+`import '@videojs/react/live-video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+- [Read about presets](./presets.md)

package/docs/concepts/typescript.md

@@ -0,0 +1,34 @@
+# TypeScript
+
+TypeScript version and module resolution requirements for Video.js packages
+
+Video.js packages require **TypeScript 5.0 or newer**. TypeScript must also follow the import paths that each package publishes.
+
+## TypeScript version
+
+Video.js type files use syntax introduced in TypeScript 5.0. Older versions cannot read that syntax. The `skipLibCheck` option does not help because TypeScript must read a type file before it can skip checking it.
+
+## Module resolution
+
+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
+
+```
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+If Node.js runs files emitted directly by TypeScript, use `node16` for both `module` and `moduleResolution`, or use `nodenext` for both.
+
+Do not use the older `node` setting, now called `node10`. It does not understand package exports and can report valid Video.js imports or types as missing.
+
+## Errors from other dependencies
+
+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.

package/docs/concepts/ui-components.md

@@ -0,0 +1,90 @@
+# UI components
+
+How Video.js UI components use focused elements, data attributes for state, and compound composition.
+
+UI components are controls like buttons, sliders, and time displays.
+
+Visible UI components render at most one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you. State-only components render no markup, and controls can skip rendering when their feature is unavailable.
+
+Individual controls provide interaction, accessible names, and state. You add their visible text or icons and CSS. Sliders also need the child elements and styles shown on their reference pages.
+
+## Where to put your components
+
+UI components can go anywhere inside a [`<Player>`](../reference/player.md).
+
+However, you should consider placing your components in `<Container>`. Components in `<Container>` will go fullscreen with the player, respond to user activity, and more.
+
+- [Read more about <Container>](../reference/player-container.md)
+
+## Styling and customization
+
+For components you add yourself, use the documented props, state `data-*` attributes, and CSS custom properties. Add your own `className` when you need a selector.
+
+### The `render` prop
+
+The `render` prop is the primary customization mechanism. It accepts a function that receives `props` and `state`, and returns your element. The `props` object includes event handlers, ARIA attributes, data attributes, and a ref — always spread `{...props}` to keep everything working:
+
+tsx
+
+```
+import { PlayButton } from '@videojs/react';
+import { PauseIcon, PlayIcon } from '@videojs/react/icons';
+
+<PlayButton
+  render={(props, state) => (
+    <button {...props}>
+      {state.paused ? <PlayIcon /> : <PauseIcon />}
+    </button>
+  )}
+/>
+```
+
+`className` and `style` also accept functions of state for dynamic styling without a full render prop:
+
+tsx
+
+```
+<PlayButton
+  className={(state) =>
+    state.paused ? 'btn btn--paused' : 'btn btn--playing'
+  }
+/>
+```
+
+### Data attributes and CSS custom properties
+
+Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
+
+This lets you style state changes in pure CSS:
+
+css
+
+```
+/* Show/hide icons based on play state */
+.play-icon  { display: none; }
+.pause-icon { display: none; }
+
+button[data-paused] .play-icon        { display: inline; }
+button:not([data-paused]) .pause-icon { display: inline; }
+```
+
+Each component’s reference page documents its full set of data attributes.
+
+Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
+
+## Compound components
+
+Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each visible part owns at most one element.
+
+Compound components use dot notation off a shared namespace:
+
+tsx
+
+```
+<VolumeSlider.Root orientation="vertical">
+  <VolumeSlider.Track>
+    <VolumeSlider.Fill />
+  </VolumeSlider.Track>
+  <VolumeSlider.Thumb />
+</VolumeSlider.Root>
+```

package/docs/concepts/v10-roadmap.md

@@ -0,0 +1,75 @@
+# 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](../how-to/installation.md), try it out, and report issues
+
+## Mid-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](../how-to/migrate-from-video-js-8.md), [Mux Player](../how-to/migrate-from-mux-player.md), [Plyr](../how-to/migrate-from-plyr.md), and [Media Chrome](../how-to/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