@karnstack/kino 0.2.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 <p align="center">
   A themeable React video player with a pluggable-provider architecture —
   translucent glass chrome, keyboard-first controls, and a small typed surface.
-  Mux is the first provider.
+  Mux, raw files, and YouTube are built in.
 </p>
 
 <p align="center">
@@ -24,7 +24,7 @@
 
 > **[Try it live → kino.karnstack.com](https://kino.karnstack.com)** — drop in any public Mux playback ID, pick an accent, and play with the real glass UI.
 
-kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. The Mux provider is built on the `@mux/mux-video` custom element.
+kino ships the player UI and a provider contract. Each provider adapts a streaming engine to that contract, so the same glass chrome can sit on top of different backends. 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
 
@@ -106,6 +106,53 @@ Pass sidecar subtitles/captions via `tracks`, and kino renders the cues in its o
 
 `NativePlayer` also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `crossOrigin` (set the last when the media or a caption track is cross-origin). Quality switching hides itself since a raw file carries no rendition ladder.
 
+## Playing a YouTube video
+
+For a YouTube source, use the YouTube provider. It drives the YouTube IFrame Player API under the same glass chrome, with kino owning the controls and keyboard map (the native YouTube UI is hidden).
+
+```tsx
+import { YouTubePlayer } from "@karnstack/kino/youtube"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <YouTubePlayer
+        videoId="dQw4w9WgXcQ"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+`videoId` accepts a bare id or any `watch`, `youtu.be`, `embed`, or `shorts` URL — kino resolves it (the `parseYouTubeId` helper is exported if you want it directly). It also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `metadata`.
+
+Speed, fullscreen, and captions work. The captions menu lists the video's own subtitle tracks; YouTube renders the cues itself inside the embed, so they appear in YouTube's style rather than kino's caption overlay.
+
+kino plays YouTube through the official IFrame Player API and, per YouTube's terms, **doesn't obscure the player**: before playback and while paused, YouTube shows its own thumbnail, play button, title, and logo, and kino's controls sit alongside them. A few things the API simply doesn't expose, so kino hides those controls: **manual quality** (YouTube dropped it — playback is always automatic), **picture-in-picture**, and **scrub-preview thumbnails** (storyboards aren't available to embeds).
+
+## 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.
@@ -175,7 +222,6 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: YouTube and Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome

package/dist/{captions-BBk_DvTt.js → captions-CGVAzrJq.js}

@@ -1,38 +1,3 @@
-//#region src/core/fake-provider.ts
-const DEFAULT_CAPS = {
-	canSetQuality: true,
-	hasStoryboard: false,
-	canPiP: true,
-	canFullscreen: true,
-	canSetRate: true,
-	hasTextTracks: false
-};
-function defaultState() {
-	return {
-		paused: true,
-		currentTime: 0,
-		duration: 0,
-		buffered: [],
-		rate: 1,
-		volume: 1,
-		muted: false,
-		readyState: 0,
-		seeking: false,
-		ended: false,
-		error: null,
-		qualities: [],
-		activeQualityId: "auto",
-		videoHeight: 0,
-		textTracks: [],
-		activeTextTrackId: null,
-		activeCueText: "",
-		fullscreen: false,
-		pip: false,
-		storyboard: null,
-		capabilities: { ...DEFAULT_CAPS }
-	};
-}
-//#endregion
 //#region src/util/platform.ts
 function detectIOS(ua, maxTouchPoints = 0) {
 	if (/iPhone|iPad|iPod/.test(ua)) return true;
@@ -72,4 +37,4 @@ function activeCueText(tracks, now) {
 	return "";
 }
 //#endregion
-export { detectIOS as n, defaultState as r, activeCueText as t };
+export { detectIOS as n, activeCueText as t };

package/dist/fake-provider-Do3fX4-T.js

@@ -0,0 +1,36 @@
+//#region src/core/fake-provider.ts
+const DEFAULT_CAPS = {
+	canSetQuality: true,
+	hasStoryboard: false,
+	canPiP: true,
+	canFullscreen: true,
+	canSetRate: true,
+	hasTextTracks: false
+};
+function defaultState() {
+	return {
+		paused: true,
+		currentTime: 0,
+		duration: 0,
+		buffered: [],
+		rate: 1,
+		volume: 1,
+		muted: false,
+		readyState: 0,
+		seeking: false,
+		ended: false,
+		error: null,
+		qualities: [],
+		activeQualityId: "auto",
+		videoHeight: 0,
+		textTracks: [],
+		activeTextTrackId: null,
+		activeCueText: "",
+		fullscreen: false,
+		pip: false,
+		storyboard: null,
+		capabilities: { ...DEFAULT_CAPS }
+	};
+}
+//#endregion
+export { defaultState as t };

package/dist/mux.js

@@ -1,5 +1,6 @@
 import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
-import { n as detectIOS, r as defaultState, t as activeCueText } from "./captions-BBk_DvTt.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { n as detectIOS, t as activeCueText } from "./captions-CGVAzrJq.js";
 import { useEffect, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import "@mux/mux-video";

package/dist/native.js

@@ -1,5 +1,6 @@
 import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
-import { n as detectIOS, r as defaultState, t as activeCueText } from "./captions-BBk_DvTt.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { n as detectIOS, t as activeCueText } from "./captions-CGVAzrJq.js";
 import { useEffect, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/native/provider.ts

package/dist/styles.css

@@ -28,11 +28,21 @@
   box-sizing: border-box;
 }
 .kino mux-video,
-.kino video {
+.kino video,
+/* The YouTube provider mounts an <iframe> here; size it like the video. */
+.kino .kino-video-host iframe {
   position: absolute;
   inset: 0;
   width: 100%;
   height: 100%;
+  border: 0;
+}
+/* Let kino's gesture layer own every pointer interaction. Without this the
+   YouTube iframe surfaces its own hover chrome — title, "More videos", a second
+   progress bar — on top of kino's controls. Killing pointer events on the
+   iframe stops YouTube from ever seeing a hover, so only kino's UI shows. */
+.kino .kino-video-host iframe {
+  pointer-events: none;
 }
 .kino .kino-placeholder {
   position: absolute;

package/dist/vimeo.d.ts

@@ -0,0 +1,57 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/vimeo/provider.d.ts
+type VimeoProviderOptions = {
+  videoId: string;
+  hash?: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  defaultRate?: number;
+};
+declare function parseVimeoSource(input: string): {
+  id: string;
+  hash?: string;
+};
+declare function playerUrl(id: string, hash: string): string;
+declare function createVimeoProvider(opts: VimeoProviderOptions): Provider;
+//#endregion
+//#region src/vimeo/vimeo-player.d.ts
+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;
+};
+/**
+ * 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.
+ */
+declare function VimeoPlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: VimeoPlayerProps): import("react").JSX.Element;
+//#endregion
+export { VimeoPlayer, type VimeoPlayerProps, type VimeoProviderOptions, createVimeoProvider, parseVimeoSource, playerUrl };

package/dist/vimeo.js

@@ -0,0 +1,378 @@
+import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/vimeo/provider.ts
+function parseVimeoSource(input) {
+	const trimmed = input.trim();
+	const q = trimmed.match(/[?&]h=([\w]+)/);
+	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 };
+}
+function playerUrl(id, hash) {
+	return `https://player.vimeo.com/video/${id}?h=${hash}`;
+}
+const SDK_SRC = "https://player.vimeo.com/api/player.js";
+let apiPromise = null;
+function loadVimeoAPI() {
+	const w = window;
+	if (w.Vimeo?.Player) return Promise.resolve(w.Vimeo);
+	if (apiPromise) return apiPromise;
+	apiPromise = new Promise((resolve, reject) => {
+		const finish = () => {
+			if (w.Vimeo?.Player) resolve(w.Vimeo);
+			else reject(/* @__PURE__ */ 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() {
+	if (typeof window === "undefined") return null;
+	const v = window.Vimeo;
+	return v && typeof v.Player === "function" ? v : null;
+}
+function mapQualities(raw) {
+	return {
+		qualities: raw.filter((q) => parseInt(q.id, 10) > 0).map((q) => ({
+			id: q.id,
+			height: parseInt(q.id, 10),
+			bitrate: 0,
+			selected: q.active
+		})),
+		activeId: raw.find((q) => q.active)?.id ?? "auto"
+	};
+}
+function mapTracks(raw) {
+	const seen = /* @__PURE__ */ new Map();
+	return raw.map((t) => {
+		const base = `${t.language}.${t.kind}`;
+		const n = seen.get(base) ?? 0;
+		seen.set(base, n + 1);
+		return {
+			id: n === 0 ? base : `${base}.${n}`,
+			kind: t.kind,
+			label: t.label || t.language,
+			lang: t.language,
+			mode: t.mode === "showing" ? "showing" : "disabled"
+		};
+	});
+}
+function createVimeoProvider(opts) {
+	const explicit = parseVimeoSource(opts.videoId);
+	const initial = {
+		id: explicit.id,
+		hash: opts.hash ?? explicit.hash
+	};
+	let player = null;
+	let destroyed = false;
+	let desiredRate = opts.defaultRate ?? 1;
+	let state = {
+		...defaultState(),
+		rate: desiredRate,
+		muted: opts.muted ?? false,
+		capabilities: {
+			canSetRate: true,
+			hasStoryboard: false,
+			canPiP: false,
+			canFullscreen: true,
+			canSetQuality: false,
+			hasTextTracks: false
+		}
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	const patch = (p) => {
+		state = {
+			...state,
+			...p
+		};
+		emit();
+	};
+	const onFullscreenChange = () => patch({ fullscreen: document.fullscreenElement != null });
+	const actions = {
+		play: () => void player?.play().catch(() => {}),
+		pause: () => void player?.pause().catch(() => {}),
+		seek: (t) => {
+			patch({ seeking: true });
+			player?.setCurrentTime(t).catch(() => {});
+		},
+		setRate: (r) => {
+			desiredRate = r;
+			player?.setPlaybackRate(r).then(() => patch({ rate: r })).catch(() => {});
+		},
+		setVolume: (v) => void player?.setVolume(v).catch(() => {}),
+		setMuted: (m) => void player?.setMuted(m).catch(() => {}),
+		setQuality: (id) => void player?.setQuality(id).catch(() => {}),
+		setTextTrack: (id) => {
+			if (id == null) {
+				patch({
+					activeTextTrackId: null,
+					activeCueText: ""
+				});
+				player?.disableTextTrack().catch(() => {});
+				return;
+			}
+			const ref = state.textTracks.find((t) => t.id === id);
+			patch({ activeTextTrackId: id });
+			if (ref) player?.enableTextTrack(ref.lang, ref.kind, false).catch(() => {});
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+		},
+		enterPiP: () => {},
+		exitPiP: () => {}
+	};
+	const setSessionMetadata = (title) => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		if (typeof MediaMetadata === "undefined") return;
+		try {
+			navigator.mediaSession.metadata = new MediaMetadata({ title });
+		} catch {}
+	};
+	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;
+		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) => {
+		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("bufferend", () => {});
+		p.on("timeupdate", (d) => {
+			const e = d;
+			patch({
+				currentTime: e.seconds ?? 0,
+				duration: e.duration ?? state.duration,
+				seeking: false,
+				readyState: 4
+			});
+		});
+		p.on("progress", (d) => {
+			const e = d;
+			const duration = e.duration ?? state.duration;
+			patch({ buffered: duration > 0 ? [[0, e.percent * duration]] : [] });
+		});
+		p.on("seeking", (d) => {
+			patch({
+				seeking: true,
+				currentTime: d?.seconds ?? state.currentTime
+			});
+		});
+		p.on("seeked", (d) => {
+			patch({
+				seeking: false,
+				ended: false,
+				currentTime: d?.seconds ?? state.currentTime
+			});
+		});
+		p.on("volumechange", (d) => {
+			const e = d;
+			patch({
+				volume: e.volume,
+				muted: e.muted ?? state.muted
+			});
+		});
+		p.on("playbackratechange", (d) => {
+			const e = d;
+			desiredRate = e.playbackRate;
+			patch({ rate: e.playbackRate });
+		});
+		p.on("fullscreenchange", (d) => {
+			patch({ fullscreen: !!d.fullscreen });
+		});
+		p.on("enterpictureinpicture", () => patch({ pip: true }));
+		p.on("leavepictureinpicture", () => patch({ pip: false }));
+		p.on("error", (d) => {
+			const e = d;
+			patch({ error: {
+				code: 0,
+				message: e.name ? `${e.name}: ${e.message ?? ""}`.trim() : e.message ?? "Vimeo playback error"
+			} });
+		});
+		p.on("loaded", () => void onLoaded());
+		p.on("qualitychange", (d) => patch({ activeQualityId: d.quality }));
+		p.on("cuechange", (d) => {
+			patch({ activeCueText: d.cues?.[0]?.text ?? "" });
+		});
+		p.on("texttrackchange", (d) => {
+			const e = d;
+			if (e.language == null) {
+				patch({
+					activeTextTrackId: null,
+					activeCueText: ""
+				});
+				return;
+			}
+			patch({ activeTextTrackId: state.textTracks.find((t) => t.lang === e.language && t.kind === e.kind)?.id ?? state.activeTextTrackId });
+		});
+	};
+	const createPlayer = (v, host) => {
+		const ctorOpts = {
+			controls: false,
+			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;
+		p.ready().then(() => {
+			if (destroyed) return;
+		});
+		bindEvents(p);
+	};
+	return {
+		mount(container) {
+			const host = document.createElement("div");
+			container.appendChild(host);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			const v = readyVimeo();
+			if (v) createPlayer(v, host);
+			else loadVimeoAPI().then((loaded) => {
+				if (destroyed) return;
+				if (host.isConnected) createPlayer(loaded, host);
+			});
+		},
+		getState: () => state,
+		subscribe: (l) => {
+			listeners.add(l);
+			return () => listeners.delete(l);
+		},
+		swapSource(next) {
+			if (!player || next.src == null) return;
+			const { id, hash } = parseVimeoSource(next.src);
+			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;
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			try {
+				player?.destroy();
+			} catch {}
+			player = null;
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/vimeo/vimeo-player.tsx
+const packSrc = (videoId, hash) => {
+	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.
+*/
+function VimeoPlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(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 /* @__PURE__ */ jsxs(Player, {
+		provider,
+		accentColor,
+		theme,
+		className,
+		placeholder,
+		children: [
+			/* @__PURE__ */ jsx(IdleOverlay, {}),
+			/* @__PURE__ */ jsx(Captions, {}),
+			/* @__PURE__ */ jsx(ControlBar, {}),
+			children
+		]
+	});
+}
+//#endregion
+export { VimeoPlayer, createVimeoProvider, parseVimeoSource, playerUrl };

package/dist/youtube.d.ts

@@ -0,0 +1,54 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/youtube/provider.d.ts
+type YouTubeProviderOptions = {
+  videoId: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  defaultRate?: number;
+};
+declare function parseYouTubeId(input: string): string;
+declare function createYouTubeProvider(opts: YouTubeProviderOptions): Provider;
+//#endregion
+//#region src/youtube/youtube-player.d.ts
+type YouTubePlayerProps = YouTubeProviderOptions & {
+  accentColor?: string;
+  theme?: Record<string, string>;
+  className?: string; /** Blur-up still painted behind the video until the first frame loads. */
+  placeholder?: string;
+  children?: ReactNode;
+};
+/**
+ * kino's glass chrome over a YouTube video, backed by the YouTube IFrame Player
+ * API. Pass a video id or any watch / youtu.be / embed / shorts URL.
+ *
+ * Only `videoId` and `metadata.videoTitle` are reactive (they flow through
+ * `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read once
+ * when the provider is created — changing them later is a no-op. Remount (e.g.
+ * via `key`) if you need them to change.
+ *
+ * The IFrame API can't expose quality or picture-in-picture, so those controls
+ * hide themselves automatically. Captions work through the API and are rendered
+ * by YouTube inside the embed.
+ *
+ * Per YouTube's API terms, kino doesn't obscure the player: YouTube shows its
+ * own thumbnail, play button, title, and logo before playback and while paused.
+ * kino's controls sit alongside them.
+ */
+declare function YouTubePlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: YouTubePlayerProps): import("react").JSX.Element;
+//#endregion
+export { YouTubePlayer, type YouTubePlayerProps, type YouTubeProviderOptions, createYouTubeProvider, parseYouTubeId };

package/dist/youtube.js

@@ -0,0 +1,293 @@
+import { c as Captions, d as Player, l as IdleOverlay, t as ControlBar } from "./control-bar-B-p1rMgm.js";
+import { t as defaultState } from "./fake-provider-Do3fX4-T.js";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/youtube/provider.ts
+const PLAYING = 1;
+const ENDED = 0;
+const BUFFERING = 3;
+const CAPTION_MODULES = ["captions", "cc"];
+const IFRAME_API_SRC = "https://www.youtube.com/iframe_api";
+function parseYouTubeId(input) {
+	const trimmed = input.trim();
+	if (/^[\w-]{11}$/.test(trimmed)) return trimmed;
+	const m = trimmed.match(/(?:youtu\.be\/|\/embed\/|\/shorts\/|[?&]v=)([\w-]{11})/);
+	return m ? m[1] : trimmed;
+}
+let apiPromise = null;
+function loadYouTubeAPI() {
+	const w = window;
+	if (w.YT?.Player) return Promise.resolve(w.YT);
+	if (apiPromise) return apiPromise;
+	apiPromise = new Promise((resolve) => {
+		const prev = w.onYouTubeIframeAPIReady;
+		w.onYouTubeIframeAPIReady = () => {
+			prev?.();
+			if (w.YT) resolve(w.YT);
+		};
+		if (!document.querySelector(`script[src="${IFRAME_API_SRC}"]`)) {
+			const script = document.createElement("script");
+			script.src = IFRAME_API_SRC;
+			script.async = true;
+			document.head.appendChild(script);
+		}
+	});
+	return apiPromise;
+}
+function readyYT() {
+	if (typeof window === "undefined") return null;
+	const yt = window.YT;
+	return yt && typeof yt.Player === "function" ? yt : null;
+}
+function createYouTubeProvider(opts) {
+	const initialId = parseYouTubeId(opts.videoId);
+	let player = null;
+	let destroyed = false;
+	let ready = false;
+	let ticker;
+	let desiredRate = opts.defaultRate ?? 1;
+	let captionModule = CAPTION_MODULES[0];
+	let captionsSig = "";
+	let state = {
+		...defaultState(),
+		rate: desiredRate,
+		muted: opts.muted ?? false,
+		capabilities: {
+			canSetQuality: false,
+			hasStoryboard: false,
+			canPiP: false,
+			canFullscreen: true,
+			canSetRate: true,
+			hasTextTracks: false
+		}
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	const patch = (p) => {
+		state = {
+			...state,
+			...p
+		};
+		emit();
+	};
+	const onFullscreenChange = () => patch({ fullscreen: document.fullscreenElement != null });
+	const syncFromPlayer = () => {
+		if (!player || !ready) return;
+		if (player.getPlaybackRate() !== desiredRate) player.setPlaybackRate(desiredRate);
+		const ps = player.getPlayerState();
+		const duration = player.getDuration() || 0;
+		const loaded = player.getVideoLoadedFraction() || 0;
+		patch({
+			paused: ps !== PLAYING && ps !== BUFFERING,
+			ended: ps === ENDED,
+			currentTime: player.getCurrentTime() || 0,
+			duration,
+			buffered: duration > 0 ? [[0, loaded * duration]] : [],
+			rate: desiredRate,
+			volume: (player.getVolume() || 0) / 100,
+			muted: player.isMuted(),
+			readyState: 4
+		});
+		syncCaptions();
+	};
+	const syncCaptions = () => {
+		if (!player) return;
+		let list = [];
+		for (const mod of CAPTION_MODULES) try {
+			const got = player.getOption(mod, "tracklist");
+			if (Array.isArray(got)) {
+				list = got;
+				captionModule = mod;
+				if (got.length) break;
+			}
+		} catch {}
+		const tracks = list.map((t) => ({
+			id: t.languageCode,
+			kind: "captions",
+			label: t.displayName || t.languageCode,
+			lang: t.languageCode,
+			mode: state.activeTextTrackId === t.languageCode ? "showing" : "disabled"
+		}));
+		const sig = tracks.map((t) => `${t.id}:${t.mode}`).join("|");
+		if (sig === captionsSig) return;
+		captionsSig = sig;
+		patch({
+			textTracks: tracks,
+			capabilities: {
+				...state.capabilities,
+				hasTextTracks: tracks.length > 0
+			}
+		});
+	};
+	const setSessionMetadata = (title) => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		if (typeof MediaMetadata === "undefined") return;
+		try {
+			navigator.mediaSession.metadata = new MediaMetadata({ title });
+		} catch {}
+	};
+	const startTicker = () => {
+		if (ticker == null) ticker = setInterval(syncFromPlayer, 250);
+	};
+	const actions = {
+		play: () => player?.playVideo(),
+		pause: () => player?.pauseVideo(),
+		seek: (t) => player?.seekTo(t, true),
+		setRate: (r) => {
+			desiredRate = r;
+			player?.setPlaybackRate(r);
+			patch({ rate: r });
+		},
+		setVolume: (v) => player?.setVolume(Math.min(100, Math.max(0, v * 100))),
+		setMuted: (m) => {
+			if (m) player?.mute();
+			else player?.unMute();
+			patch({ muted: m });
+		},
+		setQuality: () => {},
+		setTextTrack: (id) => {
+			patch({ activeTextTrackId: id });
+			try {
+				player?.setOption(captionModule, "track", id == null ? {} : { languageCode: id });
+			} catch {}
+			syncCaptions();
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+		},
+		enterPiP: () => {},
+		exitPiP: () => {}
+	};
+	const createPlayer = (yt, host) => {
+		player = new yt.Player(host, {
+			videoId: initialId,
+			playerVars: {
+				controls: 0,
+				playsinline: 1,
+				rel: 0,
+				modestbranding: 1,
+				disablekb: 1,
+				autoplay: opts.autoPlay ? 1 : 0,
+				mute: opts.muted ? 1 : 0,
+				loop: opts.loop ? 1 : 0,
+				...opts.loop ? { playlist: initialId } : {}
+			},
+			events: {
+				onReady: (e) => {
+					player = e.target;
+					ready = true;
+					player.setPlaybackRate(desiredRate);
+					if (opts.muted) player.mute();
+					for (const mod of CAPTION_MODULES) try {
+						player.loadModule(mod);
+					} catch {}
+					setSessionMetadata(opts.metadata?.videoTitle ?? "Video");
+					syncFromPlayer();
+					startTicker();
+				},
+				onStateChange: syncFromPlayer,
+				onError: (e) => patch({ error: {
+					code: e.data ?? 0,
+					message: "YouTube playback error"
+				} })
+			}
+		});
+	};
+	return {
+		mount(container) {
+			const host = document.createElement("div");
+			container.appendChild(host);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			const yt = readyYT();
+			if (yt) createPlayer(yt, host);
+			else loadYouTubeAPI().then((loaded) => {
+				if (destroyed) return;
+				if (host.isConnected) createPlayer(loaded, host);
+			});
+		},
+		swapSource(next) {
+			if (!player || !ready || next.src == null) return;
+			player.loadVideoById(parseYouTubeId(next.src));
+			if (next.metadata?.videoTitle != null) setSessionMetadata(next.metadata.videoTitle);
+			player.setPlaybackRate(desiredRate);
+			patch({
+				currentTime: 0,
+				duration: 0,
+				ended: false,
+				seeking: false,
+				error: null
+			});
+		},
+		getState: () => state,
+		subscribe: (l) => {
+			listeners.add(l);
+			return () => listeners.delete(l);
+		},
+		actions,
+		destroy() {
+			destroyed = true;
+			ready = false;
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			if (ticker != null) clearInterval(ticker);
+			ticker = void 0;
+			try {
+				player?.destroy();
+			} catch {}
+			player = null;
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/youtube/youtube-player.tsx
+/**
+* kino's glass chrome over a YouTube video, backed by the YouTube IFrame Player
+* API. Pass a video id or any watch / youtu.be / embed / shorts URL.
+*
+* Only `videoId` and `metadata.videoTitle` are reactive (they flow through
+* `swapSource`). `autoPlay`, `muted`, `loop`, and `defaultRate` are read once
+* when the provider is created — changing them later is a no-op. Remount (e.g.
+* via `key`) if you need them to change.
+*
+* The IFrame API can't expose quality or picture-in-picture, so those controls
+* hide themselves automatically. Captions work through the API and are rendered
+* by YouTube inside the embed.
+*
+* Per YouTube's API terms, kino doesn't obscure the player: YouTube shows its
+* own thumbnail, play button, title, and logo before playback and while paused.
+* kino's controls sit alongside them.
+*/
+function YouTubePlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(null);
+	if (providerRef.current === null) providerRef.current = createYouTubeProvider(opts);
+	const provider = providerRef.current;
+	const mountedRef = useRef(false);
+	useEffect(() => {
+		if (!mountedRef.current) {
+			mountedRef.current = true;
+			return;
+		}
+		provider.swapSource?.({
+			src: opts.videoId,
+			metadata: opts.metadata
+		});
+	}, [opts.videoId, opts.metadata?.videoTitle]);
+	return /* @__PURE__ */ jsxs(Player, {
+		provider,
+		accentColor,
+		theme,
+		className,
+		placeholder,
+		children: [
+			/* @__PURE__ */ jsx(IdleOverlay, {}),
+			/* @__PURE__ */ jsx(Captions, {}),
+			/* @__PURE__ */ jsx(ControlBar, {}),
+			children
+		]
+	});
+}
+//#endregion
+export { YouTubePlayer, createYouTubeProvider, parseYouTubeId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karnstack/kino",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Themeable React video player with pluggable providers.",
   "license": "MIT",
   "author": "Karn",
@@ -17,6 +17,8 @@
     "player",
     "react",
     "mux",
+    "youtube",
+    "vimeo",
     "hls",
     "video-player"
   ],
@@ -44,6 +46,14 @@
       "types": "./dist/native.d.ts",
       "import": "./dist/native.js"
     },
+    "./youtube": {
+      "types": "./dist/youtube.d.ts",
+      "import": "./dist/youtube.js"
+    },
+    "./vimeo": {
+      "types": "./dist/vimeo.d.ts",
+      "import": "./dist/vimeo.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "peerDependencies": {