From 514532c1efedb96ec902f624f2f056bc014b1e84 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 15:59:50 +0530
Subject: [PATCH 01/21] docs: Vimeo provider design spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Event-driven provider over the Vimeo Player SDK — quality, captions,
PiP, and rate. Mirrors youtube/ shape (async iframe SDK, destroyed
flag) but syncs on SDK events instead of a ticker, renders cues in
kino's own overlay (enableTextTrack showing:false + cuechange), and
derives plan-gated capabilities at runtime. Supports unlisted videos
via hash parsing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../specs/2026-06-28-vimeo-provider-design.md | 338 ++++++++++++++++++
 1 file changed, 338 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-28-vimeo-provider-design.md

diff --git a/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md b/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md
new file mode 100644
index 0000000..0e3ecb0
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md
@@ -0,0 +1,338 @@
+# Vimeo provider — design
+
+## Goal
+
+Add a Vimeo provider to kino so the same glass chrome plays Vimeo videos,
+mirroring the existing `mux/`, `native/`, and `youtube/` providers. Vimeo's
+Player SDK is the richest of the iframe-backed engines — quality selection,
+text tracks with cue text, picture-in-picture, and playback rate — so this
+provider reports the widest capability set **and** is the first iframe provider
+to render styled captions in kino's own overlay. Then update the README, demo
+site, and overview copy so the docs advertise **four** shipped providers (Mux,
+Native, YouTube, Vimeo).
+
+## 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 Vimeo provider follows the `youtube/` shape (async-loaded iframe SDK, host
+div, `destroyed` flag), but its state sync is **event-driven** like `native/`
+rather than polled — the Vimeo SDK emits `timeupdate`.
+
+### New files
+
+- `src/vimeo/provider.ts` — `createVimeoProvider(opts): Provider` +
+  `VimeoProviderOptions` type + `parseVimeoSource(input): { id; hash? }` helper.
+- `src/vimeo/vimeo-player.tsx` — `<VimeoPlayer>` (props = `VimeoProviderOptions`
+  + `accentColor/theme/className/placeholder/children`).
+- `src/vimeo/provider.test.ts` — vitest, mirroring `youtube/provider.test.ts`
+  (fake `window.Vimeo.Player`).
+- `src/vimeo.ts` — entry re-exporting the provider, component, types, helper.
+
+### Wiring
+
+- `package.json` → add `exports["./vimeo"]` (`./dist/vimeo.{d.ts,js}`); add
+  `"vimeo"` to `keywords` (mirrors the `youtube` entry).
+- `tsdown.config.ts` → add `vimeo: "src/vimeo.ts"` entry.
+- `src/styles/kino.css` → **no change**. The existing
+  `.kino .kino-video-host iframe` rules (sizing + `pointer-events: none`, added
+  for YouTube) already cover the Vimeo iframe, which lands inside
+  `.kino-video-host`.
+- No runtime dependency and no `@types/*` package — the SDK script is loaded at
+  runtime and its surface is hand-rolled as a narrow local structural type
+  (matching `MuxVideoEl` / the YouTube `YTPlayer` alias style).
+
+## Engine integration
+
+Vimeo Player SDK (`player.js`). A module-level singleton promise lazy-loads
+`https://player.vimeo.com/api/player.js` and resolves when `window.Vimeo.Player`
+is ready. An already-present `window.Vimeo` short-circuits. Unlike YouTube there
+is **no global ready callback** — the injected `<script>`'s `onload` resolves
+the promise (this shapes the test harness; see Testing).
+
+`mount(container)` appends a host `<div>` and, once the SDK resolves, constructs
+`new Vimeo.Player(hostDiv, options)`. The SDK injects an `<iframe>` inside the
+div. The kino gesture overlay sits above the iframe and owns clicks/keys
+(`controls: false` removes Vimeo's own chrome — see the plan caveat below).
+
+Because mount is synchronous but player creation is async, the provider tracks a
+`destroyed` flag: if `destroy()` runs before the player resolves, the player is
+torn down (`player.destroy()`) as soon as it does.
+
+### Readiness
+
+The provider's `ready` flag flips on `player.ready()` (the SDK's iframe-init
+promise). player.js internally queues method calls made before ready, so
+fire-and-forget calls are safe regardless, but reads (`getDuration`,
+`getQualities`, `getTextTracks`) and the capability refresh run in the `loaded`
+handler, which fires once video metadata is available.
+
+### Player options
+
+```ts
+new Vimeo.Player(host, {
+  id,                 // numeric id (public videos)
+  url,                // player.vimeo.com/video/ID?h=HASH (unlisted — see below)
+  controls: false,    // kino owns the chrome (paid-plan feature — see caveat)
+  autoplay: !!opts.autoPlay,
+  muted: !!opts.muted,
+  loop: !!opts.loop,
+  playsinline: true,
+  dnt: true,          // do-not-track; no analytics cookies
+  keyboard: false,    // kino owns the keyboard map
+})
+```
+
+Pass `id` for public videos; pass `url` when a hash is present (the hash
+authorizes unlisted/private videos and must reach the embed). Use the
+SDK-documented query form `https://player.vimeo.com/video/<id>?h=<hash>`.
+
+> **Plan caveat (document in JSDoc).** `controls: false` (chromeless playback)
+> requires a **paid** Vimeo plan. On a free-account video the flag is ignored:
+> Vimeo's own controls render beneath kino's overlay, and because the iframe is
+> `pointer-events: none`, the viewer sees but cannot use them. kino can't detect
+> the plan, so the `<VimeoPlayer>` JSDoc must state that a chromeless-eligible
+> (paid) source is required for the intended experience.
+
+### Promise-based surface
+
+Every Vimeo method returns a Promise. Actions call them fire-and-forget with a
+trailing `.catch(() => {})` — a method that is plan-gated (`setPlaybackRate`,
+`setQuality`), read-only on the platform (`setVolume` on iOS), or called against
+a torn-down player rejects, and we swallow it. State is then driven by the
+echo **event** (e.g. `playbackratechange`) rather than an optimistic patch, so
+a rejected call never leaves the UI showing a change that did not happen.
+
+## State mapping
+
+Vimeo is event-driven — **no ticker**. `timeupdate` (~4×/sec during playback)
+carries `{ seconds, duration, percent }` and `progress` carries the buffered
+`{ seconds, duration, percent }`, so `currentTime`/`buffered` stay fresh without
+polling.
+
+| MediaState          | Source                                                            |
+| ------------------- | ---------------------------------------------------------------- |
+| `paused`            | `play` → false; `pause`/`ended` → true; `bufferstart` keeps false |
+| `ended`             | `ended` → true; cleared on `play`/`seeked`/swap                   |
+| `currentTime`       | `timeupdate.seconds` (and `seeked`)                              |
+| `duration`          | `timeupdate.duration` / `getDuration()` at `loaded`              |
+| `buffered`          | `progress.percent` → `[[0, percent * duration]]`                |
+| `rate`              | `playbackratechange.playbackRate` (re-asserted as `desiredRate`) |
+| `volume`            | `volumechange.volume` (already `0..1`, no scaling)              |
+| `muted`             | `volumechange.muted`; `getMuted()` at `loaded`                  |
+| `qualities`         | `getQualities()` at `loaded` → `QualityLevel[]`                 |
+| `activeQualityId`   | active entry id; `qualitychange.quality` (string id) thereafter |
+| `textTracks`        | `getTextTracks()` at `loaded` → `TextTrackInfo[]`               |
+| `activeTextTrackId` | synthesized id of the active track; `null` on `texttrackchange` disable |
+| `activeCueText`     | `cuechange.cues[0].text` (cues rendered in kino's overlay)       |
+| `pip`               | `enterpictureinpicture` / `leavepictureinpicture`               |
+| `fullscreen`        | `fullscreenchange.fullscreen` / `document.fullscreenElement`     |
+| `error`             | `error` → `{ code: 0, message: name ? `${name}: ${message}` : message }` |
+| `readyState`        | 4 once `loaded` fires, else 0                                    |
+| `storyboard`        | null — no scrub-preview source                                  |
+
+`bufferstart`/`bufferend` keep `paused` honest during a mid-playback stall so
+the poster cover doesn't flash (same intent as YouTube's `BUFFERING` handling).
+`volumechange` carries `{ volume, muted }` — read **both** so an external
+mute/unmute (e.g. an autoplay-muted video being unmuted) doesn't drift
+`state.muted`. The `error` payload is `{ message, name, method? }` with **no
+numeric code**, so `code` is a fixed `0` and `name` is folded into the message.
+
+## Capabilities
+
+| Capability      | Value                                       | Reason                                                    |
+| --------------- | ------------------------------------------- | --------------------------------------------------------- |
+| `canSetRate`    | true (best-effort — see note)               | `setPlaybackRate` works on Pro/Business; can't be probed cheaply. |
+| `canFullscreen` | true                                        | We fullscreen the kino wrapper; the iframe is inside it.   |
+| `canPiP`        | `!!document.pictureInPictureEnabled`        | SDK `requestPictureInPicture` where the browser allows it. |
+| `canSetQuality` | `getQualities().length > 0` (set at `loaded`) | Quality API is plan-gated; an empty/failed call ⇒ no menu. |
+| `hasTextTracks` | `getTextTracks().length > 0` (set at `loaded`) | `getTextTracks` returns the caption list.              |
+| `hasStoryboard` | false                                       | No scrub-preview source.                                  |
+
+`canSetQuality` and `hasTextTracks` start `false` and flip on once the `loaded`
+handler reads non-empty lists — so a plan that lacks the quality API simply
+never shows the menu (no dead button). `canSetRate` cannot be detected before a
+`setPlaybackRate` attempt, so it is reported `true` as best-effort: if the call
+rejects (free/Personal plan), `playbackratechange` never fires and the rate
+state stays put rather than lying. `canPiP` reads
+`document.pictureInPictureEnabled` at creation (note: **undefined in Firefox**,
+which has its own PiP and will report `false` here; the cross-origin request
+also needs a user gesture, which kino's button click supplies).
+
+## Actions
+
+All gated on `ready`; all Promise calls carry `.catch(() => {})`; state changes
+land via the echo event, not an optimistic patch (except `seek`, which patches
+`seeking` immediately for responsiveness).
+
+| Action            | Implementation                                                      |
+| ----------------- | ------------------------------------------------------------------ |
+| `play / pause`    | `player.play() / player.pause()`                                   |
+| `seek(t)`         | `player.setCurrentTime(t)`; patch `seeking: true`                  |
+| `setRate(r)`      | store `desiredRate = r`; `player.setPlaybackRate(r)` — `rate` patched on `playbackratechange` |
+| `setVolume(v)`    | `player.setVolume(v)` — `0..1`, no scaling                          |
+| `setMuted(m)`     | `player.setMuted(m)` — `muted` patched on `volumechange`            |
+| `setQuality(id)`  | `player.setQuality(id)` (`"auto"` for adaptive) — patched on `qualitychange` |
+| `setTextTrack(id)`| resolve id → `{language, kind}`; `enableTextTrack(language, kind, false)` or `disableTextTrack()` |
+| `enterFullscreen` | `wrapper.requestFullscreen()` (kino wrapper, controls stay on top)  |
+| `exitFullscreen`  | `document.exitFullscreen()`                                         |
+| `enterPiP`        | `player.requestPictureInPicture()`                                 |
+| `exitPiP`         | `player.exitPictureInPicture()`                                    |
+
+### Quality mapping
+
+`getQualities()` returns `[{ id, label, active }]` where `id` is the resolution
+token (`"2160p"`, `"1080p"`, `"auto"`) and `label` is a human string (`"4K"`,
+`"1080p"`, `"Auto"`). Map to kino's `QualityLevel`:
+
+```
+{ id, height: parseInt(id) || 0, bitrate: 0, selected: active }
+```
+
+**Height is parsed from `id`, not `label`** — `parseInt("4K")` is `4`. Vimeo
+exposes no bitrate, so `bitrate: 0`. `activeQualityId` is the `active` entry's
+`id`, falling back to `"auto"`; `qualitychange` carries `{ quality }` (the new
+id string) thereafter.
+
+### Captions
+
+Unlike YouTube, this provider renders cues in kino's own overlay. `getTextTracks`
+returns `{ label, language, kind, mode }` with **no `id`**, so the provider
+synthesizes a stable id `${language}.${kind}` (with an index suffix on
+collision) for `textTracks[]` and `activeTextTrackId`. `setTextTrack(id)`
+resolves that back to `{ language, kind }` and calls
+`enableTextTrack(language, kind, /* showing */ false)` — the `false` keeps the
+player from painting its own cues while still emitting `cuechange`. The provider
+maps `cuechange.cues[0].text` into `activeCueText`, so kino's styled
+`.kino-captions` overlay shows the caption (the same path `native/` uses).
+`disableTextTrack()` clears it (`activeTextTrackId: null`, `activeCueText: ""`).
+`texttrackchange` (payload `{ kind, label, language }`, all null when disabled)
+reconciles `activeTextTrackId` against the synthesized scheme.
+
+> iOS caveat (mirror `native/`): during iOS native fullscreen the system paints
+> its own captions; the provider should not double-render. Follow native's iOS
+> branch if the same condition applies.
+
+## Options
+
+```ts
+type VimeoProviderOptions = {
+  videoId: string // numeric id, or any vimeo.com / player.vimeo.com URL
+  hash?: string // unlisted/private hash; also parsed from the URL
+  metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }
+  autoPlay?: boolean
+  muted?: boolean
+  loop?: boolean
+  defaultRate?: number
+}
+```
+
+`parseVimeoSource(input)` returns `{ id, hash? }` and accepts:
+
+| Input                                          | → id        | → hash       |
+| ---------------------------------------------- | ----------- | ------------ |
+| `123456789` (bare)                             | `123456789` | —            |
+| `https://vimeo.com/123456789`                  | `123456789` | —            |
+| `https://vimeo.com/123456789/abcdef0123`       | `123456789` | `abcdef0123` |
+| `https://player.vimeo.com/video/123456789?h=X` | `123456789` | `X`          |
+
+An explicit `hash` option wins over a URL-derived one. A bare id passes through
+unchanged (input returned as id if no numeric match). When a hash is present the
+provider builds the documented `https://player.vimeo.com/video/<id>?h=<hash>`
+URL for the SDK; otherwise it passes the numeric `id`.
+
+### swapSource and the hash channel
+
+`SourceOptions` (`{ playbackId, src, poster, tokens, metadata }`) has **no
+`hash` field**, so the hash can't travel as a separate property. Instead,
+`<VimeoPlayer>` packs the source into `src` as a single string: when a hash is
+present it passes the full `player.vimeo.com/video/ID?h=HASH` URL; otherwise the
+bare id. `swapSource` runs `parseVimeoSource(next.src)` to recover `{ id, hash }`
+and calls `player.loadVideo(hash ? { url } : id)`, then resets
+`currentTime/duration/ended/error`, re-asserts `desiredRate`, and refreshes the
+media-session title. (Re-asserting the rate after a load is defensive — that
+Vimeo resets `playbackRate` on `loadVideo` is **assumed, not doc-confirmed**;
+the re-assert is harmless either way.)
+
+Like the other providers, `autoPlay/muted/loop/defaultRate` are read once at
+creation.
+
+### `<VimeoPlayer>` reactive machinery
+
+Replicate `youtube-player.tsx` exactly, with `hash` threaded through:
+
+- `providerRef = useRef<Provider|null>(null)`; create the provider only when
+  `null`, so `<Player>`'s mount effect runs once and the iframe persists.
+- `mountedRef` skip-first guard so the initial render doesn't fire a redundant
+  `swapSource` (the source is already set at creation).
+- The swap effect builds `src` from `videoId` + `hash`
+  (`hash ? playerUrl(videoId, hash) : videoId`) and passes `metadata`; its
+  dependency array is `[opts.videoId, opts.hash, opts.metadata?.videoTitle]` —
+  note `hash` is included (YouTube has no equivalent).
+
+## Testing
+
+Mirror `youtube/provider.test.ts`, mocking `window.Vimeo.Player` with a fake
+`Player` that (a) records method calls, (b) returns resolved Promises from the
+async methods, and (c) lets tests emit events by invoking the handlers
+registered via `on(event, fn)`. Because there is no global ready callback, the
+harness differs from YouTube's:
+
+- For normal tests, **pre-set `window.Vimeo.Player`** so the loader
+  short-circuits synchronously.
+- For the loader / early-destroy tests, leave `window.Vimeo` unset, then grab
+  the injected `<script>` and **dispatch its `load` event manually** (jsdom does
+  not fire it) to drive the singleton promise.
+
+Cover:
+
+- initial state defaults + the capability set (with `canSetQuality`/
+  `hasTextTracks` starting `false`, then flipping on after `loaded`);
+- `parseVimeoSource` across every URL form + bare id + explicit-hash precedence;
+- unlisted construction passes the `?h=` `url`, public passes `id`;
+- actions call the right SDK methods (`setVolume` unscaled; `setQuality`;
+  `enableTextTrack(lang, kind, false)` / `disableTextTrack`; PiP enter/exit);
+- `loaded` populates duration, qualities (height parsed from `id`, incl. a `4K`
+  ⇒ height `2160` case via `id:"2160p"`), and text tracks (synthesized ids, no
+  collision for same-language different-kind tracks);
+- event sync: `timeupdate`/`progress` update time+buffered; `cuechange` →
+  `activeCueText`; `volumechange.muted` reconciles mute; `qualitychange.quality`;
+  `texttrackchange`; `enter/leavepictureinpicture`; `fullscreenchange`;
+- rate: `setRate` does **not** patch `rate` optimistically; `rate` only moves on
+  `playbackratechange`, and `desiredRate` survives a `swapSource`;
+- `swapSource` calls `loadVideo` (with `{ url }` when the new src carries a hash)
+  and resets progress;
+- deferred readiness — no SDK method runs before the loader resolves;
+- `destroy` tears the player down, and an early `destroy()` (before the SDK
+  script's `load`) leaves no live player.
+
+## Docs / demo updates
+
+- **README.md** — add Vimeo to the shipped-providers list; add a "Playing a
+  Vimeo video" section (incl. an unlisted-with-hash example); drop Vimeo from
+  the roadmap.
+- **demo/pages/providers.tsx** — Vimeo card `planned` → `shipped` with `entry`
+  (`@karnstack/kino/vimeo`) + `importLine`
+  (`import { VimeoPlayer } from "@karnstack/kino/vimeo"`); the detail copy should
+  note the chromeless/paid-plan requirement.
+- **demo/pages/install.tsx** — Vimeo snippet + `VimeoPlayer` props table.
+- **demo/pages/overview.tsx** — highlight copy: Vimeo now ships.
+- **demo/player-studio.tsx** — add a "Vimeo" provider tab playing a public,
+  chromeless-eligible id.
+- **.changeset/** — a `minor` changeset describing the new provider.
+
+## Embed terms
+
+Like YouTube, kino must not obscure the Vimeo player: no poster-on-pause cover
+over the embed. kino's controls sit alongside Vimeo's surface. Documented in the
+`<VimeoPlayer>` component JSDoc, together with the chromeless/paid-plan note.
+
+## Out of scope
+
+AirPlay, chapters, Vimeo analytics events, live-stream–specific controls, and
+runtime detection of the account plan (kino documents the chromeless/paid
+requirement rather than probing for it).

From 26c021c97f0edbf439bbfcffaf2fa2cac33a5562 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:20:58 +0530
Subject: [PATCH 02/21] docs: Vimeo provider implementation plan

10 TDD tasks from source parsing through docs/changeset. Shared
FakeVimeoPlayer fixture, event-driven sync, runtime-derived
capabilities, hash channel through swapSource.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-06-28-vimeo-provider.md        | 1593 +++++++++++++++++
 1 file changed, 1593 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-28-vimeo-provider.md

diff --git a/docs/superpowers/plans/2026-06-28-vimeo-provider.md b/docs/superpowers/plans/2026-06-28-vimeo-provider.md
new file mode 100644
index 0000000..a0e0d9f
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-28-vimeo-provider.md
@@ -0,0 +1,1593 @@
+# Vimeo Provider Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `@karnstack/kino/vimeo` provider that plays Vimeo videos under kino's glass chrome, with quality, styled captions, PiP, and rate — the richest of the iframe providers.
+
+**Architecture:** A function factory `createVimeoProvider(opts): Provider` wraps the Vimeo Player SDK (`player.js`). It mirrors the `youtube/` shape (module-level singleton SDK loader, host `<div>`, `destroyed` flag for early teardown) but syncs state from SDK **events** (like `native/`) instead of a polling ticker. A thin `<VimeoPlayer>` React wrapper creates the provider once and routes reactive prop changes through `swapSource`. Plan-gated capabilities (quality) are derived at `loaded` rather than hardcoded.
+
+**Tech Stack:** TypeScript, React 19, Vimeo Player SDK (loaded at runtime, hand-rolled structural types — no `@types` package, no runtime dep), vitest + jsdom, tsdown build.
+
+## Global Constraints
+
+- Package is single-package `@karnstack/kino` (not a monorepo). New entry point `./vimeo` mirrors `./youtube`.
+- No runtime dependency on the Vimeo SDK and no `@types/*` — load the script at runtime, type its surface with a narrow local structural alias (match `YTPlayer` in `src/youtube/provider.ts` and `MuxVideoEl` in `src/mux/provider.ts`).
+- SDK script URL: `https://player.vimeo.com/api/player.js`; global: `window.Vimeo.Player`. No global ready callback — resolve the loader on the injected `<script>`'s `load` event; short-circuit if `window.Vimeo` already exists.
+- `Provider` contract (`src/core/types.ts`): `mount`, `getState`, `subscribe`, `actions`, `destroy`, optional `swapSource`. State shape is `MediaState`; quality items are `QualityLevel { id, height, bitrate, selected }`; tracks are `TextTrackInfo { id, kind, label, lang, mode }`; errors are `MediaError { code, message }`.
+- Vimeo SDK methods all return Promises. Actions call them fire-and-forget with a trailing `.catch(() => {})`. State changes land via the echo **event**, never an optimistic patch that a rejected (plan-gated) call could leave lying. The one exception: `seek` patches `seeking: true` immediately.
+- Volume is `0..1` on the Vimeo SDK — maps straight to `MediaState.volume`, **no ×100 scaling**.
+- Quality height is parsed from the quality **`id`** (`"2160p"` → `2160`), never the human `label` (`"4K"` → `4`).
+- `controls: false` (chromeless) is a **paid Vimeo plan** feature — document in the `<VimeoPlayer>` JSDoc; do not detect it at runtime.
+- Embed terms (mirror YouTube): do not obscure the player; no poster-on-pause cover. Document in JSDoc.
+- All work happens on branch `feat/vimeo-provider`; never commit to `main`. The PR is opened at the end.
+- Run the full check before any "done" claim: `pnpm test`, `pnpm typecheck`, `pnpm lint`.
+
+---
+
+## File Structure
+
+- **Create** `src/vimeo/provider.ts` — `createVimeoProvider`, `VimeoProviderOptions`, `parseVimeoSource`, `playerUrl`, local SDK types, singleton loader.
+- **Create** `src/vimeo/vimeo-player.tsx` — `<VimeoPlayer>` React wrapper.
+- **Create** `src/vimeo/fake-vimeo.ts` — **test-only** fake `Vimeo.Player` + `installFakeVimeo()` helper (imported only by the test, so it never enters a build-entry graph and never ships).
+- **Create** `src/vimeo/provider.test.ts` — vitest suite.
+- **Create** `src/vimeo/vimeo-player.test.tsx` — light React wrapper test.
+- **Create** `src/vimeo.ts` — entry re-export.
+- **Modify** `package.json` — `exports["./vimeo"]`, `keywords` += `"vimeo"`.
+- **Modify** `tsdown.config.ts` — `entry.vimeo`.
+- **Modify** `README.md`, `demo/pages/providers.tsx`, `demo/pages/install.tsx`, `demo/pages/overview.tsx`, `demo/player-studio.tsx`.
+- **Create** `.changeset/<name>.md`.
+
+---
+
+## Task 1: Source parsing + URL helper + options type
+
+**Files:**
+- Create: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces:
+  - `type VimeoProviderOptions = { videoId: string; hash?: string; metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }; autoPlay?: boolean; muted?: boolean; loop?: boolean; defaultRate?: number }`
+  - `function parseVimeoSource(input: string): { id: string; hash?: string }`
+  - `function playerUrl(id: string, hash: string): string` → `https://player.vimeo.com/video/<id>?h=<hash>`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/vimeo/provider.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest"
+import { parseVimeoSource, playerUrl } from "./provider"
+
+describe("parseVimeoSource", () => {
+  it("passes a bare numeric id through", () => {
+    expect(parseVimeoSource("123456789")).toEqual({ id: "123456789" })
+  })
+  it("extracts id from a vimeo.com URL", () => {
+    expect(parseVimeoSource("https://vimeo.com/123456789")).toEqual({
+      id: "123456789",
+    })
+  })
+  it("extracts id + hash from an unlisted share URL", () => {
+    expect(parseVimeoSource("https://vimeo.com/123456789/abcdef0123")).toEqual({
+      id: "123456789",
+      hash: "abcdef0123",
+    })
+  })
+  it("extracts id + hash from a player.vimeo.com ?h= URL", () => {
+    expect(
+      parseVimeoSource("https://player.vimeo.com/video/123456789?h=xyz789"),
+    ).toEqual({ id: "123456789", hash: "xyz789" })
+  })
+  it("returns input unchanged as id when no number is found", () => {
+    expect(parseVimeoSource("not-a-vimeo")).toEqual({ id: "not-a-vimeo" })
+  })
+})
+
+describe("playerUrl", () => {
+  it("builds the documented ?h= embed URL", () => {
+    expect(playerUrl("123456789", "abc")).toBe(
+      "https://player.vimeo.com/video/123456789?h=abc",
+    )
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: FAIL — cannot resolve `./provider` (file does not exist yet).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `src/vimeo/provider.ts`:
+
+```ts
+export type VimeoProviderOptions = {
+  // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
+  // parseVimeoSource resolves it.
+  videoId: string
+  // Unlisted/private hash. Also parsed from the URL form; an explicit hash here
+  // wins over a URL-derived one.
+  hash?: string
+  metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }
+  autoPlay?: boolean
+  muted?: boolean
+  loop?: boolean
+  defaultRate?: number
+}
+
+// Pull the numeric id (and optional unlisted hash) out of any common Vimeo
+// reference. A bare id is returned unchanged so callers can pass either.
+//   vimeo.com/123                -> { id: "123" }
+//   vimeo.com/123/HASH           -> { id: "123", hash: "HASH" }
+//   player.vimeo.com/video/123?h=HASH -> { id: "123", hash: "HASH" }
+export function parseVimeoSource(input: string): { id: string; hash?: string } {
+  const trimmed = input.trim()
+  // ?h= query form (player.vimeo.com embeds).
+  const q = trimmed.match(/[?&]h=([\w]+)/)
+  // /ID or /ID/HASH path form (vimeo.com share links). The id is the first
+  // numeric path segment; the hash is the next path segment if present.
+  const path = trimmed.match(/(?:^|\/)(\d+)(?:\/([\w]+))?/)
+  if (!path) return { id: trimmed }
+  const id = path[1]!
+  const hash = q?.[1] ?? path[2]
+  return hash ? { id, hash } : { id }
+}
+
+// The documented SDK embed URL that carries an unlisted hash.
+export function playerUrl(id: string, hash: string): string {
+  return `https://player.vimeo.com/video/${id}?h=${hash}`
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): source parsing + embed-url helper"
+```
+
+---
+
+## Task 2: SDK loader, lifecycle, and the test fake
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Create: `src/vimeo/fake-vimeo.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: `VimeoProviderOptions`, `parseVimeoSource`, `playerUrl` (Task 1).
+- Produces:
+  - `function createVimeoProvider(opts: VimeoProviderOptions): Provider`
+  - From `fake-vimeo.ts`: `class FakeVimeoPlayer` (records `calls: Array<[string, unknown]>`, exposes `emit(event, data)`, static `instances: FakeVimeoPlayer[]`, mutable `_duration/_qualities/_textTracks/_muted`), `function installFakeVimeo(): void`, `function uninstallFakeVimeo(): void`, `function flush(): Promise<void>`.
+
+- [ ] **Step 1: Write the fake**
+
+Create `src/vimeo/fake-vimeo.ts`:
+
+```ts
+// Test-only stand-in for the Vimeo Player SDK. jsdom has no SDK, so tests
+// install this on window.Vimeo. Methods record their calls and return resolved
+// promises; tests drive state by calling emit(event, payload). Imported ONLY by
+// the vitest specs, so it never enters a tsdown build-entry graph.
+type Handler = (data?: unknown) => void
+
+export class FakeVimeoPlayer {
+  static instances: FakeVimeoPlayer[] = []
+  el: HTMLElement
+  opts: Record<string, unknown>
+  calls: Array<[string, unknown]> = []
+  private handlers: Record<string, Set<Handler>> = {}
+  _duration = 0
+  _qualities: Array<{ id: string; label: string; active: boolean }> = []
+  _textTracks: Array<{
+    label: string
+    language: string
+    kind: string
+    mode: string
+  }> = []
+  _muted = false
+
+  constructor(el: HTMLElement, opts: Record<string, unknown>) {
+    this.el = el
+    this.opts = opts
+    FakeVimeoPlayer.instances.push(this)
+    el.appendChild(document.createElement("iframe")) // the SDK injects an iframe
+  }
+
+  on(event: string, fn: Handler) {
+    ;(this.handlers[event] ??= new Set()).add(fn)
+  }
+  off(event: string, fn?: Handler) {
+    if (fn) this.handlers[event]?.delete(fn)
+    else delete this.handlers[event]
+  }
+  emit(event: string, data?: unknown) {
+    this.handlers[event]?.forEach((fn) => fn(data))
+  }
+
+  ready() {
+    return Promise.resolve()
+  }
+  play() {
+    this.calls.push(["play", undefined])
+    return Promise.resolve()
+  }
+  pause() {
+    this.calls.push(["pause", undefined])
+    return Promise.resolve()
+  }
+  setCurrentTime(t: number) {
+    this.calls.push(["setCurrentTime", t])
+    return Promise.resolve(t)
+  }
+  getDuration() {
+    return Promise.resolve(this._duration)
+  }
+  getVolume() {
+    return Promise.resolve(1)
+  }
+  setVolume(v: number) {
+    this.calls.push(["setVolume", v])
+    return Promise.resolve(v)
+  }
+  getMuted() {
+    return Promise.resolve(this._muted)
+  }
+  setMuted(m: boolean) {
+    this.calls.push(["setMuted", m])
+    return Promise.resolve(m)
+  }
+  setPlaybackRate(r: number) {
+    this.calls.push(["setPlaybackRate", r])
+    return Promise.resolve(r)
+  }
+  getQualities() {
+    return Promise.resolve(this._qualities)
+  }
+  setQuality(id: string) {
+    this.calls.push(["setQuality", id])
+    return Promise.resolve(id)
+  }
+  getTextTracks() {
+    return Promise.resolve(this._textTracks)
+  }
+  enableTextTrack(language: string, kind?: string, showing?: boolean) {
+    this.calls.push(["enableTextTrack", [language, kind, showing]])
+    return Promise.resolve({ language, kind })
+  }
+  disableTextTrack() {
+    this.calls.push(["disableTextTrack", undefined])
+    return Promise.resolve()
+  }
+  requestPictureInPicture() {
+    this.calls.push(["requestPictureInPicture", undefined])
+    return Promise.resolve()
+  }
+  exitPictureInPicture() {
+    this.calls.push(["exitPictureInPicture", undefined])
+    return Promise.resolve()
+  }
+  loadVideo(idOrObj: unknown) {
+    this.calls.push(["loadVideo", idOrObj])
+    return Promise.resolve(idOrObj)
+  }
+  destroy() {
+    this.calls.push(["destroy", undefined])
+    return Promise.resolve()
+  }
+}
+
+export function installFakeVimeo() {
+  FakeVimeoPlayer.instances = []
+  ;(window as unknown as { Vimeo?: unknown }).Vimeo = { Player: FakeVimeoPlayer }
+}
+
+export function uninstallFakeVimeo() {
+  delete (window as unknown as { Vimeo?: unknown }).Vimeo
+  FakeVimeoPlayer.instances = []
+}
+
+// Flush pending microtasks (the provider's async reads at mount/loaded).
+export function flush() {
+  return new Promise<void>((r) => setTimeout(r, 0))
+}
+```
+
+- [ ] **Step 2: Write the failing lifecycle test**
+
+Append to `src/vimeo/provider.test.ts`:
+
+```ts
+import { afterEach, beforeEach } from "vitest"
+import { createVimeoProvider } from "./provider"
+import {
+  FakeVimeoPlayer,
+  installFakeVimeo,
+  uninstallFakeVimeo,
+  flush,
+} from "./fake-vimeo"
+
+const mount = (provider: ReturnType<typeof createVimeoProvider>) => {
+  const host = document.createElement("div")
+  document.body.appendChild(host)
+  provider.mount(host)
+  return host
+}
+
+describe("createVimeoProvider lifecycle", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("constructs a player with the numeric id for a public video", async () => {
+    const provider = createVimeoProvider({ videoId: "123456789" })
+    mount(provider)
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    expect(FakeVimeoPlayer.instances[0]!.opts.id).toBe("123456789")
+    expect(FakeVimeoPlayer.instances[0]!.opts.url).toBeUndefined()
+    expect(FakeVimeoPlayer.instances[0]!.opts.controls).toBe(false)
+    provider.destroy()
+  })
+
+  it("constructs with the ?h= url when a hash is present", async () => {
+    const provider = createVimeoProvider({
+      videoId: "123456789",
+      hash: "abc",
+    })
+    mount(provider)
+    await flush()
+    expect(FakeVimeoPlayer.instances[0]!.opts.url).toBe(
+      "https://player.vimeo.com/video/123456789?h=abc",
+    )
+    expect(FakeVimeoPlayer.instances[0]!.opts.id).toBeUndefined()
+    provider.destroy()
+  })
+
+  it("exposes default state before any event", () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    const s = provider.getState()
+    expect(s.paused).toBe(true)
+    expect(s.currentTime).toBe(0)
+    provider.destroy()
+  })
+
+  it("tears down the player on destroy", async () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    await flush()
+    const player = FakeVimeoPlayer.instances[0]!
+    provider.destroy()
+    expect(player.calls.map((c) => c[0])).toContain("destroy")
+  })
+
+  it("does not leave a live player if destroyed before the SDK loads", async () => {
+    // No window.Vimeo yet -> loader path. Capture the injected <script>.
+    uninstallFakeVimeo()
+    delete (window as unknown as { Vimeo?: unknown }).Vimeo
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    provider.destroy() // before the script "loads"
+    installFakeVimeo()
+    const script = document.querySelector(
+      'script[src="https://player.vimeo.com/api/player.js"]',
+    ) as HTMLScriptElement | null
+    script?.dispatchEvent(new Event("load"))
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(0)
+  })
+
+  it("notifies subscribers on state change", async () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    await flush()
+    let calls = 0
+    provider.subscribe(() => calls++)
+    FakeVimeoPlayer.instances[0]!.emit("play")
+    expect(calls).toBeGreaterThan(0)
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: FAIL — `createVimeoProvider` is not exported.
+
+- [ ] **Step 4: Implement the loader + lifecycle**
+
+Append to `src/vimeo/provider.ts` (above the helpers add the imports; the loader and factory go below them):
+
+```ts
+import { defaultState } from "../core/fake-provider"
+import type { MediaState, PlayerActions, Provider } from "../core/types"
+
+// Narrow structural view of the Vimeo Player SDK surface we touch. Hand-rolled
+// (like youtube's YTPlayer) so the provider needs no runtime dep or typings.
+type VimeoEventHandler = (data?: unknown) => void
+export type VimeoPlayer = {
+  on(event: string, handler: VimeoEventHandler): void
+  off(event: string, handler?: VimeoEventHandler): void
+  ready(): Promise<void>
+  play(): Promise<unknown>
+  pause(): Promise<unknown>
+  setCurrentTime(seconds: number): Promise<number>
+  getDuration(): Promise<number>
+  getVolume(): Promise<number>
+  setVolume(volume: number): Promise<number>
+  getMuted(): Promise<boolean>
+  setMuted(muted: boolean): Promise<boolean>
+  setPlaybackRate(rate: number): Promise<number>
+  getQualities(): Promise<Array<{ id: string; label: string; active: boolean }>>
+  setQuality(id: string): Promise<string>
+  getTextTracks(): Promise<
+    Array<{ label: string; language: string; kind: string; mode: string }>
+  >
+  enableTextTrack(
+    language: string,
+    kind?: string,
+    showing?: boolean,
+  ): Promise<unknown>
+  disableTextTrack(): Promise<unknown>
+  requestPictureInPicture(): Promise<unknown>
+  exitPictureInPicture(): Promise<unknown>
+  loadVideo(idOrOpts: number | string | { id?: number | string; url?: string }): Promise<unknown>
+  destroy(): Promise<unknown>
+}
+type VimeoNamespace = {
+  Player: new (el: HTMLElement, opts: Record<string, unknown>) => VimeoPlayer
+}
+type VimeoWindow = Window & typeof globalThis & { Vimeo?: VimeoNamespace }
+
+const SDK_SRC = "https://player.vimeo.com/api/player.js"
+
+// Lazily load player.js exactly once; resolve when window.Vimeo.Player exists.
+// There is no global ready callback (unlike YouTube), so we resolve on the
+// script's load event. An already-present window.Vimeo short-circuits.
+let apiPromise: Promise<VimeoNamespace> | null = null
+function loadVimeoAPI(): Promise<VimeoNamespace> {
+  const w = window as VimeoWindow
+  if (w.Vimeo?.Player) return Promise.resolve(w.Vimeo)
+  if (apiPromise) return apiPromise
+  apiPromise = new Promise<VimeoNamespace>((resolve, reject) => {
+    const finish = () => {
+      if (w.Vimeo?.Player) resolve(w.Vimeo)
+      else reject(new Error("Vimeo SDK loaded but window.Vimeo is missing"))
+    }
+    const existing = document.querySelector(`script[src="${SDK_SRC}"]`)
+    if (existing) {
+      existing.addEventListener("load", finish)
+      return
+    }
+    const script = document.createElement("script")
+    script.src = SDK_SRC
+    script.async = true
+    script.addEventListener("load", finish)
+    document.head.appendChild(script)
+  })
+  return apiPromise
+}
+
+function readyVimeo(): VimeoNamespace | null {
+  if (typeof window === "undefined") return null
+  const v = (window as VimeoWindow).Vimeo
+  return v && typeof v.Player === "function" ? v : null
+}
+
+export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
+  const explicit = parseVimeoSource(opts.videoId)
+  const initial = { id: explicit.id, hash: opts.hash ?? explicit.hash }
+  let player: VimeoPlayer | null = null
+  let destroyed = false
+  let ready = false
+  let desiredRate = opts.defaultRate ?? 1
+
+  let state: MediaState = {
+    ...defaultState(),
+    rate: desiredRate,
+    muted: opts.muted ?? false,
+    capabilities: {
+      canSetRate: true, // best-effort: setPlaybackRate is plan-gated, can't probe
+      hasStoryboard: false,
+      canPiP: !!(
+        typeof document !== "undefined" && document.pictureInPictureEnabled
+      ),
+      canFullscreen: true,
+      // Flip on at `loaded` once getQualities/getTextTracks return non-empty.
+      canSetQuality: false,
+      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 })
+
+  // Stub actions; later tasks replace this object's bodies.
+  const actions: PlayerActions = {
+    play: () => {},
+    pause: () => {},
+    seek: () => {},
+    setRate: () => {},
+    setVolume: () => {},
+    setMuted: () => {},
+    setQuality: () => {},
+    setTextTrack: () => {},
+    enterFullscreen: () => {},
+    exitFullscreen: () => {},
+    enterPiP: () => {},
+    exitPiP: () => {},
+  }
+
+  const createPlayer = (v: VimeoNamespace, host: HTMLElement) => {
+    const ctorOpts: Record<string, unknown> = {
+      controls: false, // kino owns the chrome (paid-plan feature)
+      autoplay: !!opts.autoPlay,
+      muted: !!opts.muted,
+      loop: !!opts.loop,
+      playsinline: true,
+      dnt: true,
+      keyboard: false,
+    }
+    if (initial.hash) ctorOpts.url = playerUrl(initial.id, initial.hash)
+    else ctorOpts.id = initial.id
+    const p = new v.Player(host, ctorOpts)
+    player = p
+    void p.ready().then(() => {
+      if (destroyed) return
+      ready = true
+    })
+  }
+
+  return {
+    mount(container) {
+      const host = document.createElement("div")
+      container.appendChild(host)
+      document.addEventListener("fullscreenchange", onFullscreenChange)
+      const v = readyVimeo()
+      if (v) {
+        createPlayer(v, host)
+      } else {
+        void loadVimeoAPI().then((loaded) => {
+          if (destroyed) return
+          if (host.isConnected) createPlayer(loaded, host)
+        })
+      }
+    },
+    getState: () => state,
+    subscribe: (l) => {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    actions,
+    destroy() {
+      destroyed = true
+      ready = false
+      document.removeEventListener("fullscreenchange", onFullscreenChange)
+      try {
+        void player?.destroy()
+      } catch {
+        /* already gone */
+      }
+      player = null
+      listeners.clear()
+    },
+  }
+}
+```
+
+Note: the `emit`/`patch`/`subscribe` plumbing is referenced by the "notifies subscribers" test indirectly — Task 3 wires the events that call `patch`. For this task, add a temporary `play` listener so that test passes: inside `createPlayer`, after `player = p`, add `p.on("play", () => patch({ paused: false, ended: false }))`. Task 3 expands the handler set.
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS (all lifecycle + parser tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/fake-vimeo.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): SDK loader, player lifecycle, test fake"
+```
+
+---
+
+## Task 3: Event-driven state sync
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: the `createPlayer` / `patch` from Task 2.
+- Produces: a `bindEvents(p: VimeoPlayer)` step inside `createPlayer` registering all playback events. No new exports.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append a `describe("state sync")` block to `provider.test.ts`. Helper to mount+ready+get the player:
+
+```ts
+const ready = async (o: Parameters<typeof createVimeoProvider>[0]) => {
+  const provider = createVimeoProvider(o)
+  mount(provider)
+  await flush()
+  return { provider, player: FakeVimeoPlayer.instances.at(-1)! }
+}
+
+describe("state sync", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("play/pause/ended set paused + ended", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("play")
+    expect(provider.getState().paused).toBe(false)
+    player.emit("pause")
+    expect(provider.getState().paused).toBe(true)
+    player.emit("ended")
+    expect(provider.getState().ended).toBe(true)
+    provider.destroy()
+  })
+
+  it("bufferstart keeps paused false (no poster flash)", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("play")
+    player.emit("bufferstart")
+    expect(provider.getState().paused).toBe(false)
+    provider.destroy()
+  })
+
+  it("timeupdate updates currentTime + duration", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 12, duration: 100, percent: 0.12 })
+    expect(provider.getState().currentTime).toBe(12)
+    expect(provider.getState().duration).toBe(100)
+    provider.destroy()
+  })
+
+  it("progress maps to buffered ranges", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 0, duration: 200, percent: 0 })
+    player.emit("progress", { seconds: 0, duration: 200, percent: 0.5 })
+    expect(provider.getState().buffered).toEqual([[0, 100]])
+    provider.destroy()
+  })
+
+  it("volumechange reads volume AND muted", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("volumechange", { volume: 0.3, muted: true })
+    expect(provider.getState().volume).toBe(0.3)
+    expect(provider.getState().muted).toBe(true)
+    provider.destroy()
+  })
+
+  it("error folds name into the message with code 0", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("error", { name: "PrivacyError", message: "not allowed" })
+    expect(provider.getState().error).toEqual({
+      code: 0,
+      message: "PrivacyError: not allowed",
+    })
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts -t "state sync"`
+Expected: FAIL — e.g. `timeupdate` does not update state yet.
+
+- [ ] **Step 3: Implement event binding**
+
+In `provider.ts`, replace the temporary single `p.on("play", ...)` line in `createPlayer` with a `bindEvents(p)` call, and add the function inside `createVimeoProvider` (so it closes over `patch`/`state`/`desiredRate`):
+
+```ts
+  const bindEvents = (p: VimeoPlayer) => {
+    p.on("play", () => patch({ paused: false, ended: false }))
+    p.on("pause", () => patch({ paused: true }))
+    p.on("ended", () => patch({ paused: true, ended: true }))
+    p.on("bufferstart", () => patch({ paused: false }))
+    p.on("bufferend", () => {})
+    p.on("timeupdate", (d) => {
+      const e = d as { seconds: number; duration: number }
+      patch({
+        currentTime: e.seconds ?? 0,
+        duration: e.duration ?? state.duration,
+        seeking: false,
+        readyState: 4,
+      })
+    })
+    p.on("progress", (d) => {
+      const e = d as { duration: number; percent: number }
+      const duration = e.duration ?? state.duration
+      patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] })
+    })
+    p.on("seeking", () => patch({ seeking: true }))
+    p.on("seeked", (d) => {
+      const e = d as { seconds?: number }
+      patch({ seeking: false, ended: false, currentTime: e?.seconds ?? state.currentTime })
+    })
+    p.on("volumechange", (d) => {
+      const e = d as { volume: number; muted?: boolean }
+      patch({ volume: e.volume, muted: e.muted ?? state.muted })
+    })
+    p.on("playbackratechange", (d) => {
+      const e = d as { playbackRate: number }
+      desiredRate = e.playbackRate
+      patch({ rate: e.playbackRate })
+    })
+    p.on("fullscreenchange", (d) => {
+      const e = d as { fullscreen: boolean }
+      patch({ fullscreen: !!e.fullscreen })
+    })
+    p.on("enterpictureinpicture", () => patch({ pip: true }))
+    p.on("leavepictureinpicture", () => patch({ pip: false }))
+    p.on("error", (d) => {
+      const e = d as { name?: string; message?: string }
+      const message = e.name ? `${e.name}: ${e.message ?? ""}`.trim() : (e.message ?? "Vimeo playback error")
+      patch({ error: { code: 0, message } })
+    })
+  }
+```
+
+Call `bindEvents(p)` in `createPlayer` right after `player = p`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS (lifecycle + state sync).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): event-driven state sync"
+```
+
+---
+
+## Task 4: `loaded` handler — duration, qualities, tracks, capabilities
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: Task 2/3 internals.
+- Produces: an async `onLoaded()` bound to the `loaded` event; sets duration, `qualities`/`activeQualityId`, `textTracks`, capability flips, re-asserts rate/mute, and media-session title. A `mapQualities(raw)` and `mapTracks(raw)` helper.
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+describe("loaded handler", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("reads duration and flips no capabilities when lists are empty", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._duration = 90
+    player.emit("loaded")
+    await flush()
+    expect(provider.getState().duration).toBe(90)
+    expect(provider.getState().capabilities.canSetQuality).toBe(false)
+    expect(provider.getState().capabilities.hasTextTracks).toBe(false)
+    provider.destroy()
+  })
+
+  it("maps qualities with height parsed from id, not label", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._qualities = [
+      { id: "auto", label: "Auto", active: true },
+      { id: "2160p", label: "4K", active: false },
+      { id: "1080p", label: "1080p", active: false },
+    ]
+    player.emit("loaded")
+    await flush()
+    const s = provider.getState()
+    expect(s.capabilities.canSetQuality).toBe(true)
+    expect(s.activeQualityId).toBe("auto")
+    const uhd = s.qualities.find((q) => q.id === "2160p")!
+    expect(uhd.height).toBe(2160) // NOT 4 from "4K"
+    provider.destroy()
+  })
+
+  it("maps text tracks with synthesized ids and flips hasTextTracks", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._textTracks = [
+      { label: "English", language: "en", kind: "captions", mode: "disabled" },
+      { label: "English", language: "en", kind: "subtitles", mode: "disabled" },
+    ]
+    player.emit("loaded")
+    await flush()
+    const s = provider.getState()
+    expect(s.capabilities.hasTextTracks).toBe(true)
+    expect(s.textTracks.map((t) => t.id)).toEqual(["en.captions", "en.subtitles"])
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts -t "loaded handler"`
+Expected: FAIL — duration unchanged / qualities empty.
+
+- [ ] **Step 3: Implement**
+
+Add helpers near the bottom of `provider.ts` (module scope):
+
+```ts
+import type { QualityLevel, TextTrackInfo } from "../core/types"
+
+function mapQualities(
+  raw: Array<{ id: string; label: string; active: boolean }>,
+): { qualities: QualityLevel[]; activeId: string } {
+  const qualities = raw.map((q) => ({
+    id: q.id,
+    height: parseInt(q.id, 10) || 0, // id is "2160p"; label "4K" would parse to 4
+    bitrate: 0, // Vimeo exposes no bitrate
+    selected: q.active,
+  }))
+  const active = raw.find((q) => q.active)?.id ?? "auto"
+  return { qualities, activeId: active }
+}
+
+// getTextTracks() objects have no id; synthesize a stable one. Disambiguate
+// same-language/same-kind duplicates with an index suffix.
+function mapTracks(
+  raw: Array<{ label: string; language: string; kind: string; mode: string }>,
+): TextTrackInfo[] {
+  const seen = new Map<string, number>()
+  return raw.map((t) => {
+    const base = `${t.language}.${t.kind}`
+    const n = seen.get(base) ?? 0
+    seen.set(base, n + 1)
+    const id = n === 0 ? base : `${base}.${n}`
+    return {
+      id,
+      kind: t.kind,
+      label: t.label || t.language,
+      lang: t.language,
+      mode: t.mode === "showing" ? "showing" : "disabled",
+    }
+  })
+}
+```
+
+Add the media-session helper (copy from youtube's `setSessionMetadata`) and an `onLoaded` inside `createVimeoProvider`, bound in `bindEvents`:
+
+```ts
+  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 onLoaded = async () => {
+    if (!player) return
+    const p = player
+    const [duration, rawQualities, rawTracks, muted] = await Promise.all([
+      p.getDuration().catch(() => 0),
+      p.getQualities().catch(() => []),
+      p.getTextTracks().catch(() => []),
+      p.getMuted().catch(() => false),
+    ])
+    if (destroyed) return
+    void p.setPlaybackRate(desiredRate).catch(() => {})
+    const { qualities, activeId } = mapQualities(rawQualities)
+    const tracks = mapTracks(rawTracks)
+    setSessionMetadata(opts.metadata?.videoTitle ?? "Video")
+    patch({
+      duration: duration || state.duration,
+      readyState: 4,
+      muted,
+      qualities,
+      activeQualityId: activeId,
+      textTracks: tracks,
+      capabilities: {
+        ...state.capabilities,
+        canSetQuality: qualities.length > 0,
+        hasTextTracks: tracks.length > 0,
+      },
+    })
+  }
+```
+
+Bind in `bindEvents`: `p.on("loaded", () => void onLoaded())`. Also add `p.on("qualitychange", (d) => patch({ activeQualityId: (d as { quality: string }).quality }))`.
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): loaded handler — duration, qualities, tracks, capabilities"
+```
+
+---
+
+## Task 5: Actions
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: `player`, `ready`, `desiredRate`, `patch`.
+- Produces: the fully-implemented `actions` object (replaces the Task 2 stub bodies). Captions action (`setTextTrack`) is stubbed here and completed in Task 6.
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+describe("actions", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+  const names = (p: FakeVimeoPlayer) => p.calls.map((c) => c[0])
+
+  it("play/pause/seek call the SDK; seek patches seeking immediately", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.play()
+    provider.actions.pause()
+    provider.actions.seek(42)
+    expect(names(player)).toEqual(["play", "pause", "setCurrentTime"])
+    expect(player.calls.find((c) => c[0] === "setCurrentTime")![1]).toBe(42)
+    expect(provider.getState().seeking).toBe(true)
+    provider.destroy()
+  })
+
+  it("setVolume passes 0..1 unscaled", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setVolume(0.4)
+    expect(player.calls).toContainEqual(["setVolume", 0.4])
+    provider.destroy()
+  })
+
+  it("setRate does NOT patch rate optimistically (waits for the event)", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setRate(2)
+    expect(player.calls).toContainEqual(["setPlaybackRate", 2])
+    expect(provider.getState().rate).toBe(1) // unchanged until the echo event
+    player.emit("playbackratechange", { playbackRate: 2 })
+    expect(provider.getState().rate).toBe(2)
+    provider.destroy()
+  })
+
+  it("setQuality + PiP call the SDK", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setQuality("1080p")
+    provider.actions.enterPiP()
+    provider.actions.exitPiP()
+    expect(names(player)).toEqual([
+      "setQuality",
+      "requestPictureInPicture",
+      "exitPictureInPicture",
+    ])
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts -t "actions"`
+Expected: FAIL — stub actions record nothing.
+
+- [ ] **Step 3: Implement**
+
+Replace the stub `actions` object body in `createVimeoProvider`:
+
+```ts
+  const actions: PlayerActions = {
+    play: () => void player?.play().catch(() => {}),
+    pause: () => void player?.pause().catch(() => {}),
+    seek: (t) => {
+      patch({ seeking: true })
+      void player?.setCurrentTime(t).catch(() => {})
+    },
+    setRate: (r) => {
+      desiredRate = r
+      // No optimistic patch — rate moves on the playbackratechange echo, so a
+      // plan-gated rejection never leaves the UI showing a rate that didn't take.
+      void player?.setPlaybackRate(r).catch(() => {})
+    },
+    setVolume: (v) => void player?.setVolume(v).catch(() => {}),
+    setMuted: (m) => void player?.setMuted(m).catch(() => {}),
+    setQuality: (id) => void player?.setQuality(id).catch(() => {}),
+    setTextTrack: () => {}, // Task 6
+    enterFullscreen: (wrapper) => {
+      if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
+    },
+    exitFullscreen: () => {
+      if (document.fullscreenElement) void document.exitFullscreen?.()
+    },
+    enterPiP: () => void player?.requestPictureInPicture().catch(() => {}),
+    exitPiP: () => void player?.exitPictureInPicture().catch(() => {}),
+  }
+```
+
+(`actions` is referenced by the returned object; defining it before the `return` is fine since the return already references `actions`.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): player actions"
+```
+
+---
+
+## Task 6: Captions — cue rendering + track selection
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: `mapTracks` ids (Task 4), `player`, `patch`, `state`.
+- Produces: real `setTextTrack` + `cuechange`/`texttrackchange` handling. A `trackRef(id)` lookup that resolves a synthesized id back to `{ language, kind }`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+describe("captions", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  const withTracks = async () => {
+    const r = await ready({ videoId: "1" })
+    r.player._textTracks = [
+      { label: "English", language: "en", kind: "captions", mode: "disabled" },
+      { label: "Français", language: "fr", kind: "subtitles", mode: "disabled" },
+    ]
+    r.player.emit("loaded")
+    await flush()
+    return r
+  }
+
+  it("setTextTrack(id) enables the track with showing:false", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("fr.subtitles")
+    expect(player.calls).toContainEqual([
+      "enableTextTrack",
+      ["fr", "subtitles", false],
+    ])
+    expect(provider.getState().activeTextTrackId).toBe("fr.subtitles")
+    provider.destroy()
+  })
+
+  it("setTextTrack(null) disables and clears the cue", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("en.captions")
+    provider.actions.setTextTrack(null)
+    expect(player.calls.map((c) => c[0])).toContain("disableTextTrack")
+    expect(provider.getState().activeTextTrackId).toBe(null)
+    expect(provider.getState().activeCueText).toBe("")
+    provider.destroy()
+  })
+
+  it("cuechange renders the cue text in the overlay", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("en.captions")
+    player.emit("cuechange", { cues: [{ text: "Hello there" }] })
+    expect(provider.getState().activeCueText).toBe("Hello there")
+    player.emit("cuechange", { cues: [] })
+    expect(provider.getState().activeCueText).toBe("")
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts -t "captions"`
+Expected: FAIL — `setTextTrack` is a no-op.
+
+- [ ] **Step 3: Implement**
+
+Replace `setTextTrack: () => {}` in `actions`:
+
+```ts
+    setTextTrack: (id) => {
+      if (id == null) {
+        patch({ activeTextTrackId: null, activeCueText: "" })
+        void player?.disableTextTrack().catch(() => {})
+        return
+      }
+      const ref = state.textTracks.find((t) => t.id === id)
+      patch({ activeTextTrackId: id })
+      if (ref) void player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {})
+    },
+```
+
+Add to `bindEvents`:
+
+```ts
+    p.on("cuechange", (d) => {
+      const e = d as { cues?: Array<{ text?: string }> }
+      patch({ activeCueText: e.cues?.[0]?.text ?? "" })
+    })
+    p.on("texttrackchange", (d) => {
+      const e = d as { language: string | null; kind: string | null }
+      if (e.language == null) {
+        patch({ activeTextTrackId: null, activeCueText: "" })
+        return
+      }
+      const match = state.textTracks.find(
+        (t) => t.lang === e.language && t.kind === e.kind,
+      )
+      patch({ activeTextTrackId: match?.id ?? state.activeTextTrackId })
+    })
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): captions — overlay cues + track selection"
+```
+
+---
+
+## Task 7: `swapSource` + the hash channel
+
+**Files:**
+- Modify: `src/vimeo/provider.ts`
+- Test: `src/vimeo/provider.test.ts`
+
+**Interfaces:**
+- Consumes: `parseVimeoSource`, `playerUrl`, `player`, `ready`, `desiredRate`, `patch`.
+- Produces: the optional `swapSource(opts: SourceOptions)` method on the returned provider. It reads the packed `src` string (bare id, or a `?h=` URL when unlisted).
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+describe("swapSource", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("loads a public id and resets progress + rate", async () => {
+    const { provider, player } = await ready({ videoId: "1", defaultRate: 1.5 })
+    player.emit("timeupdate", { seconds: 30, duration: 60, percent: 0.5 })
+    provider.swapSource!({ src: "987654321" })
+    expect(player.calls).toContainEqual(["loadVideo", 987654321])
+    expect(player.calls).toContainEqual(["setPlaybackRate", 1.5])
+    expect(provider.getState().currentTime).toBe(0)
+    expect(provider.getState().ended).toBe(false)
+    provider.destroy()
+  })
+
+  it("loads an unlisted source by url when src carries a hash", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.swapSource!({
+      src: "https://player.vimeo.com/video/987654321?h=newhash",
+    })
+    expect(player.calls).toContainEqual([
+      "loadVideo",
+      { url: "https://player.vimeo.com/video/987654321?h=newhash" },
+    ])
+    provider.destroy()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts -t "swapSource"`
+Expected: FAIL — `provider.swapSource` is undefined.
+
+- [ ] **Step 3: Implement**
+
+Add `swapSource` to the returned object (after `subscribe`), and import `SourceOptions`:
+
+```ts
+import type { SourceOptions } from "../core/types"
+```
+
+```ts
+    swapSource(next: SourceOptions) {
+      if (!player || next.src == null) return
+      const { id, hash } = parseVimeoSource(next.src)
+      void player
+        .loadVideo(hash ? { url: playerUrl(id, hash) } : Number(id))
+        .then(() => void player?.setPlaybackRate(desiredRate).catch(() => {}))
+        .catch(() => {})
+      if (next.metadata?.videoTitle != null)
+        setSessionMetadata(next.metadata.videoTitle)
+      patch({
+        currentTime: 0,
+        duration: 0,
+        ended: false,
+        seeking: false,
+        error: null,
+      })
+    },
+```
+
+Note: `Number(id)` is passed for the public case so `loadVideo` receives a numeric id (Vimeo accepts number | string | object).
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/provider.test.ts`
+Expected: PASS (whole file).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vimeo/provider.ts src/vimeo/provider.test.ts
+git commit -m "feat(vimeo): swapSource with hash channel"
+```
+
+---
+
+## Task 8: `<VimeoPlayer>` React wrapper + entry re-export
+
+**Files:**
+- Create: `src/vimeo/vimeo-player.tsx`
+- Create: `src/vimeo.ts`
+- Test: `src/vimeo/vimeo-player.test.tsx`
+
+**Interfaces:**
+- Consumes: `createVimeoProvider`, `VimeoProviderOptions`, `parseVimeoSource`, `playerUrl`.
+- Produces: `function VimeoPlayer(props): JSX.Element`, `type VimeoPlayerProps`. `src/vimeo.ts` re-exports everything public.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/vimeo/vimeo-player.test.tsx`:
+
+```tsx
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { render, cleanup } from "@testing-library/react"
+import { VimeoPlayer } from "./vimeo-player"
+import {
+  FakeVimeoPlayer,
+  installFakeVimeo,
+  uninstallFakeVimeo,
+  flush,
+} from "./fake-vimeo"
+
+describe("<VimeoPlayer>", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => {
+    cleanup()
+    uninstallFakeVimeo()
+  })
+
+  it("creates exactly one player and swaps on videoId change", async () => {
+    const view = render(<VimeoPlayer videoId="111" />)
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    view.rerender(<VimeoPlayer videoId="222" />)
+    await flush()
+    // Still one player; the new source flows through loadVideo, not a remount.
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    expect(
+      FakeVimeoPlayer.instances[0]!.calls.find((c) => c[0] === "loadVideo")![1],
+    ).toBe(222)
+  })
+
+  it("swaps to a ?h= url when hash changes", async () => {
+    const view = render(<VimeoPlayer videoId="111" />)
+    await flush()
+    view.rerender(<VimeoPlayer videoId="111" hash="secret" />)
+    await flush()
+    expect(
+      FakeVimeoPlayer.instances[0]!.calls.find((c) => c[0] === "loadVideo")![1],
+    ).toEqual({ url: "https://player.vimeo.com/video/111?h=secret" })
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm vitest run src/vimeo/vimeo-player.test.tsx`
+Expected: FAIL — cannot resolve `./vimeo-player`.
+
+- [ ] **Step 3: Implement the component**
+
+Create `src/vimeo/vimeo-player.tsx` (mirror `youtube-player.tsx`, threading `hash`):
+
+```tsx
+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 {
+  createVimeoProvider,
+  parseVimeoSource,
+  playerUrl,
+  type VimeoProviderOptions,
+} from "./provider"
+import type { Provider } from "../core/types"
+
+export type VimeoPlayerProps = VimeoProviderOptions & {
+  accentColor?: string
+  theme?: Record<string, string>
+  className?: string
+  /** Blur-up still painted behind the video until the first frame loads. */
+  placeholder?: string
+  children?: ReactNode
+}
+
+// Pack id + optional hash into the single `src` string swapSource consumes.
+const packSrc = (videoId: string, hash?: string) => {
+  const parsed = parseVimeoSource(videoId)
+  const h = hash ?? parsed.hash
+  return h ? playerUrl(parsed.id, h) : parsed.id
+}
+
+/**
+ * kino's glass chrome over a Vimeo video, backed by the Vimeo Player SDK. Pass a
+ * numeric id or any vimeo.com / player.vimeo.com URL; for unlisted videos pass
+ * the `hash` (or a share URL that already contains it).
+ *
+ * Only `videoId`, `hash`, and `metadata.videoTitle` are reactive (they flow
+ * through `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read
+ * once at creation — remount (e.g. via `key`) to change them.
+ *
+ * Chromeless playback (kino owning the controls) requires a **paid** Vimeo plan;
+ * on a free-account video Vimeo renders its own controls under kino's overlay.
+ *
+ * Per Vimeo's embed terms, kino does not obscure the player — no poster-on-pause
+ * cover over the embed; kino's controls sit alongside Vimeo's surface.
+ */
+export function VimeoPlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: VimeoPlayerProps) {
+  const providerRef = useRef<Provider | null>(null)
+  if (providerRef.current === null) {
+    providerRef.current = createVimeoProvider(opts)
+  }
+  const provider = providerRef.current
+
+  const mountedRef = useRef(false)
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true
+      return
+    }
+    provider.swapSource?.({
+      src: packSrc(opts.videoId, opts.hash),
+      metadata: opts.metadata,
+    })
+  }, [opts.videoId, opts.hash, opts.metadata?.videoTitle])
+
+  return (
+    <Player
+      provider={provider}
+      accentColor={accentColor}
+      theme={theme}
+      className={className}
+      placeholder={placeholder}
+    >
+      <IdleOverlay />
+      <Captions />
+      <ControlBar />
+      {children}
+    </Player>
+  )
+}
+```
+
+- [ ] **Step 4: Create the entry re-export**
+
+Create `src/vimeo.ts`:
+
+```ts
+export {
+  createVimeoProvider,
+  parseVimeoSource,
+  playerUrl,
+  type VimeoProviderOptions,
+} from "./vimeo/provider"
+export { VimeoPlayer, type VimeoPlayerProps } from "./vimeo/vimeo-player"
+```
+
+- [ ] **Step 5: Run to verify it passes**
+
+Run: `pnpm vitest run src/vimeo/vimeo-player.test.tsx`
+Expected: PASS (2 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/vimeo/vimeo-player.tsx src/vimeo.ts src/vimeo/vimeo-player.test.tsx
+git commit -m "feat(vimeo): VimeoPlayer React wrapper + entry"
+```
+
+---
+
+## Task 9: Build wiring
+
+**Files:**
+- Modify: `package.json` (`exports`, `keywords`)
+- Modify: `tsdown.config.ts` (`entry.vimeo`)
+
+**Interfaces:**
+- Consumes: `src/vimeo.ts` (Task 8).
+- Produces: published `@karnstack/kino/vimeo` entry.
+
+- [ ] **Step 1: Add the export map entry**
+
+In `package.json`, add under `exports` after the `./youtube` block:
+
+```json
+    "./vimeo": {
+      "types": "./dist/vimeo.d.ts",
+      "import": "./dist/vimeo.js"
+    },
+```
+
+And add `"vimeo"` to `keywords` (after `"youtube"`).
+
+- [ ] **Step 2: Add the tsdown entry**
+
+In `tsdown.config.ts`, add to `entry`:
+
+```ts
+    vimeo: "src/vimeo.ts",
+```
+
+- [ ] **Step 3: Verify the build, types, lint, and tests all pass**
+
+Run:
+```bash
+pnpm build && pnpm typecheck && pnpm lint && pnpm test
+```
+Expected: `dist/vimeo.js` and `dist/vimeo.d.ts` emitted; typecheck clean; lint clean; all tests PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add package.json tsdown.config.ts
+git commit -m "build(vimeo): wire ./vimeo entry point"
+```
+
+---
+
+## Task 10: Docs, demo, changeset
+
+**Files:**
+- Modify: `README.md`, `demo/pages/providers.tsx`, `demo/pages/install.tsx`, `demo/pages/overview.tsx`, `demo/player-studio.tsx`
+- Create: `.changeset/vimeo-provider.md`
+
+**Interfaces:**
+- Consumes: the shipped provider + `<VimeoPlayer>`.
+- Produces: docs/demo that advertise four shipped providers.
+
+- [ ] **Step 1: Flip the demo provider card**
+
+In `demo/pages/providers.tsx`, change the Vimeo entry to shipped:
+
+```ts
+  {
+    name: "Vimeo",
+    status: "shipped",
+    entry: "@karnstack/kino/vimeo",
+    detail:
+      "The Vimeo Player SDK under the same kino chrome — quality, styled captions, picture-in-picture, and rate. Chromeless playback needs a paid Vimeo plan.",
+    importLine: 'import { VimeoPlayer } from "@karnstack/kino/vimeo"',
+  },
+```
+
+- [ ] **Step 2: README — add Vimeo usage + drop from roadmap**
+
+Add a "Playing a Vimeo video" section near the YouTube one:
+
+````markdown
+### Playing a Vimeo video
+
+```tsx
+import { VimeoPlayer } from "@karnstack/kino/vimeo"
+import "@karnstack/kino/styles.css"
+
+export default function Watch() {
+  return <VimeoPlayer videoId="76979871" accentColor="#00adef" />
+}
+```
+
+For an unlisted video, pass the hash (or a share URL that contains it):
+
+```tsx
+<VimeoPlayer videoId="123456789" hash="abcdef0123" />
+```
+
+Chromeless playback (kino owning the controls) requires a paid Vimeo plan.
+````
+
+Remove "Vimeo" from the roadmap/planned list and add it to the shipped-providers list/entry-points table.
+
+- [ ] **Step 3: install.tsx + overview.tsx + player-studio.tsx**
+
+- `demo/pages/install.tsx`: add a Vimeo import snippet and a `VimeoPlayer` props table mirroring the YouTube entry (props: `videoId`, `hash`, `metadata`, `autoPlay`, `muted`, `loop`, `defaultRate`, plus the shared `accentColor/theme/className/placeholder`).
+- `demo/pages/overview.tsx`: update the highlight copy to state Vimeo now ships (match the existing sentence pattern that lists providers).
+- `demo/player-studio.tsx`: add a "Vimeo" provider tab rendering `<VimeoPlayer videoId="76979871" />` (a public, chromeless-eligible Vimeo staff-pick id), mirroring the YouTube tab wiring.
+
+(Read each file first and follow its existing data-shape; these are copy/data additions, not new patterns.)
+
+- [ ] **Step 4: Add the changeset**
+
+Create `.changeset/vimeo-provider.md`:
+
+```markdown
+---
+"@karnstack/kino": minor
+---
+
+Add a Vimeo provider (`@karnstack/kino/vimeo`) — the Vimeo Player SDK under
+kino's chrome with quality selection, styled captions, picture-in-picture, and
+playback rate. Supports unlisted videos via a `hash`. Import `VimeoPlayer` or
+the lower-level `createVimeoProvider`.
+```
+
+- [ ] **Step 5: Verify the demo builds + full check**
+
+Run:
+```bash
+pnpm build && pnpm typecheck && pnpm lint && pnpm test
+```
+Expected: all clean/PASS. (Optionally `pnpm dev` and eyeball the Vimeo studio tab per the headless-screenshot workflow.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add README.md demo/ .changeset/vimeo-provider.md
+git commit -m "docs(vimeo): README, demo, changeset"
+```
+
+---
+
+## Final: open the PR
+
+- [ ] Push the branch and open the PR (only when the user asks):
+
+```bash
+git push -u origin feat/vimeo-provider
+gh pr create --base main --title "feat: Vimeo provider" --body "<summary + test plan>"
+```
+
+---
+
+## Self-Review Notes (plan author)
+
+- **Spec coverage:** loader/lifecycle (T2), event sync incl. bufferstart/volumechange.muted/error.name (T3), loaded+quality height-from-id+synthesized track ids+capability flips (T4), actions with no-optimistic-rate (T5), captions overlay via cuechange + enableTextTrack(…,false) (T6), hash channel through swapSource (T7), `<VimeoPlayer>` reactive machinery incl. `hash` dep (T8), wiring + keywords (T9), docs/demo/changeset + paid-plan caveat (T10). All spec sections map to a task.
+- **Plan-gated capabilities:** `canSetQuality`/`hasTextTracks` start false and flip at `loaded`; `canSetRate` documented best-effort; rate state event-driven (T5 test asserts no optimistic patch).
+- **Type consistency:** `QualityLevel{id,height,bitrate,selected}`, `TextTrackInfo{id,kind,label,lang,mode}`, `MediaError{code,message}` used consistently; `mapQualities`/`mapTracks`/`parseVimeoSource`/`playerUrl`/`packSrc` names stable across tasks.
+- **No placeholders:** every code step shows complete code; commands have expected output.

