@joewinke/jatui 0.9.0 → 0.10.0

package/dist/components/VideoPlayer.svelte

@@ -9,6 +9,10 @@
 		VideoWaveform,
 		VideoSpeakerTalkTime
 	} from '../video/types';
+	// mos-5lzns.30 — one-axis state, the light track, social markers.
+	export type { BandAxis, BandState } from '../video/band/axis';
+	export type { VideoLumaTrack } from '../video/band/luma';
+	export type { VideoMarker } from '../video/band/markers';
 </script>
 
 <script lang="ts">
@@ -90,6 +94,7 @@
 		UNKNOWN_KEY
 	} from '../video/model';
 	import {
+		bandClusters,
 		clampCardX,
 		followPlayhead,
 		fracToSec,
@@ -106,6 +111,27 @@
 		zoomAt,
 		type BandWindow
 	} from '../video/band';
+	import {
+		barHidden,
+		bandStateOf,
+		createBandReporter,
+		overviewBracket,
+		playheadX,
+		type BandState
+	} from '../video/band/axis';
+	import { normalizeLuma, ribbonColumns, RIBBON_STOPS, type VideoLumaTrack } from '../video/band/luma';
+	import {
+		commentAt,
+		commentJump,
+		describeComments,
+		MARKER_HIT_PX,
+		MARKER_HIT_PX_COARSE,
+		sortMarkers,
+		splitMarkers,
+		type VideoMarker
+	} from '../video/band/markers';
+	import { dragCancel, dragEnd, dragMove, dragStart, type DragState } from '../video/band/drag';
+	import { createBandLayerCache } from '../video/band/memo';
 	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';
@@ -150,6 +176,11 @@
 		 * refresh/copy/share picks up where playback left off.
 		 */
 		syncUrlTime = false,
+		luma = null,
+		markers = [],
+		oneAxis = true,
+		onBandChange = undefined,
+		onMarkerClick = undefined,
 		onTimeUpdate = undefined,
 		onAddBookmark = undefined,
 		onBookmarkContext = undefined,
@@ -205,6 +236,41 @@
 		transcriptMaxHeight?: string;
 		crossorigin?: 'anonymous' | 'use-credentials' | null;
 		syncUrlTime?: boolean;
+		/**
+		 * The light track — the host's pre-scanned brightness sidecar (integers
+		 * 0–99 at `rate` samples/s; extension-library's `.luma` verbatim).
+		 * Present ⇒ the band paints the light ribbon under its envelope, so
+		 * bright passages glow on the timeline before you reach them. Night
+		 * dimming (mos-5lzns.33) reads the same prop. Garbage or < 4 samples ⇒
+		 * no ribbon, never a wrong one.
+		 */
+		luma?: VideoLumaTrack | null;
+		/**
+		 * Social markers on the band: `kind: 'comment'` draws a dot under the
+		 * chapter flags (hover = the comment, click = seek to its exact second);
+		 * `kind: 'like'` folds into a heat strip along the bottom edge.
+		 */
+		markers?: VideoMarker[];
+		/**
+		 * One time axis (default on): while the band has an envelope it OWNS the
+		 * axis and the native timeline stands down (Chromium; elsewhere it can't
+		 * be hidden and simply stays); zoomed, the band grows a whole-video
+		 * overview rail with the window bracketed. Off ⇒ both, permanently.
+		 */
+		oneAxis?: boolean;
+		/**
+		 * The four-state arbitration, reported on real change only and deferred
+		 * a microtask (the host's ref to this component may not be set yet when
+		 * the first report fires). A host that draws its OWN seek bar reads
+		 * `axis` to decide whether to show it — see video/band/axis.ts.
+		 */
+		onBandChange?: (state: BandState) => void;
+		/**
+		 * A comment marker was clicked (after the seek to it). Dots within a few
+		 * px merge into one; `cluster` carries every comment under that dot,
+		 * earliest first, and `marker` is `cluster[0]` — the one seeked to.
+		 */
+		onMarkerClick?: (marker: VideoMarker, cluster: VideoMarker[]) => void;
 		onTimeUpdate?: (video: HTMLVideoElement) => void;
 		/** Present ⇒ the band grows an "add bookmark at current time" control. */
 		onAddBookmark?: (playbackSec: number, label: string) => void;
@@ -226,6 +292,8 @@
 	// Autoplay forces muted — browsers refuse to autoplay audible video, and a
 	// silent presentation clip is the point of the primitive anyway.
 	const effectiveAutoplay = $derived(autoplay && !reduceMotion);
