@karnstack/kino 0.1.3 → 0.3.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. Three providers ship today: **Mux** (adaptive HLS via `@mux/mux-video`), **Native** (a plain `<video>` over any raw file URL), and **YouTube** (the IFrame Player API wrapped in the same chrome). Each lives behind its own entry point, so you only pull in the engine you use.
 
 ## Install
 
@@ -67,6 +67,71 @@ Before the poster and first frame load, the video box is empty. Pass a small `pl
 
 The poster itself stays the signed Mux thumbnail (kino derives it from `playbackId` + the `thumbnail` token), so `placeholder` is purely the instant low-res layer underneath.
 
+## Playing a raw URL
+
+For a plain media URL (mp4, webm, ogg, …) — no Mux account or HLS engine — use the native provider. It puts the same glass chrome over a native `<video>` element, so this entry pulls in none of the Mux engine.
+
+```tsx
+import { NativePlayer } from "@karnstack/kino/native"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <NativePlayer
+        src="https://example.com/clip.mp4"
+        poster="https://example.com/clip.jpg"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+Pass sidecar subtitles/captions via `tracks`, and kino renders the cues in its own styled overlay:
+
+```tsx
+<NativePlayer
+  src="https://example.com/clip.mp4"
+  tracks={[
+    {
+      src: "https://example.com/en.vtt",
+      srclang: "en",
+      label: "English",
+      default: true,
+    },
+  ]}
+/>
+```
+
+`NativePlayer` also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `crossOrigin` (set the last when the media or a caption track is cross-origin). Quality switching hides itself since a raw file carries no rendition ladder.
+
+## Playing a YouTube video
+
+For a YouTube source, use the YouTube provider. It drives the YouTube IFrame Player API under the same glass chrome, with kino owning the controls and keyboard map (the native YouTube UI is hidden).
+
+```tsx
+import { YouTubePlayer } from "@karnstack/kino/youtube"
+import "@karnstack/kino/styles.css"
+
+export function Clip() {
+  return (
+    <div style={{ aspectRatio: "16 / 9" }}>
+      <YouTubePlayer
+        videoId="dQw4w9WgXcQ"
+        accentColor="oklch(50.8% 0.118 165.612)"
+      />
+    </div>
+  )
+}
+```
+
+`videoId` accepts a bare id or any `watch`, `youtu.be`, `embed`, or `shorts` URL — kino resolves it (the `parseYouTubeId` helper is exported if you want it directly). It also takes `autoPlay`, `muted`, `loop`, `defaultRate`, and `metadata`.
+
+Speed, fullscreen, and captions work. The captions menu lists the video's own subtitle tracks; YouTube renders the cues itself inside the embed, so they appear in YouTube's style rather than kino's caption overlay.
+
+kino plays YouTube through the official IFrame Player API and, per YouTube's terms, **doesn't obscure the player**: before playback and while paused, YouTube shows its own thumbnail, play button, title, and logo, and kino's controls sit alongside them. A few things the API simply doesn't expose, so kino hides those controls: **manual quality** (YouTube dropped it — playback is always automatic), **picture-in-picture**, and **scrub-preview thumbnails** (storyboards aren't available to embeds).
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.
@@ -136,7 +201,7 @@ pnpm lint       # eslint
 
 ## Roadmap
 
-- More providers: YouTube, file, and Vimeo
+- More providers: Vimeo
 - AirPlay support
 - Chapters
 - Documented headless primitives for fully custom chrome

package/dist/captions-CGVAzrJq.js

@@ -0,0 +1,40 @@
+//#region src/util/platform.ts
+function detectIOS(ua, maxTouchPoints = 0) {
+	if (/iPhone|iPad|iPod/.test(ua)) return true;
+	return /Macintosh/.test(ua) && maxTouchPoints > 1;
+}
+//#endregion
+//#region src/util/captions.ts
+function joinCues(cues) {
+	if (!cues || cues.length === 0) return "";
+	const parts = [];
+	for (let i = 0; i < cues.length; i++) {
+		const c = cues[i];
+		if (c && typeof c.text === "string") parts.push(c.text);
+	}
+	return parts.join("\n").replace(/<[^>]+>/g, "").replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{2,}/g, "\n").trim();
+}
+function activeCueText(tracks, now) {
+	if (!tracks) return "";
+	for (let i = 0; i < tracks.length; i++) {
+		const t = tracks[i];
+		if (!t) continue;
+		if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+		if (t.mode === "disabled") continue;
+		const active = joinCues(t.activeCues);
+		if (active) return active;
+		const all = t.cues;
+		if (all && all.length) {
+			const hits = [];
+			for (let j = 0; j < all.length; j++) {
+				const c = all[j];
+				if (c && c.startTime <= now && now < c.endTime) hits.push(c);
+			}
+			const text = joinCues(hits);
+			if (text) return text;
+		}
+	}
+	return "";
+}
+//#endregion
+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,88 +1,19 @@
 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 { 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";
-//#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/mux/urls.ts
 const IMAGE_HOST = "https://image.mux.com";
 function buildImageUrl(playbackId, kind, token, ext = kind === "storyboard" ? "vtt" : "webp") {
 	const base = `${IMAGE_HOST}/${playbackId}/${kind}.${ext}`;
 	return token ? `${base}?token=${token}` : base;
 }
-function detectIOS(ua) {
-	return /iPhone|iPad|iPod/.test(ua);
-}
-//#endregion
-//#region src/util/captions.ts
-function joinCues(cues) {
-	if (!cues || cues.length === 0) return "";
-	const parts = [];
-	for (let i = 0; i < cues.length; i++) {
-		const c = cues[i];
-		if (c && typeof c.text === "string") parts.push(c.text);
-	}
-	return parts.join("\n").replace(/<[^>]+>/g, "").replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{2,}/g, "\n").trim();
-}
-function activeCueText(tracks, now) {
-	if (!tracks) return "";
-	for (let i = 0; i < tracks.length; i++) {
-		const t = tracks[i];
-		if (!t) continue;
-		if (t.kind !== "subtitles" && t.kind !== "captions") continue;
-		if (t.mode === "disabled") continue;
-		const active = joinCues(t.activeCues);
-		if (active) return active;
-		const all = t.cues;
-		if (all && all.length) {
-			const hits = [];
-			for (let j = 0; j < all.length; j++) {
-				const c = all[j];
-				if (c && c.startTime <= now && now < c.endTime) hits.push(c);
-			}
-			const text = joinCues(hits);
-			if (text) return text;
-		}
-	}
-	return "";
-}
 //#endregion
 //#region src/mux/provider.ts
 function createMuxProvider(opts) {
-	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent);
+	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent, navigator.maxTouchPoints);
 	let el = null;
 	let renditions = null;
 	let renditionsBound = false;