From fed53d24979e5db9e7fc1e493cf17b8a5e670425 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:25:40 +0530
Subject: [PATCH 03/21] feat(vimeo): source parsing + embed-url helper

---
 src/vimeo/provider.test.ts | 35 +++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 src/vimeo/provider.test.ts
 create mode 100644 src/vimeo/provider.ts

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
new file mode 100644
index 0000000..bcfd2dc
--- /dev/null
+++ b/src/vimeo/provider.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest"
+import { parseVimeoSource, playerUrl } from "./provider"
+
+describe("parseVimeoSource", () => {
+  it("passes a bare numeric id through", () => {
+    expect(parseVimeoSource("123456789")).toEqual({ id: "123456789" })
+  })
+  it("extracts id from a vimeo.com URL", () => {
+    expect(parseVimeoSource("https://vimeo.com/123456789")).toEqual({
+      id: "123456789",
+    })
+  })
+  it("extracts id + hash from an unlisted share URL", () => {
+    expect(parseVimeoSource("https://vimeo.com/123456789/abcdef0123")).toEqual({
+      id: "123456789",
+      hash: "abcdef0123",
+    })
+  })
+  it("extracts id + hash from a player.vimeo.com ?h= URL", () => {
+    expect(
+      parseVimeoSource("https://player.vimeo.com/video/123456789?h=xyz789"),
+    ).toEqual({ id: "123456789", hash: "xyz789" })
+  })
+  it("returns input unchanged as id when no number is found", () => {
+    expect(parseVimeoSource("not-a-vimeo")).toEqual({ id: "not-a-vimeo" })
+  })
+})
+
+describe("playerUrl", () => {
+  it("builds the documented ?h= embed URL", () => {
+    expect(playerUrl("123456789", "abc")).toBe(
+      "https://player.vimeo.com/video/123456789?h=abc",
+    )
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
new file mode 100644
index 0000000..1b8eaa1
--- /dev/null
+++ b/src/vimeo/provider.ts
@@ -0,0 +1,36 @@
+export type VimeoProviderOptions = {
+  // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
+  // parseVimeoSource resolves it.
+  videoId: string
+  // Unlisted/private hash. Also parsed from the URL form; an explicit hash here
+  // wins over a URL-derived one.
+  hash?: string
+  metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }
+  autoPlay?: boolean
+  muted?: boolean
+  loop?: boolean
+  defaultRate?: number
+}
+
+// Pull the numeric id (and optional unlisted hash) out of any common Vimeo
+// reference. A bare id is returned unchanged so callers can pass either.
+//   vimeo.com/123                -> { id: "123" }
+//   vimeo.com/123/HASH           -> { id: "123", hash: "HASH" }
+//   player.vimeo.com/video/123?h=HASH -> { id: "123", hash: "HASH" }
+export function parseVimeoSource(input: string): { id: string; hash?: string } {
+  const trimmed = input.trim()
+  // ?h= query form (player.vimeo.com embeds).
+  const q = trimmed.match(/[?&]h=([\w]+)/)
+  // /ID or /ID/HASH path form (vimeo.com share links). The id is the first
+  // numeric path segment; the hash is the next path segment if present.
+  const path = trimmed.match(/(?:^|\/)(\d+)(?:\/([\w]+))?/)
+  if (!path) return { id: trimmed }
+  const id = path[1]!
+  const hash = q?.[1] ?? path[2]
+  return hash ? { id, hash } : { id }
+}
+
+// The documented SDK embed URL that carries an unlisted hash.
+export function playerUrl(id: string, hash: string): string {
+  return `https://player.vimeo.com/video/${id}?h=${hash}`
+}

From 07f5642a7f67ed01ad9376c5db826c5355af0e16 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:37:40 +0530
Subject: [PATCH 04/21] feat(vimeo): SDK loader, player lifecycle, test fake

---
 src/vimeo/fake-vimeo.ts    | 126 ++++++++++++++++++++++++++
 src/vimeo/provider.test.ts |  91 ++++++++++++++++++-
 src/vimeo/provider.ts      | 179 +++++++++++++++++++++++++++++++++++++
 3 files changed, 394 insertions(+), 2 deletions(-)
 create mode 100644 src/vimeo/fake-vimeo.ts

diff --git a/src/vimeo/fake-vimeo.ts b/src/vimeo/fake-vimeo.ts
new file mode 100644
index 0000000..96b30e1
--- /dev/null
+++ b/src/vimeo/fake-vimeo.ts
@@ -0,0 +1,126 @@
+// Test-only stand-in for the Vimeo Player SDK. jsdom has no SDK, so tests
+// install this on window.Vimeo. Methods record their calls and return resolved
+// promises; tests drive state by calling emit(event, payload). Imported ONLY by
+// the vitest specs, so it never enters a tsdown build-entry graph.
+type Handler = (data?: unknown) => void
+
+export class FakeVimeoPlayer {
+  static instances: FakeVimeoPlayer[] = []
+  el: HTMLElement
+  opts: Record<string, unknown>
+  calls: Array<[string, unknown]> = []
+  private handlers: Record<string, Set<Handler>> = {}
+  _duration = 0
+  _qualities: Array<{ id: string; label: string; active: boolean }> = []
+  _textTracks: Array<{
+    label: string
+    language: string
+    kind: string
+    mode: string
+  }> = []
+  _muted = false
+
+  constructor(el: HTMLElement, opts: Record<string, unknown>) {
+    this.el = el
+    this.opts = opts
+    FakeVimeoPlayer.instances.push(this)
+    el.appendChild(document.createElement("iframe")) // the SDK injects an iframe
+  }
+
+  on(event: string, fn: Handler) {
+    ;(this.handlers[event] ??= new Set()).add(fn)
+  }
+  off(event: string, fn?: Handler) {
+    if (fn) this.handlers[event]?.delete(fn)
+    else delete this.handlers[event]
+  }
+  emit(event: string, data?: unknown) {
+    this.handlers[event]?.forEach((fn) => fn(data))
+  }
+
+  ready() {
+    return Promise.resolve()
+  }
+  play() {
+    this.calls.push(["play", undefined])
+    return Promise.resolve()
+  }
+  pause() {
+    this.calls.push(["pause", undefined])
+    return Promise.resolve()
+  }
+  setCurrentTime(t: number) {
+    this.calls.push(["setCurrentTime", t])
+    return Promise.resolve(t)
+  }
+  getDuration() {
+    return Promise.resolve(this._duration)
+  }
+  getVolume() {
+    return Promise.resolve(1)
+  }
+  setVolume(v: number) {
+    this.calls.push(["setVolume", v])
+    return Promise.resolve(v)
+  }
+  getMuted() {
+    return Promise.resolve(this._muted)
+  }
+  setMuted(m: boolean) {
+    this.calls.push(["setMuted", m])
+    return Promise.resolve(m)
+  }
+  setPlaybackRate(r: number) {
+    this.calls.push(["setPlaybackRate", r])
+    return Promise.resolve(r)
+  }
+  getQualities() {
+    return Promise.resolve(this._qualities)
+  }
+  setQuality(id: string) {
+    this.calls.push(["setQuality", id])
+    return Promise.resolve(id)
+  }
+  getTextTracks() {
+    return Promise.resolve(this._textTracks)
+  }
+  enableTextTrack(language: string, kind?: string, showing?: boolean) {
+    this.calls.push(["enableTextTrack", [language, kind, showing]])
+    return Promise.resolve({ language, kind })
+  }
+  disableTextTrack() {
+    this.calls.push(["disableTextTrack", undefined])
+    return Promise.resolve()
+  }
+  requestPictureInPicture() {
+    this.calls.push(["requestPictureInPicture", undefined])
+    return Promise.resolve()
+  }
+  exitPictureInPicture() {
+    this.calls.push(["exitPictureInPicture", undefined])
+    return Promise.resolve()
+  }
+  loadVideo(idOrObj: unknown) {
+    this.calls.push(["loadVideo", idOrObj])
+    return Promise.resolve(idOrObj)
+  }
+  destroy() {
+    this.calls.push(["destroy", undefined])
+    return Promise.resolve()
+  }
+}
+
+export function installFakeVimeo() {
+  FakeVimeoPlayer.instances = []
+  ;(window as unknown as { Vimeo?: unknown }).Vimeo = { Player: FakeVimeoPlayer }
+}
+
+export function uninstallFakeVimeo() {
+  delete (window as unknown as { Vimeo?: unknown }).Vimeo
+  FakeVimeoPlayer.instances = []
+}
+
+// Flush pending microtasks (the provider's async reads at mount/loaded).
+export function flush() {
+  return new Promise<void>((r) => setTimeout(r, 0))
+}
diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index bcfd2dc..72c28d2 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -1,5 +1,11 @@
-import { describe, it, expect } from "vitest"
-import { parseVimeoSource, playerUrl } from "./provider"
+import { describe, it, expect, afterEach, beforeEach } from "vitest"
+import { parseVimeoSource, playerUrl, createVimeoProvider } from "./provider"
+import {
+  FakeVimeoPlayer,
+  installFakeVimeo,
+  uninstallFakeVimeo,
+  flush,
+} from "./fake-vimeo"
 
 describe("parseVimeoSource", () => {
   it("passes a bare numeric id through", () => {
@@ -33,3 +39,84 @@ describe("playerUrl", () => {
     )
   })
 })
+
+const mount = (provider: ReturnType<typeof createVimeoProvider>) => {
+  const host = document.createElement("div")
+  document.body.appendChild(host)
+  provider.mount(host)
+  return host
+}
+
+describe("createVimeoProvider lifecycle", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("constructs a player with the numeric id for a public video", async () => {
+    const provider = createVimeoProvider({ videoId: "123456789" })
+    mount(provider)
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    expect(FakeVimeoPlayer.instances[0]!.opts.id).toBe("123456789")
+    expect(FakeVimeoPlayer.instances[0]!.opts.url).toBeUndefined()
+    expect(FakeVimeoPlayer.instances[0]!.opts.controls).toBe(false)
+    provider.destroy()
+  })
+
+  it("constructs with the ?h= url when a hash is present", async () => {
+    const provider = createVimeoProvider({
+      videoId: "123456789",
+      hash: "abc",
+    })
+    mount(provider)
+    await flush()
+    expect(FakeVimeoPlayer.instances[0]!.opts.url).toBe(
+      "https://player.vimeo.com/video/123456789?h=abc",
+    )
+    expect(FakeVimeoPlayer.instances[0]!.opts.id).toBeUndefined()
+    provider.destroy()
+  })
+
+  it("exposes default state before any event", () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    const s = provider.getState()
+    expect(s.paused).toBe(true)
+    expect(s.currentTime).toBe(0)
+    provider.destroy()
+  })
+
+  it("tears down the player on destroy", async () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    await flush()
+    const player = FakeVimeoPlayer.instances[0]!
+    provider.destroy()
+    expect(player.calls.map((c) => c[0])).toContain("destroy")
+  })
+
+  it("does not leave a live player if destroyed before the SDK loads", async () => {
+    // No window.Vimeo yet -> loader path. Capture the injected <script>.
+    uninstallFakeVimeo()
+    delete (window as unknown as { Vimeo?: unknown }).Vimeo
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    provider.destroy() // before the script "loads"
+    installFakeVimeo()
+    const script = document.querySelector(
+      'script[src="https://player.vimeo.com/api/player.js"]',
+    ) as HTMLScriptElement | null
+    script?.dispatchEvent(new Event("load"))
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(0)
+  })
+
+  it("notifies subscribers on state change", async () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    mount(provider)
+    await flush()
+    let calls = 0
+    provider.subscribe(() => calls++)
+    FakeVimeoPlayer.instances[0]!.emit("play")
+    expect(calls).toBeGreaterThan(0)
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 1b8eaa1..de947ad 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -1,3 +1,6 @@
+import { defaultState } from "../core/fake-provider"
+import type { MediaState, PlayerActions, Provider } from "../core/types"
+
 export type VimeoProviderOptions = {
   // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
   // parseVimeoSource resolves it.
@@ -34,3 +37,179 @@ export function parseVimeoSource(input: string): { id: string; hash?: string } {
 export function playerUrl(id: string, hash: string): string {
   return `https://player.vimeo.com/video/${id}?h=${hash}`
 }
+
+// Narrow structural view of the Vimeo Player SDK surface we touch. Hand-rolled
+// (like youtube's YTPlayer) so the provider needs no runtime dep or typings.
+type VimeoEventHandler = (data?: unknown) => void
+export type VimeoPlayer = {
+  on(event: string, handler: VimeoEventHandler): void
+  off(event: string, handler?: VimeoEventHandler): void
+  ready(): Promise<void>
+  play(): Promise<unknown>
+  pause(): Promise<unknown>
+  setCurrentTime(seconds: number): Promise<number>
+  getDuration(): Promise<number>
+  getVolume(): Promise<number>
+  setVolume(volume: number): Promise<number>
+  getMuted(): Promise<boolean>
+  setMuted(muted: boolean): Promise<boolean>
+  setPlaybackRate(rate: number): Promise<number>
+  getQualities(): Promise<Array<{ id: string; label: string; active: boolean }>>
+  setQuality(id: string): Promise<string>
+  getTextTracks(): Promise<
+    Array<{ label: string; language: string; kind: string; mode: string }>
+  >
+  enableTextTrack(
+    language: string,
+    kind?: string,
+    showing?: boolean,
+  ): Promise<unknown>
+  disableTextTrack(): Promise<unknown>
+  requestPictureInPicture(): Promise<unknown>
+  exitPictureInPicture(): Promise<unknown>
+  loadVideo(idOrOpts: number | string | { id?: number | string; url?: string }): Promise<unknown>
+  destroy(): Promise<unknown>
+}
+type VimeoNamespace = {
+  Player: new (el: HTMLElement, opts: Record<string, unknown>) => VimeoPlayer
+}
+type VimeoWindow = Window & typeof globalThis & { Vimeo?: VimeoNamespace }
+
+const SDK_SRC = "https://player.vimeo.com/api/player.js"
+
+// Lazily load player.js exactly once; resolve when window.Vimeo.Player exists.
+// There is no global ready callback (unlike YouTube), so we resolve on the
+// script's load event. An already-present window.Vimeo short-circuits.
+let apiPromise: Promise<VimeoNamespace> | null = null
+function loadVimeoAPI(): Promise<VimeoNamespace> {
+  const w = window as VimeoWindow
+  if (w.Vimeo?.Player) return Promise.resolve(w.Vimeo)
+  if (apiPromise) return apiPromise
+  apiPromise = new Promise<VimeoNamespace>((resolve, reject) => {
+    const finish = () => {
+      if (w.Vimeo?.Player) resolve(w.Vimeo)
+      else reject(new Error("Vimeo SDK loaded but window.Vimeo is missing"))
+    }
+    const existing = document.querySelector(`script[src="${SDK_SRC}"]`)
+    if (existing) {
+      existing.addEventListener("load", finish)
+      return
+    }
+    const script = document.createElement("script")
+    script.src = SDK_SRC
+    script.async = true
+    script.addEventListener("load", finish)
+    document.head.appendChild(script)
+  })
+  return apiPromise
+}
+
+function readyVimeo(): VimeoNamespace | null {
+  if (typeof window === "undefined") return null
+  const v = (window as VimeoWindow).Vimeo
+  return v && typeof v.Player === "function" ? v : null
+}
+
+export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
+  const explicit = parseVimeoSource(opts.videoId)
+  const initial = { id: explicit.id, hash: opts.hash ?? explicit.hash }
+  let player: VimeoPlayer | null = null
+  let destroyed = false
+  const desiredRate = opts.defaultRate ?? 1
+
+  let state: MediaState = {
+    ...defaultState(),
+    rate: desiredRate,
+    muted: opts.muted ?? false,
+    capabilities: {
+      canSetRate: true, // best-effort: setPlaybackRate is plan-gated, can't probe
+      hasStoryboard: false,
+      canPiP: !!(
+        typeof document !== "undefined" && document.pictureInPictureEnabled
+      ),
+      canFullscreen: true,
+      // Flip on at `loaded` once getQualities/getTextTracks return non-empty.
+      canSetQuality: false,
+      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 })
+
+  // Stub actions; later tasks replace this object's bodies.
+  const actions: PlayerActions = {
+    play: () => {},
+    pause: () => {},
+    seek: () => {},
+    setRate: () => {},
+    setVolume: () => {},
+    setMuted: () => {},
+    setQuality: () => {},
+    setTextTrack: () => {},
+    enterFullscreen: () => {},
+    exitFullscreen: () => {},
+    enterPiP: () => {},
+    exitPiP: () => {},
+  }
+
+  const createPlayer = (v: VimeoNamespace, host: HTMLElement) => {
+    const ctorOpts: Record<string, unknown> = {
+      controls: false, // kino owns the chrome (paid-plan feature)
+      autoplay: !!opts.autoPlay,
+      muted: !!opts.muted,
+      loop: !!opts.loop,
+      playsinline: true,
+      dnt: true,
+      keyboard: false,
+    }
+    if (initial.hash) ctorOpts.url = playerUrl(initial.id, initial.hash)
+    else ctorOpts.id = initial.id
+    const p = new v.Player(host, ctorOpts)
+    player = p
+    void p.ready().then(() => {
+      if (destroyed) return
+    })
+    p.on("play", () => patch({ paused: false, ended: false }))
+  }
+
+  return {
+    mount(container) {
+      const host = document.createElement("div")
+      container.appendChild(host)
+      document.addEventListener("fullscreenchange", onFullscreenChange)
+      const v = readyVimeo()
+      if (v) {
+        createPlayer(v, host)
+      } else {
+        void loadVimeoAPI().then((loaded) => {
+          if (destroyed) return
+          if (host.isConnected) createPlayer(loaded, host)
+        })
+      }
+    },
+    getState: () => state,
+    subscribe: (l) => {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    actions,
+    destroy() {
+      destroyed = true
+      document.removeEventListener("fullscreenchange", onFullscreenChange)
+      try {
+        void player?.destroy()
+      } catch {
+        /* already gone */
+      }
+      player = null
+      listeners.clear()
+    },
+  }
+}

From d28529fe250e94073ba558f12478cf7dc049a440 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:46:48 +0530
Subject: [PATCH 05/21] feat(vimeo): event-driven state sync

---
 src/vimeo/provider.test.ts | 65 ++++++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 51 ++++++++++++++++++++++++++++--
 2 files changed, 114 insertions(+), 2 deletions(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 72c28d2..80fc050 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -120,3 +120,68 @@ describe("createVimeoProvider lifecycle", () => {
     provider.destroy()
   })
 })
+
+const ready = async (o: Parameters<typeof createVimeoProvider>[0]) => {
+  const provider = createVimeoProvider(o)
+  mount(provider)
+  await flush()
+  return { provider, player: FakeVimeoPlayer.instances.at(-1)! }
+}
+
+describe("state sync", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("play/pause/ended set paused + ended", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("play")
+    expect(provider.getState().paused).toBe(false)
+    player.emit("pause")
+    expect(provider.getState().paused).toBe(true)
+    player.emit("ended")
+    expect(provider.getState().ended).toBe(true)
+    provider.destroy()
+  })
+
+  it("bufferstart keeps paused false (no poster flash)", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("play")
+    player.emit("bufferstart")
+    expect(provider.getState().paused).toBe(false)
+    provider.destroy()
+  })
+
+  it("timeupdate updates currentTime + duration", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 12, duration: 100, percent: 0.12 })
+    expect(provider.getState().currentTime).toBe(12)
+    expect(provider.getState().duration).toBe(100)
+    provider.destroy()
+  })
+
+  it("progress maps to buffered ranges", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 0, duration: 200, percent: 0 })
+    player.emit("progress", { seconds: 0, duration: 200, percent: 0.5 })
+    expect(provider.getState().buffered).toEqual([[0, 100]])
+    provider.destroy()
+  })
+
+  it("volumechange reads volume AND muted", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("volumechange", { volume: 0.3, muted: true })
+    expect(provider.getState().volume).toBe(0.3)
+    expect(provider.getState().muted).toBe(true)
+    provider.destroy()
+  })
+
+  it("error folds name into the message with code 0", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("error", { name: "PrivacyError", message: "not allowed" })
+    expect(provider.getState().error).toEqual({
+      code: 0,
+      message: "PrivacyError: not allowed",
+    })
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index de947ad..9f1cef0 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -115,7 +115,7 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   const initial = { id: explicit.id, hash: opts.hash ?? explicit.hash }
   let player: VimeoPlayer | null = null
   let destroyed = false
-  const desiredRate = opts.defaultRate ?? 1
+  let desiredRate = opts.defaultRate ?? 1
 
   let state: MediaState = {
     ...defaultState(),
@@ -159,6 +159,53 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     exitPiP: () => {},
   }
 
+  const bindEvents = (p: VimeoPlayer) => {
+    p.on("play", () => patch({ paused: false, ended: false }))
+    p.on("pause", () => patch({ paused: true }))
+    p.on("ended", () => patch({ paused: true, ended: true }))
+    p.on("bufferstart", () => patch({ paused: false }))
+    p.on("bufferend", () => {})
+    p.on("timeupdate", (d) => {
+      const e = d as { seconds: number; duration: number }
+      patch({
+        currentTime: e.seconds ?? 0,
+        duration: e.duration ?? state.duration,
+        seeking: false,
+        readyState: 4,
+      })
+    })
+    p.on("progress", (d) => {
+      const e = d as { duration: number; percent: number }
+      const duration = e.duration ?? state.duration
+      patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] })
+    })
+    p.on("seeking", () => patch({ seeking: true }))
+    p.on("seeked", (d) => {
+      const e = d as { seconds?: number }
+      patch({ seeking: false, ended: false, currentTime: e?.seconds ?? state.currentTime })
+    })
+    p.on("volumechange", (d) => {
+      const e = d as { volume: number; muted?: boolean }
+      patch({ volume: e.volume, muted: e.muted ?? state.muted })
+    })
+    p.on("playbackratechange", (d) => {
+      const e = d as { playbackRate: number }
+      desiredRate = e.playbackRate
+      patch({ rate: e.playbackRate })
+    })
+    p.on("fullscreenchange", (d) => {
+      const e = d as { fullscreen: boolean }
+      patch({ fullscreen: !!e.fullscreen })
+    })
+    p.on("enterpictureinpicture", () => patch({ pip: true }))
+    p.on("leavepictureinpicture", () => patch({ pip: false }))
+    p.on("error", (d) => {
+      const e = d as { name?: string; message?: string }
+      const message = e.name ? `${e.name}: ${e.message ?? ""}`.trim() : (e.message ?? "Vimeo playback error")
+      patch({ error: { code: 0, message } })
+    })
+  }
+
   const createPlayer = (v: VimeoNamespace, host: HTMLElement) => {
     const ctorOpts: Record<string, unknown> = {
       controls: false, // kino owns the chrome (paid-plan feature)
@@ -176,7 +223,7 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     void p.ready().then(() => {
       if (destroyed) return
     })
-    p.on("play", () => patch({ paused: false, ended: false }))
+    bindEvents(p)
   }
 
   return {

From 2edccc4ee07b6b1267dfe0f5a1cbdfa4ea6b8e0b Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:52:23 +0530
Subject: [PATCH 06/21] =?UTF-8?q?feat(vimeo):=20loaded=20handler=20?=
 =?UTF-8?q?=E2=80=94=20duration,=20qualities,=20tracks,=20capabilities?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/vimeo/provider.test.ts | 47 +++++++++++++++++++++++
 src/vimeo/provider.ts      | 77 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 123 insertions(+), 1 deletion(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 80fc050..d49f925 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -185,3 +185,50 @@ describe("state sync", () => {
     provider.destroy()
   })
 })
+
+describe("loaded handler", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("reads duration and flips no capabilities when lists are empty", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._duration = 90
+    player.emit("loaded")
+    await flush()
+    expect(provider.getState().duration).toBe(90)
+    expect(provider.getState().capabilities.canSetQuality).toBe(false)
+    expect(provider.getState().capabilities.hasTextTracks).toBe(false)
+    provider.destroy()
+  })
+
+  it("maps qualities with height parsed from id, not label", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._qualities = [
+      { id: "auto", label: "Auto", active: true },
+      { id: "2160p", label: "4K", active: false },
+      { id: "1080p", label: "1080p", active: false },
+    ]
+    player.emit("loaded")
+    await flush()
+    const s = provider.getState()
+    expect(s.capabilities.canSetQuality).toBe(true)
+    expect(s.activeQualityId).toBe("auto")
+    const uhd = s.qualities.find((q) => q.id === "2160p")!
+    expect(uhd.height).toBe(2160) // NOT 4 from "4K"
+    provider.destroy()
+  })
+
+  it("maps text tracks with synthesized ids and flips hasTextTracks", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._textTracks = [
+      { label: "English", language: "en", kind: "captions", mode: "disabled" },
+      { label: "English", language: "en", kind: "subtitles", mode: "disabled" },
+    ]
+    player.emit("loaded")
+    await flush()
+    const s = provider.getState()
+    expect(s.capabilities.hasTextTracks).toBe(true)
+    expect(s.textTracks.map((t) => t.id)).toEqual(["en.captions", "en.subtitles"])
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 9f1cef0..920b00f 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -1,5 +1,5 @@
 import { defaultState } from "../core/fake-provider"
-import type { MediaState, PlayerActions, Provider } from "../core/types"
+import type { MediaState, PlayerActions, Provider, QualityLevel, TextTrackInfo } from "../core/types"
 
 export type VimeoProviderOptions = {
   // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
@@ -110,6 +110,40 @@ function readyVimeo(): VimeoNamespace | null {
   return v && typeof v.Player === "function" ? v : null
 }
 
+function mapQualities(
+  raw: Array<{ id: string; label: string; active: boolean }>,
+): { qualities: QualityLevel[]; activeId: string } {
+  const qualities = raw.map((q) => ({
+    id: q.id,
+    height: parseInt(q.id, 10) || 0, // id is "2160p"; label "4K" would parse to 4
+    bitrate: 0, // Vimeo exposes no bitrate
+    selected: q.active,
+  }))
+  const active = raw.find((q) => q.active)?.id ?? "auto"
+  return { qualities, activeId: active }
+}
+
+// getTextTracks() objects have no id; synthesize a stable one. Disambiguate
+// same-language/same-kind duplicates with an index suffix.
+function mapTracks(
+  raw: Array<{ label: string; language: string; kind: string; mode: string }>,
+): TextTrackInfo[] {
+  const seen = new Map<string, number>()
+  return raw.map((t) => {
+    const base = `${t.language}.${t.kind}`
+    const n = seen.get(base) ?? 0
+    seen.set(base, n + 1)
+    const id = n === 0 ? base : `${base}.${n}`
+    return {
+      id,
+      kind: t.kind,
+      label: t.label || t.language,
+      lang: t.language,
+      mode: t.mode === "showing" ? "showing" : "disabled",
+    }
+  })
+}
+
 export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   const explicit = parseVimeoSource(opts.videoId)
   const initial = { id: explicit.id, hash: opts.hash ?? explicit.hash }
@@ -159,6 +193,45 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     exitPiP: () => {},
   }
 
+  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 onLoaded = async () => {
+    if (!player) return
+    const p = player
+    const [duration, rawQualities, rawTracks, muted] = await Promise.all([
+      p.getDuration().catch(() => 0),
+      p.getQualities().catch(() => []),
+      p.getTextTracks().catch(() => []),
+      p.getMuted().catch(() => false),
+    ])
+    if (destroyed) return
+    void p.setPlaybackRate(desiredRate).catch(() => {})
+    const { qualities, activeId } = mapQualities(rawQualities)
+    const tracks = mapTracks(rawTracks)
+    setSessionMetadata(opts.metadata?.videoTitle ?? "Video")
+    patch({
+      duration: duration || state.duration,
+      readyState: 4,
+      muted,
+      qualities,
+      activeQualityId: activeId,
+      textTracks: tracks,
+      capabilities: {
+        ...state.capabilities,
+        canSetQuality: qualities.length > 0,
+        hasTextTracks: tracks.length > 0,
+      },
+    })
+  }
+
   const bindEvents = (p: VimeoPlayer) => {
     p.on("play", () => patch({ paused: false, ended: false }))
     p.on("pause", () => patch({ paused: true }))
@@ -204,6 +277,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
       const message = e.name ? `${e.name}: ${e.message ?? ""}`.trim() : (e.message ?? "Vimeo playback error")
       patch({ error: { code: 0, message } })
     })
