@joewinke/jatui 0.38.2 → 0.38.3

package/CLAUDE.md

@@ -119,7 +119,7 @@ Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOpti
 | `ThumbnailGrid` | Generic thumbnail strip (chimaro port) — image tiles with text-tile fallback, +N overflow counter, remove/add affordances. Decoupled from any media library: pass `{id, url, alt}` items, or a `cell` snippet for full control of tile contents. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. | `items: ThumbnailItem[]`, `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `cell` snippet |
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
 | `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
-| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed) and zoom over the band. Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
+| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed) and zoom over the band. Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane, a reader scroll pauses it behind a "Jump to current" pill; a hovered chapter lights its whole span on the band), `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
 | `MediaCapture` | One-tap audio/selfie-video/screen(+mic) recording — a host-agnostic PRIMITIVE. Owns permission requests, MIME negotiation, the record/stop state machine, live self-preview, and mixes screen+mic audio into one track via AudioContext. Never uploads anything — hands the finished clip to `onCapture` as a Blob and the host decides what to do with it. `onCapture` may be async; the component shows "processing" until it resolves. | `onCapture: (result: MediaCaptureResult) => void \| Promise<void>`, `modes?` (default all three), `maxDurationMs?` (default 120000), `label?`, `hint?`, `compact?`, `disabled?` |
 | `MultimodalCaptureField` | "Upload a file, or record yourself going over it" as one input surface — composes `FileDropzone` (capped to one file) with `MediaCapture`. File and recording are independent (either, both, or neither); neither half uploads anything, same "validate and hand back" contract as `FileDropzone`. | `onFileSelected?`, `onFileRemoved?`, `onCapture?`, `onRecordingRemoved?`, `accept?`, `maxFileSize?`, `modes?`, `maxDurationMs?`, `file?`/`fileUrl?`/`fileName?`, `recordingSummary?` |
 | `ListenControl` | "Listen to this page" — a compact pill that expands into a TWO-ROW playback bar over the host's PER-SENTENCE audio (TTS): row 1 = play/pause · chapter chip + current sentence (full remaining width) · ONE settings pill ("1.25× · Sarah" → speed 0.75–2× + voice menu) · close; row 2 = prev/next sentence and −15s/+15s · a document-wide progress bar with chapter ticks (a hatched tail marks the not-yet-synthesized part), time, close. The host supplies an async `source` (sentences/paragraphs with ids → audio URLs, streamed page by page so playback starts on the first chunk while the rest synthesizes; pages merge by id so late URLs fill in) and gets `onSegmentChange(id)` at every boundary for highlight + scroll-follow. Media Session (lock-screen/headset controls, one document-wide position), keyboard scoped to the player (Space/K, ←/→ sentences, Shift+←/→ ±15s, [ / ] speed, Escape), speed+voice persisted in localStorage, `bind:api` for hosts wiring their own global keys, reduced-motion aware, token-only theming, never overflows its host (border-box, `max-width: 100%`, `min-width: 0` chain), fixed sticky mini-bar (same two rows) on narrow screens. Internals in `src/lib/listen/` (one timeline across per-sentence files — `buildTimeline` offsets; see `video/` for the doctrine). Demo synthesizes real WAVs locally. | `source`, `voices?`, `voiceId?` (bindable), `chapters?`, `title?`, `triggerLabel?`, `open?` (bindable), `preload?`, `estimateSec?`, `storageKey?`, `onSegmentChange?`, `onOpenChange?`, `api?` (bindable), `class?`, `children?` (custom trigger) |

package/dist/components/VideoPlayer.svelte

@@ -86,6 +86,8 @@
 	import { listNav } from '../actions/listNav';
 	// mos-777hj — the chapter rail's pure state (ends, played checks, progress).
 	import { railChapters, activeRailIndex, type RailChapter } from '../video/chapterRail';
+	import { scrollRowIntoPane, watchReaderScroll } from '../video/transcriptFollow';
+	import JumpToLatest from './basic/JumpToLatest.svelte';
 	import type {
 		VideoBookmark,
 		VideoChapter,
@@ -272,7 +274,7 @@
 		talkTime = [],
 		startAt = null,
 		transcriptPosition = 'below',
-		transcriptMaxHeight = '18rem',
+		transcriptMaxHeight,
 		/**
 		 * CORS mode for the <video> element — passed straight through as the
 		 * `crossorigin` attribute. `'anonymous'` asks the server for a
@@ -431,6 +433,11 @@
 		/** Seek here once metadata lands (a queued seek never fires on a later source). */
 		startAt?: number | null;
 		transcriptPosition?: 'below' | 'side';
+		/**
+		 * CSS length bounding the transcript pane's height — it scrolls inside
+		 * this, never the page. Default: `min(40vh, 28rem)` below the player;
+		 * beside it (`transcriptPosition: 'side'`), the player column's height.
+		 */
 		transcriptMaxHeight?: string;
 		crossorigin?: 'anonymous' | 'use-credentials' | null;
 		syncUrlTime?: boolean;
@@ -799,6 +806,10 @@
 	let viewStart = $state(0);
 	let viewEnd = $state(0); // 0 until a duration is known
 	let hoverChapter = $state(-1);
+	/** A chapter-rail row under the pointer or keyboard focus (-1 = none). */
+	let railHoverChapter = $state(-1);
+	/** The band canvas holds KEYBOARD focus (:focus-visible) — light the chapter under the playhead. */
+	let bandKeyFocus = $state(false);
 	let hover: {
 		x: number;
 		title: string;
@@ -848,6 +859,11 @@
 	});
 
 	let transcriptEl: HTMLDivElement | null = null;
+	/** The reader scrolled the pane themselves — auto-follow waits for "Jump to current". */
+	let followPaused = $state(false);
+	/** Height of the main column (stage + band), for a side transcript's bound. */
+	let mainEl: HTMLDivElement | undefined = $state();
+	let mainHeight = $state(0);
 	let vpScrollTop = $state(0);
 	let vpHeight = $state(0);
 	let heightsVersion = $state(0);
@@ -1041,9 +1057,13 @@
 			scheduleRowMeasure();
 		});
 		ro.observe(el);
+		const unwatch = watchReaderScroll(el, () => {
+			if (activeSegment) followPaused = true;
+		});
 		return {
 			destroy() {
 				ro.disconnect();
+				unwatch();
 				transcriptEl = null;
 			}
 		};
@@ -1092,10 +1112,9 @@
 		if (!railOn || railActive < 0) return;
 		const row = chapterRailEl?.querySelector<HTMLElement>('.vp-chapter-row.active');
 		if (!row) return;
-		row.scrollIntoView({
-			block: 'nearest',
-			behavior: reduceMotion ? 'auto' : 'smooth'
-		});
+		// The rail's own overflow only — scrollIntoView would also scroll the
+		// page whenever the rail sits partly off-screen (jatui-ap4oz).
+		if (chapterRailEl) scrollRowIntoPane(chapterRailEl, row, !reduceMotion);
 	});
 	const sortedTurns = $derived(sortTurns(speakers));
 	const sortedSegments = $derived(sortSegments(transcript));
@@ -1168,6 +1187,21 @@
 		sortedSegments.find((s) => currentTime >= s.startSec && currentTime < s.endSec) ?? null
 	);
 
+	/**
+	 * The chapter whose span the band lights (jatui-ap4oz): the one under the
+	 * pointer, else a hovered/focused rail row, else — while the band has
+	 * keyboard focus — the chapter under the playhead.
+	 */
+	const litChapter = $derived(
+		hoverChapter >= 0
+			? hoverChapter
+			: railHoverChapter >= 0
+				? railHoverChapter
+				: bandKeyFocus
+					? chapterAt(currentTime, sortedChapters)
+					: -1
+	);
+
 	/** The zoom window, as the band module sees it (plain data — band.ts is DOM-free). */
 	const bandWindow = $derived<BandWindow>({ start: viewStart, end: viewEnd });
 
@@ -1187,7 +1221,7 @@
 			soloKey,
 			mutedKeys,
 			window: bandWindow,
-			hoverChapter,
+			hoverChapter: litChapter,
 			luma: lumaSeries,
 			comments: socialMarkers.comments,
 			likes: socialMarkers.likes,
@@ -2884,28 +2918,64 @@
 	});
 
 	// Auto-scroll the active transcript row into view as playback advances.
+	// Only the PANE scrolls (jatui-ap4oz): scrollIntoView also scrolled the
+	// window, pushing the video out of frame on load and on every new line.
 	// Windowed panes may not have the row rendered: jump to its (estimated)
 	// offset first, then a follow-up effect lands exactly on the real row once
-	// the window renders it.
+	// the window renders it. A reader who scrolled the pane pauses this until
+	// they press "Jump to current" (or click a line).
+	function followSegment(seg: VideoTranscriptSegment) {
+		const pane = transcriptEl;
+		if (!pane) return;
+		const node = rowRefs[seg.id];
+		if (node) {
+			scrollRowIntoPane(pane, node, !reduceMotion);
+			return;
+		}
+		if (!transVirtual) return;
+		const idx = segIndexById.get(seg.id);
+		if (idx == null) return;
+		const top = ensureOffsets()[idx] ?? 0;
+		// Row top (in content coords) = pane padding + offset; land it ⅓ down.
+		pane.scrollTop = Math.max(0, top + transPadTop - Math.max(0, vpHeight) / 3);
+		pendingAutoScrollId = seg.id;
+	}
+
 	$effect(() => {
 		const seg = activeSegment;
 		if (!seg) return;
 		untrack(() => {
-			const node = rowRefs[seg.id];
-			if (node) {
-				node.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-				return;
-			}
-			if (!transVirtual || !transcriptEl) return;
-			const idx = segIndexById.get(seg.id);
-			if (idx == null) return;
-			const top = ensureOffsets()[idx] ?? 0;
-			// Row top (in content coords) = pane padding + offset; land it ⅓ down.
-			transcriptEl.scrollTop = Math.max(0, top + transPadTop - Math.max(0, vpHeight) / 3);
-			pendingAutoScrollId = seg.id;
+			if (!followPaused) followSegment(seg);
 		});
 	});
 
+	function jumpToCurrent() {
+		followPaused = false;
+		if (activeSegment) followSegment(activeSegment);
+	}
+
+	/** Clicking a line is choosing where to be: seek there and follow again. */
+	function onRowClick(seg: VideoTranscriptSegment) {
+		followPaused = false;
+		seekTo(seg.startSec);
+	}
+
+	// No active line (seeked past the transcript) ⇒ nothing to jump to.
+	$effect(() => {
+		if (!activeSegment && followPaused) untrack(() => (followPaused = false));
+	});
+
+	// A side transcript is bounded by the player column's height, so the
+	// pane shrinks to fit beside the video instead of growing past it.
+	$effect(() => {
+		const el = mainEl;
+		if (!el || typeof ResizeObserver === 'undefined') return;
+		const ro = new ResizeObserver(() => (mainHeight = el.offsetHeight));
+		ro.observe(el);
+		mainHeight = el.offsetHeight;
+		return () => ro.disconnect();
+	});
+
 	// Exact landing after a windowed jump: the row is now rendered — snap to it.
 	$effect(() => {
 		void renderedSegments;
@@ -2915,7 +2985,7 @@
 			const node = rowRefs[id];
 			if (!node) return;
 			pendingAutoScrollId = null;
-			node.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+			if (transcriptEl && !followPaused) scrollRowIntoPane(transcriptEl, node, !reduceMotion);
 		});
 	});
 
@@ -2961,7 +3031,7 @@
 	onclickcapture={maybeAskIdle}
 	onkeydowncapture={maybeAskIdle}
 >
-	<div class="vp-main">
+	<div class="vp-main" bind:this={mainEl}>
 		<div
 			class="vp-stage-wrap"
 			class:vp-stage-audio={isAudio}
@@ -3118,6 +3188,8 @@
 				ondblclick={onBandDblClick}
 				oncontextmenu={onBandContextMenu}
 				onkeydown={onBandKeyDown}
+				onfocus={(e) => (bandKeyFocus = (e.currentTarget as HTMLElement).matches(':focus-visible'))}
+				onblur={() => (bandKeyFocus = false)}
 			></canvas>
 			<!-- Polite announcements for comment jumps/clicks — the dots are
 			     canvas pixels, so without this a comment is invisible to AT. -->
@@ -3441,6 +3513,10 @@
 					data-chapter-index={i}
 					aria-current={railActive === i ? 'true' : undefined}
 					onclick={() => chapterGo(i)}
+					onmouseenter={() => (railHoverChapter = i)}
+					onmouseleave={() => (railHoverChapter = -1)}
+					onfocus={() => (railHoverChapter = i)}
+					onblur={() => (railHoverChapter = -1)}
 				>
 					<span class="vp-chapter-head">
 						{#if ch.status}
@@ -3485,9 +3561,17 @@
 	{/if}
 
 	{#if sortedSegments.length > 0 && transcriptVisible}
+		<!-- Height-bounded (jatui-ap4oz): the pane scrolls itself and never
+		     the page, so the video stays in frame. Below the player the bound
+		     is `transcriptMaxHeight` (default min(40vh, 28rem)); beside it, the
+		     player column's height. -->
+		<div
+			class="vp-transcript-wrap"
+			style:--vp-transcript-max={transcriptMaxHeight}
+			style:--vp-transcript-side-max={!transcriptMaxHeight && mainHeight > 0 ? `${mainHeight}px` : undefined}
+		>
 		<div
 			class="vp-transcript"
-			style="max-height: {transcriptMaxHeight}"
 			use:transcriptPaneAction
 			onscroll={onTranscriptScroll}
 		>
@@ -3506,7 +3590,7 @@
 							? highlightKey !== speakerKeyOf(seg)
 							: filterDims(speakerKeyOf(seg), false, soloKey, mutedKeys)}
 						use:transcriptRowAction={seg}
-						onclick={() => seekTo(seg.startSec)}
+						onclick={() => onRowClick(seg)}
 					>
 						<span class="vp-row-time">{formatTime(seg.startSec, useHours)}</span>
 						{#if multiSpeaker}
@@ -3529,7 +3613,7 @@
 							? highlightKey !== speakerKeyOf(seg)
 							: filterDims(speakerKeyOf(seg), false, soloKey, mutedKeys)}
 						use:transcriptRowAction={seg}
-						onclick={() => seekTo(seg.startSec)}
+						onclick={() => onRowClick(seg)}
 					>
 						<span class="vp-row-time">{formatTime(seg.startSec, useHours)}</span>
 						{#if multiSpeaker}
@@ -3542,6 +3626,12 @@
 				{/each}
 			{/if}
 		</div>
+		<JumpToLatest
+			visible={followPaused && activeSegment != null}
+			label="Jump to current"
+			onclick={jumpToCurrent}
+		/>
+		</div>
 	{/if}
 
 	{#if keysOpen}
@@ -3614,6 +3704,11 @@
 
 	/* Side layout: transcript beside the video once there's room for both. */
 	@media (min-width: 64rem) {
+		/* Beside the player: no taller than the player column. */
+		.vp-root.vp-side .vp-transcript {
+			max-height: var(--vp-transcript-max, var(--vp-transcript-side-max, min(40vh, 28rem)));
+		}
+
 		.vp-root.vp-side {
 			display: grid;
 			grid-template-columns: minmax(0, 3fr) minmax(16rem, 2fr);
@@ -3847,7 +3942,7 @@
 			grid-area: below;
 		}
 
-		.vp-root.vp-rail-side > .vp-transcript {
+		.vp-root.vp-rail-side > .vp-transcript-wrap {
 			grid-area: transcript;
 		}
 
@@ -4409,8 +4504,21 @@
 		background: color-mix(in oklch, var(--color-warning) 28%, transparent);
 	}
 
-	/* Transcript pane */
+	/* Transcript pane. The wrap positions the "Jump to current" pill over
+	   the pane and carries the height bound (jatui-ap4oz). */
+	.vp-transcript-wrap {
+		position: relative;
+		display: flex;
+		flex-direction: column;
+		min-width: 0;
+		min-height: 0;
+	}
+
 	.vp-transcript {
+		/* The bound is the pane's visible box, padding and border included. */
+		box-sizing: border-box;
+		max-height: var(--vp-transcript-max, min(40vh, 28rem));
+		overscroll-behavior: contain;
 		display: flex;
 		flex-direction: column;
 		gap: 1px;

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

@@ -163,6 +163,11 @@ type $$ComponentProps = {
     /** Seek here once metadata lands (a queued seek never fires on a later source). */
     startAt?: number | null;
     transcriptPosition?: 'below' | 'side';
+    /**
+     * CSS length bounding the transcript pane's height — it scrolls inside
+     * this, never the page. Default: `min(40vh, 28rem)` below the player;
+     * beside it (`transcriptPosition: 'side'`), the player column's height.
+     */
     transcriptMaxHeight?: string;
     crossorigin?: 'anonymous' | 'use-credentials' | null;
     syncUrlTime?: boolean;

package/dist/video/band.d.ts

@@ -67,6 +67,7 @@ export interface BandPaintState {
     soloKey: string;
     mutedKeys: Set<string>;
     window: BandWindow;
+    /** Chapter whose whole span is lit (hover / keyboard focus); -1 = none. */
     hoverChapter: number;
     /** Normalised light track (band/luma.ts); null ⇒ no ribbon. */
     luma?: LumaSeries | null;
@@ -111,6 +112,17 @@ export declare function prepareCanvas(canvas: HTMLCanvasElement): CanvasRenderin
  * the playhead. `W`/`H` are CSS pixels of the canvas box.
  */
 export declare function paintBand(ctx: CanvasRenderingContext2D, W: number, H: number, s: BandPaintState): void;
+/** Height of the accent rule along the top of a lit chapter span, px. */
+export declare const LIT_RULE_H = 2;
+/**
+ * Pixel extent [x0, x1) of chapter `index` — its start to the next chapter's
+ * start (or the end of the video) — through the zoom window, clipped to the
+ * canvas. Null when there is no such chapter or it is entirely off-screen.
+ */
+export declare function chapterSpanPx(chapters: VideoChapter[], index: number, w: BandWindow, duration: number, width: number): {
+    x0: number;
+    x1: number;
+} | null;
 /** Turn → BandTurn for the paint state (resolved key, ad flag). */
 export declare function toBandTurns(turns: VideoSpeakerTurn[]): BandTurn[];
 export { ALL_KEY };

package/dist/video/band.js

@@ -161,6 +161,19 @@ export function paintBand(ctx, W, H, s) {
         }
         ctx.globalAlpha = 1;
     }
+    // The lit chapter (jatui-ap4oz): a wash over its whole span plus an
+    // accent rule along the top edge, under every other layer so the
+    // envelope, flags and playhead stay legible on top. Static — nothing
+    // animates, so it is reduced-motion safe by construction.
+    const lit = chapterSpanPx(s.chapters, s.hoverChapter, s.window, dur, W);
+    if (lit) {
+        ctx.fillStyle = accent;
+        ctx.globalAlpha = 0.14;
+        ctx.fillRect(lit.x0, 0, lit.x1 - lit.x0, H);
+        ctx.globalAlpha = 0.9;
+        ctx.fillRect(lit.x0, 0, lit.x1 - lit.x0, LIT_RULE_H);
+        ctx.globalAlpha = 1;
+    }
     const p = s.peaks;
     const withWave = !!p;
     const n = p?.length ?? 0;
@@ -310,6 +323,22 @@ export function paintBand(ctx, W, H, s) {
     ctx.fillRect(playheadX(s.currentTime, w, dur, W) - PLAYHEAD_W / 2, 0, PLAYHEAD_W, H);
     ctx.globalAlpha = 1;
 }
+/** Height of the accent rule along the top of a lit chapter span, px. */
+export const LIT_RULE_H = 2;
+/**
+ * Pixel extent [x0, x1) of chapter `index` — its start to the next chapter's
+ * start (or the end of the video) — through the zoom window, clipped to the
+ * canvas. Null when there is no such chapter or it is entirely off-screen.
+ */
+export function chapterSpanPx(chapters, index, w, duration, width) {
+    const ch = chapters[index];
+    if (!ch || duration <= 0 || width <= 0)
+        return null;
+    const end = chapters[index + 1]?.startSec ?? duration;
+    const x0 = Math.max(0, secToFrac(w, duration, ch.startSec) * width);
+    const x1 = Math.min(width, secToFrac(w, duration, end) * width);
+    return x1 > x0 ? { x0, x1 } : null;
+}
 /** Turn → BandTurn for the paint state (resolved key, ad flag). */
 export function toBandTurns(turns) {
     return turns.map((t) => ({

package/dist/video/transcriptFollow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Transcript follow (jatui-ap4oz) — keep the active line in view by scrolling
+ * the transcript pane ONLY, and stop following the moment the reader scrolls
+ * the pane themselves.
+ *
+ * Why not `scrollIntoView`: it scrolls every scrollable ancestor up to the
+ * window, so a pane below the video dragged the whole page and pushed the
+ * video out of frame on load and on every new line. Setting the pane's own
+ * `scrollTop` cannot move anything else.
+ *
+ * Reader intent follows createStickToBottom's rules (actions/stickToBottom):
+ * wheel, touch drag, scroll keys and a scrollbar grab inside the pane are
+ * "the reader is reading", and follow pauses until they ask for it back
+ * (the "Jump to current" pill, or clicking a line). Plain `scroll` events are
+ * never intent — the follow's own scrolls and the windowing's height
+ * corrections fire them too.
+ */
+/**
+ * Where the pane should scroll so a row spanning [rowTop, rowBottom) (content
+ * coordinates) is fully visible, with `margin` px of breathing room — or null
+ * when it already is. "Nearest" semantics: move the least distance.
+ */
+export declare function nearestScrollTop(rowTop: number, rowBottom: number, scrollTop: number, viewHeight: number, margin?: number): number | null;
+/**
+ * Scroll `pane` (and nothing else) so `row` is visible. Returns true when it
+ * moved. `smooth` is the caller's call — pass false under reduced motion.
+ */
+export declare function scrollRowIntoPane(pane: HTMLElement, row: HTMLElement, smooth: boolean, margin?: number): boolean;
+/**
+ * Listen for reader scroll intent on `pane`; `onIntent` fires on each one.
+ */
+export declare function watchReaderScroll(pane: HTMLElement, onIntent: () => void): () => void;

package/dist/video/transcriptFollow.js

@@ -0,0 +1,80 @@
+/**
+ * Transcript follow (jatui-ap4oz) — keep the active line in view by scrolling
+ * the transcript pane ONLY, and stop following the moment the reader scrolls
+ * the pane themselves.
+ *
+ * Why not `scrollIntoView`: it scrolls every scrollable ancestor up to the
+ * window, so a pane below the video dragged the whole page and pushed the
+ * video out of frame on load and on every new line. Setting the pane's own
+ * `scrollTop` cannot move anything else.
+ *
+ * Reader intent follows createStickToBottom's rules (actions/stickToBottom):
+ * wheel, touch drag, scroll keys and a scrollbar grab inside the pane are
+ * "the reader is reading", and follow pauses until they ask for it back
+ * (the "Jump to current" pill, or clicking a line). Plain `scroll` events are
+ * never intent — the follow's own scrolls and the windowing's height
+ * corrections fire them too.
+ */
+/**
+ * Where the pane should scroll so a row spanning [rowTop, rowBottom) (content
+ * coordinates) is fully visible, with `margin` px of breathing room — or null
+ * when it already is. "Nearest" semantics: move the least distance.
+ */
+export function nearestScrollTop(rowTop, rowBottom, scrollTop, viewHeight, margin = 0) {
+    if (viewHeight <= 0)
+        return null;
+    const top = rowTop - margin;
+    const bottom = rowBottom + margin;
+    if (top >= scrollTop && bottom <= scrollTop + viewHeight)
+        return null;
+    // Taller than the pane, or above the view ⇒ align its top.
+    if (top < scrollTop || bottom - top > viewHeight)
+        return Math.max(0, top);
+    return Math.max(0, bottom - viewHeight);
+}
+/**
+ * Scroll `pane` (and nothing else) so `row` is visible. Returns true when it
+ * moved. `smooth` is the caller's call — pass false under reduced motion.
+ */
+export function scrollRowIntoPane(pane, row, smooth, margin = 8) {
+    const p = pane.getBoundingClientRect();
+    const r = row.getBoundingClientRect();
+    const offset = pane.scrollTop - p.top - pane.clientTop;
+    const next = nearestScrollTop(r.top + offset, r.bottom + offset, pane.scrollTop, pane.clientHeight, margin);
+    if (next === null || Math.abs(next - pane.scrollTop) < 1)
+        return false;
+    if (smooth && typeof pane.scrollTo === 'function')
+        pane.scrollTo({ top: next, behavior: 'smooth' });
+    else
+        pane.scrollTop = next;
+    return true;
+}
+// Arrows, Space, Home and End belong to the player's keymap (seek, volume,
+// play) — only the page keys are left to scroll the pane natively.
+const SCROLL_KEYS = new Set(['PageUp', 'PageDown']);
+/**
+ * Listen for reader scroll intent on `pane`; `onIntent` fires on each one.
+ */
+export function watchReaderScroll(pane, onIntent) {
+    const wheel = () => onIntent();
+    const touch = () => onIntent();
+    const key = (e) => {
+        if (SCROLL_KEYS.has(e.key))
+            onIntent();
+    };
+    // A press on the pane's own box beyond its client width is the scrollbar.
+    const down = (e) => {
+        if (e.target === pane && e.offsetX > pane.clientWidth)
+            onIntent();
+    };
+    pane.addEventListener('wheel', wheel, { passive: true });
+    pane.addEventListener('touchmove', touch, { passive: true });
+    pane.addEventListener('keydown', key);
+    pane.addEventListener('pointerdown', down);
+    return () => {
+        pane.removeEventListener('wheel', wheel);
+        pane.removeEventListener('touchmove', touch);
+        pane.removeEventListener('keydown', key);
+        pane.removeEventListener('pointerdown', down);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.38.2",
+  "version": "0.38.3",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",