+	// `(pointer: coarse)` — a fingertip gets a wider comment-dot target.
+	let coarsePointer = $state(false);
 
 	// ── Element refs + media state ──────────────────────────────────────────
 	let videoEl: HTMLVideoElement | undefined = $state();
@@ -250,6 +318,7 @@
 		text: string;
 		thumb: string | null;
 		isBookmark: boolean;
+		isComment?: boolean;
 	} | null = $state(null);
 	let zoomLabel = $state('');
 	let zoomLabelOn = $state(false);
@@ -302,6 +371,12 @@
 	});
 	const hasWave = $derived(!!peaks);
 
+	const lumaSeries = $derived(normalizeLuma(luma));
+	// Memo slots for the ribbon / heat / cluster arrays — plain object, never a
+	// reactive source (band/memo.ts): a playhead repaint reuses them.
+	const layerCache = createBandLayerCache();
+	const socialMarkers = $derived(splitMarkers(sortMarkers(markers)));
+
 	/**
 	 * Ordered speaker registry, built from turns first then transcript, so the
 	 * palette index is stable across both panes and the legend.
@@ -343,14 +418,58 @@
 			mutedKeys,
 			window: bandWindow,
 			hoverChapter,
+			luma: lumaSeries,
+			comments: socialMarkers.comments,
+			likes: socialMarkers.likes,
+			cache: layerCache,
 			colors: {
 				accent: getDaisyUIColor('primary'),
 				neutral: getDaisyUIColor('base-content'),
-				marker: getDaisyUIColor('warning')
+				marker: getDaisyUIColor('warning'),
+				ribbon: getDaisyUIColor('warning'),
+				comment: getDaisyUIColor('info'),
+				like: getDaisyUIColor('secondary'),
+				surface: getDaisyUIColor('base-100')
 			}
 		};
 	});
 
+	// ── One time axis (video/band/axis.ts) ─────────────────────────────────
+	const currentBandState = $derived<BandState>(
+		bandStateOf(hasWave, bandWindow, effectiveDuration, oneAxis)
+	);
+	const nativeBarHidden = $derived(barHidden(currentBandState.axis));
+	/** The overview rail: whole video, window bracketed — only while zoomed. */
+	const bracket = $derived(overviewBracket(bandWindow, effectiveDuration));
+	const overviewPlayhead = $derived(
+		effectiveDuration > 0 ? Math.max(0, Math.min(1, currentTime / effectiveDuration)) : 0
+	);
+	/** The ribbon on the overview too, as a gradient — FEATURES.md's 120 stops. */
+	const overviewRibbon = $derived.by(() => {
+		void themeTick;
+		if (!lumaSeries || !(effectiveDuration > 0)) return '';
+		const alphas = ribbonColumns(lumaSeries, { start: 0, end: effectiveDuration }, effectiveDuration, RIBBON_STOPS);
+		const stops = alphas.map(
+			(a, i) =>
+				`color-mix(in oklch, var(--color-warning) ${(a * 100).toFixed(1)}%, transparent) ${((i / (alphas.length - 1)) * 100).toFixed(2)}%`
+		);
+		return `linear-gradient(to right, ${stops.join(', ')})`;
+	});
+
+	/**
+	 * The current four-state arbitration — the extension's `bandState()`.
+	 * Callable on the instance (`bind:this`) for hosts that prefer to pull.
+	 */
+	export function bandState(): BandState {
+		return { ...currentBandState };
+	}
+
+	const reportBand = createBandReporter(() => onBandChange);
+	$effect(() => {
+		const st = currentBandState;
+		untrack(() => reportBand(st));
+	});
+
 	/** Help-overlay rows: only keys whose feature's data exists are advertised. */
 	const availableKeys = $derived(
 		PLAYER_KEYS.filter((row) => {
@@ -358,6 +477,7 @@
 			if (row.when === 'chapters') return sortedChapters.length > 0;
 			if (row.when === 'bookmarks') return onAddBookmark != null;
 			if (row.when === 'transcript') return sortedSegments.length > 0;
+			if (row.when === 'comments') return socialMarkers.comments.length > 0;
 			return true;
 		})
 	);
@@ -508,10 +628,20 @@
 			mq.addEventListener('change', onChange);
 			stopReduce = () => mq.removeEventListener('change', onChange);
 		}
