diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md
index c69752a7..3b7e98b7 100644
--- a/.claude/skills/docs/SKILL.md
+++ b/.claude/skills/docs/SKILL.md
@@ -151,7 +151,7 @@ For full guidelines, load `references/writing-style.md`. The essentials:
 - **Self-contained examples.** Include all imports. Use realistic values, not `foo`/`bar`.
 - **Show output.** When the result isn't obvious, add a comment showing expected output.
 - **Progressive.** Start with the simplest version. Add complexity in later examples.
-- **Cross-link.** End pages with "See also" linking related concepts and references. Repetition across pages is fine — readers land anywhere.
+- **Cross-link.** Generously link related concepts and references. Repetition across pages is fine — readers land anywhere.
 
 ### Do/don't contrasts
 
@@ -195,7 +195,7 @@ Key gotchas:
 3. Check existing docs for style and patterns
 4. Write concise draft — code before prose
 5. Add do/don't contrasts where helpful
-6. Add cross-links and "See also" section
+6. Add cross-links
 7. **Site pages only:** Add page to sidebar in `site/src/docs.config.ts`
 8. **Site pages only:** Verify it renders for all framework combinations
 
diff --git a/.claude/skills/docs/references/component-libraries.md b/.claude/skills/docs/references/component-libraries.md
index 05c6726d..72ebb538 100644
--- a/.claude/skills/docs/references/component-libraries.md
+++ b/.claude/skills/docs/references/component-libraries.md
@@ -16,7 +16,6 @@ All top-tier component libraries follow this structure:
 8. **Data Attributes** (CSS styling hooks)
 9. **CSS Variables** (theming)
 10. **Accessibility** (keyboard table, ARIA)
-11. **See also** (related components)
 
 ## Anatomy Documentation
 
diff --git a/.claude/skills/docs/review/agents.md b/.claude/skills/docs/review/agents.md
index c39fbc4e..134ec625 100644
--- a/.claude/skills/docs/review/agents.md
+++ b/.claude/skills/docs/review/agents.md
@@ -74,7 +74,7 @@ Review for:
 2. **Matches template** — Does it follow the structure from its template?
 3. **Code-first** — Code appears before explanation, not after
 4. **Progressive** — Starts simple, adds complexity in later sections
-5. **Cross-links** — Has "See also" section linking related pages
+5. **Cross-links** — Links related pages
 6. **Callouts** — Uses `<Aside>` (not `:::note`), correct severity
 7. **No H1** — Title comes from frontmatter only (site pages)
 8. **Sidebar** — Page added to `site/src/docs.config.ts` (site pages)
diff --git a/.claude/skills/docs/review/checklist.md b/.claude/skills/docs/review/checklist.md
index ad1ff136..bb20f2cf 100644
--- a/.claude/skills/docs/review/checklist.md
+++ b/.claude/skills/docs/review/checklist.md
@@ -22,7 +22,7 @@ See SKILL.md for doc types and templates.
 - [ ] Matches template structure?
 - [ ] Code appears before explanation?
 - [ ] Progressive — starts simple, adds complexity?
-- [ ] Has "See also" section with related links?
+- [ ] Links related pages?
 - [ ] `<Aside>` used correctly (not `:::note`)?
 - [ ] Correct callout types (note/tip/caution/danger)?
 - [ ] No H1 — title from frontmatter only (site pages)?
diff --git a/.claude/skills/docs/review/templates.md b/.claude/skills/docs/review/templates.md
index 920e6584..7ee3442b 100644
--- a/.claude/skills/docs/review/templates.md
+++ b/.claude/skills/docs/review/templates.md
@@ -24,7 +24,7 @@ improved text or code
 | Level      | Meaning                        | Examples                                           |
 | ---------- | ------------------------------ | -------------------------------------------------- |
 | `CRITICAL` | Broken example, wrong info     | Missing import, incorrect API, code won't run      |
-| `MAJOR`    | Missing section, unclear prose | No "See also", wrong doc type, wall of text        |
+| `MAJOR`    | Missing section, unclear prose | Wrong doc type, wall of text        |
 | `MINOR`    | Suboptimal wording or layout   | Filler words, passive voice, could be more concise |
 | `NIT`      | Polish, phrasing preference    | Minor rewording, formatting tweak                  |
 
@@ -51,23 +51,6 @@ import { createPlayer } from '@videojs/html';
 const player = createPlayer({ src: 'video.mp4' });
 ```
 
-### MAJOR — Missing cross-links
-
-```markdown
-### [MAJOR] No "See also" section
-
-**What:** Page ends without linking to related concepts
-**Where:** `site/src/content/docs/concepts/themes.mdx`
-**Why:** Readers can't discover related pages; reduces navigation
-**Fix:** Add See also section
-
-// After
-## See also
-
-- [Styling](/concepts/styling) — CSS custom properties reference
-- [Accessibility](/concepts/accessibility) — Color contrast requirements
-```
-
 ### MINOR — Filler words
 
 ```markdown
diff --git a/.claude/skills/docs/templates/concept.md b/.claude/skills/docs/templates/concept.md
index 67786365..bcbf2ada 100644
--- a/.claude/skills/docs/templates/concept.md
+++ b/.claude/skills/docs/templates/concept.md
@@ -86,5 +86,4 @@ Helpful optimization or best practice.
 - [ ] Brief explanation (2-3 paragraphs max)
 - [ ] Framework-specific content uses `<FrameworkCase>`
 - [ ] Common pitfalls as do/don't
-- [ ] See also with 2-4 links
 - [ ] Scannable in under 2 minutes
diff --git a/site/src/components/Aside.astro b/site/src/components/Aside.astro
index e0438848..ffa80b1f 100644
--- a/site/src/components/Aside.astro
+++ b/site/src/components/Aside.astro
@@ -39,7 +39,7 @@ const renderTitle = title ?? defaultTitles[type];
 <aside
   class={twMerge(
     clsx(
-      "mx-auto my-4 flex w-full max-w-3xl overflow-hidden rounded-xs border border-manila-75 dark:border-warm-gray",
+      "mx-auto my-8 flex w-full max-w-3xl overflow-hidden rounded-xs border border-manila-75 dark:border-warm-gray",
     ),
     className,
   )}
diff --git a/site/src/components/docs/DocsLink.astro b/site/src/components/docs/DocsLink.astro
index d5b9cec7..1bbc91c8 100644
--- a/site/src/components/docs/DocsLink.astro
+++ b/site/src/components/docs/DocsLink.astro
@@ -20,6 +20,4 @@ const { url: href } = resolveDocsLinkUrl({
 });
 ---
 
-<A href={href}>
-  <slot />
-</A>
+<A href={href}><slot /></A>
diff --git a/site/src/components/docs/DocsLinkCard.astro b/site/src/components/docs/DocsLinkCard.astro
new file mode 100644
index 00000000..39d44fae
--- /dev/null
+++ b/site/src/components/docs/DocsLinkCard.astro
@@ -0,0 +1,47 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { ChevronRight } from 'lucide-react';
+import { isValidFramework } from '@/types/docs';
+import { resolveDocsLinkUrl } from '@/utils/docs/routing';
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {
+  slug: string;
+  description?: string;
+}
+const { slug, description } = Astro.props;
+
+const { framework: paramFramework } = Astro.params;
+if (!paramFramework || !isValidFramework(paramFramework)) {
+  throw new Error(`Invalid or missing framework param "${paramFramework ?? 'undefined'}".`);
+}
+
+const { url: href } = resolveDocsLinkUrl({
+  targetSlug: slug,
+  contextFramework: paramFramework,
+});
+---
+
+<div
+  class="docs-link-card mx-auto my-8 grid w-full max-w-3xl grid-cols-1 gap-4 has-[+_.docs-link-card]:mb-4 md:grid-cols-2 [&+.docs-link-card]:mt-4"
+>
+  <a
+    href={href}
+    class="flex items-center justify-between gap-4 rounded-xs border border-manila-dark p-4 no-underline md:pl-6 dark:border-warm-gray intent:bg-manila-75 dark:intent:bg-warm-gray"
+  >
+    {
+      description ? (
+        <div>
+          <div class="font-bold">
+            <slot />
+          </div>
+          <div class="mt-2 text-p3">{description}</div>
+        </div>
+      ) : (
+        <span>
+          <slot />
+        </span>
+      )
+    }
+    <ChevronRight size={14} />
+  </a>
+</div>
diff --git a/site/src/components/docs/DocsNavigation.astro b/site/src/components/docs/DocsNavigation.astro
index d9e60967..96b7a031 100644
--- a/site/src/components/docs/DocsNavigation.astro
+++ b/site/src/components/docs/DocsNavigation.astro
@@ -16,12 +16,12 @@ function getGuideUrl(framework: SupportedFramework, slug: string): string {
 }
 ---
 
