diff --git a/.changeset/youtube-provider.md b/.changeset/youtube-provider.md
new file mode 100644
index 0000000..39cba8b
--- /dev/null
+++ b/.changeset/youtube-provider.md
@@ -0,0 +1,17 @@
+---
+"@karnstack/kino": minor
+---
+
+feat: YouTube provider. A new `@karnstack/kino/youtube` entry puts the same kino
+glass chrome over the YouTube IFrame Player API. `<YouTubePlayer videoId="…" />`
+accepts a bare id or any watch / youtu.be / embed / shorts URL (resolved via the
+exported `parseYouTubeId` helper).
+
+Play/pause, seek, speed, fullscreen, volume, and a captions menu (driven by the
+video's own subtitle tracks, rendered by YouTube inside the embed) all work
+through kino's controls. The provider follows YouTube's API terms — it plays
+through the official IFrame API and doesn't obscure the player, so YouTube's own
+thumbnail, play button, title, and logo show before playback and while paused.
+Quality, picture-in-picture, and scrub-preview storyboards are hidden because
+the IFrame API doesn't expose them. No runtime dependency — the API is loaded on
+demand.
diff --git a/README.md b/README.md
index 5e54d27..d728160 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 <p align="center">
   A themeable React video player with a pluggable-provider architecture —
   translucent glass chrome, keyboard-first controls, and a small typed surface.
-  Mux is the first provider.
+  Mux, raw files, and YouTube are built in.
 </p>
 
 <p align="center">
@@ -24,7 +24,7 @@
 
 > **[Try it live → kino.karnstack.com](https://kino.karnstack.com)** — drop in any public Mux playback ID, pick an accent, and play with the real glass UI.
 
-kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. The Mux provider is built on the `@mux/mux-video` custom element.
+kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. Three providers ship today: **Mux** (adaptive HLS via `@mux/mux-video`), **Native** (a plain `<video>` over any raw file URL), and **YouTube** (the IFrame Player API wrapped in the same chrome). Each lives behind its own entry point, so you only pull in the engine you use.
 
 ## Install
 
@@ -106,6 +106,32 @@ Pass sidecar subtitles/captions via `tracks`, and kino renders the cues in its o
 
 `NativePlayer` also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `crossOrigin` (set the last when the media or a caption track is cross-origin). Quality switching hides itself since a raw file carries no rendition ladder.
 
+## Playing a YouTube video
+
+For a YouTube source, use the YouTube provider. It drives the YouTube IFrame Player API under the same glass chrome, with kino owning the controls and keyboard map (the native YouTube UI is hidden).
+
+```tsx
+import { YouTubePlayer } from "@karnstack/kino/youtube"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <YouTubePlayer
+        videoId="dQw4w9WgXcQ"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+`videoId` accepts a bare id or any `watch`, `youtu.be`, `embed`, or `shorts` URL — kino resolves it (the `parseYouTubeId` helper is exported if you want it directly). It also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `metadata`.
+
+Speed, fullscreen, and captions work. The captions menu lists the video's own subtitle tracks; YouTube renders the cues itself inside the embed, so they appear in YouTube's style rather than kino's caption overlay.
+
+kino plays YouTube through the official IFrame Player API and, per YouTube's terms, **doesn't obscure the player**: before playback and while paused, YouTube shows its own thumbnail, play button, title, and logo, and kino's controls sit alongside them. A few things the API simply doesn't expose, so kino hides those controls: **manual quality** (YouTube dropped it — playback is always automatic), **picture-in-picture**, and **scrub-preview thumbnails** (storyboards aren't available to embeds).
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -175,7 +201,7 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: YouTube and Vimeo
+- More providers: Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome
diff --git a/demo/pages/install.tsx b/demo/pages/install.tsx
index 08ea8fc..cf002d8 100644
--- a/demo/pages/install.tsx
+++ b/demo/pages/install.tsx
@@ -35,6 +35,17 @@ export function Clip() {
   )
 }`
 
+const YOUTUBE_SNIPPET = `import { YouTubePlayer } from "@karnstack/kino/youtube"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <YouTubePlayer videoId="dQw4w9WgXcQ" />
+    </div>
+  )
+}`
+
 type Prop = [string, string, string]
 
 const SHARED_PROPS: Prop[] = [
@@ -87,6 +98,24 @@ const NATIVE_PROPS: Prop[] = [
   ...SHARED_PROPS,
 ]
 
+const YOUTUBE_PROPS: Prop[] = [
+  [
+    "videoId",
+    "string",
+    "Video id or watch / youtu.be / embed / shorts URL. Required.",
+  ],
+  ["autoPlay", "boolean", "Start playback on mount."],
+  ["muted", "boolean", "Start muted."],
+  ["loop", "boolean", "Loop playback."],
+  ["defaultRate", "number", "Initial playback rate."],
+  [
+    "metadata",
+    "{ videoId?, videoTitle?, viewerUserId? }",
+    "OS media-session metadata.",
+  ],
+  ...SHARED_PROPS,
+]
+
 const propRows = (props: Prop[]) =>
   props.map(([name, type, desc]) => ({
     key: name,
@@ -99,7 +128,7 @@ export function InstallPage() {
       <PageHeader
         eyebrow="Install"
         title="Up and running."
-        lead="kino is a single package with per-provider entry points. React 19 is a peer dependency; the Mux engine is pulled in transitively, and the file provider needs nothing extra."
+        lead="kino is a single package with per-provider entry points. React 19 is a peer dependency; the Mux engine is pulled in transitively, while the native and YouTube providers need nothing extra — YouTube loads the IFrame API at runtime."
       />
 
       <section className="flex flex-col gap-6">
@@ -129,6 +158,10 @@ export function InstallPage() {
             <h3 className="text-lg font-medium text-paper">Native</h3>
             <CodeBlock code={NATIVE_SNIPPET} label="native.tsx" />
           </div>
+          <div className="flex flex-col gap-3">
+            <h3 className="text-lg font-medium text-paper">YouTube</h3>
+            <CodeBlock code={YOUTUBE_SNIPPET} label="youtube.tsx" />
+          </div>
         </div>
       </section>
 
@@ -157,6 +190,15 @@ export function InstallPage() {
             rows={propRows(NATIVE_PROPS)}
           />
         </div>
+        <div className="flex flex-col gap-4">
+          <h3 className="font-mono text-sm tracking-wide text-paper-faint uppercase">
+            YouTubePlayer
+          </h3>
+          <Table
+            head={["Prop", "Type", "Description"]}
+            rows={propRows(YOUTUBE_PROPS)}
+          />
+        </div>
       </section>
     </div>
   )
diff --git a/demo/pages/overview.tsx b/demo/pages/overview.tsx
index be3c7b7..21ed22c 100644
--- a/demo/pages/overview.tsx
+++ b/demo/pages/overview.tsx
@@ -16,7 +16,7 @@ const HIGHLIGHTS = [
     n: "01",
     term: "Pluggable providers",
     detail:
-      "One UI contract, many engines. Mux HLS and raw files ship today; YouTube and Vimeo are next.",
+      "One UI contract, many engines. Mux HLS, raw files, and YouTube ship today; Vimeo is next.",
   },
   {
     n: "02",
@@ -50,7 +50,7 @@ export function OverviewPage() {
           <p className="mt-6 max-w-[56ch] text-lg/8 text-pretty text-paper-dim">
             kino is a themeable React video player with a pluggable-provider
             architecture. The same translucent, keyboard-first UI sits over Mux,
-            raw files, and more — behind a small typed surface.
+            raw files, and YouTube — behind a small typed surface.
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-3">
diff --git a/demo/pages/providers.tsx b/demo/pages/providers.tsx
index e95aece..556bb46 100644
--- a/demo/pages/providers.tsx
+++ b/demo/pages/providers.tsx
@@ -27,9 +27,11 @@ const PROVIDERS: ProviderCard[] = [
   },
   {
     name: "YouTube",
-    status: "planned",
+    status: "shipped",
+    entry: "@karnstack/kino/youtube",
     detail:
-      "Embed-backed playback wrapped in the same kino chrome, so a YouTube source feels native to the player.",
+      "The YouTube IFrame Player API wrapped in the same kino chrome — kino owns the controls, keyboard map, and captions menu. Quality and PiP follow YouTube's API limits.",
+    importLine: 'import { YouTubePlayer } from "@karnstack/kino/youtube"',
   },
   {
     name: "Vimeo",
diff --git a/demo/player-studio.tsx b/demo/player-studio.tsx
index 305cd77..97572a8 100644
--- a/demo/player-studio.tsx
+++ b/demo/player-studio.tsx
@@ -1,10 +1,11 @@
 import { useState, type CSSProperties } from "react"
 import { MuxPlayer } from "../src/mux/mux-player"
 import { NativePlayer } from "../src/native/native-player"
+import { YouTubePlayer } from "../src/youtube/youtube-player"
 import { CheckIcon } from "./icons"
 import { TouchTarget } from "./ui"
 
-export type Mode = "mux" | "native"
+export type Mode = "mux" | "native" | "youtube"
 
 // Public sample assets so the studio plays real media with no account or signed
 // tokens — anyone who clones the repo gets the full UI.
@@ -18,6 +19,13 @@ const NATIVE_SAMPLE = {
   label: "accrobra · mp4",
 } as const
 
+// A public, embeddable Creative Commons video so the YouTube tab plays for
+// anyone who clones the repo.
+const YOUTUBE_SAMPLE = {
+  id: "aqz-KE-bpKQ",
+  label: "Big Buck Bunny · YouTube",
+} as const
+
 export const DEFAULT_ACCENT = "#f4b942"
 const ACCENTS = [
   { name: "Leader", value: DEFAULT_ACCENT },
@@ -48,8 +56,18 @@ export function PlayerStudio({
   const [radius, setRadius] = useState(DEFAULT_RADIUS)
 
   const activeSample = SAMPLES.find((s) => s.id === source)
-  const label = mode === "native" ? NATIVE_SAMPLE.label : activeSample?.label
-  const code = mode === "native" ? NATIVE_SAMPLE.src : source
+  const label =
+    mode === "native"
+      ? NATIVE_SAMPLE.label
+      : mode === "youtube"
+        ? YOUTUBE_SAMPLE.label
+        : activeSample?.label
+  const code =
+    mode === "native"
+      ? NATIVE_SAMPLE.src
+      : mode === "youtube"
+        ? YOUTUBE_SAMPLE.id
+        : source
 
   return (
     <div className="flex flex-col gap-5">
@@ -71,6 +89,13 @@ export function PlayerStudio({
               accentColor={accent}
               theme={{ "--kino-radius": `${radius}px` }}
             />
+          ) : mode === "youtube" ? (
+            <YouTubePlayer
+              key="youtube"
+              videoId={YOUTUBE_SAMPLE.id}
+              accentColor={accent}
+              theme={{ "--kino-radius": `${radius}px` }}
+            />
           ) : (
             <MuxPlayer
               key="mux"
@@ -105,6 +130,7 @@ export function PlayerStudio({
               [
                 { id: "mux", label: "Mux · HLS" },
                 { id: "native", label: "Native · mp4" },
+                { id: "youtube", label: "YouTube · Embed" },
               ] as const
             ).map((p) => {
               const active = mode === p.id
diff --git a/docs/superpowers/specs/2026-06-28-youtube-provider-design.md b/docs/superpowers/specs/2026-06-28-youtube-provider-design.md
new file mode 100644
index 0000000..43a53d0
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-28-youtube-provider-design.md
@@ -0,0 +1,153 @@
+# YouTube provider — design
+
+## Goal
+
+Add a YouTube provider to kino so the same glass chrome plays YouTube videos,
+mirroring the existing `mux/` and `native/` providers. Then update the README,
+demo site, and overview copy so the docs advertise **three** shipped providers
+(Mux, Native, YouTube) instead of framing Mux as the only/first one.
+
+## Architecture
+
+kino's contract is `Provider` (`src/core/types.ts`): `mount(container)`,
+`getState()`, `subscribe(listener)`, `actions`, `destroy()`, optional
+`swapSource(opts)`. A thin React wrapper creates the provider once
+(`useRef`) and routes reactive prop changes through `swapSource`. UI controls
+gate themselves on the `capabilities` set the provider reports.
+
+The YouTube provider follows the `native/` shape exactly.
+
+### New files
+
+- `src/youtube/provider.ts` — `createYouTubeProvider(opts): Provider` +
+  `YouTubeProviderOptions` type + `parseYouTubeId(input): string` helper.
+- `src/youtube/youtube-player.tsx` — `<YouTubePlayer>` (props =
+  `YouTubeProviderOptions` + `accentColor/theme/className/placeholder/children`).
+- `src/youtube/provider.test.ts` — vitest, mirroring `native/provider.test.ts`.
+- `src/youtube.ts` — entry re-exporting the provider, component, types, helper.
+
+### Wiring
+
+- `package.json` → add `exports["./youtube"]`.
+- `tsdown.config.ts` → add `youtube: "src/youtube.ts"` entry.
+- `package.json` `devDependencies` → `@types/youtube` (global `YT` typings only;
+  no runtime dependency — the IFrame API script is loaded at runtime).
+- `src/styles/kino.css` → add `.kino iframe` to the existing
+  `.kino mux-video, .kino video { inset:0; width/height:100% }` rule.
+
+## Engine integration
+
+YouTube IFrame Player API. A module-level singleton promise lazy-loads
+`https://www.youtube.com/iframe_api` and resolves when `window.YT.Player` is
+ready (chaining the existing global `onYouTubeIframeAPIReady` callback so
+multiple players coexist). Already-loaded `window.YT` short-circuits.
+
+`mount(container)` appends a host `<div>` and, once the API resolves, constructs
+`new YT.Player(hostDiv, { videoId, playerVars: { controls: 0, playsinline: 1,
+rel: 0, modestbranding: 1, autoplay, mute, loop, playlist }, events })`. The API
+replaces the div with an `<iframe>`. The kino gesture overlay sits above the
+iframe and owns clicks/keys (`controls: 0` hides YouTube's own chrome).
+
+Because mount is synchronous but player creation is async, the provider tracks a
+`destroyed` flag: if `destroy()` runs before the player is ready, the player is
+torn down as soon as it resolves.
+
+### Hand-rolled vs typed
+
+`@types/youtube` supplies the global `YT` namespace types (devDependency).
+Provider internals reference `YT.Player` through a narrow local alias so the
+file stays self-contained, matching the `MuxVideoEl` structural-type style.
+
+## State mapping
+
+YT fires no `timeupdate`. A ~250ms ticker (`setInterval`) runs while a player
+exists and pushes `currentTime`, `duration`, and `buffered`. `onStateChange`
+drives play/pause/ended transitions immediately.
+
+| MediaState                          | Source                                                           |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| `paused`                            | state `PLAYING(1)` → false; `PAUSED/ENDED/CUED/UNSTARTED` → true |
+| `ended`                             | state `ENDED(0)`                                                 |
+| `currentTime`                       | `getCurrentTime()`                                               |
+| `duration`                          | `getDuration()`                                                  |
+| `buffered`                          | `[[0, getVideoLoadedFraction() * duration]]`                     |
+| `rate`                              | `getPlaybackRate()` (re-asserted as `desiredRate`)               |
+| `volume`                            | `getVolume() / 100`                                              |
+| `muted`                             | `isMuted()`                                                      |
+| `error`                             | `onError(code)` → `{ code, message }`                            |
+| `readyState`                        | 4 once a video is cued/playing, else 0                           |
+| qualities / textTracks / storyboard | empty / null                                                     |
+
+## Capabilities
+
+| Capability      | Value | Reason                                                   |
+| --------------- | ----- | -------------------------------------------------------- |
+| `canSetRate`    | true  | `setPlaybackRate` works.                                 |
+| `canFullscreen` | true  | We fullscreen the kino wrapper; the iframe is inside it. |
+| `canSetQuality` | false | IFrame API removed manual quality selection.             |
+| `canPiP`        | false | No PiP handle on a cross-origin iframe.                  |
+| `hasTextTracks` | false | Caption control over the iframe API is unofficial.       |
+| `hasStoryboard` | false | No scrub-preview source.                                 |
+
+Gated controls (quality menu, PiP button, captions menu, storyboard preview)
+hide themselves automatically — no dead buttons.
+
+## Actions
+
+| Action               | Implementation                                          |
+| -------------------- | ------------------------------------------------------- |
+| `play / pause`       | `playVideo() / pauseVideo()`                            |
+| `seek(t)`            | `seekTo(t, true)`                                       |
+| `setRate(r)`         | `setPlaybackRate(r)`; store `desiredRate`; patch `rate` |
+| `setVolume(v)`       | `setVolume(v * 100)`                                    |
+| `setMuted(m)`        | `mute() / unMute()`                                     |
+| `setQuality`         | no-op                                                   |
+| `setTextTrack`       | no-op                                                   |
+| `enterFullscreen`    | `wrapper.requestFullscreen()` (same as native)          |
+| `exitFullscreen`     | `document.exitFullscreen()`                             |
+| `enterPiP / exitPiP` | no-op                                                   |
+
+## Options
+
+```ts
+type YouTubeProviderOptions = {
+  videoId: string // a raw id; parseYouTubeId() accepts a URL too
+  metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }
+  autoPlay?: boolean
+  muted?: boolean
+  loop?: boolean
+  defaultRate?: number
+}
+```
+
+`parseYouTubeId(input)` accepts a bare id, `watch?v=`, `youtu.be/`, `/embed/`,
+and `/shorts/` URLs, returning the 11-char id (input returned unchanged if no
+match, so a bare id passes through).
+
+`swapSource` reacts to `videoId` (→ `loadVideoById` / `cueVideoById` per
+`autoPlay`) and `metadata.videoTitle` (→ media-session title). Like the other
+providers, `muted/loop/defaultRate/autoPlay` are read once at creation.
+
+## Testing
+
+Mirror `native/provider.test.ts`, mocking `window.YT` with a fake `Player` that
+records method calls (jsdom has no IFrame API). Cover: initial state defaults;
+capability set; `parseYouTubeId` across URL forms; actions call the right YT
+methods; `setRate` reflects immediately and survives a swap; `swapSource` calls
+`loadVideoById` and resets progress; `destroy` tears down the player and ticker.
+
+## Docs / demo updates
+
+- **README.md** — replace "Mux is the first provider" framing with three shipped
+  providers; add a "Playing a YouTube video" section; update the roadmap (drop
+  YouTube from "planned").
+- **demo/pages/providers.tsx** — YouTube card `planned` → `shipped` with entry +
+  import line.
+- **demo/pages/install.tsx** — YouTube snippet + `YouTubePlayer` props table.
+- **demo/pages/overview.tsx** — highlight copy: YouTube now ships.
+- **demo/player-studio.tsx** — add a "YouTube" provider tab playing a public id.
+- **.changeset/** — a `minor` changeset describing the new provider.
+
+## Out of scope
+
+Vimeo, AirPlay, chapters, YouTube captions/quality control (API limits).
diff --git a/package.json b/package.json
index b9b5506..56cba58 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
     "player",
     "react",
     "mux",
+    "youtube",
     "hls",
     "video-player"
   ],
@@ -45,6 +46,10 @@
       "types": "./dist/native.d.ts",
       "import": "./dist/native.js"
     },
+    "./youtube": {
+      "types": "./dist/youtube.d.ts",
+      "import": "./dist/youtube.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "scripts": {
diff --git a/src/styles/kino.css b/src/styles/kino.css
index 33c2705..d41a51e 100644
--- a/src/styles/kino.css
+++ b/src/styles/kino.css
@@ -28,11 +28,21 @@
   box-sizing: border-box;
 }
 .kino mux-video,
-.kino video {
+.kino video,
+/* The YouTube provider mounts an <iframe> here; size it like the video. */
+.kino .kino-video-host iframe {
   position: absolute;
   inset: 0;
   width: 100%;
   height: 100%;
+  border: 0;
+}
+/* Let kino's gesture layer own every pointer interaction. Without this the
+   YouTube iframe surfaces its own hover chrome — title, "More videos", a second
+   progress bar — on top of kino's controls. Killing pointer events on the
+   iframe stops YouTube from ever seeing a hover, so only kino's UI shows. */
+.kino .kino-video-host iframe {
+  pointer-events: none;
 }
 .kino .kino-placeholder {
   position: absolute;
diff --git a/src/youtube.ts b/src/youtube.ts
new file mode 100644
index 0000000..53c4ce2
--- /dev/null
+++ b/src/youtube.ts
@@ -0,0 +1,9 @@
+export {
+  createYouTubeProvider,
+  parseYouTubeId,
+  type YouTubeProviderOptions,
+} from "./youtube/provider"
+export {
+  YouTubePlayer,
+  type YouTubePlayerProps,
+} from "./youtube/youtube-player"
diff --git a/src/youtube/provider.test.ts b/src/youtube/provider.test.ts
new file mode 100644
index 0000000..8749c26
--- /dev/null
+++ b/src/youtube/provider.test.ts
@@ -0,0 +1,407 @@
+import { afterEach, beforeEach, expect, test, vi } from "vitest"
+import { createYouTubeProvider, parseYouTubeId } from "./provider"
+
+// YT.PlayerState numeric codes (mirrors the real IFrame API).
+const PS = {
+  UNSTARTED: -1,
+  ENDED: 0,
+  PLAYING: 1,
+  PAUSED: 2,
+  BUFFERING: 3,
+  CUED: 5,
+}
+
+// A faithful stand-in for YT.Player: jsdom has no IFrame API, so we record the
+// methods the provider calls and fire the events the real player would.
+class FakePlayer {
+  static instances: FakePlayer[] = []
+  // When true, the player is constructed but onReady is withheld until
+  // fireReady() — mirrors the real API, where methods only work post-ready.
+  static deferReady = false
+  opts: {
+    videoId: string
+    playerVars?: Record<string, unknown>
+    events?: Record<string, (e: unknown) => void>
+  }
+  destroyed = false
+  rate = 1
+  vol = 100
+  private _muted = false
+  current = 0
+  dur = 100
+  loaded = 0.5
+  state = PS.CUED
+  polls = 0 // counts the polling getter, so a test can prove no early polling
+  tracklist: Array<{ languageCode: string; displayName: string }> = [
+    { languageCode: "en", displayName: "English" },
+    { languageCode: "es", displayName: "Spanish" },
+  ]
+  modules: string[] = []
+  lastOption: { module: string; option: string; value: unknown } | null = null
+  loadVideoById = vi.fn((id: string) => {
+    this.opts.videoId = id
+    this.rate = 1 // a load resets the element's playback rate to 1x
+    this.fire(PS.PLAYING)
+  })
+
+  constructor(
+    el: HTMLElement,
+    opts: FakePlayer["opts"] & {
+      events?: Record<string, (e: unknown) => void>
+    },
+  ) {
+    this.opts = opts
+    FakePlayer.instances.push(this)
+    // The real API replaces the passed element with an <iframe>.
+    const iframe = document.createElement("iframe")
+    el.replaceWith(iframe)
+    // onReady fires once the player is constructed (deferred when asked).
+    if (!FakePlayer.deferReady) this.fireReady()
+  }
+  fireReady() {
+    this.opts.events?.onReady?.({ target: this })
+  }
+  private fire(state: number) {
+    this.state = state
+    this.opts.events?.onStateChange?.({ target: this, data: state })
+  }
+  playVideo() {
+    this.fire(PS.PLAYING)
+  }
+  pauseVideo() {
+    this.fire(PS.PAUSED)
+  }
+  buffer() {
+    this.fire(PS.BUFFERING)
+  }
+  seekTo(t: number) {
+    this.current = t
+  }
+  getCurrentTime() {
+    this.polls++
+    return this.current
+  }
+  getDuration() {
+    return this.dur
+  }
+  getVideoLoadedFraction() {
+    return this.loaded
+  }
+  setPlaybackRate(r: number) {
+    this.rate = r
+  }
+  getPlaybackRate() {
+    return this.rate
+  }
+  setVolume(v: number) {
+    this.vol = v
+  }
+  getVolume() {
+    return this.vol
+  }
+  mute() {
+    this._muted = true
+  }
+  unMute() {
+    this._muted = false
+  }
+  isMuted() {
+    return this._muted
+  }
+  getPlayerState() {
+    return this.state
+  }
+  loadModule(m: string) {
+    this.modules.push(m)
+  }
+  unloadModule() {}
+  getOption(_module: string, option: string) {
+    return option === "tracklist" ? this.tracklist : undefined
+  }
+  setOption(module: string, option: string, value: unknown) {
+    this.lastOption = { module, option, value }
+  }
+  destroy() {
+    this.destroyed = true
+  }
+}
+
+beforeEach(() => {
+  FakePlayer.instances = []
+  FakePlayer.deferReady = false
+  ;(window as unknown as { YT: unknown }).YT = {
+    Player: FakePlayer,
+    PlayerState: PS,
+  }
+})
+
+afterEach(() => {
+  delete (window as unknown as { YT?: unknown }).YT
+})
+
+function mount(provider: ReturnType<typeof createYouTubeProvider>) {
+  const host = document.createElement("div")
+  document.body.appendChild(host)
+  provider.mount(host)
+  const player = FakePlayer.instances.at(-1)!
+  return { host, player }
+}
+
+test("parseYouTubeId extracts the id from every common URL form", () => {
+  expect(parseYouTubeId("dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ")
+  expect(parseYouTubeId("https://www.youtube.com/watch?v=dQw4w9WgXcQ")).toBe(
+    "dQw4w9WgXcQ",
+  )
+  expect(
+    parseYouTubeId("https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=42s"),
+  ).toBe("dQw4w9WgXcQ")
+  expect(parseYouTubeId("https://youtu.be/dQw4w9WgXcQ?si=abc")).toBe(
+    "dQw4w9WgXcQ",
+  )
+  expect(parseYouTubeId("https://www.youtube.com/embed/dQw4w9WgXcQ")).toBe(
+    "dQw4w9WgXcQ",
+  )
+  expect(parseYouTubeId("https://www.youtube.com/shorts/dQw4w9WgXcQ")).toBe(
+    "dQw4w9WgXcQ",
+  )
+})
+
+test("initial state defaults paused with auto quality and the given rate", () => {
+  const p = createYouTubeProvider({ videoId: "abc", defaultRate: 1.5 })
+  const s = p.getState()
+  expect(s.paused).toBe(true)
+  expect(s.activeQualityId).toBe("auto")
+  expect(s.rate).toBe(1.5)
+  p.destroy()
+})
+
+test("capabilities: rate + fullscreen only; no quality, pip, captions, storyboard", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const caps = p.getState().capabilities
+  expect(caps.canSetRate).toBe(true)
+  expect(caps.canFullscreen).toBe(true)
+  expect(caps.canSetQuality).toBe(false)
+  expect(caps.canPiP).toBe(false)
+  expect(caps.hasTextTracks).toBe(false)
+  expect(caps.hasStoryboard).toBe(false)
+  p.destroy()
+})
+
+test("mount creates a YT.Player with the video id and custom-chrome player vars", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  expect(player.opts.videoId).toBe("abc")
+  expect(player.opts.playerVars?.controls).toBe(0)
+  expect(player.opts.playerVars?.playsinline).toBe(1)
+  p.destroy()
+})
+
+test("mount accepts a full URL and resolves it to the id", () => {
+  const p = createYouTubeProvider({
+    videoId: "https://youtu.be/dQw4w9WgXcQ",
+  })
+  const { player } = mount(p)
+  expect(player.opts.videoId).toBe("dQw4w9WgXcQ")
+  p.destroy()
+})
+
+test("play and pause flip paused via the player's state-change events", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  mount(p)
+  p.actions.play()
+  expect(p.getState().paused).toBe(false)
+  p.actions.pause()
+  expect(p.getState().paused).toBe(true)
+  p.destroy()
+})
+
+test("buffering mid-playback is not reported as paused", () => {
+  // A stall would otherwise read as paused and flash the poster cover.
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.play()
+  expect(p.getState().paused).toBe(false)
+  player.buffer()
+  expect(p.getState().paused).toBe(false)
+  p.destroy()
+})
+
+test("seek forwards to the player's seekTo", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.seek(30)
+  expect(player.getCurrentTime()).toBe(30)
+  p.destroy()
+})
+
+test("setRate reflects immediately and calls the player", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.setRate(2)
+  expect(p.getState().rate).toBe(2)
+  expect(player.getPlaybackRate()).toBe(2)
+  p.destroy()
+})
+
+test("setVolume maps 0..1 to the player's 0..100 scale", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.setVolume(0.5)
+  expect(player.getVolume()).toBe(50)
+  p.destroy()
+})
+
+test("setMuted toggles the player and reflects in state", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.setMuted(true)
+  expect(player.isMuted()).toBe(true)
+  p.actions.setMuted(false)
+  expect(player.isMuted()).toBe(false)
+  p.destroy()
+})
+
+test("setQuality is a no-op (stays auto)", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  mount(p)
+  p.actions.setQuality("anything")
+  expect(p.getState().activeQualityId).toBe("auto")
+  p.destroy()
+})
+
+test("playback rate survives a source swap", () => {
+  const p = createYouTubeProvider({ videoId: "first" })
+  const { player } = mount(p)
+  p.actions.setRate(2)
+  // YouTube carries the next video id through SourceOptions.src.
+  p.swapSource?.({ src: "second" })
+  expect(player.getPlaybackRate()).toBe(2)
+  expect(p.getState().rate).toBe(2)
+  p.destroy()
+})
+
+test("swapSource loads the new video and resets progress", () => {
+  const p = createYouTubeProvider({ videoId: "first" })
+  const { player } = mount(p)
+  player.current = 42
+  p.swapSource?.({ src: "second" })
+  expect(player.loadVideoById).toHaveBeenCalledWith("second")
+  const s = p.getState()
+  expect(s.currentTime).toBe(0)
+  expect(s.duration).toBe(0)
+  expect(s.ended).toBe(false)
+  expect(s.error).toBeNull()
+  p.destroy()
+})
+
+test("discovers caption tracks from the captions module", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  mount(p)
+  const s = p.getState()
+  expect(s.capabilities.hasTextTracks).toBe(true)
+  expect(s.textTracks.map((t) => t.label)).toEqual(["English", "Spanish"])
+  expect(s.textTracks.map((t) => t.id)).toEqual(["en", "es"])
+  p.destroy()
+})
+
+test("loads the captions module once the player is ready", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  expect(player.modules).toContain("captions")
+  p.destroy()
+})
+
+test("setTextTrack enables the chosen language via the captions module", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.setTextTrack("es")
+  expect(p.getState().activeTextTrackId).toBe("es")
+  expect(player.lastOption).toEqual({
+    module: "captions",
+    option: "track",
+    value: { languageCode: "es" },
+  })
+  p.destroy()
+})
+
+test("setTextTrack(null) turns captions off", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.actions.setTextTrack("en")
+  p.actions.setTextTrack(null)
+  expect(p.getState().activeTextTrackId).toBeNull()
+  expect(player.lastOption).toEqual({
+    module: "captions",
+    option: "track",
+    value: {},
+  })
+  p.destroy()
+})
+
+test("does not poll the player until it is ready", () => {
+  // The IFrame API attaches its methods only after onReady fires; a ticker that
+  // polls before then throws "getPlaybackRate is not a function". The provider
+  // must not touch the player until ready.
+  vi.useFakeTimers()
+  try {
+    FakePlayer.deferReady = true
+    const p = createYouTubeProvider({ videoId: "abc" })
+    const host = document.createElement("div")
+    document.body.appendChild(host)
+    p.mount(host)
+    const player = FakePlayer.instances.at(-1)!
+    vi.advanceTimersByTime(1000)
+    expect(player.polls).toBe(0) // no polling before ready
+    player.fireReady()
+    vi.advanceTimersByTime(1000)
+    expect(player.polls).toBeGreaterThan(0) // polling once ready
+    p.destroy()
+  } finally {
+    vi.useRealTimers()
+  }
+})
+
+test("subscribe is notified on state change", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  mount(p)
+  let calls = 0
+  const off = p.subscribe(() => calls++)
+  p.actions.setRate(0.5)
+  expect(calls).toBeGreaterThan(0)
+  off()
+  p.destroy()
+})
+
+test("destroy tears down the player", () => {
+  const p = createYouTubeProvider({ videoId: "abc" })
+  const { player } = mount(p)
+  p.destroy()
+  expect(player.destroyed).toBe(true)
+})
+
+test("destroy before the player is ready tears it down once it loads", async () => {
+  // No window.YT yet: the provider must wait for the API and then honor an
+  // early destroy by tearing the player down as soon as it resolves.
+  delete (window as unknown as { YT?: unknown }).YT
+  vi.resetModules()
+  const mod = await import("./provider")
+  const host = document.createElement("div")
+  document.body.appendChild(host)
+  const p = mod.createYouTubeProvider({ videoId: "abc" })
+  p.mount(host)
+  // A script tag for the IFrame API should have been injected.
+  const script = document.querySelector('script[src*="youtube.com/iframe_api"]')
+  expect(script).toBeTruthy()
+  p.destroy()
+  // Now the API "arrives": the provider must not leave a live player behind.
+  ;(window as unknown as { YT: unknown }).YT = {
+    Player: FakePlayer,
+    PlayerState: PS,
+  }
+  ;(
+    window as unknown as { onYouTubeIframeAPIReady?: () => void }
+  ).onYouTubeIframeAPIReady?.()
+  await Promise.resolve()
+  const created = FakePlayer.instances.at(-1)
+  if (created) expect(created.destroyed).toBe(true)
+})
diff --git a/src/youtube/provider.ts b/src/youtube/provider.ts
new file mode 100644
index 0000000..78f3f06
--- /dev/null
+++ b/src/youtube/provider.ts
@@ -0,0 +1,391 @@
+import { defaultState } from "../core/fake-provider"
+import type {
+  MediaState,
+  Provider,
+  PlayerActions,
+  SourceOptions,
+  TextTrackInfo,
+} from "../core/types"
+
+// Minimal structural types for the bits of the YouTube IFrame Player API we
+// touch. Hand-rolled (like mux's MuxVideoEl) so the provider needs no runtime
+// dependency and no global typings package — the API is loaded at runtime.
+type YTCaptionTrack = { languageCode: string; displayName?: string }
+type YTPlayer = {
+  playVideo(): void
+  pauseVideo(): void
+  seekTo(seconds: number, allowSeekAhead: boolean): void
+  loadVideoById(id: string): void
+  setPlaybackRate(rate: number): void
+  getPlaybackRate(): number
+  setVolume(volume: number): void
+  getVolume(): number
+  mute(): void
+  unMute(): void
+  isMuted(): boolean
+  getCurrentTime(): number
+  getDuration(): number
+  getVideoLoadedFraction(): number
+  getPlayerState(): number
+  // Undocumented captions module (the only way to drive YouTube's captions
+  // through the IFrame API). YouTube renders the cues itself inside the iframe.
+  loadModule(module: string): void
+  unloadModule(module: string): void
+  getOption(module: string, option: string): unknown
+  setOption(module: string, option: string, value: unknown): void
+  destroy(): void
+}
+type YTPlayerEvent = { target: YTPlayer; data?: number }
+type YTPlayerCtorOptions = {
+  videoId: string
+  playerVars?: Record<string, unknown>
+  events?: {
+    onReady?: (e: YTPlayerEvent) => void
+    onStateChange?: (e: YTPlayerEvent) => void
+    onError?: (e: YTPlayerEvent) => void
+  }
+}
+type YTNamespace = {
+  Player: new (el: HTMLElement, opts: YTPlayerCtorOptions) => YTPlayer
+}
+type YTWindow = Window &
+  typeof globalThis & {
+    YT?: YTNamespace
+    onYouTubeIframeAPIReady?: () => void
+  }
+
+// YT.PlayerState codes (the API publishes these on YT.PlayerState; we only need
+// the numbers, which are stable).
+const PLAYING = 1
+const ENDED = 0
+// Buffering means the player is trying to play, not paused — treat it as such
+// so a mid-playback stall doesn't read as "paused" (which would flash the
+// poster cover).
+const BUFFERING = 3
+
+// The captions module is undocumented and has been renamed over the years, so
+// we probe both names.
+const CAPTION_MODULES = ["captions", "cc"] as const
+
+const IFRAME_API_SRC = "https://www.youtube.com/iframe_api"
+
+export type YouTubeProviderOptions = {
+  // A YouTube video id, or any watch / youtu.be / embed / shorts URL —
+  // parseYouTubeId resolves it.
+  videoId: string
+  metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }
+  autoPlay?: boolean
+  muted?: boolean
+  loop?: boolean
+  defaultRate?: number
+}
+
+// Pull the 11-char video id out of any common YouTube URL form; a bare id is
+// returned unchanged, so callers can pass either.
+export function parseYouTubeId(input: string): string {
+  const trimmed = input.trim()
+  if (/^[\w-]{11}$/.test(trimmed)) return trimmed
+  const m = trimmed.match(
+    /(?:youtu\.be\/|\/embed\/|\/shorts\/|[?&]v=)([\w-]{11})/,
+  )
+  return m ? m[1]! : trimmed
+}
+
+// Lazily load the IFrame API exactly once and resolve when YT.Player is ready.
+// Multiple players share this single promise; an already-present YT short-
+// circuits. The API calls window.onYouTubeIframeAPIReady when it finishes, so
+// we chain any existing handler rather than clobber it.
+let apiPromise: Promise<YTNamespace> | null = null
+function loadYouTubeAPI(): Promise<YTNamespace> {
+  const w = window as YTWindow
+  if (w.YT?.Player) return Promise.resolve(w.YT)
+  if (apiPromise) return apiPromise
+  apiPromise = new Promise<YTNamespace>((resolve) => {
+    const prev = w.onYouTubeIframeAPIReady
+    w.onYouTubeIframeAPIReady = () => {
+      prev?.()
+      if (w.YT) resolve(w.YT)
+    }
+    if (!document.querySelector(`script[src="${IFRAME_API_SRC}"]`)) {
+      const script = document.createElement("script")
+      script.src = IFRAME_API_SRC
+      script.async = true
+      document.head.appendChild(script)
+    }
+  })
+  return apiPromise
+}
+
+function readyYT(): YTNamespace | null {
+  if (typeof window === "undefined") return null
+  const yt = (window as YTWindow).YT
+  return yt && typeof yt.Player === "function" ? yt : null
+}
+
+export function createYouTubeProvider(opts: YouTubeProviderOptions): Provider {
+  const initialId = parseYouTubeId(opts.videoId)
+  let player: YTPlayer | null = null
+  let destroyed = false
+  // The IFrame API attaches the player's methods only after onReady fires;
+  // touching it before then throws. Gate all reads on this flag.
+  let ready = false
+  let ticker: ReturnType<typeof setInterval> | undefined
+  // The rate the viewer chose. Loading a new video resets the player's rate to
+  // 1x, so we re-assert this after every load (see syncFromPlayer) and always
+  // report it as state.rate so the reset never surfaces.
+  let desiredRate = opts.defaultRate ?? 1
+  // Which captions-module name this player answers to, and a signature of the
+  // last-published track list so we only patch when it actually changes (the
+  // ticker reads the list every 250ms).
+  let captionModule: string = CAPTION_MODULES[0]
+  let captionsSig = ""
+
+  let state: MediaState = {
+    ...defaultState(),
+    rate: desiredRate,
+    muted: opts.muted ?? false,
+    capabilities: {
+      // The IFrame API no longer exposes manual quality selection.
+      canSetQuality: false,
+      hasStoryboard: false,
+      // No PiP handle on a cross-origin iframe.
+      canPiP: false,
+      // We fullscreen the kino wrapper (the iframe lives inside it).
+      canFullscreen: true,
+      canSetRate: true,
+      // Caption control over the iframe API is unofficial; keep it off.
+      hasTextTracks: false,
+    },
+  }
+  const listeners = new Set<() => void>()
+  const emit = () => listeners.forEach((l) => l())
+  const patch = (p: Partial<MediaState>) => {
+    state = { ...state, ...p }
+    emit()
+  }
+
+  const onFullscreenChange = () =>
+    patch({ fullscreen: document.fullscreenElement != null })
+
+  const syncFromPlayer = () => {
+    if (!player || !ready) return
+    // A video load resets the player's rate to 1x; re-assert the chosen rate so
+    // it survives loads/swaps.
+    if (player.getPlaybackRate() !== desiredRate)
+      player.setPlaybackRate(desiredRate)
+    const ps = player.getPlayerState()
+    const duration = player.getDuration() || 0
+    const loaded = player.getVideoLoadedFraction() || 0
+    patch({
+      paused: ps !== PLAYING && ps !== BUFFERING,
+      ended: ps === ENDED,
+      currentTime: player.getCurrentTime() || 0,
+      duration,
+      buffered: duration > 0 ? [[0, loaded * duration]] : [],
+      rate: desiredRate,
+      volume: (player.getVolume() || 0) / 100,
+      muted: player.isMuted(),
+      readyState: 4,
+    })
+    syncCaptions()
+  }
+
+  // Read YouTube's caption track list (it populates a beat or two after the
+  // module loads) and publish it as text tracks. YouTube renders the cues
+  // itself inside the iframe, so kino only owns the on/off + language menu —
+  // activeCueText stays empty and the styled overlay paints nothing.
+  const syncCaptions = () => {
+    if (!player) return
+    let list: YTCaptionTrack[] = []
+    for (const mod of CAPTION_MODULES) {
+      try {
+        const got = player.getOption(mod, "tracklist")
+        if (Array.isArray(got)) {
+          list = got as YTCaptionTrack[]
+          captionModule = mod
+          if (got.length) break
+        }
+      } catch {
+        /* module not loaded yet */
+      }
+    }
+    const tracks: TextTrackInfo[] = list.map((t) => ({
+      id: t.languageCode,
+      kind: "captions",
+      label: t.displayName || t.languageCode,
+      lang: t.languageCode,
+      mode: state.activeTextTrackId === t.languageCode ? "showing" : "disabled",
+    }))
+    const sig = tracks.map((t) => `${t.id}:${t.mode}`).join("|")
+    if (sig === captionsSig) return
+    captionsSig = sig
+    patch({
+      textTracks: tracks,
+      capabilities: {
+        ...state.capabilities,
+        hasTextTracks: tracks.length > 0,
+      },
+    })
+  }
+
+  const setSessionMetadata = (title: string) => {
+    if (typeof navigator === "undefined" || !("mediaSession" in navigator))
+      return
+    if (typeof MediaMetadata === "undefined") return
+    try {
+      navigator.mediaSession.metadata = new MediaMetadata({ title })
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const startTicker = () => {
+    // The IFrame API fires no timeupdate, so poll while a player exists to keep
+    // currentTime / buffered fresh during playback.
+    if (ticker == null) ticker = setInterval(syncFromPlayer, 250)
+  }
+
+  const actions: PlayerActions = {
+    play: () => player?.playVideo(),
+    pause: () => player?.pauseVideo(),
+    seek: (t) => player?.seekTo(t, true),
+    setRate: (r) => {
+      desiredRate = r
+      player?.setPlaybackRate(r)
+      // Reflect immediately even before the player echoes the change.
+      patch({ rate: r })
+    },
+    setVolume: (v) => player?.setVolume(Math.min(100, Math.max(0, v * 100))),
+    setMuted: (m) => {
+      if (m) player?.mute()
+      else player?.unMute()
+      patch({ muted: m })
+    },
+    // The IFrame API exposes no rendition ladder; quality is always "auto".
+    setQuality: () => {},
+    setTextTrack: (id) => {
+      patch({ activeTextTrackId: id })
+      // Drive YouTube's native caption rendering: a language code shows that
+      // track, an empty value clears it. (The cues paint inside the iframe.)
+      try {
+        player?.setOption(
+          captionModule,
+          "track",
+          id == null ? {} : { languageCode: id },
+        )
+      } catch {
+        /* module not loaded yet */
+      }
+      syncCaptions()
+    },
+    enterFullscreen: (wrapper) => {
+      // Fullscreen the kino wrapper so our controls stay over the iframe.
+      if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
+    },
+    exitFullscreen: () => {
+      if (document.fullscreenElement) void document.exitFullscreen?.()
+    },
+    enterPiP: () => {},
+    exitPiP: () => {},
+  }
+
+  const createPlayer = (yt: YTNamespace, host: HTMLElement) => {
+    player = new yt.Player(host, {
+      videoId: initialId,
+      playerVars: {
+        controls: 0, // kino owns the chrome
+        playsinline: 1,
+        rel: 0,
+        modestbranding: 1,
+        disablekb: 1, // kino owns the keyboard map
+        autoplay: opts.autoPlay ? 1 : 0,
+        mute: opts.muted ? 1 : 0,
+        loop: opts.loop ? 1 : 0,
+        // loop needs an explicit single-video playlist to repeat.
+        ...(opts.loop ? { playlist: initialId } : {}),
+      },
+      events: {
+        onReady: (e) => {
+          // The event carries the ready player; bind it (onReady can fire before
+          // the `new YT.Player()` assignment lands). Methods are live now.
+          player = e.target
+          ready = true
+          player.setPlaybackRate(desiredRate)
+          if (opts.muted) player.mute()
+          // Ask YouTube to expose its caption tracks (names vary by vintage).
+          for (const mod of CAPTION_MODULES) {
+            try {
+              player.loadModule(mod)
+            } catch {
+              /* unsupported module name */
+            }
+          }
+          setSessionMetadata(opts.metadata?.videoTitle ?? "Video")
+          syncFromPlayer()
+          startTicker()
+        },
+        onStateChange: syncFromPlayer,
+        onError: (e) =>
+          patch({
+            error: { code: e.data ?? 0, message: "YouTube playback error" },
+          }),
+      },
+    })
+  }
+
+  return {
+    mount(container) {
+      // The API replaces the passed element with an <iframe>, so give it a
+      // throwaway host div parented in our video host.
+      const host = document.createElement("div")
+      container.appendChild(host)
+      document.addEventListener("fullscreenchange", onFullscreenChange)
+      const yt = readyYT()
+      if (yt) {
+        createPlayer(yt, host)
+      } else {
+        void loadYouTubeAPI().then((loaded) => {
+          // Honor an early teardown: if destroy() ran before the API resolved,
+          // don't leave a live player behind.
+          if (destroyed) return
+          if (host.isConnected) createPlayer(loaded, host)
+        })
+      }
+    },
+    swapSource(next: SourceOptions) {
+      // YouTube carries the next video id through SourceOptions.src.
+      if (!player || !ready || next.src == null) return
+      player.loadVideoById(parseYouTubeId(next.src))
+      if (next.metadata?.videoTitle != null)
+        setSessionMetadata(next.metadata.videoTitle)
+      player.setPlaybackRate(desiredRate)
+      patch({
+        currentTime: 0,
+        duration: 0,
+        ended: false,
+        seeking: false,
+        error: null,
+      })
+    },
+    getState: () => state,
+    subscribe: (l) => {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    actions,
+    destroy() {
+      destroyed = true
+      ready = false
+      document.removeEventListener("fullscreenchange", onFullscreenChange)
+      if (ticker != null) clearInterval(ticker)
+      ticker = undefined
+      try {
+        player?.destroy()
+      } catch {
+        /* already gone */
+      }
+      player = null
+      listeners.clear()
+    },
+  }
+}
diff --git a/src/youtube/youtube-player.tsx b/src/youtube/youtube-player.tsx
new file mode 100644
index 0000000..c74bb6c
--- /dev/null
+++ b/src/youtube/youtube-player.tsx
@@ -0,0 +1,82 @@
+import { useEffect, useRef, type ReactNode } from "react"
+import { Player } from "../ui/player"
+import { ControlBar } from "../ui/control-bar"
+import { IdleOverlay } from "../ui/idle-overlay"
+import { Captions } from "../ui/captions"
+import { createYouTubeProvider, type YouTubeProviderOptions } from "./provider"
+import type { Provider } from "../core/types"
+
+export type YouTubePlayerProps = YouTubeProviderOptions & {
+  accentColor?: string
+  theme?: Record<string, string>
+  className?: string
+  /** Blur-up still painted behind the video until the first frame loads. */
+  placeholder?: string
+  children?: ReactNode
+}
+
+/**
+ * kino's glass chrome over a YouTube video, backed by the YouTube IFrame Player
+ * API. Pass a video id or any watch / youtu.be / embed / shorts URL.
+ *
+ * Only `videoId` and `metadata.videoTitle` are reactive (they flow through
+ * `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read once
+ * when the provider is created — changing them later is a no-op. Remount (e.g.
+ * via `key`) if you need them to change.
+ *
+ * The IFrame API can't expose quality or picture-in-picture, so those controls
+ * hide themselves automatically. Captions work through the API and are rendered
+ * by YouTube inside the embed.
+ *
+ * Per YouTube's API terms, kino doesn't obscure the player: YouTube shows its
+ * own thumbnail, play button, title, and logo before playback and while paused.
+ * kino's controls sit alongside them.
+ */
+export function YouTubePlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: YouTubePlayerProps) {
+  // Create the provider exactly once so <Player>'s mount effect runs a single
+  // time and the underlying iframe persists across source changes.
+  const providerRef = useRef<Provider | null>(null)
+  if (providerRef.current === null) {
+    providerRef.current = createYouTubeProvider(opts)
+  }
+  const provider = providerRef.current
+
+  // Source changes flow through swapSource so the iframe is reused instead of
+  // recreated, preserving DOM and fullscreen continuity. Skip the first run:
+  // the initial source is already set when the provider is created.
+  const mountedRef = useRef(false)
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true
+      return
+    }
+    provider.swapSource?.({
+      src: opts.videoId,
+      metadata: opts.metadata,
+    })
+    // Depend on the primitive title (not the metadata object) so a title-only
+    // change refreshes the OS media session without re-swapping every render.
+  }, [opts.videoId, opts.metadata?.videoTitle])
+
+  return (
+    <Player
+      provider={provider}
+      accentColor={accentColor}
+      theme={theme}
+      className={className}
+      placeholder={placeholder}
+    >
+      <IdleOverlay />
+      <Captions />
+      <ControlBar />
+      {children}
+    </Player>
+  )
+}
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 28e14c3..25408f9 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -1,7 +1,12 @@
 import { defineConfig } from "tsdown"
 
 export default defineConfig({
-  entry: { index: "src/index.ts", mux: "src/mux.ts", native: "src/native.ts" },
+  entry: {
+    index: "src/index.ts",
+    mux: "src/mux.ts",
+    native: "src/native.ts",
+    youtube: "src/youtube.ts",
+  },
   format: ["esm"],
   dts: true,
   clean: true,