+		let stopCoarse: (() => void) | undefined;
+		if (typeof window !== 'undefined' && window.matchMedia) {
+			const mq = window.matchMedia('(pointer: coarse)');
+			coarsePointer = mq.matches;
+			const onChange = () => (coarsePointer = mq.matches);
+			mq.addEventListener('change', onChange);
+			stopCoarse = () => mq.removeEventListener('change', onChange);
+		}
 
 		return () => {
 			stopTheme();
 			stopReduce?.();
+			stopCoarse?.();
+			if (dragRaf) cancelAnimationFrame(dragRaf);
 			if (zoomTimer) clearTimeout(zoomTimer);
 			if (osdTimer) clearTimeout(osdTimer);
 		};
@@ -565,12 +695,115 @@
 		return { sec: fracToSec(bandWindow, effectiveDuration, x / r.width), x, width: r.width };
 	}
 
+	/**
+	 * The comment cluster under the pointer, hit-tested in the band's own
+	 * window against the SAME memoised clusters the paint drew (clientWidth,
+	 * like the paint — so the hit test and the dots can never disagree).
+	 */
+	function commentUnder(hit: { x: number; width: number }) {
+		const canvas = canvasEl;
+		if (socialMarkers.comments.length === 0 || !canvas || !hit.width) return null;
+		const cw = canvas.clientWidth || hit.width;
+		const clusters = bandClusters(socialMarkers.comments, bandWindow, effectiveDuration, cw, layerCache);
+		return commentAt(hit.x * (cw / hit.width), clusters, coarsePointer ? MARKER_HIT_PX_COARSE : MARKER_HIT_PX);
+	}
+
+	// ── Screen-reader announcements (comment jumps / clicks) ───────────────
+	let announcement = $state('');
+	function announce(text: string) {
+		// Clear first so repeating the same comment is announced again.
+		announcement = '';
+		queueMicrotask(() => (announcement = text));
+	}
+	function landOnComments(group: VideoMarker[]) {
+		seekTo(group[0].atSec);
+		announce(describeComments(group, (sec) => formatTime(sec, useHours)));
+	}
+
 	function onBandClick(e: MouseEvent) {
+		// The click the browser fires after a drag-scrub's release is not a click.
+		if (suppressNextClick) {
+			suppressNextClick = false;
+			return;
+		}
 		const hit = canvasSec(e);
 		if (!hit) return;
+		// A comment is ABOUT its instant: land exactly there, no transcript bias.
+		const c = commentUnder(hit);
+		if (c) {
+			landOnComments(c.markers);
+			onMarkerClick?.(c.markers[0], c.markers.slice());
+			return;
+		}
 		seekTo(biasToSegmentStart(hit.sec, sortedSegments));
 	}
 
+	// ── Drag-to-scrub (video/band/drag.ts) ──────────────────────────────────
+	// One-axis hides the native timeline, so the band must scrub like it:
+	// pointer capture keeps the drag alive off the canvas, seeks are throttled
+	// to one per animation frame, and the release lands exactly under the
+	// pointer (no transcript bias — a scrub is deliberate).
+	let drag: DragState | null = null;
+	let dragRaf = 0;
+	let suppressNextClick = false;
+
+	function flushDragSeek() {
+		dragRaf = 0;
+		if (drag?.pendingSec != null) seekTo(drag.pendingSec);
+	}
+
+	function onBandPointerDown(e: PointerEvent) {
+		if (e.button !== 0 || !canvasEl) return;
+		drag = dragStart(e.pointerId, e.clientX, currentTime);
+		suppressNextClick = false;
+		try {
+			canvasEl.setPointerCapture(e.pointerId);
+		} catch {
+			// capture can fail on a pointer that's already gone — the drag just ends early
+		}
+	}
+
+	function onBandPointerMove(e: PointerEvent) {
+		if (!drag) return;
+		const hit = canvasSec(e);
+		if (!hit) return;
+		const sec = Math.max(0, Math.min(effectiveDuration, hit.sec));
+		const next = dragMove(drag, e.pointerId, e.clientX, sec);
+		if (next === drag) return;
+		drag = next;
+		if (!dragRaf) dragRaf = requestAnimationFrame(flushDragSeek);
+	}
+
+	function finishDrag(e: PointerEvent, cancelled: boolean) {
+		if (!drag || drag.pointerId !== e.pointerId) return;
+		const hit = canvasSec(e);
+		const sec = hit ? Math.max(0, Math.min(effectiveDuration, hit.sec)) : (drag.pendingSec ?? currentTime);
+		const out = cancelled ? dragCancel(drag, e.pointerId) : dragEnd(drag, e.pointerId, sec);
+		if (dragRaf) {
+			cancelAnimationFrame(dragRaf);
+			dragRaf = 0;
+		}
+		drag = null;
+		if (canvasEl?.hasPointerCapture?.(e.pointerId)) canvasEl.releasePointerCapture(e.pointerId);
+		if (out.seekSec != null) seekTo(out.seekSec);
+		suppressNextClick = out.suppressClick;
+	}
+
+	/** Overview rail: click seeks, and brings the window along if it lands outside it. */
+	function onOverviewClick(e: MouseEvent) {
+		const d = effectiveDuration;
+		const el = e.currentTarget as HTMLElement;
+		const r = el.getBoundingClientRect();
+		if (!d || !r.width) return;
+		const sec = Math.max(0, Math.min(1, (e.clientX - r.left) / r.width)) * d;
+		seekTo(sec);
+		const follow = followPlayhead(bandWindow, d, sec);
+		if (follow) {
+			viewStart = follow.start;
+			viewEnd = follow.end;
+		}
+	}
+
 	function onBandDblClick() {
 		if (!isZoomedNow()) return;
 		resetZoom();
@@ -604,6 +837,23 @@
 			if (hoverChapter !== -1) hoverChapter = -1;
 			return;
 		}