package/dist/native.d.ts

@@ -0,0 +1,56 @@
+import { a as Provider } from "./types-D0bLitH2.js";
+import { ReactNode } from "react";
+
+//#region src/native/provider.d.ts
+type NativeTextTrack = {
+  src: string;
+  srclang: string;
+  label: string;
+  kind?: "subtitles" | "captions";
+  default?: boolean;
+};
+type NativeProviderOptions = {
+  src: string;
+  poster?: string;
+  metadata?: {
+    videoId?: string;
+    videoTitle?: string;
+    viewerUserId?: string;
+  };
+  autoPlay?: boolean;
+  defaultRate?: number;
+  muted?: boolean;
+  loop?: boolean;
+  crossOrigin?: "anonymous" | "use-credentials";
+  tracks?: NativeTextTrack[];
+};
+declare function createNativeProvider(opts: NativeProviderOptions): Provider;
+//#endregion
+//#region src/native/native-player.d.ts
+type NativePlayerProps = NativeProviderOptions & {
+  accentColor?: string;
+  theme?: Record<string, string>;
+  className?: string; /** Blur-up still painted behind the video until the poster/first frame loads. */
+  placeholder?: string;
+  children?: ReactNode;
+};
+/**
+ * kino's glass chrome over a plain HTML <video> element, playing a raw media
+ * URL (mp4, webm, ogg, …) directly. Use this when you have a file URL rather
+ * than a Mux playback id.
+ *
+ * Only `src`, `poster`, and `metadata.videoTitle` are reactive (they flow
+ * through `swapSource`). `tracks`, `crossOrigin`, `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.
+ */
+declare function NativePlayer({
+  accentColor,
+  theme,
+  className,
+  placeholder,
+  children,
+  ...opts
+}: NativePlayerProps): import("react").JSX.Element;
+//#endregion
+export { NativePlayer, type NativePlayerProps, type NativeProviderOptions, type NativeTextTrack, createNativeProvider };

