@joewinke/jatui 0.8.5 → 0.9.0

package/dist/components/VideoPlayer.svelte

@@ -1,3 +1,16 @@
+<script module lang="ts">
+	// Public type surface — unchanged (the interfaces moved to video/types.ts in
+	// the mos-5lzns.28 internal split; both import sites keep working).
+	export type {
+		VideoChapter,
+		VideoSpeakerTurn,
+		VideoTranscriptSegment,
+		VideoBookmark,
+		VideoWaveform,
+		VideoSpeakerTalkTime
+	} from '../video/types';
+</script>
+
 <script lang="ts">
 	/**
 	 * VideoPlayer — one video surface for everything, from a bare mp4 to a
@@ -21,8 +34,9 @@
 	 *
 	 * ── Design notes carried over from player.js ────────────────────────────
 	 * · ONE time axis. Every position — waveform bars, chapter flags, bookmarks,
-	 *   the speaker lane, click/hover-to-seek — maps through secToFrac/fracToSec,
-	 *   so scroll-to-zoom is one piece of state everything else respects for free.
+	 *   the speaker lane, click/hover-to-seek — maps through the band window's
+	 *   secToFrac/fracToSec (video/band.ts), so scroll-to-zoom is one piece of
+	 *   state everything else respects for free.
 	 * · ONE speaker surface. With a waveform, the envelope's own bars wear the
 	 *   turn colours; the slim lane under it paints only as the no-waveform
 	 *   fallback. Never two stacked time-parallel strips.
@@ -31,7 +45,15 @@
 	 *   yours), so the two families are never confused at a glance.
 	 * · The wheel means different things in different regions, and each region is
 	 *   its own hover target so nothing is ambiguous: over the video it's volume
-	 *   (shift = seek); over the band it's zoom.
+	 *   (shift = seek, alt = speed); over the band it's zoom.
+	 * · The keyboard map (video/keys.ts) is the single source the keydown
+	 *   handler and the `?` overlay both read — a key that exists is documented,
+	 *   a documented key exists.
+	 *
+	 * Internals live in `src/lib/video/` (band / keys / rate / deepLink /
+	 * settings + types/time/model; audio, night and presence are contracts for
+	 * mos-5lzns.31/.33/.34 — see that directory's README for the ownership map
+	 * and the advisor doctrine).
 	 *
 	 * Deliberately NOT ported: player.js's trim region (in/out handles). That's
 	 * clip-editing, not playback, and belongs in an editor component.
@@ -44,74 +66,49 @@
 
 	import { onMount, untrack } from 'svelte';
 	import { getDaisyUIColor, watchThemeChanges, clearColorCache } from '../utils/daisyuiColors';
-
-	/** A model-authored marker: the video's structure. */
-	export interface VideoChapter {
-		startSec: number;
-		title: string;
-		/** Optional captured still, shown in the band's hover card. */
-		thumbUrl?: string | null;
-	}
-
-	/** A diarized turn (or an ad read, `ad: true`). Structurally accepts meeting data. */
-	export interface VideoSpeakerTurn {
-		startSec: number;
-		endSec: number;
-		speakerIdentity?: string | null;
-		speakerName?: string | null;
-		/** Explicit oklch hue (0–360). Omit to take the next palette colour. */
-		hue?: number | null;
-		/** Ad read — shares the lane but reads as not-a-person. */
-		ad?: boolean;
-	}
-
-	/** Transcript line. Structurally compatible with TranscriptPlayer's `TranscriptSegment`. */
-	export interface VideoTranscriptSegment {
-		id: string;
-		startSec: number;
-		endSec: number;
-		speakerIdentity?: string | null;
-		speakerName?: string | null;
-		text: string;
-	}
-
-	/** A user-authored marker. Structurally compatible with `TranscriptBookmark`. */
-	export interface VideoBookmark {
-		playbackSec: number;
-		label?: string | null;
-		note?: string | null;
-		participantName?: string | null;
-	}
-
-	/** Precomputed audio envelope. `peaks` are normalised against their own max. */
-	export interface VideoWaveform {
-		peaks: number[];
-		/** Seconds the peaks span. Defaults to the video's duration. */
-		durationSec?: number;
-	}
-
-	/** Per-speaker totals. Structurally compatible with `TranscriptSpeakerTalkTime`. */
-	export interface VideoSpeakerTalkTime {
-		speakerIdentity?: string | null;
-		speakerName?: string | null;
-		seconds: number;
-	}
-
-	/**
-	 * Speaker identity palette — the same small distinct oklch set TranscriptPlayer
-	 * cycles, so a speaker reads as the same colour in both components.
-	 */
-	const SPEAKER_PALETTE = [
-		'oklch(0.70 0.16 250)', // blue
-		'oklch(0.68 0.18 145)', // green
-		'oklch(0.78 0.16 85)', // amber
-		'oklch(0.68 0.19 25)', // red
-		'oklch(0.68 0.16 300)', // violet
-		'oklch(0.72 0.14 200)' // cyan
-	];
-
-	const ALL_KEY = '__all__';
-	const UNKNOWN_KEY = '__unknown__';
+	import type {
+		VideoBookmark,
+		VideoChapter,
+		VideoSpeakerTalkTime,
+		VideoSpeakerTurn,
+		VideoTranscriptSegment,
+		VideoWaveform
+	} from '../video/types';
+	import { aspectRatioCss, formatDuration, formatTime, truncate } from '../video/time';
+	import {
+		ALL_KEY,
+		buildSpeakerColors,
+		buildSpeakerIndex,
+		buildTalkTime,
+		filterDims,
+		sortBookmarks,
+		sortChapters,
+		sortSegments,
+		sortTurns,
+		speakerKeyOf,
+		SPEAKER_PALETTE,
+		UNKNOWN_KEY
+	} from '../video/model';
+	import {
+		clampCardX,
+		followPlayhead,
+		fracToSec,
+		isZoomed,
+		nearestBookmark,
+		paintBand,
+		prepareCanvas,
+		resetWindow,
+		secToFrac,
+		biasToSegmentStart,
+		segmentAt,
+		chapterAt,
+		toBandTurns,
+		zoomAt,
+		type BandWindow
+	} from '../video/band';
+	import { BAND_KEYS, PLAYER_KEYS, chapterJump, FRAME_STEP_SEC } from '../video/keys';
+	import { composeRate, formatSpeedLabel, stepRate } from '../video/rate';
+	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
 
 	let {
 		src,
@@ -132,6 +129,27 @@
 		startAt = null,
 		transcriptPosition = 'below',
 		transcriptMaxHeight = '18rem',
+		/**
+		 * CORS mode for the <video> element — passed straight through as the
+		 * `crossorigin` attribute. `'anonymous'` asks the server for a
+		 * CORS-readable load, which is what frame-reading features (night
+		 * dimming's canvas sampling, mos-5lzns.33) require. Omitted (default)
+		 * keeps today's behaviour exactly. extension-library parity: it
+		 * re-requests with `crossOrigin = "anonymous"` and remembers success —
+		 * here the host opts in explicitly, because a *component* can't own a
+		 * localStorage memory the host page also depends on.
+		 */
+		crossorigin = null,
+		/**
+		 * Deep-link the timestamp: when true, a `?t=` param on the current URL
+		 * seeds the start position (an explicit `startAt` prop still wins) and
+		 * playback keeps the param in step via history.replaceState — throttled,
+		 * whole-second precision, every other query param preserved. Opt-in
+		 * because a component library must not rewrite the host page's URL
+		 * uninvited. The param persists after unmount: it IS the deep link —
+		 * refresh/copy/share picks up where playback left off.
+		 */
+		syncUrlTime = false,
 		onTimeUpdate = undefined,
 		onAddBookmark = undefined,
 		onBookmarkContext = undefined,
@@ -185,6 +203,8 @@
 		startAt?: number | null;
 		transcriptPosition?: 'below' | 'side';
 		transcriptMaxHeight?: string;
+		crossorigin?: 'anonymous' | 'use-credentials' | null;
+		syncUrlTime?: boolean;
 		onTimeUpdate?: (video: HTMLVideoElement) => void;
 		/** Present ⇒ the band grows an "add bookmark at current time" control. */
 		onAddBookmark?: (playbackSec: number, label: string) => void;
@@ -198,28 +218,6 @@
 		class?: string;
 	} = $props();
 