+		const c = commentUnder(hit);
+		if (c) {
+			// Other people's words at this instant — they outrank the model's
+			// chapter guess, but not your own bookmark.
+			const first = c.markers[0];
+			const more = c.markers.length > 1 ? ` · +${c.markers.length - 1}` : '';
+			hover = {
+				x: cardX,
+				title: `${first.author || 'Comment'} · ${formatTime(first.atSec, useHours)}${more}`,
+				text: first.text ? truncate(first.text, 90) : '',
+				thumb: null,
+				isBookmark: false,
+				isComment: true
+			};
+			if (hoverChapter !== -1) hoverChapter = -1;
+			return;
+		}
 		const ch = chapterAt(hit.sec, sortedChapters);
 		const title = ch >= 0 ? sortedChapters[ch]?.title : '';
 		const at = segmentAt(hit.sec, sortedSegments);
@@ -782,6 +1032,19 @@
 				}
 				return;
 			}
+			case '{':
+			case '}': {
+				if (socialMarkers.comments.length === 0) return;
+				e.preventDefault();
+				const group = commentJump(currentTime, socialMarkers.comments, e.key === '}' ? 1 : -1);
+				if (group) {
+					landOnComments(group);
+					flashOsd(group[0].author || 'Comment');
+				} else {
+					flashOsd(e.key === '}' ? 'No later comments' : 'No earlier comments');
+				}
+				return;
+			}
 			case 'b':
 			case 'B':
 				if (onAddBookmark) {
@@ -891,6 +1154,8 @@
 <div
 	class="vp-root {className}"
 	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
+	class:vp-one-axis={nativeBarHidden}
+	data-band-axis={currentBandState.axis}
 	role="region"
 	aria-label="Video player"
 	tabindex="-1"
@@ -942,6 +1207,26 @@
 			onmouseleave={onBandLeave}
 			role="presentation"
 		>
+			<!-- Overview rail (one-axis "overview" state): the whole video, with
+			     the zoomed window as an outlined bracket. Lives in the band's
+			     reserved top padding, so appearing is never a layout shove, and
+			     shares the canvas's exact box so the two axes line up. -->
+			{#if bracket}
+				<!-- svelte-ignore a11y_click_events_have_key_events -->
+				<div
+					class="vp-overview"
+					role="presentation"
+					style={overviewRibbon ? `--vp-ribbon: ${overviewRibbon};` : undefined}
+					onclick={onOverviewClick}
+				>
+					<div class="vp-overview-played" style="width: {overviewPlayhead * 100}%"></div>
+					<div
+						class="vp-overview-bracket"
+						style="left: {bracket.left * 100}%; width: {bracket.width * 100}%"
+					></div>
+					<div class="vp-overview-head" style="left: {overviewPlayhead * 100}%"></div>
+				</div>
+			{/if}
 			<canvas
 				bind:this={canvasEl}
 				class="vp-wave"
@@ -954,10 +1239,17 @@
 				aria-valuenow={Math.round(currentTime)}
 				aria-valuetext={formatTime(currentTime, useHours)}
 				onclick={onBandClick}
+				onpointerdown={onBandPointerDown}
+				onpointermove={onBandPointerMove}
+				onpointerup={(e) => finishDrag(e, false)}
+				onpointercancel={(e) => finishDrag(e, true)}
 				ondblclick={onBandDblClick}
 				oncontextmenu={onBandContextMenu}
 				onkeydown={onBandKeyDown}
 			></canvas>
+			<!-- Polite announcements for comment jumps/clicks — the dots are
+			     canvas pixels, so without this a comment is invisible to AT. -->
+			<div class="vp-sr" aria-live="polite" aria-atomic="true">{announcement}</div>
 
 			<!-- Speaker lane. Painted ONLY as the no-waveform fallback: with an
 			     envelope its own bars wear the turn colours, and two stacked
@@ -1003,6 +1295,11 @@
 						<img class="vp-card-thumb" src={hover.thumb} alt="" />
 					{/if}
 					<div class="vp-card-title">
+						{#if hover.isComment}
+							<svg viewBox="0 0 24 24" width="11" height="11" aria-hidden="true" class="vp-cm-icon">
+								<path d="M4 4h16a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1H9l-5 4V5a1 1 0 0 1 1-1z" fill="currentColor" />
+							</svg>
+						{/if}
 						{#if hover.isBookmark}
 							<svg viewBox="0 0 24 24" width="11" height="11" aria-hidden="true" class="vp-bm-icon">
 								<path d="M6 2a2 2 0 0 0-2 2v18l8-5 8 5V4a2 2 0 0 0-2-2H6z" fill="currentColor" />
@@ -1266,6 +1563,57 @@
 		opacity: 1;
 	}
 
+	/* One time axis: while the band owns it, the native timeline stands down.
+	   Only Chromium exposes it; elsewhere this matches nothing and the native
+	   bar simply stays (see video/band/axis.ts). */
+	.vp-one-axis .vp-video::-webkit-media-controls-timeline {
+		display: none;
+	}
+
+	/* Overview rail — sits in the band's padding-top, exactly the canvas's
+	   width, so its mapping and the band's share one box. */
+	.vp-overview {
+		position: absolute;
+		top: 1px;
+		left: 0;
+		right: 0;
+		height: 5px;
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		background: var(--vp-ribbon, none), color-mix(in oklch, var(--color-base-content) 12%, transparent);
+		cursor: pointer;
+		overflow: visible;
+	}
+
+	.vp-overview-played {
+		position: absolute;
+		inset: 0 auto 0 0;
+		border-radius: inherit;
+		background: color-mix(in oklch, var(--color-primary) 70%, transparent);
+	}
+
+	/* A RANGE of the axis: an outline, never a fill — the played bar under it
+	   stays readable, and range ≠ position at a glance. */
+	.vp-overview-bracket {
+		position: absolute;
+		top: -1px;
+		bottom: -1px;
+		box-sizing: border-box;
+		border: 1px solid var(--color-base-content);
+		border-radius: 2px;
+		pointer-events: none;
+	}
+
+	/* Same line as the canvas playhead: 1.5px, centred on the position. */
+	.vp-overview-head {
+		position: absolute;
+		top: -1px;
+		bottom: -1px;
+		width: 1.5px;
+		transform: translateX(-50%);
+		background: var(--color-base-content);
+		pointer-events: none;
+	}
+
 	.vp-wave {
 		display: block;
 		width: 100%;
@@ -1274,6 +1622,23 @@
 		border-radius: var(--jatui-radius-field, 0.25rem);
 	}
 
+	/* Horizontal drags belong to the scrubber; vertical still scrolls the page. */
+	.vp-wave {
+		touch-action: pan-y;
+	}
+
+	.vp-sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0 0 0 0);
+		white-space: nowrap;
+		border: 0;
+	}
+
 	.vp-wave:focus-visible {
 		outline: 2px solid var(--color-primary);
 		outline-offset: 2px;
@@ -1382,6 +1747,11 @@
 		flex-shrink: 0;
 	}
 
+	.vp-cm-icon {
+		color: var(--color-info);
+		flex-shrink: 0;
+	}
+
 	.vp-card-text {
 		margin-top: var(--jatui-space-xs, 2px);
 		color: color-mix(in oklch, var(--color-base-content) 65%, transparent);

package/dist/components/VideoPlayer.svelte.d.ts

@@ -1,5 +1,11 @@
 export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime } from '../video/types';
+export type { BandAxis, BandState } from '../video/band/axis';
+export type { VideoLumaTrack } from '../video/band/luma';
+export type { VideoMarker } from '../video/band/markers';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
+import { type BandState } from '../video/band/axis';
+import { type VideoLumaTrack } from '../video/band/luma';
+import { type VideoMarker } from '../video/band/markers';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -51,6 +57,41 @@ type $$ComponentProps = {
     transcriptMaxHeight?: string;
     crossorigin?: 'anonymous' | 'use-credentials' | null;
     syncUrlTime?: boolean;
+    /**
+     * The light track — the host's pre-scanned brightness sidecar (integers
+     * 0–99 at `rate` samples/s; extension-library's `.luma` verbatim).
+     * Present ⇒ the band paints the light ribbon under its envelope, so
+     * bright passages glow on the timeline before you reach them. Night
+     * dimming (mos-5lzns.33) reads the same prop. Garbage or < 4 samples ⇒
+     * no ribbon, never a wrong one.
+     */
+    luma?: VideoLumaTrack | null;
+    /**
+     * Social markers on the band: `kind: 'comment'` draws a dot under the
+     * chapter flags (hover = the comment, click = seek to its exact second);
+     * `kind: 'like'` folds into a heat strip along the bottom edge.
+     */
+    markers?: VideoMarker[];
+    /**
+     * One time axis (default on): while the band has an envelope it OWNS the
+     * axis and the native timeline stands down (Chromium; elsewhere it can't
+     * be hidden and simply stays); zoomed, the band grows a whole-video
+     * overview rail with the window bracketed. Off ⇒ both, permanently.
+     */
+    oneAxis?: boolean;
+    /**
+     * The four-state arbitration, reported on real change only and deferred
+     * a microtask (the host's ref to this component may not be set yet when
+     * the first report fires). A host that draws its OWN seek bar reads
+     * `axis` to decide whether to show it — see video/band/axis.ts.
+     */
+    onBandChange?: (state: BandState) => void;
+    /**
+     * A comment marker was clicked (after the seek to it). Dots within a few
+     * px merge into one; `cluster` carries every comment under that dot,
+     * earliest first, and `marker` is `cluster[0]` — the one seeked to.
+     */
+    onMarkerClick?: (marker: VideoMarker, cluster: VideoMarker[]) => void;
     onTimeUpdate?: (video: HTMLVideoElement) => void;
     /** Present ⇒ the band grows an "add bookmark at current time" control. */
     onAddBookmark?: (playbackSec: number, label: string) => void;
@@ -58,6 +99,8 @@ type $$ComponentProps = {
     onBookmarkContext?: (sec: number, existing: VideoBookmark | null, clientX: number, clientY: number) => void;
     class?: string;
 };
-declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {
+    bandState: () => BandState;
+}, "">;
 type VideoPlayer = ReturnType<typeof VideoPlayer>;
 export default VideoPlayer;

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { ChapterBlock } from './components/replay/ChapterTimeline.svelte';
 export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelte';
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
-export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, } from './components/VideoPlayer.svelte';
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, } from './components/VideoPlayer.svelte';
 export { default as Flythrough } from './components/Flythrough.svelte';
 export { default as LessonEmbed } from './components/LessonEmbed.svelte';
 export type { Collection, CollectionCut, CollectionBeat, } from './components/LessonEmbed.svelte';

package/dist/video/README.md

@@ -15,6 +15,7 @@ props + callback surfaces.
 | `time.ts` | .28 (done) | Pure formatting: `formatTime`, `formatDuration`, `truncate`, `aspectRatioCss`. |
 | `model.ts` | .28 (done) | Speaker registry + identity colours + talk-time derivation + the sort normalisations. `ALL_KEY`/`UNKNOWN_KEY` live here. |
 | `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |
+| `band/` | **.30** (done) | `window.ts` — the zoom-window math (moved out of band.ts, re-exported there; shared by every band layer without an import cycle). `axis.ts` — one-axis four-state arbitration (`resolveAxis`, `BandState`, the churn-guarded microtask `createBandReporter`), `playheadX` (the one "where you are" mapping — ≤0.2px agreement) and `overviewBracket`. `luma.ts` — the light track (`VideoLumaTrack`, the sidecar verbatim) → ribbon (`v² × 0.55`, max-per-interval). `markers.ts` — `VideoMarker` comments (clustered dots) + like heat. |
 | `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
 | `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |