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

package/docs/reference/{player-controller.md → api/player-controller.md}

@@ -4,19 +4,15 @@ Reactive controller for accessing player store state in HTML custom elements
 
 ## Import
 
-ts
-
-```
+```ts
 import { PlayerController } from "@videojs/html/video";
 ```
 
-`PlayerController` is a reactive controller that consumes the player store from [`playerContext`](./player-context.md). 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.
+`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
-
-```
+```ts
 import { UIElement, selectPlayback } from '@videojs/html';
 import { PlayerController } from '@videojs/html/video';
 
@@ -29,15 +25,9 @@ class PlayButtonElement extends UIElement {
 
 ### Basic Usage
 
-Play Pause 50% Volume Paused: Yes | Time: 0.0s | Volume: 100%
-
-index.html
+**index.html**
 
-index.css
-
-index.ts
-
-```
+```html
 <demo-ctrl-player class="demo-ctrl-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
@@ -54,7 +44,10 @@ index.ts
   </media-container>
 </demo-ctrl-player>
 ```
-```
+
+**index.css**
+
+```css
 .demo-ctrl-player media-container {
   position: relative;
 }
@@ -80,6 +73,7 @@ index.ts
 .actions button {
   padding: 4px 12px;
   font-size: 0.8125rem;
+  color: #111827;
   cursor: pointer;
   background: white;
   border: 1px solid #ccc;
@@ -92,7 +86,10 @@ index.ts
   color: #374151;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import {
   applyElementProps,
   createButton,
@@ -173,142 +170,39 @@ customElements.define(PlayerState.tagName, PlayerState);
 
 ## API Reference
 
-### Overload 1
-
-#### Parameters
-
-Parameter
-
-Type
-
-Default
+### Without Selector
 
-Details
+`new PlayerController<Store extends PlayerStore, Result = Store>(host, context)`
 
-`host*`
-
-`object`
-
-`—`
-
-▸
-
-Description
-
-The host element that owns this controller.
-
-Type
-
-`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
-
-`context*`
-
-`Context<typeof PLAYER_CONTEXT_KEY, PlayerContextValue<Store>>`
-
-`—`
-
-▸
-
-Description
+#### Parameters
 
-Player context to resolve the store from.
+| 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
-
-Details
-
-`value`
-
-`Result | undefined`
-
-`displayName`
+| Property | Type |
+| --- | --- |
+| `value` | `Result \| undefined` |
+| `displayName` | `string \| undefined` |
 
-`string | undefined`
+### With Selector
 
-`hostConnected`
-
-`(() => void)`
-
-`hostDisconnected`
-
-`(() => void)`
-
-### Overload 2
+`new PlayerController<Store extends PlayerStore, Result = Store>(host, context, selector)`
 
 #### Parameters
 
-Parameter
-
-Type
-
-Default
-
-Details
-
-`host*`
-
-`object`
-
-`—`
-
-▸
-
-Description
-
-The host element that owns this controller.
-
-Type
-
-`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
-
-`context*`
-
-`Context<typeof PLAYER_CONTEXT_KEY, PlayerContextValue<Store>>`
-
-`—`
-
-▸
-
-Description
-
-Player context to resolve the store from.
-
-`selector*`
-
-`Selector<InferStoreState<Store>, Result>`
-
-`—`
-
-▸
-
-Description
-
-Derives a value from the player store state.
+| 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
-
-Details
-
-`value`
-
-`Result | undefined`
-
-`displayName`
-
-`string | undefined`
-
-`hostConnected`
-
-`(() => void)`
-
-`hostDisconnected`
-
-`(() => void)`
+| Property | Type |
+| --- | --- |
+| `value` | `Result \| undefined` |
+| `displayName` | `string \| undefined` |

package/docs/reference/{register-i18n.md → api/register-i18n.md}

@@ -4,19 +4,15 @@ Register or merge translation strings for a BCP 47 locale tag in the global i18n
 
 ## Import
 
-ts
-
-```
+```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 keys](./translation-phrases.md) for the complete catalog.
-
-ts
+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', {
@@ -29,43 +25,14 @@ registerI18n('es', {
 
 ## API Reference
 
-### Parameters
-
-Parameter
-
-Type
-
-Default
-
-Details
-
-`locale*`
-
-`(typeof LOCALES)[number] | string & o...`
+`registerI18n(locale, translations): void`
 
-`—`
-
-▸
-
-Description
-
-BCP 47 tag (normalized to lowercase; unicode extensions stripped for the registry key).
-
-Type
-
-`(typeof LOCALES)[number] | string & object`
-
-`translations*`
-
-`Partial<Translations>`
-
-`—`
-
-▸
-
-Description
+### Parameters
 
-Partial nested locale values; merges with any existing layer for the tag.
+| 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
 

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

@@ -0,0 +1,95 @@
+# SnapshotController
+
+Reactive controller for subscribing to a State container in HTML custom elements
+
+## Import
+
+```ts
+import { SnapshotController } from "@videojs/store/html";
+```
+
+`SnapshotController` subscribes to a `State` container and triggers host updates when state changes. It has two overloads:
+
+**Full state** – returns the entire state object. Re-renders on any state change.
+
+```ts
+class Display extends HTMLElement {
+  #state = new SnapshotController(this, sliderState);
+
+  render() {
+    const value = this.#state.value;
+    // Full state object
+  }
+}
+```
+
+**With selector** – returns a derived value from state. Re-renders only when the selected value changes (using shallow equality).
+
+```ts
+class SliderValue extends HTMLElement {
+  #value = new SnapshotController(this, sliderState, (s) => s.value);
+
+  render() {
+    return this.#value.value; // Only the selected slice
+  }
+}
+```
+
+Use `.track(state)` to switch to a different `State` container at runtime.
+
+### SnapshotController vs StoreController
+
+Both are reactive controllers, but they operate at different levels:
+
+| | `SnapshotController` | [`StoreController`](./store-controller.md) |
+| --- | --- | --- |
+| **Input** | `State` container | Store instance or context |
+| **Subscribes** | Always | Only with a selector |
+| **Use case** | Subscribe to raw state changes | Access store actions and optionally subscribe |
+
+`SnapshotController` is lower-level. It works with `State` containers directly – the reactive primitives that back a store. Use it when building custom controllers or working outside the player store system.
+
+[`StoreController`](./store-controller.md) is higher-level. It resolves a store from a context or direct reference and internally creates a `SnapshotController` when you pass a selector. Use it for player UI elements.
+
+### Lifecycle
+
+`SnapshotController` subscribes on `hostConnected()` and unsubscribes on `hostDisconnected()`. The React equivalent is [`useSnapshot`](https://videojs.org/docs/framework/react/reference/api/use-snapshot).
+
+## API Reference
+
+### Without Selector
+
+`new SnapshotController<T extends object, R = T>(host, state)`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> }` | — | The host element that owns this controller. |
+| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — | The State container to subscribe to. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `R` | |
+| `track` | `((state: { current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }) => void)` | Switch to tracking a different state container. |
+
+### With Selector
+
+`new SnapshotController<T extends object, R = T>(host, state, selector)`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> }` | — | The host element that owns this controller. |
+| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — | The State container to subscribe to. |
+| `selector` (required) | `{ (state: T): R; displayName?: string }` | — | Derives a value from the state. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `R` | |
+| `track` | `((state: { current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }) => void)` | Switch to tracking a different state container. |

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

@@ -0,0 +1,85 @@
+# StoreController
+
+Reactive controller for subscribing to store state in HTML custom elements
+
+## Import
+
+```ts
+import { StoreController } from "@videojs/store/html";
+```
+
+`StoreController` is a reactive controller for accessing store state and actions in custom elements. It accepts a store instance or a context, resolving the store automatically.
+
+**Without selector** – returns the store instance directly. Does NOT subscribe to changes. Use this to access store actions.
+
+```ts
+class VolumeControl extends HTMLElement {
+  #store = new StoreController(this, storeSource);
+
+  handleClick() {
+    this.#store.value.setVolume(0.5);
+  }
+}
+```
+
+**With selector** – returns the selected value and subscribes to changes. Triggers a host update when the selected value changes (using shallow equality).
+
+```ts
+class PlayButton extends HTMLElement {
+  #playback = new StoreController(this, storeSource, selectPlayback);
+
+  render() {
+    const playback = this.#playback.value;
+    // Re-renders when playback state changes
+  }
+}
+```
+
+### StoreController vs PlayerController vs SnapshotController
+
+| | `StoreController` | [`PlayerController`](./player-controller.md) | [`SnapshotController`](./snapshot-controller.md) |
+| --- | --- | --- | --- |
+| **Input** | Any store or context | Player store context | `State` container |
+| **Typed to** | Generic store | Player features | Raw state |
+| **Use case** | General-purpose store access | Player UI elements | Low-level state subscription |
+
+[`PlayerController`](./player-controller.md) is a typed wrapper around `StoreController` scoped to the player store. For player UI, prefer `PlayerController`. Use `StoreController` when working with a custom store outside the player system.
+
+When you pass a selector, `StoreController` internally creates a [`SnapshotController`](./snapshot-controller.md) on the store’s `$state` container. Without a selector, no subscription is created – you get the store instance for imperative access to actions.
+
+## API Reference
+
+### Without Selector
+
+`new StoreController<Store extends AnyStore, Result = Store>(host, source)`
+
+#### 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. |
+| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `value` | `Result` |
+
+### With Selector
+
+`new StoreController<Store extends AnyStore, Result = Store>(host, source, 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. |
+| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |
+| `selector` (required) | `{ (state: Store['state']): Result; displayName?: string }` | — | Derives a value from the store state. |
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `value` | `Result` |

package/docs/reference/{subscription-controller.md → api/subscription-controller.md}

@@ -4,9 +4,7 @@ Reactive controller that resolves a store and manages a derived subscription
 
 ## Import
 
-ts
-
-```
+```ts
 import { SubscriptionController } from "@videojs/store/html";
 ```
 
@@ -14,9 +12,7 @@ import { SubscriptionController } from "@videojs/store/html";
 
 Provide a store or store context plus functions that read the current value and subscribe to changes.
 
-ts
-
-```
+```ts
 class QueueController {
   readonly #tasks;
 
@@ -37,72 +33,18 @@ The controller requests a host update when the subscription changes and unsubscr
 
 ## API Reference
 
-### Parameters
-
-Parameter
-
-Type
-
-Default
-
-Details
-
-`host*`
-
-`object`
-
-`—`
-
-▸
-
-Description
-
-The host element that owns this controller.
-
-Type
-
-`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
-
-`source*`
+`new SubscriptionController<Store extends AnyStore, Value>(host, source, config)`
 
-`Store | Context<unknown, Store>`
-
-`—`
-
-▸
-
-Description
-
-Store instance or context to resolve the store from.
-
-`config*`
-
-`function`
-
-`—`
-
-▸
-
-Description
-
-Subscription and value extraction configuration.
-
-Type
+### Parameters
 
-`{ getValue: ((store: Store) => Value); subscribe: ((store: Store, onChange: (() => void)) => (() => void)) }`
+| 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. |
+| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |
+| `config` (required) | `{ getValue: ((store: Store) => Value); subscribe: ((store: Store, onChange: (() => void)) => (() => void)) }` | — | Subscription and value extraction configuration. |
 
 ### Return Value
 
-Property
-
-Type
-
-Details
-
-`value`
-
-`Value`
-
-`hostDisconnected`
-
-`(() => void)`
+| Property | Type |
+| --- | --- |
+| `value` | `Value` |