-	/**
-	 * `aspect` → a CSS `aspect-ratio` value. Accepts `"W:H"`, a bare ratio number,
-	 * or null/"auto" (⇒ no lock; the video's intrinsic ratio drives the box). Shared
-	 * with <Flythrough>/<LessonEmbed> conceptually, kept inline so the primitive has
-	 * no cross-file coupling for one small pure function.
-	 */
-	const aspectRatioCss = $derived.by(() => {
-		const a = aspect;
-		if (a == null) return null;
-		const trimmed = String(a).trim();
-		if (trimmed === '' || trimmed === 'auto') return null;
-		const colon = trimmed.match(/^(\d+(?:\.\d+)?)\s*[:/]\s*(\d+(?:\.\d+)?)$/);
-		if (colon) {
-			const w = parseFloat(colon[1]);
-			const h = parseFloat(colon[2]);
-			if (w > 0 && h > 0) return `${w} / ${h}`;
-		}
-		const num = Number(trimmed);
-		if (Number.isFinite(num) && num > 0) return String(num);
-		return null;
-	});
-
 	// prefers-reduced-motion gate for autoplay: an autoplaying clip IS motion, so
 	// under the reduce preference the video holds on its poster instead. Tracked
 	// live (media query listener) so a mid-session preference flip is honoured, and
@@ -255,7 +253,7 @@
 	} | null = $state(null);
 	let zoomLabel = $state('');
 	let zoomLabelOn = $state(false);
-	let osd = $state(''); // transient wheel readout (volume / seek)
+	let osd = $state(''); // transient wheel/keyboard readout (volume / seek / speed)
 	let osdOn = $state(false);
 
 	// ── Speaker filter state ────────────────────────────────────────────────
@@ -264,6 +262,17 @@
 	let highlightKey: string | null = $state(null);
 	let bookmarkLabel = $state('');
 
+	// ── Speed state (rate.ts owns the staircase; see the composer contract) ──
+	// `base` is the only rate a human chose, and therefore the only one the UI
+	// reports. Advisors (mos-5lzns.32) multiply into the applied rate without
+	// ever touching this — the label must keep saying 1× while a gap is taken
+	// at 2.2×, or the readout becomes a strobe.
+	let baseRate = $state(1);
+
+	// ── Transcript + help overlays ──────────────────────────────────────────
+	let transcriptVisible = $state(true);
+	let keysOpen = $state(false);
+
 	let zoomTimer: ReturnType<typeof setTimeout> | null = null;
 	let osdTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -277,32 +286,10 @@
 	);
 	const useHours = $derived(effectiveDuration >= 3600);
 