+    p.on("loaded", () => void onLoaded())
+    p.on("qualitychange", (d) => patch({ activeQualityId: (d as { quality: string }).quality }))
   }
 
   const createPlayer = (v: VimeoNamespace, host: HTMLElement) => {

From 2d5fca5e527b7de8a9cbe6e4d99f924e24c8967c Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 16:57:21 +0530
Subject: [PATCH 07/21] feat(vimeo): player actions

---
 src/vimeo/provider.test.ts | 47 ++++++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 37 +++++++++++++++++++-----------
 2 files changed, 71 insertions(+), 13 deletions(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index d49f925..5a3a9e2 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -232,3 +232,50 @@ describe("loaded handler", () => {
     provider.destroy()
   })
 })
+
+describe("actions", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+  const names = (p: FakeVimeoPlayer) => p.calls.map((c) => c[0])
+
+  it("play/pause/seek call the SDK; seek patches seeking immediately", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.play()
+    provider.actions.pause()
+    provider.actions.seek(42)
+    expect(names(player)).toEqual(["play", "pause", "setCurrentTime"])
+    expect(player.calls.find((c) => c[0] === "setCurrentTime")![1]).toBe(42)
+    expect(provider.getState().seeking).toBe(true)
+    provider.destroy()
+  })
+
+  it("setVolume passes 0..1 unscaled", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setVolume(0.4)
+    expect(player.calls).toContainEqual(["setVolume", 0.4])
+    provider.destroy()
+  })
+
+  it("setRate does NOT patch rate optimistically (waits for the event)", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setRate(2)
+    expect(player.calls).toContainEqual(["setPlaybackRate", 2])
+    expect(provider.getState().rate).toBe(1) // unchanged until the echo event
+    player.emit("playbackratechange", { playbackRate: 2 })
+    expect(provider.getState().rate).toBe(2)
+    provider.destroy()
+  })
+
+  it("setQuality + PiP call the SDK", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.actions.setQuality("1080p")
+    provider.actions.enterPiP()
+    provider.actions.exitPiP()
+    expect(names(player)).toEqual([
+      "setQuality",
+      "requestPictureInPicture",
+      "exitPictureInPicture",
+    ])
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 920b00f..1038219 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -177,20 +177,31 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   const onFullscreenChange = () =>
     patch({ fullscreen: document.fullscreenElement != null })
 
-  // Stub actions; later tasks replace this object's bodies.
   const actions: PlayerActions = {
-    play: () => {},
-    pause: () => {},
-    seek: () => {},
-    setRate: () => {},
-    setVolume: () => {},
-    setMuted: () => {},
-    setQuality: () => {},
-    setTextTrack: () => {},
-    enterFullscreen: () => {},
-    exitFullscreen: () => {},
-    enterPiP: () => {},
-    exitPiP: () => {},
+    play: () => void player?.play().catch(() => {}),
+    pause: () => void player?.pause().catch(() => {}),
+    seek: (t) => {
+      patch({ seeking: true })
+      void player?.setCurrentTime(t).catch(() => {})
+    },
+    setRate: (r) => {
+      desiredRate = r
+      // No optimistic patch — rate moves on the playbackratechange echo, so a
+      // plan-gated rejection never leaves the UI showing a rate that didn't take.
+      void player?.setPlaybackRate(r).catch(() => {})
+    },
+    setVolume: (v) => void player?.setVolume(v).catch(() => {}),
+    setMuted: (m) => void player?.setMuted(m).catch(() => {}),
+    setQuality: (id) => void player?.setQuality(id).catch(() => {}),
+    setTextTrack: () => {}, // Task 6
+    enterFullscreen: (wrapper) => {
+      if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
+    },
+    exitFullscreen: () => {
+      if (document.fullscreenElement) void document.exitFullscreen?.()
+    },
+    enterPiP: () => void player?.requestPictureInPicture().catch(() => {}),
+    exitPiP: () => void player?.exitPictureInPicture().catch(() => {}),
   }
 
   const setSessionMetadata = (title: string) => {

From 93fb021d268fe9ed2435cf4f1cb58cce118678db Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:02:34 +0530
Subject: [PATCH 08/21] =?UTF-8?q?feat(vimeo):=20captions=20=E2=80=94=20ove?=
 =?UTF-8?q?rlay=20cues=20+=20track=20selection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/vimeo/provider.test.ts | 47 ++++++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 26 ++++++++++++++++++++-
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 5a3a9e2..1d4969f 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -279,3 +279,50 @@ describe("actions", () => {
     provider.destroy()
   })
 })
+
+describe("captions", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  const withTracks = async () => {
+    const r = await ready({ videoId: "1" })
+    r.player._textTracks = [
+      { label: "English", language: "en", kind: "captions", mode: "disabled" },
+      { label: "Français", language: "fr", kind: "subtitles", mode: "disabled" },
+    ]
+    r.player.emit("loaded")
+    await flush()
+    return r
+  }
+
+  it("setTextTrack(id) enables the track with showing:false", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("fr.subtitles")
+    expect(player.calls).toContainEqual([
+      "enableTextTrack",
+      ["fr", "subtitles", false],
+    ])
+    expect(provider.getState().activeTextTrackId).toBe("fr.subtitles")
+    provider.destroy()
+  })
+
+  it("setTextTrack(null) disables and clears the cue", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("en.captions")
+    provider.actions.setTextTrack(null)
+    expect(player.calls.map((c) => c[0])).toContain("disableTextTrack")
+    expect(provider.getState().activeTextTrackId).toBe(null)
+    expect(provider.getState().activeCueText).toBe("")
+    provider.destroy()
+  })
+
+  it("cuechange renders the cue text in the overlay", async () => {
+    const { provider, player } = await withTracks()
+    provider.actions.setTextTrack("en.captions")
+    player.emit("cuechange", { cues: [{ text: "Hello there" }] })
+    expect(provider.getState().activeCueText).toBe("Hello there")
+    player.emit("cuechange", { cues: [] })
+    expect(provider.getState().activeCueText).toBe("")
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 1038219..c5de3f3 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -193,7 +193,16 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     setVolume: (v) => void player?.setVolume(v).catch(() => {}),
     setMuted: (m) => void player?.setMuted(m).catch(() => {}),
     setQuality: (id) => void player?.setQuality(id).catch(() => {}),
-    setTextTrack: () => {}, // Task 6
+    setTextTrack: (id) => {
+      if (id == null) {
+        patch({ activeTextTrackId: null, activeCueText: "" })
+        void player?.disableTextTrack().catch(() => {})
+        return
+      }
+      const ref = state.textTracks.find((t) => t.id === id)
+      patch({ activeTextTrackId: id })
+      if (ref) void player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {})
+    },
     enterFullscreen: (wrapper) => {
       if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
     },
@@ -290,6 +299,21 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     })
     p.on("loaded", () => void onLoaded())
     p.on("qualitychange", (d) => patch({ activeQualityId: (d as { quality: string }).quality }))
+    p.on("cuechange", (d) => {
+      const e = d as { cues?: Array<{ text?: string }> }
+      patch({ activeCueText: e.cues?.[0]?.text ?? "" })
+    })
+    p.on("texttrackchange", (d) => {
+      const e = d as { language: string | null; kind: string | null }
+      if (e.language == null) {
+        patch({ activeTextTrackId: null, activeCueText: "" })
+        return
+      }
+      const match = state.textTracks.find(
+        (t) => t.lang === e.language && t.kind === e.kind,
+      )
+      patch({ activeTextTrackId: match?.id ?? state.activeTextTrackId })
+    })
   }
 
   const createPlayer = (v: VimeoNamespace, host: HTMLElement) => {

From 49f86a8ce4fb419f3deb14092a1fcc5e7889e3f8 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:07:50 +0530
Subject: [PATCH 09/21] feat(vimeo): swapSource with hash channel

---
 src/vimeo/provider.test.ts | 30 ++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 19 ++++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 1d4969f..9c14b7d 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -326,3 +326,33 @@ describe("captions", () => {
     provider.destroy()
   })
 })
+
+describe("swapSource", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  it("loads a public id and resets progress + rate", async () => {
+    const { provider, player } = await ready({ videoId: "1", defaultRate: 1.5 })
+    player.emit("timeupdate", { seconds: 30, duration: 60, percent: 0.5 })
+    provider.swapSource!({ src: "987654321" })
+    await flush()
+    expect(player.calls).toContainEqual(["loadVideo", 987654321])
+    expect(player.calls).toContainEqual(["setPlaybackRate", 1.5])
+    expect(provider.getState().currentTime).toBe(0)
+    expect(provider.getState().ended).toBe(false)
+    provider.destroy()
+  })
+
+  it("loads an unlisted source by url when src carries a hash", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    provider.swapSource!({
+      src: "https://player.vimeo.com/video/987654321?h=newhash",
+    })
+    await flush()
+    expect(player.calls).toContainEqual([
+      "loadVideo",
+      { url: "https://player.vimeo.com/video/987654321?h=newhash" },
+    ])
+    provider.destroy()
+  })
+})
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index c5de3f3..2050c33 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -1,5 +1,5 @@
 import { defaultState } from "../core/fake-provider"
-import type { MediaState, PlayerActions, Provider, QualityLevel, TextTrackInfo } from "../core/types"
+import type { MediaState, PlayerActions, Provider, QualityLevel, TextTrackInfo, SourceOptions } from "../core/types"
 
 export type VimeoProviderOptions = {
   // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
@@ -356,6 +356,23 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
       listeners.add(l)
       return () => listeners.delete(l)
     },
+    swapSource(next: SourceOptions) {
+      if (!player || next.src == null) return
+      const { id, hash } = parseVimeoSource(next.src)
+      void player
+        .loadVideo(hash ? { url: playerUrl(id, hash) } : Number(id))
+        .then(() => void player?.setPlaybackRate(desiredRate).catch(() => {}))
+        .catch(() => {})
+      if (next.metadata?.videoTitle != null)
+        setSessionMetadata(next.metadata.videoTitle)
+      patch({
+        currentTime: 0,
+        duration: 0,
+        ended: false,
+        seeking: false,
+        error: null,
+      })
+    },
     actions,
     destroy() {
       destroyed = true

From 7fd2d5c7fa33332fa09d1fe2ce233351bf2bd406 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:12:32 +0530
Subject: [PATCH 10/21] feat(vimeo): VimeoPlayer React wrapper + entry

---
 src/vimeo.ts                    |  7 +++
 src/vimeo/vimeo-player.test.tsx | 40 ++++++++++++++++
 src/vimeo/vimeo-player.tsx      | 85 +++++++++++++++++++++++++++++++++
 3 files changed, 132 insertions(+)
 create mode 100644 src/vimeo.ts
 create mode 100644 src/vimeo/vimeo-player.test.tsx
 create mode 100644 src/vimeo/vimeo-player.tsx

diff --git a/src/vimeo.ts b/src/vimeo.ts
new file mode 100644
index 0000000..d2700b5
--- /dev/null
+++ b/src/vimeo.ts
@@ -0,0 +1,7 @@
+export {
+  createVimeoProvider,
+  parseVimeoSource,
+  playerUrl,
+  type VimeoProviderOptions,
+} from "./vimeo/provider"
+export { VimeoPlayer, type VimeoPlayerProps } from "./vimeo/vimeo-player"
diff --git a/src/vimeo/vimeo-player.test.tsx b/src/vimeo/vimeo-player.test.tsx
new file mode 100644
index 0000000..a5f6c42
--- /dev/null
+++ b/src/vimeo/vimeo-player.test.tsx
@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { render, cleanup } from "@testing-library/react"
+import { VimeoPlayer } from "./vimeo-player"
+import {
+  FakeVimeoPlayer,
+  installFakeVimeo,
+  uninstallFakeVimeo,
+  flush,
+} from "./fake-vimeo"
+
+describe("<VimeoPlayer>", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => {
+    cleanup()
+    uninstallFakeVimeo()
+  })
+
+  it("creates exactly one player and swaps on videoId change", async () => {
+    const view = render(<VimeoPlayer videoId="111" />)
+    await flush()
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    view.rerender(<VimeoPlayer videoId="222" />)
+    await flush()
+    // Still one player; the new source flows through loadVideo, not a remount.
+    expect(FakeVimeoPlayer.instances).toHaveLength(1)
+    expect(
+      FakeVimeoPlayer.instances[0]!.calls.find((c) => c[0] === "loadVideo")![1],
+    ).toBe(222)
+  })
+
+  it("swaps to a ?h= url when hash changes", async () => {
+    const view = render(<VimeoPlayer videoId="111" />)
+    await flush()
+    view.rerender(<VimeoPlayer videoId="111" hash="secret" />)
+    await flush()
+    expect(
+      FakeVimeoPlayer.instances[0]!.calls.find((c) => c[0] === "loadVideo")![1],
+    ).toEqual({ url: "https://player.vimeo.com/video/111?h=secret" })
+  })
+})
diff --git a/src/vimeo/vimeo-player.tsx b/src/vimeo/vimeo-player.tsx
new file mode 100644
index 0000000..5ee0a8e
--- /dev/null
+++ b/src/vimeo/vimeo-player.tsx
@@ -0,0 +1,85 @@
+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 {
+  createVimeoProvider,
+  parseVimeoSource,
+  playerUrl,
+  type VimeoProviderOptions,
+} from "./provider"
+import type { Provider } from "../core/types"
+
+export type VimeoPlayerProps = VimeoProviderOptions & {
+  accentColor?: string
+  theme?: Record<string, string>
+  className?: string
+  /** Blur-up still painted behind the video until the first frame loads. */
+  placeholder?: string
+  children?: ReactNode
+}
+
+// Pack id + optional hash into the single `src` string swapSource consumes.
+const packSrc = (videoId: string, hash?: string) => {
+  const parsed = parseVimeoSource(videoId)
+  const h = hash ?? parsed.hash
+  return h ? playerUrl(parsed.id, h) : parsed.id
+}
+
+/**
+ * kino's glass chrome over a Vimeo video, backed by the Vimeo Player SDK. Pass a
+ * numeric id or any vimeo.com / player.vimeo.com URL; for unlisted videos pass
+ * the `hash` (or a share URL that already contains it).
+ *
+ * Only `videoId`, `hash`, and `metadata.videoTitle` are reactive (they flow
+ * through `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read
+ * once at creation — remount (e.g. via `key`) to change them.
+ *
+ * Chromeless playback (kino owning the controls) requires a **paid** Vimeo plan;
+ * on a free-account video Vimeo renders its own controls under kino's overlay.
+ *
+ * Per Vimeo's embed terms, kino does not obscure the player — no poster-on-pause
+ * cover over the embed; kino's controls sit alongside Vimeo's surface.
+ */
+export function VimeoPlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: VimeoPlayerProps) {
+  const providerRef = useRef<Provider | null>(null)
+  if (providerRef.current === null) {
+    providerRef.current = createVimeoProvider(opts)
+  }
+  const provider = providerRef.current
+
+  const mountedRef = useRef(false)
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true
+      return
+    }
+    provider.swapSource?.({
+      src: packSrc(opts.videoId, opts.hash),
+      metadata: opts.metadata,
+    })
+  }, [opts.videoId, opts.hash, opts.metadata?.videoTitle])
+
+  return (
+    <Player
+      provider={provider}
+      accentColor={accentColor}
+      theme={theme}
+      className={className}
+      placeholder={placeholder}
+    >
+      <IdleOverlay />
+      <Captions />
+      <ControlBar />
+      {children}
+    </Player>
+  )
+}

From fbb334f23b38e3eff8012547210fb184846ecf32 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:17:49 +0530
Subject: [PATCH 11/21] build(vimeo): wire ./vimeo entry point

---
 package.json     | 5 +++++
 tsdown.config.ts | 1 +
 2 files changed, 6 insertions(+)

diff --git a/package.json b/package.json
index 04d2c6d..bc6e36f 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
     "react",
     "mux",
     "youtube",
+    "vimeo",
     "hls",
     "video-player"
   ],
@@ -50,6 +51,10 @@
       "types": "./dist/youtube.d.ts",
       "import": "./dist/youtube.js"
     },
+    "./vimeo": {
+      "types": "./dist/vimeo.d.ts",
+      "import": "./dist/vimeo.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "scripts": {
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 25408f9..4e23bf5 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -6,6 +6,7 @@ export default defineConfig({
     mux: "src/mux.ts",
     native: "src/native.ts",
     youtube: "src/youtube.ts",
+    vimeo: "src/vimeo.ts",
   },
   format: ["esm"],
   dts: true,

From ff8ac8c5ac8fa2e5ab3efe927b600ab14818381b Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:23:54 +0530
Subject: [PATCH 12/21] docs(vimeo): README, demo, changeset

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .changeset/vimeo-provider.md |  8 ++++++++
 README.md                    | 24 ++++++++++++++++++++--
 demo/pages/install.tsx       | 39 ++++++++++++++++++++++++++++++++++++
 demo/pages/overview.tsx      |  4 ++--
 demo/pages/providers.tsx     |  6 ++++--
 demo/player-studio.tsx       | 26 +++++++++++++++++++++---
 6 files changed, 98 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/vimeo-provider.md

diff --git a/.changeset/vimeo-provider.md b/.changeset/vimeo-provider.md
new file mode 100644
index 0000000..61ad681
--- /dev/null
+++ b/.changeset/vimeo-provider.md
@@ -0,0 +1,8 @@
+---
+"@karnstack/kino": minor
+---
+
+Add a Vimeo provider (`@karnstack/kino/vimeo`) — the Vimeo Player SDK under
+kino's chrome with quality selection, styled captions, picture-in-picture, and
+playback rate. Supports unlisted videos via a `hash`. Import `VimeoPlayer` or
+the lower-level `createVimeoProvider`.
diff --git a/README.md b/README.md
index d728160..328be66 100644
--- a/README.md
+++ b/README.md
@@ -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. 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.
+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. Four providers ship today: **Mux** (adaptive HLS via `@mux/mux-video`), **Native** (a plain `<video>` over any raw file URL), **YouTube** (the IFrame Player API wrapped in the same chrome), and **Vimeo** (the Vimeo Player SDK under the same chrome). Each lives behind its own entry point, so you only pull in the engine you use.
 
 ## Install
 
@@ -132,6 +132,27 @@ Speed, fullscreen, and captions work. The captions menu lists the video's own su
 
 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).
 
+## Playing a Vimeo video
+
+For a Vimeo source, use the Vimeo provider. It drives the Vimeo Player SDK under the same glass chrome, with kino owning the controls and keyboard map.
+
+```tsx
+import { VimeoPlayer } from "@karnstack/kino/vimeo"
+import "@karnstack/kino/styles.css"
+
+export default function Watch() {
+  return <VimeoPlayer videoId="291235566" accentColor="#00adef" />
+}
+```
+
+For an unlisted video, pass the hash (or a share URL that contains it):
+
+```tsx
+<VimeoPlayer videoId="123456789" hash="abcdef0123" />
+```
+
+Chromeless playback (kino owning the controls) requires a paid Vimeo plan.
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -201,7 +222,6 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- 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 cf002d8..98b990e 100644
--- a/demo/pages/install.tsx
+++ b/demo/pages/install.tsx
@@ -46,6 +46,17 @@ export function Clip() {
   )
 }`
 
+const VIMEO_SNIPPET = `import { VimeoPlayer } from "@karnstack/kino/vimeo"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <VimeoPlayer videoId="291235566" />
+    </div>
+  )
+}`
+
 type Prop = [string, string, string]
 
 const SHARED_PROPS: Prop[] = [
@@ -116,6 +127,21 @@ const YOUTUBE_PROPS: Prop[] = [
   ...SHARED_PROPS,
 ]
 
+const VIMEO_PROPS: Prop[] = [
+  ["videoId", "string", "Vimeo video id or any Vimeo share URL. Required."],
+  ["hash", "string", "Privacy hash for unlisted videos."],
+  ["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,
@@ -162,6 +188,10 @@ export function InstallPage() {
             <h3 className="text-lg font-medium text-paper">YouTube</h3>
             <CodeBlock code={YOUTUBE_SNIPPET} label="youtube.tsx" />
           </div>
+          <div className="flex flex-col gap-3">
+            <h3 className="text-lg font-medium text-paper">Vimeo</h3>
+            <CodeBlock code={VIMEO_SNIPPET} label="vimeo.tsx" />
+          </div>
         </div>
       </section>
 
@@ -199,6 +229,15 @@ export function InstallPage() {
             rows={propRows(YOUTUBE_PROPS)}
           />
         </div>
+        <div className="flex flex-col gap-4">
+          <h3 className="font-mono text-sm tracking-wide text-paper-faint uppercase">
+            VimeoPlayer
+          </h3>
+          <Table
+            head={["Prop", "Type", "Description"]}
+            rows={propRows(VIMEO_PROPS)}
+          />
+        </div>
       </section>
     </div>
   )
diff --git a/demo/pages/overview.tsx b/demo/pages/overview.tsx
index 21ed22c..72eebed 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, raw files, and YouTube ship today; Vimeo is next.",
+      "One UI contract, many engines. Mux HLS, raw files, YouTube, and Vimeo all ship today.",
   },
   {
     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 YouTube — behind a small typed surface.
+            raw files, YouTube, and Vimeo — 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 556bb46..4d10130 100644
--- a/demo/pages/providers.tsx
+++ b/demo/pages/providers.tsx
@@ -35,9 +35,11 @@ const PROVIDERS: ProviderCard[] = [
   },
   {
     name: "Vimeo",
-    status: "planned",
+    status: "shipped",
+    entry: "@karnstack/kino/vimeo",
     detail:
-      "The Vimeo player SDK adapted to the kino provider contract, sharing the glass UI and keyboard map.",
+      "The Vimeo Player SDK under the same kino chrome — quality, styled captions, picture-in-picture, and rate. Chromeless playback needs a paid Vimeo plan.",
+    importLine: 'import { VimeoPlayer } from "@karnstack/kino/vimeo"',
   },
 ]
 
diff --git a/demo/player-studio.tsx b/demo/player-studio.tsx
index 97572a8..5ce76fd 100644
--- a/demo/player-studio.tsx
+++ b/demo/player-studio.tsx
@@ -2,10 +2,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 { VimeoPlayer } from "../src/vimeo/vimeo-player"
 import { CheckIcon } from "./icons"
 import { TouchTarget } from "./ui"
 
-export type Mode = "mux" | "native" | "youtube"
+export type Mode = "mux" | "native" | "youtube" | "vimeo"
 
 // Public sample assets so the studio plays real media with no account or signed
 // tokens — anyone who clones the repo gets the full UI.
@@ -26,6 +27,13 @@ const YOUTUBE_SAMPLE = {
   label: "Big Buck Bunny · YouTube",
 } as const
 
+// A public Vimeo staff-pick video so the Vimeo tab plays for anyone who clones
+// the repo.
+const VIMEO_SAMPLE = {
+  id: "291235566",
+  label: "Vimeo staff pick · Vimeo",
+} as const
+
 export const DEFAULT_ACCENT = "#f4b942"
 const ACCENTS = [
   { name: "Leader", value: DEFAULT_ACCENT },
@@ -61,13 +69,17 @@ export function PlayerStudio({
       ? NATIVE_SAMPLE.label
       : mode === "youtube"
         ? YOUTUBE_SAMPLE.label
-        : activeSample?.label
+        : mode === "vimeo"
+          ? VIMEO_SAMPLE.label
+          : activeSample?.label
   const code =
     mode === "native"
       ? NATIVE_SAMPLE.src
       : mode === "youtube"
         ? YOUTUBE_SAMPLE.id
-        : source
+        : mode === "vimeo"
+          ? VIMEO_SAMPLE.id
+          : source
 
   return (
     <div className="flex flex-col gap-5">
@@ -96,6 +108,13 @@ export function PlayerStudio({
               accentColor={accent}
               theme={{ "--kino-radius": `${radius}px` }}
             />
+          ) : mode === "vimeo" ? (
+            <VimeoPlayer
+              key="vimeo"
+              videoId={VIMEO_SAMPLE.id}
+              accentColor={accent}
+              theme={{ "--kino-radius": `${radius}px` }}
+            />
           ) : (
             <MuxPlayer
               key="mux"
@@ -131,6 +150,7 @@ export function PlayerStudio({
                 { id: "mux", label: "Mux · HLS" },
                 { id: "native", label: "Native · mp4" },
                 { id: "youtube", label: "YouTube · Embed" },
+                { id: "vimeo", label: "Vimeo · Embed" },
               ] as const
             ).map((p) => {
               const active = mode === p.id

From 435155c7c217ed13b9ecc6b478c3b06259c9887c Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:35:20 +0530
Subject: [PATCH 13/21] fix(vimeo): drop auto pseudo-quality + sync rate on
 setPlaybackRate resolve
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Vimeo SDK's getQualities() returns an "auto" pseudo-entry; mapping it
surfaced a bogus "0p" rendition that also matched activeQualityId === "auto",
double-checking the quality menu. Filter it out — kino renders its own Auto row.

setRate relied on a playbackratechange echo that Vimeo does not emit for
programmatic rate changes, leaving the control stuck at the old rate while the
video played at the new one. Patch rate when setPlaybackRate resolves instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/vimeo/provider.test.ts | 33 +++++++++++++++++++++++++++++++--
 src/vimeo/provider.ts      | 28 +++++++++++++++++++---------
 2 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 9c14b7d..e42801b 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -218,6 +218,21 @@ describe("loaded handler", () => {
     provider.destroy()
   })
 
+  it("excludes Vimeo's auto pseudo-quality so no 0p row appears", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player._qualities = [
+      { id: "auto", label: "Auto", active: true },
+      { id: "1080p", label: "1080p", active: false },
+    ]
+    player.emit("loaded")
+    await flush()
+    const s = provider.getState()
+    expect(s.qualities.map((q) => q.id)).toEqual(["1080p"]) // no "auto"/0p row
+    expect(s.qualities.every((q) => q.height > 0)).toBe(true)
+    expect(s.activeQualityId).toBe("auto") // still tracks auto as the active id
+    provider.destroy()
+  })
+
   it("maps text tracks with synthesized ids and flips hasTextTracks", async () => {
     const { provider, player } = await ready({ videoId: "1" })
     player._textTracks = [
@@ -256,11 +271,25 @@ describe("actions", () => {
     provider.destroy()
   })
 
-  it("setRate does NOT patch rate optimistically (waits for the event)", async () => {
+  it("setRate calls the SDK and does not patch rate synchronously", async () => {
     const { provider, player } = await ready({ videoId: "1" })
     provider.actions.setRate(2)
     expect(player.calls).toContainEqual(["setPlaybackRate", 2])
-    expect(provider.getState().rate).toBe(1) // unchanged until the echo event
+    expect(provider.getState().rate).toBe(1) // no optimistic patch
+    provider.destroy()
+  })
+
+  it("patches rate when setPlaybackRate resolves, even without a playbackratechange echo", async () => {
+    const { provider } = await ready({ videoId: "1" })
+    provider.actions.setRate(1.5)
+    expect(provider.getState().rate).toBe(1) // not synchronous
+    await flush() // setPlaybackRate promise resolves; Vimeo emits no echo
+    expect(provider.getState().rate).toBe(1.5)
+    provider.destroy()
+  })
+
+  it("also reflects a native-control playbackratechange echo", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
     player.emit("playbackratechange", { playbackRate: 2 })
     expect(provider.getState().rate).toBe(2)
     provider.destroy()
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 2050c33..b003955 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -113,12 +113,17 @@ function readyVimeo(): VimeoNamespace | null {
 function mapQualities(
   raw: Array<{ id: string; label: string; active: boolean }>,
 ): { qualities: QualityLevel[]; activeId: string } {
-  const qualities = raw.map((q) => ({
-    id: q.id,
-    height: parseInt(q.id, 10) || 0, // id is "2160p"; label "4K" would parse to 4
-    bitrate: 0, // Vimeo exposes no bitrate
-    selected: q.active,
-  }))
+  const qualities = raw
+    // Drop Vimeo's "auto" pseudo-quality: kino renders its own Auto row, and
+    // parseInt("auto") would surface a bogus "0p" rendition that also matches
+    // activeQualityId === "auto", double-checking the menu.
+    .filter((q) => parseInt(q.id, 10) > 0)
+    .map((q) => ({
+      id: q.id,
+      height: parseInt(q.id, 10), // id is "2160p"; label "4K" would parse to 4
+      bitrate: 0, // Vimeo exposes no bitrate
+      selected: q.active,
+    }))
   const active = raw.find((q) => q.active)?.id ?? "auto"
   return { qualities, activeId: active }
 }
@@ -186,9 +191,14 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     },
     setRate: (r) => {
       desiredRate = r
-      // No optimistic patch — rate moves on the playbackratechange echo, so a
-      // plan-gated rejection never leaves the UI showing a rate that didn't take.
-      void player?.setPlaybackRate(r).catch(() => {})
+      // Patch rate when setPlaybackRate resolves (confirms it took). Vimeo does
+      // not emit playbackratechange for a programmatic rate change, so relying
+      // on the echo alone leaves the control stuck at the old rate while the
+      // video plays at the new one.
+      void player
+        ?.setPlaybackRate(r)
+        .then(() => patch({ rate: r }))
+        .catch(() => {})
     },
     setVolume: (v) => void player?.setVolume(v).catch(() => {}),
     setMuted: (m) => void player?.setMuted(m).catch(() => {}),

From 57205e77d87a2fe6abde494e49ba666b42835185 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:35:20 +0530
Subject: [PATCH 14/21] docs(vimeo): reorder studio providers + show Source
 only for Mux

Provider tabs now read Mux, Vimeo, Native, YouTube. The Source picker swaps the
Mux playback id and has no effect on the embed providers, so it's hidden unless
the Mux tab is active.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 demo/player-studio.tsx | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/demo/player-studio.tsx b/demo/player-studio.tsx
index 5ce76fd..dcedad2 100644
--- a/demo/player-studio.tsx
+++ b/demo/player-studio.tsx
@@ -6,7 +6,7 @@ import { VimeoPlayer } from "../src/vimeo/vimeo-player"
 import { CheckIcon } from "./icons"
 import { TouchTarget } from "./ui"
 
-export type Mode = "mux" | "native" | "youtube" | "vimeo"
+export type Mode = "mux" | "vimeo" | "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.
@@ -63,6 +63,10 @@ export function PlayerStudio({
   const [accent, setAccent] = useState<string>(DEFAULT_ACCENT)
   const [radius, setRadius] = useState(DEFAULT_RADIUS)
 
+  // The Source picker swaps the Mux playback id; the embed providers each play a
+  // single fixed sample, so it only applies to Mux.
+  const sourceVisible = showSource && mode === "mux"
+
   const activeSample = SAMPLES.find((s) => s.id === source)
   const label =
     mode === "native"
@@ -148,9 +152,9 @@ export function PlayerStudio({
             {(
               [
                 { id: "mux", label: "Mux · HLS" },
+                { id: "vimeo", label: "Vimeo · Embed" },
                 { id: "native", label: "Native · mp4" },
                 { id: "youtube", label: "YouTube · Embed" },
-                { id: "vimeo", label: "Vimeo · Embed" },
               ] as const
             ).map((p) => {
               const active = mode === p.id
@@ -174,7 +178,7 @@ export function PlayerStudio({
           </div>
         </Control>
 
-        {showSource && (
+        {sourceVisible && (
           <Control
             label="Source"
             className={showRadius ? undefined : "sm:col-span-2"}
@@ -218,7 +222,7 @@ export function PlayerStudio({
 
         <Control
           label="Accent"
-          className={showSource ? undefined : "sm:col-span-2"}
+          className={sourceVisible ? undefined : "sm:col-span-2"}
         >
           <div className="flex flex-wrap items-center gap-2.5">
             {ACCENTS.map((a) => {

From 765f380131c2db0d448a2f909fd11307003bb47e Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 17:55:55 +0530
Subject: [PATCH 15/21] fix(vimeo): advance currentTime on seeking event; guard
 bufferstart during seek
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Seeking past the buffered region appeared stuck/laggy: the seeking event
carries the target seconds (like seeked), but the handler ignored it. While
Vimeo buffers the new position, timeupdate is suppressed, so currentTime — and
the scrubber thumb — held at the pre-seek value. Native/mux read el.currentTime,
which returns the target instantly; mirror that by patching currentTime from the
seeking event.

bufferstart also fired during a paused seek and flipped paused to false with no
later event to correct it, stranding the wrong paused state. Guard it on
!state.seeking so it only reflects an active-playback buffer stall.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/vimeo/provider.test.ts | 73 ++++++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      |  7 ++--
 2 files changed, 78 insertions(+), 2 deletions(-)

diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index e42801b..a2ab4a0 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -264,6 +264,79 @@ describe("actions", () => {
     provider.destroy()
   })
 
+  // Regression: seeking event from SDK must update currentTime to the target
+  // position immediately. Without this, the scrubber stays at the pre-seek
+  // position for the entire buffering window (several seconds on an unbuffered
+  // seek), which the user sees as a "seek that didn't take / laggy seek".
+  it("SDK seeking event immediately advances currentTime to the target", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 30, duration: 120 })
+    expect(provider.getState().currentTime).toBe(30)
+
+    provider.actions.seek(90)
+    player.emit("seeking", { seconds: 90, duration: 120 })
+
+    expect(provider.getState().seeking).toBe(true)
+    expect(provider.getState().currentTime).toBe(90) // scrubber must show target
+    provider.destroy()
+  })
+
+  // Regression: currentTime stays at the target during the buffering window
+  // (no timeupdate/seeked yet) so the scrubber does not snap back.
+  it("currentTime holds at seek target during the buffering window", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("timeupdate", { seconds: 30, duration: 120 })
+    provider.actions.seek(90)
+    player.emit("seeking", { seconds: 90, duration: 120 })
+    player.emit("bufferstart") // buffering starts for the unbuffered region
+
+    // During buffering: scrubber must remain at 90, not snap back to 30
+    expect(provider.getState().currentTime).toBe(90)
+    expect(provider.getState().seeking).toBe(true)
+
+    // Once buffering finishes and seeked fires, seeking clears
+    player.emit("bufferend")
+    player.emit("seeked", { seconds: 90 })
+    expect(provider.getState().currentTime).toBe(90)
+    expect(provider.getState().seeking).toBe(false)
+    provider.destroy()
+  })
+
+  // Regression: bufferstart during a paused seek must not corrupt paused flag.
+  // Previously bufferstart unconditionally patched paused:false. If the user
+  // was paused and sought into an unbuffered region, bufferstart would flip
+  // paused to false; after seeked cleared seeking, the player was physically
+  // paused but kino state said paused:false (no further events to correct it).
+  it("bufferstart during a paused seek does not flip paused to false", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    expect(provider.getState().paused).toBe(true) // default: paused
+
+    provider.actions.seek(90)
+    player.emit("seeking", { seconds: 90, duration: 120 })
+    player.emit("bufferstart") // fires because target is unbuffered
+
+    expect(provider.getState().paused).toBe(true) // must stay paused
+    expect(provider.getState().seeking).toBe(true)
+
+    player.emit("bufferend")
+    player.emit("seeked", { seconds: 90 })
+    expect(provider.getState().paused).toBe(true) // still paused after seek
+    expect(provider.getState().seeking).toBe(false)
+    provider.destroy()
+  })
+
+  // Ensure the original intent of bufferstart is preserved: during active
+  // playback a buffer stall must keep paused:false (no poster-image flash).
+  it("bufferstart during active playback keeps paused false", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    player.emit("play")
+    expect(provider.getState().paused).toBe(false)
+
+    player.emit("bufferstart") // buffer stall mid-playback (not a seek)
+    expect(provider.getState().paused).toBe(false)
+    provider.destroy()
+  })
+
   it("setVolume passes 0..1 unscaled", async () => {
     const { provider, player } = await ready({ videoId: "1" })
     provider.actions.setVolume(0.4)
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index b003955..f7b04c2 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -266,7 +266,7 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     p.on("play", () => patch({ paused: false, ended: false }))
     p.on("pause", () => patch({ paused: true }))
     p.on("ended", () => patch({ paused: true, ended: true }))
-    p.on("bufferstart", () => patch({ paused: false }))
+    p.on("bufferstart", () => { if (!state.seeking) patch({ paused: false }) })
     p.on("bufferend", () => {})
     p.on("timeupdate", (d) => {
       const e = d as { seconds: number; duration: number }
@@ -282,7 +282,10 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
       const duration = e.duration ?? state.duration
       patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] })
     })
-    p.on("seeking", () => patch({ seeking: true }))
+    p.on("seeking", (d) => {
+      const e = d as { seconds?: number }
+      patch({ seeking: true, currentTime: e?.seconds ?? state.currentTime })
+    })
     p.on("seeked", (d) => {
       const e = d as { seconds?: number }
       patch({ seeking: false, ended: false, currentTime: e?.seconds ?? state.currentTime })

From f5bb39abe0a3b7c865fad198b8c81c83abce5a4f Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 18:05:18 +0530
Subject: [PATCH 16/21] =?UTF-8?q?docs:=20design=20spec=20=E2=80=94=20demo?=
 =?UTF-8?q?=20copy-as-markdown=20+=20llms.txt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...6-28-demo-copy-markdown-llms-txt-design.md | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md

diff --git a/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md b/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md
new file mode 100644
index 0000000..900d51b
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md
@@ -0,0 +1,53 @@
+# Demo: Copy-as-Markdown buttons + `/llms.txt` — design
+
+**Goal:** Make the kino demo site (kino.karnstack.com) easy to feed to an LLM:
+a per-page "Copy as Markdown" button, and a root `/llms.txt` index following the
+[llms.txt standard](https://llmstxt.org).
+
+**Status:** approved 2026-06-28. Scope ~5 files in `demo/`.
+
+## Decisions (user-approved)
+
+- **llms.txt delivery:** static file at `/llms.txt` (not a rendered SPA page) —
+  correct `text/markdown` content type, the location crawlers/LLMs fetch. Plus a
+  discoverable footer link.
+- **llms.txt depth:** index only (summary + curated links). No `llms-full.txt`.
+- **Markdown source:** co-located per-page markdown const. No DOM-derivation, no
+  markdown-render library.
+
+## Components
+
+### 1. Per-page markdown source
+Each page file (`overview`, `install`, `providers`, `theming`) gains a
+co-located `const markdown = \`…\`` — a concise, LLM-pasteable markdown of the
+page: H1 title, the prose, and the key code blocks. Authored to be useful to an
+LLM, not a literal DOM mirror. Kept in rough sync with the JSX by hand (4 small
+pages, low churn).
+
+### 2. `CopyMarkdownButton` (shared, `demo/ui.tsx`)
+Reuses the existing `useCopied()` hook (clipboard + 1.4s copied state). A labeled
+secondary button: `CopyIcon` + "Copy as Markdown", flipping to `CheckIcon` +
+"Copied". Rendered by `PageHeader` when given an optional `markdown` prop
+(top-right of the eyebrow row); the overview hero renders it inline near its
+eyebrow.
+
+### 3. `/llms.txt` static file (`demo/public/llms.txt`)
+New `demo/public/` dir (Vite `root: demo` serves `public/` at the site root and
+copies it to `demo/dist/` on build; the Worker serves `demo/dist` static assets
+ahead of its SPA fallback). Hand-authored to the standard:
+- `# kino` + a one-line blockquote summary
+- `## Docs` — links to the four pages (absolute `https://kino.karnstack.com/…`)
+  with a short note each
+- `## Reference` — npm entry points (`@karnstack/kino`, `/mux`, `/native`,
+  `/youtube`, `/vimeo`), the GitHub repo, and the README
+
+A footer link to `/llms.txt` in `shell.tsx` makes it discoverable.
+
+## Out of scope (YAGNI)
+`llms-full.txt`; DOM-derived markdown; a markdown-render dependency; any router
+or build-pipeline change beyond adding `demo/public/`.
+
+## Verification
+No demo unit tests exist. Gate: `pnpm build` emits `demo/dist/llms.txt`;
+`pnpm typecheck` + `pnpm lint` clean; a headless screenshot of a doc page shows
+the button.