-<nav class="mx-auto grid w-full max-w-3xl grid-cols-1 gap-5 md:grid-cols-2">
+<nav class="mx-auto grid w-full max-w-3xl grid-cols-1 gap-4 md:grid-cols-2">
   {
     prev ? (
       <a
         href={getGuideUrl(framework, prev.slug)}
-        class="grid items-center gap-x-2 rounded-xs border border-manila-75 bg-manila-50 p-4 dark:border-soot dark:bg-warm-gray intent:bg-manila-dark dark:intent:bg-soot"
+        class="grid items-center gap-x-2 rounded-xs border border-manila-dark p-4 dark:border-warm-gray intent:bg-manila-75 dark:intent:bg-warm-gray"
         style="grid-template-areas: 'empty direction' 'icon title'; grid-template-columns: auto minmax(0,1fr); grid-template-rows: auto minmax(0,1fr);"
       >
         <div class="text-p3" style="grid-area: direction;">
@@ -42,7 +42,7 @@ function getGuideUrl(framework: SupportedFramework, slug: string): string {
     next ? (
       <a
         href={getGuideUrl(framework, next.slug)}
-        class="grid items-center gap-x-2 rounded-xs border border-manila-75 bg-manila-50 p-4 text-right dark:border-soot dark:bg-warm-gray intent:bg-manila-dark dark:intent:bg-soot"
+        class="grid items-center gap-x-2 rounded-xs border border-manila-dark p-4 text-right dark:border-warm-gray intent:bg-manila-75 dark:intent:bg-warm-gray"
         style="grid-template-areas: 'direction empty' 'title icon';grid-template-columns: minmax(0,1fr) auto; grid-template-rows: auto minmax(0,1fr);"
       >
         <div class="text-p3" style="grid-area: direction;">
diff --git a/site/src/components/docs/demos/create-player/react/css/BasicUsage.tsx b/site/src/components/docs/demos/create-player/react/css/BasicUsage.tsx
index 3ce57252..afa3ae3a 100644
--- a/site/src/components/docs/demos/create-player/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/create-player/react/css/BasicUsage.tsx
@@ -3,13 +3,13 @@ import { Video, videoFeatures } from '@videojs/react/video';
 
 import './BasicUsage.css';
 
-const { Provider, Container, usePlayer } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function Controls() {
-  const store = usePlayer();
-  const paused = usePlayer((s) => s.paused);
+  const store = Player.usePlayer();
+  const paused = Player.usePlayer((s) => s.paused);
 
   return (
     <div className="react-create-player-basic__controls">
@@ -26,8 +26,8 @@ function Controls() {
 
 export default function BasicUsage() {
   return (
-    <Provider>
-      <Container className="react-create-player-basic">
+    <Player.Provider>
+      <Player.Container className="react-create-player-basic">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -35,7 +35,7 @@ export default function BasicUsage() {
           playsInline
         />
         <Controls />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx b/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx
index 1d00d290..97a07f69 100644
--- a/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx
@@ -1,14 +1,14 @@
-import { createPlayer, useMedia } from '@videojs/react';
+import { createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
 import './BasicUsage.css';
 
-const { Provider, Container } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function MediaInfo() {
-  const media = useMedia();
+  const media = Player.useMedia();
 
   if (!media) return null;
 
@@ -36,8 +36,8 @@ function MediaInfo() {
 
 export default function BasicUsage() {
   return (
-    <Provider>
-      <Container className="react-use-media-basic">
+    <Player.Provider>
+      <Player.Container className="react-use-media-basic">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -46,7 +46,7 @@ export default function BasicUsage() {
           loop
         />
         <MediaInfo />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/docs/demos/use-player/react/css/Selector.tsx b/site/src/components/docs/demos/use-player/react/css/Selector.tsx
index da5f6e6b..aa42b65e 100644
--- a/site/src/components/docs/demos/use-player/react/css/Selector.tsx
+++ b/site/src/components/docs/demos/use-player/react/css/Selector.tsx
@@ -1,14 +1,14 @@
-import { createPlayer, usePlayer } from '@videojs/react';
+import { createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
 import './Selector.css';
 
-const { Provider, Container } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function StateDisplay() {
-  const state = usePlayer((s) => ({
+  const state = Player.usePlayer((s) => ({
     paused: s.paused,
     currentTime: s.currentTime,
     duration: s.duration,
@@ -32,8 +32,8 @@ function StateDisplay() {
 
 export default function Selector() {
   return (
-    <Provider>
-      <Container className="react-use-player-selector">
+    <Player.Provider>
+      <Player.Container className="react-use-player-selector">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -42,7 +42,7 @@ export default function Selector() {
           loop
         />
         <StateDisplay />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/docs/demos/use-player/react/css/StoreAccess.tsx b/site/src/components/docs/demos/use-player/react/css/StoreAccess.tsx
index 56edb16b..40878e84 100644
--- a/site/src/components/docs/demos/use-player/react/css/StoreAccess.tsx
+++ b/site/src/components/docs/demos/use-player/react/css/StoreAccess.tsx
@@ -1,14 +1,14 @@
-import { createPlayer, usePlayer } from '@videojs/react';
+import { createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
 import './StoreAccess.css';
 
-const { Provider, Container } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function Controls() {
-  const store = usePlayer();
+  const store = Player.usePlayer();
 
   return (
     <div className="react-use-player-store__controls">
@@ -24,8 +24,8 @@ function Controls() {
 
 export default function StoreAccess() {
   return (
-    <Provider>
-      <Container className="react-use-player-store">
+    <Player.Provider>
+      <Player.Container className="react-use-player-store">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -34,7 +34,7 @@ export default function StoreAccess() {
           loop
         />
         <Controls />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/docs/demos/use-store/react/css/Selector.tsx b/site/src/components/docs/demos/use-store/react/css/Selector.tsx
index 8691b6c3..a3598dd8 100644
--- a/site/src/components/docs/demos/use-store/react/css/Selector.tsx
+++ b/site/src/components/docs/demos/use-store/react/css/Selector.tsx
@@ -1,14 +1,14 @@
-import { createPlayer, usePlayer, useStore } from '@videojs/react';
+import { createPlayer, useStore } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
 import './Selector.css';
 
-const { Provider, Container } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function DerivedState() {
-  const store = usePlayer();
+  const store = Player.usePlayer();
   const derived = useStore(store, (s) => ({
     remaining: s.duration - s.currentTime,
     progress: s.duration > 0 ? (s.currentTime / s.duration) * 100 : 0,
@@ -30,8 +30,8 @@ function DerivedState() {
 
 export default function Selector() {
   return (
-    <Provider>
-      <Container className="react-use-store-selector">
+    <Player.Provider>
+      <Player.Container className="react-use-store-selector">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -40,7 +40,7 @@ export default function Selector() {
           loop
         />
         <DerivedState />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/docs/demos/use-store/react/css/StoreAccess.tsx b/site/src/components/docs/demos/use-store/react/css/StoreAccess.tsx
index ff5f1c6b..6094f379 100644
--- a/site/src/components/docs/demos/use-store/react/css/StoreAccess.tsx
+++ b/site/src/components/docs/demos/use-store/react/css/StoreAccess.tsx
@@ -1,14 +1,14 @@
-import { createPlayer, usePlayer, useStore } from '@videojs/react';
+import { createPlayer, useStore } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
 import './StoreAccess.css';
 
-const { Provider, Container } = createPlayer({
+const Player = createPlayer({
   features: videoFeatures,
 });
 
 function SeekControls() {
-  const store = usePlayer();
+  const store = Player.usePlayer();
   const s = useStore(store);
 
   return (
@@ -25,8 +25,8 @@ function SeekControls() {
 
 export default function StoreAccess() {
   return (
-    <Provider>
-      <Container className="react-use-store-access">
+    <Player.Provider>
+      <Player.Container className="react-use-store-access">
         <Video
           src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
           autoPlay
@@ -35,7 +35,7 @@ export default function StoreAccess() {
           loop
         />
         <SeekControls />
-      </Container>
-    </Provider>
+      </Player.Container>
+    </Player.Provider>
   );
 }
diff --git a/site/src/components/typography/H3Markdown.astro b/site/src/components/typography/H3Markdown.astro
index fed7ee02..51bfecfc 100644
--- a/site/src/components/typography/H3Markdown.astro
+++ b/site/src/components/typography/H3Markdown.astro
@@ -5,6 +5,6 @@ import H3 from './H3.astro';
 const { class: className, ...props } = Astro.props;
 ---
 
-<H3 as="h3" class:list={["mt-8", className]} {...props}>
+<H3 as="h3" class:list={["mt-12", className]} {...props}>
   <slot />
 </H3>
diff --git a/site/src/components/typography/styles.ts b/site/src/components/typography/styles.ts
index f871e477..89bb1939 100644
--- a/site/src/components/typography/styles.ts
+++ b/site/src/components/typography/styles.ts
@@ -9,7 +9,7 @@ export const shared = {
   a: 'underline intent:no-underline',
   code: 'border border-manila-75 bg-manila-25 dark:bg-soot dark:border-warm-gray px-1 rounded font-mono text-code normal-case',
   codeBlock: 'font-mono text-code',
-  em: 'font-bold',
+  em: 'italic',
   li: 'text-p2',
   ol: 'list-decimal list-outside pl-4 space-y-1',
   strong: 'font-bold',
diff --git a/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx b/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx
index 2d589896..d7cc759e 100644
--- a/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx
+++ b/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx
@@ -123,21 +123,23 @@ For example here's a simple React "hello world" with just a video and play butto
 import { createPlayer, features } from '@videojs/react';
 import { Video } from '@videojs/react/video';
 
-const { Provider, usePlayer } = createPlayer({
+const Player = createPlayer({
   features: [features.playback],
 });
 
 function App() {
-  const store = usePlayer();
-  const paused = usePlayer((s) => s.paused);
+  const store = Player.usePlayer();
+  const paused = Player.usePlayer((s) => s.paused);
 
   return (
-    <Provider>
-      <Video src="video.mp4" />
-      <button onClick={() => (paused ? store.play() : store.pause())}>
-        {paused ? 'Play' : 'Pause'}
-      </button>
-    </Provider>
+    <Player.Provider>
+      <Player.Container>
+        <Video src="video.mp4" />
+        <button onClick={() => (paused ? store.play() : store.pause())}>
+          {paused ? 'Play' : 'Pause'}
+        </button>
+      </Player.Container>
+    </Player.Provider>
   );
 }
 ```
@@ -248,7 +250,7 @@ If you wanted to build a podcast player with Video.js v8, you'd start with a vid
 
 We do actually know what people are building, believe it or not. Not just the individual features, but the specific combinations that tend to show up together. A TV streaming app needs different things than a hero background video, which needs different things than a podcast player. And those combinations are pretty consistent across the web.
 
-So in v10 we're packaging them up as Presets. A Preset is a purpose-built combination of skin, features, and media configuration for a specific use case. Instead of assembling a player from scratch, you'll pick the preset closest to what you're building and start there.
+So in v10 we're packaging them up as presets. A preset is a purpose-built combination of skin, features, and media configuration for a specific use case. Instead of assembling a player from scratch, you'll pick the preset closest to what you're building and start there.
 
 The beta ships three:
 
@@ -257,7 +259,7 @@ A default video preset (general website video, the kind of thing you might other
 ```html
 <video-player>
   <video-skin>
-    <video src="video.mp4"></video>
+    <video slot="media" src="video.mp4"></video>
   </video-skin>
 </video-player>
 ```
diff --git a/site/src/content/docs/concepts/_architecture.mdx b/site/src/content/docs/concepts/_architecture.mdx
deleted file mode 100644
index 4d34fbd9..00000000
--- a/site/src/content/docs/concepts/_architecture.mdx
+++ /dev/null
@@ -1,124 +0,0 @@
----
-title: Architecture
-description: How Video.js structures its video player — state management, UI components, and platform renderers
----
-
-import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs';
-import DocsLink from '@/components/docs/DocsLink.astro';
-
-Video.js v10 is built around a three-tier architecture that separates concerns and maximizes flexibility. Each tier is designed to work independently or together, allowing you to use as much or as little of Video.js as you need.
-
-## The three tiers
-
-### 1. State management
-
-<FrameworkCase frameworks={["react"]}>
-State is handled by `VideoProvider`, which creates a central store that all components can access. When you wrap your player in a `VideoProvider`, components automatically connect to the state.
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-State is handled by `video-provider`, which creates a central store that all components can access. When you wrap your player in a `video-provider`, components automatically connect to the state.
-</FrameworkCase>
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-<VideoProvider>
-  {/* All components inside automatically connect to state */}
-</VideoProvider>
-```
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-```html
-<video-provider>
-  <!-- All components inside automatically connect to state -->
-</video-provider>
-```
-</FrameworkCase>
-
-### 2. User interface
-
-#### Skins
-Complete, pre-designed player UIs that package components and styles together:
-- Frosted (glassy design)
-- Minimal (clean, simple design)
-
-Want to learn more? <DocsLink slug="concepts/skins">Read the skins guide →</DocsLink>
-
-#### Components
-Most should use a skin as a starting point. However, if you want more control, you have two options.
-
-First, you can use eject a skin to customize it. <DocsLink slug="how-to/customize-skins">to learn more, check out our guide on customizing skins →</DocsLink>
-
-Next, you can use the individual, unstyled UI primitives, standalone or composed into custom designs:
-- Buttons (Play, Mute, Fullscreen)
-- Sliders (Time, Volume)
-- Displays (CurrentTime, Duration)
-- Compound components (Tooltip, Popover)
-
-Want to dive deeper? <DocsLink slug="concepts/ui-components">Explore UI components →</DocsLink>
-
-### 3. Media renderers
-
-Media renderers are the components that actually display your media. They're essentially "players with no UI". They handle the video/audio rendering and expose a consistent API.
-
-<FrameworkCase frameworks={["react"]}>
-For now, we'll have a default `<Video />` component, which supports MP4 and other natively-supported streams and `<HlsVideo />`, which supports HLS. In the future, we'll be adding additional support for streaming standards like DASH and services like YouTube and Vimeo.
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-For now, we're starting with just the native HTML5 `<video />` component, but we're looking forward to adding more in the future. From engines like HLS and DASH, to services like YouTube and Vimeo.
-</FrameworkCase>
-
-## How it all works together
-
-Here's a complete example showing all three tiers:
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-import '@videojs/react-preview/skins/frosted.css';
-
-import { VideoProvider, FrostedSkin, Video } from '@videojs/react-preview';
-
-function Player() {
-  return (
-    // Tier 1: State Management
-    <VideoProvider>
-      {/* Tier 2: User Interface (Skin with components) */}
-      <FrostedSkin>
-        {/* Tier 3: Media Renderer */}
-        <Video src="video.mp4" />
-      </FrostedSkin>
-    </VideoProvider>
-  );
-}
-```
-</FrameworkCase>
-
-<FrameworkCase frameworks={["html"]}>
-<TabsRoot client:idle>
-  <TabsList client:idle label="HTML implementation">
-    <Tab client:idle value="html" initial>HTML</Tab>
-    <Tab client:idle value="javascript">JavaScript</Tab>
-  </TabsList>
-  <TabsPanel client:idle value="html" initial>
-
-```html
-<!-- Tier 1: State Management -->
-<video-provider>
-  <!-- Tier 2: User Interface (Skin with components) -->
-  <media-skin-frosted>
-    <!-- Tier 3: Media Renderer -->
-    <video slot="media" src="video.mp4"></video>
-  </media-skin-frosted>
-</video-provider>
-```
-
-  </TabsPanel>
-  <TabsPanel client:idle value="javascript">
-
-```ts
-import '@videojs/html-preview/skins/frosted';
-```
-
-  </TabsPanel>
-</TabsRoot>
-</FrameworkCase>
diff --git a/site/src/content/docs/concepts/_skins.mdx b/site/src/content/docs/concepts/_skins.mdx
deleted file mode 100644
index cd7e8b79..00000000
--- a/site/src/content/docs/concepts/_skins.mdx
+++ /dev/null
@@ -1,173 +0,0 @@
----
-title: Skins
-description: Packaged sets of video player UI components and styles that you can customize or replace
----
-
-import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import { FrostedSkinDemo } from '@/examples/react/FrostedSkin/FrostedSkinDemo';
-import { MinimalSkinDemo } from '@/examples/react/MinimalSkin/MinimalSkinDemo';
-import ContentWidth from '@/components/frames/ContentWidth.astro';
-import DocsLink from '@/components/docs/DocsLink.astro';
-
-In Video.js v10, skins are **complete, packaged player designs** that include both UI components and their styles. This is a significant change from v8, where skins were purely CSS themes applied to a fixed component structure.
-
-## What's different in v10?
-
-### Video.js v8 skins
-- CSS-only themes
-- Applied to a fixed component structure
-- Limited customization without JavaScript
-
-### Video.js v10 skins
-- **UI components + styles packaged together**
-- Each skin can have completely different components
-- Can address entirely different use cases
-- Only include the components they need
-
-## Built-in skins
-
-### Frosted
-
-A modern, glassy design with backdrop blur effects and polished interactions.
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-import '@videojs/react/video/skin.css';
-
-import { createPlayer, Poster } from '@videojs/react';
-import { VideoSkin, Video, videoFeatures } from '@videojs/react/video';
-
-const Player = createPlayer({ features: videoFeatures });
-
-export function VideoPlayer() {
-  return (
-    <Player.Provider>
-      <VideoSkin className="w-full aspect-video">
-        <Video src="video.mp4" />
-        <Poster src="poster.webp" />
-      </VideoSkin>
-    </Player.Provider>
-  );
-}
-```
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-```html
-<video-provider>
-  <media-skin-frosted>
-    <video slot="media" src="video.mp4"></video>
-  </media-skin-frosted>
-</video-provider>
-```
-</FrameworkCase>
-
-<ContentWidth class='relative z-20'>
-  <FrostedSkinDemo client:visible />
-</ContentWidth>
-
-### Minimal
-
-A clean, straightforward design that focuses on simplicity and clarity.
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-import '@videojs/react/video/minimal-skin.css';
-
-import { createPlayer, Poster } from '@videojs/react';
-import { MinimalVideoSkin, Video, videoFeatures } from '@videojs/react/video';
-
-const Player = createPlayer({ features: videoFeatures });
-
-export function VideoPlayer() {
-  return (
-    <Player.Provider>
-      <MinimalVideoSkin className="w-full aspect-video">
-        <Video src="video.mp4" />
-        <Poster src="poster.webp" />
-      </MinimalVideoSkin>
-    </Player.Provider>
-  );
-}
-```
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-```html
-<video-provider>
-  <media-skin-minimal>
-    <video slot="media" src="video.mp4"></video>
-  </media-skin-minimal>
-</video-provider>
-```
-</FrameworkCase>
-
-<ContentWidth class='relative z-20'>
-  <MinimalSkinDemo client:visible />
-</ContentWidth>
-
-## Customizing skins
-
-Skins are designed to be ejected and modified for your specific needs.
-
-Ready to make it your own? <DocsLink slug="how-to/customize-skins">Learn how to customize a skin →</DocsLink>
-
-## Building your own skin
-
-A skin is simply a component that:
-<FrameworkCase frameworks={["react"]}>
-1. Wraps content in a `MediaContainer`
-2. Includes a `children` prop (for the media renderer)
-3. Arranges UI components as desired
-4. Provides styles for those components
-</FrameworkCase>
-<FrameworkCase frameworks={["html"]}>
-1. Wraps content in a `media-container`
-2. Includes a `<slot>` element (for the media renderer)
-3. Arranges UI components as desired
-4. Provides styles for those components
-</FrameworkCase>
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-import { MediaContainer, PlayButton, TimeSlider } from '@videojs/react-preview';
-
-export function CustomSkin({ children, className }) {
-  return (
-    <MediaContainer className={className}>
-      {children}
-      <div className="controls">
-        <PlayButton />
-        <TimeSlider.Root>
-          <TimeSlider.Track>
-            <TimeSlider.Progress />
-          </TimeSlider.Track>
-          <TimeSlider.Thumb />
-        </TimeSlider.Root>
-      </div>
-    </MediaContainer>
-  );
-}
-```
-</FrameworkCase>
-
-<FrameworkCase frameworks={["html"]}>
-```html
-<video-provider>
-  <media-container class="custom-skin">
-    <slot></slot>
-    <div class="controls">
-      <media-play-button></media-play-button>
-      <media-time-slider>
-        <!-- Custom skin structure -->
-      </media-time-slider>
-    </div>
-  </media-container>
-</video-provider>
-```
-</FrameworkCase>
-
-Read more about components <DocsLink slug="concepts/ui-components">in the components guide →</DocsLink>
-
-## Coming soon
-
-- More built-in skins for different use cases
-- CLI tool for ejecting and customizing skins
diff --git a/site/src/content/docs/concepts/_ui-components.mdx b/site/src/content/docs/concepts/_ui-components.mdx
deleted file mode 100644
index 2ecef5e2..00000000
--- a/site/src/content/docs/concepts/_ui-components.mdx
+++ /dev/null
@@ -1,92 +0,0 @@
----
-title: UI components
-description: Primitive-based component architecture for building accessible, composable video player controls
----
-
-import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import DocsLink from '@/components/docs/DocsLink.astro';
-
-Video.js v10 components are built from **unstyled UI primitives**, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you.
-
-## Core principles
-
-### 1. Primitive-based design
-
-Each primitive represents at most **one HTML element**, without internal elements.
-
-<FrameworkCase frameworks={["react"]}>
-```tsx
-<TimeSlider.Root>
-  <TimeSlider.Track>        {/* One element: the track */}
-    <TimeSlider.Progress /> {/* One element: the progress bar */}
-    <TimeSlider.Pointer />  {/* One element: hover indicator */}
-  </TimeSlider.Track>
-  <TimeSlider.Thumb />      {/* One element: the draggable thumb */}
-</TimeSlider.Root>
-```
-</FrameworkCase>
-
-<FrameworkCase frameworks={["html"]}>
-```html
-<media-time-slider>
-  <div class="track">        <!-- One element: the track -->
-    <div class="progress"></div>  <!-- One element: the progress bar -->
-    <div class="pointer"></div>   <!-- One element: hover indicator -->
-  </div>
-  <div class="thumb"></div>       <!-- One element: the draggable thumb -->
-</media-time-slider>
-```
-</FrameworkCase>
-
-### 2. Compound components
-
-Complex components are broken into smaller, composable pieces. This pattern is used for:
-
-- **Sliders** - Root, Track, Thumb, Progress, Pointer
-- **Tooltips** - Root, Trigger, Positioner, Popup
-- **Popovers** - Root, Trigger, Positioner, Popup
-
-Each piece handles one concern, but they work together seamlessly.
-
-### 3. Built-in accessibility
-
-Components include proper ARIA attributes, keyboard navigation, and focus management out of the box:
-
-- Buttons have correct roles and labels
-- Sliders support arrow key navigation
-- Focus is managed properly in tooltips and popovers
-- Screen readers get meaningful announcements
-
-### 4. Data attributes for styling
-
-Components expose state through data attributes, allowing pure CSS state styling:
-
-```css
-/* Style based on state without JavaScript */
-button[data-paused] {
-  /* Paused state */
-}
-
-button:not([data-paused]) {
-  /* Playing state */
-}
-```
-
-Common data attributes:
-- `data-paused` - Present when media is paused
-- `data-muted` - Present when audio is muted
-- `data-fullscreen` - Present when in fullscreen mode
-- `data-volume-level` - Values: `high`, `medium`, `low`, `off`
-
-## Available components
-
-### Simple components
-
-Single-element components that handle one piece of UI:
-
-- <DocsLink slug="reference/play-button">**PlayButton**</DocsLink> - Play/pause toggle
-- <DocsLink slug="reference/mute-button">**MuteButton**</DocsLink> - Audio mute toggle
-
-### Compound components
-
-Multi-element components for complex interactions
diff --git a/site/src/content/docs/concepts/features.mdx b/site/src/content/docs/concepts/features.mdx
new file mode 100644
index 00000000..0d52cb78
--- /dev/null
+++ b/site/src/content/docs/concepts/features.mdx
@@ -0,0 +1,202 @@
+---
+title: Features
+description: The state and actions each feature adds to the player
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+import Aside from '@/components/Aside.astro';
+
+
+Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, "playback" adds `paused` and `play()`, "volume" adds `volume` and `setVolume()`, and so on.
+
+## Using features
+### Feature bundles and presets
+
+You probably don't want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
+
+<FrameworkCase frameworks={["react"]}>
+
+For example, `videoFeatures` bundles playback, volume, time, fullscreen, and more — everything a general video player needs:
+
+```tsx
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+```
+
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+
+For example, if you import `<video-player>` from the `/video` path, you'll has playback, volume, time, fullscreen, and more already enabled. 
+
+```html
+<script type="module" src="@videojs/html/video/player"></script> <!-- [!code focus] -->
+<video-player> <!-- [!code focus] -->
+  <video-skin>
+    <video slot="media" src="movie.mp4"></video>
+  </video-skin>
+</video-player> <!-- [!code focus] -->
+```
+</FrameworkCase>
+
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you'll want to check out the presets guide.
+
+<DocsLinkCard slug="concepts/presets">Learn more about presets</DocsLinkCard>
+
+### Create a player with individual features
+If you're not using presets, you can create a player that has individual features.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { createPlayer, playback, volume, time } from '@videojs/react';
+
+const Player = createPlayer({
+  features: [playback, volume, time],
+});
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts
+import { createPlayer, playback, volume, time } from '@videojs/html';
+
+const { ProviderMixin, PlayerController, context } = createPlayer({
+  features: [playback, volume, time],
+});
+
+class MyPlayer extends ProviderMixin(MediaElement) {
+  static readonly tagName = 'my-player';
+}
+
+customElements.define('my-player', MyPlayer);
+```
+</FrameworkCase>
+
+### Extending a feature bundle
+
+Since feature bundles are just an array of features under the hood, it doesn't take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { createPlayer, playback } from '@videojs/react';
+import { backgroundFeatures } from '@videojs/react/background';
+
+const Player = createPlayer({
+  features: [...backgroundFeatures, playback],
+});
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```ts
+import { createPlayer, playback } from '@videojs/html';
+import { backgroundFeatures } from '@videojs/html/background';
+import { MediaElement } from '@videojs/html';
+
+const { ProviderMixin } = createPlayer({
+  features: [...backgroundFeatures, playback],
+});
+
+class MyPlayer extends ProviderMixin(MediaElement) {
+  static readonly tagName = 'my-player';
+}
+
+customElements.define('my-player', MyPlayer);
+```
+</FrameworkCase>
+
+### Access features in components
+
+<FrameworkCase frameworks={["react"]}>
+You access feature state and actions through <DocsLink slug="reference/use-player">`usePlayer`</DocsLink>:
+```tsx
+// Subscribe to state (re-renders when selected values change)
+const { paused, volume } = Player.usePlayer((s) => ({
+  paused: s.paused,
+  volume: s.volume,
+}));
+
+// Call actions
+const store = Player.usePlayer();
+store.play();
+store.setVolume(0.8);
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+You can access feature state and actions through <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> and pre-built feature selectors (e.g. <DocsLink slug="reference/feature-playback">`selectPlayback`</DocsLink>, <DocsLink slug="reference/feature-volume">`selectVolume`</DocsLink>):
+```ts
+import { selectPlayback } from '@videojs/html';
+
+// Subscribe to feature state (triggers element updates on change)
+readonly #playback = new PlayerController(this, context, selectPlayback);
+
+// Read state and call actions
+const media = this.#playback.value;
+if (media?.paused) media.play();
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+### Feature selectors
+Each feature also has a pre-built selector (e.g. <DocsLink slug="reference/feature-playback">`selectPlayback`</DocsLink>, <DocsLink slug="reference/feature-volume">`selectVolume`</DocsLink>) that returns just that feature's state and actions:
+
+```tsx
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+const playback = Player.usePlayer(selectPlayback);
+playback?.play();
+```
+</FrameworkCase>
+
+### Checking for feature support
+
+Volume, fullscreen, and picture-in-picture expose an `*Availability` property because platform support varies. For example, iOS Safari doesn't allow programmatic volume control.
+
+| Value | Meaning |
+|---|---|
+| `'available'` | Ready to use |
+| `'unavailable'` | Could work, not ready yet |
+| `'unsupported'` | Platform can never do this |
+
+Components that depend on availability (like <DocsLink slug="reference/pip-button">`PiPButton`</DocsLink> and <DocsLink slug="reference/fullscreen-button">`FullscreenButton`</DocsLink>) expose a `data-availability` attribute, so you can hide unsupported controls with CSS:
+
+<FrameworkCase frameworks={["html"]}>
+```css
+media-pip-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["react"]}>
+```css
+.pip-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+</FrameworkCase>
+
+You can also check availability in JS:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="PiPControl.tsx"
+function PiPControl() {
+  const availability = Player.usePlayer((s) => s.pipAvailability);
+
+  if (availability === 'unsupported') return null;
+
+  return <PiPButton />;
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```ts
+const media = this.#pip.value;
+
+if (media?.availability === 'unsupported') {
+  this.hidden = true;
+}
+```
+</FrameworkCase>
diff --git a/site/src/content/docs/concepts/overview.mdx b/site/src/content/docs/concepts/overview.mdx
new file mode 100644
index 00000000..856d8418
--- /dev/null
+++ b/site/src/content/docs/concepts/overview.mdx
@@ -0,0 +1,190 @@
+---
+title: Overview
+description: How Video.js players are structured — state, UI, and media
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+import Aside from '@/components/Aside.astro';
+
+Video.js v10 is built around a three-part architecture that separates concerns and maximizes flexibility. Each part is designed to work independently or together, allowing you to use as much or as little of Video.js as you need.
+
+## 1. State management
+<FrameworkCase frameworks={["react"]}>
+State is handled by a `Player.Provider`, which creates a central state store that all components can access. When you wrap your player in a `Player.Provider`, the components automatically connect to the state.
+
+```tsx
+<Player.Provider>
+  {/* All components inside automatically connect to state */}
+</Player.Provider>
+```
+
+You can access state and actions from anywhere within the provider with the <DocsLink slug="reference/use-player">`usePlayer` hook</DocsLink>.
+
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+State is handled by a `video-player` element, which creates a central state store that all components can access. Child components can automatically connect to the state of the `video-player` element.
+
+```html
+<video-player>
+  <!-- All components inside automatically connect to state -->
+</video-player>
+```
+
+You can access state and actions from anywhere within `<video-player>` with <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink>.
+</FrameworkCase>
+
+<DocsLinkCard slug="concepts/features">Learn more about state and actions</DocsLinkCard>
+
+
+## 2. User interface
+
+Use a prebuilt **skin** or build your own from the individual **UI components**.
+
+
+### Skins
+Skins are complete, pre-designed player UIs that package components and styles together:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+</FrameworkCase>
+
+<DocsLinkCard slug="concepts/skins">Learn more about skins</DocsLinkCard>
+
+### UI components
+
+If you want more control than skins offer you, you can build your own UI from our components.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+
+  <Player.Container>
+    <Video src="video.mp4" />
+    <MediaControls>
+      <PlayButton />
+      {/* ... */}
+    </MediaControls>
+  </Player.Container>
+
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+    <media-controls>
+      <media-play-button></media-play-button>
+      <!-- ... -->
+    </media-controls>
+  </media-container>
+
+</video-player>
+```
+</FrameworkCase>
+
+To get started with UI components, you might consider <DocsLink slug="how-to/customize-skins">ejecting a skin</DocsLink> and using its pre-styled components as a foundation.
+
+<DocsLinkCard slug="concepts/ui-components">Learn more about UI components</DocsLinkCard>
+
+## 3. Media
+
+Media components are the components that actually display your media. They're essentially "players with no UI". They handle the video/audio rendering and expose a consistent API.
+
+Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
+
+<FrameworkCase frameworks={["html"]}>
+Media elements are detected via a `slot="media"` attribute. Always include it on your `<video>`, `<audio>`, or custom media element.
+</FrameworkCase>
+
+<Aside type="note">
+DASH, YouTube, Vimeo, Mux, and more media elements are currently under development.
+</Aside>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <VideoSkin>
+
+    <HlsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
+
+  </VideoSkin>
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <video-skin>
+
+    <hls-video slot="media" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></hls-video>
+
+  </video-skin>
+</video-player>
+```
+</FrameworkCase>
+
+## Presets
+
+**Presets** preconfigure these parts for a specific use case.
+
+The default presets are `/video` and `/audio`, covering the baseline set of controls you'd expect from the HTML `<video>` and `<audio>` tags. 
+
+Beyond the defaults, presets target more specific use cases. For example, `/background` includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power it:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { createPlayer } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo, BackgroundVideoSkin } from '@videojs/react/background';
+
+const Player = createPlayer({ features: backgroundFeatures });
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </Player.Provider>
+  );
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<script type="module">
+  import '@videojs/html/background/player';
+  import '@videojs/html/background/video';
+  import '@videojs/html/background/skin';
+  import '@videojs/html/background/skin.css';
+</script>
+
+<background-video-player>
+  <background-video-skin>
+    <background-video slot="media" src="hero.mp4"></background-video>
+  </background-video-skin>
+</background-video-player>
+```
+</FrameworkCase>
+
+<DocsLinkCard slug="concepts/presets">Learn more about presets</DocsLinkCard>
diff --git a/site/src/content/docs/concepts/presets.mdx b/site/src/content/docs/concepts/presets.mdx
new file mode 100644
index 00000000..c3ec72a5
--- /dev/null
+++ b/site/src/content/docs/concepts/presets.mdx
@@ -0,0 +1,164 @@
+---
+title: Presets
+description: Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import Aside from '@/components/Aside.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+A **preset** packages what you need for a specific player use case. It can include special <DocsLink slug="concepts/features">state management</DocsLink>, one or more <DocsLink slug="concepts/skins">skins</DocsLink> for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you're building.
+
+For example, the `/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="App.tsx"
+import { createPlayer } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo, BackgroundVideoSkin } from '@videojs/react/background'; // [!code focus]
+
+const Player = createPlayer({ features: backgroundFeatures });
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </Player.Provider>
+  );
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html title="index.html"
+<script type="module">
+  import '@videojs/html/background/player';
+  import '@videojs/html/background/video';
+  import '@videojs/html/background/skin';
+  import '@videojs/html/background/skin.css';
+</script>
+
+<background-video-player>
+  <background-video-skin>
+    <background-video slot="media" src="hero.mp4"></background-video>
+  </background-video-skin>
+</background-video-player>
+```
+</FrameworkCase>
+
+## Available presets
+
+The default presets are `/video` and `/audio`. These cover the baseline controls you'd expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we'll add more: short-form players, podcast players, TV streaming players, and others.
+
+<FrameworkCase frameworks={["react"]}>
+
+| Preset | Feature bundle | Skins | Default media element |
+|--------|---------------|-------|-----------------------|
+| `/video` | `videoFeatures` | `<VideoSkin>`, `<MinimalVideoSkin>` | `<Video>` |
+| `/audio` | `audioFeatures` | `<AudioSkin>`, `<MinimalAudioSkin>` | `<Audio>` |
+| `/background` | `backgroundFeatures` | `<BackgroundVideoSkin>` | `<BackgroundVideo>` |
+
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+
+| Preset | Skins | Default media element |
+|--------|-------|-----------------------|
+| `/video` | `<video-skin>`, `<video-minimal-skin>` | `<video>` |
+| `/audio` | `<audio-skin>`, `<audio-minimal-skin>` | `<audio>` |
+| `/background` | `<background-video-skin>` | `<background-video>` |
+
+</FrameworkCase>
+
+## What's in a preset
+
+Each preset exports up to three things:
+
+- **Feature bundle** — An array of <DocsLink slug="concepts/features">features</DocsLink> that define the player's state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
+- **Skins** — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn't.
+- **Media element** — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.
+
+These parts aren't equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
+
+## Customizing a preset
+
+You can customize a preset in three ways: extend its feature bundle, eject its skin, or swap its media element.
+
+### Extend the feature bundle
+
+Add features to a preset's feature bundle to enable new functionality. For example, adding playback controls to a background video:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="App.tsx"
+import { createPlayer, playback } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
+
+const Player = createPlayer({
+  features: [...backgroundFeatures, playback],
+});
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <BackgroundVideo src="hero.mp4" />
+        <PlayButton />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html title="index.html"
+<script type="module">
+  import { createPlayer, playback, MediaElement } from '@videojs/html';
+  import { backgroundFeatures } from '@videojs/html/background';
+  import '@videojs/html/media/container';
+  import '@videojs/html/ui/play-button';
+
+  const { ProviderMixin } = createPlayer({
+    features: [...backgroundFeatures, playback],
+  });
+
+  class MyPlayer extends ProviderMixin(MediaElement) {
+    static readonly tagName = 'my-player';
+  }
+
+  customElements.define('my-player', MyPlayer);
+</script>
+
+<my-player>
+  <media-container>
+    <background-video slot="media" src="hero.mp4"></background-video>
+    <media-play-button>Play / Pause</media-play-button>
+  </media-container>
+</my-player>
+```
+</FrameworkCase>
+
+### Eject the skin
+
+If a preset's skin is close but not quite right, you can <DocsLink slug="how-to/customize-skins">eject it</DocsLink> — copy its internal components into your project and customize from there.
+
+### Swap the media element
+
+A preset's default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <VideoSkin>
+    <HlsVideo src="https://example.com/stream.m3u8" />
+  </VideoSkin>
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <video-skin>
+    <hls-video slot="media" src="https://example.com/stream.m3u8"></hls-video>
+  </video-skin>
+</video-player>
+```
+</FrameworkCase>
diff --git a/site/src/content/docs/concepts/skins.mdx b/site/src/content/docs/concepts/skins.mdx
new file mode 100644
index 00000000..7c6c9f3e
--- /dev/null
+++ b/site/src/content/docs/concepts/skins.mdx
@@ -0,0 +1,331 @@
+---
+title: Skins
+description: Packaged player designs that include both UI components and their styles.
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import { FrostedSkinDemo } from '@/examples/react/FrostedSkin/FrostedSkinDemo';
+import { MinimalSkinDemo } from '@/examples/react/MinimalSkin/MinimalSkinDemo';
+import MinimalFrame from '@/components/frames/Minimal.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+import Aside from '@/components/Aside.astro';
+
+
+<Aside type="note" title="New in version 10">
+In prior versions of Video.js, skins were CSS-only themes applied to the same set of default controls. In version 10 the concept of skins has been expanded to include the UI components, so each skin can be completely unique and only include the UI components it needs.
+</Aside>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <video-skin><!-- [!code focus] -->
+    <!-- wraps the media element -->
+    <video slot="media" src="video.mp4"></video>
+  </video-skin><!-- [!code focus] -->
+</video-player>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <VideoSkin> {/* [!code focus] */}
+    {/* wraps the Media component */}
+    <Video src="video.mp4"></Video>
+  </VideoSkin> {/* [!code focus] */}
+</Player.Provider>
+```
+</FrameworkCase>
+
+
+## Packaged vs. ejected
+
+When you choose a skin you have two options for how you use it: **packaged** or **ejected**. It's usually easiest to start with a packaged skin and later eject its internal components into your project when you need more customization.
+
+| Packaged | Ejected |
+|----------|-----------------|
+| Single component | Many UI components |
+| Limited customization | Complete customization |
+| Future design updates auto-applied by bumping the version | Future design updates manually applied, or intentionally ignored |
+
+<DocsLinkCard slug="how-to/customize-skins">Read more about ejecting skins</DocsLinkCard>
+<DocsLinkCard slug="concepts/ui-components">Read more about UI Components</DocsLinkCard>
+
+### Example of packaged
+<FrameworkCase frameworks={["html"]}>
+```html
+  <video-player>
+    <video-skin> 
+      <!--...Media...-->
+    </video-skin>
+  </video-player>
+
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["react"]}>
+```tsx
+  <Player.Provider>
+    <VideoSkin>
+      {/* ...Media... */}
+    </VideoSkin>
+  </Player.Provider>
+```
+</FrameworkCase>
+
+### Example of ejected
+<FrameworkCase frameworks={["html"]}>
+```html title="index.html"
+  <video-player>
+    <media-container class="media-default-skin">
+      <!-- ...Media... -->
+
+      <media-buffering-indicator class="media-buffering-indicator"></media-buffering-indicator>
+
+      <!-- Control Bar -->
+      <media-controls class="media-surface media-controls" data-visible="">
+        <media-play-button class="media-button media-button--icon media-button--play" role="button" tabindex="0" aria-label="Play" data-paused="">
+          <svg class="media-icon media-icon--restart" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M9 17a8 8 0 0 1-8-8h2a6 6 0 1 0 1.287-3.713l1.286 1.286A.25.25 0 0 1 5.396 7H1.25A.25.25 0 0 1 1 6.75V2.604a.25.25 0 0 1 .427-.177l1.438 1.438A8 8 0 1 1 9 17"></path><path fill="currentColor" d="m11.61 9.639-3.331 2.07a.826.826 0 0 1-1.15-.266.86.86 0 0 1-.129-.452V6.849C7 6.38 7.374 6 7.834 6c.158 0 .312.045.445.13l3.331 2.071a.858.858 0 0 1 0 1.438"></path></svg>
+          <svg class="media-icon media-icon--play" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="m14.051 10.723-7.985 4.964a1.98 1.98 0 0 1-2.758-.638A2.06 2.06 0 0 1 3 13.964V4.036C3 2.91 3.895 2 5 2c.377 0 .747.109 1.066.313l7.985 4.964a2.057 2.057 0 0 1 .627 2.808c-.16.257-.373.475-.627.637"></path></svg>
+          <svg class="media-icon media-icon--pause" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><rect width="5" height="14" x="2" y="2" fill="currentColor" rx="1.75"></rect><rect width="5" height="14" x="11" y="2" fill="currentColor" rx="1.75"></rect></svg>
+        </media-play-button>
+
+        <media-seek-button seconds="-10" class="media-button media-button--icon media-button--seek" role="button" tabindex="0" aria-label="Seek backward 10 seconds" data-direction="backward">
+          <span class="media-icon__container">
+            <svg class="media-icon media-icon--flipped" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M1 9c0 2.21.895 4.21 2.343 5.657l1.414-1.414a6 6 0 1 1 8.956-7.956l-1.286 1.286a.25.25 0 0 0 .177.427h4.146a.25.25 0 0 0 .25-.25V2.604a.25.25 0 0 0-.427-.177l-1.438 1.438A8 8 0 0 0 1 9"></path></svg>
+            <span class="media-icon__label">10</span>
+          </span>
+        </media-seek-button>
+
+        <media-seek-button seconds="10" class="media-button media-button--icon media-button--seek" role="button" tabindex="0" aria-label="Seek forward 10 seconds" data-direction="forward">
+          <span class="media-icon__container">
+            <svg class="media-icon" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M1 9c0 2.21.895 4.21 2.343 5.657l1.414-1.414a6 6 0 1 1 8.956-7.956l-1.286 1.286a.25.25 0 0 0 .177.427h4.146a.25.25 0 0 0 .25-.25V2.604a.25.25 0 0 0-.427-.177l-1.438 1.438A8 8 0 0 0 1 9"></path></svg>
+            <span class="media-icon__label">10</span>
+          </span>
+        </media-seek-button>
+
+        <media-time-group class="media-time">
+          <media-time type="current" class="media-time__value" aria-label="Current time" aria-valuetext="0 seconds" data-type="current"><span aria-hidden="true" hidden=""></span>0:00</media-time>
+          <media-time-slider class="media-slider" style="touch-action: none; user-select: none; --media-slider-fill: 0.000%; --media-slider-pointer: 0.000%; --media-slider-buffer: 9.873%;" data-orientation="horizontal">
+            <media-slider-track class="media-slider__track" data-orientation="horizontal">
+              <media-slider-fill class="media-slider__fill" data-orientation="horizontal"></media-slider-fill>
+              <media-slider-buffer class="media-slider__buffer" data-orientation="horizontal"></media-slider-buffer>
+            </media-slider-track>
+            <media-slider-thumb class="media-slider__thumb" role="slider" tabindex="0" autocomplete="off" aria-label="Seek" aria-valuemin="0" aria-valuemax="25.322667" aria-valuenow="0" aria-orientation="horizontal" aria-valuetext="0 seconds of 25 seconds" data-orientation="horizontal"></media-slider-thumb>
+          </media-time-slider>
+          <media-time type="duration" class="media-time__value" aria-label="Duration" aria-valuetext="25 seconds" data-type="duration"><span aria-hidden="true" hidden=""></span>0:25</media-time>
+        </media-time-group>
+
+        <media-playback-rate-button class="media-button media-button--icon media-button--playback-rate" role="button" tabindex="0" aria-label="Playback rate 1" data-rate="1">
+        </media-playback-rate-button>
+
+        <media-mute-button commandfor="volume-popover" class="media-button media-button--icon media-button--mute" role="button" tabindex="0" aria-label="Mute" data-volume-level="high" aria-expanded="false" aria-haspopup="dialog" aria-controls="volume-popover" style="anchor-name: --volume-popover;">
+          <svg class="media-icon media-icon--volume-off" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M.714 6.008h3.072l4.071-3.857c.5-.376 1.143 0 1.143.601V15.28c0 .602-.643.903-1.143.602l-4.071-3.858H.714c-.428 0-.714-.3-.714-.752V6.76c0-.451.286-.752.714-.752M14.5 7.586l-1.768-1.768a1 1 0 1 0-1.414 1.414L13.085 9l-1.767 1.768a1 1 0 0 0 1.414 1.414l1.768-1.768 1.768 1.768a1 1 0 0 0 1.414-1.414L15.914 9l1.768-1.768a1 1 0 0 0-1.414-1.414z"></path></svg>
+          <svg class="media-icon media-icon--volume-low" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M.714 6.008h3.072l4.071-3.857c.5-.376 1.143 0 1.143.601V15.28c0 .602-.643.903-1.143.602l-4.071-3.858H.714c-.428 0-.714-.3-.714-.752V6.76c0-.451.286-.752.714-.752m10.568.59a.91.91 0 0 1 0-1.316.91.91 0 0 1 1.316 0c1.203 1.203 1.47 2.216 1.522 3.208q.012.255.011.51c0 1.16-.358 2.733-1.533 3.803a.7.7 0 0 1-.298.156c-.382.106-.873-.011-1.018-.156a.91.91 0 0 1 0-1.316c.57-.57.995-1.551.995-2.487 0-.944-.26-1.667-.995-2.402"></path></svg>
+          <svg class="media-icon media-icon--volume-high" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M15.6 3.3c-.4-.4-1-.4-1.4 0s-.4 1 0 1.4C15.4 5.9 16 7.4 16 9s-.6 3.1-1.8 4.3c-.4.4-.4 1 0 1.4.2.2.5.3.7.3.3 0 .5-.1.7-.3C17.1 13.2 18 11.2 18 9s-.9-4.2-2.4-5.7"></path><path fill="currentColor" d="M.714 6.008h3.072l4.071-3.857c.5-.376 1.143 0 1.143.601V15.28c0 .602-.643.903-1.143.602l-4.071-3.858H.714c-.428 0-.714-.3-.714-.752V6.76c0-.451.286-.752.714-.752m10.568.59a.91.91 0 0 1 0-1.316.91.91 0 0 1 1.316 0c1.203 1.203 1.47 2.216 1.522 3.208q.012.255.011.51c0 1.16-.358 2.733-1.533 3.803a.7.7 0 0 1-.298.156c-.382.106-.873-.011-1.018-.156a.91.91 0 0 1 0-1.316c.57-.57.995-1.551.995-2.487 0-.944-.26-1.667-.995-2.402"></path></svg>
+        </media-mute-button>
+
+        <media-popover id="volume-popover" open-on-hover="" delay="200" close-delay="100" side="top" class="media-surface media-popup media-popup--volume media-popup-animation" popover="manual" role="dialog" data-side="top" data-align="center">
+          <media-volume-slider class="media-slider" orientation="vertical" thumb-alignment="edge" style="touch-action: none; user-select: none; --media-slider-fill: 100.000%; --media-slider-pointer: 0.000%;" data-orientation="vertical">
+            <media-slider-track class="media-slider__track" data-orientation="vertical">
+              <media-slider-fill class="media-slider__fill" data-orientation="vertical"></media-slider-fill>
+            </media-slider-track>
+            <media-slider-thumb class="media-slider__thumb media-slider__thumb--persistent" role="slider" tabindex="0" autocomplete="off" aria-label="Volume" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-orientation="vertical" aria-valuetext="100 percent" data-orientation="vertical"></media-slider-thumb>
+          </media-volume-slider>
+        </media-popover>
+
+        <media-fullscreen-button class="media-button media-button--icon media-button--fullscreen" role="button" tabindex="0" aria-label="Enter fullscreen" data-availability="available">
+          <svg class="media-icon media-icon--fullscreen-enter" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M9.57 3.617A1 1 0 0 0 8.646 3H4c-.552 0-1 .449-1 1v4.646a.996.996 0 0 0 1.001 1 1 1 0 0 0 .706-.293l4.647-4.647a1 1 0 0 0 .216-1.089m4.812 4.812a1 1 0 0 0-1.089.217l-4.647 4.647a.998.998 0 0 0 .708 1.706H14c.552 0 1-.449 1-1V9.353a1 1 0 0 0-.618-.924"></path></svg>
+          <svg class="media-icon media-icon--fullscreen-exit" xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="none" viewBox="0 0 18 18"><path fill="currentColor" d="M7.883 1.93a.99.99 0 0 0-1.09.217L2.146 6.793A.998.998 0 0 0 2.853 8.5H7.5c.551 0 1-.449 1-1V2.854a1 1 0 0 0-.617-.924m7.263 7.57H10.5c-.551 0-1 .449-1 1v4.646a.996.996 0 0 0 1.001 1.001 1 1 0 0 0 .706-.293l4.646-4.646a.998.998 0 0 0-.707-1.707z"></path></svg>
+        </media-fullscreen-button>
+      </media-controls>
+
+    </media-container>
+  </video-player>
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="VideoSkin.tsx"
+  <Player.Provider>
+    <Container className={cn('media-minimal-skin', className)} {...rest}>
+      <BufferingIndicator
+        render={(props) => (
+          <div {...props} className="media-buffering-indicator">
+            <SpinnerIcon className="media-icon" />
+          </div>
+        )}
+      />
+
+      <ErrorDialog
+        aria-labelledby="media-error-title"
+        aria-describedby="media-error-description"
+        render={(props, { onDismiss }) => (
+          <div {...props} className="media-error">
+            <div className="media-error__dialog">
+              <div className="media-error__content">
+                <p id="media-error-title" className="media-error__title">
+                  Something went wrong.
+                </p>
+                <p id="media-error-description" className="media-error__description">
+                  An error occurred while trying to play the video. Please try again.
+                </p>
+              </div>
+              <div className="media-error__actions">
+                <Button onClick={onDismiss}>OK</Button>
+              </div>
+            </div>
+          </div>
+        )}
+      />
+
+      <Controls.Root className="media-controls">
+        <span className="media-button-group">
+          <PlayButton
+            render={(props) => (
+              <Button {...props} className="media-button--icon media-button--play">
+                <RestartIcon className="media-icon media-icon--restart" />
+                <PlayIcon className="media-icon media-icon--play" />
+                <PauseIcon className="media-icon media-icon--pause" />
+              </Button>
+            )}
+          />
+
+          <SeekButton
+            seconds={-SEEK_TIME}
+            render={(props) => (
+              <Button {...props} className="media-button--icon media-button--seek">
+                <span className="media-icon__container">
+                  <SeekIcon className="media-icon media-icon--seek media-icon--flipped" />
+                  <span className="media-icon__label">{SEEK_TIME}</span>
+                </span>
+              </Button>
+            )}
+          />
+
+          <SeekButton
+            seconds={SEEK_TIME}
+            render={(props) => (
+              <Button {...props} className="media-button--icon media-button--seek">
+                <span className="media-icon__container">
+                  <SeekIcon className="media-icon media-icon--seek" />
+                  <span className="media-icon__label">{SEEK_TIME}</span>
+                </span>
+              </Button>
+            )}
+          />
+        </span>
+
+        <span className="media-time-controls">
+          <Time.Group className="media-time">
+            <Time.Value type="current" className="media-time__value media-time__value--current" />
+            <Time.Separator className="media-time__separator" />
+            <Time.Value type="duration" className="media-time__value media-time__value--duration" />
+          </Time.Group>
+
+          <TimeSlider.Root className="media-slider">
+            <TimeSlider.Track className="media-slider__track">
+              <TimeSlider.Fill className="media-slider__fill" />
+              <TimeSlider.Buffer className="media-slider__buffer" />
+            </TimeSlider.Track>
+            <TimeSlider.Thumb className="media-slider__thumb" />
+          </TimeSlider.Root>
+        </span>
+
+        <span className="media-button-group">
+          <PlaybackRateButton
+            render={(props) => <Button {...props} className="media-button--icon media-button--playback-rate" />}
+          />
+
+          <Popover.Root openOnHover delay={200} closeDelay={100} side="top">
+            <Popover.Trigger
+              render={
+                <MuteButton
+                  render={(props) => (
+                    <Button {...props} className="media-button--icon media-button--mute">
+                      <VolumeOffIcon className="media-icon media-icon--volume-off" />
+                      <VolumeLowIcon className="media-icon media-icon--volume-low" />
+                      <VolumeHighIcon className="media-icon media-icon--volume-high" />
+                    </Button>
+                  )}
+                />
+              }
+            />
+            <Popover.Popup className="media-surface media-popup media-popup--volume media-popup-animation">
+              <VolumeSlider.Root className="media-slider" orientation="vertical" thumbAlignment="edge">
+                <VolumeSlider.Track className="media-slider__track">
+                  <VolumeSlider.Fill className="media-slider__fill" />
+                </VolumeSlider.Track>
+                <VolumeSlider.Thumb className="media-slider__thumb media-slider__thumb--persistent" />
+              </VolumeSlider.Root>
+            </Popover.Popup>
+          </Popover.Root>
+
+          <CaptionsButton
+            render={(props) => (
+              <Button {...props} className="media-button--icon media-button--captions">
+                <CaptionsOffIcon className="media-icon media-icon--captions-off" />
+                <CaptionsOnIcon className="media-icon media-icon--captions-on" />
+              </Button>
+            )}
+          />
+
+          <PiPButton
+            render={(props) => (
+              <Button {...props} className="media-button--icon">
+                <PipIcon className="media-icon" />
+              </Button>
+            )}
+          />
+
+          <FullscreenButton
+            render={(props) => (
+              <Button {...props} className="media-button--icon media-button--fullscreen">
+                <FullscreenEnterIcon className="media-icon media-icon--fullscreen-enter" />
+                <FullscreenExitIcon className="media-icon media-icon--fullscreen-exit" />
+              </Button>
+            )}
+          />
+        </span>
+      </Controls.Root>
+
+      {/* <div className="media-captions">
+        <div className="media-captions__container">
+          <span className="media-captions__text">An example cue</span>
+          <span className="media-captions__text">
+            <p>Another example cue with HTML</p>
+          </span>
+        </div>
+      </div> */}
+
+      <div className="media-overlay" />
+
+      {children}
+    </Container>
+  </Player.Provider>
+```
+</FrameworkCase>
+
+
+## Skins, features, and presets
+
+Each skin is built with specific <DocsLink slug="concepts/features">features</DocsLink> in mind. For example, a video skin renders fullscreen and picture-in-picture controls. An audio skin doesn't. The features associated with a skin are called a **feature bundle**.
+
+<FrameworkCase frameworks={["html"]}>
+| Player with feature bundle | Available skins | Import |
+|----------|-----------------|--------|
+| `<video-player>` | `<video-skin>`, `<video-minimal-skin>` | `@videojs/html/video/*` |
+| `<audio-player>` | `<audio-skin>`, `<audio-minimal-skin>` | `@videojs/html/audio/*` |
+| `<background-video-player>` | `<background-video-skin>` | `@videojs/html/background/*` |
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+| Feature bundle | Available skins | Import |
+|----------|-----------------|--------|
+| `videoFeatures` | `<VideoSkin>`, `<MinimalVideoSkin>` | `@videojs/react/video` |
+| `audioFeatures` | `<AudioSkin>`, `<MinimalAudioSkin>` | `@videojs/react/audio` |
+| `backgroundFeatures` | `<BackgroundVideoSkin>` | `@videojs/react/background` |
+</FrameworkCase>
+
+Want to learn more about skins and feature bundles? Check out the presets guide:
+
+<DocsLinkCard slug="concepts/presets">Learn more about presets</DocsLinkCard>
diff --git a/site/src/content/docs/concepts/ui-components.mdx b/site/src/content/docs/concepts/ui-components.mdx
new file mode 100644
index 00000000..e3f9876a
--- /dev/null
+++ b/site/src/content/docs/concepts/ui-components.mdx
@@ -0,0 +1,137 @@
+---
+title: UI components
+description: How Video.js UI components work — one element per component, data attributes for state, and compound composition.
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+
+UI components are controls like buttons, sliders, and time displays.
+
+Every UI component renders exactly one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you.
+
+## Where to put your components
+<FrameworkCase frameworks={["react"]}>
+UI Components can go anywhere inside a <DocsLink slug="reference/player-provider">`<Player.Provider>`</DocsLink>.
+
+However, you should consider placing your components in `<Player.Container>`. Components in `<Player.Container>` will go fullscreen with the player, respond to user activity, and more.
+
+<DocsLinkCard slug="reference/player-container">Read more about `<Player.Container>`</DocsLinkCard>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+UI Components can go anywhere inside a <DocsLink slug="reference/player-provider">`<video-player>`</DocsLink>. 
+
+However, you should consider placing your components in `<player-container>`. Components in `<player-container>` will go fullscreen with the player, respond to user activity, and more.
+
+<DocsLinkCard slug="reference/player-container">Read more about `<player-container>`</DocsLinkCard>
+</FrameworkCase>
+
+## Styling and customization
+
+<FrameworkCase frameworks={["react"]}>
+
+### The `render` prop
+
+The `render` prop is the primary customization mechanism. It accepts a function that receives `props` and `state`, and returns your element. The `props` object includes event handlers, ARIA attributes, data attributes, and a ref — always spread `{...props}` to keep everything working:
+
+```tsx
+<PlayButton
+  render={(props, state) => (
+    <button {...props}>
+      {state.paused ? 'Play' : 'Pause'}
+    </button>
+  )}
+/>
+```
+
+`className` and `style` also accept functions of state for dynamic styling without a full render prop:
+
+```tsx
+<PlayButton
+  className={(state) =>
+    state.paused ? 'btn btn--paused' : 'btn btn--playing'
+  }
+/>
+```
+
+### Data attributes and CSS custom properties
+
+Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
+
+This lets you style state changes in pure CSS:
+
+```css
+/* Show/hide icons based on play state */
+.play-icon  { display: none; }
+.pause-icon { display: none; }
+
+button[data-paused] .play-icon        { display: inline; }
+button:not([data-paused]) .pause-icon { display: inline; }
+```
+
+Each component's reference page documents its full set of data attributes.
+
+Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
+
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+
+Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
+
+This lets you style state changes in pure CSS:
+
+```html
+<media-play-button class="my-play-button">
+  <span class="play-icon">Play</span>
+  <span class="pause-icon">Pause</span>
+</media-play-button>
+```
+
+```css
+media-play-button .play-icon  { display: none; }
+media-play-button .pause-icon { display: none; }
+
+media-play-button[data-paused] .play-icon        { display: inline; }
+media-play-button:not([data-paused]) .pause-icon  { display: inline; }
+```
+
+Each component's reference page documents its full set of data attributes.
+
+Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
+
+</FrameworkCase>
+
+## Compound components
+
+Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each part is still one element.
+
+<FrameworkCase frameworks={["react"]}>
+
+Compound components use dot notation off a shared namespace:
+
+```tsx
+<VolumeSlider.Root orientation="vertical">
+  <VolumeSlider.Track>
+    <VolumeSlider.Fill />
+  </VolumeSlider.Track>
+  <VolumeSlider.Thumb />
+</VolumeSlider.Root>
+```
+
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+
+```html
+<media-volume-slider orientation="vertical">
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-slider-thumb></media-slider-thumb>
+</media-volume-slider>
+```
+
+</FrameworkCase>
diff --git a/site/src/content/docs/concepts/v10-roadmap.mdx b/site/src/content/docs/concepts/v10-roadmap.mdx
index f3468ccb..32807a6c 100644
--- a/site/src/content/docs/concepts/v10-roadmap.mdx
+++ b/site/src/content/docs/concepts/v10-roadmap.mdx
@@ -17,19 +17,18 @@ Video.js v10 is a complete rebuild from the ground up, designed to be more modul
 ### Version 9
 
 - Reserved only for urgent API-breaking changes that cannot be avoided
-- Acts as a stopgap between v8 and the new v10 rebuild
 
 ## March 2026: v10 Beta Release
 
 Wider testing release to the community.
 
-**Core feature parity target:**
+### Core feature parity target
 
 - Basic control set (play, pause, seek, volume, fullscreen)
 - Adaptive streaming support via existing community engines
 - No plugin migrations yet, without plugin author contribution
 
-**What to expect:**
+### What to expect
 
 - Close to stable, but API changes are still possible
 - Intended for experimental adoption in real-world projects
@@ -39,14 +38,14 @@ Wider testing release to the community.
 
 **Stable release** of Video.js v10
 
-**Feature targets:**
+### Feature targets
 
 - Core feature parity with v8 in terms of fundamentals
 - Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
 - Community encouraged to begin full reintegration projects
 - Plugin ecosystem migration begins in earnest
 
-**Engine development focus:**
+### Engine development focus
 
 - Lightweight adaptive streaming
 - MoQ (Media over QUIC) support
@@ -74,4 +73,4 @@ Wider testing release to the community.
 
 ---
 
-**Want to contribute?** Check out the [Video.js repository on GitHub](https://github.com/videojs) to get involved in the v10 rebuild.
+**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved in the rebuild
diff --git a/site/src/content/docs/how-to/customize-skins.mdx b/site/src/content/docs/how-to/customize-skins.mdx
index a6a3a9ce..7d5756f4 100644
--- a/site/src/content/docs/how-to/customize-skins.mdx
+++ b/site/src/content/docs/how-to/customize-skins.mdx
@@ -1,5 +1,5 @@
 ---
-title: Customize Skins
+title: Customize skins
 description: Learn how to customize Video.js v10 skins by copying and modifying them
 ---
 
diff --git a/site/src/content/docs/how-to/installation.mdx b/site/src/content/docs/how-to/installation.mdx
index 6cff0339..55639904 100644
--- a/site/src/content/docs/how-to/installation.mdx
+++ b/site/src/content/docs/how-to/installation.mdx
@@ -41,7 +41,7 @@ Video.js aims to provide idiomatic development experiences in your favorite JS a
 
 ## Choose your use case
 
-The defaults work well for general website playback. More prebuilt players to come.
+The default presets work well for general website playback. More pre-built players to come.
 
 <ContentWidth margins="lg">
   <UseCasePicker client:idle />
diff --git a/site/src/content/docs/reference/create-player.mdx b/site/src/content/docs/reference/create-player.mdx
index ae1b69c9..9d98f5c7 100644
--- a/site/src/content/docs/reference/create-player.mdx
+++ b/site/src/content/docs/reference/create-player.mdx
@@ -19,8 +19,8 @@ The hook is typed according to the provided features, giving you full type safet
 import { createPlayer } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
-const player = createPlayer({ features: videoFeatures });
-const { Provider, Container, usePlayer, useMedia } = player;
+const Player = createPlayer({ features: videoFeatures });
+// Player.Provider, Player.Container, Player.usePlayer, Player.useMedia
 ```
 
 ## Examples
diff --git a/site/src/content/docs/reference/create-selector.mdx b/site/src/content/docs/reference/create-selector.mdx
index 0c9107ab..e14a9a2e 100644
--- a/site/src/content/docs/reference/create-selector.mdx
+++ b/site/src/content/docs/reference/create-selector.mdx
@@ -9,9 +9,9 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 `createSelector` creates a type-safe selector function for a given slice. The returned selector extracts that slice's state from the full store state, or returns `undefined` if the slice is not configured.
 
-The built-in selectors (<DocsLink slug="reference/select-playback">`selectPlayback`</DocsLink>, <DocsLink slug="reference/select-buffer">`selectBuffer`</DocsLink>, etc.) are all created with `createSelector`. Use it to create selectors for custom slices.
+The built-in selectors (<DocsLink slug="reference/feature-playback">`selectPlayback`</DocsLink>, <DocsLink slug="reference/feature-buffer">`selectBuffer`</DocsLink>, etc.) are all created with `createSelector`. Use it to create selectors for custom slices.
 
-```ts
+```ts title="my-custom-selector.ts"
 import { createSelector } from '@videojs/store';
 import { myCustomSlice } from './my-custom-slice';
 
diff --git a/site/src/content/docs/reference/select-buffer.mdx b/site/src/content/docs/reference/feature-buffer.mdx
similarity index 76%
rename from site/src/content/docs/reference/select-buffer.mdx
rename to site/src/content/docs/reference/feature-buffer.mdx
index 19be3b35..92a33bc1 100644
--- a/site/src/content/docs/reference/select-buffer.mdx
+++ b/site/src/content/docs/reference/feature-buffer.mdx
@@ -1,12 +1,23 @@
 ---
-title: selectBuffer
-description: Select the buffer state slice from the player store
+title: Buffer
+description: Buffered and seekable time range state for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Read-only — tracks buffered and seekable time ranges.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `buffered` | `[number, number][]` | Buffered time ranges as `[start, end]` tuples |
+| `seekable` | `[number, number][]` | Seekable time ranges as `[start, end]` tuples |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectBuffer` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.
 </FrameworkCase>
@@ -15,10 +26,8 @@ Pass `selectBuffer` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLi
 Pass `selectBuffer` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.
 </FrameworkCase>
 
-The returned state includes buffered ranges and percent buffered.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="BufferBar.tsx"
 import { selectBuffer, usePlayer } from '@videojs/react';
 
 function BufferBar() {
@@ -33,7 +42,7 @@ function BufferBar() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="buffer-bar.ts"
 import { createPlayer, MediaElement, selectBuffer } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-controls.mdx b/site/src/content/docs/reference/feature-controls.mdx
similarity index 76%
rename from site/src/content/docs/reference/select-controls.mdx
rename to site/src/content/docs/reference/feature-controls.mdx
index 87503368..ee6330e2 100644
--- a/site/src/content/docs/reference/select-controls.mdx
+++ b/site/src/content/docs/reference/feature-controls.mdx
@@ -1,12 +1,23 @@
 ---
-title: selectControls
-description: Select the controls state slice from the player store
+title: Controls
+description: User activity and controls visibility state for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Read-only — tracks user activity for showing and hiding controls.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `userActive` | `boolean` | Whether the user has recently interacted |
+| `controlsVisible` | `boolean` | Whether controls should be visible (active or paused) |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectControls` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to controls state. Returns `undefined` if the controls feature is not configured.
 </FrameworkCase>
@@ -15,10 +26,8 @@ Pass `selectControls` to <DocsLink slug="reference/use-player">`usePlayer`</Docs
 Pass `selectControls` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to controls state. Returns `undefined` if the controls feature is not configured.
 </FrameworkCase>
 
-The returned state includes whether controls are visible and whether the user is active (interacting with the player).
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="ControlsOverlay.tsx"
 import { selectControls, usePlayer } from '@videojs/react';
 
 function ControlsOverlay({ children }: { children: React.ReactNode }) {
@@ -35,7 +44,7 @@ function ControlsOverlay({ children }: { children: React.ReactNode }) {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="controls-overlay.ts"
 import { createPlayer, MediaElement, selectControls } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/feature-error.mdx b/site/src/content/docs/reference/feature-error.mdx
new file mode 100644
index 00000000..8eeb7833
--- /dev/null
+++ b/site/src/content/docs/reference/feature-error.mdx
@@ -0,0 +1,65 @@
+---
+title: Error
+description: Media error state and actions for the player store
+---
+
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import DocsLink from "@/components/docs/DocsLink.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+
+Tracks media errors.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `error` | `MediaError \| null` | The current error, or `null` |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `dismissError()` | Clear the current error |
+
+## Selector
+
+<FrameworkCase frameworks={["react"]}>
+Pass `selectError` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to error state. Returns `undefined` if the error feature is not configured.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+Pass `selectError` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to error state. Returns `undefined` if the error feature is not configured.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="ErrorDisplay.tsx"
+import { selectError, usePlayer } from '@videojs/react';
+
+function ErrorDisplay() {
+  const err = usePlayer(selectError);
+  if (!err?.error) return null;
+
+  return (
+    <div>
+      <p>{err.error.message}</p>
+      <button onClick={err.dismissError}>Dismiss</button>
+    </div>
+  );
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts title="error-display.ts"
+import { createPlayer, MediaElement, selectError } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class ErrorDisplay extends MediaElement {
+  readonly #error = new PlayerController(this, context, selectError);
+}
+```
+</FrameworkCase>
+
+<UtilReference util="selectError" />
diff --git a/site/src/content/docs/reference/select-fullscreen.mdx b/site/src/content/docs/reference/feature-fullscreen.mdx
similarity index 70%
rename from site/src/content/docs/reference/select-fullscreen.mdx
rename to site/src/content/docs/reference/feature-fullscreen.mdx
index 0639b6d0..63fae3a4 100644
--- a/site/src/content/docs/reference/select-fullscreen.mdx
+++ b/site/src/content/docs/reference/feature-fullscreen.mdx
@@ -1,12 +1,30 @@
 ---
-title: selectFullscreen
-description: Select the fullscreen state slice from the player store
+title: Fullscreen
+description: Fullscreen state and actions for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Controls fullscreen mode. Tries the container element first, falls back to the media element.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `fullscreen` | `boolean` | Whether fullscreen is active |
+| `fullscreenAvailability` | `MediaFeatureAvailability` | Whether fullscreen is supported |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `requestFullscreen()` | Enter fullscreen (returns a `Promise`) |
+| `exitFullscreen()` | Exit fullscreen (returns a `Promise`) |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectFullscreen` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.
 </FrameworkCase>
@@ -15,10 +33,8 @@ Pass `selectFullscreen` to <DocsLink slug="reference/use-player">`usePlayer`</Do
 Pass `selectFullscreen` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.
 </FrameworkCase>
 
-The returned state includes whether fullscreen is active and its availability on the current platform.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="FullscreenButton.tsx"
 import { selectFullscreen, usePlayer } from '@videojs/react';
 
 function FullscreenButton() {
@@ -35,7 +51,7 @@ function FullscreenButton() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="fullscreen-button.ts"
 import { createPlayer, MediaElement, selectFullscreen } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-pip.mdx b/site/src/content/docs/reference/feature-pip.mdx
similarity index 70%
rename from site/src/content/docs/reference/select-pip.mdx
rename to site/src/content/docs/reference/feature-pip.mdx
index 3ddee3ce..586a58ed 100644
--- a/site/src/content/docs/reference/select-pip.mdx
+++ b/site/src/content/docs/reference/feature-pip.mdx
@@ -1,12 +1,30 @@
 ---
-title: selectPiP
-description: Select the picture-in-picture state slice from the player store
+title: Picture-in-picture
+description: Picture-in-picture state and actions for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Controls picture-in-picture mode.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `pip` | `boolean` | Whether picture-in-picture is active |
+| `pipAvailability` | `MediaFeatureAvailability` | Whether PiP is supported |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `requestPictureInPicture()` | Enter picture-in-picture (returns a `Promise`) |
+| `exitPictureInPicture()` | Exit picture-in-picture (returns a `Promise`) |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectPiP` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.
 </FrameworkCase>
@@ -15,10 +33,8 @@ Pass `selectPiP` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink>
 Pass `selectPiP` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.
 </FrameworkCase>
 
-The returned state includes whether PiP is active and its availability on the current platform.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="PiPButton.tsx"
 import { selectPiP, usePlayer } from '@videojs/react';
 
 function PiPButton() {
@@ -35,7 +51,7 @@ function PiPButton() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="pip-button.ts"
 import { createPlayer, MediaElement, selectPiP } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-playback-rate.mdx b/site/src/content/docs/reference/feature-playback-rate.mdx
similarity index 74%
rename from site/src/content/docs/reference/select-playback-rate.mdx
rename to site/src/content/docs/reference/feature-playback-rate.mdx
index 34cd117a..e9bd87dd 100644
--- a/site/src/content/docs/reference/select-playback-rate.mdx
+++ b/site/src/content/docs/reference/feature-playback-rate.mdx
@@ -1,12 +1,29 @@
 ---
-title: selectPlaybackRate
-description: Select the playback rate state slice from the player store
+title: Playback rate
+description: Playback speed state and actions for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Controls speed of playback.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `playbackRate` | `number` | Current playback speed (1 = normal) |
+| `playbackRates` | `readonly number[]` | Available playback rates |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `setPlaybackRate(rate)` | Set the playback speed |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectPlaybackRate` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
 </FrameworkCase>
@@ -15,10 +32,8 @@ Pass `selectPlaybackRate` to <DocsLink slug="reference/use-player">`usePlayer`</
 Pass `selectPlaybackRate` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
 </FrameworkCase>
 
-The returned state includes `playbackRate`, `playbackRates`, and the `setPlaybackRate` action.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="RateDisplay.tsx"
 import { selectPlaybackRate, usePlayer } from '@videojs/react';
 
 function RateDisplay() {
@@ -31,7 +46,7 @@ function RateDisplay() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="rate-display.ts"
 import { createPlayer, MediaElement, selectPlaybackRate } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-playback.mdx b/site/src/content/docs/reference/feature-playback.mdx
similarity index 68%
rename from site/src/content/docs/reference/select-playback.mdx
rename to site/src/content/docs/reference/feature-playback.mdx
index f603db48..81eeea0d 100644
--- a/site/src/content/docs/reference/select-playback.mdx
+++ b/site/src/content/docs/reference/feature-playback.mdx
@@ -1,12 +1,31 @@
 ---
-title: selectPlayback
-description: Select the playback state slice from the player store
+title: Playback
+description: Play/pause state and actions for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Controls play/pause state and tracks whether playback has started or is stalled.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `paused` | `boolean` | Whether playback is paused |
+| `ended` | `boolean` | Whether playback reached the end |
+| `started` | `boolean` | Whether playback has started (played or seeked) |
+| `waiting` | `boolean` | Whether playback is stalled waiting for data |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `play()` | Start playback (returns a `Promise`) |
+| `pause()` | Pause playback |
+
+## Selector
 
 <FrameworkCase frameworks={["react"]}>
 Pass `selectPlayback` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to playback state. Returns `undefined` if the playback feature is not configured.
@@ -16,10 +35,8 @@ Pass `selectPlayback` to <DocsLink slug="reference/use-player">`usePlayer`</Docs
 Pass `selectPlayback` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to playback state. Returns `undefined` if the playback feature is not configured.
 </FrameworkCase>
 
-The returned state includes `paused`, `ended`, and action methods like `play`, `pause`, and `toggle`.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="PlayButton.tsx"
 import { selectPlayback, usePlayer } from '@videojs/react';
 
 function PlayButton() {
@@ -31,7 +48,7 @@ function PlayButton() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="play-button.ts"
 import { createPlayer, MediaElement, selectPlayback } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-source.mdx b/site/src/content/docs/reference/feature-source.mdx
similarity index 73%
rename from site/src/content/docs/reference/select-source.mdx
rename to site/src/content/docs/reference/feature-source.mdx
index 5499762d..a1e0955d 100644
--- a/site/src/content/docs/reference/select-source.mdx
+++ b/site/src/content/docs/reference/feature-source.mdx
@@ -1,12 +1,29 @@
 ---
-title: selectSource
-description: Select the source state slice from the player store
+title: Source
+description: Media source state and actions for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Tracks the current media source and readiness.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `source` | `string \| null` | Current media source URL |
+| `canPlay` | `boolean` | Whether enough data is loaded to begin playback |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `loadSource(src)` | Load a new media source |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectSource` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to source state. Returns `undefined` if the source feature is not configured.
 </FrameworkCase>
@@ -15,10 +32,8 @@ Pass `selectSource` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLi
 Pass `selectSource` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to source state. Returns `undefined` if the source feature is not configured.
 </FrameworkCase>
 
-The returned state includes the current `src` and `type`.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="SourceInfo.tsx"
 import { selectSource, usePlayer } from '@videojs/react';
 
 function SourceInfo() {
@@ -31,7 +46,7 @@ function SourceInfo() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="source-info.ts"
 import { createPlayer, MediaElement, selectSource } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/feature-text-tracks.mdx b/site/src/content/docs/reference/feature-text-tracks.mdx
new file mode 100644
index 00000000..f0c3ea4e
--- /dev/null
+++ b/site/src/content/docs/reference/feature-text-tracks.mdx
@@ -0,0 +1,68 @@
+---
+title: Text tracks
+description: Subtitles, captions, and chapter track state for the player store
+---
+
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import DocsLink from "@/components/docs/DocsLink.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+
+Manages subtitles, captions, chapters, and thumbnail tracks.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `textTrackList` | `MediaTextTrack[]` | All text tracks on the media element |
+| `subtitlesShowing` | `boolean` | Whether captions/subtitles are enabled |
+| `chaptersCues` | `MediaTextCue[]` | Cues from the first chapters track |
+| `thumbnailCues` | `MediaTextCue[]` | Cues from the first thumbnails track |
+| `thumbnailTrackSrc` | `string \| null` | Track `src` for resolving relative thumbnail URLs |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `toggleSubtitles(forceShow?)` | Toggle subtitle visibility. Pass `true`/`false` to force. |
+
+## Selector
+
+<FrameworkCase frameworks={["react"]}>
+Pass `selectTextTracks` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+Pass `selectTextTracks` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="CaptionsButton.tsx"
+import { selectTextTracks, usePlayer } from '@videojs/react';
+
+function CaptionsButton() {
+  const tracks = usePlayer(selectTextTracks);
+  if (!tracks) return null;
+
+  return (
+    <button onClick={() => tracks.toggleSubtitles()}>
+      {tracks.subtitlesShowing ? 'Hide captions' : 'Show captions'}
+    </button>
+  );
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```ts title="captions-button.ts"
+import { createPlayer, MediaElement, selectTextTracks } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class CaptionsButton extends MediaElement {
+  readonly #textTracks = new PlayerController(this, context, selectTextTracks);
+}
+```
+</FrameworkCase>
+
+<UtilReference util="selectTextTracks" />
diff --git a/site/src/content/docs/reference/select-time.mdx b/site/src/content/docs/reference/feature-time.mdx
similarity index 71%
rename from site/src/content/docs/reference/select-time.mdx
rename to site/src/content/docs/reference/feature-time.mdx
index 9b9d9ff4..d984a6d9 100644
--- a/site/src/content/docs/reference/select-time.mdx
+++ b/site/src/content/docs/reference/feature-time.mdx
@@ -1,12 +1,30 @@
 ---
-title: selectTime
-description: Select the time state slice from the player store
+title: Time
+description: Playback position and duration state for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Tracks playback position and duration.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `currentTime` | `number` | Current playback position in seconds |
+| `duration` | `number` | Total duration in seconds (0 if unknown) |
+| `seeking` | `boolean` | Whether a seek operation is in progress |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `seek(time)` | Seek to a position in seconds (returns a `Promise`) |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectTime` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to time state. Returns `undefined` if the time feature is not configured.
 </FrameworkCase>
@@ -15,10 +33,8 @@ Pass `selectTime` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink
 Pass `selectTime` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to time state. Returns `undefined` if the time feature is not configured.
 </FrameworkCase>
 
-The returned state includes `currentTime`, `duration`, and the `seek` action method.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="TimeDisplay.tsx"
 import { selectTime, usePlayer } from '@videojs/react';
 
 function TimeDisplay() {
@@ -35,7 +51,7 @@ function TimeDisplay() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="time-display.ts"
 import { createPlayer, MediaElement, selectTime } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/select-volume.mdx b/site/src/content/docs/reference/feature-volume.mdx
similarity index 69%
rename from site/src/content/docs/reference/select-volume.mdx
rename to site/src/content/docs/reference/feature-volume.mdx
index 336dfbbf..c466133e 100644
--- a/site/src/content/docs/reference/select-volume.mdx
+++ b/site/src/content/docs/reference/feature-volume.mdx
@@ -1,12 +1,31 @@
 ---
-title: selectVolume
-description: Select the volume state slice from the player store
+title: Volume
+description: Volume level and mute state for the player store
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
 import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
+Controls volume level and mute state.
+
+## State
+
+| State | Type | Description |
+|---|---|---|
+| `volume` | `number` | Volume level from 0 (silent) to 1 (max) |
+| `muted` | `boolean` | Whether audio is muted |
+| `volumeAvailability` | `MediaFeatureAvailability` | Whether volume can be set on this platform |
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `setVolume(volume)` | Set volume (clamped 0–1). Auto-unmutes when raising above zero. |
+| `toggleMuted()` | Toggle mute. Restores volume to 0.25 when unmuting at zero. |
+
+## Selector
+
 <FrameworkCase frameworks={["react"]}>
 Pass `selectVolume` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe to volume state. Returns `undefined` if the volume feature is not configured.
 </FrameworkCase>
@@ -15,10 +34,8 @@ Pass `selectVolume` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLi
 Pass `selectVolume` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe to volume state. Returns `undefined` if the volume feature is not configured.
 </FrameworkCase>
 
-The returned state includes `volume`, `muted`, and action methods like `setVolume` and `setMuted`.
-
 <FrameworkCase frameworks={["react"]}>
-```tsx
+```tsx title="VolumeSlider.tsx"
 import { selectVolume, usePlayer } from '@videojs/react';
 
 function VolumeSlider() {
@@ -40,7 +57,7 @@ function VolumeSlider() {
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```ts
+```ts title="volume-slider.ts"
 import { createPlayer, MediaElement, selectVolume } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/html-create-player.mdx b/site/src/content/docs/reference/html-create-player.mdx
index 4bda2e32..84d367db 100644
--- a/site/src/content/docs/reference/html-create-player.mdx
+++ b/site/src/content/docs/reference/html-create-player.mdx
@@ -14,7 +14,7 @@ import basicUsageHtmlTs from "@/components/docs/demos/html-create-player/html/cs
 
 `createPlayer` is the entry point for setting up a Video.js player with HTML custom elements. It accepts a configuration object with a `features` array and returns a typed <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink>, `context`, `ProviderMixin`, `ContainerMixin`, and a `create` store factory.
 
-```ts
+```ts title="player.ts"
 import { createPlayer, MediaElement, selectPlayback } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
@@ -36,7 +36,7 @@ class PlayButton extends MediaElement {
 
 Use split elements (recommended for reusable skins/layouts):
 
-```ts
+```ts title="player.ts"
 import { createPlayer, MediaElement } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
@@ -48,7 +48,7 @@ class PlayerRegion extends ContainerMixin(MediaElement) {}
 
 Use a single composed element when the same element should both own the store and attach media:
 
-```ts
+```ts title="player.ts"
 import { createPlayer, MediaElement } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/player-container.mdx b/site/src/content/docs/reference/player-container.mdx
new file mode 100644
index 00000000..a093c5a0
--- /dev/null
+++ b/site/src/content/docs/reference/player-container.mdx
@@ -0,0 +1,208 @@
+---
+title: Player.Container
+frameworkTitle:
+  html: media-container
+description: The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+
+<FrameworkCase frameworks={["react"]}>
+The `Player.Container` is the player's physical surface. It defines the visual boundary, attaches the media element, and detects user interaction like activity and (eventually) gestures and keyboard input. It lives inside a <DocsLink slug="reference/player-provider">`Player.Provider`</DocsLink>.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+The `<media-container>` is the player's physical surface. It defines the visual boundary, attaches the media element, and detects user interaction like activity and (eventually) gestures and keyboard input. It lives inside a <DocsLink slug="reference/player-provider">`<video-player>`</DocsLink>.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <Player.Container> {/* [!code focus] */}
+    <video src="video.mp4" />
+    <Controls />
+  </Player.Container> {/* [!code focus] */}
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <media-container> <!-- [!code focus] -->
+    <video slot="media" src="video.mp4"></video>
+    <media-controls>...</media-controls>
+  </media-container> <!-- [!code focus] -->
+</video-player>
+```
+</FrameworkCase>
+
+## How it's created
+
+<FrameworkCase frameworks={["react"]}>
+The `Player.Container` comes from the same `createPlayer()` call that creates the `Player.Provider`. They're a matched pair wired to the same feature set.
+
+```tsx
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+```
+
+<DocsLinkCard slug="reference/create-player">`createPlayer` reference</DocsLinkCard>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+For most users, importing from `@videojs/html/video/player` registers both `<video-player>` and `<media-container>` with the standard video features:
+
+```ts
+import '@videojs/html/video/player';
+```
+
+```html
+<video-player>
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+For custom behavior, use `ContainerMixin` from `createPlayer()`:
+
+```ts title="my-player.ts"
+import { createPlayer, MediaElement } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class MyContainer extends ContainerMixin(MediaElement) {}
+customElements.define('my-container', MyContainer);
+```
+
+<DocsLinkCard slug="reference/html-create-player">createPlayer reference</DocsLinkCard>
+<DocsLinkCard slug="reference/container-mixin">ContainerMixin reference</DocsLinkCard>
+</FrameworkCase>
+
+## What it does
+
+### Layout & fullscreen
+
+The container is the visual box around your media and controls. Sizing, aspect ratio, and visual boundaries all go here — on the container, not the provider.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Container style={{ width: 640, aspectRatio: '16/9' }}>
+  <video src="video.mp4" />
+  <Controls />
+</Player.Container>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-container style="width: 640px; aspect-ratio: 16/9;">
+  <video slot="media" src="video.mp4"></video>
+  <media-controls>...</media-controls>
+</media-container>
+```
+</FrameworkCase>
+
+When the user goes fullscreen, the **container** goes fullscreen — not the video element. This keeps controls and other UI visible on top of the video, since they're children of the container.
+
+### Media attachment
+
+<FrameworkCase frameworks={["react"]}>
+When a media component like `<Video>` registers itself via context, the container picks it up and attaches it to the store — wiring the media element to all of the player's features.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+The container searches its subtree for a media element — `<video>`, `<audio>`, or a custom media element — and attaches it to the store. You can also use `slot="media"` to explicitly mark which element is the media:
+
+```html
+<media-container>
+  <video slot="media" src="video.mp4"></video>
+</media-container>
+```
+
+This applies even when using a <DocsLink slug="concepts/skins">skin</DocsLink>, since skins contain a container internally.
+</FrameworkCase>
+
+### Interaction surface
+
+The container is where user intent enters the player. It listens for physical interaction on its surface and translates that into player behavior:
+
+- **User activity** — Mouse movement, touch, and keyboard activity within the container drive idle detection. This is how controls know when to show and hide.
+- **Gestures** *(coming soon)* — Click-to-play, double-click fullscreen, swipe to seek, and other touch/mouse gestures.
+- **Keyboard controls** *(coming soon)* — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container.
+
+## Relationship to skins
+
+A <DocsLink slug="concepts/skins">skin</DocsLink> is a container plus UI controls. When you use a packaged skin, the container is built in — you don't need to add one yourself.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+{/* Packaged skin — container is inside VideoSkin */}
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+
+{/* Custom UI — you use Player.Container directly */}
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <PlayButton />
+  </Player.Container>
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<!-- Packaged skin — container is inside video-skin -->
+<video-player>
+  <video-skin>
+    <video slot="media" src="video.mp4"></video>
+  </video-skin>
+</video-player>
+
+<!-- Custom UI — you use media-container directly -->
+<video-player>
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+    <media-play-button></media-play-button>
+  </media-container>
+</video-player>
+```
+</FrameworkCase>
+
+## Inside vs. outside the container
+
+The <DocsLink slug="reference/player-provider">provider</DocsLink> gives components access to state and actions. The container layers on physical behaviors — fullscreen, activity detection, gesture handling. Components work in both places; the container just adds those extras.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <Controls />          {/* fullscreen, activity detection, gestures */}
+  </Player.Container>
+
+  <Transcript />          {/* state & actions, but no container behaviors */}
+  <PlaylistSidebar />     {/* state & actions, but no container behaviors */}
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+    <media-controls>...</media-controls>  <!-- fullscreen, activity detection, gestures -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- state & actions, but no container behaviors -->
+  <playlist-sidebar></playlist-sidebar>     <!-- state & actions, but no container behaviors -->
+</video-player>
+```
+</FrameworkCase>
+
+A play button outside the container still reads playback state and can toggle play/pause — it just won't go fullscreen with the player or respond to the container's idle state.
diff --git a/site/src/content/docs/reference/player-context.mdx b/site/src/content/docs/reference/player-context.mdx
index 031af876..c95cd1e4 100644
--- a/site/src/content/docs/reference/player-context.mdx
+++ b/site/src/content/docs/reference/player-context.mdx
@@ -10,7 +10,7 @@ import DocsLink from "@/components/docs/DocsLink.astro";
 
 Pass it as the second argument to `PlayerController`:
 
-```ts
+```ts title="play-button.ts"
 import { PlayerController, MediaElement, playerContext, selectPlayback } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 
diff --git a/site/src/content/docs/reference/player-provider.mdx b/site/src/content/docs/reference/player-provider.mdx
new file mode 100644
index 00000000..e5330565
--- /dev/null
+++ b/site/src/content/docs/reference/player-provider.mdx
@@ -0,0 +1,204 @@
+---
+title: Player.Provider
+frameworkTitle:
+  html: video-player
+description: The state boundary — creates a store and broadcasts it to all descendants.
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+import DocsLinkCard from '@/components/docs/DocsLinkCard.astro';
+import Aside from '@/components/Aside.astro';
+
+<FrameworkCase frameworks={["react"]}>
+The `Player.Provider` is the state boundary of your player. It creates a store and makes it available to every component inside it via context. Every player needs exactly one.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+The `<video-player>` element is the state boundary of your player. It creates a store and makes it available to every element inside it via context. Every player needs exactly one.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx title="App.tsx"
+import { videoFeatures } from '@videojs/react/video';
+import { createPlayer } from '@videojs/react';
+
+const Player = createPlayer({ features: videoFeatures });
+
+function App() {
+  return (
+    <Player.Provider>
+      {/* Everything inside can access the player store */}
+      <Player.Container>
+        <video src="video.mp4" />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <!-- Everything inside can access the player store -->
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+</FrameworkCase>
+
+## How it's created
+
+<FrameworkCase frameworks={["react"]}>
+Call `createPlayer()` with a `features` array. The returned object contains `Provider`, `Container`, `usePlayer`, and `useMedia` — everything you need for one player instance.
+
+```tsx
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+```
+
+The <DocsLink slug="concepts/features">features</DocsLink> you pass determine what state is available in the store. `videoFeatures` is a <DocsLink slug="concepts/presets">preset</DocsLink> that includes playback, volume, fullscreen, and other standard video controls.
+
+<DocsLinkCard slug="reference/create-player">createPlayer reference</DocsLinkCard>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+For most users, importing from `@videojs/html/video/player` registers a ready-to-use `<video-player>` element with the standard video <DocsLink slug="concepts/features">features</DocsLink> (bundled as a <DocsLink slug="concepts/presets">preset</DocsLink>):
+
+```ts
+import '@videojs/html/video/player';
+```
+
+```html
+<video-player>
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+If you need a custom feature set, a custom tag name, or want to combine provider+container into a single element, use `createPlayer()` to get `ProviderMixin` and compose your own class:
+
+```ts title="my-player.ts"
+import { createPlayer, MediaElement } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ProviderMixin, ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class MyPlayer extends ProviderMixin(MediaElement) {}
+customElements.define('my-player', MyPlayer);
+```
+
+<DocsLinkCard slug="reference/html-create-player">`createPlayer` reference</DocsLinkCard>
+<DocsLinkCard slug="reference/provider-mixin">`ProviderMixin` reference</DocsLinkCard>
+</FrameworkCase>
+
+## What lives inside it
+
+Everything that needs player state goes inside the provider: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <VideoSkin>           {/* skin — includes container + controls */}
+    <Video src="..." /> {/* media element */}
+  </VideoSkin>
+  <MyCustomOverlay />   {/* your own component — can use Player.usePlayer() */}
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <video-skin>               <!-- skin — includes container + controls -->
+    <video slot="media" src="..."></video> <!-- media element -->
+  </video-skin>
+  <my-custom-overlay></my-custom-overlay> <!-- your own element — can use PlayerController -->
+</video-player>
+```
+</FrameworkCase>
+
+## No visual presence
+
+<FrameworkCase frameworks={["react"]}>
+The `Provider` renders no visible element of its own — it's purely a state wrapper. Sizing, borders, and background go on the <DocsLink slug="reference/player-container">`Container`</DocsLink>, not the Provider.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+The `<video-player>` element uses `display: contents`, meaning it has no visual box of its own. Sizing, borders, and background go on the <DocsLink slug="reference/player-container">`<media-container>`</DocsLink>, not the provider.
+</FrameworkCase>
+
+## Accessing state
+
+<FrameworkCase frameworks={["react"]}>
+Use `Player.usePlayer` to read state or call actions from any component inside the Provider:
+
+```tsx title="PlayPauseButton.tsx"
+function PlayPauseButton() {
+  const paused = Player.usePlayer(selectPlayback).paused;
+  const store = Player.usePlayer();
+
+  return (
+    <button onClick={() => store.dispatch('toggle-playback')}>
+      {paused ? 'Play' : 'Pause'}
+    </button>
+  );
+}
+```
+
+<DocsLinkCard slug="reference/use-player">usePlayer reference</DocsLinkCard>
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+Use `PlayerController` to subscribe to store state from any custom element inside the provider:
+
+```ts title="play-pause-button.ts"
+import { selectPlayback } from '@videojs/html';
+
+class PlayPauseButton extends MediaElement {
+  #playback = new PlayerController(this, context, selectPlayback);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', () => {
+      this.#playback.store?.dispatch('toggle-playback');
+    });
+  }
+}
+```
+
+<DocsLinkCard slug="reference/player-controller">PlayerController reference</DocsLinkCard>
+</FrameworkCase>
+
+## Extended player layouts
+
+The provider's scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside the provider but outside the container. They still have full access to the store, they just won't go fullscreen with the video.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <Controls />          {/* goes fullscreen with the video */}
+  </Player.Container>
+
+  <Transcript />          {/* outside container — still has store access */}
+  <PlaylistSidebar />     {/* outside container — still has store access */}
+</Player.Provider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<video-player>
+  <media-container>
+    <video slot="media" src="video.mp4"></video>
+    <media-controls>...</media-controls>  <!-- goes fullscreen with the video -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- outside container — still has store access -->
+  <playlist-sidebar></playlist-sidebar>     <!-- outside container — still has store access -->
+</video-player>
+```
+</FrameworkCase>
diff --git a/site/src/content/docs/reference/render-element.mdx b/site/src/content/docs/reference/render-element.mdx
index d677e1cb..5bab0546 100644
--- a/site/src/content/docs/reference/render-element.mdx
+++ b/site/src/content/docs/reference/render-element.mdx
@@ -14,7 +14,7 @@ import basicUsageReactCss from "@/components/docs/demos/render-element/react/css
 
 `renderElement` renders a UI component element, handling default tag rendering, render props (element or function), props merging, ref composition, and state-driven `className`/`style`.
 
-```tsx
+```tsx title="PlayButton.tsx"
 import { renderElement } from "@videojs/react";
 
 function PlayButton({ className, style, render, ...props }) {
diff --git a/site/src/content/docs/reference/thumbnail.mdx b/site/src/content/docs/reference/thumbnail.mdx
index fd8fa1bf..69f110f9 100644
--- a/site/src/content/docs/reference/thumbnail.mdx
+++ b/site/src/content/docs/reference/thumbnail.mdx
@@ -55,7 +55,7 @@ import jsonSpriteHtmlTs from "@/components/docs/demos/thumbnail/html/css/JsonSpr
 
 <FrameworkCase frameworks={["html"]}>
   ```html
-  <video src="video.mp4">
+  <video slot="media" src="video.mp4">
     <track
       kind="metadata"
       label="thumbnails"
diff --git a/site/src/content/docs/reference/use-media-registration.mdx b/site/src/content/docs/reference/use-media-registration.mdx
index 2a398c15..da49a4b7 100644
--- a/site/src/content/docs/reference/use-media-registration.mdx
+++ b/site/src/content/docs/reference/use-media-registration.mdx
@@ -7,7 +7,7 @@ import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
 
 `useMediaRegistration` returns a setter function for registering a media element with the player context. The built-in `<Video>` and `<Audio>` components use this internally -- you only need it when building a custom media element.
 
-```tsx
+```tsx title="CustomMedia.tsx"
 import { useMediaRegistration } from "@videojs/react";
 import { useRef, useEffect } from "react";
 
diff --git a/site/src/content/docs/reference/use-media.mdx b/site/src/content/docs/reference/use-media.mdx
index 8b91e38d..94c01ee2 100644
--- a/site/src/content/docs/reference/use-media.mdx
+++ b/site/src/content/docs/reference/use-media.mdx
@@ -1,6 +1,6 @@
 ---
-title: useMedia
-description: Hook to access the underlying media element from within a Player Provider
+title: Player.useMedia
+description: Hook to access the underlying media element from within a Player.Provider
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
@@ -12,7 +12,7 @@ import BasicUsageDemoReact from "@/components/docs/demos/use-media/react/css/Bas
 import basicUsageReactTsx from "@/components/docs/demos/use-media/react/css/BasicUsage.tsx?raw";
 import basicUsageReactCss from "@/components/docs/demos/use-media/react/css/BasicUsage.css?raw";
 
-`useMedia` returns the current `HTMLMediaElement` (or `null` if no media element has been registered yet). Use it to interact directly with the native media element when needed. It must be called within a Player `Provider`. The media element becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To register a custom media element instead of the built-in components, see <DocsLink slug="reference/use-media-registration">`useMediaRegistration`</DocsLink>.
+`Player.useMedia` returns the current `HTMLMediaElement` (or `null` if no media element has been registered yet). Use it to interact directly with the native media element when needed. It must be called within a `Player.Provider`. The media element becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. Also available as a standalone import (`import { useMedia } from '@videojs/react'`) — identical behavior, no typing difference. To register a custom media element instead of the built-in components, see <DocsLink slug="reference/use-media-registration">`useMediaRegistration`</DocsLink>.
 
 ## Examples
 
diff --git a/site/src/content/docs/reference/use-player-context.mdx b/site/src/content/docs/reference/use-player-context.mdx
index 278947fd..782e6cb8 100644
--- a/site/src/content/docs/reference/use-player-context.mdx
+++ b/site/src/content/docs/reference/use-player-context.mdx
@@ -8,7 +8,7 @@ import DocsLink from "@/components/docs/DocsLink.astro";
 
 `usePlayerContext` returns the full `PlayerContextValue` object, which includes the store, the current media element, and the media setter.
 
-```tsx
+```tsx title="DebugPanel.tsx"
 import { usePlayerContext } from "@videojs/react";
 
 function DebugPanel() {
diff --git a/site/src/content/docs/reference/use-player.mdx b/site/src/content/docs/reference/use-player.mdx
index caf2f8da..d533f8a7 100644
--- a/site/src/content/docs/reference/use-player.mdx
+++ b/site/src/content/docs/reference/use-player.mdx
@@ -1,6 +1,6 @@
 ---
-title: usePlayer
-description: Hook to access the player store from within a Player Provider
+title: Player.usePlayer
+description: Hook to access the player store from within a Player.Provider
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
@@ -15,13 +15,13 @@ import SelectorDemoReact from "@/components/docs/demos/use-player/react/css/Sele
 import selectorReactTsx from "@/components/docs/demos/use-player/react/css/Selector.tsx?raw";
 import selectorReactCss from "@/components/docs/demos/use-player/react/css/Selector.css?raw";
 
-`usePlayer` gives you access to the player store from any component within a Player `Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. The scoped `usePlayer` returned from <DocsLink slug="reference/create-player">`createPlayer`</DocsLink> is typed to your specific features, while the standalone export from `@videojs/react` returns an untyped store.
+`Player.usePlayer` gives you access to the player store from any component within a `Player.Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. `Player.usePlayer` is typed to the features you passed to <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>. It's also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store.
 
 ## Examples
 
 ### Store Access
 
-Call `usePlayer()` without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.
+Call `Player.usePlayer()` without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.
 
 <FrameworkCase frameworks={["react"]}>
   <StyleCase styles={["css"]}>
diff --git a/site/src/content/docs/reference/use-selector.mdx b/site/src/content/docs/reference/use-selector.mdx
index f24ab6b0..4975898d 100644
--- a/site/src/content/docs/reference/use-selector.mdx
+++ b/site/src/content/docs/reference/use-selector.mdx
@@ -8,7 +8,7 @@ import DocsLink from "@/components/docs/DocsLink.astro";
 
 `useSelector` is a low-level hook that subscribes to an external store using React's `useSyncExternalStore`. It accepts a `subscribe` function, a `getSnapshot` function, a `selector` to derive state, and an optional `isEqual` comparator (defaults to `shallowEqual`).
 
-```tsx
+```tsx title="TimeDisplay.tsx"
 import { useSelector, shallowEqual } from "@videojs/store/react";
 
 function TimeDisplay({ store }) {
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index d8b608b2..f8406774 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -2,7 +2,8 @@ import type { Sidebar } from '@/types/docs';
 
 export const sidebar: Sidebar = [
   {
-    sidebarLabel: 'Getting started',
+    sidebarLabel: 'Site development',
+    devOnly: true,
     contents: [
       {
         slug: 'how-to/write-guides',
@@ -14,18 +15,25 @@ export const sidebar: Sidebar = [
         sidebarLabel: 'Writing references',
         devOnly: true,
       },
+    ],
+  },
+  {
+    sidebarLabel: 'Getting started',
+    contents: [
       { slug: 'how-to/installation' },
+      { slug: 'concepts/overview' },
       { slug: 'concepts/v10-roadmap', sidebarLabel: 'Roadmap' },
     ],
   },
-  // {
-  //   sidebarLabel: 'Concepts',
-  //   contents: [
-  //     { slug: 'concepts/architecture' },
-  //     { slug: 'concepts/skins' },
-  //     { slug: 'concepts/ui-components' }
-  //   ],
-  // },
+  {
+    sidebarLabel: 'Concepts',
+    contents: [
+      { slug: 'concepts/features' },
+      { slug: 'concepts/skins' },
+      { slug: 'concepts/presets' },
+      { slug: 'concepts/ui-components' },
+    ],
+  },
   {
     sidebarLabel: 'How to',
     contents: [{ slug: 'how-to/customize-skins' }],
@@ -33,6 +41,8 @@ export const sidebar: Sidebar = [
   {
     sidebarLabel: 'Components',
     contents: [
+      { slug: 'reference/player-provider' },
+      { slug: 'reference/player-container' },
       // sorted alphabetically
       { slug: 'reference/buffering-indicator' },
       { slug: 'reference/captions-button' },
@@ -79,7 +89,6 @@ export const sidebar: Sidebar = [
     contents: [
       { slug: 'reference/html-create-player', sidebarLabel: 'createPlayer' },
       { slug: 'reference/player-controller' },
-      { slug: 'reference/player-mixin', sidebarLabel: 'PlayerMixin (removed)' },
       {
         sidebarLabel: 'Advanced',
         defaultOpen: false,
@@ -94,18 +103,20 @@ export const sidebar: Sidebar = [
     ],
   },
   {
-    sidebarLabel: 'Selectors',
+    sidebarLabel: 'Features',
     contents: [
       { slug: 'reference/create-selector' },
-      { slug: 'reference/select-buffer' },
-      { slug: 'reference/select-controls' },
-      { slug: 'reference/select-fullscreen' },
-      { slug: 'reference/select-pip', sidebarLabel: 'selectPiP' },
-      { slug: 'reference/select-playback' },
-      { slug: 'reference/select-playback-rate' },
-      { slug: 'reference/select-source' },
-      { slug: 'reference/select-time' },
-      { slug: 'reference/select-volume' },
+      { slug: 'reference/feature-buffer' },
+      { slug: 'reference/feature-controls' },
+      { slug: 'reference/feature-error' },
+      { slug: 'reference/feature-fullscreen' },
+      { slug: 'reference/feature-pip', sidebarLabel: 'Picture-in-picture' },
+      { slug: 'reference/feature-playback' },
+      { slug: 'reference/feature-playback-rate' },
+      { slug: 'reference/feature-source' },
+      { slug: 'reference/feature-text-tracks' },
+      { slug: 'reference/feature-time' },
+      { slug: 'reference/feature-volume' },
     ],
   },
 ];
diff --git a/site/src/layouts/Base.astro b/site/src/layouts/Base.astro
index 01f6de3f..24acca14 100644
--- a/site/src/layouts/Base.astro
+++ b/site/src/layouts/Base.astro
@@ -19,11 +19,12 @@ interface Props {
   twitterImage?: ImageMetadata | string;
   canonical?: string;
   suffix?: string;
+  withCompact?: boolean;
 }
 const { canonical, suffix } = Astro.props;
 const canonicalURL = canonical || new URL(Astro.url.pathname, PRODUCTION_URL);
 
-const { title, description, image, twitterImage } = Astro.props;
+const { title, description, image, twitterImage, withCompact } = Astro.props;
 
 function resolveImageUrl(img: ImageMetadata | string): string {
   if (typeof img === 'string') return img;
@@ -70,13 +71,17 @@ const fullTitle =
     {/* Font preloads */}
     <Font cssVariable="--font-instrument-sans" preload />
     <Font cssVariable="--font-ibm-plex-mono" preload />
-    <link
-      rel="preload"
-      href="https://static.mux.com/fonts/EurostileLTProBold/font.woff2"
-      as="font"
-      type="font/woff2"
-      crossorigin
-    />
+    {
+      withCompact && (
+        <link
+          rel="preload"
+          href="https://static.mux.com/fonts/EurostileLTProBold/font.woff2"
+          as="font"
+          type="font/woff2"
+          crossorigin
+        />
+      )
+    }
     <link
       rel="preload"
       href="https://static.mux.com/fonts/EurostileLTProExtended2/font.woff2"
diff --git a/site/src/layouts/ErrorPage.astro b/site/src/layouts/ErrorPage.astro
index ecdb99d0..39bc6fff 100644
--- a/site/src/layouts/ErrorPage.astro
+++ b/site/src/layouts/ErrorPage.astro
@@ -16,7 +16,7 @@ interface Props {
 const { title, description, code = '404', message = 'NOT FOUND' } = Astro.props;
 ---
 
-<Base {title} {description}>
+<Base {title} {description} withCompact>
   <div class="flex flex-col" style={{ minHeight: "80dvh" }}>
     <NavBar />
     <main class="w-full">
diff --git a/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts b/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts
index 3516b0e6..72852ace 100644
--- a/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts
+++ b/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts
@@ -34,7 +34,7 @@ describe('renderInlineMarkdown', () => {
 
   it('renders emphasized text', () => {
     const result = renderInlineMarkdown('*italic text*');
-    expect(result).toContain('<em class="font-bold">italic text</em>');
+    expect(result).toContain('<em class="italic">italic text</em>');
   });
 
   it('renders links with correct classes', () => {