package/dist/native.js

@@ -0,0 +1,359 @@
+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 { 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
+function createNativeProvider(opts) {
+	const ios = typeof navigator !== "undefined" && detectIOS(navigator.userAgent, navigator.maxTouchPoints);
+	const tracks = opts.tracks ?? [];
+	let el = null;
+	let state = {
+		...defaultState(),
+		rate: opts.defaultRate ?? 1,
+		muted: opts.muted ?? false,
+		activeTextTrackId: null,
+		capabilities: {
+			canSetQuality: false,
+			hasStoryboard: false,
+			canPiP: typeof document !== "undefined" && "pictureInPictureEnabled" in document,
+			canFullscreen: true,
+			canSetRate: true,
+			hasTextTracks: tracks.length > 0
+		}
+	};
+	let desiredRate = opts.defaultRate ?? 1;
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	const patch = (p) => {
+		state = {
+			...state,
+			...p
+		};
+		emit();
+	};
+	const reload = () => {
+		try {
+			el?.load();
+		} catch {}
+	};
+	const onFullscreenChange = () => patch({ fullscreen: document.fullscreenElement != null });
+	const onWebkitBeginFullscreen = () => patch({ fullscreen: true });
+	const onWebkitEndFullscreen = () => patch({ fullscreen: false });
+	const onEnterPip = () => patch({ pip: true });
+	const onLeavePip = () => patch({ pip: false });
+	let activeTrack = null;
+	const readCueText = () => ios ? "" : activeCueText(el?.textTracks, el?.currentTime ?? 0);
+	const modeForActiveTrack = () => ios ? "showing" : "hidden";
+	const onCueChange = () => patch({ activeCueText: readCueText() });
+	const bindActiveTrack = (track) => {
+		if (activeTrack) activeTrack.removeEventListener("cuechange", onCueChange);
+		activeTrack = track;
+		if (activeTrack) activeTrack.addEventListener("cuechange", onCueChange);
+		patch({ activeCueText: readCueText() });
+	};
+	const applyTextTrackModes = () => {
+		const tt = el?.textTracks;
+		if (!tt) return;
+		const id = state.activeTextTrackId;
+		let next = null;
+		for (let i = 0; i < tt.length; i++) {
+			const t = tt[i];
+			if (!t) continue;
+			if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+			if (id != null && (t.id || String(i)) === id) {
+				const mode = modeForActiveTrack();
+				if (t.mode !== mode) t.mode = mode;
+				next = t;
+			} else if (t.mode !== "disabled") t.mode = "disabled";
+		}
+		if (next !== activeTrack) bindActiveTrack(next);
+	};
+	const readTextTracks = () => {
+		const tt = el?.textTracks;
+		if (!tt) return [];
+		const out = [];
+		for (let i = 0; i < tt.length; i++) {
+			const t = tt[i];
+			if (!t) continue;
+			if (t.kind !== "subtitles" && t.kind !== "captions") continue;
+			out.push({
+				id: t.id || String(i),
+				kind: t.kind,
+				label: t.label,
+				lang: t.language,
+				mode: t.mode
+			});
+		}
+		return out;
+	};
+	const syncFromEl = () => {
+		if (!el) return;
+		if (el.playbackRate !== desiredRate) el.playbackRate = desiredRate;
+		applyTextTrackModes();
+		const ranges = [];
+		for (let i = 0; i < el.buffered.length; i++) ranges.push([el.buffered.start(i), el.buffered.end(i)]);
+		patch({
+			paused: el.paused,
+			currentTime: el.currentTime,
+			duration: el.duration || 0,
+			buffered: ranges,
+			rate: desiredRate,
+			volume: el.volume,
+			muted: el.muted,
+			readyState: el.readyState,
+			seeking: el.seeking,
+			ended: el.ended,
+			error: el.error ? {
+				code: el.error.code,
+				message: el.error.message
+			} : null,
+			videoHeight: el.videoHeight || 0,
+			textTracks: readTextTracks(),
+			activeCueText: readCueText()
+		});
+		if (typeof navigator !== "undefined" && "mediaSession" in navigator) navigator.mediaSession.playbackState = el.paused ? "paused" : "playing";
+	};
+	const MEDIA_SESSION_ACTIONS = [
+		"play",
+		"pause",
+		"seekbackward",
+		"seekforward",
+		"seekto"
+	];
+	const setupMediaSession = () => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		const ms = navigator.mediaSession;
+		const set = (a, h) => {
+			try {
+				ms.setActionHandler(a, h);
+			} catch {}
+		};
+		set("play", () => actions.play());
+		set("pause", () => actions.pause());
+		set("seekbackward", (d) => actions.seek(Math.max(0, state.currentTime - (d.seekOffset || 10))));
+		set("seekforward", (d) => actions.seek(state.currentTime + (d.seekOffset || 10)));
+		set("seekto", (d) => {
+			if (typeof d.seekTime === "number") actions.seek(d.seekTime);
+		});
+		setSessionMetadata(opts.metadata?.videoTitle ?? "Video");
+	};
+	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 teardownMediaSession = () => {
+		if (typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+		for (const a of MEDIA_SESSION_ACTIONS) try {
+			navigator.mediaSession.setActionHandler(a, null);
+		} catch {}
+	};
+	const MEDIA_EVENTS = [
+		"play",
+		"pause",
+		"timeupdate",
+		"durationchange",
+		"progress",
+		"volumechange",
+		"ratechange",
+		"seeking",
+		"seeked",
+		"ended",
+		"loadedmetadata",
+		"canplay",
+		"waiting",
+		"error"
+	];
+	const actions = {
+		play: () => {
+			el?.play?.();
+		},
+		pause: () => el?.pause(),
+		seek: (t) => {
+			if (el) el.currentTime = t;
+		},
+		setRate: (r) => {
+			desiredRate = r;
+			if (el) el.playbackRate = r;
+			patch({ rate: r });
+		},
+		setVolume: (v) => {
+			if (el) el.volume = Math.min(1, Math.max(0, v));
+		},
+		setMuted: (m) => {
+			if (el) el.muted = m;
+		},
+		setQuality: () => {},
+		setTextTrack: (id) => {
+			if (!el?.textTracks) return;
+			patch({ activeTextTrackId: id });
+			applyTextTrackModes();
+		},
+		enterFullscreen: (wrapper) => {
+			if (wrapper.requestFullscreen) wrapper.requestFullscreen();
+			else el?.webkitEnterFullscreen?.();
+		},
+		exitFullscreen: () => {
+			if (document.fullscreenElement) document.exitFullscreen?.();
+			else el?.webkitExitFullscreen?.();
+		},
+		enterPiP: () => {
+			el?.requestPictureInPicture?.();
+		},
+		exitPiP: () => {
+			document.exitPictureInPicture?.();
+		}
+	};
+	const appendTracks = () => {
+		if (!el) return;
+		let activeId = null;
+		tracks.forEach((t, i) => {
+			const node = document.createElement("track");
+			node.kind = t.kind ?? "subtitles";
+			node.src = t.src;
+			node.srclang = t.srclang;
+			node.label = t.label;
+			node.id = `kino-track-${i}`;
+			el.appendChild(node);
+			if (t.default && activeId == null) activeId = node.id;
+		});
+		if (activeId != null) state = {
+			...state,
+			activeTextTrackId: activeId
+		};
+	};
+	return {
+		mount(container) {
+			el = document.createElement("video");
+			el.src = opts.src;
+			el.setAttribute("playsinline", "");
+			el.playsInline = true;
+			el.preload = "metadata";
+			if (opts.poster) el.poster = opts.poster;
+			if (opts.crossOrigin) el.crossOrigin = opts.crossOrigin;
+			if (opts.muted) el.muted = true;
+			if (opts.loop) el.loop = true;
+			if (opts.autoPlay) el.autoplay = true;
+			el.playbackRate = desiredRate;
+			for (const ev of MEDIA_EVENTS) el.addEventListener(ev, syncFromEl);
+			document.addEventListener("fullscreenchange", onFullscreenChange);
+			el.addEventListener("webkitbeginfullscreen", onWebkitBeginFullscreen);
+			el.addEventListener("webkitendfullscreen", onWebkitEndFullscreen);
+			el.addEventListener("enterpictureinpicture", onEnterPip);
+			el.addEventListener("leavepictureinpicture", onLeavePip);
+			appendTracks();
+			container.appendChild(el);
+			const tt = el.textTracks;
+			if (tt && typeof tt.addEventListener === "function") {
+				tt.addEventListener("addtrack", onTextTracksChanged);
+				tt.addEventListener("removetrack", onTextTracksChanged);
+				tt.addEventListener("change", onTextTracksChanged);
+			}
+			applyTextTrackModes();
+			setupMediaSession();
+		},
+		swapSource(next) {
+			if (!el || next.src == null) return;
+			el.src = next.src;
+			if (next.poster != null) el.poster = next.poster;
+			if (next.metadata?.videoTitle != null) setSessionMetadata(next.metadata.videoTitle);
+			reload();
+			el.playbackRate = 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() {
+			document.removeEventListener("fullscreenchange", onFullscreenChange);
+			teardownMediaSession();
+			if (activeTrack) activeTrack.removeEventListener("cuechange", onCueChange);
+			activeTrack = null;
+			if (el) {
+				for (const ev of MEDIA_EVENTS) el.removeEventListener(ev, syncFromEl);
+				el.removeEventListener("webkitbeginfullscreen", onWebkitBeginFullscreen);
+				el.removeEventListener("webkitendfullscreen", onWebkitEndFullscreen);
+				el.removeEventListener("enterpictureinpicture", onEnterPip);
+				el.removeEventListener("leavepictureinpicture", onLeavePip);
+				const tt = el.textTracks;
+				if (tt && typeof tt.removeEventListener === "function") {
+					tt.removeEventListener("addtrack", onTextTracksChanged);
+					tt.removeEventListener("removetrack", onTextTracksChanged);
+					tt.removeEventListener("change", onTextTracksChanged);
+				}
+				el.removeAttribute("src");
+				reload();
+				el.remove();
+			}
+			el = null;
+			listeners.clear();
+		}
+	};
+	function onTextTracksChanged() {
+		applyTextTrackModes();
+		patch({
+			textTracks: readTextTracks(),
+			activeCueText: readCueText()
+		});
+	}
+}
+//#endregion
+//#region src/native/native-player.tsx
+/**
+* kino's glass chrome over a plain HTML <video> element, playing a raw media
+* URL (mp4, webm, ogg, …) directly. Use this when you have a file URL rather
+* than a Mux playback id.
+*
+* Only `src`, `poster`, and `metadata.videoTitle` are reactive (they flow
+* through `swapSource`). `tracks`, `crossOrigin`, `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.
+*/
+function NativePlayer({ accentColor, theme, className, placeholder, children, ...opts }) {
+	const providerRef = useRef(null);
+	if (providerRef.current === null) providerRef.current = createNativeProvider(opts);
+	const provider = providerRef.current;
+	const mountedRef = useRef(false);
+	useEffect(() => {
+		if (!mountedRef.current) {
+			mountedRef.current = true;
+			return;
+		}
+		provider.swapSource?.({
+			src: opts.src,
+			poster: opts.poster,
+			metadata: opts.metadata
+		});
+	}, [
+		opts.src,
+		opts.poster,
+		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 { NativePlayer, createNativeProvider };

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/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.1.3",
+  "version": "0.3.0",
   "description": "Themeable React video player with pluggable providers.",
   "license": "MIT",
   "author": "Karn",
@@ -17,6 +17,7 @@
     "player",
     "react",
     "mux",
+    "youtube",
     "hls",
     "video-player"
   ],
@@ -40,6 +41,14 @@
       "types": "./dist/mux.d.ts",
       "import": "./dist/mux.js"
     },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js"
+    },
+    "./youtube": {
+      "types": "./dist/youtube.d.ts",
+      "import": "./dist/youtube.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "peerDependencies": {
@@ -64,6 +73,7 @@
     "prettier": "^3.3.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "shiki": "^4.3.0",
     "tailwindcss": "^4.3.1",
     "tsdown": "^0.22.3",
     "typescript": "^5.7.0",