From 95befab9f507da87737e5fb229369a833dd4398c Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 18:05:18 +0530
Subject: [PATCH 17/21] feat(demo): copy-as-markdown button per page +
 /llms.txt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each docs page gets a 'Copy as Markdown' button (top-right of the header) that
copies a co-located markdown rendering of the page — handy for pasting into an
LLM. Adds /llms.txt (served as text/plain at the site root, ahead of the SPA
fallback) following the llms.txt standard: a summary plus curated links to the
four pages, the npm entry points, GitHub, and the README. A footer link makes it
discoverable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 demo/pages/install.tsx   | 105 +++++++++++++++++++++++++++++++++++++++
 demo/pages/overview.tsx  |  24 ++++++++-
 demo/pages/providers.tsx |  39 +++++++++++++++
 demo/pages/theming.tsx   |  56 +++++++++++++++++++++
 demo/public/llms.txt     |  16 ++++++
 demo/shell.tsx           |   6 +++
 demo/ui.tsx              |  27 +++++++++-
 7 files changed, 271 insertions(+), 2 deletions(-)
 create mode 100644 demo/public/llms.txt

diff --git a/demo/pages/install.tsx b/demo/pages/install.tsx
index 98b990e..ff5970f 100644
--- a/demo/pages/install.tsx
+++ b/demo/pages/install.tsx
@@ -142,6 +142,110 @@ const VIMEO_PROPS: Prop[] = [
   ...SHARED_PROPS,
 ]
 