-	const sortedChapters = $derived(
-		[...chapters]
-			.filter((c) => c && Number.isFinite(c.startSec) && c.startSec >= 0)
-			.sort((a, b) => a.startSec - b.startSec)
-	);
-	const sortedTurns = $derived(
-		[...speakers]
-			.filter(
-				(t) =>
-					t &&
-					Number.isFinite(t.startSec) &&
-					Number.isFinite(t.endSec) &&
-					t.endSec > t.startSec
-			)
-			.sort((a, b) => a.startSec - b.startSec)
-	);
-	const sortedSegments = $derived(
-		[...transcript]
-			.filter((s) => s && Number.isFinite(s.startSec))
-			.sort((a, b) => a.startSec - b.startSec)
-	);
-	const sortedBookmarks = $derived(
-		[...bookmarks]
-			.filter((b) => b && Number.isFinite(b.playbackSec) && b.playbackSec >= 0)
-			.sort((a, b) => a.playbackSec - b.playbackSec)
-	);
+	const sortedChapters = $derived(sortChapters(chapters));
+	const sortedTurns = $derived(sortTurns(speakers));
+	const sortedSegments = $derived(sortSegments(transcript));
+	const sortedBookmarks = $derived(sortBookmarks(bookmarks));
 
 	/** Peaks normalised to 0–1 against their own max, so 0–1, 0–99 and 0–255 inputs all work. */
 	const peaks = $derived.by(() => {
@@ -319,142 +306,83 @@
 	 * Ordered speaker registry, built from turns first then transcript, so the
 	 * palette index is stable across both panes and the legend.
 	 */
-	const speakerIndex = $derived.by(() => {
-		const map = new Map<string, { key: string; name: string; hue: number | null }>();
-		const add = (
-			identity: string | null | undefined,
-			name: string | null | undefined,
-			hue: number | null | undefined
-		) => {
-			const key = identity ?? name ?? UNKNOWN_KEY;
-			const existing = map.get(key);
-			if (existing) {
-				if (existing.hue == null && hue != null) existing.hue = hue;
-				return;
-			}
-			map.set(key, { key, name: name ?? 'Unknown speaker', hue: hue ?? null });
-		};
-		for (const t of sortedTurns) {
-			if (t.ad) continue;
-			add(t.speakerIdentity, t.speakerName, t.hue ?? null);
-		}
-		for (const s of sortedSegments) add(s.speakerIdentity, s.speakerName, null);
-		return map;
-	});
+	const speakerIndex = $derived(buildSpeakerIndex(sortedTurns, sortedSegments));
 
 	const hasSpeakers = $derived(speakerIndex.size > 0);
 
-	/**
-	 * key → identity colour, resolved ONCE per data change. draw() asks for a
-	 * colour per rendered column and reruns on every playhead tick, so this must
-	 * never be an indexOf scan at call time.
-	 */
-	const speakerColors = $derived.by(() => {
-		const map = new Map<string, string>();
-		let i = 0;
-		for (const [key, entry] of speakerIndex) {
-			map.set(
-				key,
-				entry.hue != null
-					? `oklch(0.72 0.14 ${entry.hue})`
-					: SPEAKER_PALETTE[i % SPEAKER_PALETTE.length]
-			);
-			i++;
-		}
-		return map;
-	});
+	/** key → identity colour, resolved ONCE per data change (see video/model.ts). */
+	const speakerColors = $derived(buildSpeakerColors(speakerIndex));
 
 	/** With an envelope the bars carry the hues; the lane is the no-waveform fallback only. */
 	const laneCarriesSpeakers = $derived(!hasWave && sortedTurns.length > 0);
 
-	const effectiveTalkTime = $derived.by(() => {
-		if (talkTime.length > 0) {
-			return [...talkTime].sort((a, b) => b.seconds - a.seconds);
-		}
-		const totals = new Map<string, VideoSpeakerTalkTime & { key: string }>();
-		const bump = (
-			identity: string | null | undefined,
-			name: string | null | undefined,
-			secs: number
-		) => {
-			const key = identity ?? name ?? UNKNOWN_KEY;
-			const existing = totals.get(key);
-			if (existing) existing.seconds += secs;
-			else totals.set(key, { key, speakerIdentity: identity ?? null, speakerName: name ?? null, seconds: secs });
-		};
-		const source = sortedTurns.length > 0 ? sortedTurns : sortedSegments;
-		for (const s of source) {
-			if ('ad' in s && s.ad) continue;
-			bump(s.speakerIdentity, s.speakerName, Math.max(0, s.endSec - s.startSec));
-		}
-		return [...totals.values()].sort((a, b) => b.seconds - a.seconds);
-	});
+	const effectiveTalkTime = $derived(buildTalkTime(talkTime, sortedTurns, sortedSegments));
 	const talkTimeTotal = $derived(effectiveTalkTime.reduce((n, t) => n + t.seconds, 0) || 1);
 
 	const activeSegment = $derived(
 		sortedSegments.find((s) => currentTime >= s.startSec && currentTime < s.endSec) ?? null
 	);
 
+	/** The zoom window, as the band module sees it (plain data — band.ts is DOM-free). */
+	const bandWindow = $derived<BandWindow>({ start: viewStart, end: viewEnd });
+
+	/** Everything paintBand reads, resolved in one place (see video/band.ts). */
+	const paintState = $derived.by(() => {
+		void themeTick; // repaint on theme swap
+		return {
+			currentTime,
+			duration: effectiveDuration,
+			peaks,
+			chapters: sortedChapters,
+			bookmarks: sortedBookmarks,
+			turns: toBandTurns(sortedTurns),
+			speakerColors,
+			laneCarriesSpeakers,
+			highlightKey,
+			soloKey,
+			mutedKeys,
+			window: bandWindow,
+			hoverChapter,
+			colors: {
+				accent: getDaisyUIColor('primary'),
+				neutral: getDaisyUIColor('base-content'),
+				marker: getDaisyUIColor('warning')
+			}
+		};
+	});
+
+	/** Help-overlay rows: only keys whose feature's data exists are advertised. */
+	const availableKeys = $derived(
+		PLAYER_KEYS.filter((row) => {
+			if (!row.when) return true;
+			if (row.when === 'chapters') return sortedChapters.length > 0;
+			if (row.when === 'bookmarks') return onAddBookmark != null;
+			if (row.when === 'transcript') return sortedSegments.length > 0;
+			return true;
+		})
+	);
+
 	// ── Helpers ─────────────────────────────────────────────────────────────
-	function speakerKeyOf(s: {
-		speakerIdentity?: string | null;
-		speakerName?: string | null;
-	}): string {
-		return s.speakerIdentity ?? s.speakerName ?? UNKNOWN_KEY;
-	}
 
 	/** Explicit hue wins (host-supplied identity colour); otherwise the cycled palette. */
 	function speakerColor(key: string): string {
 		return speakerColors.get(key) ?? SPEAKER_PALETTE[0];
 	}
 
-	function formatTime(totalSeconds: number, withHours: boolean): string {
-		const t = Number.isFinite(totalSeconds) && totalSeconds > 0 ? totalSeconds : 0;
-		const pad = (n: number) => String(n).padStart(2, '0');
-		const s = Math.floor(t % 60);
-		if (withHours) {
-			return `${Math.floor(t / 3600)}:${pad(Math.floor((t % 3600) / 60))}:${pad(s)}`;
-		}
-		return `${Math.floor(t / 60)}:${pad(s)}`;
-	}
-
-	function formatDuration(totalSeconds: number): string {
-		const s = Math.round(Math.max(0, totalSeconds));
-		const h = Math.floor(s / 3600);
-		const m = Math.floor((s % 3600) / 60);
-		if (h > 0) return `${h}h ${m}m`;
-		if (m > 0) return `${m}m ${s % 60}s`;
-		return `${s}s`;
-	}
-
-	function truncate(s: string, n: number): string {
-		return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s;
-	}
-
 	// ── Zoom window: one mapping every position computation goes through ────
-	/**
-	 * The visible window in seconds. Falls back to the whole video until the
-	 * duration effect has seeded viewEnd, so a first paint that races metadata
-	 * still maps positions correctly instead of collapsing to zero.
-	 */
 	function spanSec(): number {
-		return viewEnd > viewStart ? viewEnd - viewStart : effectiveDuration;
+		return bandWindow.end > bandWindow.start
+			? bandWindow.end - bandWindow.start
+			: effectiveDuration;
 	}
-	function isZoomed(): boolean {
-		return viewEnd > 0 && spanSec() < effectiveDuration - 0.01;
+	function isZoomedNow(): boolean {
+		return isZoomed(bandWindow, effectiveDuration);
 	}
 	function resetZoom() {
-		viewStart = 0;
-		viewEnd = effectiveDuration;
-	}
-	function secToFrac(sec: number): number {
-		const span = spanSec();
-		return span > 0 ? (sec - viewStart) / span : 0;
+		const w = resetWindow(effectiveDuration);
+		viewStart = w.start;
+		viewEnd = w.end;
 	}
-	function fracToSec(frac: number): number {
-		return viewStart + frac * spanSec();
-	}
-
 	function flashZoomLabel() {
 		const d = effectiveDuration;
 		const span = spanSec();
@@ -480,238 +408,44 @@
 		if (videoEl) videoEl.currentTime = t;
 	}
 
+	// ── Speed ───────────────────────────────────────────────────────────────
 	/**
-	 * Click-to-seek biases toward the START of the spoken line under the click —
-	 * nobody wants to land mid-sentence. Only when the transcript is dense right
-	 * there, though: on a sparse transcript the containing line could have begun
-	 * minutes earlier, and biasing to it would fling the seek somewhere the user
-	 * never clicked.
+	 * Apply the base rate. No advisors exist yet (mos-5lzns.32 fills the
+	 * speaker/silence ones) — composeRate collapses them to 1, so today this is
+	 * exactly `base`. When they land, the composer multiplies and this keeps
+	 * reporting `base` on the OSD — the contract in video/rate.ts.
 	 */
-	const DENSITY_WINDOW_SEC = 60;
-	function biasToSegmentStart(sec: number): number {
-		if (sortedSegments.length === 0) return sec;
-		let nearby = 0;
-		for (const s of sortedSegments) {
-			if (Math.abs(s.startSec - sec) <= DENSITY_WINDOW_SEC / 2) nearby++;
-		}
-		if (nearby <= 1) return sec;
-		return segmentAt(sec)?.startSec ?? sec;
+	function applyRate() {
+		const v = videoEl;
+		if (!v) return;
+		const { rate } = composeRate(baseRate, 1, 1);
+		// Only real changes are written — playbackRate is a live audio parameter.
+		if (v.playbackRate !== rate) v.playbackRate = rate;
 	}
-
-	/** Last line starting at or before `sec` — segments are ascending. */
-	function segmentAt(sec: number): VideoTranscriptSegment | null {
-		let best: VideoTranscriptSegment | null = null;
-		for (const s of sortedSegments) {
-			if (s.startSec <= sec) best = s;
-			else break;
-		}
-		return best;
-	}
-
-	function chapterAt(sec: number): number {
-		let idx = -1;
-		for (let i = 0; i < sortedChapters.length; i++) {
-			if (sortedChapters[i].startSec <= sec) idx = i;
-			else break;
-		}
-		return idx;
-	}
-
-	const BOOKMARK_HIT_PX = 6;
-	function nearestBookmark(xCss: number, width: number): VideoBookmark | null {
-		if (sortedBookmarks.length === 0 || !width) return null;
-		let best: VideoBookmark | null = null;
-		let bestD = BOOKMARK_HIT_PX;
-		for (const b of sortedBookmarks) {
-			const d = Math.abs(secToFrac(b.playbackSec) * width - xCss);
-			if (d < bestD) {
-				bestD = d;
-				best = b;
-			}
-		}
-		return best;
+	function stepSpeed(direction: 1 | -1) {
+		baseRate = stepRate(baseRate, direction);
+		applyRate();
+		flashOsd(formatSpeedLabel(baseRate));
 	}
 
 	// ── Canvas ──────────────────────────────────────────────────────────────
-	const RAIL_H = 10; // no-waveform fallback: a flat rail instead of an envelope
-
-	/** Does the active solo/mute filter recede this turn's paint? */
-	function filterDims(key: string | null, ad: boolean): boolean {
-		if (soloKey !== ALL_KEY) return !(key != null && !ad && key === soloKey);
-		return !!(key != null && !ad && mutedKeys.has(key));
-	}
-
-	function draw() {
-		const canvas = canvasEl;
-		if (!canvas) return;
-		const W = canvas.clientWidth;
-		const H = canvas.clientHeight;
-		if (!W || !H) return;
-		const dpr = window.devicePixelRatio || 1;
-		if (canvas.width !== Math.round(W * dpr) || canvas.height !== Math.round(H * dpr)) {
-			canvas.width = Math.round(W * dpr);
-			canvas.height = Math.round(H * dpr);
-		}
-		const ctx = canvas.getContext('2d');
-		if (!ctx) return;
-		ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
-		ctx.clearRect(0, 0, W, H);
-
-		const dur = effectiveDuration;
-		const accent = getDaisyUIColor('primary');
-		const neutral = getDaisyUIColor('base-content');
-		const marker = getDaisyUIColor('warning');
-
-		if (dur <= 0) {
-			// No duration yet — paint the empty rail so the band owns its space
-			// from the first frame and metadata arriving is never a layout shove.
-			ctx.globalAlpha = 0.2;
-			ctx.fillStyle = neutral;
-			ctx.fillRect(0, (H - RAIL_H) / 2, W, RAIL_H);
-			ctx.globalAlpha = 1;
-			return;
-		}
-		const p = peaks;
-		const withWave = !!p;
-		const n = p?.length ?? 0;
-		// viewEnd is seeded by the duration effect; until then the window is the
-		// whole video, so a first paint that races metadata still lands correctly.
-		const span = viewEnd - viewStart || dur;
-		// Chapter boundaries in px — a column straddling one is skipped (the seam).
-		const bounds = sortedChapters.slice(1).map((c) => secToFrac(c.startSec) * W);
-		const GAP = 4;
-		const nowChapter = chapterAt(currentTime);
-
-		const visiblePeaks = withWave ? Math.max(1, Math.round((span / dur) * n)) : 0;
-		const step = withWave ? Math.max(1.5, W / visiblePeaks) : 2;
-		const cols = Math.max(1, Math.ceil(W / step));
-		const bw = Math.max(1, step - 1);
-
-		// Speaker sweep: columns advance monotonically in time and turns are
-		// sorted by start, so ONE pointer walks the turn list across the whole
-		// draw — never a per-column find(). Turns can overlap (an ad read inside
-		// a speaker's turn), so the sweep keeps a stack of open turns and the
-		// latest start wins, matching the lane's paint order.
-		let ti = 0;
-		const open: VideoSpeakerTurn[] = [];
-
-		for (let ci = 0; ci < cols; ci++) {
-			const x = ci * step;
-			if (bounds.some((b) => Math.abs(x + bw / 2 - b) < GAP)) continue;
-			const sec = fracToSec((x + step / 2) / W);
-			while (ti < sortedTurns.length && sortedTurns[ti].startSec <= sec) open.push(sortedTurns[ti++]);
-			while (open.length && open[open.length - 1].endSec <= sec) open.pop();
-			const turn = laneCarriesSpeakers ? null : (open[open.length - 1] ?? null);
-			const turnKey = turn && !turn.ad ? speakerKeyOf(turn) : null;
-
-			const ch = sortedChapters.length ? chapterAt(sec) : -1;
-			const played = sec <= currentTime;
-			const hovered = ch >= 0 && ch === hoverChapter;
-
-			// Unplayed floor is 0.38 rather than player.js's 0.3: that value was
-			// tuned against the theater's near-black backdrop, and on a light
-			// theme's base-200 the envelope washed out at it.
-			let alpha: number;
-			if (played) alpha = hovered ? 1 : 0.85;
-			else if (hovered) alpha = 0.6;
-			else if (ch >= 0 && ch === nowChapter) alpha = 0.52;
-			else alpha = 0.38;
-
-			// Legend hover extends onto the envelope: the named speaker at full
-			// strength, everything else at 40% of its normal alpha — the
-			// played/unplayed ladder survives inside both halves.
-			if (highlightKey != null) {
-				if (turnKey === highlightKey) alpha = played ? 1 : 0.8;
-				else alpha *= 0.4;
-			} else if (filterDims(turnKey, !!turn?.ad)) {
-				alpha *= 0.4;
-			}
-
-			ctx.globalAlpha = alpha;
-			if (turn?.ad) ctx.fillStyle = marker;
-			else if (turnKey) ctx.fillStyle = speakerColor(turnKey);
-			else ctx.fillStyle = played ? accent : neutral;
-
-			const h = withWave ? Math.max(2, (p as number[])[peakIdx(sec, dur, n)] * (H - 4)) : RAIL_H;
-			ctx.fillRect(x, withWave ? H - h : (H - RAIL_H) / 2, bw, h);
-		}
-		ctx.globalAlpha = 1;
-
-		// Boundary notches: a hairline in each seam plus a small accent flag on
-		// top — the flag reads as a UI marker even when the envelope is dense.
-		// Flags within a few px of each other collapse to one so a long video at
-		// full zoom-out never smears them into a solid bar.
-		ctx.globalAlpha = 0.4;
-		ctx.fillStyle = neutral;
-		for (const b of bounds) ctx.fillRect(b - 1, 2, 2, H - 4);
-		ctx.globalAlpha = 0.95;
-		ctx.fillStyle = accent;
-		const FLAG_MERGE_PX = 6;
-		let lastFlagX = -Infinity;
-		for (const b of bounds) {
-			if (b - lastFlagX < FLAG_MERGE_PX) continue;
-			lastFlagX = b;
-			ctx.beginPath();
-			ctx.moveTo(b - 3, 0);
-			ctx.lineTo(b + 3, 0);
-			ctx.lineTo(b, 4);
-			ctx.closePath();
-			ctx.fill();
-		}
-
-		// Bookmarks: diamonds pointing up from the BOTTOM edge — the mirror image
-		// of the chapter flags on top, so yours and the model's never blur together.
-		ctx.fillStyle = marker;
-		for (const b of sortedBookmarks) {
-			const x = secToFrac(b.playbackSec) * W;
-			if (x < -4 || x > W + 4) continue;
-			ctx.beginPath();
-			ctx.moveTo(x, H);
-			ctx.lineTo(x - 3, H - 4);
-			ctx.lineTo(x, H - 8);
-			ctx.lineTo(x + 3, H - 4);
-			ctx.closePath();
-			ctx.fill();
-		}
-
-		// Playhead
-		ctx.globalAlpha = 0.9;
-		ctx.fillStyle = neutral;
-		ctx.fillRect(Math.max(0, Math.min(1, secToFrac(currentTime))) * W - 0.5, 0, 1.5, H);
-		ctx.globalAlpha = 1;
-	}
-
-	function peakIdx(sec: number, dur: number, n: number): number {
-		return Math.max(0, Math.min(n - 1, Math.floor((sec / dur) * n)));
-	}
-
 	// Repaint on any input the canvas reads. Deps are listed explicitly and the
-	// body is untracked — draw() touches a lot of state, and letting it register
-	// its own reads is exactly the effect-dep leak that has bitten this library
-	// before (PreJoinLobby's acquire loop).
+	// body is untracked — letting paintState's own reads register as deps is
+	// exactly the effect-dep leak that has bitten this library before
+	// (PreJoinLobby's acquire loop). paintState itself is a $derived, so it is
+	// one dep; canvasEl/canvasW/canvasH are the box deps.
 	$effect(() => {
-		// canvasEl is a dep, not just a read inside draw(): bind:this lands after
-		// the first effect run, so without it the very first paint is skipped and
-		// nothing ever re-triggers one.
 		void canvasEl;
-		void currentTime;
-		void viewStart;
-		void viewEnd;
-		void hoverChapter;
-		void highlightKey;
-		void soloKey;
-		void mutedKeys;
-		void sortedChapters;
-		void sortedTurns;
-		void sortedBookmarks;
-		void speakerColors;
-		void laneCarriesSpeakers;
-		void peaks;
-		void effectiveDuration;
+		void paintState;
 		void canvasW;
 		void canvasH;
-		void themeTick;
-		untrack(() => draw());
+		untrack(() => {
+			const canvas = canvasEl;
+			if (!canvas) return;
+			const ctx = prepareCanvas(canvas);
+			if (!ctx) return;
+			paintBand(ctx, canvas.clientWidth, canvas.clientHeight, paintState);
+		});
 	});
 
 	// A new duration means the old zoom window may no longer make sense.
@@ -720,6 +454,17 @@
 		untrack(() => resetZoom());
 	});
 
+	// A new source shouldn't silently inherit the last video's speed.
+	$effect(() => {
+		void src;
+		untrack(() => {
+			if (baseRate !== 1) {
+				baseRate = 1;
+			}
+			applyRate();
+		});
+	});
+
 	// The band gets resized by things this component can't see (a panel toggling,
 	// the window, the side-transcript breakpoint), so the canvas tracks its own
 	// box. Set up from an $effect keyed on canvasEl rather than onMount: bind:this
@@ -738,12 +483,20 @@
 		return () => ro.disconnect();
 	});
 
+	// ── Deep link: read once on mount; the start position prefers startAt ───
+	// A queued seek never fires on a later source (same one-shot as startAt).
+	let urlStartAt: number | null = null;
+	let appliedStartAt = false;
+	let lastUrlWrite = 0;
+
 	onMount(() => {
 		const stopTheme = watchThemeChanges(() => {
 			clearColorCache();
 			themeTick++;
 		});
 
+		if (syncUrlTime) urlStartAt = readTimeParam();
+
 		// Live reduced-motion tracking — drives the autoplay gate. A flip toward
 		// "reduce" mid-playback pauses the clip on its current frame; a flip away
 		// lets a queued autoplay fire (the effect below owns actually starting it).
@@ -764,6 +517,22 @@
 		};
 	});
 
