From d081db9507eeb92abbc1e3da65c2104e90472e43 Mon Sep 17 00:00:00 2001
From: rahim <rahim.alwer@gmail.com>
Date: Fri, 30 Jan 2026 22:39:51 +1100
Subject: [PATCH] docs(rfc): player api design v2 (#358)

---
 .../design/feature-availability-design.md     |   2 +-
 internal/design/feature-slice-design.md       | 171 ------
 rfc/player-api/api.md                         | 240 ++++++++
 rfc/player-api/architecture.md                | 223 +++----
 rfc/player-api/decisions.md                   | 439 ++++++--------
 rfc/player-api/examples.md                    | 545 ++++++++++++------
 rfc/player-api/features.md                    | 206 +++++++
 rfc/player-api/feedback.md                    |  68 +++
 rfc/player-api/html.md                        | 323 +++++++++++
 rfc/player-api/index.md                       | 363 +++---------
 rfc/player-api/primitives.md                  | 292 ++++++----
 11 files changed, 1719 insertions(+), 1153 deletions(-)
 delete mode 100644 internal/design/feature-slice-design.md
 create mode 100644 rfc/player-api/api.md
 create mode 100644 rfc/player-api/features.md
 create mode 100644 rfc/player-api/feedback.md
 create mode 100644 rfc/player-api/html.md

diff --git a/internal/design/feature-availability-design.md b/internal/design/feature-availability-design.md
index 81756f59..ebc1f9fd 100644
--- a/internal/design/feature-availability-design.md
+++ b/internal/design/feature-availability-design.md
@@ -38,7 +38,7 @@ type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
 
 ## Related: Missing Feature vs Unavailable Capability
 
-See [feature-slice-design](feature-slice-design.md) for feature access patterns.
+See [rfc/player-api](../../rfc/player-api/primitives.md) for feature access patterns.
 
 | Concept                | Cause               | Detection                         |
 | ---------------------- | ------------------- | --------------------------------- |
diff --git a/internal/design/feature-slice-design.md b/internal/design/feature-slice-design.md
deleted file mode 100644
index 4a619512..00000000
--- a/internal/design/feature-slice-design.md
+++ /dev/null
@@ -1,171 +0,0 @@
----
-status: draft
-date: 2025-01-29
----
-
-# Feature Slice Design
-
-## Problem
-
-Primitives don't know which preset the user chose:
-
-```tsx
-// Inside @videojs/react - shipped to users
-export function PlayButton() {
-  const player = usePlayer(); // What type is this?
-  // User will use custom feature configuration
-  // We don't know if `playbackFeature` is included
-}
-```
-
-They need:
-
-1. Loosely typed access to the player
-2. A way to check if a feature exists
-3. Type narrowing when the feature is present
-
-## Solution
-
-A `FeatureSlice` provides typed, scoped access to a feature's state and requests. Two API layers:
-
-1. **Primitive** — generic, explicit store/feature
-2. **Player-specific** — typed by registry, uses context
-
-## Design
-
-### Feature Definition
-
-Features have a typed `name` (literal type preserved):
-
-```ts
-const playbackFeature = createFeature<HTMLMediaElement>()({
-  name: 'playback',  // Type: 'playback' (literal)
-  initialState: { paused: true },
-  request: { play, pause },
-});
-```
-
-### Store API
-
-```ts
-// By reference — typed from feature
-store.getFeature(playbackFeature);
-
-// By name — typed from store's features array
-store.getFeature('playback');
-```
-
-Returns `FeatureSlice | undefined`. Flat access to state and requests:
-
-```ts
-const playback = store.getFeature(playbackFeature);
-
-if (!playback) return null;
-
-playback.paused;          // State (flat)
-playback.play();          // Request (flat)
-playback.subscribe(cb);   // Scoped subscription
-```
-
-### Primitive Layer (`@videojs/store`)
-
-Generic APIs that require explicit store/feature:
-
-```ts
-// React — explicit store + feature
-const playback = useFeature(store, playbackFeature);
-
-// Lit — explicit store + feature
-#playback = new FeatureController(host, store, playbackFeature);
-```
-
-### Player Layer (`@videojs/core/dom`, `@videojs/react`, `@videojs/html`)
-
-Typed by `PlayerFeatureRegistry`, uses context:
-
-```ts
-// Registry (manually maintained)
-interface PlayerFeatureRegistry {
-  playback: typeof playbackFeature;
-  volume: typeof volumeFeature;
-  time: typeof timeFeature;
-}
-
-// Utility
-getPlayerFeature(store, 'playback');  // Typed
-
-// React — uses player context
-usePlayerFeature('playback');  // Typed, store from context
-
-// Lit — uses player context
-new PlayerFeatureController(host, 'playback');  // Typed
-```
-
-### Usage Examples
-
-**React primitive (custom feature):**
-
-```tsx
-function CustomControl() {
-  const store = useStore();
-  const custom = useFeature(store, myCustomFeature);
-  // ...
-}
-```
-
-**React player-specific:**
-
-```tsx
-function PlayButton() {
-  const playback = usePlayerFeature('playback');
-  
-  if (!playback) return null;
-
-  // ...
-}
-```
-
-**Lit player-specific:**
-
-```ts
-class PlayButton extends ReactiveElement {
-  #core = new PlayButtonCore();
-  #playback = new PlayerFeatureController(this, 'playback');
-  
-  protected override update(changed: PropertyValues) {
-    super.update(changed);
-    applyElementProps(this, this.#core.getProps(this.#playback.value));
-  }
-}
-```
-
-## FeatureSlice
-
-A thin lens over the store — flat access, scoped subscription:
-
-- State keys exposed directly (not `.state.paused`)
-- Request keys exposed directly (not `.request.play()`)
-- `subscribe()` for scoped updates (reserved name)
-
-## Rationale
-
-1. **Type safety** — Types flow from feature reference or registry
-2. **No collisions** — Features keyed by symbol (unique)
-3. **Layered API** — Primitive layer is generic, player layer is typed and convenient
-4. **Familiar pattern** — Similar to Jotai atoms, Vue InjectionKey
-
-## Related
-
-See [feature-availability-design](feature-availability-design.md) for capability detection patterns.
-
-## Files
-
-| Package | File | Change |
-|---------|------|--------|
-| `store` | `src/core/feature-slice.ts` | New — `FeatureSlice` class |
-| `store` | `src/core/store.ts` | Add `getFeature()` |
-| `store` | `src/react/use-feature.ts` | New — `useFeature` hook |
-| `store` | `src/lit/feature-controller.ts` | New — `FeatureController` |
-| `core/dom` | `src/store/registry.ts` | New — `PlayerFeatureRegistry` |
-| `react` | `src/use-player-feature.ts` | New — `usePlayerFeature` hook |
-| `html` | `src/player-feature-controller.ts` | New — `PlayerFeatureController` |
diff --git a/rfc/player-api/api.md b/rfc/player-api/api.md
new file mode 100644
index 00000000..42da787f
--- /dev/null
+++ b/rfc/player-api/api.md
@@ -0,0 +1,240 @@
+# API
+
+Surface API for React and HTML.
+
+## createPlayer
+
+### React
+
+```ts
+import { createPlayer, features } from '@videojs/react';
+
+const { Provider, Container, usePlayer } = createPlayer({
+  features: [features.video]
+});
+```
+
+**Returns:**
+
+| Export      | Purpose                                  |
+| ----------- | ---------------------------------------- |
+| `Provider`  | Creates stores, provides context         |
+| `Container` | Attaches container element to player store |
+| `usePlayer` | Access player state (typed to features)  |
+
+### HTML
+
+```ts
+import { createPlayer, features } from '@videojs/html';
+
+const { PlayerElement, PlayerController } = createPlayer({
+  features: [features.video]
+});
+
+customElements.define('my-video-player', PlayerElement);
+```
+
+**Returns:**
+
+| Export             | Purpose                                             |
+| ------------------ | --------------------------------------------------- |
+| `PlayerElement`    | Combined provider + container element (common case) |
+| `PlayerController` | Reactive controller for accessing player state      |
+| `ProviderElement`  | Provider-only element (advanced, split cases)       |
+| `ContainerElement` | Container-only element (advanced, split cases)      |
+| `ProviderMixin`    | Mixin for custom provider elements                  |
+| `ContainerMixin`   | Mixin for custom container elements                 |
+
+### Config
+
+```ts
+// Individual features
+createPlayer({
+  features: [features.playback, features.volume, features.fullscreen]
+});
+
+// Feature bundles (sugar)
+createPlayer({
+  features: [features.video]
+});
+
+// Extended bundle
+createPlayer({
+  features: [features.video, features.streaming]
+});
+```
+
+## usePlayer (React)
+
+Access player state with selector-based subscriptions.
+
+### Overloads
+
+```ts
+// 1. Feature only — returns full feature slice
+usePlayer(feature): FeatureSlice | undefined
+
+// 2. Feature + selector — returns selected value from feature
+usePlayer(feature, selector): R | undefined
+
+// 3. Global selector — returns selected value from all state
+usePlayer(selector): R
+```
+
+### Examples
+
+```tsx
+// Get full playback feature slice
+const playback = usePlayer(features.playback);
+if (!playback) return null;
+playback.paused;
+playback.play();
+
+// Get specific value from feature
+const paused = usePlayer(features.playback, s => s.paused);
+
+// Derive value from feature
+const isPlaying = usePlayer(features.playback, s => !s.paused && !s.ended);
+
+// Select across multiple features (global selector)
+const state = usePlayer(s => ({
+  paused: s.paused,
+  volume: s.volume
+}));
+```
+
+### Performance
+
+> **Warning:** Global selectors without feature scoping subscribe to all state changes. During playback, `currentTime` updates frequently (4-60 times/sec). Always scope to features or use specific selectors.
+
+```tsx
+// Bad — re-renders on every currentTime update
+const state = usePlayer(s => s);
+
+// Good — only subscribes to playback feature
+const playback = usePlayer(features.playback);
+
+// Good — only subscribes to paused
+const paused = usePlayer(features.playback, s => s.paused);
+```
+
+### Selector Comparison
+
+Selectors returning objects use `shallowEqual` comparison:
+
+```tsx
+// Re-renders only when paused OR volume changes
+const state = usePlayer(s => ({
+  paused: s.paused,
+  volume: s.volume
+}));
+```
+
+`shallowEqual` is exported from `@videojs/store` for custom use.
+## store.get / store.has
+
+Access features within feature context (subscribe/request handlers).
+
+### store.get(feature | key | name)
+
+Returns typed feature slice or `undefined`.
+
+```ts
+// By feature reference
+store.get(features.playback)     // PlaybackSlice | undefined
+
+// By feature key (Symbol)
+store.get(playbackKey)           // PlaybackSlice | undefined
+
+// By name (string)
+store.get('playback')            // Slice | undefined (loose typing)
+```
+
+### store.has(feature | key | name)
+
+Returns `boolean`.
+
+```ts
+store.has(features.playback)     // boolean
+store.has('playback')            // boolean
+```
+
+### Usage in Features
+
+```ts
+const keyboardFeature = createPlayerFeature({
+  subscribe: ({ store, update, signal }) => {
+    const playback = store.get(features.playback);
+
+    document.addEventListener('keydown', (e) => {
+      if (e.key === ' ') playback?.toggle();
+    }, { signal });
+  }
+});
+```
+
+## PlayerController (HTML)
+
+Reactive controller for accessing player state in custom elements.
+
+```ts
+import { createPlayer, features, MediaElement } from '@videojs/html';
+
+const { PlayerController } = createPlayer({
+  features: [features.video]
+});
+
+class MediaPlayButton extends MediaElement {
+  #playback = new PlayerController(this, features.playback);
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#handleClick);
+  }
+
+  #handleClick = () => {
+    this.#playback.value?.toggle();
+  };
+
+  override update() {
+    const playback = this.#playback.value;
+    if (!playback) return;
+    // ...
+  }
+}
+```
+
+### Controller API
+
+| Property | Returns              | Description                                     |
+| -------- | -------------------- | ----------------------------------------------- |
+| `value`  | `FeatureSlice \| undefined` | Feature slice, triggers update on change        |
+## Type Exports
+
+### From `@videojs/store`
+
+```ts
+import { shallowEqual } from '@videojs/store';
+```
+
+| Export         | Purpose                          |
+| -------------- | -------------------------------- |
+| `shallowEqual` | Shallow comparison for selectors |
+
+### From `@videojs/react`
+
+```ts
+import { createPlayer, features, usePlayer } from '@videojs/react';
+```
+
+### From `@videojs/html`
+
+```ts
+import { createPlayer, features, MediaElement } from '@videojs/html';
+```
+
+| Export          | Purpose                           |
+| --------------- | --------------------------------- |
+| `createPlayer`  | Factory for player infrastructure |
+| `features`      | Feature definitions and bundles   |
+| `MediaElement`  | Base class for UI primitives      |
diff --git a/rfc/player-api/architecture.md b/rfc/player-api/architecture.md
index 4c62db3b..a3fae373 100644
--- a/rfc/player-api/architecture.md
+++ b/rfc/player-api/architecture.md
@@ -1,75 +1,43 @@
 # Architecture
 
-Internal structure of the Player API.
+Internal structure of the Player API. Implementation detail for feature authors.
 
 ## Overview
 
 ```
                           createPlayer()
-                    config: presets.website | { features: [...] }
-                                   │
-                         filters by feature.type
-                                   │
-                   ┌───────────────┴───────────────┐
-                   ▼                               ▼
-      ┌────────────────────────┐      ┌────────────────────────┐
-      │  createStore()         │      │  createStore()         │
-      │  type: 'media'         │      │  type: 'player'        │
-      └────────────────────────┘      └────────────────────────┘
-                   │                               │
-                   ▼                               ▼
-      ┌────────────────────────┐      ┌────────────────────────┐
-      │     Media Store        │◄─────│    Player Store        │
-      │  target: MediaTarget   │      │  target: PlayerTarget  │
-      │                        │      │                        │
-      │  state: paused, volume │      │  state: isFullscreen   │
-      │  request: play, pause  │      │  request: toggleFS     │
-      └────────────────────────┘      └────────────────────────┘
-                                                   │
-                                        getFeature(target.media, f)
-                                                   │
-                                       ┌───────────┴───────────┐
-                                       ▼                       ▼
-                                Read media state        Call media requests
-                                (iOS fallback)          (keyboard shortcuts)
+                               │
+                     filters by feature.type
+                               │
+                   ┌───────────┴───────────┐
+                   ▼                       ▼
+       ┌───────────────────┐   ┌───────────────────┐
+       │   Media Store     │   │   Player Store    │
+       │  target: <video>  │◄──│  target: container│
+       │                   │   │                   │
+       │  playback, volume │   │  fullscreen, idle │
+       │  time, etc.       │   │  keyboard, etc.   │
+       └───────────────────┘   └───────────────────┘
+                                        │
+                                 store.get(feature)
+                                        │
+                              Cross-feature access
 ```
 
-**Key insight:** Player Store's target includes a media proxy. This enables coordination without tight coupling — feature authors use the same flat API as component authors.
+**Key insight:** Player store holds reference to media store. Features use `store.get()` for cross-feature access, abstracting away which store a feature lives on.
 
 ## Two Stores
 
 ### Why Two Stores
 
-| Reason                | Explanation                                                                                         |
-| --------------------- | --------------------------------------------------------------------------------------------------- |
-| **Different targets** | Media features target `MediaTarget`. Player features target `PlayerTarget`.                         |
-| **Attachment timing** | `<Video>` and `<Container>` mount at different times, possibly different tree locations.            |
-| **Config dependency** | Player features configure against typed media store. Media store must exist first.                  |
-| **Observability**     | Player→media interactions go through store. Enables debugging, tracing, request queuing.            |
-| **Standalone media**  | Headless player, audio-only, programmatic control. Media store works alone.                         |
-| **Type safety**       | Player features declare required media capabilities. TypeScript catches mismatches at compile time. |
+| Reason                | Explanation                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| **Different targets** | Media features target `HTMLMediaElement`. Player features target container. |
+| **Attachment timing** | Video element and container mount at different times.                  |
+| **Type safety**       | Features declare which target they need. TypeScript catches mismatches. |
+| **Standalone media**  | Headless player, audio-only, programmatic control. Media store works alone. |
 
-### Feature Types
-
-Features are discriminated by `type`:
-
-```ts
-interface MediaFeature {
-  type: 'media';
-  // ...
-}
-
-interface PlayerFeature {
-  type: 'player';
-  // ...
-}
-```
-
-`createPlayer` filters features by type, builds both stores, returns unified API.
-
-## Targets
-
-### MediaTarget
+### Media Store
 
 ```ts
 interface MediaTarget {
@@ -79,131 +47,106 @@ interface MediaTarget {
 
 Media features observe and control the `<video>` or `<audio>` element directly.
 
-### PlayerTarget
+### Player Store
 
 ```ts
 interface PlayerTarget {
   container: HTMLElement;
-  media: UnknownMedia; // flat proxy, not store
+  mediaStore: MediaStore;
 }
 ```
 
 Player features can:
 
 - Control the container element (fullscreen, focus)
-- Access media proxy for coordination (same flat API as components)
+- Access media features via `store.get()` for coordination
 
-## Cross-Store Access
+## Feature Registry
 
-Player features access media via `target.media` (a flat proxy). Use `hasFeature`/`getFeature` for type narrowing, and `subscribe` for reactive updates.
+Each store maintains a feature registry:
 
 ```ts
-import * as media from '@videojs/core/dom/features/media';
-import { getFeature, hasFeature, subscribe } from '@videojs/store';
+interface Store {
+  features: Map<symbol, Feature>;
 
-const fullscreen = createPlayerFeature({
-  request: {
-    enterFullscreen: (_, { target }) => {
-      // Try container fullscreen
-      if (document.fullscreenEnabled) {
-        target.container.requestFullscreen();
-        return;
-      }
+  get(feature: Feature | FeatureKey | string): Slice | undefined;
+  has(feature: Feature | FeatureKey | string): boolean;
+}
+```
 
-      // iOS fallback — use media fullscreen (flat access)
-      const mediaFS = getFeature(target.media, media.fullscreen);
-      mediaFS.enterFullscreen?.();
-    },
-  },
+Features are keyed by their `feature.key` (symbol).
 
-  subscribe: ({ target, update, signal }) => {
-    // Subscribe to media fullscreen changes (iOS)
-    if (hasFeature(target.media, media.fullscreen)) {
-      subscribe(target.media, (s) => s.isFullscreen, update, { signal });
-    }
+## Cross-Feature Access
+
+Features access other features via `store.get()`:
+
+```ts
+const keyboardFeature = createPlayerFeature({
+  subscribe: ({ store, update, signal }) => {
+    // Access playback feature (might be on media store)
+    const playback = store.get(features.playback);
+
+    document.addEventListener('keydown', (e) => {
+      if (e.key === ' ') playback?.toggle();
+    }, { signal });
   },
 });
 ```
 
-## Feature Registry
-
-Each store maintains `features: ReadonlyMap<symbol, AnyFeature>` keyed by `feature.id`. Used by `hasFeature()` — see [primitives.md](primitives.md).
-
-## State Unification
-
-`createPlayer` merges both stores into a unified API:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                      usePlayer()                         │
-│                                                          │
-│   Media State          Player State         Requests     │
-│   ───────────          ────────────         ────────     │
-│   paused               isFullscreen         play()       │
-│   volume               isIdle               pause()      │
-│   currentTime          ...                  setVolume()  │
-│   ...                                       toggleFS()   │
-│                                             ...          │
-└─────────────────────────────────────────────────────────┘
-                            │
-                  Flattened via Proxy
-                            │
-              ┌─────────────┴─────────────┐
-              ▼                           ▼
-      Media Store                   Player Store
-```
-
-The proxy:
-
-1. Merges state from both stores
-2. Merges requests from both stores
-3. Tracks property access for fine-grained subscriptions
+The store handles looking up features across both stores transparently.
 
 ## Reactive System
 
-Proxy-based tracking (based on `SnapshotController`):
+Selector-based subscriptions via `useSyncExternalStore` (React) or ReactiveElement's update cycle (HTML).
 
-1. **Access** — Property access during render is tracked
-2. **Subscribe** — Tracker subscribes to changes on accessed keys
-3. **Update** — On change, trigger re-render
-4. **Next** — After render, finalize tracked keys for next cycle
+### Subscription Flow
 
-Works identically in React (`usePlayer()`) and Lit (`controller.value`).
+1. **Subscribe** — `usePlayer(feature, selector)` subscribes to store
+2. **Snapshot** — On change, `feature.getSnapshot()` called
+3. **Compare** — Selector result compared with `shallowEqual`
+4. **Update** — If different, trigger re-render
+
+### Feature Subscriptions
+
+When using `usePlayer(feature)`:
+
+1. Subscribe scoped to that feature's state keys
+2. Only re-render when that feature's state changes
+3. Other features updating don't cause re-render
+
+```ts
+// Only subscribes to playback state
+const playback = usePlayer(features.playback);
+
+// currentTime updates (time feature) don't affect this component
+```
 
 ## File Structure
 
 | Path                                     | Purpose                                      |
 | ---------------------------------------- | -------------------------------------------- |
+| `packages/store/src/`                    | Core store, features, selectors              |
 | `packages/core/src/dom/features/media/`  | Media features (playback, volume, time)      |
 | `packages/core/src/dom/features/player/` | Player features (fullscreen, keyboard, idle) |
-| `packages/html/src/`                     | Lit player + presets/skins                   |
-| `packages/react/src/`                    | React player + presets/skins                 |
-
-## Player Features
-
-| Feature        | Description                                    |
-| -------------- | ---------------------------------------------- |
-| **Fullscreen** | Container fullscreen with iOS media fallback   |
-| **Idle**       | Tracks user activity for auto-hide UI          |
-| **Keyboard**   | Maps keys to requests (`Space` → `togglePlay`) |
-| **Gestures**   | Touch gestures (double-tap seek, swipe volume) |
+| `packages/html/src/`                     | HTML player + skins                          |
+| `packages/react/src/`                    | React player + skins                         |
 
 ## Progressive Complexity
 
 | Level           | Example                                         | Sees internal stores? |
 | --------------- | ----------------------------------------------- | --------------------- |
-| Use skin        | `<FrostedSkin>`                                 | No                    |
-| Use preset      | `createPlayer(presets.website)`                 | No                    |
-| Custom features | `createPlayer([...presets.website, myFeature])` | No                    |
-| Use hooks       | `usePlayer()`                                   | No                    |
-| Write feature   | `createPlayerFeature({ ... })`                  | Yes (target.media)    |
+| Use skin        | `<VideoSkin>`                                   | No                    |
+| Use features    | `createPlayer({ features: [features.video] })`    | No                    |
+| Custom features | `createPlayer({ features: [..., myFeature] })`  | No                    |
+| Use hooks       | `usePlayer(features.playback)`                  | No                    |
+| Write feature   | `createPlayerFeature({ ... })`                  | Yes (store.get)       |
 
 Internal stores are implementation details until you author features.
 
 ## Constraints
 
-- Player features live in `@videojs/core/dom`
+- Media features live in `@videojs/core/dom/features/media`
+- Player features live in `@videojs/core/dom/features/player`
 - `createPlayer` lives in `@videojs/html` and `@videojs/react`
-- Skins are tied to presets — stores don't extend from skins
 - Two stores internally, one API externally
-- `hasFeature`, `getFeature`, `throwMissingFeature`, `subscribe` are framework-agnostic (from `@videojs/store`)
+- `store.get()` and `store.has()` are the feature access primitives
diff --git a/rfc/player-api/decisions.md b/rfc/player-api/decisions.md
index 3c31c51b..cc5d73a1 100644
--- a/rfc/player-api/decisions.md
+++ b/rfc/player-api/decisions.md
@@ -2,283 +2,216 @@
 
 Rationale behind Player API design choices.
 
+## Problem
+
+Original direction used use-case presets as the primary abstraction:
+
+```html
+<website-video-player>
+  <website-frosted-video-skin>
+    <hls-video src="...">
+  </website-frosted-video-skin>
+</website-video-player>
+```
+
+### Issues
+
+1. **Verbose for common case** — most people just want "a video player"
+2. **Opaque naming** — "website" means nothing without context
+3. **Mental model mismatch** — Devs think "I need a video player... then adaptive... then ads", not "I need a news player"
+4. **Preset/skin/media relationship unclear** — If you use `website` preset but `<hls-video>`, does the skin show quality controls?
+5. **Use-cases are just feature combos** — News = default + ads. Why make it a separate concept?
+6. **Feature/skin pairing unclear** — Does `streaming-video-skin` strictly require streaming features?
+7. **Default was hidden** — "website" was default but not obvious
+8. **Configuration vs composition** — Presets are "pick one". Features are "add what you need". Composition scales better.
+9. **Presets hid what's inside** — "website" bundles player + features, not transparent
+10. **Not self-documenting** — User doesn't see what's included without checking docs
+11. **Presets might make sense at a higher layer** — e.g., Mux could bundle features as presets for their customers
+
+### Core Insight
+
+Presets aren't the primary abstraction. **Features are.**
+
+Player is simple. Features are additive. Skins adapt.
+
+## Features over Presets
+
+**Decision:** Features are the primary abstraction, not presets.
+
+Features match the mental model: start simple, add what you need.
+
+## Selectors (No Proxy Tracking)
+
+**Decision:** Use explicit selectors for state subscriptions.
+
+```tsx
+// Selector-based
+const paused = usePlayer(features.playback, s => s.paused);
+```
+
+**Rationale:**
+
+- **Explicit** — You control what you subscribe to
+- **Predictable** — No magic tracking, clear performance characteristics
+- **Standard** — Matches Zustand, Redux Toolkit patterns
+
+**Trade-off:** More ceremony than proxy tracking, but no surprises.
+
+## shallowEqual for Object Selectors
+
+**Decision:** Object selector results compared with `shallowEqual`.
+
+```tsx
+const state = usePlayer(s => ({ paused: s.paused, volume: s.volume }));
+// Re-renders only when paused OR volume changes
+```
+
+**Rationale:**
+
+- Selectors often return objects for convenience
+- Without shallow comparison, new object = new reference = re-render
+- `shallowEqual` exported from `@videojs/store` for custom use
+
+## Feature Keys
+
+**Decision:** Features can have custom symbol keys with type-carrying.
+
+```ts
+const PLAYBACK_KEY = Symbol.for('@videojs/playback');
+export const playbackKey: FeatureKey<typeof playbackFeature> = PLAYBACK_KEY;
+```
+
+**Rationale:**
+
+- **Smaller imports** — Import just the key, not the feature definition
+- **Cross-realm** — `Symbol.for()` works across module boundaries
+- **Type inference** — `FeatureKey<F>` carries feature type for `store.get()`
+
+## usePlayer Overloads
+
+**Decision:** Single hook with multiple overloads.
+
+```tsx
+usePlayer(feature)           // Full feature slice
+usePlayer(feature, selector) // Selected value from feature
+usePlayer(selector)          // Selected value from all state
+```
+
+**Rationale:**
+
+- **Single hook** — Less API surface to learn
+- **Progressive** — Start simple, add selector for performance
+- **Consistent** — Same pattern for feature access and selection
+
+**Why no array support?** Call `usePlayer` multiple times. Simpler, explicit.
+
+```tsx
+const playback = usePlayer(features.playback);
+const volume = usePlayer(features.volume);
+```
+
+## Feature Returns Undefined, Not Throws
+
+**Decision:** `usePlayer(feature)` returns `Slice | undefined`, doesn't throw.
+
+**Rationale:**
+
+- Primitives need graceful handling — they don't know user's feature config
+- Throwing would break apps when features are misconfigured
+- Caller decides how to handle: return null, show fallback, throw themselves
+
+## store.get / store.has
+
+**Decision:** Use `store.get()` and `store.has()` for feature access in feature context.
+
+```ts
+subscribe: ({ store }) => {
+  const playback = store.get(features.playback);
+  if (store.has('time')) { /* ... */ }
+}
+```
+
+**Rationale:**
+
+- **Map-like** — Familiar pattern, `.get()` returns `T | undefined`
+- **Unified** — Same API for feature reference, key, or name
+- **Cross-store** — Abstracts which store a feature lives on
+
+## No Store Merge
+
+**Decision:** Keep two stores internally (media + player).
+
+**Rationale:**
+
+- Different targets (media element vs container)
+- Different attachment timing
+- `store.get()` abstracts cross-store access
+- Feature authors use same API regardless of store
+
+**Trade-off:** Internal complexity, but hidden from users.
+
 ## Naming
 
-### `createPlayer` / `createMedia` (not `createPlayerStore` / `createMediaStore`)
-
-**Decision:** Use `createPlayer` and `createMedia` — don't expose "store" in the primary API.
-
-**Rationale:**
+### createPlayer (not createPlayerStore)
 
 - Users want a player, not a store
-- "Store" is an implementation detail — complexity should grow with use case
-- Progressive disclosure: simple concept first, internals when authoring features
-- Returns stay clean: `Provider`, `usePlayer` (not `StoreProvider`, `usePlayerStore`)
+- "Store" is implementation detail
+- Matches ecosystem: `createContext`, `createRoot`, `createBrowserRouter`
 
-**"But we're not creating a player?"** — This matches React ecosystem conventions where `create*` means "create the infrastructure for X":
+### features (not slices)
 
-| Factory                 | Returns                                                 |
-| ----------------------- | ------------------------------------------------------- |
-| `createContext()`       | `{ Provider, Consumer }` — not "a context"              |
-| `createRoot()`          | `{ render, unmount }` — not "a root"                    |
-| `createBrowserRouter()` | Config for `<RouterProvider>` — not "a router"          |
-| `createTRPCReact()`     | `{ Provider, hooks }` — not "a tRPC"                    |
-| `createMachine()`       | Machine definition — needs actor to run                 |
-| **`createPlayer()`**    | `{ Provider, usePlayer }` — infrastructure for a player |
+- "Slice" implies Redux mental model (store owns state, reducers modify)
+- Our pattern: target owns state, features observe and request
+- "Feature" matches user mental model: "I want the fullscreen feature"
 
-The pattern is established: `create*` returns building blocks, not a usable instance.
+### MediaElement (not VjsElement)
 
-### `features` (not `slices`)
+- Clearer purpose — base class for media UI primitives
+- No `vjs-` prefix in new naming convention
 
-**Decision:** Rename from "slices" to "features" everywhere (user-facing AND internal).
+## Element Naming (HTML)
+
+**Decision:** No `vjs-` prefix. Pattern-based naming.
+
+| Layer  | Pattern                  | Examples                          |
+| ------ | ------------------------ | --------------------------------- |
+| Player | `<{mediatype}-player>`   | `<video-player>`, `<audio-player>` |
+| Skin   | `<{mediatype}-skin>`     | `<video-skin>`                    |
+| Media  | `<{source}-{mediatype}>` | `<hls-video>`, `<dash-video>`     |
+| UI     | `<media-{component}>`    | `<media-play-button>`             |
 
 **Rationale:**
 
-Our pattern is fundamentally different from Redux Toolkit slices:
+- Self-documenting — element name tells you what it is
+- Consistent — every name ends in its object type
+- No vendor prefix — cleaner, less typing
 
-| Aspect          | Redux "slice"          | Our pattern                               |
-| --------------- | ---------------------- | ----------------------------------------- |
-| State ownership | Store owns state       | Target owns state (HTMLMediaElement)      |
-| State mutation  | Reducers modify state  | Requests mutate target, snapshot reflects |
-| Mental model    | "A slice of the store" | "A feature I'm enabling"                  |
+## Adaptive Skins
 
-Our concept is:
+**Decision:** Default skin adapts to available features.
 
-- **Observer/Adapter** — binds store to external source of truth
-- **Feature module** — bundles related state + requests
-- **Binding** — connects reactive state to DOM element
-
-"Feature" maps to user mental models:
-
-- "I want the fullscreen feature"
-- "Add the keyboard feature"
-- "This preset includes playback, volume, and time features"
-
-Calling it "slice" creates false expectations from Redux users.
-
-### `createPlayerFeature` / `createMediaFeature` (not `createSlice`)
-
-**Decision:** Use explicit factory names: `createPlayerFeature` and `createMediaFeature`.
-
-**Alternatives considered:**
-
-- `createFeature<PlayerTarget>()` — generic with type parameter (rejected: curried call, less clear intent)
-- `createFeature` — simpler but ambiguous
-
-**Rationale:**
-
-- Clearer intent — you know what you're creating
-- Simpler call signature — no curried type parameter
-- Matches `createPlayer` naming pattern
-- Explicit is better than implicit
-
-### Simple Provider Naming
-
-**Decision:** Keep `Provider`, not `PlayerProvider`.
-
-**Rationale:**
-
-- Scoped by `createPlayer()` call — context is already clear
-- Less ceremony for the common case
-- If someone needs multiple providers (rare), they can alias:
-  ```ts
-  const { Provider: VideoProvider } = createPlayer(...);
-  ```
-
-## API Shape
-
-### Flat `usePlayer` Return
-
-**Decision:** Return flattened object with state and requests at same level, no `.state`/`.request` namespaces.
-
-```tsx
-// Before (considered)
-const player = usePlayer();
-player.state.paused;
-player.request.play();
-
-// After (chosen)
-const player = usePlayer();
-player.paused;
-player.play();
+```html
+<video-skin>  <!-- shows quality menu only if streaming feature loaded -->
 ```
 
 **Rationale:**
 
-- Less nesting = less typing
-- Proxy-based tracking works at property access level
-- Naming convention prevents collisions (state = nouns, requests = verbs)
+- DX — import features, skin "just works"
+- Progressive — add features, UI adapts
+- Named skins for specific variants (minimal, cinematic)
 
-**Trade-off:** Requires runtime duplicate detection. If a feature defines state `foo` and another defines request `foo`, throw at creation time.
+## Feature Bundles Are Sugar
 
-### Proxy-Based Tracking (No Selectors)
-
-**Decision:** Use proxy-based automatic tracking instead of selector functions.
-
-```tsx
-// Before (selector approach)
-const paused = usePlayer((s) => s.paused);
-
-// After (proxy tracking)
-const player = usePlayer();
-player.paused; // accessing subscribes automatically
-```
-
-**Rationale:**
-
-- Simpler API — no selector functions to write
-- Automatic fine-grained subscriptions
-- Matches modern patterns (Valtio, MobX)
-- Works with flattened return (proxy tracks which properties accessed)
-
-**Implementation:** Based on existing `SnapshotController` pattern using `track()`.
-
-### PlayerController Uses `.value`
-
-**Decision:** Access player state/requests via `.value` property (like `SnapshotController`).
+**Decision:** Bundles like `features.video` are convenience, not required.
 
 ```ts
-class MyComponent extends VjsElement {
-  #player = new PlayerController(this);
-
-  render() {
-    const { paused, play } = this.#player.value;
-    // ...
-  }
-}
+// These are equivalent:
+features.video
+[features.playback, features.volume, features.time, features.presentation, features.userActivity, /* ... */]
 ```
 
 **Rationale:**
 
-- Consistent with `SnapshotController` API
-- `.value` returns tracking proxy
-- Property access during render auto-subscribes
-- No `watch()` method needed — proxy handles tracking
-
-### Keep Shorthand Config
-
-**Decision:** Support both shorthand and config object forms.
-
-```ts
-// Shorthand — common case
-createPlayer(presets.website);
-createPlayer([features.playback, features.fullscreen]);
-
-// Config object — extensibility
-createPlayer({
-  features: presets.website,
-  // future: devTools, middleware, etc.
-});
-```
-
-**Rationale:**
-
-- Shorthand is the 90% case — don't penalize it
-- Config object enables future extensibility without API changes
-- Progressive disclosure: simple → extensible
-
-**Feedback addressed:** "Doing things too many ways can be rough" — but these aren't competing APIs, they're progressive complexity levels.
-
-## Escape Hatches
-
-### Keep `useMedia`
-
-**Decision:** Keep `useMedia` as escape hatch for direct media access.
-
-**Rationale:**
-
-- Progressive disclosure — 95% of users never need it
-- Costs nothing if unused
-- Saves advanced users when they need raw media state
-- Debugging scenarios: compare player vs media fullscreen state
-
-```tsx
-function DebugPanel() {
-  const player = usePlayer();
-  const media = useMedia();
-
-  // Player may abstract/transform media state
-  // Sometimes you need the raw value
-  console.log({ playerFS: player.isFullscreen, mediaFS: media.isFullscreen });
-}
-```
-
-## Architecture
-
-### Two Stores (Not One)
-
-**Decision:** Maintain two internal stores (Media Store + Player Store). See [architecture.md](architecture.md) for details.
-
-**Trade-off:** Two stores exist internally, but feature authors access media via `target.media` proxy — same flat API as components.
-
-### Container ≠ Provider
-
-**Decision:** Container is purely UI attachment. Provider owns state.
-
-## Validation
-
-### Runtime Duplicate Key Detection
-
-**Decision:** Throw at `createPlayer` time if state/request keys collide.
-
-```ts
-// This should throw
-const bad = createPlayerFeature({
-  initialState: { play: false }, // "play" as state
-  request: { play: () => {} }, // "play" as request — collision!
-});
-```
-
-**Rationale:**
-
-- Flat namespace requires disambiguation
-- Fail fast at creation, not at runtime access
-- Clear error message: "Duplicate key 'play' found in state and requests"
-
-## Primitives API
-
-See [primitives.md](primitives.md) for types, examples, and package exports.
-
-### `hasFeature`, `getFeature`, `throwMissingFeature`
-
-**Decision:** Three utilities for feature access — type guard, optional access, and fail-fast.
-
-**Rationale:**
-
-- `hasFeature` — Standard TypeScript type guard pattern, narrows proxy in place
-- `getFeature` — Properties as `T | undefined`, works with optional chaining
-- `throwMissingFeature` — Surfaces misconfiguration immediately (silent `return null` hides bugs)
-
-### `StoreProxy<T>` and `UnknownPlayer`
-
-**Decision:** Generic `StoreProxy<T>` interface that all proxies implement.
-
-**Rationale:**
-
-- Preserves store type through the proxy
-- Index signature `[key: string]: unknown` allows any property access
-- Uses interfaces (not type aliases) for clearer hover hints
-
-### `target.media` as Flat Proxy
-
-**Decision:** `PlayerTarget.media` is an `UnknownMedia` proxy, not a store.
-
-**Rationale:**
-
-- Consistent API — feature authors and component authors use same flat access pattern
-- No `.state`/`.request` namespacing to learn
-- Simpler `hasFeature`/`getFeature` — only one signature (StoreProxy)
-
-## Open Questions
-
-### "In-between" Functionality
-
-Where does functionality that's not clearly media or UI go?
-
-Examples needed to clarify boundary.
-
-### Feature Author Experience
-
-How many concepts must authors learn? Current: Target types, state, requests, subscribe pattern.
-
-Is this the right level of complexity for the extension story?
+- Bundles reduce API surface — fewer imports for common cases
+- Granular still available — full control when needed
+- Upgrade path — add to bundle, users get it automatically
diff --git a/rfc/player-api/examples.md b/rfc/player-api/examples.md
index dbb95c79..87303173 100644
--- a/rfc/player-api/examples.md
+++ b/rfc/player-api/examples.md
@@ -1,223 +1,392 @@
 # Examples
 
-Usage examples for React, HTML, and Lit.
+Progressive journey from simple to fully custom.
 
-> [!NOTE]
-> Some examples here are for demonstration. In practice, UI primitives like `<PlayButton>`, `<VolumeSlider>`, etc. would be provided.
+## 1. It Works (Minimal)
 
-For primitive authoring examples (using `hasFeature`, `UnknownPlayer`, etc.), see [primitives.md](primitives.md).
-
-## React
-
-### Declarative (Skin)
+### React
 
 ```tsx
-import { createPlayer, presets, Video } from '@videojs/react';
-import { FrostedSkin } from '@videojs/react/presets/website';
+import { createPlayer, features } from '@videojs/react';
 
-const { Provider } = createPlayer(presets.website);
-
-function App() {
-  return (
-    <Provider>
-      <FrostedSkin>
-        <Video src="video.mp4" />
-      </FrostedSkin>
-    </Provider>
-  );
-}
-```
-
-### Custom Player
-
-```tsx
-import { createPlayer, presets, Video } from '@videojs/react';
-
-const { Provider, Container, usePlayer } = createPlayer(presets.website);
-
-function App() {
-  return (
-    <Provider>
-      <Container>
-        <Video src="video.mp4" />
-        <Controls />
-      </Container>
-    </Provider>
-  );
-}
-
-function Controls() {
-  const player = usePlayer();
-
-  // Hook usage example only, you would use `PlayButton`
-  return <button onClick={player.paused ? player.play : player.pause}>{player.paused ? 'Play' : 'Pause'}</button>;
-}
-```
-
-### Extended Preset
-
-```tsx
-import { createPlayer, features, presets } from '@videojs/react';
-
-const { Provider, usePlayer } = createPlayer({
-  features: [...presets.website, features.keyboard],
+const { Provider: VideoProvider, Container: VideoContainer, usePlayer } = createPlayer({
+  features: [features.video]
 });
+
+function App() {
+  return (
+    <VideoProvider>
+      <VideoContainer>
+        <video src="video.mp4" />
+        {/* Custom UI */}
+      </VideoContainer>
+    </VideoProvider>
+  );
+}
 ```
 
-### Custom Feature
+### HTML
+
+```ts
+import '@videojs/html/player/video'; // includes features.video
+```
+
+```html
+<video-player>
+  <video src="video.mp4">
+  <!-- Custom UI -->
+</video-player>
+```
+
+## 2. It's Pretty (Add Skin)
+
+### React
 
 ```tsx
-import { createPlayer, createPlayerFeature, presets } from '@videojs/react';
+import '@videojs/react/skin/video.css';
 
-// Example of how you can create your own feature, pip would be provided.
-const pip = createPlayerFeature({
-  initialState: { active: false },
-  getSnapshot: ({ target }) => ({
-    active: document.pictureInPictureElement === target.media.element,
-  }),
-  subscribe: ({ update, signal }) => {
-    document.addEventListener('enterpictureinpicture', update, { signal });
-    document.addEventListener('leavepictureinpicture', update, { signal });
+import { createPlayer, features } from '@videojs/react';
+import { VideoSkin } from '@videojs/react/skin/video';
+
+const { Provider: VideoProvider } = createPlayer({
+  features: [features.video]
+});
+
+function App() {
+  return (
+    <VideoProvider>
+      <VideoSkin>
+        <video src="video.mp4" />
+      </VideoSkin>
+    </VideoProvider>
+  );
+}
+```
+
+### HTML
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+```
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4">
+  </video-skin>
+</video-player>
+```
+
+## 3. I Need a Feature (Chapters)
+
+Skin detects chapters feature, shows chapter menu.
+
+### React
+
+```tsx
+import { createPlayer, features } from '@videojs/react';
+import '@videojs/react/skin/video.css';
+import { VideoSkin } from '@videojs/react/skin/video';
+
+const { Provider: VideoProvider } = createPlayer({
+  features: [features.video, features.chapters]
+});
+
+function App() {
+  return (
+    <VideoProvider>
+      <VideoSkin>
+        <video src="video.mp4" />
+      </VideoSkin>
+    </VideoProvider>
+  );
+}
+```
+
+### HTML
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/feature/chapters';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+```
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4">
+  </video-skin>
+</video-player>
+```
+
+## 4. I Need Streaming (HLS)
+
+Skin detects streaming features, shows quality/tracks menus.
+
+### React
+
+```tsx
+import { createPlayer, features } from '@videojs/react';
+import { HlsVideo } from '@videojs/react/media/hls';
+import '@videojs/react/skin/video.css';
+import { VideoSkin } from '@videojs/react/skin/video';
+
+const { Provider: VideoProvider } = createPlayer({
+  features: [features.video, features.streaming]
+});
+
+function App() {
+  return (
+    <VideoProvider>
+      <VideoSkin>
+        <HlsVideo src="stream.m3u8" />
+      </VideoSkin>
+    </VideoProvider>
+  );
+}
+```
+
+### HTML
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/feature/streaming';
+import '@videojs/html/media/hls-video';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+```
+
+```html
+<video-player>
+  <video-skin>
+    <hls-video src="stream.m3u8">
+  </video-skin>
+</video-player>
+```
+
+## 5. I Need Ads
+
+Same skin adapts to show ad UI.
+
+### React
+
+```tsx
+import { createPlayer, features } from '@videojs/react';
+import { HlsVideo } from '@videojs/react/media/hls';
+import '@videojs/react/skin/video.css';
+import { VideoSkin } from '@videojs/react/skin/video';
+
+const { Provider: VideoProvider } = createPlayer({
+  features: [features.video, features.streaming, features.ads]
+});
+
+function App() {
+  return (
+    <VideoProvider>
+      <VideoSkin>
+        <HlsVideo src="stream.m3u8" />
+      </VideoSkin>
+    </VideoProvider>
+  );
+}
+```
+
+### HTML
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/feature/streaming';
+import '@videojs/html/feature/ads';
+import '@videojs/html/media/hls-video';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+```
+
+## 6. Full Custom (Escape Hatch)
+
+### React
+
+```tsx
+import { createPlayer, features } from '@videojs/react';
+import { HlsVideo } from '@videojs/react/media/hls';
+
+const myAnalytics = createMediaFeature({
+  name: 'analytics',
+  initialState: {},
+  subscribe: ({ store, signal }) => {
+    // Custom analytics logic
   },
   request: {
-    enterPip: (_, { target }) => target.media.element.requestPictureInPicture(),
-    exitPip: () => document.exitPictureInPicture(),
+    trackEvent: (name) => console.log(name),
   },
 });
 
-const { Provider, usePlayer } = createPlayer({
-  features: [...presets.website, pip],
-});
-```
-
-### Media Escape Hatch
-
-Direct media access when player features don't expose what you need.
-
-```tsx
-const { usePlayer, useMedia } = createPlayer(presets.website);
-
-function DebugPanel() {
-  const player = usePlayer();
-  const media = useMedia();
-
-  // player.isFullscreen vs media.isFullscreen (raw)
-}
-```
-
-### Headless (No UI)
-
-```tsx
-import { createMedia, features } from '@videojs/react';
-
-const { Provider, useMedia } = createMedia([features.playback, features.time]);
-
-function AudioPlayer() {
-  const media = useMedia();
-  // Programmatic control, no UI
-}
-```
-
-## HTML
-
-### Declarative (Skin)
-
-```html
-<script type="module" src="@videojs/html/presets/website/skins/frosted.js"></script>
-
-<vjs-website-provider>
-  <vjs-frosted-skin>
-    <video src="video.mp4"></video>
-  </vjs-frosted-skin>
-</vjs-website-provider>
-```
-
-### Custom Provider
-
-```ts
-import { createPlayer, presets } from '@videojs/html';
-
-const { ProviderElement } = createPlayer(presets.website);
-
-customElements.define('my-provider', ProviderElement);
-```
-
-```html
-<my-provider>
-  <video src="video.mp4"></video>
-</my-provider>
-```
-
-### Extended Preset
-
-```ts
-import { createPlayer, features, presets } from '@videojs/html';
-
-const { ProviderElement } = createPlayer({
-  features: [...presets.website, features.keyboard],
+const { Provider: VideoProvider, Container: VideoContainer, usePlayer } = createPlayer({
+  features: [features.video, features.streaming, myAnalytics]
 });
 
-customElements.define('my-provider', ProviderElement);
-```
-
-### Split Provider/Container
-
-When media element and container need different DOM locations.
-
-```ts
-import { createPlayer, presets, VjsElement } from '@videojs/html';
-
-const { ProviderMixin, ContainerMixin } = createPlayer(presets.website);
-
-class MyProvider extends ProviderMixin(VjsElement) {}
-class MyContainer extends ContainerMixin(VjsElement) {}
-
-customElements.define('my-provider', MyProvider);
-customElements.define('my-container', MyContainer);
-```
-
-```html
-<my-provider>
-  <video src="video.mp4"></video>
-  <my-container>...</my-container>
-</my-provider>
-```
-
-### Headless (No UI)
-
-```ts
-import { createMedia, features, VjsElement } from '@videojs/html';
-
-const { ProviderMixin } = createMedia([features.playback, features.time]);
-
-class AudioController extends ProviderMixin(VjsElement) {
-  // Programmatic control
+function App() {
+  return (
+    <VideoProvider>
+      <VideoContainer>
+        <HlsVideo src="stream.m3u8" />
+        <MyCustomSkin />
+      </VideoContainer>
+    </VideoProvider>
+  );
 }
 
-customElements.define('audio-controller', AudioController);
+function MyCustomSkin() {
+  const playback = usePlayer(features.playback);
+  const time = usePlayer(features.time);
+  const analytics = usePlayer(myAnalytics);
+
+  if (!playback || !time) return null;
+
+  return (
+    <div className="my-skin">
+      <button onClick={playback.toggle}>
+        {playback.paused ? 'Play' : 'Pause'}
+      </button>
+      <span>{time.currentTime} / {time.duration}</span>
+    </div>
+  );
+}
 ```
 
-## Lit
-
-### PlayerController
+### HTML
 
 ```ts
-import { html } from 'lit';
+import { createPlayer, features, MediaElement } from '@videojs/html';
 
-import { createPlayer, presets, VjsElement } from '@videojs/html';
+const { PlayerElement, PlayerController } = createPlayer({
+  features: [features.video, features.streaming, myCustomFeature]
+});
 
-const { PlayerController } = createPlayer(presets.website);
+// Define player element
+customElements.define('my-video-player', PlayerElement);
 
-class PlayButton extends VjsElement {
-  #player = new PlayerController(this);
+// Custom play button — host is the button
+class MyPlayButton extends MediaElement {
+  #playback = new PlayerController(this, features.playback);
 
-  render() {
-    const { paused, play, pause } = this.#player.value;
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#handleClick);
+  }
 
-    // Controller usage example only, you would use `PlayButton`
-    return html`<button @click=${paused ? play : pause}>${paused ? 'Play' : 'Pause'}</button>`;
+  #handleClick = () => {
+    this.#playback.value?.toggle();
+  };
+
+  override update() {
+    const playback = this.#playback.value;
+    if (!playback) return;
+
+    this.textContent = playback.paused ? 'Play' : 'Pause';
   }
 }
 
-customElements.define('play-button', PlayButton);
+customElements.define('my-play-button', MyPlayButton);
 ```
+
+```html
+<my-video-player>
+  <hls-video src="stream.m3u8"></hls-video>
+  <my-play-button></my-play-button>
+</my-video-player>
+```
+
+## 7. Configure Media Engine
+
+### HTML
+
+```html
+<hls-video
+  src="stream.m3u8"
+  buffer-size="30"
+  abr-strategy="bandwidth"
+>
+```
+
+### React
+
+```tsx
+<HlsVideo
+  src="stream.m3u8"
+  bufferSize={30}
+  abrStrategy="bandwidth"
+  onManifestLoaded={() => {}}
+/>
+```
+
+## 8. Headless (No UI)
+
+### React
+
+```tsx
+import { createPlayer, features } from '@videojs/react';
+
+const { Provider: VideoProvider, usePlayer } = createPlayer({
+  features: [features.playback, features.time]
+});
+
+function AudioController() {
+  const playback = usePlayer(features.playback);
+  const time = usePlayer(features.time);
+
+  // Programmatic control, no UI
+  useEffect(() => {
+    if (time && time.currentTime > 60) {
+      playback?.pause();
+    }
+  }, [time?.currentTime]);
+
+  return <audio src="audio.mp3" />;
+}
+```
+
+## 9. Using Selectors
+
+### Performance-Optimized Access
+
+```tsx
+function TimeDisplay() {
+  // Only re-renders when currentTime changes
+  const currentTime = usePlayer(features.time, s => s.currentTime);
+
+  if (currentTime === undefined) return null;
+
+  return <span>{formatTime(currentTime)}</span>;
+}
+```
+
+### Derived Values
+
+```tsx
+function PlayState() {
+  // Derived value, re-renders when paused OR ended changes
+  const isPlaying = usePlayer(features.playback, s => !s.paused && !s.ended);
+
+  if (isPlaying === undefined) return null;
+
+  return <span>{isPlaying ? 'Playing' : 'Stopped'}</span>;
+}
+```
+
+### Cross-Feature Selection
+
+```tsx
+function DebugPanel() {
+  // Global selector across all features
+  const debug = usePlayer(s => ({
+    paused: s.paused,
+    currentTime: s.currentTime,
+    volume: s.volume,
+  }));
+
+  return <pre>{JSON.stringify(debug, null, 2)}</pre>;
+}
diff --git a/rfc/player-api/features.md b/rfc/player-api/features.md
new file mode 100644
index 00000000..4f6cfb1c
--- /dev/null
+++ b/rfc/player-api/features.md
@@ -0,0 +1,206 @@
+# Features
+
+Features are the primary abstraction. They bundle related state and requests.
+
+## Feature Definition
+
+### createFeature
+
+```ts
+import { createFeature } from '@videojs/store';
+
+const playbackFeature = createFeature<HTMLMediaElement>()({
+  name: 'playback',
+
+  initialState: { 
+    paused: true, 
+    ended: false 
+  },
+
+  getSnapshot: ({ target }) => ({
+    paused: target.paused,
+    ended: target.ended,
+  }),
+
+  subscribe: ({ target, update, signal }) => {
+    target.addEventListener('play', update, { signal });
+    target.addEventListener('pause', update, { signal });
+    target.addEventListener('ended', update, { signal });
+  },
+
+  request: {
+    play: (_, { target }) => target.play(),
+    pause: (_, { target }) => target.pause(),
+    toggle: (_, { target }) => target.paused ? target.play() : target.pause(),
+  },
+});
+```
+
+### Config Properties
+
+| Property       | Type                          | Description                              |
+| -------------- | ----------------------------- | ---------------------------------------- |
+| `key`          | `symbol` (optional)           | Unique identifier. Auto-generated if not provided. |
+| `name`         | `string`                      | Human-readable name for debugging        |
+| `initialState` | `object`                      | Initial state before target attached     |
+| `getSnapshot`  | `(ctx) => State`              | Derive state from target                 |
+| `subscribe`    | `(ctx) => void`               | Set up subscriptions, call `update()` on changes |
+| `request`      | `Record<string, RequestHandler>` | Actions that modify target           |
+
+### Context Object
+
+Both `getSnapshot`, `subscribe`, and `request` handlers receive a context:
+
+```ts
+interface FeatureContext {
+  target: Target;        // HTMLMediaElement or PlayerTarget
+  store: Store;          // Access other features via store.get()
+  signal: AbortSignal;   // For cleanup (subscribe only)
+  update: () => void;    // Trigger re-snapshot (subscribe only)
+}
+```
+
+## Feature Keys
+
+Features can define a custom key for identity and type-carrying.
+
+### Pattern
+
+```ts
+// Define key
+const PLAYBACK_KEY = Symbol.for('@videojs/playback');
+
+// Create feature with key
+const playbackFeature = createFeature({
+  key: PLAYBACK_KEY,
+  name: 'playback',
+  // ...
+});
+
+// Export typed key
+export const playbackKey: FeatureKey<typeof playbackFeature> = PLAYBACK_KEY;
+
+// Export feature
+export { playbackFeature };
+```
+
+### Usage
+
+```ts
+// Import just the key (smaller bundle, no feature code)
+import { playbackKey } from '@videojs/core/features';
+
+// Typed access
+const playback = store.get(playbackKey); // PlaybackSlice | undefined
+```
+
+### FeatureKey Type
+
+```ts
+// Type carrier — key holds the feature's type info
+type FeatureKey<F extends Feature> = symbol & { __feature?: F };
+```
+
+### Why Keys?
+
+1. **Smaller imports** — Import just the key when you don't need the feature definition
+2. **Cross-realm identity** — `Symbol.for()` works across module boundaries
+3. **Type inference** — `FeatureKey<F>` carries the feature type for `store.get()`
+## Feature Bundles
+
+Bundles are sugar for common feature combinations.
+
+### Base Bundles
+
+```ts
+// Video player base
+features.video = [
+  features.playback,
+  features.volume,
+  features.time,
+  features.presentation,
+  features.userActivity,
+];
+
+// Audio player base
+features.audio = [
+  features.playback,
+  features.volume,
+  features.time,
+];
+```
+
+### Additional Bundles (Beta+)
+
+```ts
+features.streaming = [
+  features.qualitySelection,
+  features.audioTracks,
+  features.textTracks,
+];
+
+features.ads = [
+  features.adMarkers,
+  features.adSkip,
+  features.adCountdown,
+];
+
+features.live = [
+  features.liveIndicator,
+  features.lowLatency,
+  features.seekToLive,
+  features.dvr,
+];
+```
+
+### Granular vs Bundled
+
+```ts
+// Granular — import individual features
+import '@videojs/html/feature/quality-selection';
+import '@videojs/html/feature/audio-tracks';
+
+// Bundled — sugar for above + more
+import '@videojs/html/feature/streaming';
+```
+
+### Extending Bundles
+
+```ts
+createPlayer({
+  features: [features.video, features.streaming, myCustomFeature]
+});
+```
+
+## Media vs Player Features
+
+### Media Features
+
+Target `HTMLMediaElement`. Handle playback, volume, time, etc.
+
+```ts
+const volumeFeature = createMediaFeature({
+  name: 'volume',
+  initialState: { 
+    volume: 1, 
+    muted: false 
+  },
+  getSnapshot: ({ target }) => ({
+    volume: target.volume,
+    muted: target.muted,
+  }),
+  // ...
+});
+```
+
+### Player Features
+
+Target the container element. Have access to media store via `store.get()`.
+
+```ts
+createPlayerFeature({
+  subscribe: ({ store, target, update, signal }) => {
+    // Access media features from player store
+    const playback = store.get(features.playback);
+});
+```
\ No newline at end of file
diff --git a/rfc/player-api/feedback.md b/rfc/player-api/feedback.md
new file mode 100644
index 00000000..efe9c538
--- /dev/null
+++ b/rfc/player-api/feedback.md
@@ -0,0 +1,68 @@
+# Feedback
+
+Collected feedback on the Player API design.
+
+## On Adaptive Skins
+
+**Feedback (@heff):**
+
+There's obvious features to me like VR controls, clipping interfaces, viewer heatmaps, even ads, that I don't think we should bundle into a default theme, even with lazy loading. Pieces of back pressure I see are:
+
+- Having to account for the UI of conflicting/competitive features, when they'd never be used together (maybe ad markers vs. clip markers as a rough example)
+- Having to account for all features turned on at once when in reality that would never happen. For example 10+ buttons in the control bar.
+- The file size of the no-bundler, cdn-hosted `<video-skin>`
+- People actually being able to work with the default skin after ejecting it, not being overwhelmed by a ton of features they didn't realize it supported.
+
+I would think we still aim for "website" use case in drawing the line for the default skin features. But interested to hear what features people would want added to that. e.g. Endscreen — included or not?
+## On Feature Bundles
+
+**Feedback (@luwes):**
+
+What is the main reason for wanting to add these presets or feature bundles immediately in alpha / beta versus having these presets documented, copy/paste and maybe CLI generated? It just seems a lot less risky to add this later, maybe with community engagement than confusing users right away with various embed methods. Feeling @Darius Cepulis worries as well... Also increasing API surface, more to learn etc.
+
+**Response:**
+
+Raising a really good point! I'm very much in the middle-ish and I can make arguments either way. What's tilting me towards keeping:
+
+1. We're not shipping all of these out of the gate. Just `video`, `audio` – `streaming` little further in beta. We can adjust based on feedback.
+2. In the same way `video-skin` abstracts away individual UI components, `features.video` abstracts away individual capabilities. Both are sensible defaults for the 80%. Both should be "ejectable".
+3. Upgrade path: add a new capability to `streaming`, users get it automatically.
+4. Bundles actually reduce API surface from the user's perspective. Fewer imports to remember, fewer things to get wrong.
+5. Testing internally will be easier to validate bundles as units than every possible combination.
+6. Bundles teach users which features belong together. Most people just want streaming to work – they don't need to know about individual features.
+7. I had concerns about CDN users juggling 10+ script tags, but HTTP/2 mostly invalidates the perf issue (I think?). It'd still be stressful having a code snippet with a whole bunch of script tags. It's a lot more elegant in a few lines.
+
+My gut says let's ship a conservative set early on (audio/video) and reassess based on feedback (internal/external).
+## On features.streaming
+
+**Feedback (@decepulis):**
+
+Consider the burden of education here. With presets, a dev didn't have to know what "adaptive streaming" is. Now they do. How do you think about this potential friction?
+
+**Response:**
+
+I think you're pointing at the fact that devs need to understand what "adaptive" means just to pull in the right import. I'm leaning towards "streaming" because it's intent-based, but really the goal is using terms that they're already feel familiar. It might be nice to alias `hls`/`dash` to `streaming` too – more likely someone knows that they have a HLS manifest but never heard of "adaptive streaming." We can play with this to find the right balance. Appreciate this one!
+## Open Questions
+
+### Default Skin Feature Set
+
+Where do we draw the line for features included in the default `<video-skin>`?
+
+Candidates:
+- Endscreen — included or not?
+- Chapters — included or not?
+- Quality menu — included (with streaming feature)?
+
+### CDN Bundle Strategy
+
+For no-bundler CDN usage:
+- Single mega-bundle with everything?
+- Separate bundles per feature?
+- Core + addons pattern?
+
+### Skin Ejection Experience
+
+How do we make ejected skins manageable?
+- Clear separation of feature-specific UI
+- Documentation of what each part does
+- Generator/CLI tooling?
diff --git a/rfc/player-api/html.md b/rfc/player-api/html.md
new file mode 100644
index 00000000..122c3df8
--- /dev/null
+++ b/rfc/player-api/html.md
@@ -0,0 +1,323 @@
+# HTML API
+
+HTML-specific concerns: element naming, imports, skins.
+
+## Element Naming
+
+| Layer  | Pattern                      | Examples                                       |
+| ------ | ---------------------------- | ---------------------------------------------- |
+| Player | `<{mediatype}-player>`       | `<video-player>`, `<audio-player>`             |
+| Skin   | `<{mediatype}-skin>`         | `<video-skin>`, `<minimal-video-skin>`         |
+| Media  | `<{source}-{mediatype}>`     | `<hls-video>`, `<dash-video>`, `<hls-audio>`   |
+| UI     | `<media-{component}>`        | `<media-play-button>`, `<media-slider>`        |
+
+### Special Players
+
+Only fundamentally different behaviors get their own player:
+
+```html
+<background-video-player>  <!-- no controls, autoplay, loop -->
+```
+
+## Import Paths
+
+### Player (includes base features)
+
+```ts
+import '@videojs/html/player/video';        // includes features.video
+import '@videojs/html/player/audio';        // includes features.audio
+import '@videojs/html/player/background-video';
+```
+
+### Features (additive)
+
+```ts
+import '@videojs/html/feature/streaming';
+import '@videojs/html/feature/ads';
+import '@videojs/html/feature/live';
+import '@videojs/html/feature/chapters';
+
+// Granular
+import '@videojs/html/feature/quality-selection';
+import '@videojs/html/feature/audio-tracks';
+import '@videojs/html/feature/text-tracks';
+```
+
+### Media
+
+```ts
+import '@videojs/html/media/hls-video';
+import '@videojs/html/media/hls-audio';
+import '@videojs/html/media/dash-video';
+```
+
+### Skins
+
+```ts
+// Default skin
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+
+// Named variants
+import '@videojs/html/skin/video/minimal.css';
+import '@videojs/html/skin/video/minimal';
+
+import '@videojs/html/skin/audio.css';
+import '@videojs/html/skin/audio';
+```
+
+### UI Primitives (for custom skins)
+
+```ts
+import '@videojs/html/ui/menu';
+import '@videojs/html/ui/radio-group';
+import '@videojs/html/ui/slider';
+```
+
+## Registration Models
+
+### Side-Effect Imports (Declarative)
+
+Elements register globally when imported:
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/skin/video';
+```
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4">
+  </video-skin>
+</video-player>
+```
+
+### createPlayer (Escape Hatch)
+
+For custom element names or full control:
+
+```ts
+import { createPlayer, features } from '@videojs/html';
+
+const { PlayerElement, PlayerController } = createPlayer({
+  features: [features.video, myCustomFeature]
+});
+
+customElements.define('my-video-player', PlayerElement);
+```
+
+```html
+<my-video-player>
+  <video src="video.mp4">
+</my-video-player>
+```
+
+### Split Provider/Container (Advanced)
+
+When media element and container need different DOM locations:
+
+```ts
+import { createPlayer, features } from '@videojs/html';
+
+const { ProviderElement, ContainerElement } = createPlayer({
+  features: [features.video]
+});
+
+customElements.define('my-video-provider', ProviderElement);
+customElements.define('my-video-container', ContainerElement);
+```
+
+```html
+<my-video-provider>
+  <video src="video.mp4">
+  <my-video-container>
+    <!-- Controls here, separate from media -->
+  </my-video-container>
+</my-video-provider>
+```
+
+## Skins
+
+### Adaptive Skins
+
+Default skin adapts to available features:
+
+```ts
+import '@videojs/html/player/video';
+import '@videojs/html/feature/streaming';  // skin will show quality menu
+import '@videojs/html/skin/video';
+```
+
+```html
+<video-skin>  <!-- adapts to used features -->
+```
+
+### Named Skins
+
+Specific UI compositions and style variants:
+
+```html
+<video-skin>           <!-- default style -->
+<minimal-video-skin>   <!-- stripped down -->
+<cinematic-video-skin> <!-- dark/immersive -->
+```
+
+### Skin Customization
+
+Default skin handles optional feature UI via lazy loading.
+
+**Ejected skin structure:**
+
+```
+skin/
+  video/
+    video-skin.ts
+    video-skin.css
+    features.ts
+```
+
+**features.ts:**
+
+```ts
+import { features } from '@videojs/html';
+
+// Lazy-define element for a feature
+// Shell element registers immediately, loads implementation when feature available
+features.lazy(
+  'qualitySelection',
+  () => import('./ui/quality-menu')
+);
+```
+
+## MediaElement Base Class
+
+Base class for UI primitives. The host element IS the control (e.g., `<media-play-button>` extends button behavior).
+
+```ts
+// src/ui/media-play-button.ts
+import { MediaElement, PlayerController, features } from '@videojs/html';
+
+export class MediaPlayButton extends MediaElement {
+  #playback = new PlayerController(this, features.playback);
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#handleClick);
+  }
+
+  #handleClick = () => {
+    this.#playback.value?.toggle();
+  };
+
+  override update() {
+    const playback = this.#playback.value;
+    if (!playback) return;
+
+    this.setAttribute('aria-pressed', String(!playback.paused));
+  }
+}
+```
+
+```ts
+// define/ui/media-play-button.ts (side-effect import)
+import { MediaPlayButton } from '../src/ui/media-play-button.js';
+
+customElements.define('media-play-button', MediaPlayButton);
+```
+
+**Usage:**
+
+```ts
+import '@videojs/html/ui/media-play-button';
+```
+
+## PlayerController
+
+Reactive controller for accessing player state. Triggers `update()` when subscribed feature changes.
+
+```ts
+import { PlayerController, features, MediaElement } from '@videojs/html';
+
+export class MediaVolumeSlider extends MediaElement {
+  #volume = new PlayerController(this, features.volume);
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('input', this.#handleInput);
+  }
+
+  #handleInput = (e: Event) => {
+    this.#volume.value?.setVolume(parseFloat((e.target as HTMLInputElement).value));
+  };
+
+  override update() {
+    const volume = this.#volume.value;
+    if (!volume) return;
+
+    // Host is the slider — update its value
+    (this as unknown as HTMLInputElement).value = String(volume.volume);
+  }
+}
+```
+
+### Controller API
+
+| Property | Returns              | Description                                |
+| -------- | -------------------- | ------------------------------------------ |
+| `value`  | `Slice \| undefined` | Feature slice, triggers update on change   |
+## Mixins
+
+For advanced customization when you need to extend behavior.
+
+### ProviderMixin
+
+```ts
+import { createPlayer, features, MediaElement } from '@videojs/html';
+
+const { ProviderMixin } = createPlayer({
+  features: [features.video]
+});
+
+class MyProvider extends ProviderMixin(MediaElement) {
+  // Custom provider logic
+}
+```
+
+### ContainerMixin
+
+```ts
+const { ContainerMixin } = createPlayer({
+  features: [features.video]
+});
+
+class MyContainer extends ContainerMixin(MediaElement) {
+  // Custom container logic
+}
+```
+
+## Full Example
+
+```ts
+// main.ts
+import '@videojs/html/player/video';
+import '@videojs/html/feature/streaming';
+import '@videojs/html/media/hls-video';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
+```
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module" src="main.ts"></script>
+</head>
+<body>
+  <video-player>
+    <video-skin>
+      <hls-video src="https://example.com/stream.m3u8"></hls-video>
+    </video-skin>
+  </video-player>
+</body>
+</html>
diff --git a/rfc/player-api/index.md b/rfc/player-api/index.md
index 9d1a8842..29344808 100644
--- a/rfc/player-api/index.md
+++ b/rfc/player-api/index.md
@@ -4,313 +4,108 @@ status: draft
 
 # Player API Design
 
-Unified API for Media and Container concerns. Two stores internally, one API for users.
+| Document                           | Purpose                                    |
+| ---------------------------------- | ------------------------------------------ |
+| [index.md](index.md)               | Overview, principles, model                |
+| [api.md](api.md)                   | Surface API (usePlayer, store, controller) |
+| [features.md](features.md)         | Feature definition, keys, bundles          |
+| [primitives.md](primitives.md)     | Library author patterns                    |
+| [architecture.md](architecture.md) | Two-store internals                        |
+| [decisions.md](decisions.md)       | Problem statement, design rationale        |
+| [examples.md](examples.md)         | Progressive journey examples               |
+| [html.md](html.md)                 | HTML elements, imports, skins              |
+| [feedback.md](feedback.md)         | Collected feedback                         |
 
-## Contents
+## Principles
 
-| Document                           | Purpose                                  |
-| ---------------------------------- | ---------------------------------------- |
-| [index.md](index.md)               | Overview, quick start, surface API       |
-| [primitives.md](primitives.md)     | Library author API (`hasFeature`, types) |
-| [architecture.md](architecture.md) | Two-store architecture, internals        |
-| [decisions.md](decisions.md)       | Design decisions and rationale           |
-| [examples.md](examples.md)         | Usage examples (React, HTML, Lit)        |
+- Default should be obvious
+- Progressive enhancement
+- Declarative for common cases, programmatic for custom
+- Every name ends in its object
+- Code should be self-documenting
+- Match developer's mental model
+- Critical path bundle size matters
+- Features are the primary abstraction
+- HTML: Features register via imports, `createPlayer` is escape hatch
+- React: Features passed via `createPlayer` config, clear extension point
+- Skins adapt to available features
 
-## Problem
+## Model
 
-Two concerns, one player:
+```
+┌─────────────────────────────────────────────────┐
+│ <video-player>                                  │  ← Behavior
+│   ┌─────────────────────────────────────────┐   │
+│   │ <video-skin>                            │   │  ← Appearance
+│   │   ┌─────────────────────────────────┐   │   │
+│   │   │ <hls-video src="...">           │   │   │  ← Media
+│   │   └─────────────────────────────────┘   │   │
+│   └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────┘
+```
 
-1. **Media** — play, pause, volume, time. Owned by `<video>`.
-2. **Container** — fullscreen, keyboard, gestures, idle. Owned by the player UI wrapper.
+| Layer      | Responsibility                                  |
+| ---------- | ----------------------------------------------- |
+| **Player** | Behavior (controls, keyboard, fullscreen, idle) |
+| **Skin**   | Layout + styling, adapts to available features  |
+| **Media**  | Source handling (native, HLS, DASH)             |
+| **Features** | Additive capabilities, feature detection for skins |
 
-Different targets, different lifecycles. Internally, they need separate stores.
+## Progressive Workflow
 
-But users want one API. This doc defines:
+```
+Start simple                          Add as needed
+     │                                     │
+     ▼                                     ▼
 
-- How `createPlayer` exposes a unified API in React and HTML
-- What it returns — hooks, controllers, providers
-- How presets bundle features for common use cases
-- How to extend with custom features
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│   Player    │ → │    Skin     │ → │  Features   │ → │   Custom    │
+│             │   │             │   │             │   │             │
+│ <video-     │   │ <video-     │   │ streaming   │   │ createPlayer│
+│  player>    │   │  skin>      │   │ ads         │   │ escape hatch│
+│             │   │             │   │ chapters    │   │             │
+└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
 
-## Quick Start
+     Works            Pretty           Capable          Fully custom
+```
+
+## Overview
 
 ### React
 
 ```tsx
-import { createPlayer, presets } from '@videojs/react';
+import '@videojs/react/skin/video.css';
 
-const { Provider, Container, usePlayer } = createPlayer(presets.website);
+import { createPlayer, features } from '@videojs/react';
+import { VideoSkin } from '@videojs/react/skin/video';
+
+const { Provider: VideoProvider, usePlayer } = createPlayer({
+  features: [features.video]
+});
 
 function App() {
   return (
-    <Provider>
-      <Container>
-        <Video src="video.mp4" />
-        <Controls />
-      </Container>
-    </Provider>
+    <VideoProvider>
+      <VideoSkin>
+        <video src="video.mp4" />
+      </VideoSkin>
+    </VideoProvider>
   );
 }
-
-function Controls() {
-  const player = usePlayer();
-
-  // Flat access — state and requests on same object
-  // Proxy-based tracking — accessing .paused subscribes automatically
-  return <button onClick={player.paused ? player.play : player.pause}>{player.paused ? 'Play' : 'Pause'}</button>;
-}
 ```
 
-### HTML / Lit
+### HTML
 
 ```ts
-import { createPlayer, presets, VjsElement } from '@videojs/html';
-
-const { ProviderElement, PlayerController } = createPlayer(presets.website);
-
-customElements.define('vjs-website-provider', ProviderElement);
-
-class VjsPlayButton extends VjsElement {
-  #player = new PlayerController(this);
-
-  render() {
-    // .value returns tracking proxy — accessing .paused subscribes
-    const { paused, play, pause } = this.#player.value;
-
-    return html` <button @click=${paused ? play : pause}>${paused ? 'Play' : 'Pause'}</button> `;
-  }
-}
+import '@videojs/html/player/video';
+import '@videojs/html/skin/video.css';
+import '@videojs/html/skin/video';
 ```
 
-### Declarative (Skin)
-
 ```html
-<script type="module" src="@videojs/html/presets/website/skins/frosted.js"></script>
-
-<vjs-website-provider>
-  <vjs-frosted-skin>
-    <video src="video.mp4"></video>
-  </vjs-frosted-skin>
-</vjs-website-provider>
-```
-
-## Surface API
-
-### createPlayer
-
-```ts
-// Shorthand — preset or feature array
-createPlayer(presets.website);
-createPlayer([features.playback, features.fullscreen]);
-
-// Config object — extensible
-createPlayer({
-  features: presets.website,
-  // future: devTools, middleware, etc.
-});
-```
-
-### Returns (React)
-
-```ts
-const {
-  Provider, // Creates both stores
-  Container, // Attaches container to player store
-  usePlayer, // Player state + requests (flattened, typed to preset)
-  useMedia, // Media state + requests (escape hatch, typed to preset)
-} = createPlayer(presets.website);
-
-// Also exported from @videojs/react (for primitives):
-// - usePlayer() → UnknownPlayer (loosely typed)
-// - useMedia() → UnknownMedia (loosely typed)
-// - hasFeature(player, feature) → type guard
-// - getStore(player) → inferred store type
-```
-
-### Returns (HTML)
-
-```ts
-const {
-  // Ready-to-use elements
-  ProviderElement, // Both stores, auto-attaches media
-  ContainerElement, // Attaches container to player store
-
-  // Mixins (customization)
-  ProviderMixin, // Both stores
-  ContainerMixin, // Container attachment
-  MediaProviderMixin, // Media store only (escape hatch)
-
-  // Controllers (typed to preset)
-  PlayerController, // .value for state + requests, .store for store access
-  MediaController, // Media state + requests (escape hatch)
-} = createPlayer(presets.website);
-
-// Also exported from @videojs/html (for primitives):
-// - PlayerController → .value as UnknownPlayer, .store as UnknownPlayerStore
-// - MediaController → .value as UnknownMedia, .store as UnknownMediaStore
-// - hasFeature(player, feature) → type guard
-// - getStore(player) → inferred store type
-```
-
-### Returns (HTML) — createMedia
-
-```ts
-const {
-  ProviderElement, // Ready-to-use element
-  ProviderMixin, // Customization
-  MediaController, // Media state + requests
-} = createMedia([features.playback, features.time]);
-```
-
-### usePlayer (React)
-
-```tsx
-function Controls() {
-  const player = usePlayer();
-
-  // State — proxy tracks access, subscribes automatically
-  player.paused;
-  player.volume;
-  player.isFullscreen;
-
-  // Requests — call directly
-  player.play();
-  player.pause();
-  player.setVolume(0.5);
-  player.toggleFullscreen();
-}
-```
-
-### PlayerController (HTML/Lit)
-
-```ts
-class VjsControls extends VjsElement {
-  #player = new PlayerController(this);
-
-  render() {
-    const { paused, isFullscreen, play, pause, toggleFullscreen } = this.#player.value;
-
-    return html`
-      <button @click=${paused ? play : pause} />
-      <button @click=${toggleFullscreen} />
-    `;
-  }
-}
-```
-
-### useMedia (Escape Hatch)
-
-Direct media access. Rarely needed — use when player features don't expose what you need.
-
-```tsx
-function DebugPanel() {
-  const media = useMedia();
-
-  // Direct media state (bypasses player layer)
-  return <pre>{JSON.stringify({ readyState: media.readyState })}</pre>;
-}
-```
-
-## Features
-
-Features bundle related state and requests. Include only what you need.
-
-```ts
-import { features } from '@videojs/react';
-
-features.playback; // play, pause, ended
-features.volume; // volume, muted
-features.time; // currentTime, duration, seeking
-features.fullscreen; // isFullscreen, enter/exit
-features.keyboard; // keyboard shortcuts
-features.idle; // idle detection
-features.gestures; // touch gestures
-```
-
-### Presets
-
-Presets are curated feature collections. Pick one, get the right features.
-
-```ts
-createPlayer(presets.website); // full-featured
-createPlayer(presets.background); // minimal (autoplay, loop)
-```
-
-| Preset               | Use Case                             |
-| -------------------- | ------------------------------------ |
-| `presets.website`    | Default website player **(default)** |
-| `presets.background` | Background/hero video                |
-| `presets.news`       | Article embeds                       |
-| `presets.creator`    | Creator platforms (YouTube)          |
-| `presets.swipe`      | Short-form video (TikTok)            |
-| `presets.streaming`  | Streaming apps (Netflix)             |
-| `presets.live`       | Interactive live (Twitch)            |
-
-### Extending Presets
-
-```ts
-createPlayer({
-  features: [...presets.background, features.keyboard],
-});
-```
-
-### Creating Features
-
-```ts
-import { createPlayerFeature } from '@videojs/react';
-
-const analytics = createPlayerFeature({
-  initialState: { events: [] },
-
-  getSnapshot: ({ target, initialState }) => initialState,
-
-  subscribe: ({ target, update, signal }) => {
-    target.media.subscribe(
-      (s) => s.paused,
-      () => {
-        track(target.media.state.paused ? 'pause' : 'play');
-        update();
-      },
-      { signal }
-    );
-  },
-
-  request: {
-    trackEvent: (event, { target }) => {
-      // Access media state and requests
-      target.media.state.paused;
-      target.media.request.play();
-    },
-  },
-});
-
-createPlayer({
-  features: [...presets.website, analytics],
-});
-```
-
-## Naming Convention
-
-State and requests share the same flat namespace. Follow this convention to avoid collisions:
-
-| Type     | Convention                          | Examples                                                      |
-| -------- | ----------------------------------- | ------------------------------------------------------------- |
-| State    | Nouns, adjectives, past participles | `paused`, `volume`, `muted`, `isFullscreen`, `currentTime`    |
-| Requests | Verbs, imperative                   | `play`, `pause`, `setVolume`, `toggleMute`, `enterFullscreen` |
-
-Runtime validation throws if duplicate keys are detected.
-
-## Primitives API
-
-Building reusable UI primitives? See [primitives.md](primitives.md) for:
-
-- `hasFeature()` type guard for feature detection
-- `UnknownPlayer` / `UnknownMedia` loosely typed proxies
-- `getStore()` for direct store access
-- Cross-framework patterns (React + ReactiveElement)
-
-## Related Docs
-
-- [decisions.md](decisions.md) — Why these choices were made
-- [architecture.md](architecture.md) — Two-store internals, feature registry
-- [examples.md](examples.md) — Full usage examples
+<video-player>
+  <video-skin>
+    <video src="video.mp4">
+  </video-skin>
+</video-player>
+```
\ No newline at end of file
diff --git a/rfc/player-api/primitives.md b/rfc/player-api/primitives.md
index 69250b19..0285fdba 100644
--- a/rfc/player-api/primitives.md
+++ b/rfc/player-api/primitives.md
@@ -1,163 +1,223 @@
 # Primitives API
 
-Guide for library authors building UI primitives (like `<PlayButton>`, `<VolumeSlider>`).
+Guide for library authors building UI primitives (like `<media-play-button>`, `<media-slider>`).
 
 ## Problem
 
-Primitives don't know which preset the user chose:
+Primitives don't know which features the user configured:
 
 ```tsx
-// Inside @videojs/react - shipped to users
+// Inside @videojs/react — shipped to users
 export function PlayButton() {
-  const player = usePlayer(); // What type is this?
-  // User might use presets.website or presets.background
-  // We don't know if playbackFeature is included
+  // User might use features.video or a custom subset
+  // We don't know if playback feature is included
 }
 ```
 
 They need:
 
-1. Loosely typed access to the player
+1. Access to the player store
 2. A way to check if a feature exists
 3. Type narrowing when the feature is present
 
-## Solution: `hasFeature`, `getFeature`, `throwMissingFeature`
+## Solution: Feature Access Pattern
 
-Three utilities for feature access:
-
-| Function                | Returns                              | Use case                           |
-| ----------------------- | ------------------------------------ | ---------------------------------- |
-| `hasFeature(player, f)` | `boolean` (type guard)               | Conditional narrowing, `if` blocks |
-| `getFeature(player, f)` | Typed object, props `T \| undefined` | Direct access, optional chaining   |
-| `throwMissingFeature`   | `never` (throws)                     | Critical features, fail fast       |
-
-### `hasFeature` — Type Guard
+### React
 
 ```tsx
-import { features, hasFeature, throwMissingFeature, usePlayer } from '@videojs/react';
+import { usePlayer, features } from '@videojs/react';
 
 export function PlayButton() {
-  const player = usePlayer(); // UnknownPlayer - loosely typed
+  const playback = usePlayer(features.playback);
 
-  if (!hasFeature(player, features.playback)) {
-    throwMissingFeature(features.playback, { displayName: 'PlayButton' });
-  }
+  if (!playback) return null;
 
-  // TypeScript narrows: player.paused and player.play() are now typed
-  return <button onClick={player.play}>{player.paused ? '▶' : '⏸'}</button>;
+  // TypeScript knows playback is PlaybackSlice
+  return (
+    <button onClick={playback.paused ? playback.play : playback.pause}>
+      {playback.paused ? 'Play' : 'Pause'}
+    </button>
+  );
 }
 ```
 
-### `getFeature` — Direct Access
+### HTML
 
-For optional features, use `getFeature` with safe access:
+```ts
+import { features, MediaElement, PlayerController } from '@videojs/html';
 
-```tsx
-const volume = getFeature(player, features.volume);
-volume.setVolume?.(0.5); // Safe - no crash if undefined
+class MediaPlayButton extends MediaElement {
+  #playback = new PlayerController(this, features.playback);
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#handleClick);
+  }
+
+  #handleClick = () => {
+    this.#playback.value?.toggle();
+  };
+}
 ```
 
 ## Types
 
-### `StoreProxy<T>` Contract
+### FeatureKey
 
-All proxies implement `StoreProxy<T>`, which holds a reference to the underlying store:
+Type carrier for feature keys:
 
 ```ts
-const STORE_SYMBOL: unique symbol;
+type FeatureKey<F extends Feature> = symbol & { __feature?: F };
+```
 
-interface StoreProxy<T extends AnyStore = AnyStore> {
-  readonly [STORE_SYMBOL]: T;
-  [key: string]: unknown;
+Use with `store.get()` for typed access:
+
+```ts
+import { playbackKey } from '@videojs/core/features';
+
+const playback = store.get(playbackKey); // PlaybackSlice | undefined
+```
+
+### InferFeatureSlice
+
+Infer the slice type from a feature:
+
+```ts
+type PlaybackSlice = InferFeatureSlice<typeof playbackFeature>;
+// { paused: boolean; ended: boolean; play(): void; pause(): void; toggle(): void }
+```
+
+## Patterns
+
+### Required Feature
+
+If a primitive requires a feature to function:
+
+```tsx
+export function VolumeSlider() {
+  const volume = usePlayer(features.volume);
+
+  // Return nothing if feature not available
+  if (!volume) return null;
+
+  return <Slider value={volume.volume} onChange={volume.setVolume} />;
 }
 ```
 
-The index signature `[key: string]: unknown` allows any property access. After `hasFeature` narrows, explicit properties take precedence.
+### Optional Feature Enhancement
 
-### Proxy Types
-
-```ts
-interface UnknownPlayerStore extends Store<PlayerTarget, []> {}
-interface UnknownMediaStore extends Store<MediaTarget, []> {}
-
-interface UnknownPlayer extends StoreProxy<UnknownPlayerStore> {}
-interface UnknownMedia extends StoreProxy<UnknownMediaStore> {}
-```
-
-The `[]` for features means "no features statically typed" — the store has features at runtime, but TypeScript doesn't know which ones. Use `hasFeature` to narrow.
-
-### Type Summary
-
-| Type                 | Description                        |
-| -------------------- | ---------------------------------- |
-| `StoreProxy<T>`      | Base interface for all proxies     |
-| `UnknownPlayer`      | Player proxy with unknown features |
-| `UnknownMedia`       | Media proxy with unknown features  |
-| `UnknownPlayerStore` | Player store with unknown features |
-| `UnknownMediaStore`  | Media store with unknown features  |
-
-### Creating Proxies
-
-Internally, proxies are created from stores via `createProxy()`:
-
-```ts
-import { createProxy } from '@videojs/store';
-
-const store = createStore({ ... });
-const proxy = createProxy(store); // StoreProxy<typeof store>
-```
-
-This is used internally by `createPlayer` and controllers. Library authors typically receive proxies via `usePlayer()` or `controller.value`.
-
-### Via Controller (Lit/ReactiveElement)
-
-Controllers expose the proxy via `.value`:
-
-```ts
-const controller = new PlayerController(this);
-controller.value; // UnknownPlayer (tracked proxy)
-```
-
-## Implementation
-
-Both functions access `target[STORE_SYMBOL].features.has(feature.id)` at runtime:
-
-- **`hasFeature`** — Type guard that narrows the proxy to include feature's state and requests
-- **`getFeature`** — Returns same proxy typed to feature, with properties as `T | undefined`
-
-## Cross-Framework Consistency
-
-The same API works in React and Lit:
-
-| Concept              | React                                | Lit/ReactiveElement                     |
-| -------------------- | ------------------------------------ | --------------------------------------- |
-| Loosely typed player | `usePlayer()` → `UnknownPlayer`      | `controller.value` → `UnknownPlayer`    |
-| Type guard           | `hasFeature(player, feature)`        | `hasFeature(controller.value, feature)` |
-| Direct access        | `getFeature(player, feature)`        | `getFeature(controller.value, feature)` |
-| Throw on missing     | `throwMissingFeature(feature, opts)` | `throwMissingFeature(feature, opts)`    |
-
-### Package Exports
-
-| Package             | Exports                                                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------- |
-| `@videojs/store`    | `createProxy`, `hasFeature`, `getFeature`, `throwMissingFeature`, `subscribe`, `StoreProxy` |
-| `@videojs/core/dom` | `UnknownPlayer`, `UnknownMedia`, `UnknownPlayerStore`, `UnknownMediaStore`                  |
-| `@videojs/react`    | Re-exports above + `usePlayer`, `useMedia`, `createPlayer`                                  |
-| `@videojs/html`     | Re-exports above + `PlayerController`, `MediaController`, `createPlayer`                    |
-
-## Example: Mixing Required and Optional
+If a primitive works without a feature but enhances with it:
 
 ```tsx
 export function TimeSlider() {
-  const player = usePlayer();
+  const time = usePlayer(features.time);
+  const playback = usePlayer(features.playback);
 
-  // Required — throw if missing
-  if (!hasFeature(player, features.time)) {
-    throwMissingFeature(features.time, { displayName: 'TimeSlider' });
-  }
+  if (!time) return null;
 
-  // Optional — graceful degradation
-  const playback = getFeature(player, features.playback);
-  return <Slider onDragStart={playback.pause} onDragEnd={playback.play} />;
+  return (
+    <Slider
+      value={time.currentTime}
+      max={time.duration}
+      onChange={time.seek}
+      // Optional: pause during drag
+      onDragStart={playback?.pause}
+      onDragEnd={playback?.play}
+    />
+  );
 }
 ```
+
+### Multiple Required Features
+
+```tsx
+export function Controls() {
+  const playback = usePlayer(features.playback);
+  const volume = usePlayer(features.volume);
+  const fullscreen = usePlayer(features.fullscreen);
+
+  // All required
+  if (!playback || !volume || !fullscreen) return null;
+
+  return (
+    <div>
+      <PlayButton playback={playback} />
+      <VolumeSlider volume={volume} />
+      <FullscreenButton fullscreen={fullscreen} />
+    </div>
+  );
+}
+```
+
+## Cross-Framework Consistency
+
+Same pattern works in React and HTML:
+
+| Concept         | React                | HTML                                        |
+| --------------- | -------------------- | ------------------------------------------- |
+| Hook/Controller | `usePlayer(feature)` | `new PlayerController(this, feature)`       |
+| Get slice       | returns slice        | `controller.value`                          |
+| Check existence | `if (!slice)`        | `if (!slice)`                               |
+| Access state    | `slice.paused`       | `slice.paused`                              |
+| Call request    | `slice.play()`       | `slice.play()`                              |
+## Package Exports
+
+### @videojs/store
+
+```ts
+import { shallowEqual } from '@videojs/store';
+```
+
+### @videojs/core
+
+```ts
+import { 
+  features, createMediaFeature, createPlayerFeature,  
+  playbackKey, volumeKey, timeKey  
+} from '@videojs/core/dom';
+```
+
+### @videojs/react
+
+```ts
+import { createPlayer, usePlayer, features } from '@videojs/react';
+```
+
+### @videojs/html
+
+```ts
+import { createPlayer, features, MediaElement, PlayerController } from '@videojs/html';
+```
+
+## Feature Availability
+
+Features may target capabilities the platform doesn't support.
+
+```ts
+// iOS Safari doesn't allow programmatic volume control
+const volume = usePlayer(features.volume);
+volume?.volumeAvailability; // 'available' | 'unavailable' | 'unsupported'
+```
+
+| Value           | Meaning                                                |
+| --------------- | ------------------------------------------------------ |
+| `'unsupported'` | Platform can never do this (e.g., iOS volume)          |
+| `'unavailable'` | Could work, not ready yet (e.g., waiting for manifest) |
+| `'available'`   | Ready to use                                           |
+
+### Handling Unavailable Features
+
+```tsx
+export function VolumeSlider() {
+  const volume = usePlayer(features.volume);
+
+  if (!volume) return null;
+
+  // Hide if platform doesn't support volume control
+  if (volume.volumeAvailability === 'unsupported') return null;
+
+  // Disable if temporarily unavailable
+  const disabled = volume.volumeAvailability !== 'available';
+
+  return <Slider value={volume.volume} onChange={volume.setVolume} disabled={disabled} />;
+}