+const markdown = `# Up and running.
+
+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.
+
+## Add the package
+
+\`\`\`bash
+pnpm add @karnstack/kino
+\`\`\`
+
+Import the stylesheet once with \`import "@karnstack/kino/styles.css"\`, then give the player a sized container — it fills the full width and height of its parent.
+
+## Quick start
+
+### Mux
+
+\`\`\`tsx
+${MUX_SNIPPET}
+\`\`\`
+
+### Native
+
+\`\`\`tsx
+${NATIVE_SNIPPET}
+\`\`\`
+
+### YouTube
+
+\`\`\`tsx
+${YOUTUBE_SNIPPET}
+\`\`\`
+
+### Vimeo
+
+\`\`\`tsx
+${VIMEO_SNIPPET}
+\`\`\`
+
+## API
+
+### MuxPlayer
+
+| Prop | Type | Description |
+|---|---|---|
+| playbackId | string | Mux playback id. Required. |
+| tokens | { playback?, thumbnail?, storyboard? } | Signed-playback tokens, minted server-side. |
+| poster | string | Override the derived Mux thumbnail. |
+| metadata | { videoId?, videoTitle?, viewerUserId? } | Mux Data metadata. |
+| autoPlay | boolean | Start playback on mount. |
+| defaultRate | number | Initial playback rate. |
+| accentColor | string | Accent color — any CSS color. |
+| theme | Record<string, string> | Inline CSS custom properties on the root. |
+| placeholder | string | Blur-up still painted until the poster loads. |
+| className | string | Extra class on the .kino root. |
+
+### NativePlayer
+
+| Prop | Type | Description |
+|---|---|---|
+| src | string | Raw media URL — mp4, webm, ogg. Required. |
+| poster | string | Poster image URL. |
+| tracks | NativeTextTrack[] | Sidecar subtitle / caption tracks. |
+| autoPlay | boolean | Start playback on mount. |
+| muted | boolean | Start muted. |
+| loop | boolean | Loop playback. |
+| defaultRate | number | Initial playback rate. |
+| crossOrigin | "anonymous" \\| "use-credentials" | CORS mode for cross-origin media and tracks. |
+| metadata | { videoId?, videoTitle?, viewerUserId? } | OS media-session metadata. |
+| accentColor | string | Accent color — any CSS color. |
+| theme | Record<string, string> | Inline CSS custom properties on the root. |
+| placeholder | string | Blur-up still painted until the poster loads. |
+| className | string | Extra class on the .kino root. |
+
+### YouTubePlayer
+
+| Prop | Type | Description |
+|---|---|---|
+| 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. |
+| accentColor | string | Accent color — any CSS color. |
+| theme | Record<string, string> | Inline CSS custom properties on the root. |
+| placeholder | string | Blur-up still painted until the poster loads. |
+| className | string | Extra class on the .kino root. |
+
+### VimeoPlayer
+
+| Prop | Type | Description |
+|---|---|---|
+| videoId | string | Vimeo video id or any Vimeo share URL. Required. |
+| hash | string | Privacy hash for unlisted videos. |
+| 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. |
+| accentColor | string | Accent color — any CSS color. |
+| theme | Record<string, string> | Inline CSS custom properties on the root. |
+| placeholder | string | Blur-up still painted until the poster loads. |
+| className | string | Extra class on the .kino root. |`
+
 const propRows = (props: Prop[]) =>
   props.map(([name, type, desc]) => ({
     key: name,
@@ -155,6 +259,7 @@ export function InstallPage() {
         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, while the native and YouTube providers need nothing extra — YouTube loads the IFrame API at runtime."
+        markdown={markdown}
       />
 
       <section className="flex flex-col gap-6">
diff --git a/demo/pages/overview.tsx b/demo/pages/overview.tsx
index 72eebed..b813caf 100644
--- a/demo/pages/overview.tsx
+++ b/demo/pages/overview.tsx
@@ -4,6 +4,7 @@ import {
   btnPrimary,
   btnSecondary,
   CopyButton,
+  CopyMarkdownButton,
   Eyebrow,
   FrameNumber,
 } from "../ui"
@@ -11,6 +12,24 @@ import { ArrowRightIcon } from "../icons"
 
 const INSTALL = "pnpm add @karnstack/kino"
 
+const markdown = `# Glass chrome for every video.
+
+kino is a themeable React video player with a pluggable-provider architecture. The same translucent, keyboard-first UI sits over Mux, raw files, YouTube, and Vimeo — behind a small typed surface.
+
+\`\`\`bash
+${INSTALL}
+\`\`\`
+
+## Why kino
+
+**01 — Pluggable providers.** One UI contract, many engines. Mux HLS, raw files, YouTube, and Vimeo all ship today.
+
+**02 — Keyboard-first.** Play, seek, speed, captions, and fullscreen are all driven from the keyboard out of the box.
+
+**03 — Themeable.** Set the accent with a single prop, or repaint every surface through CSS custom properties.
+
+**04 — Capability-aware.** Controls hide themselves when the active engine or platform can't support them — never a dead button.`
+
 const HIGHLIGHTS = [
   {
     n: "01",
@@ -42,7 +61,10 @@ export function OverviewPage() {
   return (
     <div className="flex flex-col gap-20 lg:gap-28">
       <section className="flex flex-col gap-7 pt-2">
-        <Eyebrow>React video player</Eyebrow>
+        <div className="flex items-start justify-between gap-4">
+          <Eyebrow>React video player</Eyebrow>
+          <CopyMarkdownButton markdown={markdown} />
+        </div>
         <div>
           <h1 className="max-w-[18ch] font-display text-5xl font-semibold tracking-tight text-balance text-paper sm:text-6xl">
             Glass chrome for every video.
diff --git a/demo/pages/providers.tsx b/demo/pages/providers.tsx
index 4d10130..5c61b5a 100644
--- a/demo/pages/providers.tsx
+++ b/demo/pages/providers.tsx
@@ -54,6 +54,44 @@ const PROVIDER_CONTRACT = `export interface Provider {
   swapSource?(opts: SourceOptions): void
 }`
 
+const markdown = `# One UI, many engines.
+
+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 any backend.
+
+## Providers
+
+**Mux** (\`@karnstack/kino/mux\`) — Adaptive HLS through the @mux/mux-video element — renditions, storyboard scrub previews, captions, and signed playback.
+
+\`\`\`ts
+import { MuxPlayer } from "@karnstack/kino/mux"
+\`\`\`
+
+**Native** (\`@karnstack/kino/native\`) — A native <video> element over any raw mp4, webm, or ogg URL. No streaming engine, no account, nothing to register.
+
+\`\`\`ts
+import { NativePlayer } from "@karnstack/kino/native"
+\`\`\`
+
+**YouTube** (\`@karnstack/kino/youtube\`) — 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.
+
+\`\`\`ts
+import { YouTubePlayer } from "@karnstack/kino/youtube"
+\`\`\`
+
+**Vimeo** (\`@karnstack/kino/vimeo\`) — The Vimeo Player SDK under the same kino chrome — quality, styled captions, picture-in-picture, and rate. Chromeless playback needs a paid Vimeo plan.
+
+\`\`\`ts
+import { VimeoPlayer } from "@karnstack/kino/vimeo"
+\`\`\`
+
+## The contract
+
+A provider is a handful of methods. Implement \`mount\`, a \`getState\` / \`subscribe\` pair, an \`actions\` object, and \`destroy\`. The UI reads everything through this surface — it never talks to an engine directly.
+
+\`\`\`ts
+${PROVIDER_CONTRACT}
+\`\`\``
+
 export function ProvidersPage() {
   return (
     <div className="flex flex-col gap-16">
@@ -61,6 +99,7 @@ export function ProvidersPage() {
         eyebrow="Architecture"
         title="One UI, many engines."
         lead="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 any backend."
+        markdown={markdown}
       />
 
       <section className="flex flex-col gap-6">
diff --git a/demo/pages/theming.tsx b/demo/pages/theming.tsx
index a117462..d1288ed 100644
--- a/demo/pages/theming.tsx
+++ b/demo/pages/theming.tsx
@@ -81,6 +81,61 @@ const CAPABILITIES = [
   },
 ]
 
+const markdown = `# Make it yours.
+
+The quickest knob is the accentColor prop. For deeper control, every visual is driven by CSS custom properties on the .kino root — override them in your own stylesheet or pass a theme object inline.
+
+## Accent prop
+
+\`\`\`tsx
+${ACCENT_SNIPPET}
+\`\`\`
+
+## Custom properties
+
+| Property | Default | Role |
+|---|---|---|
+| --kino-accent | oklch(50.8% 0.118 165.612) | Progress, active items, ranges |
+| --kino-radius | 12px | Corner radius of glass surfaces |
+| --kino-surface | color-mix(in oklab, black 55%, transparent) | Glass surface fill |
+| --kino-surface-strong | color-mix(in oklab, black 70%, transparent) | Stronger surface (idle play) |
+| --kino-border | color-mix(in oklab, white 14%, transparent) | Hairline borders |
+| --kino-text | oklch(98% 0 0) | Primary text and icons |
+| --kino-text-dim | color-mix(in oklab, white 65%, transparent) | Secondary text (timecode) |
+| --kino-blur | 18px | Backdrop blur radius |
+| --kino-shadow | 0 8px 40px rgba(0,0,0,0.45) | Surface drop shadow |
+| --kino-ease | cubic-bezier(0.22, 1, 0.36, 1) | Shared transition easing |
+
+\`\`\`css
+${CSS_SNIPPET}
+\`\`\`
+
+## Keyboard
+
+Shortcuts are ignored while a text field is focused, and modifier combinations pass straight through.
+
+| Key | Action |
+|---|---|
+| Space / K | Play / pause |
+| < / > | Decrease / increase playback rate |
+| M | Toggle mute |
+| C | Toggle captions |
+| S | Open the speed menu |
+| F | Toggle fullscreen |
+| 0 – 9 | Seek to 0% – 90% of the duration |
+
+## Capability gating
+
+Each provider reports a capability set, and every control checks it before rendering — so the chrome only ever shows what the current engine and platform can actually do.
+
+**01 — Quality switching.** Hidden when the engine exposes no renditions, and off on iOS where the system owns adaptive playback.
+
+**02 — Fullscreen.** Custom-chrome fullscreen is off on iOS — the platform uses its native fullscreen for the underlying video.
+
+**03 — Picture-in-picture.** Hidden when the browser does not support the PiP API.
+
+**04 — Captions.** The captions menu appears only when the media actually carries subtitle or caption tracks.`
+
 export function ThemingPage() {
   return (
     <div className="flex flex-col gap-16">
@@ -88,6 +143,7 @@ export function ThemingPage() {
         eyebrow="Theming"
         title="Make it yours."
         lead="The quickest knob is the accentColor prop. For deeper control, every visual is driven by CSS custom properties on the .kino root — override them in your own stylesheet or pass a theme object inline."
+        markdown={markdown}
       />
 
       <section className="flex flex-col gap-6">
diff --git a/demo/public/llms.txt b/demo/public/llms.txt
new file mode 100644
index 0000000..ab49dd4
--- /dev/null
+++ b/demo/public/llms.txt
@@ -0,0 +1,16 @@
+# kino
+
+> A themeable, keyboard-first React video player with pluggable providers (Mux HLS, native files, YouTube, Vimeo) under one glass UI. MIT licensed.
+
+## Docs
+
+- [Overview](https://kino.karnstack.com/): what kino is, live playground, why kino.
+- [Install & API](https://kino.karnstack.com/install): install, quick start, the provider/props API.
+- [Providers](https://kino.karnstack.com/providers): the Provider contract and the four shipped providers.
+- [Theming](https://kino.karnstack.com/theming): CSS custom properties, keyboard map, capability gating.
+
+## Reference
+
+- [npm: @karnstack/kino](https://www.npmjs.com/package/@karnstack/kino) — entry points: `@karnstack/kino` (core + MuxPlayer), `/mux`, `/native`, `/youtube`, `/vimeo`, `/styles.css`.
+- [GitHub](https://github.com/karnstack/kino)
+- [README](https://github.com/karnstack/kino/blob/main/README.md)
diff --git a/demo/shell.tsx b/demo/shell.tsx
index 95b3060..fc32cb8 100644
--- a/demo/shell.tsx
+++ b/demo/shell.tsx
@@ -183,6 +183,12 @@ function Footer() {
           >
             npm
           </a>
+          <a
+            href="/llms.txt"
+            className="font-normal text-paper-dim transition-colors hover:text-paper"
+          >
+            llms.txt
+          </a>
         </div>
       </div>
     </footer>
diff --git a/demo/ui.tsx b/demo/ui.tsx
index b124f22..eefa251 100644
--- a/demo/ui.tsx
+++ b/demo/ui.tsx
@@ -106,6 +106,26 @@ export function CopyButton({
   )
 }
 
+/* Copies a page's markdown representation for pasting into an LLM. */
+export function CopyMarkdownButton({ markdown }: { markdown: string }) {
+  const { copied, copy } = useCopied()
+  return (
+    <button
+      type="button"
+      onClick={() => copy(markdown)}
+      aria-label={copied ? "Copied" : "Copy page as Markdown"}
+      className="relative inline-flex shrink-0 items-center gap-1.5 rounded-lg px-2.5 py-1.5 font-mono text-[0.8125rem] text-paper-dim ring-1 ring-white/10 transition-colors hover:bg-white/5 hover:text-paper focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-leader"
+    >
+      {copied ? (
+        <CheckIcon className="size-3.5 text-leader" />
+      ) : (
+        <CopyIcon className="size-3.5" />
+      )}
+      {copied ? "Copied" : "Copy as Markdown"}
+    </button>
+  )
+}
+
 /* The Shiki-highlighted (or plain fallback) body shared by the code surfaces. */
 function CodeBody({ code, html }: { code: string; html: string | null }) {
   return html ? (
@@ -243,14 +263,19 @@ export function PageHeader({
   eyebrow,
   title,
   lead,
+  markdown,
 }: {
   eyebrow: string
   title: string
   lead: string
+  markdown?: string
 }) {
   return (
     <header className="flex flex-col gap-4">
-      <Eyebrow>{eyebrow}</Eyebrow>
+      <div className="flex items-start justify-between gap-4">
+        <Eyebrow>{eyebrow}</Eyebrow>
+        {markdown && <CopyMarkdownButton markdown={markdown} />}
+      </div>
       <h1 className="max-w-[20ch] font-display text-4xl font-semibold tracking-tight text-balance text-paper sm:text-5xl">
         {title}
       </h1>

From 1f9de13f3ec86cfaed74445956e70dd91dc82cde Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 18:46:07 +0530
Subject: [PATCH 18/21] fix(vimeo): grant the SDK iframe picture-in-picture
 permission
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Vimeo SDK builds its cross-origin player.vimeo.com iframe with only
allow="autoplay; encrypted-media". Permissions Policy is enforced at the iframe
boundary, so requestPictureInPicture() inside the frame was silently rejected
(and swallowed by the action's .catch) even though the top document had PiP
enabled — the button did nothing.

Patch the iframe's allow attribute to include picture-in-picture the moment the
SDK inserts it, via a MutationObserver on the host (set before navigation so the
policy is evaluated with the grant present). The observer self-disconnects on
the first iframe and is torn down on destroy(). The test fake now mirrors the
SDK's real default allow list so the patch path is exercised.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/vimeo/fake-vimeo.ts    |  6 +++++-
 src/vimeo/provider.test.ts | 34 ++++++++++++++++++++++++++++++++++
 src/vimeo/provider.ts      | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/src/vimeo/fake-vimeo.ts b/src/vimeo/fake-vimeo.ts
index 96b30e1..681a448 100644
--- a/src/vimeo/fake-vimeo.ts
+++ b/src/vimeo/fake-vimeo.ts
@@ -24,7 +24,11 @@ export class FakeVimeoPlayer {
     this.el = el
     this.opts = opts
     FakeVimeoPlayer.instances.push(this)
-    el.appendChild(document.createElement("iframe")) // the SDK injects an iframe
+    // The SDK injects an iframe; mirror the real default allow list (which omits
+    // picture-in-picture) so tests exercise the provider's PiP allow patch.
+    const iframe = document.createElement("iframe")
+    iframe.setAttribute("allow", "autoplay; encrypted-media")
+    el.appendChild(iframe)
   }
 
   on(event: string, fn: Handler) {
diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index a2ab4a0..af62396 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -429,6 +429,40 @@ describe("captions", () => {
   })
 })
 
+describe("picture-in-picture allow attribute", () => {
+  beforeEach(() => installFakeVimeo())
+  afterEach(() => uninstallFakeVimeo())
+
+  // Regression: the Vimeo SDK creates the iframe with only
+  // allow="autoplay; encrypted-media". Without "picture-in-picture" the browser
+  // silently rejects requestPictureInPicture() inside the cross-origin frame
+  // (Permissions Policy enforcement at the iframe boundary). kino must patch
+  // the attribute via MutationObserver before the frame navigation completes.
+  it("patches allow=picture-in-picture on the SDK-injected iframe", async () => {
+    const provider = createVimeoProvider({ videoId: "1" })
+    const container = mount(provider)
+    await flush()
+    const iframe = container.querySelector("iframe")
+    expect(iframe).not.toBeNull()
+    expect(iframe?.getAttribute("allow")).toContain("picture-in-picture")
+    provider.destroy()
+  })
+
+  it("appends to the SDK's existing allow tokens without dropping them", async () => {
+    // The fake injects allow="autoplay; encrypted-media" like the real SDK.
+    const provider = createVimeoProvider({ videoId: "1" })
+    const container = mount(provider)
+    await flush()
+    const allow = container.querySelector("iframe")!.getAttribute("allow") ?? ""
+    expect(allow).toContain("autoplay")
+    expect(allow).toContain("encrypted-media")
+    expect(allow).toContain("picture-in-picture")
+    // Appended once, not duplicated.
+    expect(allow.split("picture-in-picture").length - 1).toBe(1)
+    provider.destroy()
+  })
+})
+
 describe("swapSource", () => {
   beforeEach(() => installFakeVimeo())
   afterEach(() => uninstallFakeVimeo())
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index f7b04c2..89c53f8 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -155,6 +155,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   let player: VimeoPlayer | null = null
   let destroyed = false
   let desiredRate = opts.defaultRate ?? 1
+  // Watches for the SDK-injected iframe so we can grant it PiP (see createPlayer).
+  let pipObserver: MutationObserver | null = null
 
   let state: MediaState = {
     ...defaultState(),
@@ -341,6 +343,35 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     }
     if (initial.hash) ctorOpts.url = playerUrl(initial.id, initial.hash)
     else ctorOpts.id = initial.id
+
+    // The Vimeo SDK programmatically creates the iframe with only
+    // allow="autoplay; encrypted-media" — "picture-in-picture" is absent.
+    // Browsers enforce Permissions Policy at the iframe boundary: without it,
+    // requestPictureInPicture() inside the cross-origin player.vimeo.com frame
+    // is silently rejected regardless of user gesture. Patch the attribute as
+    // soon as the SDK inserts the iframe so the delegation is present before
+    // the frame's document loads (Permissions Policy is evaluated at navigation
+    // time, not at call time).
+    pipObserver = new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        for (const node of m.addedNodes) {
+          if (node instanceof HTMLIFrameElement) {
+            const current = node.getAttribute("allow") ?? ""
+            if (!current.includes("picture-in-picture")) {
+              node.setAttribute(
+                "allow",
+                current ? `${current}; picture-in-picture` : "picture-in-picture",
+              )
+            }
+            pipObserver?.disconnect()
+            pipObserver = null
+            return
+          }
+        }
+      }
+    })
+    pipObserver.observe(host, { childList: true, subtree: true })
+
     const p = new v.Player(host, ctorOpts)
     player = p
     void p.ready().then(() => {
@@ -389,6 +420,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     actions,
     destroy() {
       destroyed = true
+      pipObserver?.disconnect()
+      pipObserver = null
       document.removeEventListener("fullscreenchange", onFullscreenChange)
       try {
         void player?.destroy()

From ba298cb16a63e9bb5e3d54b838cdd044395f6b77 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 19:22:33 +0530
Subject: [PATCH 19/21] =?UTF-8?q?fix(vimeo):=20disable=20PiP=20=E2=80=94?=
 =?UTF-8?q?=20it=20can't=20be=20driven=20from=20the=20parent=20frame?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Supersedes the previous allow-attribute patch, which was misguided: inspecting
the live embed shows the Vimeo SDK already grants the iframe
allow="…; picture-in-picture; …", so Permissions Policy was never the blocker.

The real cause is cross-frame user-gesture loss. The SDK's
requestPictureInPicture() is a plain postMessage to the cross-origin
player.vimeo.com iframe, and postMessage does not transfer transient user
activation. The iframe's video.requestPictureInPicture() therefore runs without
a gesture and the browser rejects it (NotAllowedError), which the action's
.catch swallowed — so the button silently did nothing. Vimeo's SDK exposes no
capability-delegation path (vimeo/player.js#696, #734, both closed not-planned).

Same limitation as YouTube: set canPiP: false so the dead button is hidden, and
stub enterPiP/exitPiP. Removes the now-pointless MutationObserver allow-patch,
its tests, and the fake's iframe injection.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/vimeo/fake-vimeo.ts    |  5 ----
 src/vimeo/provider.test.ts | 51 ++++++++++++++------------------------
 src/vimeo/provider.ts      | 49 +++++++++---------------------------
 3 files changed, 31 insertions(+), 74 deletions(-)

diff --git a/src/vimeo/fake-vimeo.ts b/src/vimeo/fake-vimeo.ts
index 681a448..a4b21d9 100644
--- a/src/vimeo/fake-vimeo.ts
+++ b/src/vimeo/fake-vimeo.ts
@@ -24,11 +24,6 @@ export class FakeVimeoPlayer {
     this.el = el
     this.opts = opts
     FakeVimeoPlayer.instances.push(this)
-    // The SDK injects an iframe; mirror the real default allow list (which omits
-    // picture-in-picture) so tests exercise the provider's PiP allow patch.
-    const iframe = document.createElement("iframe")
-    iframe.setAttribute("allow", "autoplay; encrypted-media")
-    el.appendChild(iframe)
   }
 
   on(event: string, fn: Handler) {
diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index af62396..2645768 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -368,16 +368,21 @@ describe("actions", () => {
     provider.destroy()
   })
 
-  it("setQuality + PiP call the SDK", async () => {
+  it("setQuality calls the SDK", async () => {
     const { provider, player } = await ready({ videoId: "1" })
     provider.actions.setQuality("1080p")
+    expect(names(player)).toContain("setQuality")
+    provider.destroy()
+  })
+
+  it("enterPiP and exitPiP are no-ops (PiP is not available from the parent frame)", async () => {
+    const { provider, player } = await ready({ videoId: "1" })
+    // Must not throw, and must not call the SDK (postMessage-based PiP rejects
+    // inside the cross-origin iframe without user activation).
     provider.actions.enterPiP()
     provider.actions.exitPiP()
-    expect(names(player)).toEqual([
-      "setQuality",
-      "requestPictureInPicture",
-      "exitPictureInPicture",
-    ])
+    expect(names(player)).not.toContain("requestPictureInPicture")
+    expect(names(player)).not.toContain("exitPictureInPicture")
     provider.destroy()
   })
 })
@@ -429,36 +434,18 @@ describe("captions", () => {
   })
 })
 
-describe("picture-in-picture allow attribute", () => {
+describe("picture-in-picture capability", () => {
   beforeEach(() => installFakeVimeo())
   afterEach(() => uninstallFakeVimeo())
 
-  // Regression: the Vimeo SDK creates the iframe with only
-  // allow="autoplay; encrypted-media". Without "picture-in-picture" the browser
-  // silently rejects requestPictureInPicture() inside the cross-origin frame
-  // (Permissions Policy enforcement at the iframe boundary). kino must patch
-  // the attribute via MutationObserver before the frame navigation completes.
-  it("patches allow=picture-in-picture on the SDK-injected iframe", async () => {
+  // PiP cannot be driven from the parent frame. The Vimeo SDK's
+  // requestPictureInPicture() is a plain postMessage; postMessage does not
+  // transfer transient user activation, so the browser rejects it inside the
+  // cross-origin iframe (vimeo/player.js#696, #734 — closed not-planned).
+  // canPiP: false hides the dead button; same approach as YouTube.
+  it("reports canPiP: false regardless of document.pictureInPictureEnabled", () => {
     const provider = createVimeoProvider({ videoId: "1" })
-    const container = mount(provider)
-    await flush()
-    const iframe = container.querySelector("iframe")
-    expect(iframe).not.toBeNull()
-    expect(iframe?.getAttribute("allow")).toContain("picture-in-picture")
-    provider.destroy()
-  })
-
-  it("appends to the SDK's existing allow tokens without dropping them", async () => {
-    // The fake injects allow="autoplay; encrypted-media" like the real SDK.
-    const provider = createVimeoProvider({ videoId: "1" })
-    const container = mount(provider)
-    await flush()
-    const allow = container.querySelector("iframe")!.getAttribute("allow") ?? ""
-    expect(allow).toContain("autoplay")
-    expect(allow).toContain("encrypted-media")
-    expect(allow).toContain("picture-in-picture")
-    // Appended once, not duplicated.
-    expect(allow.split("picture-in-picture").length - 1).toBe(1)
+    expect(provider.getState().capabilities.canPiP).toBe(false)
     provider.destroy()
   })
 })
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index 89c53f8..bb98ddc 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -155,8 +155,6 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   let player: VimeoPlayer | null = null
   let destroyed = false
   let desiredRate = opts.defaultRate ?? 1
-  // Watches for the SDK-injected iframe so we can grant it PiP (see createPlayer).
-  let pipObserver: MutationObserver | null = null
 
   let state: MediaState = {
     ...defaultState(),
@@ -165,9 +163,16 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     capabilities: {
       canSetRate: true, // best-effort: setPlaybackRate is plan-gated, can't probe
       hasStoryboard: false,
-      canPiP: !!(
-        typeof document !== "undefined" && document.pictureInPictureEnabled
-      ),
+      // PiP is not available from the parent frame. The Vimeo SDK's
+      // requestPictureInPicture() is a plain postMessage to the cross-origin
+      // player.vimeo.com iframe; postMessage does not transfer transient user
+      // activation, so video.requestPictureInPicture() inside the iframe runs
+      // without a user gesture and the browser rejects it (NotAllowedError:
+      // "Must be handling a user gesture…"). The Vimeo SDK has no capability-
+      // delegation path (vimeo/player.js#696, vimeo/player.js#734, closed
+      // not-planned). Same limitation as YouTube — canPiP: false hides the
+      // dead button.
+      canPiP: false,
       canFullscreen: true,
       // Flip on at `loaded` once getQualities/getTextTracks return non-empty.
       canSetQuality: false,
@@ -221,8 +226,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     exitFullscreen: () => {
       if (document.fullscreenElement) void document.exitFullscreen?.()
     },
-    enterPiP: () => void player?.requestPictureInPicture().catch(() => {}),
-    exitPiP: () => void player?.exitPictureInPicture().catch(() => {}),
+    enterPiP: () => {},
+    exitPiP: () => {},
   }
 
   const setSessionMetadata = (title: string) => {
@@ -344,34 +349,6 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     if (initial.hash) ctorOpts.url = playerUrl(initial.id, initial.hash)
     else ctorOpts.id = initial.id
 
-    // The Vimeo SDK programmatically creates the iframe with only
-    // allow="autoplay; encrypted-media" — "picture-in-picture" is absent.
-    // Browsers enforce Permissions Policy at the iframe boundary: without it,
-    // requestPictureInPicture() inside the cross-origin player.vimeo.com frame
-    // is silently rejected regardless of user gesture. Patch the attribute as
-    // soon as the SDK inserts the iframe so the delegation is present before
-    // the frame's document loads (Permissions Policy is evaluated at navigation
-    // time, not at call time).
-    pipObserver = new MutationObserver((mutations) => {
-      for (const m of mutations) {
-        for (const node of m.addedNodes) {
-          if (node instanceof HTMLIFrameElement) {
-            const current = node.getAttribute("allow") ?? ""
-            if (!current.includes("picture-in-picture")) {
-              node.setAttribute(
-                "allow",
-                current ? `${current}; picture-in-picture` : "picture-in-picture",
-              )
-            }
-            pipObserver?.disconnect()
-            pipObserver = null
-            return
-          }
-        }
-      }
-    })
-    pipObserver.observe(host, { childList: true, subtree: true })
-
     const p = new v.Player(host, ctorOpts)
     player = p
     void p.ready().then(() => {
@@ -420,8 +397,6 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     actions,
     destroy() {
       destroyed = true
-      pipObserver?.disconnect()
-      pipObserver = null
       document.removeEventListener("fullscreenchange", onFullscreenChange)
       try {
         void player?.destroy()

From 98b7b05f98d9b5c7d75cc4ea8d25493b93ce06d6 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 19:24:01 +0530
Subject: [PATCH 20/21] docs(vimeo): drop picture-in-picture from the Vimeo
 feature copy

PiP is disabled for Vimeo (can't be driven from the parent frame), so remove it
from the providers card, the page markdown, and the changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/vimeo-provider.md | 6 +++---
 demo/pages/providers.tsx     | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.changeset/vimeo-provider.md b/.changeset/vimeo-provider.md
index 61ad681..41e63bb 100644
--- a/.changeset/vimeo-provider.md
+++ b/.changeset/vimeo-provider.md
@@ -3,6 +3,6 @@
 ---
 
 Add a Vimeo provider (`@karnstack/kino/vimeo`) — the Vimeo Player SDK under
-kino's chrome with quality selection, styled captions, picture-in-picture, and
-playback rate. Supports unlisted videos via a `hash`. Import `VimeoPlayer` or
-the lower-level `createVimeoProvider`.
+kino's chrome with quality selection, styled captions, and playback rate.
+Supports unlisted videos via a `hash`. Import `VimeoPlayer` or the lower-level
+`createVimeoProvider`.
diff --git a/demo/pages/providers.tsx b/demo/pages/providers.tsx
index 5c61b5a..fa411e2 100644
--- a/demo/pages/providers.tsx
+++ b/demo/pages/providers.tsx
@@ -38,7 +38,7 @@ const PROVIDERS: ProviderCard[] = [
     status: "shipped",
     entry: "@karnstack/kino/vimeo",
     detail:
-      "The Vimeo Player SDK under the same kino chrome — quality, styled captions, picture-in-picture, and rate. Chromeless playback needs a paid Vimeo plan.",
+      "The Vimeo Player SDK under the same kino chrome — quality, styled captions, and rate. Chromeless playback needs a paid Vimeo plan.",
     importLine: 'import { VimeoPlayer } from "@karnstack/kino/vimeo"',
   },
 ]
@@ -78,7 +78,7 @@ import { NativePlayer } from "@karnstack/kino/native"
 import { YouTubePlayer } from "@karnstack/kino/youtube"
 \`\`\`
 
-**Vimeo** (\`@karnstack/kino/vimeo\`) — The Vimeo Player SDK under the same kino chrome — quality, styled captions, picture-in-picture, and rate. Chromeless playback needs a paid Vimeo plan.
+**Vimeo** (\`@karnstack/kino/vimeo\`) — The Vimeo Player SDK under the same kino chrome — quality, styled captions, and rate. Chromeless playback needs a paid Vimeo plan.
 
 \`\`\`ts
 import { VimeoPlayer } from "@karnstack/kino/vimeo"

From 889c5e1a6f94fd996d93a577d252139fff9dad8d Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Sun, 28 Jun 2026 20:40:13 +0530
Subject: [PATCH 21/21] style: apply prettier formatting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI's format:check (prettier --check) flagged the Vimeo source and the
docs/superpowers markdown — eslint passed locally but prettier is a separate
gate. Run prettier --write.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-06-28-vimeo-provider.md        | 292 ++++++++++--------
 ...6-28-demo-copy-markdown-llms-txt-design.md |   6 +
 .../specs/2026-06-28-vimeo-provider-design.md |  92 +++---
 src/vimeo/fake-vimeo.ts                       |   4 +-
 src/vimeo/provider.test.ts                    |  12 +-
 src/vimeo/provider.ts                         |  37 ++-
 6 files changed, 261 insertions(+), 182 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-28-vimeo-provider.md b/docs/superpowers/plans/2026-06-28-vimeo-provider.md
index a0e0d9f..b65cd6c 100644
--- a/docs/superpowers/plans/2026-06-28-vimeo-provider.md
+++ b/docs/superpowers/plans/2026-06-28-vimeo-provider.md
@@ -42,10 +42,12 @@
 ## Task 1: Source parsing + URL helper + options type
 
 **Files:**
+
 - Create: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: nothing.
 - Produces:
   - `type VimeoProviderOptions = { videoId: string; hash?: string; metadata?: { videoId?: string; videoTitle?: string; viewerUserId?: string }; autoPlay?: boolean; muted?: boolean; loop?: boolean; defaultRate?: number }`
@@ -159,11 +161,13 @@ git commit -m "feat(vimeo): source parsing + embed-url helper"
 ## Task 2: SDK loader, lifecycle, and the test fake
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Create: `src/vimeo/fake-vimeo.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: `VimeoProviderOptions`, `parseVimeoSource`, `playerUrl` (Task 1).
 - Produces:
   - `function createVimeoProvider(opts: VimeoProviderOptions): Provider`
@@ -288,7 +292,9 @@ export class FakeVimeoPlayer {
 
 export function installFakeVimeo() {
   FakeVimeoPlayer.instances = []
-  ;(window as unknown as { Vimeo?: unknown }).Vimeo = { Player: FakeVimeoPlayer }
+  ;(window as unknown as { Vimeo?: unknown }).Vimeo = {
+    Player: FakeVimeoPlayer,
+  }
 }
 
 export function uninstallFakeVimeo() {
@@ -440,7 +446,9 @@ export type VimeoPlayer = {
   disableTextTrack(): Promise<unknown>
   requestPictureInPicture(): Promise<unknown>
   exitPictureInPicture(): Promise<unknown>
-  loadVideo(idOrOpts: number | string | { id?: number | string; url?: string }): Promise<unknown>
+  loadVideo(
+    idOrOpts: number | string | { id?: number | string; url?: string },
+  ): Promise<unknown>
   destroy(): Promise<unknown>
 }
 type VimeoNamespace = {
@@ -609,10 +617,12 @@ git commit -m "feat(vimeo): SDK loader, player lifecycle, test fake"
 ## Task 3: Event-driven state sync
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: the `createPlayer` / `patch` from Task 2.
 - Produces: a `bindEvents(p: VimeoPlayer)` step inside `createPlayer` registering all playback events. No new exports.
 
@@ -697,52 +707,58 @@ Expected: FAIL — e.g. `timeupdate` does not update state yet.
 In `provider.ts`, replace the temporary single `p.on("play", ...)` line in `createPlayer` with a `bindEvents(p)` call, and add the function inside `createVimeoProvider` (so it closes over `patch`/`state`/`desiredRate`):
 
 ```ts
-  const bindEvents = (p: VimeoPlayer) => {
-    p.on("play", () => patch({ paused: false, ended: false }))
-    p.on("pause", () => patch({ paused: true }))
-    p.on("ended", () => patch({ paused: true, ended: true }))
-    p.on("bufferstart", () => patch({ paused: false }))
-    p.on("bufferend", () => {})
-    p.on("timeupdate", (d) => {
-      const e = d as { seconds: number; duration: number }
-      patch({
-        currentTime: e.seconds ?? 0,
-        duration: e.duration ?? state.duration,
-        seeking: false,
-        readyState: 4,
-      })
-    })
-    p.on("progress", (d) => {
-      const e = d as { duration: number; percent: number }
-      const duration = e.duration ?? state.duration
-      patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] })
-    })
-    p.on("seeking", () => patch({ seeking: true }))
-    p.on("seeked", (d) => {
-      const e = d as { seconds?: number }
-      patch({ seeking: false, ended: false, currentTime: e?.seconds ?? state.currentTime })
-    })
-    p.on("volumechange", (d) => {
-      const e = d as { volume: number; muted?: boolean }
-      patch({ volume: e.volume, muted: e.muted ?? state.muted })
-    })
-    p.on("playbackratechange", (d) => {
-      const e = d as { playbackRate: number }
-      desiredRate = e.playbackRate
-      patch({ rate: e.playbackRate })
-    })
-    p.on("fullscreenchange", (d) => {
-      const e = d as { fullscreen: boolean }
-      patch({ fullscreen: !!e.fullscreen })
+const bindEvents = (p: VimeoPlayer) => {
+  p.on("play", () => patch({ paused: false, ended: false }))
+  p.on("pause", () => patch({ paused: true }))
+  p.on("ended", () => patch({ paused: true, ended: true }))
+  p.on("bufferstart", () => patch({ paused: false }))
+  p.on("bufferend", () => {})
+  p.on("timeupdate", (d) => {
+    const e = d as { seconds: number; duration: number }
+    patch({
+      currentTime: e.seconds ?? 0,
+      duration: e.duration ?? state.duration,
+      seeking: false,
+      readyState: 4,
     })
-    p.on("enterpictureinpicture", () => patch({ pip: true }))
-    p.on("leavepictureinpicture", () => patch({ pip: false }))
-    p.on("error", (d) => {
-      const e = d as { name?: string; message?: string }
-      const message = e.name ? `${e.name}: ${e.message ?? ""}`.trim() : (e.message ?? "Vimeo playback error")
-      patch({ error: { code: 0, message } })
+  })
+  p.on("progress", (d) => {
+    const e = d as { duration: number; percent: number }
+    const duration = e.duration ?? state.duration
+    patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] })
+  })
+  p.on("seeking", () => patch({ seeking: true }))
+  p.on("seeked", (d) => {
+    const e = d as { seconds?: number }
+    patch({
+      seeking: false,
+      ended: false,
+      currentTime: e?.seconds ?? state.currentTime,
     })
-  }
+  })
+  p.on("volumechange", (d) => {
+    const e = d as { volume: number; muted?: boolean }
+    patch({ volume: e.volume, muted: e.muted ?? state.muted })
+  })
+  p.on("playbackratechange", (d) => {
+    const e = d as { playbackRate: number }
+    desiredRate = e.playbackRate
+    patch({ rate: e.playbackRate })
+  })
+  p.on("fullscreenchange", (d) => {
+    const e = d as { fullscreen: boolean }
+    patch({ fullscreen: !!e.fullscreen })
+  })
+  p.on("enterpictureinpicture", () => patch({ pip: true }))
+  p.on("leavepictureinpicture", () => patch({ pip: false }))
+  p.on("error", (d) => {
+    const e = d as { name?: string; message?: string }
+    const message = e.name
+      ? `${e.name}: ${e.message ?? ""}`.trim()
+      : (e.message ?? "Vimeo playback error")
+    patch({ error: { code: 0, message } })
+  })
+}
 ```
 
 Call `bindEvents(p)` in `createPlayer` right after `player = p`.
@@ -764,10 +780,12 @@ git commit -m "feat(vimeo): event-driven state sync"
 ## Task 4: `loaded` handler — duration, qualities, tracks, capabilities
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: Task 2/3 internals.
 - Produces: an async `onLoaded()` bound to the `loaded` event; sets duration, `qualities`/`activeQualityId`, `textTracks`, capability flips, re-asserts rate/mute, and media-session title. A `mapQualities(raw)` and `mapTracks(raw)` helper.
 
@@ -816,7 +834,10 @@ describe("loaded handler", () => {
     await flush()
     const s = provider.getState()
     expect(s.capabilities.hasTextTracks).toBe(true)
-    expect(s.textTracks.map((t) => t.id)).toEqual(["en.captions", "en.subtitles"])
+    expect(s.textTracks.map((t) => t.id)).toEqual([
+      "en.captions",
+      "en.subtitles",
+    ])
     provider.destroy()
   })
 })
@@ -872,44 +893,44 @@ function mapTracks(
 Add the media-session helper (copy from youtube's `setSessionMetadata`) and an `onLoaded` inside `createVimeoProvider`, bound in `bindEvents`:
 
 ```ts
-  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 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 onLoaded = async () => {
-    if (!player) return
-    const p = player
-    const [duration, rawQualities, rawTracks, muted] = await Promise.all([
-      p.getDuration().catch(() => 0),
-      p.getQualities().catch(() => []),
-      p.getTextTracks().catch(() => []),
-      p.getMuted().catch(() => false),
-    ])
-    if (destroyed) return
-    void p.setPlaybackRate(desiredRate).catch(() => {})
-    const { qualities, activeId } = mapQualities(rawQualities)
-    const tracks = mapTracks(rawTracks)
-    setSessionMetadata(opts.metadata?.videoTitle ?? "Video")
-    patch({
-      duration: duration || state.duration,
-      readyState: 4,
-      muted,
-      qualities,
-      activeQualityId: activeId,
-      textTracks: tracks,
-      capabilities: {
-        ...state.capabilities,
-        canSetQuality: qualities.length > 0,
-        hasTextTracks: tracks.length > 0,
-      },
-    })
-  }
+const onLoaded = async () => {
+  if (!player) return
+  const p = player
+  const [duration, rawQualities, rawTracks, muted] = await Promise.all([
+    p.getDuration().catch(() => 0),
+    p.getQualities().catch(() => []),
+    p.getTextTracks().catch(() => []),
+    p.getMuted().catch(() => false),
+  ])
+  if (destroyed) return
+  void p.setPlaybackRate(desiredRate).catch(() => {})
+  const { qualities, activeId } = mapQualities(rawQualities)
+  const tracks = mapTracks(rawTracks)
+  setSessionMetadata(opts.metadata?.videoTitle ?? "Video")
+  patch({
+    duration: duration || state.duration,
+    readyState: 4,
+    muted,
+    qualities,
+    activeQualityId: activeId,
+    textTracks: tracks,
+    capabilities: {
+      ...state.capabilities,
+      canSetQuality: qualities.length > 0,
+      hasTextTracks: tracks.length > 0,
+    },
+  })
+}
 ```
 
 Bind in `bindEvents`: `p.on("loaded", () => void onLoaded())`. Also add `p.on("qualitychange", (d) => patch({ activeQualityId: (d as { quality: string }).quality }))`.
@@ -931,10 +952,12 @@ git commit -m "feat(vimeo): loaded handler — duration, qualities, tracks, capa
 ## Task 5: Actions
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: `player`, `ready`, `desiredRate`, `patch`.
 - Produces: the fully-implemented `actions` object (replaces the Task 2 stub bodies). Captions action (`setTextTrack`) is stubbed here and completed in Task 6.
 
@@ -999,32 +1022,32 @@ Expected: FAIL — stub actions record nothing.
 Replace the stub `actions` object body in `createVimeoProvider`:
 
 ```ts
-  const actions: PlayerActions = {
-    play: () => void player?.play().catch(() => {}),
-    pause: () => void player?.pause().catch(() => {}),
-    seek: (t) => {
-      patch({ seeking: true })
-      void player?.setCurrentTime(t).catch(() => {})
-    },
-    setRate: (r) => {
-      desiredRate = r
-      // No optimistic patch — rate moves on the playbackratechange echo, so a
-      // plan-gated rejection never leaves the UI showing a rate that didn't take.
-      void player?.setPlaybackRate(r).catch(() => {})
-    },
-    setVolume: (v) => void player?.setVolume(v).catch(() => {}),
-    setMuted: (m) => void player?.setMuted(m).catch(() => {}),
-    setQuality: (id) => void player?.setQuality(id).catch(() => {}),
-    setTextTrack: () => {}, // Task 6
-    enterFullscreen: (wrapper) => {
-      if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
-    },
-    exitFullscreen: () => {
-      if (document.fullscreenElement) void document.exitFullscreen?.()
-    },
-    enterPiP: () => void player?.requestPictureInPicture().catch(() => {}),
-    exitPiP: () => void player?.exitPictureInPicture().catch(() => {}),
-  }
+const actions: PlayerActions = {
+  play: () => void player?.play().catch(() => {}),
+  pause: () => void player?.pause().catch(() => {}),
+  seek: (t) => {
+    patch({ seeking: true })
+    void player?.setCurrentTime(t).catch(() => {})
+  },
+  setRate: (r) => {
+    desiredRate = r
+    // No optimistic patch — rate moves on the playbackratechange echo, so a
+    // plan-gated rejection never leaves the UI showing a rate that didn't take.
+    void player?.setPlaybackRate(r).catch(() => {})
+  },
+  setVolume: (v) => void player?.setVolume(v).catch(() => {}),
+  setMuted: (m) => void player?.setMuted(m).catch(() => {}),
+  setQuality: (id) => void player?.setQuality(id).catch(() => {}),
+  setTextTrack: () => {}, // Task 6
+  enterFullscreen: (wrapper) => {
+    if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
+  },
+  exitFullscreen: () => {
+    if (document.fullscreenElement) void document.exitFullscreen?.()
+  },
+  enterPiP: () => void player?.requestPictureInPicture().catch(() => {}),
+  exitPiP: () => void player?.exitPictureInPicture().catch(() => {}),
+}
 ```
 
 (`actions` is referenced by the returned object; defining it before the `return` is fine since the return already references `actions`.)
@@ -1046,10 +1069,12 @@ git commit -m "feat(vimeo): player actions"
 ## Task 6: Captions — cue rendering + track selection
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: `mapTracks` ids (Task 4), `player`, `patch`, `state`.
 - Produces: real `setTextTrack` + `cuechange`/`texttrackchange` handling. A `trackRef(id)` lookup that resolves a synthesized id back to `{ language, kind }`.
 
@@ -1064,7 +1089,12 @@ describe("captions", () => {
     const r = await ready({ videoId: "1" })
     r.player._textTracks = [
       { label: "English", language: "en", kind: "captions", mode: "disabled" },
-      { label: "Français", language: "fr", kind: "subtitles", mode: "disabled" },
+      {
+        label: "Français",
+        language: "fr",
+        kind: "subtitles",
+        mode: "disabled",
+      },
     ]
     r.player.emit("loaded")
     await flush()
@@ -1129,21 +1159,21 @@ Replace `setTextTrack: () => {}` in `actions`:
 Add to `bindEvents`:
 
 ```ts
-    p.on("cuechange", (d) => {
-      const e = d as { cues?: Array<{ text?: string }> }
-      patch({ activeCueText: e.cues?.[0]?.text ?? "" })
-    })
-    p.on("texttrackchange", (d) => {
-      const e = d as { language: string | null; kind: string | null }
-      if (e.language == null) {
-        patch({ activeTextTrackId: null, activeCueText: "" })
-        return
-      }
-      const match = state.textTracks.find(
-        (t) => t.lang === e.language && t.kind === e.kind,
-      )
-      patch({ activeTextTrackId: match?.id ?? state.activeTextTrackId })
-    })
+p.on("cuechange", (d) => {
+  const e = d as { cues?: Array<{ text?: string }> }
+  patch({ activeCueText: e.cues?.[0]?.text ?? "" })
+})
+p.on("texttrackchange", (d) => {
+  const e = d as { language: string | null; kind: string | null }
+  if (e.language == null) {
+    patch({ activeTextTrackId: null, activeCueText: "" })
+    return
+  }
+  const match = state.textTracks.find(
+    (t) => t.lang === e.language && t.kind === e.kind,
+  )
+  patch({ activeTextTrackId: match?.id ?? state.activeTextTrackId })
+})
 ```
 
 - [ ] **Step 4: Run to verify it passes**
@@ -1163,10 +1193,12 @@ git commit -m "feat(vimeo): captions — overlay cues + track selection"
 ## Task 7: `swapSource` + the hash channel
 
 **Files:**
+
 - Modify: `src/vimeo/provider.ts`
 - Test: `src/vimeo/provider.test.ts`
 
 **Interfaces:**
+
 - Consumes: `parseVimeoSource`, `playerUrl`, `player`, `ready`, `desiredRate`, `patch`.
 - Produces: the optional `swapSource(opts: SourceOptions)` method on the returned provider. It reads the packed `src` string (bare id, or a `?h=` URL when unlisted).
 
@@ -1254,11 +1286,13 @@ git commit -m "feat(vimeo): swapSource with hash channel"
 ## Task 8: `<VimeoPlayer>` React wrapper + entry re-export
 
 **Files:**
+
 - Create: `src/vimeo/vimeo-player.tsx`
 - Create: `src/vimeo.ts`
 - Test: `src/vimeo/vimeo-player.test.tsx`
 
 **Interfaces:**
+
 - Consumes: `createVimeoProvider`, `VimeoProviderOptions`, `parseVimeoSource`, `playerUrl`.
 - Produces: `function VimeoPlayer(props): JSX.Element`, `type VimeoPlayerProps`. `src/vimeo.ts` re-exports everything public.
 
@@ -1437,10 +1471,12 @@ git commit -m "feat(vimeo): VimeoPlayer React wrapper + entry"
 ## Task 9: Build wiring
 
 **Files:**
+
 - Modify: `package.json` (`exports`, `keywords`)
 - Modify: `tsdown.config.ts` (`entry.vimeo`)
 
 **Interfaces:**
+
 - Consumes: `src/vimeo.ts` (Task 8).
 - Produces: published `@karnstack/kino/vimeo` entry.
 
@@ -1468,9 +1504,11 @@ In `tsdown.config.ts`, add to `entry`:
 - [ ] **Step 3: Verify the build, types, lint, and tests all pass**
 
 Run:
+
 ```bash
 pnpm build && pnpm typecheck && pnpm lint && pnpm test
 ```
+
 Expected: `dist/vimeo.js` and `dist/vimeo.d.ts` emitted; typecheck clean; lint clean; all tests PASS.
 
 - [ ] **Step 4: Commit**
@@ -1485,10 +1523,12 @@ git commit -m "build(vimeo): wire ./vimeo entry point"
 ## Task 10: Docs, demo, changeset
 
 **Files:**
+
 - Modify: `README.md`, `demo/pages/providers.tsx`, `demo/pages/install.tsx`, `demo/pages/overview.tsx`, `demo/player-studio.tsx`
 - Create: `.changeset/vimeo-provider.md`
 
 **Interfaces:**
+
 - Consumes: the shipped provider + `<VimeoPlayer>`.
 - Produces: docs/demo that advertise four shipped providers.
 
@@ -1560,9 +1600,11 @@ the lower-level `createVimeoProvider`.
 - [ ] **Step 5: Verify the demo builds + full check**
 
 Run:
+
 ```bash
 pnpm build && pnpm typecheck && pnpm lint && pnpm test
 ```
+
 Expected: all clean/PASS. (Optionally `pnpm dev` and eyeball the Vimeo studio tab per the headless-screenshot workflow.)
 
 - [ ] **Step 6: Commit**
diff --git a/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md b/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md
index 900d51b..b193165 100644
--- a/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md
+++ b/docs/superpowers/specs/2026-06-28-demo-copy-markdown-llms-txt-design.md
@@ -18,6 +18,7 @@ a per-page "Copy as Markdown" button, and a root `/llms.txt` index following the
 ## Components
 
 ### 1. Per-page markdown source
+
 Each page file (`overview`, `install`, `providers`, `theming`) gains a
 co-located `const markdown = \`…\`` — a concise, LLM-pasteable markdown of the
 page: H1 title, the prose, and the key code blocks. Authored to be useful to an
@@ -25,6 +26,7 @@ LLM, not a literal DOM mirror. Kept in rough sync with the JSX by hand (4 small
 pages, low churn).
 
 ### 2. `CopyMarkdownButton` (shared, `demo/ui.tsx`)
+
 Reuses the existing `useCopied()` hook (clipboard + 1.4s copied state). A labeled
 secondary button: `CopyIcon` + "Copy as Markdown", flipping to `CheckIcon` +
 "Copied". Rendered by `PageHeader` when given an optional `markdown` prop
@@ -32,9 +34,11 @@ secondary button: `CopyIcon` + "Copy as Markdown", flipping to `CheckIcon` +
 eyebrow.
 
 ### 3. `/llms.txt` static file (`demo/public/llms.txt`)
+
 New `demo/public/` dir (Vite `root: demo` serves `public/` at the site root and
 copies it to `demo/dist/` on build; the Worker serves `demo/dist` static assets
 ahead of its SPA fallback). Hand-authored to the standard:
+
 - `# kino` + a one-line blockquote summary
 - `## Docs` — links to the four pages (absolute `https://kino.karnstack.com/…`)
   with a short note each
@@ -44,10 +48,12 @@ ahead of its SPA fallback). Hand-authored to the standard:
 A footer link to `/llms.txt` in `shell.tsx` makes it discoverable.
 
 ## Out of scope (YAGNI)
+
 `llms-full.txt`; DOM-derived markdown; a markdown-render dependency; any router
 or build-pipeline change beyond adding `demo/public/`.
 
 ## Verification
+
 No demo unit tests exist. Gate: `pnpm build` emits `demo/dist/llms.txt`;
 `pnpm typecheck` + `pnpm lint` clean; a headless screenshot of a doc page shows
 the button.
diff --git a/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md b/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md
index 0e3ecb0..eca29ec 100644
--- a/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md
+++ b/docs/superpowers/specs/2026-06-28-vimeo-provider-design.md
@@ -28,7 +28,7 @@ rather than polled — the Vimeo SDK emits `timeupdate`.
 - `src/vimeo/provider.ts` — `createVimeoProvider(opts): Provider` +
   `VimeoProviderOptions` type + `parseVimeoSource(input): { id; hash? }` helper.
 - `src/vimeo/vimeo-player.tsx` — `<VimeoPlayer>` (props = `VimeoProviderOptions`
-  + `accentColor/theme/className/placeholder/children`).
+  - `accentColor/theme/className/placeholder/children`).
 - `src/vimeo/provider.test.ts` — vitest, mirroring `youtube/provider.test.ts`
   (fake `window.Vimeo.Player`).
 - `src/vimeo.ts` — entry re-exporting the provider, component, types, helper.
@@ -75,15 +75,15 @@ handler, which fires once video metadata is available.
 
 ```ts
 new Vimeo.Player(host, {
-  id,                 // numeric id (public videos)
-  url,                // player.vimeo.com/video/ID?h=HASH (unlisted — see below)
-  controls: false,    // kino owns the chrome (paid-plan feature — see caveat)
+  id, // numeric id (public videos)
+  url, // player.vimeo.com/video/ID?h=HASH (unlisted — see below)
+  controls: false, // kino owns the chrome (paid-plan feature — see caveat)
   autoplay: !!opts.autoPlay,
   muted: !!opts.muted,
   loop: !!opts.loop,
   playsinline: true,
-  dnt: true,          // do-not-track; no analytics cookies
-  keyboard: false,    // kino owns the keyboard map
+  dnt: true, // do-not-track; no analytics cookies
+  keyboard: false, // kino owns the keyboard map
 })
 ```
 
@@ -114,26 +114,26 @@ carries `{ seconds, duration, percent }` and `progress` carries the buffered
 `{ seconds, duration, percent }`, so `currentTime`/`buffered` stay fresh without
 polling.
 
-| MediaState          | Source                                                            |
-| ------------------- | ---------------------------------------------------------------- |
-| `paused`            | `play` → false; `pause`/`ended` → true; `bufferstart` keeps false |
-| `ended`             | `ended` → true; cleared on `play`/`seeked`/swap                   |
-| `currentTime`       | `timeupdate.seconds` (and `seeked`)                              |
-| `duration`          | `timeupdate.duration` / `getDuration()` at `loaded`              |
-| `buffered`          | `progress.percent` → `[[0, percent * duration]]`                |
-| `rate`              | `playbackratechange.playbackRate` (re-asserted as `desiredRate`) |
-| `volume`            | `volumechange.volume` (already `0..1`, no scaling)              |
-| `muted`             | `volumechange.muted`; `getMuted()` at `loaded`                  |
-| `qualities`         | `getQualities()` at `loaded` → `QualityLevel[]`                 |
-| `activeQualityId`   | active entry id; `qualitychange.quality` (string id) thereafter |
-| `textTracks`        | `getTextTracks()` at `loaded` → `TextTrackInfo[]`               |
-| `activeTextTrackId` | synthesized id of the active track; `null` on `texttrackchange` disable |
-| `activeCueText`     | `cuechange.cues[0].text` (cues rendered in kino's overlay)       |
-| `pip`               | `enterpictureinpicture` / `leavepictureinpicture`               |
-| `fullscreen`        | `fullscreenchange.fullscreen` / `document.fullscreenElement`     |
+| MediaState          | Source                                                                   |
+| ------------------- | ------------------------------------------------------------------------ |
+| `paused`            | `play` → false; `pause`/`ended` → true; `bufferstart` keeps false        |
+| `ended`             | `ended` → true; cleared on `play`/`seeked`/swap                          |
+| `currentTime`       | `timeupdate.seconds` (and `seeked`)                                      |
+| `duration`          | `timeupdate.duration` / `getDuration()` at `loaded`                      |
+| `buffered`          | `progress.percent` → `[[0, percent * duration]]`                         |
+| `rate`              | `playbackratechange.playbackRate` (re-asserted as `desiredRate`)         |
+| `volume`            | `volumechange.volume` (already `0..1`, no scaling)                       |
+| `muted`             | `volumechange.muted`; `getMuted()` at `loaded`                           |
+| `qualities`         | `getQualities()` at `loaded` → `QualityLevel[]`                          |
+| `activeQualityId`   | active entry id; `qualitychange.quality` (string id) thereafter          |
+| `textTracks`        | `getTextTracks()` at `loaded` → `TextTrackInfo[]`                        |
+| `activeTextTrackId` | synthesized id of the active track; `null` on `texttrackchange` disable  |
+| `activeCueText`     | `cuechange.cues[0].text` (cues rendered in kino's overlay)               |
+| `pip`               | `enterpictureinpicture` / `leavepictureinpicture`                        |
+| `fullscreen`        | `fullscreenchange.fullscreen` / `document.fullscreenElement`             |
 | `error`             | `error` → `{ code: 0, message: name ? `${name}: ${message}` : message }` |
-| `readyState`        | 4 once `loaded` fires, else 0                                    |
-| `storyboard`        | null — no scrub-preview source                                  |
+| `readyState`        | 4 once `loaded` fires, else 0                                            |
+| `storyboard`        | null — no scrub-preview source                                           |
 
 `bufferstart`/`bufferend` keep `paused` honest during a mid-playback stall so
 the poster cover doesn't flash (same intent as YouTube's `BUFFERING` handling).
@@ -144,14 +144,14 @@ numeric code**, so `code` is a fixed `0` and `name` is folded into the message.
 
 ## Capabilities
 
-| Capability      | Value                                       | Reason                                                    |
-| --------------- | ------------------------------------------- | --------------------------------------------------------- |
-| `canSetRate`    | true (best-effort — see note)               | `setPlaybackRate` works on Pro/Business; can't be probed cheaply. |
-| `canFullscreen` | true                                        | We fullscreen the kino wrapper; the iframe is inside it.   |
-| `canPiP`        | `!!document.pictureInPictureEnabled`        | SDK `requestPictureInPicture` where the browser allows it. |
-| `canSetQuality` | `getQualities().length > 0` (set at `loaded`) | Quality API is plan-gated; an empty/failed call ⇒ no menu. |
-| `hasTextTracks` | `getTextTracks().length > 0` (set at `loaded`) | `getTextTracks` returns the caption list.              |
-| `hasStoryboard` | false                                       | No scrub-preview source.                                  |
+| Capability      | Value                                          | Reason                                                            |
+| --------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
+| `canSetRate`    | true (best-effort — see note)                  | `setPlaybackRate` works on Pro/Business; can't be probed cheaply. |
+| `canFullscreen` | true                                           | We fullscreen the kino wrapper; the iframe is inside it.          |
+| `canPiP`        | `!!document.pictureInPictureEnabled`           | SDK `requestPictureInPicture` where the browser allows it.        |
+| `canSetQuality` | `getQualities().length > 0` (set at `loaded`)  | Quality API is plan-gated; an empty/failed call ⇒ no menu.        |
+| `hasTextTracks` | `getTextTracks().length > 0` (set at `loaded`) | `getTextTracks` returns the caption list.                         |
+| `hasStoryboard` | false                                          | No scrub-preview source.                                          |
 
 `canSetQuality` and `hasTextTracks` start `false` and flip on once the `loaded`
 handler reads non-empty lists — so a plan that lacks the quality API simply
@@ -169,19 +169,19 @@ All gated on `ready`; all Promise calls carry `.catch(() => {})`; state changes
 land via the echo event, not an optimistic patch (except `seek`, which patches
 `seeking` immediately for responsiveness).
 
-| Action            | Implementation                                                      |
-| ----------------- | ------------------------------------------------------------------ |
-| `play / pause`    | `player.play() / player.pause()`                                   |
-| `seek(t)`         | `player.setCurrentTime(t)`; patch `seeking: true`                  |
-| `setRate(r)`      | store `desiredRate = r`; `player.setPlaybackRate(r)` — `rate` patched on `playbackratechange` |
-| `setVolume(v)`    | `player.setVolume(v)` — `0..1`, no scaling                          |
-| `setMuted(m)`     | `player.setMuted(m)` — `muted` patched on `volumechange`            |
-| `setQuality(id)`  | `player.setQuality(id)` (`"auto"` for adaptive) — patched on `qualitychange` |
-| `setTextTrack(id)`| resolve id → `{language, kind}`; `enableTextTrack(language, kind, false)` or `disableTextTrack()` |
-| `enterFullscreen` | `wrapper.requestFullscreen()` (kino wrapper, controls stay on top)  |
-| `exitFullscreen`  | `document.exitFullscreen()`                                         |
-| `enterPiP`        | `player.requestPictureInPicture()`                                 |
-| `exitPiP`         | `player.exitPictureInPicture()`                                    |
+| Action             | Implementation                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `play / pause`     | `player.play() / player.pause()`                                                                  |
+| `seek(t)`          | `player.setCurrentTime(t)`; patch `seeking: true`                                                 |
+| `setRate(r)`       | store `desiredRate = r`; `player.setPlaybackRate(r)` — `rate` patched on `playbackratechange`     |
+| `setVolume(v)`     | `player.setVolume(v)` — `0..1`, no scaling                                                        |
+| `setMuted(m)`      | `player.setMuted(m)` — `muted` patched on `volumechange`                                          |
+| `setQuality(id)`   | `player.setQuality(id)` (`"auto"` for adaptive) — patched on `qualitychange`                      |
+| `setTextTrack(id)` | resolve id → `{language, kind}`; `enableTextTrack(language, kind, false)` or `disableTextTrack()` |
+| `enterFullscreen`  | `wrapper.requestFullscreen()` (kino wrapper, controls stay on top)                                |
+| `exitFullscreen`   | `document.exitFullscreen()`                                                                       |
+| `enterPiP`         | `player.requestPictureInPicture()`                                                                |
+| `exitPiP`          | `player.exitPictureInPicture()`                                                                   |
 
 ### Quality mapping
 
diff --git a/src/vimeo/fake-vimeo.ts b/src/vimeo/fake-vimeo.ts
index a4b21d9..7800cc6 100644
--- a/src/vimeo/fake-vimeo.ts
+++ b/src/vimeo/fake-vimeo.ts
@@ -111,7 +111,9 @@ export class FakeVimeoPlayer {
 
 export function installFakeVimeo() {
   FakeVimeoPlayer.instances = []
-  ;(window as unknown as { Vimeo?: unknown }).Vimeo = { Player: FakeVimeoPlayer }
+  ;(window as unknown as { Vimeo?: unknown }).Vimeo = {
+    Player: FakeVimeoPlayer,
+  }
 }
 
 export function uninstallFakeVimeo() {
diff --git a/src/vimeo/provider.test.ts b/src/vimeo/provider.test.ts
index 2645768..bdcd62f 100644
--- a/src/vimeo/provider.test.ts
+++ b/src/vimeo/provider.test.ts
@@ -243,7 +243,10 @@ describe("loaded handler", () => {
     await flush()
     const s = provider.getState()
     expect(s.capabilities.hasTextTracks).toBe(true)
-    expect(s.textTracks.map((t) => t.id)).toEqual(["en.captions", "en.subtitles"])
+    expect(s.textTracks.map((t) => t.id)).toEqual([
+      "en.captions",
+      "en.subtitles",
+    ])
     provider.destroy()
   })
 })
@@ -395,7 +398,12 @@ describe("captions", () => {
     const r = await ready({ videoId: "1" })
     r.player._textTracks = [
       { label: "English", language: "en", kind: "captions", mode: "disabled" },
-      { label: "Français", language: "fr", kind: "subtitles", mode: "disabled" },
+      {
+        label: "Français",
+        language: "fr",
+        kind: "subtitles",
+        mode: "disabled",
+      },
     ]
     r.player.emit("loaded")
     await flush()
diff --git a/src/vimeo/provider.ts b/src/vimeo/provider.ts
index bb98ddc..14706ca 100644
--- a/src/vimeo/provider.ts
+++ b/src/vimeo/provider.ts
@@ -1,5 +1,12 @@
 import { defaultState } from "../core/fake-provider"
-import type { MediaState, PlayerActions, Provider, QualityLevel, TextTrackInfo, SourceOptions } from "../core/types"
+import type {
+  MediaState,
+  PlayerActions,
+  Provider,
+  QualityLevel,
+  TextTrackInfo,
+  SourceOptions,
+} from "../core/types"
 
 export type VimeoProviderOptions = {
   // A numeric Vimeo id, or any vimeo.com / player.vimeo.com URL —
@@ -67,7 +74,9 @@ export type VimeoPlayer = {
   disableTextTrack(): Promise<unknown>
   requestPictureInPicture(): Promise<unknown>
   exitPictureInPicture(): Promise<unknown>
-  loadVideo(idOrOpts: number | string | { id?: number | string; url?: string }): Promise<unknown>
+  loadVideo(
+    idOrOpts: number | string | { id?: number | string; url?: string },
+  ): Promise<unknown>
   destroy(): Promise<unknown>
 }
 type VimeoNamespace = {
@@ -218,7 +227,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
       }
       const ref = state.textTracks.find((t) => t.id === id)
       patch({ activeTextTrackId: id })
-      if (ref) void player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {})
+      if (ref)
+        void player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {})
     },
     enterFullscreen: (wrapper) => {
       if (wrapper.requestFullscreen) void wrapper.requestFullscreen()
@@ -231,7 +241,8 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
   }
 
   const setSessionMetadata = (title: string) => {
-    if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return
+    if (typeof navigator === "undefined" || !("mediaSession" in navigator))
+      return
     if (typeof MediaMetadata === "undefined") return
     try {
       navigator.mediaSession.metadata = new MediaMetadata({ title })
@@ -273,7 +284,9 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     p.on("play", () => patch({ paused: false, ended: false }))
     p.on("pause", () => patch({ paused: true }))
     p.on("ended", () => patch({ paused: true, ended: true }))
-    p.on("bufferstart", () => { if (!state.seeking) patch({ paused: false }) })
+    p.on("bufferstart", () => {
+      if (!state.seeking) patch({ paused: false })
+    })
     p.on("bufferend", () => {})
     p.on("timeupdate", (d) => {
       const e = d as { seconds: number; duration: number }
@@ -295,7 +308,11 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     })
     p.on("seeked", (d) => {
       const e = d as { seconds?: number }
-      patch({ seeking: false, ended: false, currentTime: e?.seconds ?? state.currentTime })
+      patch({
+        seeking: false,
+        ended: false,
+        currentTime: e?.seconds ?? state.currentTime,
+      })
     })
     p.on("volumechange", (d) => {
       const e = d as { volume: number; muted?: boolean }
@@ -314,11 +331,15 @@ export function createVimeoProvider(opts: VimeoProviderOptions): Provider {
     p.on("leavepictureinpicture", () => patch({ pip: false }))
     p.on("error", (d) => {
       const e = d as { name?: string; message?: string }
-      const message = e.name ? `${e.name}: ${e.message ?? ""}`.trim() : (e.message ?? "Vimeo playback error")
+      const message = e.name
+        ? `${e.name}: ${e.message ?? ""}`.trim()
+        : (e.message ?? "Vimeo playback error")
       patch({ error: { code: 0, message } })
     })
     p.on("loaded", () => void onLoaded())
-    p.on("qualitychange", (d) => patch({ activeQualityId: (d as { quality: string }).quality }))
+    p.on("qualitychange", (d) =>
+      patch({ activeQualityId: (d as { quality: string }).quality }),
+    )
     p.on("cuechange", (d) => {
       const e = d as { cues?: Array<{ text?: string }> }
       patch({ activeCueText: e.cues?.[0]?.text ?? "" })