+	/** Keep the URL's ?t= in step with playback — throttled, whole seconds. */
+	function syncUrl() {
+		if (!syncUrlTime || !videoEl) return;
+		const now = Date.now();
+		if (now - lastUrlWrite < WRITE_THROTTLE_MS) return;
+		lastUrlWrite = now;
+		writeTimeParam(videoEl.currentTime);
+	}
+
+	/** Unthrottled: seek/pause are the moments the deep link must not be stale. */
+	function syncUrlNow() {
+		if (!syncUrlTime || !videoEl) return;
+		lastUrlWrite = Date.now();
+		writeTimeParam(videoEl.currentTime);
+	}
+
 	// Autoplay is applied imperatively (a queued `.play()` that the reduced-motion
 	// gate can veto) rather than via the native `autoplay` attribute, so a
 	// mid-session preference flip is respected instead of being a mount-only
@@ -793,17 +562,17 @@
 		const r = canvas.getBoundingClientRect();
 		if (!r.width || spanSec() <= 0) return null;
 		const x = e.clientX - r.left;
-		return { sec: fracToSec(x / r.width), x, width: r.width };
+		return { sec: fracToSec(bandWindow, effectiveDuration, x / r.width), x, width: r.width };
 	}
 
 	function onBandClick(e: MouseEvent) {
 		const hit = canvasSec(e);
 		if (!hit) return;
-		seekTo(biasToSegmentStart(hit.sec));
+		seekTo(biasToSegmentStart(hit.sec, sortedSegments));
 	}
 
 	function onBandDblClick() {
-		if (!isZoomed()) return;
+		if (!isZoomedNow()) return;
 		resetZoom();
 		flashZoomLabel();
 	}
