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

package/docs/reference/api/html-create-player.md

@@ -0,0 +1,228 @@
+# createPlayer
+
+Factory function that creates a typed player element and controller for HTML custom elements
+
+## Import
+
+```ts
+import { createPlayer } from "@videojs/html";
+import { videoFeatures } from "@videojs/html/video";
+```
+
+`createPlayer` is the entry point for custom HTML player compositions. It accepts a `features` array and returns the configured `PlayerElement`, a [`PlayerController`](./player-controller.md) already bound to that player, and `playerContext` as a lower-level escape hatch. Import `ContainerElement` separately when you need a custom container.
+
+**player.ts**
+
+```ts
+import { createPlayer, UIElement, selectPlayback } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
+  features: videoFeatures,
+});
+
+customElements.define('video-player', VideoPlayerElement);
+
+// Control element with selector
+class PlayButton extends UIElement {
+  #playback = new PlayerController(this, selectPlayback);
+}
+```
+
+`PlayerElement` and `PlayerController` are scoped to the created player’s feature set. The element owns its store and attachment lifecycle; the configured controller does not need a context argument. `ContainerElement` consumes the shared player context, so the same class works with any created player.
+
+Use split elements (recommended for reusable skins/layouts):
+
+**player.ts**
+
+```ts
+import { ContainerElement, createPlayer } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement: PlayerRoot } = createPlayer({ features: videoFeatures });
+
+class PlayerRegion extends ContainerElement {}
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<demo-video-player class="demo-video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
+    <demo-play-toggle class="media-play-button">
+      <span class="paused">Play</span>
+      <span class="playing">Pause</span>
+    </demo-play-toggle>
+  </media-container>
+</demo-video-player>
+```
+
+**index.css**
+
+```css
+.demo-video-player media-container {
+  position: relative;
+}
+
+.demo-video-player media-container video {
+  width: 100%;
+}
+
+.media-play-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-play-button .paused {
+  display: none;
+}
+
+.media-play-button .playing {
+  display: none;
+}
+
+.media-play-button[data-paused] .paused {
+  display: inline;
+}
+
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import {
+  applyElementProps,
+  applyStateDataAttrs,
+  createButton,
+  createPlayer,
+  selectPlayback,
+  UIElement,
+} from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+import '@videojs/html/ui/container';
+
+const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
+  features: videoFeatures,
+});
+
+class PlayToggle extends UIElement {
+  static readonly tagName = 'demo-play-toggle';
+
+  readonly #player = new PlayerController(this, selectPlayback);
+
+  #disconnect: AbortController | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.#disconnect = new AbortController();
+
+    const buttonProps = createButton({
+      onActivate: () => {
+        const state = this.#player.value;
+        if (!state) return;
+
+        state.paused ? state.play() : state.pause();
+      },
+      isDisabled: () => !this.#player.value,
+    });
+
+    applyElementProps(this, buttonProps, { signal: this.#disconnect.signal });
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  protected override update(changed: Map<string, unknown>): void {
+    super.update(changed);
+    const state = this.#player.value;
+    if (!state) return;
+
+    applyStateDataAttrs(this, state, { paused: 'data-paused', ended: 'data-ended' });
+  }
+}
+
+customElements.define('demo-video-player', VideoPlayerElement);
+customElements.define(PlayToggle.tagName, PlayToggle);
+```
+
+## API Reference
+
+### Video
+
+`createPlayer(config): CreatePlayerResult<VideoPlayerStore>`
+
+Creates a typed HTML player class and bound controller.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<VideoPlayerStore>)` | Configured player element class that owns the store and attachment lifecycle. |
+| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<VideoPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<VideoPlayerStore['state'], Result>): PlayerController<VideoPlayerStore, Result> }` | Player controller bound to this player's context. |
+| `playerContext` | `Context<symbol, VideoPlayerStore>` | Context that carries the player store to descendant elements. |
+
+### Audio
+
+`createPlayer(config): CreatePlayerResult<AudioPlayerStore>`
+
+Creates a typed HTML audio player class and bound controller.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<AudioPlayerStore>)` | Configured player element class that owns the store and attachment lifecycle. |
+| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<AudioPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<AudioPlayerStore['state'], Result>): PlayerController<AudioPlayerStore, Result> }` | Player controller bound to this player's context. |
+| `playerContext` | `Context<symbol, AudioPlayerStore>` | Context that carries the player store to descendant elements. |
+
+### Generic
+
+`createPlayer<const Features extends AnyPlayerFeature[]>(config): CreatePlayerResult<PlayerStore<Features>>`
+
+Creates a typed HTML player class with custom features.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` (required) | `{ features: Features }` | — | Player configuration with features. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<PlayerStore<Features>>)` | Configured player element class that owns the store and attachment lifecycle. |
+| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<PlayerStore<Features>>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<PlayerStore<Features>['state'], Result>): PlayerController<PlayerStore<Features>, Result> }` | Player controller bound to this player's context. |
+| `playerContext` | `Context<symbol, PlayerStore<Features>>` | Context that carries the player store to descendant elements. |

package/docs/reference/api/i18n-controller.md

@@ -0,0 +1,45 @@
+# I18nController
+
+Reactive controller for consuming translator and locale values from an HTML i18n context
+
+## Import
+
+```ts
+import { I18nController } from "@videojs/html";
+```
+
+## Usage
+
+Create the controller with a reactive host and an i18n context. Read the translator from `value` and the active locale from `locale`.
+
+```ts
+import { I18nController, UIElement, i18nContext } from "@videojs/html";
+
+class LocalizedPlayLabel extends UIElement {
+  readonly #i18n = new I18nController(this, i18nContext);
+
+  get label() {
+    return this.#i18n.value("buttons.play", { default: "Play" });
+  }
+}
+```
+
+The controller requests a host update when its context changes. Without a provider, it falls back to the default English locale and updates when registered translations change.
+
+## API Reference
+
+`new I18nController(host, context)`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | Reactive host updated when the i18n value changes. |
+| `context` (required) | `Context<symbol, I18nContextValue>` | — | I18n context to consume. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `value` | `Translator` |
+| `locale` | `(typeof LOCALES)[number] \| string & {}` |

package/docs/reference/api/llms.txt

@@ -0,0 +1,74 @@
+# Video.js v10 — HTML API
+
+> API reference for the player factory, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.0.0-rc.3. Links are relative paths to files in this directory.
+
+## Player
+
+API reference for creating a player and reaching it and its container from your own code.
+
+- [createPlayer](./html-create-player.md): Factory function that creates a typed player element and controller for HTML custom elements
+- [PlayerController](./player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+
+## Store
+
+API reference for reading and subscribing to player state: selectors and the store controllers.
+
+- [createSelector](./create-selector.md): Create a type-safe selector for a store slice's state
+- [StoreController](./store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
+- [SnapshotController](./snapshot-controller.md): Reactive controller for subscribing to a State container in HTML custom elements
+- [SubscriptionController](./subscription-controller.md): Reactive controller that resolves a store and manages a derived subscription
+
+## Features
+
+API reference for the feature modules passed to createPlayer, which provide player capabilities and state.
+
+- [Buffer](./feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./feature-controls.md): User activity and controls visibility state for the player store
+- [Error](./feature-error.md): Media error state and actions for the player store
+- [Fullscreen](./feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Live](./feature-live.md): Live edge state for the player store
+- [Metadata](./feature-metadata.md): Resolved title and poster values for the player store
+- [Orientation lock](./feature-orientation-lock.md): Screen orientation locking while fullscreen is active
+- [Picture-in-picture](./feature-pip.md): Picture-in-picture state and actions for the player store
+- [Playback](./feature-playback.md): Play/pause state and actions for the player store
+- [Playback rate](./feature-playback-rate.md): Playback speed state and actions for the player store
+- [Quality](./feature-quality.md): Video rendition state and actions for the player store
+- [Audio track](./feature-audio-track.md): Audio track state and actions for the player store
+- [Remote Playback](./feature-remote-playback.md): Remote playback state and actions for the player store
+- [Source](./feature-source.md): Media source state and actions for the player store
+- [Stream type](./feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text tracks](./feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./feature-time.md): Playback position and duration state for the player store
+- [Volume](./feature-volume.md): Volume level and mute state for the player store
+
+## i18n
+
+API reference for translating the player: the i18n elements, controller, and the phrase registry.
+
+- [createI18n](./create-i18n.md): Factory that creates framework i18n helpers with custom loading options
+- [media-i18n](./media-i18n.md): HTML custom element that resolves locale and supplies translations to descendants
+- [media-text](./media-text.md): HTML custom element that renders a translated string by semantic key
+- [Translation phrases](./translation-phrases.md): Semantic i18n keys, their English defaults, and the player UI that uses them
+- [registerI18n](./register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+- [getI18nTranslations](./get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
+- [hasRegisteredLocale](./has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
+- [onI18nRegistryChange](./on-i18n-registry-change.md): Subscribe to global i18n registry mutations
+- [createTranslator](./create-translator.md): Build a typed translator from a resolved translation map
+- [I18nController](./i18n-controller.md): Reactive controller for consuming translator and locale values from an HTML i18n context
+
+## Utils
+
+Lower-level building blocks for custom components: the keyboard shortcut controller.
+
+- [AriaKeyShortcutsController](./aria-key-shortcuts-controller.md): Reactive controller that exposes registered hotkey shortcut metadata
+
+## Error codes
+
+Reference for codes thrown when Video.js 8 APIs are used with the Video.js 10 package.
+
+- [Error Codes](./error-codes.md): Error codes emitted by the video.js package and how to resolve them
+- [VJS8_LEGACY_INIT](./vjs8-legacy-init.md): Legacy Video.js 8 player initialization error
+- [VJS8_LEGACY_PLUGIN](./vjs8-legacy-plugin.md): Legacy Video.js 8 plugin registration error
+- [VJS8_LEGACY_COMPONENT](./vjs8-legacy-component.md): Legacy Video.js 8 component registration error
+- [VJS8_LEGACY_GET_PLAYER](./vjs8-legacy-get-player.md): Legacy Video.js 8 player lookup error
+- [VJS8_LEGACY_OPTIONS](./vjs8-legacy-options.md): Legacy Video.js 8 global options error

package/docs/reference/api/media-i18n.md

@@ -0,0 +1,37 @@
+# media-i18n
+
+HTML custom element that resolves locale and supplies translations to descendants
+
+## Import
+
+```ts
+import "@videojs/html/i18n";
+```
+
+One import registers both `<media-i18n>` and `<media-text>`.
+
+`<media-i18n>` applies the i18n provider mixin to a subtree. Wrap a player, standalone controls, or one of several players that need different locales with this element. Without it, HTML controls use English defaults.
+
+Set `lang` on the provider or an ancestor. Built-in packs lazy-load automatically; register locale strings with [`registerI18n`](./register-i18n.md) when you need custom copy or synchronous first paint. See [Translation phrases](./translation-phrases.md) for supported keys.
+
+```html
+<script type="module">
+  import '@videojs/html/i18n';
+  import '@videojs/html/i18n/locales/es/register';
+</script>
+
+<media-i18n lang="es">
+  <media-text token="buttons.play">Play</media-text>
+</media-i18n>
+```
+
+## Attributes
+
+| Attribute | Description |
+| --- | --- |
+| `lang` | Forces the active BCP 47 locale for this subtree. Omit to inherit the nearest ancestor `[lang]`. |
+
+## Related
+
+- [`<media-text>`](./media-text.md): Renders translated text content
+- [Internationalize the player](../../guides/internationalization.md)

package/docs/reference/api/media-text.md

@@ -0,0 +1,27 @@
+# media-text
+
+HTML custom element that renders a translated string by semantic key
+
+## Import
+
+```ts
+import "@videojs/html/i18n";
+```
+
+One import registers both `<media-i18n>` and `<media-text>`.
+
+`<media-text>` renders a translated value inside a [`<media-i18n>`](./media-i18n.md) (or any ancestor with the i18n provider mixin). Set `token` to the semantic translation key and use the text content as its English fallback. Use it for authored component content, standalone labels, tooltips, or demos.
+
+```html
+<media-i18n lang="ja">
+  <media-text token="buttons.play">Play</media-text>
+</media-i18n>
+```
+
+## Token and fallback
+
+The `token` attribute accepts an opaque key such as `buttons.play`. The initial text content is the fallback shown when the active locale has no value for that key. See [Translation phrases](./translation-phrases.md) for the supported keys and English defaults.
+
+Without `token`, `<media-text>` keeps its text content unchanged. This is useful for literal copy that should not be translated.
+
+Parametric translations are not yet supported on `<media-text>`. Use `createTranslator` in script for interpolated strings.

package/docs/reference/api/on-i18n-registry-change.md

@@ -0,0 +1,27 @@
+# onI18nRegistryChange
+
+Subscribe to global i18n registry mutations
+
+## Import
+
+```ts
+import { onI18nRegistryChange } from "@videojs/html/i18n";
+```
+
+`onI18nRegistryChange` registers a callback that runs whenever any locale layer changes, for example after `registerI18n` or browser translation prefetch. Returns an unsubscribe function.
+
+## API Reference
+
+`onI18nRegistryChange(callback): (() => void)`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `callback` (required) | `(() => void)` | — | Invoked when any locale layer changes. |
+
+### Return Value
+
+| Type |
+| --- |
+| `(() => void)` |

package/docs/reference/api/player-controller.md

@@ -0,0 +1,208 @@
+# PlayerController
+
+Reactive controller for accessing player store state in HTML custom elements
+
+## Import
+
+```ts
+import { PlayerController } from "@videojs/html/video";
+```
+
+`PlayerController` is a reactive controller that consumes the player store from `playerContext`. Without a selector it returns the store instance directly (no subscription — use this for actions). With a selector it returns the selected value and subscribes to changes, triggering a host update on shallow-equal change. Access the current value via `.value`, which returns `undefined` until connected to a player.
+
+The controller exported by each preset, or returned by [`createPlayer`](./html-create-player.md), is already bound to that player’s context, so pass only the host and optional selector. The lower-level `PlayerController` exported from `@videojs/html` accepts the context as its second argument; its constructor signatures are documented below.
+
+```ts
+import { UIElement, selectPlayback } from '@videojs/html';
+import { PlayerController } from '@videojs/html/video';
+
+class PlayButtonElement extends UIElement {
+  readonly #playback = new PlayerController(this, selectPlayback);
+}
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<demo-ctrl-player class="demo-ctrl-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
+    <div class="panel">
+      <demo-ctrl-actions class="actions">
+        <button type="button" class="play">Play</button>
+        <button type="button" class="pause">Pause</button>
+        <button type="button" class="volume">50% Volume</button>
+      </demo-ctrl-actions>
+      <demo-ctrl-state class="state">
+        <span class="text">Paused: Yes | Time: 0.0s | Volume: 100%</span>
+      </demo-ctrl-state>
+    </div>
+  </media-container>
+</demo-ctrl-player>
+```
+
+**index.css**
+
+```css
+.demo-ctrl-player media-container {
+  position: relative;
+}
+
+.demo-ctrl-player media-container video {
+  width: 100%;
+}
+
+.panel {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  padding: 12px;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.actions {
+  display: flex;
+  gap: 6px;
+}
+
+.actions button {
+  padding: 4px 12px;
+  font-size: 0.8125rem;
+  color: #111827;
+  cursor: pointer;
+  background: white;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+}
+
+.state {
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+  color: #374151;
+}
+```
+
+**index.ts**
+
+```ts
+import {
+  applyElementProps,
+  createButton,
+  createPlayer,
+  selectPlayback,
+  selectTime,
+  selectVolume,
+  UIElement,
+} from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+import '@videojs/html/ui/container';
+
+const { PlayerElement: DemoPlayerElement, PlayerController } = createPlayer({
+  features: videoFeatures,
+});
+
+class PlayerActions extends UIElement {
+  static readonly tagName = 'demo-ctrl-actions';
+
+  readonly #player = new PlayerController(this);
+
+  #disconnect: AbortController | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.#disconnect = new AbortController();
+    const signal = this.#disconnect.signal;
+
+    const playBtn = this.querySelector<HTMLButtonElement>('.play')!;
+    const pauseBtn = this.querySelector<HTMLButtonElement>('.pause')!;
+    const volumeBtn = this.querySelector<HTMLButtonElement>('.volume')!;
+
+    const bind = (el: HTMLElement, action: () => void) => {
+      const props = createButton({ onActivate: action, isDisabled: () => !this.#player.value });
+
+      applyElementProps(el, props, { signal });
+    };
+
+    bind(playBtn, () => this.#player.value?.play());
+    bind(pauseBtn, () => this.#player.value?.pause());
+    bind(volumeBtn, () => this.#player.value?.setVolume(0.5));
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+}
+
+class PlayerState extends UIElement {
+  static readonly tagName = 'demo-ctrl-state';
+
+  readonly #playback = new PlayerController(this, selectPlayback);
+  readonly #time = new PlayerController(this, selectTime);
+  readonly #volume = new PlayerController(this, selectVolume);
+
+  protected override update(changed: Map<string, unknown>): void {
+    super.update(changed);
+    const playback = this.#playback.value;
+    const time = this.#time.value;
+    const volume = this.#volume.value;
+
+    if (!playback) return;
+
+    const el = this.querySelector('.text');
+
+    if (el) {
+      el.textContent = `Paused: ${playback.paused ? 'Yes' : 'No'} | Time: ${(time?.currentTime ?? 0).toFixed(1)}s | Volume: ${Math.round((volume?.volume ?? 0) * 100)}%`;
+    }
+  }
+}
+
+customElements.define('demo-ctrl-player', DemoPlayerElement);
+customElements.define(PlayerActions.tagName, PlayerActions);
+customElements.define(PlayerState.tagName, PlayerState);
+```
+
+## API Reference
+
+### Without Selector
+
+`new PlayerController<Store extends PlayerStore, Result = Store>(host, context)`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
+| `context` (required) | `Context<symbol, Store>` | — | Player context to resolve the store from. |
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `value` | `Result \| undefined` |
+| `displayName` | `string \| undefined` |
+
+### With Selector
+
+`new PlayerController<Store extends PlayerStore, Result = Store>(host, context, selector)`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
+| `context` (required) | `Context<symbol, Store>` | — | Player context to resolve the store from. |
+| `selector` (required) | `{ (state: Store['state']): Result; displayName?: string }` | — | Derives a value from the player store state. |
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `value` | `Result \| undefined` |
+| `displayName` | `string \| undefined` |

package/docs/reference/api/register-i18n.md

@@ -0,0 +1,39 @@
+# registerI18n
+
+Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+
+## Import
+
+```ts
+import { registerI18n } from "@videojs/html/i18n";
+```
+
+`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. Components carry their own English fallback text. Built-in non-English packs lazy-load automatically; call `registerI18n` for custom locales, CDN locale modules, or patched shipped packs before the provider renders.
+
+Keys are nested semantic names such as `buttons.play` and `buttons.pause`. See [Translation phrases](./translation-phrases.md) for the complete catalog.
+
+```ts
+import { registerI18n } from '@videojs/html/i18n';
+
+registerI18n('es', {
+  buttons: {
+    play: 'Reproducir',
+    pause: 'Pausar',
+  },
+});
+```
+
+## API Reference
+
+`registerI18n(locale, translations): void`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag (normalized to lowercase; unicode extensions stripped for the registry key). |
+| `translations` (required) | `Partial<Translations>` | — | Partial nested locale values; merges with any existing layer for the tag. |
+
+### Return Value
+
+`void`