@@ -813,21 +582,15 @@
 		const hit = canvasSec(e);
 		if (!hit) return;
 		e.preventDefault();
-		const near = nearestBookmark(hit.x, hit.width);
+		const near = nearestBookmark(hit.x, hit.width, sortedBookmarks, bandWindow, effectiveDuration);
 		onBookmarkContext(near ? near.playbackSec : hit.sec, near, e.clientX, e.clientY);
 	}
 
-	/** Keep the (centre-anchored) hover card inside the band's own width. */
-	const CARD_HALF_PX = 90;
-	function clampCardX(x: number, width: number): number {
-		return Math.max(Math.min(CARD_HALF_PX, width / 2), Math.min(x, width - CARD_HALF_PX));
-	}
-
 	function onBandMove(e: MouseEvent) {
 		const hit = canvasSec(e);
 		if (!hit) return;
 		const cardX = clampCardX(hit.x, hit.width);
-		const bm = nearestBookmark(hit.x, hit.width);
+		const bm = nearestBookmark(hit.x, hit.width, sortedBookmarks, bandWindow, effectiveDuration);
 		if (bm) {
 			// A bookmark under the pointer takes over the card entirely — it's
 			// yours, and it outranks the model's chapter guess at this exact spot.
@@ -841,9 +604,9 @@
 			if (hoverChapter !== -1) hoverChapter = -1;
 			return;
 		}
-		const ch = chapterAt(hit.sec);
+		const ch = chapterAt(hit.sec, sortedChapters);
 		const title = ch >= 0 ? sortedChapters[ch]?.title : '';
-		const at = segmentAt(hit.sec);
+		const at = segmentAt(hit.sec, sortedSegments);
 		hover = {
 			x: cardX,
 			title: title ? `${title} · ${formatTime(hit.sec, useHours)}` : formatTime(hit.sec, useHours),
@@ -867,8 +630,6 @@
 	 * hover region (distinct from the video, which owns volume), so nothing else
 	 * here claims the wheel.
 	 */
-	const ZOOM_FACTOR = 1.3;
-	const MIN_WINDOW_SEC = 3;
 	function onBandWheel(e: WheelEvent) {
 		const d = effectiveDuration;
 		const canvas = canvasEl;
@@ -877,14 +638,14 @@
 		const w = r.width;
 		if (!w) return;
 		e.preventDefault();
-		if (viewEnd <= 0) resetZoom();
-		const cursorSec = fracToSec(Math.max(0, Math.min(1, (e.clientX - r.left) / w)));
-		const span = spanSec();
-		let newSpan = e.deltaY < 0 ? span / ZOOM_FACTOR : span * ZOOM_FACTOR;
-		newSpan = Math.min(d, Math.max(MIN_WINDOW_SEC, newSpan));
-		const frac = span > 0 ? (cursorSec - viewStart) / span : 0.5;
-		viewStart = Math.max(0, Math.min(cursorSec - frac * newSpan, d - newSpan));
-		viewEnd = viewStart + newSpan;
+		const cursorSec = fracToSec(
+			bandWindow.end > 0 ? bandWindow : resetWindow(d),
+			d,
+			Math.max(0, Math.min(1, (e.clientX - r.left) / w))
+		);
+		const next = zoomAt(bandWindow.end > 0 ? bandWindow : resetWindow(d), d, cursorSec, e.deltaY);
+		viewStart = next.start;
+		viewEnd = next.end;
 		flashZoomLabel();
 	}
 
@@ -897,15 +658,20 @@
 		else if (e.key === 'ArrowRight') seekTo(currentTime + step);
 		else if (e.key === 'Home') seekTo(0);
 		else if (e.key === 'End') seekTo(d);
-		else if (e.key === 'Escape' && isZoomed()) resetZoom();
+		else if (e.key === 'Escape' && isZoomedNow()) resetZoom();
 		else return;
 		e.preventDefault();
 	}
 
-	// ── Video region: wheel = volume (shift = seek), plus a keyboard map ─────
+	// ── Video region: wheel = volume (shift = seek, alt = speed), keyboard map ──
 	function onStageWheel(e: WheelEvent) {
 		if (!videoEl) return;
 		e.preventDefault();
+		if (e.altKey) {
+			// alt+scroll — speed, the third wheel verb (extension parity)
+			stepSpeed(e.deltaY < 0 ? 1 : -1);
+			return;
+		}
 		if (e.shiftKey) {
 			const delta = e.deltaY < 0 ? 5 : -5;
 			seekTo(currentTime + delta);
@@ -918,14 +684,38 @@
 		flashOsd(`${Math.round(next * 100)}%`);
 	}
 
+	/**
+	 * The full keyboard map (video/keys.ts is the single source; `?` renders it).
+	 * Keys whose feature has no data are bound anyway where harmless, but only
+	 * ADVERTISED when the data exists — a documented key that does nothing is
+	 * the one thing a keymap must never be.
+	 */
 	function onRootKeyDown(e: KeyboardEvent) {
+		// The band's slider handler (and the help overlay) own their keys and
+		// preventDefault them — without this guard an ArrowLeft with the band
+		// focused seeks TWICE (band ±5s, then root ±5s more).
+		if (e.defaultPrevented) return;
 		const target = e.target as HTMLElement | null;
 		const tag = target?.tagName;
 		if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || target?.isContentEditable) return;
 		if (e.metaKey || e.ctrlKey || e.altKey) return;
 		const v = videoEl;
 		if (!v) return;
+
+		// The help overlay takes over Escape while it's open.
+		if (keysOpen) {
+			if (e.key === 'Escape' || e.key === '?') {
+				e.preventDefault();
+				keysOpen = false;
+			}
+			return;
+		}
+
 		switch (e.key) {
+			case '?':
+				e.preventDefault();
+				keysOpen = true;
+				return;
 			case ' ':
 			case 'k':
 				v.paused ? v.play() : v.pause();
@@ -940,6 +730,7 @@
 				break;
 			case 'ArrowUp':
 				v.volume = Math.min(1, v.volume + 0.05);
+				if (v.volume > 0) v.muted = false;
 				flashOsd(`${Math.round(v.volume * 100)}%`);
 				break;
 			case 'ArrowDown':
@@ -950,6 +741,62 @@
 				v.muted = !v.muted;
 				flashOsd(v.muted ? 'Muted' : `${Math.round(v.volume * 100)}%`);
 				break;
+			case '-':
+			case '_':
+				stepSpeed(-1);
+				break;
+			case '=':
+			case '+':
+				stepSpeed(1);
+				break;
+			case 'Backspace':
+				e.preventDefault();
+				if (baseRate !== 1) {
+					baseRate = 1;
+					applyRate();
+				}
+				flashOsd(formatSpeedLabel(baseRate));
+				return;
+			case '<':
+				// Frame step: pause first; the stepped frame is visible in the video
+				// itself, so no OSD — the mpv binding, shifted one key over (,</> are
+				// shifted ,/. — the extension moved it there because `,` means settings).
+				e.preventDefault();
+				v.pause();
+				v.currentTime = Math.max(0, v.currentTime - FRAME_STEP_SEC);
+				return;
+			case '>':
+				e.preventDefault();
+				v.pause();
+				v.currentTime = Math.min(effectiveDuration || Infinity, v.currentTime + FRAME_STEP_SEC);
+				return;
+			case '[':
+			case ']': {
+				e.preventDefault();
+				const jump = chapterJump(currentTime, sortedChapters, e.key === ']' ? 1 : -1);
+				if (jump) {
+					seekTo(jump.startSec);
+					flashOsd(jump.title || 'Chapter');
+				} else {
+					flashOsd('No chapters');
+				}
+				return;
+			}
+			case 'b':
+			case 'B':
+				if (onAddBookmark) {
+					e.preventDefault();
+					submitBookmark();
+				}
+				return;
+			case 't':
+			case 'T':
+				if (sortedSegments.length > 0) {
+					e.preventDefault();
+					transcriptVisible = !transcriptVisible;
+					flashOsd(transcriptVisible ? 'Transcript shown' : 'Transcript hidden');
+				}
+				return;
 			case 'Home':
 				seekTo(0);
 				break;
@@ -962,12 +809,16 @@
 		e.preventDefault();
 	}
 
-	// ── Playback: startAt + solo-speaker skipping ───────────────────────────
-	let appliedStartAt = false;
+	// ── Playback: startAt/deep-link seed + solo-speaker skipping ────────────
 	function onLoadedMetadata() {
-		if (!appliedStartAt && startAt != null && Number.isFinite(startAt)) {
-			appliedStartAt = true;
-			seekTo(startAt);
+		if (!appliedStartAt) {
+			// An explicit startAt prop wins over the URL's ?t= (the host knows its
+			// own intent); with syncUrlTime off this is exactly the old behaviour.
+			const start = startAt ?? urlStartAt;
+			if (start != null && Number.isFinite(start)) {
+				appliedStartAt = true;
+				seekTo(start);
+			}
 		}
 	}
 
@@ -991,13 +842,13 @@
 
 	function handleTimeUpdate() {
 		applySoloSkip();
+		syncUrl();
 		// Zoomed in and playback walked past the edge of the window — follow it,
 		// or you'd watch a frozen slice of waveform while the video plays on.
-		if (isZoomed() && (currentTime < viewStart || currentTime > viewEnd)) {
-			const span = spanSec();
-			const d = effectiveDuration;
-			viewStart = Math.max(0, Math.min(currentTime - span / 2, Math.max(0, d - span)));
-			viewEnd = viewStart + span;
+		const follow = followPlayhead(bandWindow, effectiveDuration, currentTime);
+		if (follow) {
+			viewStart = follow.start;
+			viewEnd = follow.end;
 		}
 		if (videoEl) onTimeUpdate?.(videoEl);
 	}
@@ -1039,7 +890,7 @@
 <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
 <div
 	class="vp-root {className}"
-	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0}
+	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
 	role="region"
 	aria-label="Video player"
 	tabindex="-1"
@@ -1059,8 +910,11 @@
 				bind:duration
 				ontimeupdate={handleTimeUpdate}
 				onloadedmetadata={onLoadedMetadata}
+				onseeked={syncUrlNow}
+				onpause={syncUrlNow}
 				{src}
 				{loop}
+				crossorigin={crossorigin ?? undefined}
 				muted={effectiveAutoplay || undefined}
 				poster={poster ?? undefined}
 				controls
@@ -1117,15 +971,15 @@
 				{#if laneCarriesSpeakers}
 					{#each sortedTurns as turn, i (turn.startSec + ':' + i)}
 						{@const key = speakerKeyOf(turn)}
-						{@const l = secToFrac(turn.startSec) * 100}
-						{@const r = secToFrac(turn.endSec) * 100}
-						{#if turn.endSec > viewStart && turn.startSec < (viewEnd || effectiveDuration)}
+						{@const l = secToFrac(bandWindow, effectiveDuration, turn.startSec) * 100}
+						{@const r = secToFrac(bandWindow, effectiveDuration, turn.endSec) * 100}
+						{#if turn.endSec > bandWindow.start && turn.startSec < (bandWindow.end || effectiveDuration)}
 							<span
 								class="vp-lane-span"
 								class:vp-lane-ad={turn.ad}
 								class:vp-dim={highlightKey != null
 									? highlightKey !== key
-									: filterDims(turn.ad ? null : key, !!turn.ad)}
+									: filterDims(turn.ad ? null : key, !!turn.ad, soloKey, mutedKeys)}
 								style="left: {Math.max(0, Math.min(100, l))}%; width: max({Math.max(
 									0,
 									Math.min(100, r) - Math.max(0, l)
@@ -1163,7 +1017,7 @@
 
 		<div class="vp-times">
 			<span>{formatTime(currentTime, useHours)}</span>
-			{#if isZoomed()}
+			{#if isZoomedNow()}
 				<button type="button" class="vp-reset-zoom" onclick={() => { resetZoom(); flashZoomLabel(); }}>
 					Reset zoom
 				</button>
@@ -1254,7 +1108,7 @@
 		{/if}
 	</div>
 
-	{#if sortedSegments.length > 0}
+	{#if sortedSegments.length > 0 && transcriptVisible}
 		<div class="vp-transcript" style="max-height: {transcriptMaxHeight}">
 			{#each sortedSegments as seg (seg.id)}
 				<button
@@ -1263,7 +1117,7 @@
 					class:active={activeSegment?.id === seg.id}
 					class:vp-dim={highlightKey != null
 						? highlightKey !== speakerKeyOf(seg)
-						: filterDims(speakerKeyOf(seg), false)}
+						: filterDims(speakerKeyOf(seg), false, soloKey, mutedKeys)}
 					bind:this={rowRefs[seg.id]}
 					onclick={() => seekTo(seg.startSec)}
 				>
@@ -1276,6 +1130,35 @@
 			{/each}
 		</div>
 	{/if}
+
+	{#if keysOpen}
+		<!-- Keyboard help — `?` toggles, Escape/`?` closes. The rows are the
+		     PLAYER_KEYS map filtered to keys whose feature's data exists, so the
+		     overlay never advertises a key that would do nothing here. -->
+		<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions -->
+		<div class="vp-keys-backdrop" onclick={(e) => { if (e.target === e.currentTarget) keysOpen = false; }}>
+			<div class="vp-keys" role="dialog" aria-label="Keyboard shortcuts">
+				<div class="vp-keys-title">Keyboard</div>
+				<ul class="vp-keys-list">
+					{#each availableKeys as row (row.keys)}
+						<li class="vp-keys-row">
+							<span class="vp-keys-kbd">{row.keys}</span>
+							<span class="vp-keys-desc">{row.description}</span>
+						</li>
+					{/each}
+				</ul>
+				<div class="vp-keys-title">Band focused</div>
+				<ul class="vp-keys-list">
+					{#each BAND_KEYS as row (row.keys)}
+						<li class="vp-keys-row">
+							<span class="vp-keys-kbd">{row.keys}</span>
+							<span class="vp-keys-desc">{row.description}</span>
+						</li>
+					{/each}
+				</ul>
+			</div>
+		</div>
+	{/if}
 </div>
 
 <style>
@@ -1291,6 +1174,7 @@
 		border-color: color-mix(in oklch, var(--color-base-content) 12%, transparent);
 		border-radius: var(--jatui-radius-box, 0.5rem);
 		padding: var(--jatui-space-lg, 12px);
+		position: relative;
 	}
 
 	.vp-root:focus {
@@ -1346,7 +1230,8 @@
 		background: var(--color-neutral);
 	}
 
-	/* Transient wheel readout (volume / seek) — one calm flash, then gone. */
+	/* Transient wheel/keyboard readout (volume / seek / speed) — one calm flash,
+	   then gone. */
 	.vp-osd {
 		position: absolute;
 		top: var(--jatui-space-base, 8px);
@@ -1713,6 +1598,78 @@
 		min-width: 10rem;
 	}
 
+	/* Keyboard help overlay — the `?` surface. Keycaps first, description after;
+	   token-only colours, same chrome family as the hover card. */
+	.vp-keys-backdrop {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background: color-mix(in oklch, var(--color-base-100) 70%, transparent);
+		z-index: 10;
+		border-radius: inherit;
+	}
+
+	.vp-keys {
+		max-width: 22rem;
+		max-height: 90%;
+		overflow-y: auto;
+		padding: var(--jatui-space-lg, 12px);
+		background: var(--color-base-100);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-base-content) 18%, transparent);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		color: var(--color-base-content);
+		box-shadow: 0 8px 30px color-mix(in oklch, var(--color-base-content) 25%, transparent);
+	}
+
+	.vp-keys-title {
+		font-size: 0.66rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+		margin: var(--jatui-space-sm, 4px) 0;
+	}
+
+	.vp-keys-title:first-child {
+		margin-top: 0;
+	}
+
+	.vp-keys-list {
+		display: flex;
+		flex-direction: column;
+		gap: var(--jatui-space-xs, 2px);
+		margin: 0 0 var(--jatui-space-sm, 4px);
+		padding: 0;
+		list-style: none;
+	}
+
+	.vp-keys-row {
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		gap: var(--jatui-space-md, 6px);
+		font-size: 0.72rem;
+	}
+
+	.vp-keys-kbd {
+		font-family: ui-monospace, monospace;
+		font-size: 0.66rem;
+		white-space: nowrap;
+		padding: 0 var(--jatui-space-xs, 2px);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-base-content) 25%, transparent);
+		border-radius: var(--jatui-radius-selector, 0.375rem);
+		background: color-mix(in oklch, var(--color-base-content) 6%, transparent);
+	}
+
+	.vp-keys-desc {
+		color: color-mix(in oklch, var(--color-base-content) 75%, transparent);
+		text-align: right;
+	}
+
 	/* Motion is decoration here — every state also has a static read (colour,
 	   position, label), so collapsing it changes nothing functional. */
 	@media (prefers-reduced-motion: reduce) {
@@ -1726,4 +1683,4 @@
 			transition: none;
 		}
 	}
-</style>
+</style>